Guia
Como criar itens personalizados com um plugin
Atualizado em 18 de outubro de 2026
Espadas, varinhas, chaves e ferramentas personalizadas estão entre os recursos de plugin mais pedidos. Um plugin não consegue adicionar um item realmente novo ao jogo, mas consegue pegar um item vanilla, dar a ele um nome, uma lore e uma tag oculta, e reagir quando um jogador o usa. Os jogadores entram com o jogo normal, sem precisar de mods.
Troque os itens pelos seus.
Gere isto com o CodexePasso a passo
1.Liste os itens
Para cada item: o material base, o nome exibido, as linhas de lore e o que ele faz. "Uma vara de blaze chamada Fire Wand que lança uma bola de fogo com o clique direito, cooldown de 5 segundos" é um item completo.
2.Marque os itens com o PersistentDataContainer
Guarde um id como
fire_wandnoPersistentDataContainerdo item com umaNamespacedKey. O plugin reconhece o item por essa tag, não pelo nome, então renomeá-lo em uma bigorna não cria uma cópia.3.Escreva as habilidades
Cada habilidade é um listener de evento:
PlayerInteractEventpara cliques direitos,EntityDamageByEntityEventpara golpes,BlockBreakEventpara ferramentas. Adicione cooldowns por jogador e por item.4.Decida como os jogadores os conseguem
Um comando de admin
/give, uma receita de crafting, uma loja, drops de mobs ou recompensas de caixas.5.Deixe tudo configurável
Nomes, lore, dano, cooldowns e receitas no
config.yml, para você equilibrar os itens sem um novo build.6.Compile e teste cada item
Deixe o Codexe compilar o plugin, entre no servidor de teste com o Teste agora, dê a si mesmo cada item e use.
Por que uma tag e não o nome
Verificar o nome exibido ou a lore é o erro clássico: qualquer jogador com uma bigorna pode renomear um graveto para "Fire Wand". O PersistentDataContainer (Minecraft 1.14 e mais recentes) guarda no item dados que os jogadores não podem editar, e eles sobrevivem a reinícios, baús e trocas porque fazem parte do item.
Da 1.8 à 1.13 não existe PersistentDataContainer; os plugins usam NBT por meio de uma biblioteca ou um marcador oculto na lore. Escreva a versão no pedido e o Codexe usa a abordagem que essa versão suporta.
As habilidades e os eventos por trás delas
| Habilidade | Evento | Observações |
|---|---|---|
| Poder com clique direito | PlayerInteractEvent | Verifique a mão, ele dispara uma vez por mão |
| Dano extra ou efeitos ao acertar | EntityDamageByEntityEvent | Verifique se quem causou o dano é um jogador segurando o item |
| Ferramenta de mineração em área | BlockBreakEvent | Respeite plugins de proteção como o WorldGuard |
| Efeito passivo enquanto segura | Uma tarefa repetida ou o PlayerItemHeldEvent | Remova o efeito quando o item for guardado |
| Arco ou projétil | EntityShootBowEvent, ProjectileHitEvent | Marque o projétil com uma tag para saber de onde ele veio |
Texturas e modelos
Um plugin muda o que um item faz, não a aparência dele. Uma aparência personalizada precisa de um resource pack que os jogadores baixam: nas versões mais antigas o item carrega um número CustomModelData que o pack associa a um modelo, e a partir da 1.21.2 um item também pode apontar para o próprio modelo pelo componente item_model. Sem um pack, o item fica com a cara do material base e um nome personalizado, o que basta para muitos servidores.
Exemplo de descrição
"Um plugin para Paper 1.21.4 chamado MagicItems. Três itens, cada um marcado com um id no PersistentDataContainer: Fire Wand (vara de blaze, clique direito lança uma bola de fogo, cooldown de 5 s), Frost Blade (espada de ferro, os golpes dão Lentidão II por 3 s), Miner's Pick (picareta de diamante, quebra 3x3 mas não em regiões do WorldGuard onde o jogador não pode construir). /mi give <player> <item> para magicitems.admin. Receitas com formato para cada um. Nomes, lore, cooldowns e receitas no config.yml."
Perguntas
Plugin ou mod para itens personalizados?
Um plugin, se os jogadores devem entrar com o jogo normal: os itens são itens vanilla com um comportamento novo. Um mod, se você precisa de itens ou blocos realmente novos com renderização própria, que todo jogador vai ter que instalar. Veja plugin vs mod.
Posso usar o ItemsAdder ou o Nexo com ele?
O seu plugin pode depender deles, mas são plugins pagos: o servidor de teste do Codexe não consegue instalá-los, então um plugin que exige um deles não vai ser ativado lá. As dependências gratuitas listadas no plugin.yml são instaladas no servidor de teste para você.
Os itens param de funcionar depois de uma atualização?
Itens marcados com o PersistentDataContainer mantêm a tag entre atualizações do Minecraft. As habilidades podem precisar de um novo build para a nova API; veja como atualizar um plugin.
Crie os seus itens personalizados
Este prompt abre pronto para enviar:
“Um plugin para Paper 1.21.4 chamado MagicItems com três itens marcados pelo PersistentDataContainer: Fire Wand (vara de blaze, clique direito lança uma bola de fogo, cooldown de 5 segundos), Frost Blade (espada de ferro, Lentidão II por 3 segundos ao acertar), Miner's Pick (picareta de diamante que minera 3x3). /mi give para magicitems.admin, uma receita com formato para cada um, nomes, lore, cooldowns e receitas no config.yml.”
Gere isto com o Codexe