Super Pickaxe! Add Custom Tools to Minecraft with Fabric

1

📖

How Tool Materials Work

Understand the five stats that define every Minecraft tool tier

Active

🎯

Goal for this step

Understand the five numbers that control how a Minecraft tool tier behaves.

📖

The 5 tool material stats:
• Durability how many uses before it breaks (wood=59, stone=131, iron=250, diamond=1561)
• Mining Speed how fast it mines compatible blocks (wood=2, stone=4, iron=6, diamond=8)
• Attack Damage Bonus extra damage added (pickaxe=1, sword=3, axe=5 approx)
• Enchantability how good enchanting results are (higher = better; gold=22, iron=14, diamond=10)
• Repair Ingredient what item fixes it in an anvil

💡

Our Crystal material will be between diamond and netherite: high durability, very fast mining, good enchantability. Feel free to change these numbers to whatever feels right!

I understand the 5 tool material stats

2

💻

Create ModToolMaterials.java

Define the Crystal tool material with all five stats

Locked

🎯

Goal for this step

Create the Crystal ToolMaterial enum that all Crystal tools will share.

1Right-click the crystalmod package → New → Java Class. Name it ModToolMaterials. When prompted for type, choose Enum.
2Replace the entire file with:

ModToolMaterials.java

package com.example.crystalmod;

import net.minecraft.item.ToolMaterial;
import net.minecraft.recipe.Ingredient;
import net.minecraft.registry.tag.BlockTags;

public enum ModToolMaterials implements ToolMaterial {

    CRYSTAL(
        BlockTags.INCORRECT_FOR_DIAMOND_TOOL,  // mines same blocks as diamond
        2000,    // durability
        9.0f,    // mining speed
        3.5f,    // attack damage bonus
        18,      // enchantability (higher = better enchants)
        () -> Ingredient.ofItems(ModItems.CRYSTAL_GEM)  // repair ingredient
    );

    private final net.minecraft.registry.tag.TagKey<net.minecraft.block.Block> incorrectBlocksTag;
    private final int itemDurability;
    private final float miningSpeed;
    private final float attackDamage;
    private final int enchantability;
    private final java.util.function.Supplier<Ingredient> repairIngredient;

    ModToolMaterials(net.minecraft.registry.tag.TagKey<net.minecraft.block.Block> tag,
                     int dur, float speed, float dmg, int ench,
                     java.util.function.Supplier<Ingredient> repair) {
        this.incorrectBlocksTag = tag;
        this.itemDurability = dur;
        this.miningSpeed = speed;
        this.attackDamage = dmg;
        this.enchantability = ench;
        this.repairIngredient = repair;
    }

    @Override public int getDurability() { return itemDurability; }
    @Override public float getMiningSpeedMultiplier() { return miningSpeed; }
    @Override public float getAttackDamage() { return attackDamage; }
    @Override public int getEnchantability() { return enchantability; }
    @Override public Ingredient getRepairIngredient() { return repairIngredient.get(); }
    @Override public net.minecraft.registry.tag.TagKey<net.minecraft.block.Block> getInverseTag() { return incorrectBlocksTag; }
}

📖

INCORRECT_FOR_DIAMOND_TOOL means blocks that don't drop when mined with diamond won't drop with crystal either. You can change this to INCORRECT_FOR_IRON_TOOL for a weaker pick or INCORRECT_FOR_NETHERITE_TOOL for the strongest.

ModToolMaterials.java created with CRYSTAL enum value

No red errors after auto-importing

3

⛏️

Register the Crystal Pickaxe

Add a PickaxeItem to ModItems.java using the Crystal material

Locked

🎯

Goal for this step

Add the Crystal Pickaxe to ModItems.java using PickaxeItem and your Crystal tool material.

1Open ModItems.java. Add these imports:

New imports for ModItems.java

import net.minecraft.item.PickaxeItem;
import net.minecraft.item.SwordItem;

2Add the Crystal Pickaxe field below your other items:

ModItems.java add Crystal Pickaxe

public static final Item CRYSTAL_PICKAXE = registerItem(
    "crystal_pickaxe",
    new PickaxeItem(
        ModToolMaterials.CRYSTAL,
        new Item.Settings().attributeModifiers(
            PickaxeItem.createAttributeModifiers(
                ModToolMaterials.CRYSTAL,
                1,      // attack damage bonus on top of material
                -2.8f   // attack speed modifier (negative = slower swing)
            )
        )
    )
);

3Add entries.add(CRYSTAL_PICKAXE); inside registerModItems().

CRYSTAL_PICKAXE field added to ModItems.java

