Um plugin Paper pode adicionar comandos, proteções, economia ou minijogos, mas a instalação altera o código executado no servidor. O nome do arquivo e a página de download não garantem compatibilidade. Confira projeto, versão, dependências e log de inicialização antes de concluir que está pronto para produção.

Este procedimento cobre uma instalação controlada. O Paper recomenda obter plugins de fontes reconhecidas, colocar o JAR no diretório correto, reiniciar e verificar o carregamento. Faça teste numa cópia para plugins que alteram mundo, permissões ou dados persistentes.

Confirme o projeto e a fonte

Pesquise o nome exato do plugin e localize sua página oficial no repositório do projeto ou no Hangar, Modrinth ou BukkitDev quando aplicável. Confirme autor, descrição, licença, versões suportadas e data do artefato. Um espelho ou site de download com muitos botões pode entregar instalador ou HTML em vez do JAR.

Se usar download direto ou ferramenta de linha de comando, verifique o conteúdo e tamanho do arquivo. A documentação do Paper alerta que um erro de rede pode salvar uma página de erro com extensão enganosa. Não execute o arquivo apenas porque termina em .jar; compare hash publicado, assinatura ou origem quando disponível.

Confira compatibilidade e dependências

Leia a compatibilidade declarada com a versão do Minecraft, Paper e Java que seu processo realmente usa. Confirme bibliotecas exigidas e se algum outro plugin fornece integração opcional. Verifique se a dependência deve ficar também no diretório plugins e se existe ordem ou passo de configuração.

Não escolha build de desenvolvimento só porque é o arquivo mais recente sem entender o motivo. Algumas releases exigem uma versão específica ou ainda estão em teste. Para rede com Velocity, Geyser ou servidor modificado, confirme compatibilidade em toda a arquitetura, não só no Paper principal.

Faça cópia e use homologação

Plugin pode criar arquivo, tabela de banco ou editar dados do mundo na primeira inicialização. Faça backup e teste numa instância isolada. Uma cópia de teste não pode enviar pagamentos, mensagens públicas, sincronizar permissões para produção ou escrever no banco real.

Instale uma versão por vez e registre arquivo e versão. Inicie e leia o console inteiro; não pare na linha “enabling plugin”. Procure erros de dependência, migração, incompatibilidade e configuração. Se plugin altera dados, reinicie novamente na cópia e verifique se o estado continua válido depois da segunda partida.

Coloque o JAR no lugar correto

Com servidor parado, envie o JAR ao diretório plugins que está na raiz de execução. Não o deixe dentro de subpasta, pois o Paper normalmente procura arquivos na pasta raiz de plugins. Confirme diretório de trabalho do painel: em hospedagem, a raiz visível pode não ser a pasta que o processo usa.

Evite manter duas versões do mesmo plugin. Uma cópia antiga e outra nova podem gerar conflito ou carregar arquivo inesperado. Mova a versão anterior para local de backup fora da pasta carregada e mantenha registro para rollback. Não atualize plug-in ativo por upload se painel não garante parada completa.

Reinicie e confirme carregamento

Inicie o servidor normalmente. O log deve indicar versão e estado de carregamento. Se não aparecer, confira se o JAR está na raiz correta, se o processo iniciou e se o arquivo é realmente um plugin. O comando /plugins ou plugins no console pode confirmar a lista carregada, mas um nome verde ainda não garante que a configuração está funcional.

Leia a primeira exceção relevante, não somente os últimos avisos. Stack traces longos podem repetir consequências de um erro anterior. Copie contexto necessário, versão e trecho integral sem expor segredos ou dados privados. Consulte a documentação do plugin antes de renomear arquivos ou apagar configuração.

Valide função e permissão

Teste a função principal com conta comum e ambiente esperado. Um comando administrativo pode funcionar para OP mesmo quando os nós LuckPerms estão ausentes. Confirme comandos, mensagens, proteção, persistência e integração com plugins relacionados, por exemplo Vault ou PlaceholderAPI se o projeto depender deles.

Revise a lista de permissões que o autor publica. Não conceda wildcard administrativo por conveniência. Adicione os nós necessários ao grupo mínimo e teste acesso negado e permitido. A equipe de staff pode precisar de subconjuntos diferentes conforme responsabilidade.

Atualize sem reload quente

Quando trocar versão, pare Paper por completo e faça backup conforme necessário. O comando reload é conhecido por causar problemas com plugins e pode deixar listeners ou tarefas duplicadas. Um restart completo permite que as classes antigas saiam e a nova versão inicialize conforme esperado.

Leia notas de versão e alterações de configuração. Faça upgrade de dependências requeridas, mas evite mudar vários plugins juntos se precisa isolar uma regressão. Após o restart, valide funções e logs novamente. Se voltar, alinhe a versão do plugin e os dados criados; nem toda migração de configuração pode ser revertida trocando apenas JAR.

Remova com segurança

Desinstalar um plugin também exige plano. Identifique arquivos de configuração, mundos próprios, tabelas externas e dados compartilhados que ele criou. Não apague tudo sem ler como o plugin armazena estado. Alguns registros podem ser usados por outro plugin ou representar dados de jogador.

Faça parada completa, mova o JAR para fora do diretório carregado e reinicie. Confirme ausência de erro em plugins dependentes. Guarde cópia antes de remover configurações e documente se a remoção foi temporária ou definitiva.

Siga o guia do Paper para instalar e conferir plugins, consulte troubleshooting e entenda as diferenças do sistema de Paper plugins quando o projeto usar esse formato. Confirme documentação e requisitos específicos do autor antes de executar código novo.

Confira biblioteca e plugin de dependência

Quando o log informa que falta uma classe ou plugin requerido, confirme a dependência oficial e sua versão. Não baixe um JAR de nome parecido em fórum aleatório. Alguns projetos são bibliotecas que carregam antes do plugin principal; outros são opcionais e ativam só uma integração. Siga a lista de dependências do autor.

Após corrigir, faça uma parada completa e reinicie. Verifique ambas as linhas de carregamento e execute a função integrada. Se a mesma exceção aparecer, não continue instalando arquivos às cegas: salve o stack trace, versão de Java, Paper e os JARs envolvidos para isolar a incompatibilidade.

Teste em diretório isolado com dados reais de exemplo

Um plugin novo pode gerar configuração apenas na primeira partida. Copie o servidor sem credenciais e dados de clientes, instale o artefato e leia o arquivo criado com comentários e defaults. Compare com documentação oficial para preencher valores mínimos; não substitua um arquivo inteiro por exemplo antigo sem conferir se a versão mudou a estrutura.

Exercite o cenário que pretende atender e reinicie mais uma vez para verificar persistência. Essa segunda inicialização ajuda a encontrar tarefa que só falha após salvar configuração ou migrar banco. Se o teste alterar o mundo, descarte a cópia em vez de misturá-la de volta à produção.

Fontes e referências

Documentação consultada em 2026-10-08. Os exemplos precisam ser conferidos na versão instalada; este guia não afirma que a configuração foi testada no seu ambiente.