How can we help?
04. Visiting Villagers – Compatibility and Commands
This page centralizes the technical specifications of Visiting Villagers, the server-side security architecture, the fallback resilience system, and the administration command reference [2, 3].
💻 Technical Specifications and Requirements
The mod was developed for the Minecraft 1.21.1 Forge ecosystem [4, 5]:
| Requirement | Supported Version | Notes |
|---|---|---|
| Minecraft | 1.21.1 | Compatible with the [1.21.1, 1.22) range [5] |
| Mod Loader | Forge 52.1.0+ | Requires Forge 52.1.0 or higher [5] |
| Java (JDK) | Java 21 | Mandatory requirement of Minecraft 1.21.1 [5] |
| Architecture | Server-Side Dominant | Trade and spawn logic processed on the server [6, 7] |
🔒 Architecture, Compatibility and Security
1. Native Server-Side Processing
- Vanilla Networking: Trade offers generated from the JSON files are loaded on the server during
ServerStartingEventand sent to the client via the base game’s standardMerchantOffersnetwork packets [6-8]. - No Special Client Requirements: Trade tables require no client-side processing, ensuring lightness and security [7].
2. Data Components Support (1.21.1)
- Native Codec (
ItemStack.CODEC): Full integration with the 1.21.1 Data Components system, allowing you to configure enchantments, custom names, durability, and potion effects [9-11].
3. Early Validation and Fallback System
- Boot and Reload Verification: During server startup or when running
/visitors reloadtrades, theTradeJsonLoadervalidates all files againstBuiltInRegistries.ITEMand checks thatcountvalues are within the allowed range (1–99) [12-14]. - Crash Protection (Fallback): If a JSON file contains a syntax error, non-existent ID, or property conflict, the mod logs a detailed warning (
WARNING), discards only the affected variant, and applies the automatic reversal (fallback) to the default JSON file embedded in the.jar[12, 13, 15].
💻 Administration Command Table (/visitors)
The mod has an integrated command system under the /visitors prefix for population management, testing, and configuration reload without needing to restart the server [3, 16]:
| Command | Permission Level | Scope / Parameters | Action Description |
|---|---|---|---|
/visitors check | Player (Everyone) | Fixed radius of 128 blocks | Prints a chat report with the count of villagers, golems, and visitors in the area [16]. |
/visitors clear <radius> | Level 2 (OP) | <radius>: 1–512 blocks | Instantly removes all visitors (VisitorEntity, BabyVisitorEntity, WanderingVisitorEntity) in the area [16]. |
/visitors population <amount> <radius> | Level 2 (OP) | <amount>: 1–250<radius>: 10–500 blocks | Controlled invocation for testing. Spawns the requested number of visitors distributed within the defined radius [16]. |
/visitors reloadtrades | Level 2 (OP) | Global (Server) | Reloads and revalidates the JSON files in config/visitingvillagers/trades/ and clears the active offers of NPCs that are not currently trading [16, 17]. |
🧪 In-Game Inspection Tools (Visitor Checker)
In addition to chat commands, the mod includes two utility items for population verification:
- 💬 Visitor Checker (Chat): prints the local village report to chat.
- 📖 Visitor Checker (Book): generates a signed book (“Visitor Check Report”) with the full report in the player’s hand.
Full item details (usage, stacking, creative tab, and spawn eggs) are on the 01. Mechanics and Entities page.