Every mob in an add-on has a behavior file. It decides how much health the mob has, how it moves, what it attacks and how it changes over time. This page takes that file apart piece by piece, using a Ruby Golem as the example.
If you have never made a mob before, start with Your first custom mob. This page goes deeper into how the file is organised.
The files
The behavior file sits in the entities folder of the behavior pack. The file name is up to you, but naming it after the mob keeps things tidy.
BP/
entities/
ruby_golem.json
spawn_rules/
ruby_golem.jsonHow the mob looks is set in a second file in the resource pack. See The client entity file.
The four parts
Inside minecraft:entity there are up to four blocks. Only description is required, but almost every mob uses all four.
| Part | What it holds |
|---|---|
description | The mob's ID and a few switches: can it have a spawn egg, can /summon make it, which properties it stores |
components | Things the mob always has: health, movement, collision box, basic behaviors |
component_groups | Named bundles of components that you switch on and off later, like "baby" or "angry" |
events | Named actions that switch those bundles on and off |
Here is the empty skeleton:
{
"format_version": "1.26.50",
"minecraft:entity": {
"description": {},
"components": {},
"component_groups": {},
"events": {}
}
}format_version tells the game which version of the rules your file follows. Use a recent version, like the one the vanilla entities use.
Part 1: description
"description": {
"identifier": "wiki:ruby_golem",
"is_spawnable": true,
"is_summonable": true
}| Field | What it does |
|---|---|
identifier | The mob's ID, in the form namespace:name. It must match the resource pack file exactly. Never use the minecraft namespace for your own mobs. |
is_spawnable | true gives the mob a spawn egg and lets spawn rules place it in the world. |
is_summonable | true lets the /summon command create it. |
runtime_identifier | Optional. Borrows hidden, hard-coded behavior from a vanilla mob, for example minecraft:snowball. Most mobs do not need it. |
properties | Optional. Values the mob remembers, explained below. |
Many vanilla mobs also have a spawn_category line, like "creature" or "monster". Your mob works without it.
Properties: values the mob remembers
Properties are small pieces of data stored on each mob. You can change them from events, test them with filters, and read them in Molang with q.property('wiki:mood').
"properties": {
"wiki:mood": {
"type": "enum",
"values": ["calm", "angry"],
"default": "calm",
"client_sync": true
},
"wiki:rubies_eaten": {
"type": "int",
"range": [0, 5],
"default": 0
}
}| Type | Holds | Extra field |
|---|---|---|
bool | true or false | none |
int | A whole number | range: the lowest and highest allowed value |
float | A decimal number | range: the lowest and highest allowed value |
enum | One word from a list | values: the list of allowed words |
defaultis the starting value. It can also be a Molang expression, which vanilla bees use to work out their starting state.client_syncsends the value to the resource pack, so animations and render controllers can use it. Turn it on only when the looks depend on it.
Properties or component groups?
Use a component group when the mob should act differently. Use a property when you just need to remember something, or when the model or texture must change with it.
Part 2: components
components are always active, from the moment the mob spawns. Put the things that never change here: its family, collision box, physics and the way it walks.
"components": {
"minecraft:type_family": { "family": ["ruby_golem", "golem", "mob"] },
"minecraft:health": { "value": 40, "max": 40 },
"minecraft:collision_box": { "width": 1.2, "height": 2.4 },
"minecraft:physics": {},
"minecraft:movement": { "value": 0.25 },
"minecraft:movement.basic": {},
"minecraft:navigation.walk": { "avoid_water": true },
"minecraft:jump.static": {},
"minecraft:behavior.random_stroll": { "priority": 6, "speed_multiplier": 0.8 },
"minecraft:behavior.look_at_player": { "priority": 7, "look_distance": 8 }
}Each key is one component, and its object holds that component's settings. An empty object {} means "use the defaults". There are hundreds of components to choose from: browse them all in Entity components.
Part 3: component groups
A component group is a named bundle of components that sits switched off until an event adds it. This is how one mob can be a baby, then an adult, or calm, then angry.
"component_groups": {
"wiki:baby": {
"minecraft:is_baby": {},
"minecraft:scale": { "value": 0.5 },
"minecraft:ageable": {
"duration": 1200,
"grow_up": { "event": "wiki:grow_up", "target": "self" }
}
},
"wiki:angry": {
"minecraft:attack": { "damage": 6 },
"minecraft:behavior.melee_attack": { "priority": 3 },
"minecraft:movement": { "value": 0.32 }
}
}A few rules worth knowing:
- Group names are yours to choose. Adding your namespace (
wiki:angry) avoids clashes and makes them easy to spot. - A mob can only have one copy of each component. When a group with
minecraft:movementis added, its speed is used instead of the one the mob had before. - Adding a group that is already active restarts its components. A
minecraft:timer, for example, starts counting from zero again.
Part 4: events
Events are the switches. Each event has a name and a list of things to do, most often add and remove for component groups.
"events": {
"wiki:grow_up": {
"remove": { "component_groups": ["wiki:baby"] }
},
"wiki:become_angry": {
"add": { "component_groups": ["wiki:angry"] },
"set_property": { "wiki:mood": "angry" }
}
}Something has to fire an event. In the baby group above, minecraft:ageable fires wiki:grow_up when the time is up. Other components, like minecraft:damage_sensor, minecraft:timer and minecraft:environment_sensor, fire events too. Commands can as well: /event entity @e[type=wiki:ruby_golem] wiki:become_angry.
Events can do much more: pick at random, run steps in order and check conditions. That is all on the next page, Entity events.
The whole Ruby Golem
Here is everything put together. The golem spawns as an adult most of the time, sometimes as a baby. It gets angry when a player hits it, and calms down after 20 seconds.
{
"format_version": "1.26.50",
"minecraft:entity": {
"description": {
"identifier": "wiki:ruby_golem",
"is_spawnable": true,
"is_summonable": true,
"properties": {
"wiki:mood": {
"type": "enum",
"values": ["calm", "angry"],
"default": "calm",
"client_sync": true
}
}
},
"components": {
"minecraft:type_family": { "family": ["ruby_golem", "golem", "mob"] },
"minecraft:health": { "value": 40, "max": 40 },
"minecraft:collision_box": { "width": 1.2, "height": 2.4 },
"minecraft:physics": {},
"minecraft:movement": { "value": 0.25 },
"minecraft:movement.basic": {},
"minecraft:navigation.walk": { "avoid_water": true },
"minecraft:jump.static": {},
"minecraft:behavior.hurt_by_target": { "priority": 2 },
"minecraft:behavior.random_stroll": { "priority": 6, "speed_multiplier": 0.8 },
"minecraft:behavior.look_at_player": { "priority": 7, "look_distance": 8 },
"minecraft:damage_sensor": {
"triggers": [
{
"on_damage": {
"filters": { "test": "is_family", "subject": "other", "value": "player" },
"event": "wiki:become_angry"
}
}
]
}
},
"component_groups": {
"wiki:baby": {
"minecraft:is_baby": {},
"minecraft:scale": { "value": 0.5 },
"minecraft:ageable": {
"duration": 1200,
"grow_up": { "event": "wiki:grow_up", "target": "self" }
}
},
"wiki:angry": {
"minecraft:attack": { "damage": 6 },
"minecraft:behavior.melee_attack": { "priority": 3 },
"minecraft:movement": { "value": 0.32 },
"minecraft:timer": {
"time": 20,
"looping": false,
"time_down_event": { "event": "wiki:calm_down" }
}
}
},
"events": {
"minecraft:entity_spawned": {
"randomize": [
{ "weight": 80 },
{ "weight": 20, "add": { "component_groups": ["wiki:baby"] } }
]
},
"wiki:grow_up": {
"remove": { "component_groups": ["wiki:baby"] }
},
"wiki:become_angry": {
"add": { "component_groups": ["wiki:angry"] },
"set_property": { "wiki:mood": "angry" }
},
"wiki:calm_down": {
"remove": { "component_groups": ["wiki:angry"] },
"set_property": { "wiki:mood": "calm" }
}
}
}
}How it flows:
- The golem appears. The game fires
minecraft:entity_spawnedby itself, and therandomizegives a 1 in 5 chance of addingwiki:baby. - A player hits it. The damage sensor checks the filter (is the attacker a player?) and fires
wiki:become_angry. - That event adds the angry group: the golem now has an attack, a melee behavior and a faster speed.
hurt_by_targethas already made the player its target. - The timer in the angry group counts 20 seconds, then fires
wiki:calm_down, which removes the group again.
Tips
- Keep
componentsfor things that never change. If a component is both incomponentsand in a group, it gets hard to tell which one is active. Put changing things only in groups. - One job per group. Small groups like
wiki:angryandwiki:babyare easier to combine than one huge group per state. - Copy from vanilla. The cow, wolf and bee files in Vanilla entities show many real patterns.
When something goes wrong
| What you see | Most likely cause |
|---|---|
The mob does not exist (/summon fails) | A JSON error, or the identifier has a typo. Check the Content Log. |
| No spawn egg | is_spawnable is false, or the resource pack has no spawn_egg |
| An event does nothing | The group name in add does not match a name in component_groups |
| A property error in the log | The property is not declared in description.properties, or the value is outside range or values |
| The mob never changes back | Nothing fires the event that removes the group |
More help is in Troubleshooting. Next: Entity events.