Weapons and tools

In this guide you will make two things from rubies: a Ruby Sword that hits harder than iron, and a Ruby Pickaxe that mines stone and ores quickly. Along the way you will learn the components every weapon and tool uses: damage, durability, enchanting, repairing and digging.

This guide builds on Your first custom item. The icon, texture and name steps work the same, so we will focus on what is new.

The quick way: GodCraft

GodCraft has ready-made Sword and Tool objects. You pick numbers, it writes the components and the tags.

1. Open the Workshop and add a Sword or a Tool to your add-on.
2. Draw it in the pixel editor (diagonal, handle at the bottom left, like vanilla tools).
3. Set the damage, durability, repair items and enchantments.
4. Tap Export and try it on the nearest zombie.

Here is what that looks like by hand.

By hand: the sword

We use the namespace myname. Replace it with your own everywhere.

{
  "format_version": "1.26.30",
  "minecraft:item": {
    "description": {
      "identifier": "myname:ruby_sword",
      "menu_category": {
        "category": "equipment",
        "group": "minecraft:itemGroup.name.sword"
      }
    },
    "components": {
      "minecraft:icon": {
        "textures": {
          "default": "myname_ruby_sword"
        }
      },
      "minecraft:display_name": {
        "value": "item.myname:ruby_sword.name"
      },
      "minecraft:max_stack_size": 1,
      "minecraft:hand_equipped": true,
      "minecraft:damage": 7,
      "minecraft:durability": {
        "max_durability": 900
      },
      "minecraft:enchantable": {
        "slot": "sword",
        "value": 14
      },
      "minecraft:repairable": {
        "repair_items": [
          {
            "items": ["myname:ruby"],
            "repair_amount": "query.max_durability * 0.25"
          },
          {
            "items": ["myname:ruby_sword"],
            "repair_amount": "context.other->query.remaining_durability"
          }
        ]
      },
      "minecraft:tags": {
        "tags": ["minecraft:is_sword"]
      }
    }
  }
}

What each part does

1. menu_category puts the sword in the Equipment tab, inside the same folder as the vanilla swords.
2. minecraft:max_stack_size set to 1, because weapons do not stack.
3. minecraft:hand_equipped makes the player hold it like a tool, pointing forward, instead of like a flat item.
4. minecraft:damage is how much damage the item adds when you attack with it. Higher is stronger. Start around 7 for a diamond-like sword, then test it on a few mobs and adjust.
5. minecraft:durability is how much wear the item can take before it breaks. Iron tools have 250, diamond 1561. You can also add damage_chance with a min and max percentage, if you want it to only lose durability some of the time.
6. minecraft:enchantable decides which enchantments fit. slot is the kind of item (sword here) and value is how good the enchantments are on a table: gold is very high, stone is low, 14 is a solid middle.
7. minecraft:repairable lists what can repair it on an anvil. Each entry has the items and a repair_amount, which is a small Molang formula. The first entry gives back a quarter of the durability per ruby. The second one lets players combine two damaged swords.
8. minecraft:tags with minecraft:is_sword tells the game and other add-ons that this is a sword.

Texture and name

Save a 16x16 PNG at RP/textures/items/ruby_sword.png, then add it to your item_texture.json (inside texture_data) and the name to your lang file:

"myname_ruby_sword": {
  "textures": "textures/items/ruby_sword"
}

item.myname:ruby_sword.name=Ruby Sword
item.myname:ruby_pickaxe.name=Ruby Pickaxe

By hand: the pickaxe

A tool is a weapon with one more job: breaking blocks fast. That job belongs to minecraft:digger.

{
  "format_version": "1.26.30",
  "minecraft:item": {
    "description": {
      "identifier": "myname:ruby_pickaxe",
      "menu_category": {
        "category": "equipment",
        "group": "minecraft:itemGroup.name.pickaxe"
      }
    },
    "components": {
      "minecraft:icon": {
        "textures": {
          "default": "myname_ruby_pickaxe"
        }
      },
      "minecraft:display_name": {
        "value": "item.myname:ruby_pickaxe.name"
      },
      "minecraft:max_stack_size": 1,
      "minecraft:hand_equipped": true,
      "minecraft:damage": 5,
      "minecraft:durability": {
        "max_durability": 900
      },
      "minecraft:enchantable": {
        "slot": "pickaxe",
        "value": 14
      },
      "minecraft:repairable": {
        "repair_items": [
          {
            "items": ["myname:ruby"],
            "repair_amount": "query.max_durability * 0.25"
          }
        ]
      },
      "minecraft:digger": {
        "use_efficiency": true,
        "destroy_speeds": [
          {
            "block": {
              "tags": "query.any_tag('stone', 'metal')"
            },
            "speed": 7
          },
          {
            "block": "minecraft:obsidian",
            "speed": 7
          }
        ]
      },
      "minecraft:tags": {
        "tags": ["minecraft:is_pickaxe", "minecraft:is_tool", "minecraft:diamond_tier"]
      }
    }
  }
}

How digging works

• destroy_speeds is a list. Each entry says which blocks and how fast.
• block can be one block ID, like "minecraft:obsidian", or an object with tags and a Molang query. query.any_tag('stone', 'metal') matches every block that has at least one of those tags, so you do not have to list hundreds of blocks.
• speed is how fast it breaks those blocks. For a feel: wood tools are 2, stone 4, iron 6, diamond 8, netherite 9 and gold 12.
• use_efficiency set to true lets the Efficiency enchantment make it even faster.

Tags for tools

The tags tell Minecraft what kind of tool this is. minecraft:is_pickaxe and minecraft:is_tool say "this is a pickaxe". A tier tag like minecraft:iron_tier or minecraft:diamond_tier says how strong it is, the same tags vanilla tools use. Other kinds of tool use minecraft:is_axe, minecraft:is_shovel or minecraft:is_hoe.

Test it

1. Load your packs into a new world (see Export and install).
2. Give yourself both items with /give:

/give @s myname:ruby_sword
/give @s myname:ruby_pickaxe

3. Hit a mob, mine some stone, and try enchanting both on a table.
4. Damage them a little, then put one on an anvil with a ruby to test repairing.

Enchantment slots you can use

When something goes wrong

More fixes are in Troubleshooting. To let players craft these, read Crafting and furnace recipes, and for the matching armor, see Custom armor.