Adicionar Interfaces de Anvil ao Servidor Minecraft

Construir um plugin Minecraft que precisa de entrada do jogador é um problema comum. Você poderia pedir via chat, mas isso enche o log de chat. Qualquer pessoa poderia construir uma GUI de inventário customizada, mas requer texturas e código extra. Telas de anvil são perfeitas para entrada de texto simples, e AnvilGUI é a biblioteca que as torna funcionar em todas as versões do Minecraft sem tocar em uma linha de código NMS.

Isso importa porque os internos do Minecraft mudam constantemente. GUIs de anvil na versão 1.20 são tratadas completamente diferente da 1.21. A maioria dos desenvolvedores de plugins fica em sua versão de servidor ou usa hacks de reflection para suportar múltiplas versões. AnvilGUI faz esse trabalho de reflection para você.

O Que AnvilGUI Faz

AnvilGUI é um wrapper em torno do inventário de anvil do Minecraft projetado especificamente para capturar texto de jogadores. Em vez de mergulhar em net.minecraft.server (os internos ofuscados que mudam a cada patch), você escreve código limpo com padrão builder. A biblioteca detecta qual versão você está executando e carrega a implementação correta em tempo de execução.

Aqui está como fica na prática.

O fluxo principal é direto: o jogador vê uma tela de anvil com um título e algum texto padrão. Ele digita algo, clica no slot de saída (o mais à direita), e seu código é executado. Você valida a entrada, fecha a tela, ou pede para tentar novamente. Tudo com manipuladores de eventos.

Quando Usar Isso

Entrada de texto de jogadores aparece em toda parte no desenvolvimento de plugins. Sistemas de quests pedindo nomes de personagem. Comandos de nickname customizados. Casas de leilão onde vendedores definem preços. Sistemas de loja com lances de jogadores. Até ferramentas de conversão de coordenadas como nossa Calculadora de Portal do Nether precisam de interfaces de entrada limpas.

E aqui está o ponto: GUIs de anvil se sentem nativas do Minecraft. A interface já está lá, jogadores entendem instantaneamente, e não quebra a imersão com diálogos estranhos ou menus popup. Se você estivesse construindo algo como nosso Criador de MOTD do Minecraft (que permite jogadores designarem mensagens de servidor), uma entrada de anvil encaixaria perfeitamente naquele fluxo.

Alguns plugins usam chat para entrada, mas isso entope o log de chat e parece bagunçado. Outros constroem GUIs completas de inventário customizado, que requerem texturas customizadas e muito mais código. Anvils acertam o ponto certo: são construídas, parecem vanilla, e AnvilGUI abstrai o pesadelo da compatibilidade de versão.

Instalando AnvilGUI

Primeiro, adicione o repositório Maven. A partir da versão 1.10.11, o repositório mudou para uma nova URL:

<repository>
 <id>mvn-wesjd-net</id>
 <url>https://mvn.wesjd.net/</url>
</repository>

Depois adicione a dependência:

<dependency>
 <groupId>net.wesjd</groupId>
 <artifactId>anvilgui</artifactId>
 <version>1.10.12-SNAPSHOT</version>
 <scope>compile</scope>
</dependency>

O escopo ser compile significa que AnvilGUI fica empacotado no seu JAR final.

Agora para a parte que confunde pessoas: shading. AnvilGUI é uma biblioteca, não um plugin autossuficiente, então você precisa de maven-shade-plugin para empacotá-la no JAR do seu plugin. Isso previne conflitos de classpath se múltiplos plugins no mesmo servidor usarem AnvilGUI.

<plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-shade-plugin</artifactId>
 <version>3.5.0</version>
 <executions>
 <execution>
 <phase>package</phase>
 <goals>
 <goal>shade</goal>
 </goals>
 <configuration>
 <relocations>
 <relocation>
 <pattern>net.wesjd.anvilgui</pattern>
 <shadedPattern>your.plugin.package.anvilgui</shadedPattern>
 </relocation>
 </relocations>
 </configuration>
 </execution>
 </executions>
</plugin>

Substitua seu.plugin.package pelo nome do seu pacote atual. Isso reposiciona AnvilGUI no seu namespace para que não conflite com outros plugins.

Como a API Funciona

Aqui está um exemplo completo do projeto:

