Create a Custom Entity

Every custom entity requires at least two JSON definitions that share the exact same identifier. The server-side file lives in the Behavior Pack under the entities folder and declares health, movement speed, collision box size, and AI behaviors. The client-side file lives in the Resource Pack under the entity folder (singular) and links the identifier to a 3D model, texture, material, and animation controller.

Because the two packs do different jobs, an entity can exist on the server even if its resource definition is missing. In that state, the entity will still walk around, take damage, and drop loot, but players will see nothing except its shadow on the ground. Getting both halves connected via a shared namespace and identifier is the core workflow of entity creation.

The server entity file starts with a format_version and the minecraft:entity wrapper. Inside the description block, you declare your custom identifier using a namespace prefix (never use minecraft: for custom content) and three booleans that dictate how the entity enters the world: is_spawnable adds a spawn egg to the Creative inventory, is_summonable allows the /summon command to create it, and is_experimental unlocks experimental components if your world has those toggles enabled.

Below the description block sits the components object. Bedrock entities are built by stacking modular components together. A basic passive mob needs physics so gravity affects it, a collision box so players can hit it, a health pool, and a navigation component alongside movement mechanics so it knows how to pathfind over blocks.

{
  "format_version": "1.20.80",
  "minecraft:entity": {
    "description": {
      "identifier": "tut:pebble_golem",
      "is_spawnable": true,
      "is_summonable": true,
      "is_experimental": false
    },
    "components": {
      "minecraft:type_family": {
        "family": [ "golem", "mob" ]
      },
      "minecraft:collision_box": {
        "width": 0.6,
        "height": 0.8
      },
      "minecraft:health": {
        "value": 12,
        "max": 12
      },
      "minecraft:movement": {
        "value": 0.22
      },
      "minecraft:navigation.walk": {
        "can_path_over_water": true,
        "avoid_water": true
      },
      "minecraft:movement.basic": {},
      "minecraft:jump.static": {},
      "minecraft:physics": {},
      "minecraft:pushable": {
        "is_pushable": true,
        "is_pushable_by_piston": true
      },
      "minecraft:behavior.random_stroll": {
        "priority": 1,
        "speed_multiplier": 1.0
      },
      "minecraft:behavior.look_at_player": {
        "priority": 2,
        "look_distance": 6.0
      }
    }
  }
}

A common point of confusion for beginners is why an entity requires four separate components just to walk around. Bedrock separates the stat, the physics controller, the pathfinder, and the AI desire into distinct pieces. First, minecraft:movement sets the raw speed stat. Second, minecraft:movement.basic acts as the motor that turns that speed stat into forward motion. Third, minecraft:navigation.walk generates the actual path across terrain, checking for cliffs or water. Finally, minecraft:jump.static allows the entity to hop up single-block elevations along that path.

Even with all four movement pieces in place, the entity will stand completely still until you give it a reason to move. Components starting with minecraft:behavior. are AI goals. Every behavior goal takes a priority integer, where lower numbers mean higher importance. In the example above, random strolling has priority 1, while looking at a nearby player has priority 2. This ensures the golem wanders around by default and glances at players when idle.

To make the entity visible, you must create a client entity file in your Resource Pack. Notice that the folder is named entity rather than entities, and the top-level JSON key is minecraft:client_entity. The identifier inside the description must match the Behavior Pack identifier character for character.

Rather than pointing directly to raw file paths inside rendering logic, the client entity acts as a dictionary of short names. You assign a short name like default to your texture, geometry, and material. The render_controllers array then takes a render controller (such as the built-in controller.render.default) which automatically looks up the geometry, material, and texture labeled default and draws them on screen. You also define the spawn_egg colors here using hexadecimal codes.

{
  "format_version": "1.10.0",
  "minecraft:client_entity": {
    "description": {
      "identifier": "tut:pebble_golem",
      "materials": {
        "default": "entity_alphatest"
      },
      "textures": {
        "default": "textures/entity/pebble_golem"
      },
      "geometry": {
        "default": "geometry.pebble_golem"
      },
      "render_controllers": [ "controller.render.default" ],
      "spawn_egg": {
        "base_color": "#7a7a7a",
        "overlay_color": "#4f6b48"
      }
    }
  }
}

The client entity references geometry.pebble_golem, which must be defined inside a file in the RP/models/entity/ directory. While production models are usually built visually in Blockbench, the underlying file is plain JSON. A modern Bedrock geometry file uses format_version 1.12.0 and consists of bones and cubes. The visible_bounds properties tell the rendering engine when the model is on screen so it does not cull the entity prematurely.

You also need a PNG texture placed at RP/textures/entity/pebble_golem.png. Notice that in the client entity file, you omit the .png extension when declaring the texture path. For our simple 10x10x10 cube model below, any 64x64 PNG image placed at that path will wrap around the box and allow you to see your entity in-game.

{
  "format_version": "1.12.0",
  "minecraft:geometry": [
    {
      "description": {
        "identifier": "geometry.pebble_golem",
        "texture_width": 64,
        "texture_height": 64,
        "visible_bounds_width": 2,
        "visible_bounds_height": 2,
        "visible_bounds_offset": [ 0, 0.5, 0 ]
      },
      "bones": [
        {
          "name": "body",
          "pivot": [ 0, 0, 0 ],
          "cubes": [
            {
              "origin": [ -5, 0, -5 ],
              "size": [ 10, 10, 10 ],
              "uv": [ 0, 0 ]
            }
          ]
        }
      ]
    }
  ]
}

If you load into a world right now with both packs applied, your spawn egg will display a raw translation key like item.spawn_egg.entity.tut:pebble_golem.name. To give the entity and its egg a clean display name, add two entries to your Resource Pack language file at RP/texts/en_US.lang. Ensure there are no spaces around the equals sign.

Once your language file is saved, reload your world or run /reload if you are only editing behavior files. Open the Creative inventory to find your two-toned spawn egg, or type /summon tut:pebble_golem into chat. Always enable the Content Log in your Creator settings while testing; if a bracket is missing or an identifier is mistyped, the Content Log will immediately print the exact file and line number that failed to parse.

entity.tut:pebble_golem.name=Pebble Golem
item.spawn_egg.entity.tut:pebble_golem.name=Spawn Pebble Golem

Applies to Minecraft Bedrock 1.20.80 and newer stable releases. Client entity format 1.10.0 and geometry format 1.12.0 remain the standard client formats in current versions. No experimental toggles are required for custom entities.

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