How to Make a Custom Entity in Minecraft Bedrock (Step-by-Step)

Before you start

If you have never made an add-on before, read How to Make an Add-On in Minecraft Bedrock first. It covers the two-pack structure (behaviour pack + resource pack), the manifest files, and where to put everything on your PC.

In this guide you will create a small robot entity. You will need:

• A text editor (VS Code is free and recommended).
• Blockbench: a free 3D modelling tool with a dedicated Bedrock Entity format.
• A UUID generator (e.g. uuidgenerator.net) for your manifest files.
• Minecraft Bedrock on PC with cheats enabled in your test world.

Put your work-in-progress packs in the development_behavior_packs and development_resource_packs folders inside your com.mojang directory. This avoids caching issues while you edit.

The behaviour-pack entity file

The behaviour pack (BP) tells the game what the entity is: its identifier, health, movement, and AI behaviour. Create a file called robot.json inside the entities/ folder of your behaviour pack.

Here is a complete, valid entity file. Copy it into entities/robot.json:

{
  "format_version": "1.26.50",
  "minecraft:entity": {
    "description": {
      "identifier": "myaddon:robot",
      "is_spawnable": true,
      "is_summonable": true
    },
    "components": {
      "minecraft:type_family": { "family": ["robot"] },
      "minecraft:collision_box": { "width": 0.6, "height": 1.0 },
      "minecraft:health": { "value": 20, "max": 20 },
      "minecraft:physics": {},
      "minecraft:movement": { "value": 0.25 },
      "minecraft:movement.basic": {},
      "minecraft:jump.static": {},
      "minecraft:navigation.walk": { "avoid_water": true },
      "minecraft:nameable": {},
      "minecraft:behavior.random_stroll": { "priority": 6, "speed_multiplier": 0.8 },
      "minecraft:behavior.look_at_player": { "priority": 7, "look_distance": 6, "probability": 0.02 },
      "minecraft:behavior.random_look_around": { "priority": 7 }
    }
  }
}

What each part does

description

• identifier: the unique name of your entity. It must be namespace:name, all lowercase, using only letters, digits and underscores. The minecraft namespace is reserved, so pick your own (e.g. myaddon).
• is_spawnable: true: registers a spawn egg in the creative inventory.
• is_summonable: true: allows the /summon command to create the entity.

components (together they make a walkable, interactive mob)

• minecraft:type_family: groups your entity so other systems (loot, targeting) can reference it by family name.
• minecraft:collision_box: the hitbox size in blocks. width 0.6 and height 1.0 is roughly human-sized.
• minecraft:health: starting and maximum health. 20 equals 10 hearts.
• minecraft:physics: enables gravity and collision. An empty object {} is the default.
• minecraft:movement: base speed. 0.25 is the standard animal pace.
• minecraft:movement.basic: allows the entity to move at all. Without this (and a navigation component) the entity will not walk.
• minecraft:jump.static: lets the entity jump over small obstacles.
• minecraft:navigation.walk: pathfinding for land. avoid_water: true keeps it out of deep water.
• minecraft:nameable: lets you rename the entity with a name tag.
• minecraft:behavior.random_stroll: wanders to random spots. priority is the decision order (lower = checked first); speed_multiplier scales its walking speed.
• minecraft:behavior.look_at_player: occasionally turns toward you. look_distance is in blocks; probability is the chance per tick.
• minecraft:behavior.random_look_around: looks around randomly when idle.

The client-entity file (resource pack)

The resource pack (RP) tells the game how the entity looks: which texture, which 3D model, and which render controller to use. Create a file called robot.entity.json inside the entity/ folder of your resource pack.

Here is a complete, valid client-entity file:

{
  "format_version": "1.10.0",
  "minecraft:client_entity": {
    "description": {
      "identifier": "myaddon:robot",
      "materials": { "default": "entity_alphatest" },
      "textures": { "default": "textures/entity/robot" },
      "geometry": { "default": "geometry.robot" },
      "render_controllers": [ "controller.render.default" ],
      "spawn_egg": {
        "base_color": "#505152",
        "overlay_color": "#3b9dff"
      }
    }
  }
}

What each key does

• identifier: must be exactly the same as in the BP file, including the namespace. If it does not match, the game cannot link the two files.
• materials: maps a short name to a vanilla material. Use entity_alphatest if your texture has transparent pixels (most do). Use entity_alphablend for fully translucent entities.
• textures: the path to your PNG, without the .png extension, relative to the resource-pack root.
• geometry: the geometry identifier inside your .geo.json file (e.g. geometry.robot). This is NOT a file path.
• render_controllers: an array of controller IDs. controller.render.default is a built-in vanilla controller that uses the default geometry, material and texture. You do not need to write your own for a simple entity.
• spawn_egg: two hex colours that tint the default egg shape. Alternatively you can use a custom icon texture with a "texture" key.

The model and texture (Blockbench)

You need a 3D model (geometry) and a texture (PNG) for your entity. The easiest way to make both is with Blockbench, a free modelling tool that has a dedicated "Bedrock Entity" format.

1. Open Blockbench and create a new project with the Minecraft Bedrock format.
2. Build your model using cubes. Set the geometry name in the project settings to match your entity (e.g. robot). Blockbench will generate the geometry.robot identifier automatically.
3. Paint the texture directly in Blockbench (or import a PNG you made elsewhere).
4. Export the model as a .geo.json file. Save it to models/entity/robot.geo.json in your resource pack.
5. Save the texture as a PNG. Save it to textures/entity/robot.png in your resource pack.

The exported .geo.json file will look something like this (simplified):

