Custom Item Tool Durability in Minecraft Bedrock

All item wear in a behavior pack begins with the "minecraft:durability" component. Adding this component to your item definition gives the item a hidden damage counter starting at zero and increasing each time the item takes wear. Once the accumulated damage equals the maximum durability value you set, the item breaks, plays the standard breaking sound, and is removed from the player's inventory.

Because a damaged item carries unique instance data in its durability counter, any item with "minecraft:durability" must be unstackable. You always pair it with "minecraft:max_stack_size" set to 1. The component itself accepts two properties: the total health pool of the item, and a probability range that controls how often an action actually registers as wear.

{
  "format_version": "1.20.80",
  "minecraft:item": {
    "description": {
      "identifier": "my_pack:copper_pickaxe",
      "menu_category": {
        "category": "equipment",
        "group": "itemGroup.name.pickaxe"
      }
    },
    "components": {
      "minecraft:max_stack_size": 1,
      "minecraft:hand_equipped": true,
      "minecraft:durability": {
        "max_durability": 190,
        "damage_chance": {
          "min": 100,
          "max": 100
        }
      },
      "minecraft:icon": "copper_pickaxe"
    }
  }
}

The "damage_chance" object inside "minecraft:durability" determines how frequently the item loses health when triggered. When both "min" and "max" are set to 100, every single wear event reduces the remaining durability by the full amount. If you set "min" to 25 and "max" to 75, the engine rolls a random number within that range on each use to decide whether the item takes damage.

To let your custom tool benefit from the vanilla Unbreaking enchantment at an enchanting table or anvil, you must also give the item the "minecraft:enchantable" component. When an item is enchanted with Unbreaking, the game automatically scales down the effective damage chance ontop of whatever base range you defined in "damage_chance". For a standard tool that wears down predictably until enchanted, leave "damage_chance" at its default 100 to 100 range and let the enchantment slot handle durability conservation.

{
  "format_version": "1.20.80",
  "minecraft:item": {
    "description": {
      "identifier": "my_pack:copper_pickaxe"
    },
    "components": {
      "minecraft:max_stack_size": 1,
      "minecraft:durability": {
        "max_durability": 190
      },
      "minecraft:enchantable": {
        "slot": "pickaxe",
        "value": 14
      }
    }
  }
}

Giving an item "minecraft:durability" allows two damaged copies of that same item to be combined in a crafting grid or grindstone automatically. However, if you want players to repair the tool on an anvil using raw materials like ingots or planks, you need to add the "minecraft:repairable" component alongside it.

Inside "minecraft:repairable", the "repair_items" array lists which items can restore durability and how much each unit restores. The "repair_amount" field accepts either a flat integer or a Molang expression. In most cases, you can use the Molang query "q.max_durability" multiplied by 0.25 so that four raw materials fully restore the tool, matching the behavior of vanilla tools on an anvil.

{
  "format_version": "1.20.80",
  "minecraft:item": {
    "description": {
      "identifier": "my_pack:copper_pickaxe"
    },
    "components": {
      "minecraft:max_stack_size": 1,
      "minecraft:durability": {
        "max_durability": 190
      },
      "minecraft:repairable": {
        "repair_items": [
          {
            "items": [
              "minecraft:copper_ingot"
            ],
            "repair_amount": "q.max_durability * 0.25"
          },
          {
            "items": [
              "my_pack:copper_pickaxe"
            ],
            "repair_amount": "context.other->q.remaining_durability + 0.12 * context.other->q.max_durability"
          }
        ]
      }
    }
  }
}

A common point of confusion in modern Bedrock item formats (1.20.10 and newer) is that "minecraft:durability" only gives the item a health pool; it does not automatically deduct durability when you break a block or hit a mob. Legacy Holiday Creator Features event responses like "damage" are removed in current format versions. To actually wear the tool down during normal use, you pair your JSON item with the "@minecraft/server" Script API.

In your script, you read the "minecraft:durability" component from the "ItemStack" currently held in the player's mainhand. You then increment its "damage" property and write the updated item back into the player's equipment slot. Before adding damage, check whether the new damage total will reach or exceed "maxDurability" so you can clear the item slot and play the break sound when the tool runs out of health.

import { world, EquipmentSlot, GameMode } from "@minecraft/server";

world.afterEvents.playerBreakBlock.subscribe((event) => {
  const player = event.player;
  if (player.getGameMode() === GameMode.creative) return;

  const equippable = player.getComponent("minecraft:equippable");
  if (!equippable) return;

  const item = equippable.getEquipment(EquipmentSlot.Mainhand);
  if (!item || item.typeId !== "my_pack:copper_pickaxe") return;

  const durability = item.getComponent("minecraft:durability");
  if (!durability) return;

  const unbreakingLevel = item.getComponent("minecraft:enchantable")?.getEnchantment("unbreaking")?.level ?? 0;
  const damageChance = durability.getDamageChance(unbreakingLevel) / 100;

  if (Math.random() <= damageChance) {
    if (durability.damage + 1 >= durability.maxDurability) {
      equippable.setEquipment(EquipmentSlot.Mainhand, undefined);
      player.playSound("random.break");
    } else {
      durability.damage += 1;
      equippable.setEquipment(EquipmentSlot.Mainhand, item);
    }
  }
});

Applies to Bedrock Edition 1.20.10 and newer (shown using format_version 1.20.80). Both "minecraft:durability" and "minecraft:repairable" are stable and require no experimental toggles. Deducting durability via script requires a script module dependency on "@minecraft/server" (version 1.11.0 or newer).

Read out of the game itself, so the ids match the version you are building for.