Configuration

Every Mercantile setting, organized by section. Tune via the Mod Menu + Cloth Config GUI or by hand-editing the JSON file.

File Location & Reload

The config file is generated on first launch at:

.minecraft/config/mercantile.json

Server operators can apply changes without a restart with:

/mercantile reload

Missing keys are filled with defaults and saved. Unknown keys are ignored. All numeric values are clamped on load — out-of-range hand edits are silently corrected.

Server Config

Server-side settings that affect gameplay rules. Synced to clients via the ConfigSyncS2CPayload on join and after /mercantile reload.

Pickup

Key	Type	Default	Range	Description
`enableVillagerPickup`	boolean	true	—	Master toggle for villager pickup feature.
`pickupXpCost`	int	5	0+	XP levels deducted per pickup (creative waived).

Names

Key	Type	Default	Range	Description
`enableNames`	boolean	true	—	Auto-assign biome-themed names on villager spawn.

Trade Cycling

Key	Type	Default	Range	Description
`enableTradeCycling`	boolean	true	—	Show the "Re-roll Trades" button in the merchant GUI.
`tradeCycleEmeraldCost`	int	6	0+	Emeralds consumed per cycle (creative waived).

Reputation

Key	Type	Default	Range	Description
`enableReputation`	boolean	true	—	Master toggle for the reputation system (score, tiers, exclusive trades).
`reputationTradeGain`	int	1	0+	Score gained per trade-gain pulse (every `reputationTradesPerGain`-th completed trade).
`reputationCureGain`	int	5	0+	Score gained per cured zombie villager (one-time per UUID).
`reputationAttackLoss`	int	15	0+	Score lost per villager attack (absolute value).
`reputationKillLoss`	int	40	0+	Score lost per villager kill (absolute value).
`reputationCycleGain`	int	1	0+	Score gained per trade cycle.
`reputationDailyCap`	int	5	1–50	Maximum total reputation earnable per in-game day from trades and cycles combined. Daily counters reset at day rollover.
`reputationTradesPerGain`	int	5	1–20	Completed trades required to trigger one trade-gain pulse.
`reputationDailyMaxTradeRep`	int	2	1–10	Daily cap on reputation earned from trading.
`reputationDailyMaxCycleRep`	int	1	1–10	Daily cap on reputation earned from trade cycling.
`enableRaidReputation`	boolean	true	—	Grant reputation to players vanilla awards Hero of the Village for defending a raid.
`reputationRaidWinGain`	int	10	0+	Reputation granted for winning a raid. Bypasses the daily cap, like the cure bonus.
`enableWanderingTraderRep`	boolean	true	—	Offer a wandering trader a bonus trade at Trusted tier and above (one sticky offer per trader).
`enableGifting`	boolean	true	—	Allow villagers to accept profession-matched item gifts for reputation. Gated behind `enableReputation`.
`reputationGiftGain`	int	1	0+	Score gained per accepted gift item.
`reputationDailyMaxGiftRep`	int	2	1–10	Daily cap on reputation earned from gifting (also counts against `reputationDailyCap`).
`reputationNegativeDecayPerDay`	int	1	0+	Points a negative reputation recovers toward 0 each in-game day. `0` disables decay; positive scores are never affected.
`enableGratitudeGifts`	boolean	true	—	Honored-tier players occasionally receive a thrown, profession-flavored gift from a nearby villager — the inverse of gifting. Gated behind `enableReputation`.
`gratitudeGiftsPerDay`	int	1	0–10	Daily cap on gratitude gifts a player can receive. `0` disables gifts without turning off the feature flag.
`enableNitwitRehab`	boolean	true	—	Trusted+ players can rehabilitate an adult nitwit into an unemployed villager with a golden apple plus an emerald fee. With `enableReputation` off the tier gate is skipped and only the cost applies.
`nitwitRehabEmeraldCost`	int	16	0+	Emeralds drawn from the player's inventory per rehabilitation, on top of the golden apple (creative waived; `0` makes the apple the only cost).

Delivery Contracts

