Guia

Como criar um plugin de Paper

Atualizado em 7 de outubro de 2026

O Paper é o software de servidor de Minecraft mais usado para plugins: ele roda plugins do Spigot e acrescenta uma API maior e mais rápida. Um plugin de Paper é um projeto Java (ou Kotlin) compilado contra o paper-api. Aqui está o que ele precisa, à mão ou com uma IA que compila para você.

Um exemplo para começar.

Gere isto com o Codexe

Passo a passo

  1. 1.Escolha a versão do Minecraft

    Use a versão que o seu servidor roda. Ela define a versão do Java: Java 17 antes da 1.20.5, Java 21 a partir da 1.20.5 e Java 25 para a 26.x.

  2. 2.Crie o projeto

    Um projeto Gradle ou Maven com a dependência paper-api dessa versão, do repositório do PaperMC, no escopo provided/compileOnly.

  3. 3.Escreva a classe principal

    Uma classe que estenda JavaPlugin, com onEnable() para registrar comandos e listeners.

  4. 4.Descreva o plugin para o servidor

    plugin.yml (name, version, main, api-version, commands, permissions). O Paper também aceita o paper-plugin.yml, com regras de carregamento próprias.

  5. 5.Compile e teste

    Gere o .jar, coloque na pasta plugins/ de um servidor de teste Paper, inicie e confira se há erros no console.

Paper ou Spigot?

O código escrito para a API do Spigot roda no Paper, mas o contrário não vale: o Paper acrescenta eventos e métodos (por exemplo, os componentes de texto do Adventure e muitas APIs assíncronas) que o Spigot não tem. Escreva para o Paper se o seu servidor roda Paper; escreva para o Spigot se o plugin também precisa rodar em servidores Spigot.

O caminho rápido

No Codexe, escolha um plugin de Bukkit/Spigot/Paper, diga "Paper" e a versão no pedido, e descreva o que ele faz. O Codexe configura o projeto e a versão certa do Java, compila, corrige os erros de build e deixa você entrar em um servidor de teste Paper com o plugin instalado.

Problemas comuns

  • UnsupportedClassVersionError: o plugin foi compilado com um Java mais novo do que o do servidor.
  • NoSuchMethodError / NoClassDefFoundError: o plugin usa uma API que não existe na versão do servidor, ou uma dependência não foi incluída (shade) no .jar.
  • O plugin carrega, mas os comandos não fazem nada: o comando não está no plugin.yml ou o executor não foi registrado.

Perguntas

Os plugins de Paper funcionam no Purpur ou no Folia?

O Purpur é um fork do Paper, então os plugins de Paper rodam nele. O Folia muda o tratamento de threads: para rodar no Folia, um plugin precisa ser escrito para o agendador por regiões dele.

Posso escrever um plugin de Paper em Kotlin?

Sim. O Codexe pode gerar um projeto Gradle em Kotlin com build.gradle.kts para a mesma API do Paper.

Crie agora um plugin de Paper

Este prompt abre pronto para enviar:

“Um plugin para Paper 1.21.4 chamado Bounties: /bounty set <player> <amount> usando a economia do Vault, quem mata recebe a recompensa, /bounty list mostra o top 10, as recompensas são salvas entre reinicializações e as mensagens ficam no config.yml.”

Gere isto com o Codexe
Como criar um plugin de Paper (Minecraft) | Codexe