Hytale Modding API: O Guia de Desenvolvimento do Plugin de Servidor Completo

O sistema de plugin de servidor do Hytale dá aos desenvolvedores um controle profundo sobre cada aspecto do jogo. Se você escreveu plugins Bukkit ou Spigot para Minecraft, a transição é simples — mas a arquitetura de Hytale é fundamentalmente diferente das maneiras que importam. Este guia te acompanha desde a configuração inicial até a implantação da produção. Arquitectura Visão geral Antes de escrever qualquer código, entenda como o modding de Hytale funciona: O cliente é um renderizador. O cliente C# da Hytale lida com gráficos, entradas e áudio — mas não contém lógica de jogo. Toda a simulação é executada no servidor Java, mesmo no singleplayer. Tudo é do lado do servidor. Quando os jogadores se juntam a um servidor modificado, ativos personalizados e fluxo de comportamento automaticamente. Nenhum mods de cliente necessário. Quatro categorias de modificação existem: Activos de Dados (JSON), Activos de Arte (modelos Blockbench), Plugins de Servidor (Java) e Scripting Visual (em breve). Os plugins Server são a categoria mais poderosa — eles dão acesso Java completo ao tempo de execução do servidor, incluindo o Entity Component System, pipeline de eventos, framework de comando e manipulação mundial. Configuração do Ambiente de Desenvolvimento Prerequisitos FerramentaVersãoNotas Java25+ Hytale usa recursos modernos, incluindo threads virtuais (Project Loom) IntelliJ IDEAComunidade ou UltimateRecomendado IDE — Edição Comunitária Livre funciona bem Gradle9.2.0+Sistema de compilação (incluído no modelo de plugin) Git Qualquer versão recente Para clonar o modelo oficial Fechar o Modelo Oficial Hypixel Studios fornece um modelo oficial de plugin no GitHub: git clone https://github.com/HytaleModding/plugin-template.git MeuPrimeiroPlugin cd MyFirstPlugin Abra o projeto no IntelliJ IDEA e deixe Gradle sincronizar. O modelo inclui a estrutura de diretório correta, configuração de compilação e dependências da API do servidor. Alternativamente, o HytaleIO Project Generator em hytaleio.com/project-generator pode criar um andaime de projetos Plugin, Mod ou Full (combo) com uma interface web. Estrutura de Plugins Todo plugin Hytale segue este layout de diretório: seu-plugin/ - Src/main/java/com/seu nome/seuplugin/ Seu Plugin. java # Principal ponto de entrada • src/main/resources/ Manifeste-se. metadados do plug-in json # (obrigatório) Ativos comuns/ # compartilhados (modelos, texturas) Ativos de dados do lado do servidor Constrói.gradle.kts Settings.gradle.kts No entanto, o presente regulamento é obrigatório em todos os seus elementos e diretamente aplicável em todos os Estados-Membros. manifest.json Cada plugin requer um manifest.json na raiz do JAR compilado. Este é o equivalente de Hytale de Bukkit plugin.yml: { "Grupo": "com.seu nome", "Nome": "SeuPluginName", "Main": "com.seu nome.seu plug-in.seu Plugin", "Versão": "1.0.0", "Descrição": "O que seu plugin faz", "Autors": [{"Nome": "Seu nome"}], "ServerVersion": "*", "Dependências": {}, "Dependências Opcionais": {}, "Antes": [] "Desactivado por padrão": falso, "Inclui assetPack": false } O identificador do plugin é formado como Grupo:Nome (por exemplo, com.seu nome:YourPluginName). O Main campo aponta para sua classe de entrada — entenda isso errado e o plugin não irá carregar. ciclo de vida da plugina Sua classe principal se estende JavaPlugin e tem quatro fases do ciclo de vida: classe pública Extensões do plug-in JavaPlugin { Público SeuPlugin(@ Nãonull JavaPluginInit init) { super(init); getLogger().info("Plugin construted!"); } @ Sobreride configuração do vazio público () { // Fase 2: Registro de eventos, comandos, sistemas ECS // Aqui é onde a maior parte do seu código de registo vai } @ Sobreride public void start () { // Fase 3: O servidor está pronto para jogadores // Iniciar tarefas agendadas, abrir conexões } @ Sobreride desligamento público vazio () { // Fase 4: Limpeza antes do servidor parar // Salvar dados, fechar conexões, cancelar tarefas } } FaseMetodo O que fazer aqui 1. ConstruçãoConstrutor Inicialização básica, registro Configuraçãosetup() Registro de eventos, comandos, componentes e sistemas ECS 3. Iniciarstart() Iniciar tarefas, o servidor está aceitando jogadores 4. Desligarshutdown() Salvar dados, recursos de limpeza The Dual Event System Este é o conceito mais importante para entender. Hytale tem dois sistemas de eventos separados, e usar o errado é um erro comum. Evento Ônibus — Eventos do servidor global O EventBus lida com eventos de todo o servidor como conexões de jogador, chat e carregamento mundial. Manipuladores de registro através do EventRegistry fornecido ao seu plugin: @ Substituir configuração do vazio público () { // evento global sincronizado getEventRegistry().registerGlobal( PlayerReadyEvent.class, evento -> { getLogger().info("Player juntou- se: " + event.getPlayer().getUsername(); } ); // Evento de sincronização (como o PlayerChatEvent) getEventRegistry().registerAsyncGlobal( PlayerChatEvent.class, futuro -> { futuro. entãoAccept(evento -> { se (event.getMessage().contains("spam")) { event.setCancelled( verdade); } }); } ); } Evento chave Eventos de autocarro: PlayerConnectEvent / PlayerDisconnectEvent — ciclo de vida da ligação PlayerReadyEvent — jogador totalmente carregado e pronto PlayerChatEvent — mensagens de chat (async, cancellable) AddPlayerToWorldEvent — jogador entrando em um mundo StartWorldEvent / AddWorldEvent / RemoveWorld Evento — gestão mundial Prioridades do evento: Usar EventoPrioridade. EARLY para executar primeiro e modificar os eventos antes que outros manipuladores os vejam. Usar EventoPrioridade. LATE para ver o estado final depois de todos os outros manipuladores terem processado. ECS Acontecimentos — Ações específicas da entidade Eventos de nível de entrada como quebra de bloco, colocação de bloco e dano são manipulados através do Entity Component System, não o EventBus. Você cria um EntityEventSystem: classe pública BlockBreakHandler extende EntityEventSystem