Creating Custom Weapons

Every melee weapon relies on a small cluster of item components to function like a vanilla sword or axe. Unlike stackable resources, weapons must have their stack size locked to one so the game can track wear and tear on the individual item instance. They also need to be flagged as hand-equipped so the third-person model renders upright like a tool rather than flat like an apple.

The table below outlines the stable components used to construct a melee weapon in format versions 1.20.50 and newer.

To create a working custom sword, place an item definition file inside your behavior pack's items directory. This file sets the item's identifier, places it into the Equipment tab of the Creative inventory, and combines the combat components discussed above.

Notice how the repairable component uses a Molang expression referencing query.max_durability. Calculating the repair amount as 25 percent of the maximum durability mimics how vanilla ingots repair tools on an anvil.

{
  "format_version": "1.20.80",
  "minecraft:item": {
    "description": {
      "identifier": "my_pack:ruby_sword",
      "menu_category": {
        "category": "equipment",
        "group": "itemGroup.name.sword"
      }
    },
    "components": {
      "minecraft:max_stack_size": 1,
      "minecraft:hand_equipped": true,
      "minecraft:can_destroy_in_creative": false,
      "minecraft:damage": {
        "value": 8
      },
      "minecraft:durability": {
        "max_durability": 950
      },
      "minecraft:enchantable": {
        "slot": "sword",
        "value": 14
      },
      "minecraft:repairable": {
        "repair_items": [
          {
            "items": [
              "minecraft:diamond"
            ],
            "repair_amount": "query.max_durability * 0.25"
          }
        ]
      },
      "minecraft:icon": "ruby_sword"
    }
  }
}

In older Holiday Creator Features items, creators had to manually wire up event responses to decrement durability when hitting mobs or breaking blocks. Under the current stable item system, the game automatically reduces durability by 1 when an item with both minecraft:durability and minecraft:damage hits an entity.

However, if a player uses your custom sword to break dirt or leaves, the durability will not automatically drop unless the item also defines block-breaking rules. Adding the minecraft:digger component lets your weapon slice through cobwebs and bamboo quickly, just like a vanilla sword, and ensures the weapon takes durability damage when used to break those blocks.

{
  "minecraft:digger": {
    "use_efficiency": false,
    "destroy_speeds": [
      {
        "block": "minecraft:web",
        "speed": 15
      },
      {
        "block": "minecraft:bamboo",
        "speed": 10
      }
    ]
  }
}

Because legacy JSON item events have been removed from modern format versions, special combat mechanics—such as applying poison on hit, lifesteal, or knockback bursts—are built using the Script API. You have two ways to wire this up: listening to the global entityHurt after-event, or registering a custom item component with an onHitEntity callback.

Using minecraft:custom_components is the cleanest approach for packs with multiple weapons. You list your custom component identifier inside the item's JSON components block, then register its behavior during the worldInitialize event in your script file. The script below inflicts the Wither effect for 5 seconds (100 ticks) whenever the weapon strikes a target.

import { world } from "@minecraft/server";

world.beforeEvents.worldInitialize.subscribe((eventData) => {
  eventData.itemComponentRegistry.registerCustomComponent("my_pack:wither_blade_hit", {
    onHitEntity(event) {
      const target = event.hitEntity;
      if (target) {
        target.addEffect("wither", 100, {
          amplifier: 1,
          showParticles: true
        });
      }
    }
  });
});

If you only assign a 2D texture via the minecraft:icon component, Bedrock automatically extrudes the pixel art into a thin 3D item model. As long as minecraft:hand_equipped is set to true in your behavior pack, the game rotates and scales this generated model so the player holds it by the hilt in both first-person and third-person views.

When you want a true 3D custom Blockbench model for a broadsword or hammer, you add the minecraft:wearable or attachable setup in your resource pack, or use the item's geometry component if making a simpler block-style mesh. For high-detail 3D weapons that animate with the player's arm, creating a resource pack attachable matched to your item's identifier gives you complete control over first-person and third-person bone animations.

Applies to Bedrock Edition 1.20.50 and newer (with custom components requiring 1.21.10+ for stable use). No experimental toggles are needed if you use the stable @minecraft/server module.

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