Added to registerModItems()

🎓 Teacher Note — Step 3The createAttributeModifiers parameters confuse students because attackSpeed is negative. Explain that Minecraft uses offsets from default values: a -2.8f attack speed means 2.8 slower than baseline. This is intentional pickaxes swing slower than swords by design.

🚨 Stuck? Pickaxe won't compile or has wrong stats

Cannot find symbol: PickaxeItem press Alt+Enter on the red word → Import → net.minecraft.item.PickaxeItem.
createAttributeModifiers not found make sure you're using Fabric for Minecraft 1.21.1. Older tutorials use a different API.
Cannot find symbol: ModToolMaterials check ModToolMaterials.java is in the same package and the file has no compile errors of its own first.
Tool deals wrong damage in-game the attackDamage in createAttributeModifiers is a bonus on top of the tool's base. A pickaxe with +1 deals 1 + 4 (base) = 5 total.

4

⚔️

Register the Crystal Sword

Add a SwordItem using the same Crystal material

Locked

🎯

Goal for this step

Add the Crystal Sword it deals more damage than a diamond sword!

1In ModItems.java, add the Crystal Sword below the pickaxe:

ModItems.java — add Crystal Sword

public static final Item CRYSTAL_SWORD = registerItem(
    "crystal_sword",
    new SwordItem(
        ModToolMaterials.CRYSTAL,
        new Item.Settings().attributeModifiers(
            SwordItem.createAttributeModifiers(
                ModToolMaterials.CRYSTAL,
                3,      // attack damage bonus
                -2.4f   // attack speed (swords are -2.4f in vanilla)
            )
        )
    )
);

2Add entries.add(CRYSTAL_SWORD); inside registerModItems().

📖

Total sword damage = base player attack (1) + material attack damage (3.5) + bonus (3) = 7.5 damage. A diamond sword deals 7 damage. So your Crystal Sword is slightly better!

CRYSTAL_SWORD added to ModItems.java

Added to registerModItems()

5

🎨

Create Textures & Models for Both Tools

Draw pickaxe and sword sprites and create their model JSON files

Locked

🎯

Goal for this step

Create textures and model JSON for the Crystal Pickaxe and Crystal Sword.

Textures

1Use Pixel Studio to draw a 16×16 pickaxe sprite. The classic pickaxe shape has a diagonal handle and a T-shaped head. Use cyan/blue crystal colours for the head and brown for the stick.
2Save as crystal_pickaxe.png in assets/crystalmod/textures/item/.
3Draw a sword sprite a diagonal blade pointing top-right with a crossguard. Use crystal blue/cyan for the blade.
4Save as crystal_sword.png in the same folder.

Model JSON files

5Create crystal_pickaxe.json in assets/crystalmod/models/item/:

models/item/crystal_pickaxe.json

{
  "parent": "item/handheld",
  "textures": {
    "layer0": "crystalmod:item/crystal_pickaxe"
  }
}

6Create the same for crystal_sword.json (change texture path to crystal_sword).
7Add both names to en_us.json:
"item.crystalmod.crystal_pickaxe": "Crystal Pickaxe"
"item.crystalmod.crystal_sword": "Crystal Sword"

💡

Tools use "parent": "item/handheld" instead of "item/generated". This makes the item hold at the right angle in your hand!

crystal_pickaxe.png and crystal_sword.png textures created

Both model JSON files created with "item/handheld" parent

en_us.json updated with both names

6

🔨

Add Crafting Recipes for Both Tools

Standard shaped pickaxe and sword recipes using Crystal Gem

Locked

🎯

Goal for this step

Add classic-shaped crafting recipes for both tools same pattern as vanilla, just with Crystal Gem.

1Create crystal_pickaxe.json in data/crystalmod/recipe/:

data/crystalmod/recipe/crystal_pickaxe.json

{
  "type": "minecraft:crafting_shaped",
  "pattern": ["GGG", " S ", " S "],
  "key": {
    "G": { "item": "crystalmod:crystal_gem" },
    "S": { "item": "minecraft:stick" }
  },
  "result": { "id": "crystalmod:crystal_pickaxe", "count": 1 }
}

2Create crystal_sword.json in the same folder:

data/crystalmod/recipe/crystal_sword.json

{
  "type": "minecraft:crafting_shaped",
  "pattern": [" G ", " G ", " S "],
  "key": {
    "G": { "item": "crystalmod:crystal_gem" },
    "S": { "item": "minecraft:stick" }
  },
  "result": { "id": "crystalmod:crystal_sword", "count": 1 }
}

crystal_pickaxe.json recipe created

crystal_sword.json recipe created

