You built a custom mob. It has a cool model, interesting behaviors, great loot drops. You install the addon, load a world, and... nothing spawns. You wander for 20 minutes and never see it. Or worse, it spawns everywhere — in the ocean, underground, inside your house — drowning out every vanilla mob.
The problem is almost always the spawn rules. Spawn rules are the most misunderstood part of Bedrock addon development, and getting them wrong makes an otherwise great mod feel broken. This guide explains exactly how the system works.
What Spawn Rules Actually Do
A spawn rule file tells the game when, where, and how often to naturally spawn an entity. Without a spawn rule, your custom mob will never appear naturally in the world — the only way to get it is through spawn eggs, commands, or scripts.
Spawn rules live in your behavior pack at spawn_rules/ and are JSON files that define conditions for spawning. The game checks these rules constantly and spawns mobs when all conditions are met.
The Core Components
Population Control
This is the most important and least intuitive part of spawn rules. Every mob belongs to a "population control" pool that limits how many of that type can exist in loaded chunks at one time.
The vanilla pools are:
- animal: Passive mobs like cows, pigs, sheep. Cap is relatively high.
- monster: Hostile mobs like zombies, skeletons, creepers. Shared cap means adding too many custom monsters reduces vanilla monster spawns.
- water_animal: Fish, dolphins, squid.
- ambient: Bats. Very low cap.
Here's the critical thing most modders miss: your custom mob shares the population cap with every other mob in that pool. If you add a custom mob to the "monster" pool and set its spawn weight high, it will spawn frequently — but at the cost of zombies, skeletons, and creepers spawning less. You're competing for limited spawn slots.
For custom mobs, you often want to be conservative with your population allocation. A weight that's too high makes your mob dominant; too low and players never see it.
Spawn Conditions
Conditions are filters that must ALL be true for the mob to spawn. The game evaluates these continuously. Common conditions:
Biome Filter
Controls which biomes the mob can spawn in. You can target specific biomes by name or use biome tags for broader groups.
Examples:
- Specific biome:
"biome_filter": {"test": "has_biome_tag", "value": "jungle"}— spawns only in jungle biomes. - Multiple biomes: Use
"any_of"to combine multiple biome tags: jungle OR swamp OR dark forest. - Exclusion: Use
"none_of"to prevent spawning in specific biomes: anywhere EXCEPT ocean and deep ocean. - The Nether: Use the "nether" biome tag. The End uses "the_end".
Common biome tags: plains, desert, forest, taiga, jungle, swamp, ocean, mountain, mushroom_island, nether, the_end, frozen, cold, temperate, warm.
Brightness Filter
Controls the light level required for spawning. This is how vanilla Minecraft makes hostile mobs spawn in the dark and passive mobs spawn in daylight.
- Hostile mobs: Typically require brightness below 7 (dark caves, nighttime surface).
- Passive mobs: Typically require brightness above 7 (daylight, lit areas).
- Any light level: Omit the brightness filter, or set min to 0 and max to 15.
The brightness filter uses a min/max range. "min": 0, "max": 7 means the mob spawns in light levels 0 through 7 (dark). "min": 8, "max": 15 means bright areas only.
Height Filter
Restricts spawning to specific Y-levels. Useful for underground-only mobs (below Y=0 for deep dark creatures) or surface-only mobs (above Y=60).
Difficulty Filter
Prevents spawning on specific difficulty settings. Hostile mobs typically don't spawn on Peaceful. You can also make "hard mode only" mobs by requiring Hard difficulty.
Density Limit
Limits how many of your specific mob can exist in a local area, separate from the global population cap. If density limit is 2, there will never be more than 2 of your mob in a small area — but there could be 10 total across all loaded chunks.
Spawn Weight
Within a population pool, spawn weight determines how likely your mob is to be chosen when the game decides to spawn something. Higher weight = more frequent. But remember, this is relative to every other mob in the same pool.
Vanilla reference weights (monster pool):
- Zombie: 100
- Skeleton: 80
- Creeper: 100
- Spider: 100
- Enderman: 10
- Witch: 5
If you set your custom mob's weight to 100, it will spawn roughly as often as zombies — which means it's taking a significant chunk of the monster spawn budget. For most custom mobs, a weight of 10-30 is a good starting point. Rare boss-type mobs should be 1-5.
Herd Size
Determines how many mobs spawn together in a group. Defined as a min/max range. Wolves use 1-4. Zombies use 2-4. Setting herd size to 1-1 means they always spawn alone (good for rare or powerful mobs).
Practical Examples
Example 1: Forest Guardian
A protective spirit that spawns in forests during the day. Passive unless attacked.
Spawn rule design:
- Population control: animal pool (doesn't compete with hostile spawns)
- Biome filter: forest, birch_forest, dark_forest, flower_forest
- Brightness: min 8, max 15 (daytime only)
- Weight: 8 (uncommon — you'll see one occasionally but they won't be everywhere)
- Herd size: 1-1 (always spawns alone — it's a solitary guardian)
- Density limit: 1 (max 1 per local area — they're territorial)
Example 2: Cave Crawler
A hostile spider-like mob that lives deep underground in packs.
Spawn rule design:
- Population control: monster pool
- Biome filter: Use
"none_of"to exclude ocean, the_end, nether — spawns in all Overworld land biomes - Brightness: min 0, max 4 (very dark only — deep caves)
- Height: min -64, max 20 (underground only)
- Weight: 20 (less common than zombies but you'll find packs in caves)
- Herd size: 2-5 (spawns in groups — pack hunters)
- Density limit: 6 (can have several in one cave system)
Example 3: Nether Merchant
A rare trader that appears in the Nether. Very uncommon, always alone.
Spawn rule design:
- Population control: monster pool (Nether uses the monster pool for most mobs)
- Biome filter: nether_wastes, crimson_forest, warped_forest, soul_sand_valley, basalt_deltas
- Brightness: any (Nether lighting is inconsistent)
- Weight: 3 (very rare — finding one is an event)
- Herd size: 1-1 (always alone)
- Density limit: 1 (max 1 in loaded chunks — truly rare)
Common Mistakes
- Forgetting the spawn rule entirely. Your mob won't spawn naturally without one. This is the #1 reason custom mobs "don't work."
- Weight too high. A weight of 200 makes your mob the most common thing in the game. Start low (10-20) and increase if needed.
- Wrong population pool. Putting a rare boss in the "animal" pool means it competes with cows and pigs for spawns — which works, but feels weird. Hostile mobs belong in the monster pool.
- No density limit. Without a density limit, your mob can cluster. You'll find 15 of them in one spot and none anywhere else.
- Biome filter too broad. A mob that spawns in every biome feels generic. Give it a home biome to make finding it feel special.
- Brightness filter mismatch. A "deep cave creature" that spawns at brightness 15 will appear on the surface in daylight. Match the brightness to the mob's lore.
Testing Spawn Rules
Spawn rules are hard to test because natural spawning is inherently random. Tips:
- Use /tickingarea to keep chunks loaded and give mobs more chances to spawn.
- Set game to nighttime for hostile mob testing:
/time set night - Kill existing mobs to free up population cap slots:
/kill @e[type=!player] - Teleport to the right biome. Your jungle mob won't spawn in a desert.
- Be patient. Even with correct rules, spawning is probabilistic. Give it a few minutes.
- Check the behavior pack is active. Obvious but commonly overlooked after an edit.
Skip the Spawn Rule Headaches
When you generate a mod with BlockSmith, spawn rules are created automatically based on your mob description. Tell it "spawns in jungle biomes at night, uncommon" and the AI generates the correct biome filters, brightness ranges, weights, and density caps. No JSON debugging required.