Bedrock Wiki
  • Discord
  • Contribute
  • bedrock.dev
  • MS Learn
Beginner's Guide
  • Guide
    • 1. Introduction
      guide
    • 2. Add-Ons Explained
    • 3. Software & Preparation
    • 4. Project Setup
    • 5. Create a Custom Item
    • 6. Create a Custom Entity
    • 7. Blockbench: Modeling, Texturing & Animating
    • 8. Adding a Loot Table, Spawn Rule & Crafting Recipe
  • Extra
    • a. Understanding JSON
    • b. Download Example Packs
    • c. Troubleshooting
      help
    • d. Advanced Manifest
    • e. Format Versions
    • f. Project Setup Android
Animation Controllers
  • Intro to Animation Controllers
    guide
  • Entity Commands
  • AFK Detector
  • Death Commands
  • Molang into Scoreboard
  • Respawn Commands
Blocks
  • General
    • Intro to Blocks
      guide
    • Block Components
    • Block Tags
    • Block States
    • Block Traits
    • Block Permutations
    • Block Events
      Scripts
    • Block Event Migration
      help
    • Blocks as Items
    • Troubleshooting Blocks
      help
  • Visuals
    • Block Culling
    • Block Models
      guide
    • Block Texture Animation
    • Block Texture Variation
    • Block Tinting
  • Tutorials
    • Applying Constant Effects
      Scripts
    • Avoiding State Limit
    • Fake Blocks
    • Ore Loot Tables
      Scripts
    • Precise Interaction
      Scripts
    • Precise Rotation
      Scripts
    • Rotatable Blocks
  • Vanilla Re-Creations
    • Custom Crops
      Scripts
    • Custom Glass
    • Custom Glazed Terracotta
    • Custom Trapdoors
      Scripts
  • Documentation
    • Block Format History
    • Block Shapes
    • Block Sounds
    • Vanilla Block Models
Commands
  • General
    • Intro to Command Blocks
    • Functions
    • Block States
    • Coordinate System
    • NBT Commands
    • Scoreboard Operations
    • Understanding Selectors
  • Commands
    • Damage
    • Execute
    • Playanimation
    • Playsound
  • On Event Systems
    • On Player First Join
    • On Player Join
    • On Player Leave
    • On Player Death
    • On Player Respawn
    • On First World Load
  • Scoreboard Systems
    • Entity Counter
    • Scoreboard Timers
    • Comparing And Retrieving Scores
  • Techniques
    • Execute Logic Gates
    • MBE - Max's Block Entity
    • FMBE - A New Way to Create Display Entities
    • Look Detection
    • Movement Detections
    • Orbital Camera
  • Useful Creations
    • Custom Crafter
    • Multiplayer Position Rearrangement
      function
Concepts
  • contents.json
  • Emojis & Symbols
  • Molang
  • Namespaces
  • Overwriting Assets
  • Raw Text
  • Shaders
  • Sounds
  • Subpacks
  • Text and Localization
  • Texture Atlases
  • textures_list.json
Documentation
  • Shared Constructs
  • Advanced Molang
  • File Types
  • Fog IDs
  • Material Configuration Description
  • Menu Categories
  • Molang Queries
  • Pack Folder Structure
  • Sound Definitions
  • Vanilla Materials
Entities
  • General
    • Intro to Entities BP
      guide
    • Intro to Entities RP
      guide
    • Troubleshooting Entities
      help
    • Entity Events
    • Entity Properties
    • NPC Dialogues
    • Render Controllers
    • Spawn Rules
  • Tutorials
    • Convert Points Between Any Space (World, Entity, Bones)
    • Creating Boats
    • Detecting Other Entities
    • Disabling Team Damage
    • Dummy Entities
    • Entity Attacks
    • Entity Holds Item
    • Entity Movement
    • Entity Timers
    • Flying Entities
    • Introduction to AOE Clouds
    • Invulnerable Entities
    • Look at Entity
    • Sleeping Entities
    • Solid Entities
    • Spawning Tamed Entities
      Scripts
    • Village Mechanic
  • Documentation
    • Dummy Components
    • Non-Mob Runtime Identifiers
    • Projectiles
    • Runtime Identifiers
    • Vanilla Usage Components
    • Vanilla Usage Spawn Rules
