Configuration

Villager Overhaul uses a server config file for module toggles, prices, ranges, stats, chat, respawning, and balancing.

Most gameplay-sensitive behavior is server-authoritative.

Note

Server config reloads on config loading/reloading events. Existing villagers keep their saved stats and data; config changes affect how those values are interpreted.

Module Toggles

Setting	Default	What It Controls
`enableMerchantModule`	`true`	Rerolls, locks, auto-search, auto-trade, manual trading, and Trading Hall features.
`enableCombatModule`	`true`	Combat modes, combat stats, loadouts, and combat AI.
`enableFarmingModule`	`true`	Deposit, withdraw, and manual farming.

Chat

Setting	Default	Range	Notes
`localizedChatEnabled`	`true` in spec	boolean	Localized 3D chat.
`localizedChatRange`	`26`	`1-256`	Normal chat range.
`shoutEnabled`	`true` in spec	boolean	Enables shout prefix.
`shoutHungerCost`	`4` in spec	`0-20`	Food points consumed by shouts.
`shoutPrefix`	`!`	first char	Server-wide shout.
`whisperEnabled`	`true` in spec	boolean	Enables whisper prefix.
`whisperRange`	`3`	`1-64`	Whisper range.
`whisperPrefix`	`#`	first char	Local whisper.
`chatRadius`	`26`	`1-128`	Custom Commands trigger radius.

Technical note: runtime fallback

Some runtime fields have conservative defaults before config reload. The server config values are the values to edit.

Cost and Payment

Setting	Default	Notes
`itemOrTag`	`minecraft:emerald`	Exact item id or item tag such as `#minecraft:logs`.
`preferWallet`	`true`	Prefer Lightman's Currency wallet when possible.
`autoPreferLCIfPresent`	`true`	Can switch default emerald cost to Lightman's emerald coin.
`freeOffers`	`2`	Number of offers that do not add reroll cost.
`costPerOffer`	`8`	Cost per paid offer.
`maxDeductibleLockedOffers`	`1`	Legacy/preview config concept; manual source cost uses actual unlocked offers.
`autoHourlyThreshold`	`6`	Auto-search hourly scaling threshold.
`autoHourlyDiscountOrIncreasePct`	`5.0`	Percent change per threshold step.
`enableMaxAutoSearchCost`	`false`	Enables settlement clamp.
`maxAutoSearchCostMultiplier`	`10.0`	Clamp multiplier when enabled.

Recruitment and Respawn

Setting	Default	Notes
`recruitCostMin`	`8`	Minimum normalized recruit cost.
`recruitCostMax`	`64`	Maximum normalized recruit cost.
`respawnCostMultiplier`	`2.0`	Multiplies recruit cost at death.
`respawnKeepEquipment`	`false`	Restores hands and armor from respawn snapshot.
`respawnKeepInventory`	`true`	Restores villager internal inventory from respawn snapshot.

Merchant Limits and XP

Setting	Default	Notes
`cooldownTicks`	`100`	Manual reroll cooldown. `0` disables the cooldown gate.
`cooldownTicksAuto`	`600`	Auto-search reroll cooldown.
`perVillagerDaily`	`0`	Daily reroll cap per villager. `0` disables it.
`allowAfterTradeUsed`	`true`	Allows rerolling after trades have been used.
`manualRerollXpPerOffer`	`1.0`	Base XP per rerolled offer.
`autoSearchXpPerOffer`	`0.1`	Base XP per auto-search rerolled offer per successful reroll.

Farming

Setting	Default	Notes
`farmingHarvestItemsPerXp`	`10`	Planted item progress needed per XP payout.
`farmingHarvestXp`	`1`	XP awarded per completed progress unit.
`manualFarmBaseRange`	`10`	Base max manual farming range before Ranger.
`manualFarmWorkStartTick`	`2000`	Start of manual farming work window.
`manualFarmWorkEndTick`	`9000`	End of manual farming work window.
`plantWhispererIntervalSeconds`	`60`	Passive Plant Whisperer check interval.
`plantWhispererBaseChancePct`	`50.0`	Base chance per interval.

Stat Ranges

Stats are stored as points from -100 to 100. Config ranges decide what those points mean.

Merchant Stats

Range	Default Min	Default Max
Generosity percent	`-20.0`	`20.0`
Timeliness percent	`-20.0`	`20.0`
Intellect percent	`-20.0`	`20.0`
Hoarder extra offers	`-3`	`3`

Farming Stats

Range	Default Min	Default Max
Motivation percent	`-20.0`	`20.0`
Efficiency percent	`-20.0`	`20.0`
Plant Whisperer percent	`-20.0`	`20.0`
Ranger percent	`-20.0`	`20.0`
Breeding stat mutation chance	`10.0`	`10.0`

Combat Stats

Range	Default Min	Default Max	Unit
Vitality	`-6.0`	`10.0`	Max health additive value.
Agility	`-0.02`	`0.03`	Movement speed additive value.
Strength	`-1.0`	`3.0`	Attack damage additive value.
Armor	`-5.0`	`15.0`	Armor additive value.

Combat AI Settings

Combat AI toggles such as blocking, eating, circling, eat force hits, and eat max resets are saved through combat settings rather than the main server config.

Use:

Per-villager Combat Settings for one villager.
Global Combat Settings for a reusable template.
Sync to copy the global template onto a villager.

Balancing Advice

Increase costPerOffer if rerolling replaces ordinary villager progression too quickly.
Increase cooldownTicksAuto if auto-search feels too fast.
Keep manualFarmBaseRange modest unless you want each farmer to cover a very large area.
Use stat ranges instead of rerolling stats if you want a server-wide balance change.
Enable max auto-search cost if you want long searches to have a hard ceiling.

Deep dive: percent directions

Generosity and Timeliness are discount-style stats: positive values reduce cost or cooldown.

Intellect is multiplier-style: positive values increase XP.

Motivation scales the farming work window length around its midpoint.

Efficiency is chance-based: positive can save seeds/bonemeal, negative can consume extra.