You are building an adventure map. A player crafts a diamond sword and you want to automatically replace it with your custom version: renamed, with special lore text, custom enchantments, and maybe an attribute modifier.
The trick is using /clear to detect and remove the vanilla item, then /give to hand out the custom version. Here is how to build this system step by step.
The Basic Idea
- Detect that the player has a specific item
- Remove exactly one of that item
- Give them the custom version
All three steps happen in a single tick, so the player sees an instant transformation.
Step 1: Detect and Remove with /clear
The /clear command does two things: it checks if a player has an item, and it removes it.
/clear @a diamond_sword 0 0
Wait: this syntax changed in 1.13+. The modern syntax is:
/clear @a minecraft:diamond_sword 1
This removes exactly 1 diamond sword from every player who has one. The command returns a success value that you can check with /execute store.
Step 2: Build the Detection Chain
Use a repeating command block with this command:
/execute as @a[nbt={Inventory:[{id:"minecraft:diamond_sword"}]}] run clear @s minecraft:diamond_sword 1
This checks every player's inventory for a diamond sword. If found, it removes one. The as @a part makes sure the command runs for each player individually.
Step 3: Give the Custom Item
Chain a conditional command block after the clear command. Conditional means it only runs if the previous command succeeded (meaning an item was actually removed):
/give @s minecraft:diamond_sword[custom_name='{"text":"Blade of the Void","color":"dark_purple","italic":false}',lore=['{"text":"Forged in shadow","color":"gray","italic":true}','{"text":"","italic":false}','{"text":"+5 Attack Damage","color":"green","italic":false}'],enchantments={levels:{"minecraft:sharpness":5,"minecraft:fire_aspect":2,"minecraft:unbreaking":3}},attribute_modifiers=[{type:"minecraft:attack_damage",amount:5.0,operation:"add_value",slot:"mainhand",id:"minecraft:custom_sword_damage"}]] 1
This gives the player a diamond sword with:
- Custom name: "Blade of the Void" in dark purple
- Two lines of lore text
- Sharpness 5, Fire Aspect 2, Unbreaking 3
- +5 attack damage attribute modifier
Breaking Down the NBT Syntax (1.21+)
Starting from 1.20.5, Minecraft replaced the old NBT {tag:{...}} format with component syntax. Here is a reference for the most useful components:
| Component | Example | What It Does |
|---|---|---|
| custom_name | custom_name='{"text":"Cool Sword","color":"gold"}' | Sets the item name |
| lore | lore=['{"text":"Line 1"}','{"text":"Line 2"}'] | Adds description lines |
| enchantments | enchantments={levels:{"minecraft:sharpness":5}} | Adds enchantments |
| attribute_modifiers | See above example | Adds stat modifiers |
| unbreakable | unbreakable={} | Item never breaks |
| custom_model_data | custom_model_data=12345 | Links to resource pack model |
| max_stack_size | max_stack_size=1 | Limits stack size |
Full Command Block Setup
You need two command blocks chained together:
Block 1: Repeating, Always Active
/execute as @a[nbt={Inventory:[{id:"minecraft:diamond_sword",components:{"!minecraft:custom_name":{}}}]}] run clear @s minecraft:diamond_sword 1
The "!minecraft:custom_name":{} filter means: only match swords that do NOT have a custom name. This prevents the command from removing the custom sword you gave them and creating an infinite loop.
Block 2: Chain, Conditional, Always Active
/give @s minecraft:diamond_sword[custom_name='{"text":"Blade of the Void","color":"dark_purple","italic":false}',enchantments={levels:{"minecraft:sharpness":5}}] 1
The chain block inherits the @s context from the repeating block, so it gives the item to the correct player.
Preventing Infinite Loops
The biggest mistake is forgetting to exclude your custom item from the detection. If you remove "any diamond sword" and give back "a diamond sword with a name", the repeating command block will detect the named sword and remove it next tick.
Always add a filter that distinguishes the vanilla version from the custom version. Options:
- Check for the absence of
custom_name(shown above) - Check for a specific
custom_model_datavalue - Use a custom item tag
Testing
Test your command chain in creative mode first:
- Place both command blocks
- Craft a regular diamond sword
- The sword should instantly transform into the custom version
- Crafting a second regular sword should also transform
- The custom sword in your inventory should NOT get replaced again
If the custom sword keeps disappearing and reappearing, your detection filter is not working. Check the NBT exclusion syntax.
This setup works the same way on a Space-Node hosted server. Place command blocks, configure the chain, and every player who crafts the item gets the upgraded version automatically. Get started here.
