Como instalar plugins no servidor de Minecraft

Para instalar um plugin no Minecraft, o servidor precisa rodar Paper, Spigot ou Purpur. Com ele parado, você coloca o arquivo .jar do plugin direto na pasta plugins, liga o servidor de novo e roda plugins no console. Se o nome aparece em verde, o plugin carregou. Em vermelho ou fora da lista, a resposta está no logs/latest.log.

O resto deste guia cobre os detalhes que fazem a instalação dar errado: o tipo de servidor, a versão do Java, a origem do arquivo, a rede com proxy, a atualização e os erros mais comuns.

Plugin só roda em servidor com API Bukkit

O server.jar vanilla da Mojang não carrega plugins. Para isso você precisa de um servidor da família Bukkit: Spigot, Paper ou um fork do Paper, como Purpur e Folia. A documentação do Paper diz que ele é "a drop-in replacement for both CraftBukkit and Spigot", então um plugin feito para Spigot também roda no Paper.

Fabric e Forge são outra coisa: usam mods, que vão na pasta mods, não em plugins. O Paper avisa que um mod de Forge ou Fabric colocado em plugins gera o erro Invalid plugin.yml e não roda.

Em muitas hospedagens, trocar de vanilla para Paper é uma opção do painel; se hospeda você mesmo, basta baixar o JAR do Paper e iniciar com ele no lugar do vanilla. Se a dúvida for o que a hospedagem faz e o que fica com você, o guia hospedagem e loja: o que cada uma faz separa as duas partes.

Confira a versão do Java

Cada versão do Paper pede um Java mínimo. Pela tabela do Paper:

Plugins também têm requisito de Java, e ele aparece na página de cada um. Um plugin compilado para um Java mais novo que o do servidor não carrega, mesmo que a versão do Minecraft bata.

Onde baixar plugins

Baixe só de onde você confia. A página de plugins do Paper é direta sobre o motivo: "Plugins are given full and unrestricted access to not only your server but also the machine that it runs on".

Os lugares que o próprio Paper indica:

• Hangar, o repositório de plugins do Paper.
• Modrinth, que lista plugins e mods.
• BukkitDev e as páginas de GitHub dos próprios autores.

O SpigotMC também é usado por boa parte dos autores. Seja qual for o site, confira na página do plugin as versões do Minecraft suportadas antes de baixar.

Passo a passo da instalação

1. Faça um backup do servidor, ou pelo menos da pasta plugins e das configs.
2. Pare o servidor. O Paper recomenda nunca trocar um JAR com o servidor rodando.
3. Confirme que o arquivo termina em .jar. Se veio um .zip, extraia e pegue o JAR da sua plataforma, que costuma ter bukkit ou paper no nome.
4. Envie o JAR para a pasta plugins, que fica ao lado do JAR do servidor. Na hospedagem, use o gerenciador de arquivos do painel ou SFTP.
5. Ligue o servidor e acompanhe o console durante a inicialização.
6. Rode plugins no console ou /plugins no jogo. Verde quer dizer ativo; vermelho quer dizer que o plugin não está habilitado.

O JAR precisa ficar na raiz de plugins. O servidor não procura em subpastas, então plugins/novos/MeuPlugin.jar é ignorado sem nenhum aviso no log.

Na primeira inicialização, a maioria dos plugins cria uma pasta própria dentro de plugins com o arquivo de configuração. É ali que você ajusta o plugin, sempre com o servidor parado ou usando o comando de reload que o próprio plugin oferecer.

Servidor com proxy (Velocity ou BungeeCord)

Numa rede, cada peça tem seus plugins. O proxy roda plugins feitos para Velocity ou BungeeCord, e os servidores de baixo rodam plugins de Paper ou Spigot. Um JAR de Spigot colocado no Velocity não carrega.

Antes de instalar, veja na página do plugin onde ele deve ficar. Alguns têm um JAR para cada lado; outros só funcionam no backend. Na dúvida, instale nos servidores de jogo, que é onde a maioria dos plugins de gameplay precisa estar.

Jogadores de Bedrock com Geyser

O jeito de aceitar jogadores de Bedrock num servidor Java é o Geyser, que também se instala como plugin. Pelo guia de instalação do Geyser, num servidor Paper ou Spigot você coloca o Geyser-Spigot.jar em plugins, reinicia e ajusta a porta Bedrock em plugins/Geyser-Spigot/config.yml (a padrão é 19132). Lembre de liberar essa porta na hospedagem.

Como atualizar plugins sem derrubar o servidor

O Paper tem um recurso pouco conhecido: a pasta update. Pelo guia de atualização:

1. Crie a pasta update dentro de plugins.
2. Coloque nela os JARs novos dos plugins que quer atualizar.
3. Reinicie o servidor, sem mexer nos JARs que estão fora de update.

Na reinicialização, o Paper troca as versões. Isso evita o erro de ficar com duas versões do mesmo plugin em plugins.

O mesmo guia desaconselha atualização automática: atualize com alguém olhando o log, porque é na inicialização que aparecem os conflitos entre plugins.

Quando o plugin não carrega

O primeiro lugar para olhar é o logs/latest.log, perto do começo, onde os plugins são carregados. Os casos que mais aparecem, segundo a documentação do Paper:

Se o servidor começou a travar ou cair depois de uma instalação, o guia de solução de problemas do Paper sugere desligar metade dos plugins, testar e repetir com a metade suspeita até achar o culpado. Mantenha juntos os plugins que dependem um do outro, como bibliotecas tipo Vault e ProtocolLib e os plugins que as usam.

Exemplo: o plugin da loja

O plugin de uma loja de servidor segue o mesmo processo, com um passo a mais: o token que liga o servidor à loja. Na Gamecart, o guia do conector de Minecraft funciona assim:

1. No painel, em Integrations > Servers, crie um servidor com o método Plugin.
2. Baixe o JAR da sua plataforma na página de downloads: gamecart-spigot para Spigot, Paper, Purpur e Folia (1.8.8 ou mais recente), gamecart-bungeecord, gamecart-velocity (3.5 ou mais recente) ou a versão de Fabric que bate com o seu servidor, que vai em mods.
3. Coloque um único JAR em plugins e inicie o servidor uma vez para gerar a configuração.
4. Cole o token do servidor em serverToken e reinicie.
5. Rode gamecart status no console para ver se conectou.

O mesmo token não deve ser usado em duas instalações, porque as duas passariam a disputar os mesmos comandos. Se preferir não instalar nada, a Gamecart também entrega por RCON. Os comandos que o plugin vai rodar, como o VIP com LuckPerms, estão no guia como entregar VIP automático no Minecraft, e a página da loja para servidor de Minecraft lista as plataformas suportadas.