Custom Items: Attachables and 3D Rendering

By default, custom items in Minecraft Bedrock render as extruded 2D sprites generated from their item texture, while custom armor items do not show anything on the player body unless configured. An attachable overrides this default rendering by wrapping a 3D model, texture, material, and animation set into a mini client-entity definition that attaches to the holder's skeleton.

Attachable JSON files live in the resource pack under the RP/attachables/ folder. The game links an attachable to a behavior pack item strictly by matching the identifier string inside the description block. When a player or mob holds or equips the item with that identifier, the client looks up the attachable and runs its render controllers.

Because attachables only control how an item looks when equipped on an entity, they do not change the 2D icon shown in the inventory slot, hotbar, or item frame. You still define the 2D inventory icon using the standard minecraft:icon component in your behavior pack item file.

The structure of an attachable file closely mirrors a client entity file. Inside the description object, you declare the item identifier, map short names to actual resource identifiers for textures, geometry, and materials, and list the render controllers that put them together.

For armor or worn items, the bones in your custom geometry must share the exact names of the humanoid bones they are meant to follow (such as head, body, leftArm, rightArm, leftLeg, and rightLeg) and share the same pivot points. During rendering, the game automatically snaps bones with matching names in your attachable geometry to the pose of the parent entity's skeleton.

{
  "format_version": "1.10.0",
  "minecraft:attachable": {
    "description": {
      "identifier": "wiki:ruby_chestplate",
      "materials": {
        "default": "armor",
        "enchanted": "armor_enchanted"
      },
      "textures": {
        "default": "textures/models/armor/ruby_layer_1",
        "enchanted": "textures/misc/enchanted_item_glint"
      },
      "geometry": {
        "default": "geometry.humanoid.armor.chestplate"
      },
      "scripts": {
        "parent_setup": "variable.chest_layer_visible = 0.0;"
      },
      "render_controllers": [
        "controller.render.armor"
      ]
    }
  }
}

Every attachable uses the description object to register its assets and execute Molang logic. Most keys map a local short name (like default or enchanted) to a global resource identifier defined elsewhere in your resource pack.

Unlike armor, which drapes over multiple body bones, a held 3D item is usually bound to a single bone named rightItem or leftItem inside its geometry file. Because the camera angle and arm posture differ drastically between first-person view and third-person view, a single static model will rarely look right in both views out of the box.

To solve this, creators pair a held attachable with two positioning animations: one that rotates and translates the bone for first-person view, and another for third-person view. You trigger the right animation inside the scripts.animate array using the c.is_first_person Molang query.

In format version 1.10.0, each entry in the scripts.animate array can be an object where the key is the short name of the animation and the value is the Molang condition under which it runs.

{
  "format_version": "1.10.0",
  "minecraft:attachable": {
    "description": {
      "identifier": "wiki:heavy_hammer",
      "materials": {
        "default": "entity_alphatest",
        "enchanted": "entity_alphatest_glint"
      },
      "textures": {
        "default": "textures/items/heavy_hammer_3d",
        "enchanted": "textures/misc/enchanted_item_glint"
      },
      "geometry": {
        "default": "geometry.wiki_heavy_hammer"
      },
      "animations": {
        "wield_first_person": "animation.wiki_heavy_hammer.first_person",
        "wield_third_person": "animation.wiki_heavy_hammer.third_person"
      },
      "scripts": {
        "animate": [
          {
            "wield_first_person": "c.is_first_person"
          },
          {
            "wield_third_person": "!c.is_first_person"
          }
        ]
      },
      "render_controllers": [
        "controller.render.item_default"
      ]
    }
  }
}

When a player equips a helmet or chestplate, the player's second skin layer (hat, jacket, sleeves, or pants) can clip through tight-fitting custom armor models. Attachables provide a special script key called parent_setup that executes Molang in the context of the wearing entity before the entity renders.

By setting standard player visibility variables to 0.0 inside parent_setup, you can hide the outer skin layer of the body part covered by your item. For example, setting variable.helmet_layer_visible = 0.0; hides the player's hat layer while the helmet is worn, and variable.boot_layer_visible = 0.0; hides the lower pant cuffs.

You can also use scripts.pre_animation inside the attachable to compute custom Molang variables for the attachable itself, such as switching texture arrays or scaling bones based on entity queries like q.is_sneaking or q.main_hand_item_use_duration.

Attachables using format_version 1.10.0 are stable across modern Bedrock releases (1.16.100 and newer) and do not require any experimental toggles. Note that if an item uses the minecraft:wearable component in recent versions (1.20.80+) without a custom attachable, the game may attempt to render a default armor layer unless an attachable overrides it.

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