Key	Type	Default	Range	Description
`enableContracts`	boolean	true	—	Employed villagers occasionally offer delivery contracts: sneak + use paper to sign, deliver the goods before the deadline, earn emeralds plus cap-bypassing reputation. Requires `enableReputation`.
`contractOfferChance`	int	50	0–100	Percent chance per eligible villager per in-game day of a new offer appearing (`0` stops new offers; outstanding contracts still settle).
`contractPaymentScale`	int	100	0–1000	Emerald payments as a percent of the data-driven pool values (`100` = as authored).
`contractRepGain`	int	3	0+	Reputation per completed delivery. Bypasses the daily cap and sub-caps, like curing and raid defense.
`contractRepPerDay`	int	3	0–50	Deliveries per day that earn the reputation bonus — the bound that keeps the cap bypass from scaling with villager count. Later deliveries still pay emeralds; `0` disables contract rep entirely.
`contractDeadlineDays`	int	2	1–30	In-game days between signing a contract and its deadline. Expired contracts vanish from the inventory with no penalty.

Follow Mode

Key	Type	Default	Range	Description
`enableFollowMode`	boolean	true	—	Sneak-right-click + emerald to recruit a villager to follow.
`maxFollowingVillagers`	int	3	1+	Maximum villagers one player may have following at once.
`enableSendHome`	boolean	true	—	When released, a villager walks back to its bed (or workstation) instead of stopping in place.

Pathfinding

Key	Type	Default	Range	Description
`enablePathfindingFixes`	boolean	true	—	Master toggle for all pathfinding improvements.
`enablePathfindingDoors`	boolean	true	—	Fence gate + double door navigation.
`enablePathfindingStairs`	boolean	true	—	Multi-step staircase + slab transitions.
`enablePathfindingLadders`	boolean	true	—	Allow villagers to climb ladders.
`enablePathfindingWater`	boolean	true	—	Penalize water paths so villagers prefer dry routes.

Bulk Trading

Key	Type	Default	Range	Description
`enableBulkTrading`	boolean	true	—	Shift-click trade output to repeat the trade up to 64 times.

Profession Lock

Key	Type	Default	Range	Description
`enableProfessionLock`	boolean	true	—	Permanently lock profession after any completed trade.

Work Orders

Key	Type	Default	Range	Description
`enableWorkOrders`	boolean	true	—	Sneak + right-click an unemployed adult villager with a workstation item to send it to claim the nearest unclaimed workstation of that type and take the profession.
`workOrderEmeraldCost`	int	1	0+	Emeralds drawn from the player's inventory per accepted work order (creative waived; denied orders are free). The workstation item is never consumed.

Healing

Key	Type	Default	Range	Description
`enableHealing`	boolean	true	—	Multiply splash/lingering heal + regen effects on villagers.
`healingMultiplier`	float	2.0	1.0 – 10.0	Multiplier applied to heal amount and regen duration.

Trade GUI

Key	Type	Default	Range	Description
`enableRestockIndicator`	boolean	true	—	Show restock timer + counter in the merchant screen.
`enableDemandTransparency`	boolean	true	—	Show hoverable price breakdown tooltip.

Trade Pinning

Key	Type	Default	Range	Description
`enableTradePinning`	boolean	true	—	Master toggle for pinning trades and restock notifications.
`maxPinnedTradesPerPlayer`	int	10	1–64	Cap on pinned trades each player may hold.
`pinRestockNotifyRange`	int	128	8–256	Max distance (blocks) between player and villager for a restock notification.

Breeding Tooltip

Key	Type	Default	Range	Description
`enableBreedingTooltip`	boolean	true	—	Send breeding data to Jade/WTHIT tooltips.

Baby Feeding

Key	Type	Default	Range	Description
`enableBabyFeeding`	boolean	true	—	Feed baby villagers villager food to speed up growth.
`babyFeedPercentPerFeed`	int	10	1 – 100	Percent of remaining growth time removed per bread fed; lower-value foods scale down proportionally.
`babyFeedMaxReductionPercent`	int	50	0 – 100	Cap on total growth time a single baby can have removed by feeding, as a percent of the full growth time.

State Indicators

Key	Type	Default	Range	Description
`enableStateIndicators`	boolean	true	—	Send contextual state icons (needs workstation, panicking, trading) to Jade/WTHIT.

Mood

