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

01 – Intro Mod Visiting Villager

Posted
Updated
ByRed

Welcome to the official documentation for Visiting Villagers!

Visiting Villagers is a mod for Minecraft 1.21.1 (Forge) that turns villages generated across the world into living, thriving communities full of movement.

Forget static villages where villagers wander aimlessly. With this mod, the world comes to life: new visitors arrive, settle in, do business, and start families — interacting with the player and with the village itself.

 

How Does the Mod Work?

The mod’s main goal is to bring villages to life while staying fully integrated with the game’s progression. Here are its core pillars:

1. Organic Spawn System

The NPCs don’t just appear out of thin air; the world monitors your village’s growth.

  • Growth Requirements: For visitors to start appearing, the village must meet basic population prerequisites — a minimum number of villagers and Iron Golems (defaults: 6 villagers + 1 golem). Nothing happens in the first cycles; as the village grows, visitors start arriving on their own.
  • Life Cycle: The mod introduces three new main entities:
    • Adult Visitors (VisitorEntity): They arrive at villages with varied professions and skins (14 themed visual variants + the default one, from the miner to the piglin dealer). Each variant has its own trade catalog — and even two NPCs of the same variant can get different shuffled offers.
    • Visitor Babies (BabyVisitorEntity): They add extra immersion to the environment, playing with each other, making sounds, and bringing life to village squares. They are only born after the village already has established adult visitors — and they don’t trade.
    • Wanderers (WanderingVisitorEntity): Rare travelers who appear based on the village’s biome (plains, forest, cave, mountain, snow, swamp, desert) and bring themed resources from wherever they came from — diamonds, enchanted books, axolotl buckets, echo shards… The Wandering Master is the rich, rare version of this group.

 

2. Smart AI Behavior

Visitors react to their surroundings through advanced AI goals:

  • Follow the Player: They can follow the player to specific workstations — gratitude from a merchant who just made a good deal.
  • Dynamic Trading System: You can interact with them to close deals. Offers are shuffled from the variant’s catalog and restock just like any vanilla trade.
  • Natural Routine: They arrive during the day, eat, sneak out at night, and have cleanup and dispersal routines based on the time of day or when the player goes to sleep.

 

3. 100% Customizable Trade Sources (JSON)

Want to change what visitors buy or sell? The mod uses a robust system based on JSON files (config/visitingvillagers/trades/), one for each NPC variant:

  • The 23 default files come bundled with the mod and are copied to the config folder on first launch — edit any of them as you like.
  • It supports fixed items (with vanilla data components: enchantments, names, damage…), dynamic families (wood types, dyes, pottery sherds…), and shuffling (family / one_of).
  • Changes can be applied on the fly with the /visitors reloadtrades command right in the server chat, no restart needed.

 

Where to Start?

Explore the detailed guides in our documentation to master every setting:

  1. ⚙️ Spawn Configuration Guide (TOML) — Learn how to fine-tune rates, timing, intervals, and the rules that decide when visitors appear on your server.
  2. 📄 Trade Configuration Guide (JSON) — Understand the structure of trade files, the special types, and how to create custom offers.
  3. 💡 Examples Guide — Practical, ready-to-copy examples pulled straight from the mod’s own files.