Allowing Custom Entities to Hold Items

In Minecraft Bedrock, an entity holding an item is split into two completely separate systems: the server-side inventory state and the client-side visual rendering. On the server (behavior pack), the entity stores what item is currently in its mainhand or offhand slot, along with any weapon stats or durability. On the client (resource pack), the game engine checks if that entity is allowed to render held items and looks for a specific bone in the geometry to attach the item model to.

Because these systems are decoupled, a bug in your resource pack will result in a mob that hits with the strength of a diamond sword while appearing completely empty-handed. Conversely, if the geometry bone is misaligned, the item may render floating several blocks away from the mob's body. Setting this up properly requires touching three files: the geometry JSON, the client entity JSON, and the server entity JSON.

The Bedrock item renderer does not guess where your entity's hands are. Instead, it searches the entity's geometry for a bone named `rightItem` (case-sensitive) to attach mainhand items, and `leftItem` for offhand items. This bone does not need any cubes of its own; it acts purely as a pivot and attachment point.

When modeling in Blockbench, create an empty bone named `rightItem` as a child of your entity's right arm bone. Position the pivot point of `rightItem` right where the palm or grip of the hand is located. For standard humanoid proportions matching the vanilla player or zombie, placing the pivot near the bottom tip of the right arm ensures that swords and tools rotate naturally from the wrist when the arm swings.

{
  "format_version": "1.12.0",
  "minecraft:geometry": [
    {
      "description": {
        "identifier": "geometry.custom_guard",
        "texture_width": 64,
        "texture_height": 64,
        "visible_bounds_width": 2,
        "visible_bounds_height": 3,
        "visible_bounds_offset": [0, 1.5, 0]
      },
      "bones": [
        {
          "name": "root",
          "pivot": [0, 0, 0]
        },
        {
          "name": "body",
          "parent": "root",
          "pivot": [0, 24, 0],
          "cubes": [
            {"origin": [-4, 12, -2], "size": [8, 12, 4], "uv": [16, 16]}
          ]
        },
        {
          "name": "rightArm",
          "parent": "body",
          "pivot": [-5, 22, 0],
          "cubes": [
            {"origin": [-8, 12, -2], "size": [4, 12, 4], "uv": [40, 16]}
          ]
        },
        {
          "name": "rightItem",
          "parent": "rightArm",
          "pivot": [-6, 15, 1]
        }
      ]
    }
  ]
}

Even with the `rightItem` bone present in your geometry, the engine will not render anything in the mob's hand until you enable the `enable_attachables` flag in the client entity definition (`RP/entity/`). Despite the name suggesting it only applies to attachable armor and custom 3D items, `enable_attachables` is the master switch that allows an entity to render standard held items, weapons, and armor pieces.

If your entity holds custom 3D items that rely on vanilla hold animations (such as bows, crossbows, or tridents), your client entity must also declare the animation keys that those attachables expect, such as `c.is_first_person` or specific hold poses. For standard melee weapons and blocks, simply enabling attachables is sufficient.

{
  "format_version": "1.10.0",
  "minecraft:client_entity": {
    "description": {
      "identifier": "wiki:custom_guard",
      "materials": {
        "default": "entity_alphatest"
      },
      "textures": {
        "default": "textures/entity/custom_guard"
      },
      "geometry": {
        "default": "geometry.custom_guard"
      },
      "render_controllers": [
        "controller.render.default"
      ],
      "enable_attachables": true
    }
  }
}

With the visuals ready, you must give the entity an item on the server side. There are three primary ways a custom entity acquires a held item: spawning with gear via a loot table, picking up dropped items from the ground, or receiving an item directly via the `/replaceitem` command.

To spawn the entity with a weapon already in its hand, add the `minecraft:equipment` component pointing to a loot table. When the loot table rolls a weapon or tool, the entity automatically equips it into its mainhand slot. If you want the mob to pick up better weapons it finds on the ground during gameplay, combine `minecraft:equip_item` with `minecraft:shareables` and `minecraft:behavior.pickup_items`.

{
  "format_version": "1.16.0",
  "minecraft:entity": {
    "description": {
      "identifier": "wiki:custom_guard",
      "is_spawnable": true,
      "is_summonable": true
    },
    "components": {
      "minecraft:physics": {},
      "minecraft:health": {
        "value": 20,
        "max": 20
      },
      "minecraft:equipment": {
        "table": "loot_tables/entities/guard_gear.json"
      },
      "minecraft:equip_item": {},
      "minecraft:shareables": {
        "items": [
          {
            "item": "minecraft:iron_sword",
            "priority": 0,
            "max_amount": 1
          }
        ]
      },
      "minecraft:behavior.pickup_items": {
        "priority": 2,
        "max_dist": 3.0,
        "speed_multiplier": 1.0
      }
    }
  }
}

During development, you do not need to write loot tables just to verify your `rightItem` bone positioning. Summon your custom entity in-game and run `/replaceitem entity @e[type=wiki:custom_guard,c=1] slot.weapon.mainhand 0 iron_sword`. The sword should immediately appear in the entity's hand.

If you want your entity to change its posture when holding an item—such as raising its arm like a vindicator or aiming with two hands—you can check whether the hand is occupied using Molang inside an animation controller or render controller. Use the query `q.is_item_equipped(0)` (or `query.is_item_equipped('main_hand')`) to return `1.0` when an item is in the mainhand, and `0.0` when the hand is empty.

Applies to Minecraft Bedrock 1.10.0 and above. The `enable_attachables` client entity property works in format_version 1.10.0+. No experimental toggles are required.

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