Without a spawn rule, a mob only appears from its spawn egg or /summon. A spawn rule tells the game where and when it may appear by itself: which biomes, how dark it must be, how many at once and how often compared with other mobs.
This page uses the Ruby Golem from The entity file. For the full mob, start with Your first custom mob.
The files
BP/
entities/
ruby_golem.json
spawn_rules/
ruby_golem.jsonThe file name does not matter. What links the rule to the mob is the identifier inside it.
The mob must be spawnable
Spawn rules only work if the mob's behavior file has "is_spawnable": true in its description.
A first spawn rule
Ruby Golems appear in deserts and badlands, in small groups, on sand or red sand, in daylight:
{
"format_version": "1.8.0",
"minecraft:spawn_rules": {
"description": {
"identifier": "wiki:ruby_golem",
"population_control": "animal"
},
"conditions": [
{
"minecraft:spawns_on_surface": {},
"minecraft:spawns_on_block_filter": ["minecraft:sand", "minecraft:red_sand"],
"minecraft:brightness_filter": {
"min": 7,
"max": 15,
"adjust_for_weather": false
},
"minecraft:weight": { "default": 6 },
"minecraft:herd": { "min_size": 1, "max_size": 2 },
"minecraft:biome_filter": {
"any_of": [
{ "test": "has_biome_tag", "value": "desert" },
{ "test": "has_biome_tag", "value": "mesa" }
]
}
}
]
}
}Almost every vanilla spawn rule still uses "format_version": "1.8.0", and so can you.
The description
| Field | What it does |
|---|---|
identifier | The mob's ID. It must match the entity file exactly. |
population_control | Which pool the mob counts toward. Each pool has its own limit, so your mob cannot fill the world. |
The pools you will use most:
| Pool | Used by |
|---|---|
animal | Land animals like cows, pigs and sheep |
water_animal | Fish, squid, dolphins and axolotls |
monster | Hostile mobs like zombies and skeletons |
ambient | Small background mobs, like bats |
Vanilla also has a few special pools, such as cat and pillager, for single mobs.
Conditions
conditions is a list. Each entry is a complete set of rules. If the game finds a spot that matches any one entry, the mob may spawn there.
Inside one entry, every component must pass. So the rule above means "on the surface AND on sand AND in daylight AND in a desert or badlands biome".
Want the mob in two very different places, like caves at night and beaches by day? Add a second entry to the list instead of cramming everything into one.
Where: surface, underground or water
At least one of these is needed, or the mob has nowhere to spawn. They are empty objects: just being there switches them on.
| Component | Spawns the mob |
|---|---|
minecraft:spawns_on_surface | On the ground, open to the sky |
minecraft:spawns_underground | In caves, with blocks above |
minecraft:spawns_underwater | In water |
minecraft:spawns_lava | In lava, like striders |
You can combine them. Vanilla axolotls use both spawns_underground and spawns_underwater to appear in cave water.
Which blocks
"minecraft:spawns_on_block_filter": ["minecraft:sand", "minecraft:red_sand"],
"minecraft:spawns_on_block_prevented_filter": ["minecraft:cactus"]spawns_on_block_filter: the block under the mob must be one of these. A single block can be a plain string.spawns_on_block_prevented_filter: the mob may never spawn on these blocks.
Which biomes
minecraft:biome_filter is a normal filter, usually with the has_biome_tag test. Every biome carries a few tags, like desert, forest, ocean, frozen, overworld or nether. Testing a tag is better than naming biomes one by one, because it also catches biome variants and biomes from other add-ons.
"minecraft:biome_filter": [
{ "test": "has_biome_tag", "value": "overworld" },
{ "test": "has_biome_tag", "operator": "not", "value": "ocean" }
]A plain list works like all_of: here, "in the Overworld, but not in an ocean". Look up which tags each biome has in Vanilla biomes, and see how biomes get their tags in biome tags.
The animal and monster tags
Most land biomes carry the tags animal and monster. Vanilla cows use has_biome_tag with animal, and zombies use monster. They are an easy way to say "anywhere a normal mob could live".
Light level
"minecraft:brightness_filter": {
"min": 0,
"max": 7,
"adjust_for_weather": true
}Light goes from 0 (pitch black) to 15 (full daylight). Animals usually use 7 to 15, monsters 0 to 7. With adjust_for_weather set to true, rain and storms make it count as darker, so monsters can appear on a stormy day.
How often: weight
"minecraft:weight": { "default": 6 }When the game picks which mob to spawn at a spot, mobs with a bigger weight are picked more often. For a sense of scale: vanilla cows use 8, bats 10, and zombies 100. Start low for a rare mob and raise it while testing.
How many: herd
"minecraft:herd": {
"min_size": 2,
"max_size": 4,
"event": "minecraft:entity_born",
"event_skip_count": 2
}min_sizeandmax_size: how many spawn together.event(optional): an event fired on the mobs of the group as they spawn.event_skip_count: how many mobs spawn before the event starts firing.
The example above is the vanilla trick for families: the first 2 spawn as normal adults, and the rest get minecraft:entity_born. In those mobs' entity files, that event adds the baby group, so the rest are babies. Foxes and axolotls do exactly this.
How crowded: density limit
"minecraft:density_limit": {
"surface": 4,
"underground": 2
}A cap just for this mob, on top of the pool limit. Once this many are already around, no more spawn on the surface (or underground). Useful for strong or rare mobs that should never come in crowds.
Difficulty
"minecraft:difficulty_filter": {
"min": "easy",
"max": "hard"
}The difficulties are peaceful, easy, normal and hard. Hostile mobs usually start at easy, so they never appear on Peaceful.
More conditions
| Component | What it checks |
|---|---|
minecraft:height_filter | The height range (min, max) the mob can spawn at |
minecraft:distance_filter | How far from the player it must be (min, max) |
minecraft:world_age_filter | How old the world must be before the mob can appear (min) |
minecraft:disallow_spawns_in_bubble | Stops it spawning in bubble columns |
minecraft:permute_type | Sometimes spawns a different mob instead, by weight. Zombies use it to make a few zombie villagers. |
A night-time version
Want angry Ruby Golems in caves too? Add a second condition with different rules:
"conditions": [
{
"minecraft:spawns_on_surface": {},
"minecraft:spawns_on_block_filter": ["minecraft:sand", "minecraft:red_sand"],
"minecraft:brightness_filter": { "min": 7, "max": 15, "adjust_for_weather": false },
"minecraft:weight": { "default": 6 },
"minecraft:herd": { "min_size": 1, "max_size": 2 },
"minecraft:biome_filter": { "test": "has_biome_tag", "value": "desert" }
},
{
"minecraft:spawns_underground": {},
"minecraft:brightness_filter": { "min": 0, "max": 4, "adjust_for_weather": false },
"minecraft:height_filter": { "min": -64, "max": 0 },
"minecraft:weight": { "default": 2 },
"minecraft:herd": { "min_size": 1, "max_size": 1, "event": "wiki:become_angry" },
"minecraft:density_limit": { "underground": 2 },
"minecraft:biome_filter": { "test": "has_biome_tag", "value": "overworld" }
}
]The second entry spawns lone golems deep underground and fires wiki:become_angry on them right away. That event comes from the Entity events page.
Testing spawn rules
Natural spawning is slow to test, so make it easier:
- Make a new world in Creative and set the difficulty to Easy or higher if your mob is hostile.
- Raise the
weighta lot (like100) while testing, then lower it again. - Fly around the right biome. Mobs only spawn some distance away from the player.
- Use
/kill @e[type=wiki:ruby_golem]to clear them and watch new ones appear.
When something goes wrong
| What you see | Most likely cause |
|---|---|
| It never spawns | is_spawnable is false, the identifier does not match, or the condition has no "where" component like spawns_on_surface |
| It never spawns in a biome | The biome does not have that tag. Check Vanilla biomes. |
| Far too many | Lower weight or max_size, or add a density_limit |
| A hostile mob never shows up on Peaceful | That is the difficulty_filter doing its job |
| Monsters during the day | adjust_for_weather is on and it is raining |
More help is in Troubleshooting. Next: Filters.