01. Visiting Villagers – Mechanics and Entities
This page details the entities introduced by Visiting Villagers, their visual variants, AI behaviors, their organic life cycle within Minecraft villages, and the population inspection tools [1, 2].
👥 The 3 Visitor Entities
The mod replaces the static population with three entity types with well-defined roles and dynamics [2]:
1. Adults (VisitorEntity)
- Role: Professional visitors that arrive at villages to perform trades with the player [2].
- Visual Variants: They have 14 themed variants + the default variant [2]. Full list (in-game names): Miner (miner), Beekeeper (beekeeper), Lumberjack (lumberjack), Good Pillager (good_pillager), Glassworker (glassworker), Railwright (railwright), Piglin Trader (piglin_trader), Beachcomber (beachcomber), Mycologist (mycologist), Redstone Engineer (redstone_engineer), Pyrotechnic (pyrotechnic), Relic Scavenger (relic_scavenger), EnchantSmith (enchant_smith) and Hunter (hunter).
ℹ️ The name in parentheses is the key used in the trade JSON files and texture IDs. The EnchantSmith variant uses the
enchant_smithkey (without the “s” separator).
- Trade Catalog: Each variant has its own JSON file of offers. Even two NPCs of the same variant receive randomly shuffled offers on each visit [2].
- Trade Interaction: They have configurable buy and sell offers and can follow the player to workstations [2, 3].
2. Babies (BabyVisitorEntity)
- Role: Add immersion and community life to village and town squares [2].
- Organic Birth: They only start appearing when the village reaches a minimum number of settled adult visitors [2].
- Behavior: They play with each other, emit characteristic ambient sounds, and run around villages [1, 2].
- Trade Restriction: They do not perform trades under any circumstances [2, 4].
3. Wanderers (WanderingVisitorEntity)
- Role: Rare travelers that appear according to the biome in which the village is located [2].
- Biome Variants (8 total): Plains Wanderer (
wandering_plains), Forest Wanderer (wandering_forest), Cave Wanderer (wandering_cave), Mountain Wanderer (wandering_mountain), Snow Wanderer (wandering_snow), Swamp Wanderer (wandering_swamp), Desert Wanderer (wandering_desert) and the rare Master Wanderer (wandering_master) [2]. - Resources and Animals: They carry thematic resources from their home biomes and may appear accompanied by animals (such as horses, wolves, and donkeys) [1, 2].
🧠 Behaviors and AI (AI Goals)
Visitors use a set of 9 custom Artificial Intelligence routines to interact with the environment and the player [1, 3]:
| AI Goal | Type | Behavior Description |
|---|---|---|
FollowTradingPlayerGoal | Interaction | Makes the visitor follow the player to workstations after negotiations [3]. |
ShowTradesToPlayerGoal | Interaction | Displays the interface and trade offers when interacting with the player [3]. |
PlayWithOthersGoal | Social | Controls playtime and joint movement between baby visitors [2]. |
GoToPoiGoal | Navigation | Directs visitors to points of interest (POIs) in the village. |
GoToTaggedBlockGoal | Navigation | Guides movement toward blocks marked with preference tags. |
JumpToBlockGoal | Navigation | Assists transition and jumping over specific blocks. |
DespawnAtDayGoal | Life Cycle | Manages the stay duration and departure of specific daytime visitors [3]. |
DespawnAtNightGoal | Life Cycle | Ensures visitors withdraw when night falls [3]. |
DespawnWhenPlayerSleepsGoal | Cleanup | Removes visitors and clears instances when the player sleeps [3]. |
🧰 Mod Items and Creative Tab
The mod adds 5 usable items, all concentrated in its own creative tab, plus one internal item used only as the tab icon [1]. None of them are craftable at a crafting table — they are available in creative mode and for administrators via /give [1].
Item Table
| Item (in-game name) | ID | Type | Function | Stackable |
|---|---|---|---|---|
| Villager Visitor Spawn Egg | visitor_spawn_egg | Spawn Egg | Summons an adult Visitor with a random variant | Yes (64) |
| Baby Villager Visitor Spawn Egg | baby_visitor_spawn_egg | Spawn Egg | Summons a baby Visitor | Yes (64) |
| Wandering Villager Visitor Spawn Egg | wandering_visitor_spawn_egg | Spawn Egg | Summons a Wanderer with a random biome variant | Yes (64) |
| Visitor Checker (Chat) | visitor_checker_chat | Tool | Prints the village population report in chat (residents, iron golems, and capacity for new visitors) | Yes (64) |
| Visitor Checker (Book) | visitor_checker | Tool | Generates a signed book with the full village report, delivered directly to the hand | No (1) |
Note: there is a sixth internally registered item, tab_icon (Visiting Villagers Icon), which does not appear in the creative tab and cannot be obtained in-game — it exists only to serve as the mod tab’s icon [1].
🎨 Creative Tab
The mod creates its own tab in the creative menu, named “Visiting Villagers”, with an exclusive icon [1]:
- Items in the tab (in this order): visitor spawn egg → baby spawn egg → wanderer spawn egg →
visitor_checker_chat→visitor_checker[1]. - Spawn egg usage: they work like vanilla eggs — right-click on a valid block (preferably those with the
#visitingvillagers:visitors_spawnable_ontag) to summon the entity immediately [1]. - Tool usage: right-click with the item in hand to get the diagnosis of the village you are in [1]:
- Visitor Checker (Chat): prints the report to chat instantly, without altering the item.
- Visitor Checker (Book): the held item is replaced by a written book (“Visitor Check Report”, with enchantment glint) containing the full report, which can be read like any vanilla book. The original item is not returned — use the book or grab another checker from the creative tab.
The tab is useful for administrators and mapmakers who want to place visitors manually without relying on the organic spawning configured in the spawn configuration [1].
🌅 Life Cycle and Night Dispersion
☀️ Daytime Routine and Timings
- Visitor Arrival: The appearance of adult and baby visitors happens exclusively during the daytime period (between 500 and 12000 ticks) [4, 5].
- Wanderer Arrival: Wanderers arrive a bit later in the daytime cycle (starting at tick 1500) [5].
- Spawn Blocks: All visitors appear on valid blocks marked with the
#visitingvillagers:visitors_spawnable_ontag (such as grass and similar natural blocks) [1, 4].
🌙 Night Dispersion
- Organic Withdrawal: At dusk and during the night, visitors wrap up their activities and begin the natural dispersion and removal process [3].
- Cleanup on Sleep: If the player sleeps to pass the night, the cleanup routine is triggered instantly, renewing the village for the next daytime cycle [3].