How to make a tool tier of your own in a Minecraft mod
A tier is the material of a tool (called a tool material from 1.21.2): how many uses it has, how fast it mines, the damage bonus, which blocks it cannot harvest, how enchantable it is and what repairs it. Vanilla keeps them in Tiers (ToolMaterial from 1.21.2). For your own, implement Tier in an enum (IItemTier on 1.16.5, Forge’s EnumHelper on 1.12.2) or, from 1.21.2, build a ToolMaterial record, and pass it to the tool item. Every tool of the material shares the one tier, so a change to the numbers changes all of them.
Works on Minecraft 1.20.1 to 26.3 on NeoForge; Minecraft 1.16.5 to 26.3 on Fabric; Minecraft 1.16.5 to 1.20.1 on Forge; Minecraft 1.12.2 on Forge. Each example was compiled against its loader and version before it shipped in Linen.
- Write the tier with your numbers (an enum that implements Tier, or a ToolMaterial on 1.21.2 and newer).
- On 1.20.5 and newer, pick the incorrect-blocks tag: INCORRECT_FOR_IRON_TOOL, or your own tag.
- Pass the tier to a tool item (a tool class such as SwordItem, or the tool properties on 1.21.5 and newer).
- Check the durability and mining speed in the game.
What you can change
Section titled “What you can change”The example uses these values. Change them in the code.
| Setting | In the example | What it does |
|---|---|---|
| uses | 800 |
Durability (iron 250, diamond 1561). |
| mining | 7 |
Mining speed (iron 6, diamond 8). |
| bonus | 2.5 |
Attack bonus (iron 2, diamond 3). |
| repair | IRON_INGOT |
The item that repairs it. |
For each loader and version
Section titled “For each loader and version”The example mod is examplemod in the package com.example.examplemod. Use your own mod id and package.
Fabric and NeoForge 1.20.1 to 1.20.4, Fabric 1.16.5 to 1.20, Forge 1.17.1 to 1.20.1
Section titled “Fabric and NeoForge 1.20.1 to 1.20.4, Fabric 1.16.5 to 1.20, Forge 1.17.1 to 1.20.1”Uses:
TierTier.getUsesTier.getSpeedTier.getLevel
The tier is not registered with Forge. For tools that should sit between vanilla tiers, register it with TierSortingRegistry.registerTier.
src/main/java/com/example/examplemod/item/RubySwordItem.java
package com.example.examplemod.item;
import net.minecraft.world.item.Item;import net.minecraft.world.item.SwordItem;
// Ruby Sword: a sword of its own tier, RubySwordItemTier.public class RubySwordItem extends SwordItem { public RubySwordItem(Item.Properties properties) { super(RubySwordItemTier.INSTANCE, 3, -2.4F, properties); }}src/main/java/com/example/examplemod/item/RubySwordItemTier.java
package com.example.examplemod.item;
import net.minecraft.world.item.Item;import net.minecraft.world.item.Items;import net.minecraft.world.item.Tier;import net.minecraft.world.item.crafting.Ingredient;
// The tier of Ruby Sword: 800 uses, mining speed 7.0F, attack bonus 2.5F. Tools of this tier mine like iron, by the level below.public enum RubySwordItemTier implements Tier { INSTANCE;
@Override public int getUses() { return 800; }
@Override public float getSpeed() { return 7.0F; }
@Override public float getAttackDamageBonus() { return 2.5F; }
// The mining level: 2 is iron, so blocks that need iron or less drop. (Level 3 is diamond, 4 netherite.) @Override public int getLevel() { return 2; }
@Override public int getEnchantmentValue() { return 15; }
@Override public Ingredient getRepairIngredient() { return Ingredient.of(Items.IRON_INGOT); }}In src/main/resources/data/minecraft/tags/items/swords.json, add this to the list at /values:
"examplemod:ruby_sword"It’s registered like any other item, as RubySwordItem: see a new item.
Fabric and NeoForge 1.20.5 to 1.20.6
Section titled “Fabric and NeoForge 1.20.5 to 1.20.6”Uses:
TierTier.getUsesTier.getSpeedTier.getIncorrectBlocksForDropsBlockTags.INCORRECT_FOR_IRON_TOOL
src/main/java/com/example/examplemod/item/RubySwordItem.java
package com.example.examplemod.item;
import net.minecraft.world.item.Item;import net.minecraft.world.item.SwordItem;
// Ruby Sword: a sword of its own tier, RubySwordItemTier.public class RubySwordItem extends SwordItem { public RubySwordItem(Item.Properties properties) { super(RubySwordItemTier.INSTANCE, properties.attributes(SwordItem.createAttributes(RubySwordItemTier.INSTANCE, 3, -2.4F))); }}src/main/java/com/example/examplemod/item/RubySwordItemTier.java
package com.example.examplemod.item;
import net.minecraft.tags.BlockTags;import net.minecraft.tags.TagKey;import net.minecraft.world.item.Item;import net.minecraft.world.item.Items;import net.minecraft.world.item.Tier;import net.minecraft.world.item.crafting.Ingredient;import net.minecraft.world.level.block.Block;
// The tier of Ruby Sword: 800 uses, mining speed 7.0F, attack bonus 2.5F. Tools of this tier mine like iron or better, by the tag below.public enum RubySwordItemTier implements Tier { INSTANCE;
@Override public int getUses() { return 800; }
@Override public float getSpeed() { return 7.0F; }
@Override public float getAttackDamageBonus() { return 2.5F; }
// The blocks this tier cannot mine for drops: the tag of blocks that need a better tool. @Override public TagKey<Block> getIncorrectBlocksForDrops() { return BlockTags.INCORRECT_FOR_IRON_TOOL; }
@Override public int getEnchantmentValue() { return 15; }
@Override public Ingredient getRepairIngredient() { return Ingredient.of(Items.IRON_INGOT); }}In src/main/resources/data/minecraft/tags/items/swords.json, add this to the list at /values:
"examplemod:ruby_sword"It’s registered like any other item, as RubySwordItem: see a new item.
Fabric and NeoForge 1.21 to 1.21.1
Section titled “Fabric and NeoForge 1.21 to 1.21.1”Uses:
TierTier.getUsesTier.getSpeedTier.getIncorrectBlocksForDropsBlockTags.INCORRECT_FOR_IRON_TOOL
src/main/java/com/example/examplemod/item/RubySwordItem.java
package com.example.examplemod.item;
import net.minecraft.world.item.Item;import net.minecraft.world.item.SwordItem;
// Ruby Sword: a sword of its own tier, RubySwordItemTier.public class RubySwordItem extends SwordItem { public RubySwordItem(Item.Properties properties) { super(RubySwordItemTier.INSTANCE, properties.attributes(SwordItem.createAttributes(RubySwordItemTier.INSTANCE, 3, -2.4F))); }}src/main/java/com/example/examplemod/item/RubySwordItemTier.java
package com.example.examplemod.item;
import net.minecraft.tags.BlockTags;import net.minecraft.tags.TagKey;import net.minecraft.world.item.Item;import net.minecraft.world.item.Items;import net.minecraft.world.item.Tier;import net.minecraft.world.item.crafting.Ingredient;import net.minecraft.world.level.block.Block;
// The tier of Ruby Sword: 800 uses, mining speed 7.0F, attack bonus 2.5F. Tools of this tier mine like iron or better, by the tag below.public enum RubySwordItemTier implements Tier { INSTANCE;
@Override public int getUses() { return 800; }
@Override public float getSpeed() { return 7.0F; }
@Override public float getAttackDamageBonus() { return 2.5F; }
// The blocks this tier cannot mine for drops: the tag of blocks that need a better tool. @Override public TagKey<Block> getIncorrectBlocksForDrops() { return BlockTags.INCORRECT_FOR_IRON_TOOL; }
@Override public int getEnchantmentValue() { return 15; }
@Override public Ingredient getRepairIngredient() { return Ingredient.of(Items.IRON_INGOT); }}In src/main/resources/data/minecraft/tags/item/swords.json, add this to the list at /values:
"examplemod:ruby_sword"It’s registered like any other item, as RubySwordItem: see a new item.
Fabric and NeoForge 1.21.2 to 1.21.4
Section titled “Fabric and NeoForge 1.21.2 to 1.21.4”Uses:
ToolMaterialToolMaterial.durabilityToolMaterial.speedToolMaterial.incorrectBlocksForDropsSwordItemBlockTags.INCORRECT_FOR_IRON_TOOLItemTags.IRON_TOOL_MATERIALS
Since 1.21.2 a tier is the ToolMaterial record, not an interface: you build one with new ToolMaterial(…) and pass it to the tool class. The repair items are a tag (here the vanilla iron one); use your own item tag to change what repairs it.
src/main/java/com/example/examplemod/item/RubySwordItem.java
package com.example.examplemod.item;
import net.minecraft.world.item.Item;import net.minecraft.world.item.SwordItem;
// Ruby Sword: a sword of its own tier, RubySwordItemToolMaterial. The numbers are the attack damage and speed on top of the tier's.public class RubySwordItem extends SwordItem { public RubySwordItem(Item.Properties properties) { super(RubySwordItemToolMaterial.INSTANCE, 3, -2.4F, properties); }}src/main/java/com/example/examplemod/item/RubySwordItemToolMaterial.java
package com.example.examplemod.item;
import net.minecraft.tags.BlockTags;import net.minecraft.tags.ItemTags;import net.minecraft.world.item.ToolMaterial;
// The tier of Ruby Sword: 800 uses, mining speed 7.0F, attack bonus 2.5F. Since 1.21.2 a tier is a ToolMaterial record, not an interface.public final class RubySwordItemToolMaterial { private RubySwordItemToolMaterial() { }
// Arguments: blocks it cannot mine for drops (a tag), durability, mining speed, attack bonus, enchantability, tag of repair items. public static final ToolMaterial INSTANCE = new ToolMaterial(BlockTags.INCORRECT_FOR_IRON_TOOL, 800, 7.0F, 2.5F, 15, ItemTags.IRON_TOOL_MATERIALS);}In src/main/resources/data/minecraft/tags/item/swords.json, add this to the list at /values:
"examplemod:ruby_sword"It’s registered like any other item, as RubySwordItem: see a new item.
Fabric and NeoForge 1.21.5 to 26.3
Section titled “Fabric and NeoForge 1.21.5 to 26.3”Uses:
ToolMaterialToolMaterial.durabilityToolMaterial.speedToolMaterial.incorrectBlocksForDropsItem.Properties.swordBlockTags.INCORRECT_FOR_IRON_TOOLItemTags.IRON_TOOL_MATERIALS
Since 1.21.2 a tier is the ToolMaterial record, not an interface: you build one with new ToolMaterial(…). Since 1.21.5 there is no SwordItem: Item.Properties#sword(material, damage, speed) makes a plain Item a sword. The repair items are a tag (here the vanilla iron one); use your own item tag to change what repairs it.
src/main/java/com/example/examplemod/item/RubySwordItem.java
package com.example.examplemod.item;
import net.minecraft.world.item.Item;
// Ruby Sword: a sword of its own tier, RubySwordItemToolMaterial. The numbers are the attack damage and speed on top of the tier's.public class RubySwordItem extends Item { public RubySwordItem(Item.Properties properties) { super(properties.sword(RubySwordItemToolMaterial.INSTANCE, 3, -2.4F)); }}src/main/java/com/example/examplemod/item/RubySwordItemToolMaterial.java
package com.example.examplemod.item;
import net.minecraft.tags.BlockTags;import net.minecraft.tags.ItemTags;import net.minecraft.world.item.ToolMaterial;
// The tier of Ruby Sword: 800 uses, mining speed 7.0F, attack bonus 2.5F. Since 1.21.2 a tier is a ToolMaterial record, not an interface.public final class RubySwordItemToolMaterial { private RubySwordItemToolMaterial() { }
// Arguments: blocks it cannot mine for drops (a tag), durability, mining speed, attack bonus, enchantability, tag of repair items. public static final ToolMaterial INSTANCE = new ToolMaterial(BlockTags.INCORRECT_FOR_IRON_TOOL, 800, 7.0F, 2.5F, 15, ItemTags.IRON_TOOL_MATERIALS);}In src/main/resources/data/minecraft/tags/item/swords.json, add this to the list at /values:
"examplemod:ruby_sword"It’s registered like any other item, as RubySwordItem: see a new item.
Forge 1.16.5
Section titled “Forge 1.16.5”Uses:
IItemTierIItemTier.getUsesIItemTier.getSpeedIItemTier.getLevel
The tier is your own IItemTier: getLevel() is the mining level (2 is iron), there is no tier sorting registry in 1.16.5. The minecraft:swords and minecraft:pickaxes item tags do not exist in 1.16.5: the item class (SwordItem, PickaxeItem) decides what it can do.
src/main/java/com/example/examplemod/item/RubySwordItem.java
package com.example.examplemod.item;
import net.minecraft.item.Item;import net.minecraft.item.SwordItem;
// Ruby Sword: a sword of its own tier, RubySwordItemTier.public class RubySwordItem extends SwordItem { public RubySwordItem(Item.Properties properties) { super(RubySwordItemTier.INSTANCE, 3, -2.4F, properties); }}src/main/java/com/example/examplemod/item/RubySwordItemTier.java
package com.example.examplemod.item;
import net.minecraft.item.Item;import net.minecraft.item.Items;import net.minecraft.item.IItemTier;import net.minecraft.item.crafting.Ingredient;
// The tier of Ruby Sword: 800 uses, mining speed 7.0F, attack bonus 2.5F. Tools of this tier mine like iron, by the level below.public enum RubySwordItemTier implements IItemTier { INSTANCE;
@Override public int getUses() { return 800; }
@Override public float getSpeed() { return 7.0F; }
@Override public float getAttackDamageBonus() { return 2.5F; }
// The mining level: 2 is iron, so blocks that need iron or less drop. (World 3 is diamond, 4 netherite.) @Override public int getLevel() { return 2; }
@Override public int getEnchantmentValue() { return 15; }
@Override public Ingredient getRepairIngredient() { return Ingredient.of(Items.IRON_INGOT); }}It’s registered like any other item, as RubySwordItem: see a new item.
Forge 1.12.2
Section titled “Forge 1.12.2”Uses:
ToolMaterialToolMaterial.getUsesToolMaterial.getSpeedToolMaterial.getLevel
In 1.12.2 a tier is the Item.ToolMaterial enum, which Forge’s EnumHelper.addToolMaterial extends with your values; the harvest level 2 is iron.
src/main/java/com/example/examplemod/item/RubySwordItem.java
package com.example.examplemod.item;
import net.minecraft.item.ItemSword;
// Ruby Sword: a sword of its own tier, RubySwordItemTier.public class RubySwordItem extends ItemSword { public RubySwordItem() { super(RubySwordItemTier.INSTANCE); }}src/main/java/com/example/examplemod/item/RubySwordItemTier.java
package com.example.examplemod.item;
import net.minecraft.init.Items;import net.minecraft.item.Item;import net.minecraft.item.ItemStack;import net.minecraftforge.common.util.EnumHelper;
// The tier of Ruby Sword: 800 uses, mining speed 7.0F, attack bonus 2.5F. Tools of this tier mine like iron, by the harvest level below.public final class RubySwordItemTier { // 1.12.2 tool materials are an enum; Forge's EnumHelper adds one. Arguments: name, harvest level (2 is iron, 3 diamond), uses, efficiency, attack damage, enchantability. public static final Item.ToolMaterial INSTANCE = EnumHelper.addToolMaterial("RubySwordItem", 2, 800, 7.0F, 2.5F, 15) .setRepairItem(new ItemStack(Items.IRON_INGOT));
private RubySwordItemTier() { }}It’s registered like any other item, as RubySwordItem: see a new item.
Sources
Section titled “Sources”- https://docs.fabricmc.net/1.21.1/develop/items/custom-tools
- https://docs.neoforged.net/docs/1.21.1/items/tools
- https://docs.fabricmc.net/develop/
Related how-tos
Section titled “Related how-tos”- An item that wears out
- Make a block need a certain tool
- A sword that sets targets on fire
- A new enchantment
- An enchantment that heals you (lifesteal)
In Linen
Section titled “In Linen”Linen’s How-tos library has this page too, with the example for your own mod’s loader and Minecraft version. Hover a name in your code and Linen points to the how-tos that explain it. Both are free. Download Linen.