Items
  • General
    • Intro to Items
      guide
    • Item Components
    • Item Tags
    • Item Events
      Scripts
    • Item Event Migration
      help
    • Troubleshooting Items
      help
  • Tutorials
    • Custom Armor
    • Custom Food
      Scripts
    • Custom Pottery Sherds
    • Custom Weapons
    • Equipment-Based Commands
    • High Resolution Items
    • Spawning Items
    • Throwable Items
  • Documentation
    • Enchantments
    • Attachables
    • Item Format History
    • Numerical Item IDs
    • Vanilla Item Identifiers
    • Vanilla Usage Components
JSON UI
  • General
    • Intro to JSON UI
      guide
    • Best Practices
      guide
  • Tutorials
    • Adding HUD Elements
    • Aseprite Animations
    • Buttons and Toggles
    • Modifying Server Forms
    • Preserve Title Texts
    • String to Number
  • Documentation
    • JSON UI Documentation
Loot, Recipes & Trading
  • General
    • Trading Behavior
  • Documentation
    • Loot Tables
    • Trade Tables
    • Recipes
    • Item Functions
  • Tutorials
    • Randomized Structure Loot
Meta
  • Add-On Performance
  • Style Guide
  • Useful Links
  • Using Schemas
  • Version Control
  • Q&A
    • Blocks and Items Q&A 2024/08/30
    • Deferred Technical Preview Q&A 2024/02/23
    • GameTest Q&A 2021/08/06
    • Scripting and Editor Q&A 2023/09/22
    • World Generation Q&A 2024/11/15
NBT
  • General
    • .mcstructure
  • Tutorials
    • Experiments in Education Edition
    • Extending Structure Limits
  • NBT in Depth
    • About NBT (Named Binary Tag)
    • NBT Libraries
    • Reading NBT Example
Particles
  • General
    • Intro to Particles
      guide
  • Tutorials
    • Disabling Particles
  • Documentation
    • Vanilla Particles
Scripting
  • General
    • Intro to Scripting
    • What is Script API?
    • API Modules
  • Tutorials
    • Block Placement Prevention
    • GameTests
    • Script Core Features
    • Script Forms
    • Script Requests API
    • Simple Chat Commands
  • Documentation
    • Engine Environment
    • Script Resources
    • Script Watchdog
    • Troubleshooting JavaScript
    • TypeScript
Servers
  • Software
    • Bedrock Server Software
  • Protocols
    • Bedrock Protocol
    • NetherNet Protocol
    • RakNet Protocol
Visuals
  • General
    • Introduction to Entity Visuals
      guide
    • Bedrock Modeling
    • Custom Death Animations
    • Effects in Animations
    • Material Creations
    • Materials
    • Math-Based Animations
    • Skin Packs
  • Tutorials
    • Entity Texture Animation
    • Glowing Entity Texture
    • Hurt Animations
    • Leash Position
    • Player Geometry
    • Remove Entity Shadows
    • Retexturing Spawn Eggs
  • Ideas
    • Structure Presentation
World Generation
  • General
    • Intro to World Generation
      guide
    • Biomes
      guide
    • Feature Types
  • Tutorials
    • Block Conditions for Features
    • Generating Custom Ores
    • Generating Custom Structures
    • Generating Patches
    • Heightmap Noise
  • Documentation
    • Biome Tags

Attachables

beginner
Attachables
  • Introduction
  • Overview
    • File Structure
    • Attachable Definition
  • Method 1 - Attached to the Skeleton
    • Setting up the Skeleton
    • Display Settings
    • First-person Animations
    • Conclusion
  • Method 2 - Bound to a Bone
    • Model Binding
    • Display Settings
    • First-person Animations
  • Example Pack

TIP

This document assumes you have a basic understanding of Molang, render controllers, animations, and client entity definitions. Ensure you are familiar with the basics of client entities!

