Skip to main content
How can we help?
Table of Contents
< All Topics
Print

02. Visiting Villagers – Spawn Configuration Guide (TOML)

This page details how to customize visitor spawning in Visiting Villagers through the TOML configuration file or the game’s native screens.

📂 Configuration File and Access

Spawn configurations are located in: config/visitingvillagers-common.toml

Editing Methods

  1. Via In-Game Menu (Forge): Click the Config button in the mods list to open the 5 slider screens (1 root screen + 4 submenus split by category).
  2. Direct File Editing: Open the visitingvillagers-common.toml file in any text editor.

⚠️Important: Changes to the .toml file require a server or game restart to take effect. Unlike the JSON trade files, the spawn system has no real-time reload.

📋 The 4 Categories and 10 Configuration Keys

All 10 keys use integer (integer) values with defined minimum and maximum limits (min–max).

1. General Settings (General Settings)

Defines the global rules for visitors being attracted to the village.

KeyDefaultRangeEffect Description
spawnCheckIntervalSeconds101–60Interval in seconds between spawn checks around the player.
minVillagersForSpawn61–100Minimum number of settled villagers in the village to allow visitors to arrive.
minGolemsForSpawn10–50Minimum number of Iron Golems in the village to allow visitors to appear.

2. Adult Visitors (Adult Visitors)

Controls the population cap and the arrival rate of adult traders (VisitorEntity).

KeyDefaultRangeEffect Description
visitorSpawnPercentage1000–100Percentage of the village population used to define the maximum cap of adult visitors (e.g.: 100% = 1 adult visitor per villager).
maxSpawnsPerCycle31–10Maximum number of adults that can appear in a single check.
defaultVisitorTradeChance400–100Chance (%) of a default variant visitor having a trade catalog.

3. Baby Visitors (Baby Visitors)

Regulates the birth and amount of playful children (BabyVisitorEntity).

KeyDefaultRangeEffect Description
minAdultsForBaby21–10Minimum number of settled adult visitors in the village before babies start appearing.
babySpawnPercentage600–100Percentage relative to the number of adults that determines the maximum cap of babies (e.g.: 60% = up to 3 babies for 5 adults).

4. Wandering Visitors (Wandering Visitors)

Adjusts the presence of rare biome travelers (WanderingVisitorEntity).

KeyDefaultRangeEffect Description
maxWanderingVisitors20–10Maximum number of wanderers present simultaneously in the world/area.
wanderingSpawnDelaySeconds12010–600Waiting time (in seconds) between wanderer spawn attempts.

🧠 How the Spawn Algorithm Works

The server runs the decision cycle every spawnCheckIntervalSeconds in the area around the player, following three cascading triggers:

  1. Established Village Trigger: The mod checks whether the local village meets the minimum number of villagers (minVillagersForSpawn) and the minimum number of golems (minGolemsForSpawn). If the village does not meet both requirements, no visitor is generated.
  2. Adults and Babies Trigger:
    • Adult Cap: Cap = (Villagers × visitorSpawnPercentage) / 100. If there is room, the mod generates up to maxSpawnsPerCycle adults per cycle, near a villager.
    • Baby Cap: When Adults ≥ minAdultsForBaby, the cap is computed as (Adults × babySpawnPercentage) / 100. Babies appear near an adult visitor.
  3. Wanderer Trigger: Computed separately (respecting the maxWanderingVisitors limit). Each attempt happens after the time defined in wanderingSpawnDelaySeconds, and the spawn always occurs near an Iron Golem.

Fixed Spawn Rules

  • Daytime Period: Adult and baby visitors appear exclusively during the day (between 500 and 12000 ticks). Wanderers appear slightly later in the cycle (starting at tick 1500).
  • Valid Surface: Spawning only occurs on natural blocks marked with the #visitingvillagers:visitors_spawnable_on tag (such as grass blocks).

🩺 Diagnostic Checklist (Visitors Not Appearing?)

If visitors are not appearing in the village, check the 5 points below before changing settings:

  1. Population Requirements: Check that there are enough villagers and golems in the area near the player. The calculation is local relative to the player, not global on the map.
  2. Time of Day: Make sure it is daytime (between sunrise and noon). During the afternoon, night, or storms, spawning is blocked.
  3. Spawn Block: Ensure there are valid, unobstructed grass/dirt blocks in the village (tag visitors_spawnable_on).
  4. Server Restart: Remember to restart the server/game after editing the visitingvillagers-common.toml file.
  5. Small Village: With default values, a village with only 4 villagers does not meet the minimum requirement (4 < 6) and will not generate visitors.