Guide
How to make custom items with a plugin
Updated October 18, 2026
Custom swords, wands, keys and tools are some of the most requested plugin features. A plugin cannot add a truly new item to the game, but it can take a vanilla item, give it a name, lore and a hidden tag, and react when a player uses it. Players join with the normal game, no mods needed.
Change the items to your own.
Generate this with CodexeStep by step
1.List the items
For each item: the base material, the display name, the lore lines and what it does. "A blaze rod called Fire Wand that shoots a fireball on right click, 5-second cooldown" is a complete item.
2.Tag them with PersistentDataContainer
Store an id such as
fire_wandin the item'sPersistentDataContainerwith aNamespacedKey. The plugin recognises the item by that tag, not by its name, so renaming it in an anvil does not create a copy.3.Write the abilities
Each ability is an event listener:
PlayerInteractEventfor right clicks,EntityDamageByEntityEventfor hits,BlockBreakEventfor tools. Add cooldowns per player and per item.4.Decide how players get them
An admin
/givecommand, a crafting recipe, a shop, mob drops or crate rewards.5.Make everything configurable
Names, lore, damage, cooldowns and recipes in
config.yml, so you can balance items without a new build.6.Build and try every item
Let Codexe compile the plugin, join the test server with Try it now, give yourself each item and use it.
Why a tag and not the name
Checking the display name or lore is the classic mistake: any player with an anvil can rename a stick to "Fire Wand". The PersistentDataContainer (Minecraft 1.14 and newer) stores data on the item that players cannot edit, and it survives restarts, chests and trades because it is part of the item.
On 1.8 to 1.13 there is no PersistentDataContainer; plugins use NBT through a library or a hidden lore marker. Say the version in the request and Codexe writes the approach that version supports.
Abilities and the events behind them
| Ability | Event | Notes |
|---|---|---|
| Right-click power | PlayerInteractEvent | Check the hand, it fires once per hand |
| Extra damage or effects on hit | EntityDamageByEntityEvent | Check the damager is a player holding the item |
| Area mining tool | BlockBreakEvent | Respect protection plugins such as WorldGuard |
| Passive effect while held | A repeating task or PlayerItemHeldEvent | Remove the effect when the item is put away |
| Bow or projectile | EntityShootBowEvent, ProjectileHitEvent | Tag the projectile to know where it came from |
Textures and models
A plugin changes what an item does, not how it looks. A custom look needs a resource pack that players download: on older versions the item carries a CustomModelData number the pack maps to a model, and from 1.21.2 an item can also point to its own model through the item_model component. Without a pack the item looks like its base material with a custom name, which is fine for many servers.
Example description
"A Paper 1.21.4 plugin called MagicItems. Three items, each tagged with a PersistentDataContainer id: Fire Wand (blaze rod, right click shoots a fireball, 5 s cooldown), Frost Blade (iron sword, hits give Slowness II for 3 s), Miner's Pick (diamond pickaxe, breaks 3x3 but not in WorldGuard regions where the player cannot build). /mi give <player> <item> for magicitems.admin. Shaped recipes for each. Names, lore, cooldowns and recipes in config.yml."
Questions
Plugin or mod for custom items?
A plugin if players should join with the normal game: the items are vanilla items with new behaviour. A mod if you need genuinely new items or blocks with their own rendering, which every player then installs. See plugin vs mod.
Can I use ItemsAdder or Nexo with it?
Your plugin can depend on them, but they are paid plugins: the Codexe test server cannot install them, so a plugin that requires one will not enable there. Free dependencies listed in plugin.yml are installed on the test server for you.
Do the items stop working after an update?
Items tagged with a PersistentDataContainer keep their tag across Minecraft updates. Abilities may need a rebuild for the new API; see updating a plugin.
Make your custom items
This prompt opens ready to send:
“A Paper 1.21.4 plugin called MagicItems with three items tagged by PersistentDataContainer: Fire Wand (blaze rod, right click shoots a fireball, 5 second cooldown), Frost Blade (iron sword, Slowness II for 3 seconds on hit), Miner's Pick (diamond pickaxe that mines 3x3). /mi give for magicitems.admin, a shaped recipe for each, names, lore, cooldowns and recipes in config.yml.”
Generate this with Codexe