Skip to content

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.

  1. Write the tier with your numbers (an enum that implements Tier, or a ToolMaterial on 1.21.2 and newer).
  2. On 1.20.5 and newer, pick the incorrect-blocks tag: INCORRECT_FOR_IRON_TOOL, or your own tag.
  3. Pass the tier to a tool item (a tool class such as SwordItem, or the tool properties on 1.21.5 and newer).
  4. Check the durability and mining speed in the game.

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.

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:

  • Tier
  • Tier.getUses
  • Tier.getSpeed
  • Tier.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.

Uses:

  • Tier
  • Tier.getUses
  • Tier.getSpeed
  • Tier.getIncorrectBlocksForDrops
  • BlockTags.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.

Uses:

  • Tier
  • Tier.getUses
  • Tier.getSpeed
  • Tier.getIncorrectBlocksForDrops
  • BlockTags.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.

Uses:

  • ToolMaterial
  • ToolMaterial.durability
  • ToolMaterial.speed
  • ToolMaterial.incorrectBlocksForDrops
  • SwordItem
  • BlockTags.INCORRECT_FOR_IRON_TOOL
  • ItemTags.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.

Uses:

  • ToolMaterial
  • ToolMaterial.durability
  • ToolMaterial.speed
  • ToolMaterial.incorrectBlocksForDrops
  • Item.Properties.sword
  • BlockTags.INCORRECT_FOR_IRON_TOOL
  • ItemTags.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.

Uses:

  • IItemTier
  • IItemTier.getUses
  • IItemTier.getSpeed
  • IItemTier.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.

Uses:

  • ToolMaterial
  • ToolMaterial.getUses
  • ToolMaterial.getSpeed
  • ToolMaterial.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.

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.