General Systems

General systems are the shared foundation under the merchant, farming, combat, and command modules.

Recruitment

Recruiting turns a villager into a managed villager owned by you.

Recruitment unlocks owner-only controls.
Recruitment cost is computed from the villager's enabled module stats and normalized between the server's min and max recruit cost.
Recruited villagers keep their Villager Overhaul data in persistent entity data.
Combat, farming, merchant, history, respawn, and custom-command systems all check the recruited state.

tip

A villager can be valuable even before it has the exact trades you want. Stats affect long-term cost, farming, and combat behavior.

Movement Modes

Villagers can be moved between several high-level behavior states.

Mode	Behavior
Neutral	Lets the villager behave closest to vanilla, while still keeping Villager Overhaul data.
Idle	Keeps the villager under manual control and stops ordinary wandering.
Follow	Follows the owning player.
Patrol	Walks a saved patrol route.
Trading	Uses a registered Trading Hall setup.
Manual Farming	Lets the farming module control movement and farm tasks.

Combat can temporarily take over movement. When a fight ends, the villager returns to the previous relevant behavior where possible.

Names, Gender, and Family Tree

Villager Overhaul tracks identity information for villagers.

Villagers can receive generated first and last names.
Gender data is stored with the villager.
Family tree data stores relationships, names, gender, and stat snapshots.
Children can inherit stats from parents.

Deep dive: inherited stats

A child inherits each stat from one of its parents, then applies a small random variance controlled by server config.

If variance is enabled and rounding would produce the exact same value, the inherited value is nudged by 1 point so the child is not a perfect clone.

History

Each recruited villager tracks a history record. The history is not just a summary; it is fed by gameplay events across the modules.

Tracked examples include:

Time alive and distance moved.
Hits, damage, kills, deaths, food eaten, and healing.
Merchant screen opens, completed trades, manual rerolls, auto rerolls, trade lock toggles, and emeralds earned from trading systems.
Farming planted, harvested, bonemealed, deposited, and withdrawn counts, split between manual and neutral farming where relevant.
Patrol routes and other management events.

Localized Chat

Villager Overhaul includes localized chat behavior that also keeps chat commands working.

Chat Type	Trigger	Range / Behavior
Normal	No prefix	Sent only to players in the configured 3D chat range and same dimension.
Shout	Default `!` prefix	Server-wide, orange, and can cost hunger.
Whisper	Default `#` prefix	Short range, gray italics.

Prefixes are stripped before Villager Overhaul checks custom command triggers.

Note

Server config keeps only the first character of the shout and whisper prefixes. Empty prefixes fall back to the defaults.

Respawning

When a recruited villager dies, Villager Overhaul can save a respawn snapshot.

Hold an emerald in your main hand.
Use a Respawn Anchor.
Choose the saved villager.
Pay the respawn cost.

Respawn cost is based on the villager's recruit cost at death, multiplied by the server respawn multiplier.

Setting	Behavior
Keep inventory	Restores the villager's internal inventory when enabled.
Keep equipment	Restores hand and armor equipment when enabled.
Purge	Removes saved respawn data for villagers you no longer want to restore.

Trading Hall

The Trading Hall block is a 27-slot container with a separate stored emerald balance.

It can be registered to a villager for trading behavior.
It must be in the same dimension.
It must be close to the villager's job-site anchor or current villager position.
Horizontal range is 16 blocks.
Vertical tolerance is 4 blocks.
Breaking it drops both inventory contents and stored emeralds.
It outputs a redstone comparator signal based on container fullness.

Recipe

→

White carpet fills the top row. Any plank type fills the middle row and the two bottom corners.

Trading Hall

Register the block from the villager commands radial, then keep it near the villager's job-site area. The block stores trade inventory separately from its emerald payout balance.

Emerald pile clicked: payout collected

Emerald Payout

Stored emeralds are collected by clicking the visible emerald pile area on the block.

If EZ Emerald Pouch is available, payout can go into the pouch.
Otherwise emeralds go to the player inventory.
If inventory cannot accept them, they drop at the player.

Admin Commands

Command	Permission	What It Does
`/vo_takeheld [radius]`	2	Takes the nearest villager's held main/offhand items into the player's inventory if there is room. Default radius is `16`.
`/vo_fixgenprices [radius]`	2	Recalculates nearby villager trade prices from Generosity only and clears other discounts. Default radius is `32`.

Technical note: price fixing

/vo_fixgenprices is meant as a recovery/admin tool. It normalizes generated prices from Villager Overhaul's Generosity system instead of preserving every temporary discount source.