new AnvilGUI.Builder().onClose(stateSnapshot -> {
 stateSnapshot.getPlayer().sendMessage("You closed the inventory.");
 }).onClick((slot, stateSnapshot) -> {
 if(slot!= AnvilGUI.Slot.OUTPUT) {
 return Collections.emptyList();
 }

 if(stateSnapshot.getText().equalsIgnoreCase("you")) {
 stateSnapshot.getPlayer().sendMessage("You've magical powers!");
 return Arrays.asList(AnvilGUI.ResponseAction.close());
 } else {
 return Arrays.asList(AnvilGUI.ResponseAction.replaceInputText("Try again"));
 }
 }).preventClose().text("What's the meaning of life?").title("Enter your answer").plugin(plugin).open(player);

O padrão builder encadeia chamadas de método. Title é o texto acima da anvil. Text é a entrada padrão (conteúdo pré-preenchido). OnClose dispara quando o jogador fecha sem enviar. OnClick dispara quando clicam em um slot na anvil.

O parâmetro slot te diz o que ele clicou. Há INPUT (slot esquerdo), OUTPUT (slot direito onde resultados mostram), e RESULT (o item que receberiam se fosse uma receita real). Você quase sempre verifica OUTPUT já que é o botão enviar.

StateSnapshot contém o jogador e qualquer texto que ele digitou. Você valida e retorna ResponseActions. ResponseAction.close() fecha a tela. ResponseAction.replaceInputText() atualiza o campo de entrada - útil para mensagens de erro como "esse nome foi pego" ou "tente novamente".

PreventClose() remove a opção da tecla escape, forçando jogadores a enviar ou clicar em outros slots. Use isso para informações críticas que você absolutamente precisa deles.

Plugin(plugin) é sua instância de plugin. É necessário para registro de eventos e detecção de versão nos bastidores.

Uma coisa mais poderosa: você pode customizar praticamente tudo. Títulos mais longos, texto somente leitura, diferentes comportamentos de slot baseados em entrada. A API te dá controle.

Erros Comuns e Armadilhas

A configuração de shading é a maior. Pule maven-shade-plugin e seu plugin nem vai carregar. Você terá ClassNotFoundException em tempo de execução, e leva um segundo para perceber por quê.

Outro padrão que confunde pessoas: onClick espera List<ResponseAction> para retornar. Uma lista vazia (Collections.emptyList()) é válida e simplesmente mantém a tela aberta. O compilador pega retornos faltantes mesmo assim, então geralmente não é um problema na prática.

Texto de entrada na anvil não é colorido ou especialmente formatado. É só texto. Além do título e conteúdo padrão, não há muita customização visual disponível. Se você precisa de visuais mais bonitos (cores customizadas, texto formatado), você quereria uma abordagem diferente.

Sobre suporte de versão: AnvilGUI funciona em versões recentes. Na verdade, funciona em antigas também via detecção de versão baseada em reflection. Verifique a página de releases se você estiver rodando algo realmente velho, mas a resposta curta é que se seu servidor conseguir carregar a biblioteca, ela funciona.

A biblioteca não trata i18n tradução para você. Se seu servidor suporta múltiplas linguagens, você está traduzindo o título e texto você mesmo antes de passar para AnvilGUI.

Alternativas e Quando Usá-las

Se telas de anvil não são o ajuste certo, você tem outras opções.

GUIs de sign deixam jogadores escrever em um sign, então você lê. Mais simples em alguns aspectos, mas não se sente tão integrado. Jogadores veem um sign em vez de uma anvil.

GUIs de livro usam a interface de livro escritável do Minecraft. Ótimo para texto mais longo, mas é exagero para um único campo de entrada. É uma interação mais pesada.

GUIs completas de inventário customizado te dão controle máximo. Botões, sliders, ícones, cores - o que quiser. O tradeoff é mais código e texturas customizadas. Se você está construindo algo complexo, pode valer a pena. Para entrada de texto simples, é exagero.

Entrada de chat é sempre tecnicamente possível. Só peça ao jogador para responder no chat ou usar um comando. Funciona, mas enche o log de chat e parece gambiarrado. A maioria dos plugins modernos evita.

Minha Opinião Sobre Isso

AnvilGUI resolve um problema específico bem: capturar texto de jogadores sem lutar contra código específico de versão do Minecraft. É uma biblioteca Java com licença MIT, mantida ativamente, e tem 542 stars sólidas no GitHub. Se você está construindo um plugin que precisa de entrada de jogador e uma anvil faz sentido para seu caso de uso, gaste dez minutos integrando isso. Vai economizar você do inferno da debugging de compatibilidade de versão adiante.