Natural spawning data
Configure spawn groups, environmental filters, group sizes and local density limits.
Natural spawn definitions configure server encounter selection and bounded group timing. They retain Minecraft’s population caps and entity restrictions; changing a weight never guarantees a successful spawn.
Where the files live
Use data/<namespace>/natural_spawning/*.json, including nested folders. A file is one group setting, entry rule or hostile-pressure profile. Its relative resource path is its ID; the highest-priority pack wins for the same ID. Distinct definitions run in ascending priority, then lexicographic ID order. The last matching group definition supplies the entire group setting, without field inheritance from earlier definitions.
Rules alter live natural spawning. New-chunk creature population retains its biome entries and only reads generation_probability from group settings. Creature defaults target minecraft:overworld; pressure defaults also cover minecraft:the_nether and minecraft:the_end; every definition must explicitly list its worlds.
Minimal example
{
"kind": "group",
"group": "creature",
"dimensions": ["minecraft:overworld"]
}
This accepted group definition leaves timing and population probability inherited and keeps height sampling unchanged. The bundled creature file adds explicit settings to this shape.
Fields
| Field | Type | Default | What it does |
|---|---|---|---|
kind | enum(group, rule, pressure) | required | Selects timing/sampling settings or entry rules. |
group | string | required | One of monster, creature, ambient, axolotls, underground_water_creature, water_creature, water_ambient. |
dimensions | array<identifier> | required | Nonempty world-ID list, at most 128 values; repeated IDs are deduplicated. These are dimension IDs, not dimension-type IDs. |
priority | integer | 0 | Inclusive range −1000–1000. Later priorities run later; ties sort by definition ID. |
interval_ticks | integer | -1 (inherit) | Group only, creature only. If supplied, 20–24000 ticks (1–1200 seconds); changes live creature attempt timing. Omit to inherit. |
surface_chance | number | 0 | Group only. Fraction 0–1 of existing attempts placed at the top non-leaf blocking surface. Nonzero only for creature or monster. |
surface_budget | number | omitted | Group only, monster only; if supplied, 0.1–0.9 of the existing global monster allowance is reserved for the surface, with the remainder reserved for caves. |
generation_probability | number | -1 (inherit) | Group only, creature only. If supplied, 0–0.35; replaces the new-chunk population probability. Does not replace generation entries. |
conditions | object | {} | Rule or pressure. All tests must pass before the definition applies. See the shared condition table. |
spawn_chance | number | 1 | Rule only. Default chance for entries added by this rule, from 0–1. Rolled once after encounter selection; failure skips that encounter without selecting a replacement. Does not gate removals, replacement or existing biome entries. |
mode | enum(merge, replace) | merge | Rule only. Merge keeps untargeted entries; replace clears the incoming biome pool. Structure and substituted pools are preserved in both modes. |
remove | array<entity id> | [] | Rule only. Remove every entry of each registered entity type before adding entries; at most 128 IDs. |
encounter | object | omitted | Rule only. Stage a viable group during the selected attempt; omit to retain vanilla placement. |
encounter.radius | integer | 6 | Horizontal search radius, 2–16 blocks. Surface members use the heightmap; cave members search within 2 vertical blocks. |
encounter.attempts | integer | 32 | Maximum candidate positions per encounter, 8–64. Fewer than entries[].min valid members cancels the whole group. |
encounter.cooldown_ticks | integer | 2400 | Saved quiet time after success, 20–240000 ticks (1–12000 seconds). Default 120 seconds. |
encounter.cooldown_radius | integer | 64 | Quiet-area radius, 16–128 blocks, rounded up to 16-block cells. Covers the cell and one vertical section either side. Keyed by rule ID. |
entries | array<object> | [] | Rule only. At most 64 entries. Empty replace intentionally disables this biome pool at matching positions. |
entries[].entity | entity id | required | Registered entity whose spawn group equals the rule group. Its own spawn restrictions still apply. |
entries[].weight | integer | 1 | Relative selection weight, 1–1000; not a percentage or a guaranteed spawn rate. |
entries[].spawn_chance | number | rule spawn_chance | Overrides the rule default, from 0–1; the two values are not multiplied. 0 always skips the selected encounter, 1 adds no chance check. Other spawn restrictions still apply. |
entries[].min | integer | 1 | Requested minimum group size, 0–8. Each integer from min through max is equally likely; a roll of 0 skips that group. Vanilla entity group limits still apply. |
entries[].max | integer | min | Requested maximum, 0–8 and at least min. With min 0 and max 1, the selected entry skips its group half the time. Both 0 always skip. With encounter enabled the minimum must fit; otherwise failed vanilla positions can produce a smaller group. |
entries[].slime_size | integer | 0 (entity default) | If supplied, 1, 2 or 4 and only for minecraft:slime. The chosen size is checked for collision before natural insertion. Omit for the entity default. |
entries[].local_limit | integer | 0 (disabled) | If supplied, 1–64 alive matching entities in the local box and habitat; all sizes and persistent mobs count. Omit to disable this additional cap. |
entries[].local_radius | integer | 32 | Horizontal X/Z expansion of the candidate block box, 8–64 blocks; used with local_limit. |
entries[].local_vertical_radius | integer | 16 | Vertical box expansion, 1–64 blocks; used with local_limit. |
entries[].density_tag | entity type tag id | omitted | Count all alive members of this entity tag together, including persistent mobs, within the same surface/cave habitat. Omit to count this entity type. Unresolved tags contain no members. |
entries[].conditions | object | {} | Additional entry filters using the same fields as rule conditions; does not relax rule or entity restrictions. |
entries[].group | object | omitted | Gives supported Isekai monsters a persistent cohort for this natural spawn pack. Omission leaves them independent. Other entity types ignore this object. |
entries[].group.cohesion_radius | number | 6 | Follow the loaded leader when farther away; 2–32 blocks. |
entries[].group.assist_radius | number | 20 | Maximum range for loaded cohort discovery and shared visible threats; cohesion_radius–48 blocks. |
entries[].group.max_attackers | integer | 2 | Concurrent action reservations in the cohort; 1–8. Reservations expire and release on cancellation. |
Cohorts preserve their identity when saved. Loaded nearby members elect a replacement when the leader disappears; this never loads a chunk. Cohort behaviour does not bypass population caps. Encounter placement is bounded by its own attempt budget inside one existing scheduled attempt. All six goblin variants use rules/goblins.json for surface patrols and rules/cave_goblins.json for cave groups.
The surface habitat tag extends #isekaiexpansion:pasture_animals with swamps, mangrove swamps, windswept forests and sparse jungles. The cave tag includes those biomes, lush caves, dripstone caves and optional Worldroot Hollow (isekaiexpansion:worldroot_hollow_ancient). Both rules require block light of at most 7. Surface patrols require raw sky light of at least 1 and accept daylight; cave groups require zero sky light through habitat: cave. The two rules therefore do not add duplicate goblin entries at one position. Common melee variants have the highest weights, and all variants request 3–5 members. These entries request one equipment type per spawn group; nearby compatible patrols can join a cohort, but a mixed party is not guaranteed.
Hostile pressure
Use kind: pressure with group: monster. The last matching profile wins as a whole, using the same priority and ID ordering. Conditions can select biome IDs or tags, height and the other environmental filters below. A naturally spawned hostile defeated by a player, an active follower, a tamed companion or a bound summon adds one kill contribution. Spawners, summons, commands and environmental deaths do not contribute.
Progress is shared by players in each dimension and saved in separate surface and cave sets of 16 × 16 × 16 cells. A kill affects a square of horizontal chunk cells and the configured vertical sections around its death position, without loading those chunks. At the kill budget, the kill-pressure multiplier reaches minimum_chance. The quiet timer restarts on each credited kill; afterwards suppression decreases linearly by one full budget per recovery period. Partial clearing therefore recovers sooner. Existing enemies remain. The multiplier is rolled once for each selected natural encounter, including structure-specific natural pools; it does not block scripted encounters.
| Field | Type | Default | What it does |
|---|---|---|---|
base_chance | number | 0.35 | Admission probability per selected monster encounter, 0–1, before kill and boundary multipliers. |
local_limit | integer | 5 | Maximum local monster count for admission, 0–64. Zero closes natural monster spawning. |
local_radius | integer | 48 | Horizontal expansion of the candidate block box, 8–64 blocks along X and Z. |
local_vertical_radius | integer | 16 | Vertical expansion of that box, 1–64 blocks above and below. |
kills_to_clear | integer | 16 | Full suppression after this many credited kills before recovery; 1–10000. |
radius_chunks | integer | 2 | Horizontal cell radius; 0–8 chunks. Default affects a 5 × 5 chunk square. |
vertical_radius_sections | integer | 1 | Vertical cell radius; 0–8 sections of 16 blocks. Default spans 3 sections. |
quiet_ticks | integer | 12000 | Delay before recovery after a kill; 0–2400000 ticks (0–120000 seconds). Default 600 seconds. |
recovery_ticks | integer | 24000 | Time to remove full suppression after the quiet period; 20–2400000 ticks (1–120000 seconds). Default 1200 seconds. |
minimum_chance | number | 0 | Remaining natural-spawn multiplier at full suppression; 0–1. Zero fully quiets the cells; one disables suppression. |
Bundled ordinary Overworld areas use 12 kills, 12000 quiet ticks (600 seconds) and 24000 recovery ticks (1200 seconds). Dark forests, swamps, mangrove swamps and the deep dark use 18 kills, 6000 quiet ticks (300 seconds) and 18000 recovery ticks (900 seconds). The Nether uses 32 kills, 2400 quiet ticks (120 seconds) and 12000 recovery ticks (600 seconds). The End uses 24 kills, 6000 quiet ticks (300 seconds) and 18000 recovery ticks (900 seconds). All use a zero minimum chance.
Ordinary Overworld, hazardous Overworld, Nether and End profiles respectively use base chances of 35%, 55%, 75% and 65% and local limits of 8, 10, 10 and 8. Each checks living mobs in the monster group, including mobs from other sources in the same surface/cave habitat, in the loaded area around each proposed pack member. The nearest spawn exclusion scales both chance and cap over 32 blocks, with the scaled cap rounded up. Movement and explicit spawns can take the count above the admission cap.
The ordinary Overworld profile is a starting point for tuning:
{
"kind": "pressure",
"group": "monster",
"dimensions": [
"minecraft:overworld"
],
"priority": -100,
"kills_to_clear": 12,
"radius_chunks": 2,
"vertical_radius_sections": 1,
"quiet_ticks": 12000,
"recovery_ticks": 24000,
"minimum_chance": 0,
"base_chance": 0.35,
"local_limit": 8,
"local_radius": 48,
"local_vertical_radius": 16
}
Timers use game ticks: sleeping or changing daylight does not advance recovery and an offline server does not recover. Successful reloads change profile selection immediately; saved cells retain the recovery schedule from their last credited kill until the next kill. Expired cells are pruned every 1200 ticks (60 seconds); at most 65536 active cells are stored per habitat in each dimension. At capacity, existing cells continue updating but new cells receive no contribution until space is freed.
Shared conditions
The following keys go inside both conditions and entries[].conditions. All tests are conjunctive. A cave filter includes covered rooms; it is not a geological cave detector. Raw sky light does not encode day or night: use effective light or the time interval for that distinction.
| Field | Type | Default | What it does |
|---|---|---|---|
conditions.biomes | array<string> | [] | Any matching biome ID or #namespace:tag; empty accepts all. At most 128 values. |
conditions.excluded_biomes | array<string> | [] | Reject any matching ID or tag, even if included; at most 128 values. |
conditions.habitat | enum(any, surface, cave, water, lava) | any | Surface: dry feet at or above the top non-leaf blocking height. Cave: dry feet and zero raw sky light, including covered rooms. Water/lava: the corresponding fluid tag at the feet. |
conditions.min_y | integer | -2032 | Minimum block Y, −2032–2031. |
conditions.max_y | integer | 2031 | Maximum block Y, −2032–2031; at least min_y. |
conditions.min_light | integer | 0 | Minimum effective light, 0–15; includes ambient darkness. |
conditions.max_light | integer | 15 | Maximum effective light, 0–15; at least min_light. |
conditions.min_sky_light | integer | 0 | Minimum raw sky light, 0–15. |
conditions.max_sky_light | integer | 15 | Maximum raw sky light, 0–15; at least min_sky_light. |
conditions.min_block_light | integer | 0 | Minimum block light, 0–15. |
conditions.max_block_light | integer | 15 | Maximum block light, 0–15; at least min_block_light. |
conditions.time_start | integer | 0 | Inclusive start, 0–23999 ticks within a 24000-tick day (1200 seconds). A start later than the end wraps across midnight. |
conditions.time_end | integer | 23999 | Inclusive end, 0–23999 ticks. Equal endpoints select one tick per day. |
conditions.ground_tag | identifier | "" | Block tag ID without # for the block directly below the candidate. Empty disables this test. |
Full example
The bundled cave rule adds size-weighted slimes only in tagged, dark cave habitats. It runs after the bundled rule that removes the old biome slime entries.
Both cave and surface slime rules use spawn_chance: 0.60: 60% of selected slime encounters proceed, suppressing 40% before the remaining checks. This does not guarantee a matching reduction in the live population, which still depends on caps and available positions. Weights and group sizes remain separate controls; a zero group-size roll can still skip an encounter that passes the chance check.
{
"kind": "rule",
"group": "monster",
"spawn_chance": 0.60,
"dimensions": [
"minecraft:overworld"
],
"priority": 10,
"conditions": {
"biomes": [
"#isekaiexpansion:cave_slime_habitats"
],
"habitat": "cave",
"max_light": 7
},
"entries": [
{
"entity": "minecraft:slime",
"weight": 10,
"slime_size": 1,
"local_limit": 4,
"local_radius": 48
},
{
"entity": "minecraft:slime",
"weight": 4,
"slime_size": 2,
"local_limit": 4,
"local_radius": 48
},
{
"entity": "minecraft:slime",
"weight": 2,
"slime_size": 4,
"local_limit": 4,
"local_radius": 48
}
]
}
Validation
Missing required fields, unknown keys, wrong JSON types, non-finite or fractional integer values, invalid identifiers, unknown entity types, cross-group entity entries and invalid ranges reject the entire natural-spawning reload. Empty files are invalid; an empty rule entry list is valid. At most 256 definition resources are accepted. No legacy field names or aliases are read.
Biome and block tags are resolved against the live world at query time. A syntactically valid unknown biome or tag matches nothing; an unknown dimension receives no attempts. Two entries for the same entity remain separate weighted entries unless a later rule removes that type. A later merge rule can add entries after a replace rule.
Restrictions remain conjunctive: a water entry still needs its aquatic spawn restriction, and a hostile entity that requires darkness does not become a daylight spawner merely because max_light permits it. Ordinary slimes have their own redesigned spawn predicate. Local limits query loaded entities only; they do not load chunks or remove existing mobs. Structure and externally substituted pools pass through unchanged.
Reloading
The server reads definitions at resource reload and /reload, then swaps one validated snapshot. Clients do not choose entries or receive this rule database. Removing a definition removes its effect on the next successful reload. Existing entities keep their state. Invalid definitions retain the prior natural-spawning snapshot; this does not promise rollback of other mods’ reload listeners.
Use /ise ecology inspect creature or /ise ecology inspect monster with permission level 2 to inspect current rules and caps. Biome tag changes take effect through the normal datapack tag reload.
Each entry reports its effective spawn-chance; inspection and pool queries never roll it.
Related
Natural spawning lists defaults, slimes explains encounters and natural spawning runtime describes the implementation boundaries.