02 – Spawn Configuration Guide (TOML)

Besides the trades (JSON), the mod can be tweaked in the config/visitingvillagers-common.toml file, in 4 categories. The easiest way to edit it is the Config button in the mod list — Forge opens the native slider screens (one root screen + one per category); editing the .toml directly also works.

All 10 keys are integers with a min–max range. The file is generated with the defaults on first launch; the limits are shown in the .toml comments and in the slider screens.

 

1. General Settings

2. Adult Visitors

3. Baby Visitors

4. Wandering Visitors

How the Spawn Decides

Everything works in check cycles: every spawnCheckIntervalSeconds seconds (converted to ticks), the server collects what exists in the area around the player — villagers, golems, existing visitors — and decides who is born. Nothing spawns outside this window; the larger the interval, the more you feel spawns arriving in “batches”.

One village, three cascading triggers

1. The village must be established — everything depends on the two population keys: villagers ≥ minVillagersForSpawn and golems ≥ minGolemsForSpawn. Without that, no visitor type appears at all.
2. Adults — the village cap is max visitors = villagers × visitorSpawnPercentage ÷ 100. With a slot open and the right time of day, the mod spawns min(remaining slots, maxSpawnsPerCycle) per cycle, near a villager. Babies come next: max babies = adults × babySpawnPercentage ÷ 100, as long as adults ≥ minAdultsForBaby — they are born near an adult visitor.
3. Wanderers — they follow the same village requirement but are counted separately (maxWanderingVisitors simultaneously) and have their own delay: wanderingSpawnDelaySeconds must pass between attempts. The clock is stamped at the moment of the attempt even if it fails — spawn happens near an Iron Golem, one at a time.

Time of day (fixed rule)

• Visitors and babies: only while the sun is up (between sunrise and midday of the day cycle).
• Wanderers: arrive a bit later, after the visitors.

Example with the default values

Village with 10 villagers and 1 golem:

• Requirement: 10 ≥ 6 villagers and 1 ≥ 1 golem ✔ — the village is enabled.
• Adults: 10 × 100% = up to 10 visitors, arriving 3 per cycle of 10 s — the village can fill up within minutes.
• Babies: from 2 adults onward, adults × 60% sets the cap — with 5 adult visitors, up to 3 babies playing around the village.
• Wanderers: up to 2 at once, with at least 2 minutes between attempts.

Fixed rules (not configurable)

• Spawning only happens during the day (visitors at sunrise, wanderers a bit later) and on blocks with the tag visitingvillagers:visitors_spawnable_on.
• Babies don’t trade — they just play with each other.
• Visitors are born with the trade pool of their variant; the default visitor only has trades if it passes the defaultVisitorTradeChance roll.

🩺 My village doesn’t spawn — checklist

Before touching the sliders, check in order:

1. Population: are there enough villagers and golems within the area of the player watching the village? The check is local to the player, not global to the world.
2. Time of day: is it between sunrise and midday? From afternoon through night, no one arrives.
3. Ground: is the spawn spot on a block with the visitingvillagers:visitors_spawnable_on tag (grass and similar)?
4. Config reloaded: changes to the .toml require restarting the server (this config has no in-game reload — only the trade JSONs do).
5. Number expectations: with defaults, a village of 4 villagers doesn’t spawn anything yet (4 < 6). That’s a feature, not a bug.