Referência da API do servidor Hytale: Guia de Desenvolvimento de Eventos, Mensagens e Plugin

Compreendendo a arquitetura do servidor Hytale A API do servidor Hytale é construída em uma arquitetura baseada em Java robusta que se sentirá familiar a qualquer um que tenha trabalhado com plugins de servidor Minecraft. Com o retorno ao Legacy Engine, os desenvolvedores agora têm acesso a uma base de códigos madura e bem testada que prioriza a acessibilidade de modding sobre complexidade multiplataforma. No coração do servidor está o pacote com.hypixel.hytale.server.core, que fornece a base para todas as operações do lado do servidor. Isso inclui gerenciamento de jogadores, manipulação mundial, expedição de eventos e processamento de comandos. Eventos da conexão do jogador: Manipulação Junte-se e deixe Um dos requisitos mais comuns para qualquer plugin de servidor é responder aos jogadores que se juntam ou saem. A API Hytale fornece dois eventos essenciais para este fim. PlayerConnectEvent Fired quando um jogador conecta-se com sucesso ao servidor, este evento lhe dá acesso à referência do jogador antes que ele desove totalmente para o mundo. As propriedades principais incluem: playerRef - A instância PlayerRef contendo UUID, nome de usuário e informações de rede jogador - A entidade do jogador que irá representá-los no mundo mundo - A instância mundial que eles estão juntando holder - O titular da loja de entidade para acesso ao componente Diferente de alguns outros eventos, PlayerConnect O evento é não cancelável. Se você precisa impedir um jogador de se juntar, você deve lidar com isso na camada de autenticação em vez disso. eventRegistry.register(PlayerConnectEvent::class.java) { evento -> val player = event.playerRef logger.info("Player conectado: ${player.username}") // Enviar mensagem de boas-vindas player.sendMessage(Message.raw("Bem-vindo ao servidor!") } PlayerDesconnectEvent Triggered quando um jogador sai do servidor, este evento inclui contexto importante sobre por que desligaram: jogadorRef - Referência do jogador que parte desconexãoReason - Enum indicando tempo limite, pontapé, saída ou desligamento do servidor Este evento também não é cancelável uma vez que a desconexão já ocorreu no nível da rede. A Classe de Mensagem: Formatação de Texto Rico Os proprietários de servidores que procuram criar experiências de chat polidas passarão um tempo significativo com a classe Mensagem. Localizado no pacote principal de mensagens, ele fornece uma API fluente para construir texto formatado. Criação de Mensagem Básica // Mensagem de texto simples val msg = Message.raw("Olá, mundo!") // Com formatação de cores val styled = Message.raw("Importante!") .color ("vermelho") . negrito( verdadeiro) .italic( falso) .monospace( true) Substituição do parâmetro Para conteúdo dinâmico, use placeholders de parâmetros: val welcome = Message.raw("Welcome, {name}! Você tem moedas.") .param( "nome", player.username) .param("coins", playerData.coinBalance.toString()) Links clicáveis Mensagens podem incluir hiperlinks clicáveis: val linked = Message.raw("Clique aqui para visitar nosso site") .link ("https://example.com") Padrões de registo de acontecimentos O sistema de eventos Hytale suporta o manuseio de eventos síncronos e assíncronos, dando aos desenvolvedores flexibilidade com base em seus requisitos de desempenho. Síncrono Registo Para eventos que necessitem de processamento imediato no tópico servidor: eventRegistry.register(PlayerInteractEvent::class.java) { evento -> se (event.action Tipo ==ActionType.RIGHT_CLICK) { // Processar a interação event.setCancelled( true) } } Assíncrono Registo Para eventos que podem ser processados fora do tópico principal (como moderação de chat): eventRegistry.registerAsync(PlayerChatEvent::class.java) {future -> futuro. entãoAplicar { event -> // Realizar filtragem de chat assync se (contémBannedWords(event.content)) { event.setCancelled( true) } evento } } Comum Quadro de Referência do Evento Aqui está uma referência rápida para os eventos mais usados no desenvolvimento do servidor: Nome do eventoCancellable Propriedades da Chave PlayerConnectEvent NojogadorRef, jogador, mundo, detentor PlayerDesconnectEvent NãoplayerRef, desconexãoReason PlayerChatEventYes (Async)sender, alvos, conteúdo, formatação PlayerInteractEventSimplayer, ação Tipo, itemInHand, targetBlock, targetEntity PlayerDeathEvent Não jogador PlayerRespawnEvent Não jogador BreakBlockEventSimitem InHand, targetBlock, blockType PlaceBlockEventSimitemInHand, targetBlock, rotation DamagemBlockEventSimitem InHand, targetBlock, correnteDamagem, dano DropItemEventSimitem, localização CraftRecipeEvent SimcraftedRecipe, quantidade Construindo comandos personalizados O sistema de comando permite que você registre comandos de barra que os jogadores podem executar no chat. Implementação de Comando Básico classe Meu Comando: Comando { sobrescrever fun getName(): String = "mycommand" sobrescrever execução divertida(sender: CommandSender, args: Array) { remetente.sendMessage(Message.raw("Olá do meu comando personalizado!") } } // Registre-se na fase de configuração do seu plugin comandoRegistry.registerCommand(MyCommand()) Usando o Gestor de Comando Você também pode executar comandos programaticamente: comandovalManager = CommandManager.get() comandoManager.handleCommand(sender, "time day") Ciclo de Vida e Estrutura de Plugins Todo plugin de servidor Hytale estende a classe base JavaPlugin, que fornece registros essenciais e ganchos de ciclo de vida. Fases do ciclo de vida da plugina Construção - Instanciação da classe do plug-in PreLoad - Inicialização da sincronização antes do início do servidor Setup - Componentes de registro, eventos e comandos Iniciar - O servidor está pronto para aceitar jogadores Shutdown - Limpeza antes do servidor parar Propriedades do Plugin de Chave // Disponível na sua classe de plugins registrador: HytaleLogger // Capacidade de registo manifesto: PluginManifest? // Metadados de plug- in do arquivo manifesto eventRegistry: EventRegistry // Registar ouvintes de eventos comandoRegistry: CommandRegistry // Comandos de registo dados Pasta: Caminho // Localização do armazenamento de plug-ins taskRegistry: TaskRegistry // Gerenciamento agendado de tarefas Ajuda à Configuração Plugins pode facilmente carregar arquivos de configuração JSON: // Usando o config.json padrão val config: Config = comConfig(MyConfigClass.CODEC) // Usando nome de arquivo personalizado val config: Config = withConfig("custom-name.json", MyConfigClass.CODEC) Trabalhando com Jogadores A classe PlayerRef é sua interface primária para interagir com jogadores conectados. Identidade e Localização do Jogador jogador val: PlayerRef = event.playerRef // Identidade val uuid: UUID = player.uuid val name: String = player.username val language: String = player.language // Posição val transform: Transform = player.transform val worldUuid: UUID = player.worldUuid val headRotação: Vector3f = player.headRotation Acesso à Entidade Jogadora Para interações mais profundas como gerenciamento de inventário, acesse a entidade Jogador: jogador valEntity: Player = player.entity // Operações de inventário inventário val: Inventário = jogadorEntity.inventário playerEntity.sendInventory () // Gestores de IU val hotbar = jogadorEntity.hotbarManager val windows = playerEntity.windowManager val pages = playerEntity.pageManager val hud = jogadorEntity.hudManager // Permissões val canBuild: Boolean = playerEntity.hasPermission("server.build") Gestão Mundial e do Universo O singleton Universe oferece acesso a todos os mundos e jogadores conectados. val universe = Universe.get() // Acesso do jogador val allPlayers: List = universe.players val player Contagem: Int = universo.playerCount val especificPlayer: PlayerRef? = universe.getPlayer(uuid) // Grande acesso mundos val: Map = universo.worlds valor padrão Mundo: Mundo? = universo.defaultWorld val especific Mundo: Mundo? = universo.getWorld("meu mundo") // Grande gestão val newWorld: CompletableFuture = universe.addWorld("novo mundo") val carregado: Completável Future = universe.loadWorld("mundo existente") Aviso de segurança de thread O acesso do componente deve ocorrer na linha do mundo. Always wrap operations in the execute block: world.execute { // Acesso seguro ao componente aqui val entities = world.getEntities() } Próximos Passos para Desenvolvedores de Servidor Com esta referência API como sua fundação, você está pronto para começar a construir plugins de servidor Hytale. Recursos-chave para explorar a seguir: O Sistema de Componentes de Entidade (ECS) para manipulação avançada de entidades Módulos construídos como NPCs, Portals e sistemas Quest O sistema de scripts visuais para comportamentos de jogo Protocolo de rede para tratamento personalizado de pacotes Lembre-se que, à medida que Hytale passa pelo Early Access, a API pode evoluir. Mantenha-se conectado com a comunidade e documentação oficial conforme ela se desenvolve.