{
  "format_version": "1.12.0",
  "minecraft:geometry": [
    {
      "description": {
        "identifier": "geometry.robot",
        "texture_width": 64,
        "texture_height": 64,
        "visible_bounds_width": 2,
        "visible_bounds_height": 2.5,
        "visible_bounds_offset": [0, 0.75, 0]
      },
      "bones": [
        {
          "name": "body",
          "pivot": [0, 24, 0],
          "cubes": [
            { "origin": [-4, 12, -2], "size": [8, 12, 4], "uv": [0, 0] }
          ]
        }
      ]
    }
  ]
}

File locations summary for the resource pack:

• entity/robot.entity.json: the client-entity definition.
• models/entity/robot.geo.json: the 3D model (from Blockbench).
• textures/entity/robot.png: the texture.

Name and spawn egg

Minecraft reads display names from a .lang file in the resource pack. Open (or create) texts/en_US.lang in your resource pack and add these two lines:

entity.myaddon:robot.name=Robot
item.spawn_egg.entity.myaddon:robot.name=Robot Spawn Egg

• entity.<identifier>.name: the name shown in the HUD, name tags, and the creative-inventory search.
• item.spawn_egg.entity.<identifier>.name: the name of the spawn egg item.

Also create texts/languages.json in the resource pack containing:

["en_US"]

Summon and test it

1. Make sure both packs are active in your world. Because the BP depends on the RP (via the manifest dependency), activating the BP should also activate the RP. Check under world settings → Behaviour Packs and Resource Packs.
2. Make sure cheats are on in the world settings.
3. Open the chat and type: /summon myaddon:robot
4. Your robot should appear at your feet. It will wander around, look at you, and look around when idle.

You can also find the spawn egg in the creative inventory (search for "Robot").

Debugging with the Content Log

If the entity does not appear, turn on the Content Log:

1. Go to Settings → Creator.
2. Enable both content-log toggles (the in-game display and the file log).
3. Re-enter the world (or restart Minecraft).
4. Press Ctrl + H to open the Content Log History and look for errors related to your entity.

If you are editing files while the game is running, use the development_behavior_packs / development_resource_packs folders and simply exit and re-enter the world to reload. Packs in the normal behavior_packs / resource_packs folders can be cached and may not pick up changes.

Common mistakes

1. Wrong folder name. BP uses entities/ (plural), RP uses entity/ (singular). Swapping them means the game cannot find your files.
2. Identifier mismatch. The identifier in the BP file and the RP client-entity file must be exactly the same, including the namespace. A single typo breaks the link.
3. Only one pack active. Make sure the BP depends on the RP (via the manifest dependencies field) so both activate together.
4. JSON syntax error. One missing comma or wrong quote ignores the entire file. Minecraft does accept // comments in JSON, but online linters will flag them. That is fine, the game does not care.
5. Wrong geometry reference. The geometry value in the client-entity file must be the geometry identifier (e.g. geometry.robot), not a file path.
6. Texture path includes .png. The textures value must be the path without the extension (e.g. textures/entity/robot, not textures/entity/robot.png).
7. Entity does not move. You need both a minecraft:movement.* component AND a minecraft:navigation.* component, plus at least one behaviour goal like random_stroll.
8. Raising format_version too high. At 1.26.40 and above, entity files get stricter validation. If you copy an old entity file and bump the version, it may fail to load. Stick with "1.26.50" for new files.

Diagnose by the spawn egg

• No egg at all: the BP entity file is broken or in the wrong folder.
• Egg is black with a raw name (e.g. item.spawn_egg.entity.myaddon:robot.name): the RP client-entity file is broken or the identifier does not match.
• Egg is the right colour but the entity is invisible: bad geometry reference, missing texture, or material problem.

Make it do more

Once your basic entity is working, here are a few components you can add to the BP file to give it more personality:

• minecraft:attack: add a "damage" value to make the entity deal damage when it hits you.
• minecraft:behavior.tempt: makes the entity follow you when you hold a specific item. Uses items (array of item IDs), within_radius, and speed_multiplier.
• minecraft:loot: set a "table" path to a loot-table JSON file in the BP so the entity drops items when it dies.
• minecraft:experience_reward: set "on_death" to give XP on kill.

For more advanced behaviour (component groups, events, animations), check the official Microsoft documentation linked in the sources below.

FAQ

Do I need to enable any experimental features?

No. Basic custom entities work on the current stable version without any experiments. You do not need "Holiday Creator Features" (which no longer exists) or "Upcoming Creator Features."

Can I use this on Xbox or PlayStation?

Custom add-ons (including custom entities) are not available on consoles. This guide is for PC (Windows) and other platforms that support add-on files.

Why does my entity show as a black cube or not appear at all?

Work through the Common mistakes list. The most likely causes are: wrong folder name (entity vs entities), identifier mismatch between BP and RP, or a missing/incorrect geometry reference. Turn on the Content Log (Settings → Creator) to see specific errors.

Can I have multiple entities in one add-on?

Yes. Create a separate JSON file in entities/ for each entity (e.g. robot.json, dragon.json), and a matching .entity.json file in the RP's entity/ folder. Each one needs its own unique identifier.

What if I want to add animations?

Animations are defined in separate .animation.json files and referenced in the client-entity file via an animations key and a scripts.animate list. Defining an animation without listing it in scripts.animate does nothing. This is an intermediate topic. Check the official Microsoft documentation for details.

Where do I find the official component reference?

The Microsoft Learn documentation has a full JSON reference for entities, blocks, and items. See the sources below for direct links.