Key	Type	Default	Range	Description
`enableMood`	boolean	true	—	Master toggle for the villager mood system — living conditions drive a 0–100 mood that nudges prices and restock speed.
`moodPriceModifierPercent`	int	5	0–50	Price nudge as a percent of base price: Happy villagers discount by this much, Miserable ones mark up. 0 disables the price effect.
`moodRestockSpeedPercent`	int	20	0–80	Restock interval change: Happy villagers restock this percent sooner, Miserable ones later. 0 disables the restock effect.
`moodRecalcIntervalTicks`	int	100	20–24000	Ticks between mood re-evaluations; mood drifts 2 points toward current conditions per interval.
`moodAmbientParticles`	boolean	true	—	Happy villagers occasionally emit happy particles; Miserable ones emit angry particles.

Market Day

Key	Type	Default	Range	Description
`enableMarketDay`	boolean	true	—	Master toggle for the recurring market day — a dawn-to-dusk window with discounted trades and an extra restock cycle.
`marketDayIntervalDays`	int	7	1–1000	In-game days between market days. The schedule is shared by the whole world; the first market day falls on this day number.
`marketDayDiscountPercent`	int	5	0–100	Discount on every trade during market day, as a percent of base price. Stacks with reputation, mood, and gossip; shows as its own line in the price breakdown. 0 disables the discount.

Memorials & Fear

Key	Type	Default	Range	Description
`enableMemorials`	boolean	true	—	A named villager's death drops a memorial keepsake recording name, profession, level, and cause of death.
`enableMourning`	boolean	true	—	Villagers near a villager death briefly stop, face the spot, and shed grief tears (cosmetic only).
`enableFearMarkup`	boolean	true	—	A killing spree in one village marks up that village's prices for the killer, keyed to the village bell and decaying over time. Shows as a "Fear" line in the price breakdown.
`fearKillThreshold`	int	3	1–20	Villager kills in the same village within the kill window needed to trigger the fear markup.
`fearKillWindowMinutes`	int	10	1–120	Minutes (real time) in which the threshold kills must land to count as a spree.
`fearMarkupPercent`	int	25	0–200	Price markup when fear is fresh, as a percent of base price; decays linearly to zero over the duration. `0` disables the price effect.
`fearMarkupDurationDays`	int	3	1–30	In-game days for a village's fear of the killer to fade completely.

Fear is tracked per player, per village — a village is identified by its nearest bell within 48 blocks. Kills in a bell-less cluster belong to no village and never trigger fear.

Sentry Pylon

Key	Type	Default	Range	Description
`enableSentryPylon`	boolean	true	—	Master toggle for the Sentry Pylon block + crafting recipe.
`enablePylonBellAlarm`	boolean	true	—	On detecting a threat, the pylon rings the nearest village bell within its radius (max once per 10s).
`pylonDetectionRadius`	int	32	4 – 128	Blocks within which the pylon detects hostile mobs.
`pylonMaxFuel`	int	8	1+	Iron blocks the pylon can store at once.
`pylonMaxGolems`	int	3	1+	Maximum active sentry golems per pylon.
`sentryDespawnSeconds`	int	30	5+	Seconds without hostiles before a sentry despawns.
`pylonTribulationGolemBonusPerTier`	int	1	0+	Extra sentry golems allowed per Tribulation threat tier. Only active when Tribulation is installed.
`pylonTribulationRadiusBonusPerTier`	int	4	0+	Extra detection radius in blocks per Tribulation threat tier. Only active when Tribulation is installed.
`pylonTribulationMaxGolems`	int	6	≥ pylonMaxGolems	Hard cap on sentry golems per pylon under Tribulation scaling. Only active when Tribulation is installed.

Client Config

Client-side rendering and audio preferences. Stored in the same JSON file but never synced — every client owns its values independently.

