Como atualizar um plugin para uma nova versão do Minecraft

Passo a passo

1. 1.Teste primeiro o .jar antigo

   Coloque-o em um servidor de teste da nova versão e leia o console. Se ele carregar e funcionar, talvez você não precise mudar nada.

2. 2.Mude a dependência da API

   No pom.xml ou no build.gradle, defina paper-api ou spigot-api com a nova versão.

3. 3.Atualize o api-version e o Java

   Defina o api-version no plugin.yml (por exemplo '1.21') e compile para o Java que a nova versão exige: Java 17 antes da 1.20.5, Java 21 a partir da 1.20.5, Java 25 para a 26.x.

4. 4.Corrija o que não compila mais

   Compile e passe pelos erros: materiais renomeados, métodos removidos, classes de evento alteradas. O compilador lista cada um com arquivo e linha.

5. 5.Atualize as dependências

   Os plugins que o seu plugin usa (Vault, PlaceholderAPI, ProtocolLib, WorldGuard) também precisam de versões que suportem a nova versão do Minecraft, tanto no arquivo de build quanto no servidor.

6. 6.Teste na nova versão

   Carregue-o em um servidor da nova versão com os mesmos plugins e teste cada comando e recurso, não só a inicialização.

O que costuma quebrar

• Nomes de materiais e enums: a atualização 1.13 renomeou a maioria dos itens e blocos; as versões seguintes adicionam, renomeiam ou removem alguns. Código que usa nomes antigos ou ids numéricos falha.
• Métodos obsoletos removidos: métodos marcados como obsoletos por várias versões acabam sumindo.
• Dados dos itens: a partir da 1.20.5, o NBT dos itens foi substituído pelos data components. Plugins que editam o NBT dos itens diretamente precisam reescrever essa parte; a API normal de ItemMeta continua funcionando.
• NMS e reflection: código que usa classes internas do servidor quebra em quase todas as versões. Substitua pela API sempre que possível, ou por uma biblioteca como o ProtocolLib.
• Versões de bibliotecas: bibliotecas empacotadas (shaded) compiladas para um Java mais antigo podem falhar no novo.

Atualizando através de muitas versões

Ir da 1.8 ou da 1.12 para a 1.21 está mais perto de reescrever as partes que mexem com itens, blocos e partículas do que de uma atualização. Faça tudo de uma vez com a nova API, não versão por versão, e conte com a necessidade de novos nomes de materiais também nos arquivos de configuração.

Se o plugin precisa suportar várias versões ao mesmo tempo, compile com a mais antiga que você suporta e evite APIs adicionadas depois, ou use builds separados por versão.

Com o Codexe

No Pro e acima, você pode importar o código-fonte do plugin como ZIP e pedir, por exemplo, "Este é o meu plugin para Paper 1.20.4. Atualize para Paper 1.21.4". O Codexe lê a versão do Minecraft no arquivo de build, compila com o Java que essa versão exige e corrige os erros de compilação usando as assinaturas reais da API com a qual compila. Para um plugin que você fez no Codexe, peça a nova versão no chat do projeto.

Compilar prova que o plugin compila com a nova API. Depois teste em um servidor de teste, porque mudanças de comportamento entre versões não aparecem como erros de compilação.

Perguntas