7

🏃

Run Minecraft & Test Your Tools!

Mine some obsidian with the pickaxe and fight some zombies with the sword

Locked

🎯

Goal for this step

Launch Minecraft and verify the pickaxe mines fast, the sword deals good damage, and both can be enchanted and repaired.

1Launch Minecraft Client. Create a creative world.
2Search for Crystal Pickaxe and Crystal Sword in the creative inventory.
3Switch to survival (/gamemode survival). Give yourself the pickaxe: /give @p crystalmod:crystal_pickaxe.
4Mine some stone it should be noticeably faster than diamond!
5Hover over the pickaxe in your inventory check the Attack Speed and Attack Damage stats shown in the tooltip.
6Try the crafting recipe in a crafting table with Crystal Gems and sticks.
7Test anvil repair: put the pickaxe in an anvil with a Crystal Gem durability should restore!

🎉

Try enchanting the pickaxe in an enchanting table the high enchantability (18) should give great enchantments!

Crystal Pickaxe appears in creative inventory with correct tooltip stats

Crystal Sword appears with correct damage

Both crafting recipes work

Anvil repair with Crystal Gem works

8

🪓

Challenge: Add a Crystal Axe

Use the same pattern to add an axe useful for both wood and combat

Locked

🎯

Goal for this step

Add a Crystal Axe using AxeItem following the exact same pattern as the pickaxe.

1In ModItems.java, add: import net.minecraft.item.AxeItem;
2Add the Crystal Axe field using AxeItem (same structure as pickaxe, change attack damage to 5 and speed to -3.0f).
3Draw a 16×16 axe texture and create the model JSON.
4Add to en_us.json.
5Create a crafting recipe (axe pattern: two gems in top-left column, stick below).
6Test in-game!

💡

You can also add ShovelItem and HoeItem using exactly the same approach. All tool classes in Fabric follow this same constructor pattern.

Crystal Axe registered and working in-game

9

🛡️

Bonus: Add a Mining Tag for Crystal Blocks

Make the Crystal Pickaxe the best tool for mining Crystal Blocks

Locked

🎯

Goal for this step

Create a block tag that makes Crystal Block mine faster with the Crystal Pickaxe.

📖

In Minecraft, tools mine blocks faster when those blocks are in the tool's "mineable" tag. We can make the Crystal Pickaxe mine Crystal Blocks at full speed by adding a tag.

1In data/minecraft/tags/block/, create the file mineable/pickaxe.json:

data/minecraft/tags/block/mineable/pickaxe.json

{
  "replace": false,
  "values": [
    "crystalmod:crystal_block"
  ]
}

📖

"replace": false means we're adding to the existing tag, not replacing it. This is crucial — you never want to accidentally remove vanilla blocks from their mining tags!

pickaxe.json tag file created

Crystal Block mines faster with Crystal Pickaxe in-game

🎓 Teacher Note Step 9This is the "silent fail" step without the tag, the block still breaks but very slowly, and students think the tool is broken. The folder path uses minecraft not crystalmod that surprises students. Explain: we're extending Minecraft's own tag, not creating a new one.

🚨 Stuck? Pickaxe is no faster than fists

Correct path is critical the file must be at data/minecraft/tags/block/mineable/pickaxe.json. It's minecraft, not crystalmod! You're extending Minecraft's own tag list.
"replace" must always be false setting it to true would remove ALL vanilla blocks from pickaxe mining. Always use false.
Folders don't exist yet you may need to create data/minecraft/tags/block/mineable/ one folder at a time. Right-click → New Directory in IntelliJ.
Still slow after adding the tag hot-reload may not pick up tag changes. Fully stop and restart the game from the Gradle panel.

10

🌟

Review & What's Next

You now have a full custom tool set Episode 5 adds a living mob!

Locked

🎯

Goal for this step

Review your Crystal tool set and prepare for the most exciting episode yet custom mobs!

What you built

✓A custom ToolMaterial enum with 5 stats
✓Crystal Pickaxe faster than diamond, enchants well
✓Crystal Sword strong attack damage
✓Block tag so the pickaxe mines Crystal Blocks efficiently
✓Anvil repair using Crystal Gem

🐸

Episode 5 Crystal Frog: Create a custom mob from scratch! You'll write an entity class, set AI goals (wandering, following players), create a spawn egg and add mob drops. It's the most advanced episode so far and the most impressive!

Crystal Pickaxe and Sword both work in-game

I'm ready for the mob episode!

Super Pickaxe!Custom Tool Set

Textures

Model JSON files

What you built

Super Pickaxe!
Custom Tool Set