Key	Type	Default	Range	Description
`villagerSoundVolume`	float	1.0	0.0 – 1.0	Volume for all villager sound events (0.0 = mute, 1.0 = vanilla).
`enableWorkstationVis`	boolean	true	—	Render workstation-link particles while holding a bell.
`enableBellRadiusVis`	boolean	true	—	Render the 48-block bell radius circle while holding a bell — a gold circle around each nearby placed bell plus a dim-white placement preview around you — and outline adult villagers within it.
`enableInfoPanel`	boolean	true	—	Show the villager info side panel in the merchant screen.
`enableReputationHud`	boolean	true	—	Show the top-left reputation tier indicator near villagers.
`enableTierChangeMessages`	boolean	true	—	Show a chat notice when your reputation tier changes.
`hudAnchor`	enum	TOP_LEFT	TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT	Screen corner the reputation HUD is anchored to.
`hudOffsetX`	int	4	0 – 10000	Horizontal distance in pixels from the anchored screen edge.
`hudOffsetY`	int	4	0 – 10000	Vertical distance in pixels from the anchored screen edge.

Full Default JSON

For reference, the complete mercantile.json with every field set to its default value:

{
  "enableVillagerPickup": true,
  "pickupXpCost": 5,
  "enableNames": true,
  "enableTradeCycling": true,
  "tradeCycleEmeraldCost": 6,
  "enableReputation": true,
  "reputationTradeGain": 1,
  "reputationCureGain": 5,
  "reputationAttackLoss": 15,
  "reputationKillLoss": 40,
  "reputationCycleGain": 1,
  "reputationDailyCap": 5,
  "reputationTradesPerGain": 5,
  "reputationDailyMaxTradeRep": 2,
  "reputationDailyMaxCycleRep": 1,
  "enableRaidReputation": true,
  "reputationRaidWinGain": 10,
  "enableWanderingTraderRep": true,
  "enableGifting": true,
  "reputationGiftGain": 1,
  "reputationDailyMaxGiftRep": 2,
  "reputationNegativeDecayPerDay": 1,
  "enableGratitudeGifts": true,
  "gratitudeGiftsPerDay": 1,
  "enableNitwitRehab": true,
  "nitwitRehabEmeraldCost": 16,
  "enableWorkOrders": true,
  "workOrderEmeraldCost": 1,
  "enableContracts": true,
  "contractOfferChance": 50,
  "contractPaymentScale": 100,
  "contractRepGain": 3,
  "contractRepPerDay": 3,
  "contractDeadlineDays": 2,
  "enableMemorials": true,
  "enableMourning": true,
  "enableFearMarkup": true,
  "fearKillThreshold": 3,
  "fearKillWindowMinutes": 10,
  "fearMarkupPercent": 25,
  "fearMarkupDurationDays": 3,
  "enableFollowMode": true,
  "maxFollowingVillagers": 3,
  "enableSendHome": true,
  "enablePathfindingFixes": true,
  "enablePathfindingDoors": true,
  "enablePathfindingStairs": true,
  "enablePathfindingLadders": true,
  "enablePathfindingWater": true,
  "enableBulkTrading": true,
  "enableProfessionLock": true,
  "enableHealing": true,
  "healingMultiplier": 2.0,
  "enableRestockIndicator": true,
  "enableDemandTransparency": true,
  "enableTradePinning": true,
  "maxPinnedTradesPerPlayer": 10,
  "pinRestockNotifyRange": 128,
  "enableBreedingTooltip": true,
  "enableBabyFeeding": true,
  "babyFeedPercentPerFeed": 10,
  "babyFeedMaxReductionPercent": 50,
  "enableStateIndicators": true,
  "enableMood": true,
  "moodPriceModifierPercent": 5,
  "moodRestockSpeedPercent": 20,
  "moodRecalcIntervalTicks": 100,
  "moodAmbientParticles": true,
  "enableMarketDay": true,
  "marketDayIntervalDays": 7,
  "marketDayDiscountPercent": 5,
  "enableSentryPylon": true,
  "enablePylonBellAlarm": true,
  "pylonDetectionRadius": 32,
  "pylonMaxFuel": 8,
  "pylonMaxGolems": 3,
  "sentryDespawnSeconds": 30,
  "pylonTribulationGolemBonusPerTier": 1,
  "pylonTribulationRadiusBonusPerTier": 4,
  "pylonTribulationMaxGolems": 6,
  "villagerSoundVolume": 1.0,
  "enableWorkstationVis": true,
  "enableBellRadiusVis": true,
  "enableInfoPanel": true,
  "enableReputationHud": true,
  "enableTierChangeMessages": true,
  "hudAnchor": "TOP_LEFT",
  "hudOffsetX": 4,
  "hudOffsetY": 4
}