File Location and Structure
Every behavior entity resides in the `BP/entities/` directory of your behavior pack. You can organize this folder using subdirectories, such as `BP/entities/hostile/` or `BP/entities/projectiles/`, because the game engine scans the entire folder tree and registers every valid JSON file it finds. The filename itself does not dictate the entity's in-game identifier, though keeping them identical is standard practice to avoid confusion in larger projects.
At the root of the JSON file, you must declare a `format_version` and the `minecraft:entity` object. The `format_version` tells Minecraft which schema parser to use when reading your components. Inside `minecraft:entity`, the file splits into four distinct regions: `description`, `components`, `component_groups`, and `events`. Only `description` and `components` are strictly required for a minimal working entity.
{
"format_version": "1.20.40",
"minecraft:entity": {
"description": {
"identifier": "custom:copper_golem",
"is_spawnable": true,
"is_summonable": true,
"is_experimental": false
},
"components": {
"minecraft:type_family": {
"family": [ "golem", "mob" ]
},
"minecraft:collision_box": {
"width": 0.9,
"height": 1.2
},
"minecraft:health": {
"value": 30,
"max": 30
},
"minecraft:physics": {},
"minecraft:pushable": {
"is_pushable": true,
"is_pushable_by_piston": true
}
}
}
}The Description Block
The `description` block registers the entity's identity and basic engine permissions. The `identifier` field requires a namespace followed by a colon and the entity name (for example, `custom:copper_golem`). You must never use the `minecraft` namespace for new entities; doing so is reserved for overriding vanilla files and will cause your custom entity to fail to load.
The boolean flags inside the description control how players and commands can bring the entity into the world. If you are making a technical utility entity—like an invisible point that generates particles—you will typically disable the spawn egg while leaving `/summon` access enabled. This block is also where you define entity properties and server-side animations, though those are optional for basic mobs.
| Field | What it does | Notes |
|---|---|---|
| identifier | Sets the unique namespace and ID for the entity. | Must be lowercase. Match this exact string in your Resource Pack client_entity file. |
| is_spawnable | Generates a spawn egg in the Creative inventory. | Requires a matching entry or texture definition in the Resource Pack to look correct. |
| is_summonable | Allows the entity to be spawned using the /summon command. | Set to true for almost all custom entities. |
| is_experimental | Locks the entity behind experimental gameplay toggles. | Always set to false unless using specific unstable beta components. |
Components: Attributes, Physics, and AI
Bedrock uses an entity-component architecture. On its own, a newly declared entity is completely inert: it has no gravity, no hitbox, no health, and no movement. You give the entity traits by stacking individual `minecraft:*` components inside the `components` object. Anything placed in the base `components` block is active the moment the entity enters the world and remains active unless explicitly overridden.
Components generally fall into three functional categories. Physical components define how the entity exists in space: `minecraft:physics` enables gravity and block collisions, `minecraft:collision_box` sets the hitbox dimensions in blocks, and `minecraft:health` sets hit points. Movement mechanics require a combination of components working together—typically `minecraft:movement` to set the speed attribute, a movement type like `minecraft:movement.basic` to control turning, and a pathfinding ruleset like `minecraft:navigation.walk` so the mob knows how to route around obstacles.
The third category is AI behavior, identifiable by the `minecraft:behavior.*` prefix. Behavior components dictate what the entity actively tries to do, such as wandering, fleeing, or attacking. Most behavior components take a `priority` integer. The engine evaluates lower numbers as higher priority: a goal with priority 0 will interrupt and override a goal with priority 3.
{
"format_version": "1.20.40",
"minecraft:entity": {
"description": {
"identifier": "custom:roaming_beetle",
"is_spawnable": true,
"is_summonable": true,
"is_experimental": false
},
"components": {
"minecraft:physics": {},
"minecraft:collision_box": {
"width": 0.6,
"height": 0.4
},
"minecraft:health": {
"value": 10,
"max": 10
},
"minecraft:movement": {
"value": 0.25
},
"minecraft:movement.basic": {},
"minecraft:navigation.walk": {
"can_path_over_water": true,
"avoid_damage_blocks": true
},
"minecraft:jump.static": {},
"minecraft:behavior.float": {
"priority": 0
},
"minecraft:behavior.panic": {
"priority": 1,
"speed_multiplier": 1.25
},
"minecraft:behavior.random_stroll": {
"priority": 2,
"speed_multiplier": 1.0
},
"minecraft:behavior.look_at_player": {
"priority": 3,
"look_distance": 6.0
}
}
}
}Dynamic States with Component Groups and Events
If an entity never changes how it acts, placing everything inside the main `components` block is sufficient. However, most mobs need to change states over their lifetime: a baby animal grows into an adult, a neutral guard becomes hostile when struck, or a pet sits down when interacted with. Bedrock handles state changes through `component_groups` and `events`.
A component group is a named bundle of components that sits dormant until activated. When an event fires, it can `add` or `remove` specific component groups on the entity. If an added group contains a component that already exists in the base `components` block (for example, a new `minecraft:movement` value), the group's version temporarily overwrites the base version. Removing the group reverts the entity back to its base component values.
The engine automatically fires certain built-in events, most notably `minecraft:entity_spawned` when the mob first generates, and `minecraft:entity_born` when it is bred. You can also trigger custom events from within components (like an age timer running out) or externally via the `/event` command.
{
"format_version": "1.20.40",
"minecraft:entity": {
"description": {
"identifier": "custom:growing_beetle",
"is_spawnable": true,
"is_summonable": true,
"is_experimental": false
},
"component_groups": {
"custom:baby_state": {
"minecraft:is_baby": {},
"minecraft:scale": {
"value": 0.5
},
"minecraft:ageable": {
"duration": 1200,
"grow_up": {
"event": "custom:age_up_event",
"target": "self"
}
}
},
"custom:adult_state": {
"minecraft:scale": {
"value": 1.0
}
}
},
"components": {
"minecraft:physics": {},
"minecraft:collision_box": {
"width": 0.8,
"height": 0.6
},
"minecraft:health": {
"value": 16,
"max": 16
}
},
"events": {
"minecraft:entity_spawned": {
"randomize": [
{
"weight": 80,
"add": {
"component_groups": [ "custom:adult_state" ]
}
},
{
"weight": 20,
"add": {
"component_groups": [ "custom:baby_state" ]
}
}
]
},
"custom:age_up_event": {
"remove": {
"component_groups": [ "custom:baby_state" ]
},
"add": {
"component_groups": [ "custom:adult_state" ]
}
}
}
}
}Which versions this applies to
Applies to all modern Bedrock versions (1.16.0 through 1.21+). Standard entity definitions, component groups, and events are fully stable and do not require any experimental toggles.
When it does not work
| What you see | Why | The fix |
|---|---|---|
| Running `/summon custom:my_entity` returns "Syntax error: Unexpected 'custom:my_entity'" and the ID does not appear in autocomplete. | Either `is_summonable` is set to `false` in the description, you used the reserved `minecraft:` namespace for a non-vanilla entity, or your JSON file has a syntax error (like a missing comma) that caused the parser to reject the file entirely. | Open Content Log in Creator Settings to check for JSON parsing errors. Ensure the identifier uses a custom namespace and `is_summonable` is `true`. |
| The entity summons successfully (chat says "Object successfully summoned"), but it is completely invisible. | A Behavior Pack only defines server-side logic. Without a corresponding Resource Pack entity definition (`RP/entity/`), geometry, texture, and render controller, the client has nothing to draw on screen. | Turn on hitbox visualization (`F3 + B` on Windows or via the Creator settings toggle) to confirm the entity's collision box is actually present in the world, then set up the matching Resource Pack client entity file. |
| The entity spawns and renders, but stands completely frozen in place despite having `minecraft:behavior.random_stroll`. | AI behavior goals only decide where the entity wants to go; they cannot move the entity by themselves. The entity is missing the underlying mechanical components required to execute movement. | Add `minecraft:movement` (with a `value` greater than 0), `minecraft:movement.basic`, `minecraft:navigation.walk`, and `minecraft:jump.static` to the entity's components. |
Reference, straight from the game files
Read out of the game itself, so the ids match the version you are building for.