Introduction ​

When we design a custom item or block, Minecraft will build a model from a template so the item can be displayed when held. This takes the form of the item's sprite being an extruded texture mesh, or blocks displaying with their model. By using a system called attachables we can design our own models to be displayed when these items are held.

Ever wanted sticks to look like spyglasses? Or to wield a big chainsaw with a spinning chain? Attachables are the way to accomplish that!

This document covers two different ways to create attachables, depending on how the geometry being used is constructed.

Overview ​

Attachables are a system of rendering entity models when an item or block is equipped. This means having the item held in the main hand, off hand, or armor slots.

Attachable definitions are quite similar in design to client entity definitions; they let us define textures, materials, geometries, and animations to display the attachable.

File Structure ​

The attachable definition goes within the 'attachables' folder. The file layout is otherwise identical to that of custom entities.

      • 📝my_item.animation.json
      • 📝my_item.entity.json
        • 📝my_item.geo.json
        • 🖼️my_item.png
    • 📝manifest.json

Attachable Definition ​

Here's a basic example of an attachable.

RP/attachables/stick.entity.json
json
{
    "format_version": "1.10.0",
    "minecraft:attachable": {
        "description": {
            "identifier": "minecraft:stick",
            "materials": {
                "default": "entity",
                "enchanted": "entity_alphatest_glint"
            },
            "textures": {
                "default": "textures/entity/steve",
                "enchanted": "textures/misc/enchanted_item_glint"
            },
            "geometry": {
                "default": "geometry.wiki.steve_head"
            },
            "animations": {
                "hold_first_person": "animation.steve_head.hold_first_person",
                "hold_third_person": "animation.steve_head.hold_third_person"
            },
            "scripts": {
                "animate": [
                    {
                        "hold_first_person": "context.is_first_person == 1.0"
                    },
                    {
                        "hold_third_person": "context.is_first_person == 0.0"
                    }
                ]
            },
            "render_controllers": ["controller.render.item_default"]
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

A few key things to point out with this attachable definition:

  • The identifier matches an existing block or item ID. This will activate the attachable when the item is equipped, and will replace the original model that appears when held.
  • There is a material and texture listed for the enchantment glint. This is important to keep around if your item should have the glint when enchanted.

Making attachables is a little more involved than making a client entity file. We need to properly rig the geometry's skeleton so that it looks correct when equipped.

Method 1 - Attached to the Skeleton ​

beginner

In this first method we will construct the attachable using a copy of the player's skeleton, by attaching your model to one of the player's bones.

This solution is ideal for models that are intended for scenarios involving only one type of mob/entity, especially players; and involving only one equipment slot. It is easy to view what the model will look like in Blockbench.

Setting up the Skeleton ​

We need to reconstruct the player's skeleton in order for our model to be parented to the correct bone, otherwise it will not be parented to anything and will float freely on the player.

With a text editor, take the bones from the provided player skeleton file and copy them to your geometry file, then set the rightItem bone as the parent to the cubes from your model. Save this geometry to your resource pack.

For convenience, such a model has been prepared here. The cubes from the player's model have already been removed:

📄 Geometry File

Display Settings ​

Having your model floating at the player's feet is not ideal. Our next step is to create animations so we can properly display the model on the player.

Create two new animations, one for holding the item in first person and another for holding it in third person. Select your third-person animation, and position it however you want. Save this animation to your resource pack.

Here is an example of such an animation. This also includes a first-person animation—the means of making one is detailed in the section below.

📄 Animation File

First-person Animations ​

To more easily create first-person animations, we need to mimic how the arm is positioned in the first person.

TIP

To add animation for player's hands, you need to use player's animations, not attachables animations.

Use the following guide animation and import it into Blockbench. It applies a rotation of (95, -45, 115) and a translation of (13.5, -10, 12) to the right arm bone, perfectly mimicking how the arm is positioned in first-person.

📄 Attachable Guide File

NOTE

This is where things get tricky. Both animations will need to be played simultaneously; your first-person animation, and the guide's first-person animation.

Be sure you are editing your animation when making your changes. Select it first, then play the guide's first-person animation on top.

Conclusion ​

With this all set up, go through and delete the cubes from the player skeleton if there are any, but keep the bones. Check the model out in-game!

Method 2 - Bound to a Bone ​

intermediate

In this second method, the attachable geometry will be constructed using model binding. This allows a model to be directly attached to a bone within a mob's geometry corresponding to the slot it is equipped in. Minecraft employs model binding for its attachable items, including the trident, spyglass, bow, and shield.

While this method allows the attachable to apply more dynamically to other mobs and equipment slots, model binding also has strange quirks, which will be illustrated below. Some developers may find this method trickier to get working.

Model Binding ​

Our first step is to upgrade the model file format version to "1.16.0" if it is not already. If the model is a legacy file, then convert it before continuing; Blockbench has a tool to do this (File → Convert Project).

Next up is modifying the root bone of our geometry to be bound to the equipment slot the item is placed in. Take note of line 4 in this excerpt from the skeleton head geometry file:

RP/models/entity/skeleton_head.geo.json
json
// A bone
{
    "name": "skeleton_head",
    "binding": "q.item_slot_to_bone_name(context.item_slot)",
    "pivot": [0, 4, 0],
    "cubes": [
        {
            "origin": [-4, 0, -4],
            "size": [8, 8, 8],
            "uv": [0, 0]
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13

The "parent" key in a bone accepts a string, and whichever bone name is entered will be set as the parent to the current bone; the child bones keep their positions but move relative to the parent bone.

The "binding" key on the other hand accepts Molang, and the pivot point of whichever bone name is entered is set as the root position that the child bone and its children should inherit.

For the value of "binding" we are using the Molang query q.item_slot_to_bone_name, which converts a slot name to a bone name, with the contextual variable context.item_slot as an argument. This converts the name of the equipment slot this item resides in to its corresponding bone name in the player's geometry. The conversions are as follows:

  • 'main_hand' → "rightitem"
  • 'off_hand' → "leftitem"

Apply the model binding to your bone, and save the geometry to your resource pack.

An example model with this binding applied is provided here:

📄 Geometry File

Display Settings ​

With that done, the next step is to set up animations to display the model in first person and third person.

Create two new animations, one for holding the item in first person and another for holding it in third person.

To make creating these animations easier, please do the following:

  • Download the following player skeleton model. We will use this as a visual aid for positioning your model.

    📄 Player Skeleton File
  • With a text editor, add the bones and cubes from your model to the player skeleton model, then import the player skeleton model into Blockbench.

  • Set your model's root bone(s) to be a child of the 'rightItem' bone in the player skeleton.

  • Download the following animation file import the wiki.third_person_guide animation. This will be used later to make positioning easier.

    📄 Attachable Guide File

These guide animations have one notable feature: they apply a -24 offset to the y-position of the right item bone to counteract a similar -24 y-position offset Minecraft applies to bound bones. We are unsure at this time why this happens.

NOTE

Similar to Method One, two animations will need to be played simultaneously for correct positioning.

Be sure you are editing your animations when making your changes. Select it first, then play the guide animation on top.

Play both animations, and position your model however you want. Save the animations to your resource pack.

An example animation file for this positioning:

📄 Animation File

First-person Animations ​

Similar to the third-person animation, look in the Attachable Guide file and import the wiki.first_person_guide animation into Blockbench. Play both your animation and the guide's first-person animation together, then make your changes and save the file.

Example Pack ​

Each of these methods have been compiled into an example pack you may reference, for if you are getting stuck or simply want to see a working example.

💾 Example Pack

Contributors

Edit Attachables on GitHub

Bedrock Wiki by Bedrock OSS

"Minecraft" is a trademark of Mojang AB.

Bedrock OSS, Bedrock Wiki and bedrock.dev are not affiliated in any way with Microsoft or Mojang AB.

  • Privacy Policy
  • Join our Discord
  • Learn how to Contribute
  • Visit our Repository