Features

Villager Pickup

Sneak-right-click an adult or baby villager with an empty main hand to pick them up as a profession-styled player head item. Full NBT — profession, level, XP, trades, gossip, name, inventory — is preserved.

Wandering traders work the same way — sneak-right-click to capture, with the despawn countdown frozen while held and resumed on placement. Each leashed trader llama drops its lead and stays put rather than chasing the captured trader.

Right-click the head item on a block to place the villager or trader back, facing toward you. Villager pickup is blocked during raids, while another player is trading with them, or while they are following someone. Trader pickup is blocked only while another player is trading with them.

Config: enableVillagerPickup, pickupXpCost (default 5 XP)

Villager Names

Every villager and wandering trader is auto-named on spawn from a biome-themed pool: English in Plains/Forest, Arabic in Desert, Nordic in Taiga, Mesoamerican in Jungle, African in Savanna, Old English in Swamp, Western in Badlands.

Names always render above the villager or trader. Player-applied nametags override the generated name. Names survive pickup, world reloads, and dimension changes. Datapacks can override or extend pools via data/mercantile/villager_names/<category>.json.

Config: enableNames

Follow Mode

Sneak-right-click a villager while holding an emerald to make them follow you. They pathfind toward the player at ~6 blocks distance, ignore schedule goals (workstation, bed, wandering), and refuse mob-to-mob collision pushes.

Cyan particles trail at their feet while following. They auto-release if you move more than 32 blocks away. A villager already following one player cannot be recruited by another. Not persisted — cleared on logout, unload, or restart.

Sent home on release: sneak-right-click with an emerald again to dismiss, and the villager walks back to its bed (or workstation, if it has no bed) instead of standing where you left it. Taking damage cancels the trip. Toggle with enableSendHome.

Config: enableFollowMode, maxFollowingVillagers (default 3), enableSendHome

Boosted Healing

Splash and lingering potions of healing restore double the normal HP when they hit a villager. Splash and lingering regeneration potions apply double the normal duration. Tipped arrows are unaffected.

Tune the multiplier (1.0×–10.0×) to make raid recovery easier or stricter.

Config: enableHealing, healingMultiplier (default 2.0)

Baby Feeding

Right-click a baby villager with villager food — bread, carrot, potato, or beetroot — to feed it and shave a percentage off its remaining growth time (default 10% per bread; lower-value foods scale down). The growing countdown shown by Jade natively (or by Mercantile's WTHIT line) reflects every feed immediately.

Each baby caps out at a configurable share of its total growth time (default 50%); once capped, further food is refused and not consumed.

Config: enableBabyFeeding, babyFeedPercentPerFeed (default 10), babyFeedMaxReductionPercent (default 50)

Profession Lock

After any completed trade, a villager's profession becomes permanently locked. Their trade offers survive even if the workstation is broken, moved, or destroyed. They will still claim a same-type workstation if one is available nearby.

A lock icon appears in the trade GUI header. Jade/WTHIT tooltips show "Profession: Locked" vs "Profession: Unlocked".

Config: enableProfessionLock

Work Orders

Stop playing workstation roulette. Sneak-right-click an unemployed adult villager while holding a profession workstation item — a lectern, smithing table, composter, any job-site block — and it walks to the nearest unclaimed workstation of that type and claims it, taking the matching profession. The held item only identifies the job and is never consumed; the workstation block itself must already be placed in the world.

Each accepted order costs a small emerald fee (default 1, waived in creative), answered with a villager "yes" and happy particles; the profession-tinted workstation link mote then shows the new binding. If no free workstation of that type is within range the order is refused with an action-bar message and nothing is charged. Employed villagers, nitwits, and babies ignore the interaction entirely, and the job is resolved from the block's point-of-interest registration, so modded professions work automatically. One vanilla quirk carries over: while the claim is still in progress, a nearby established villager of the matching profession that lost its own workstation can inherit it.

Config: enableWorkOrders, workOrderEmeraldCost (default 1)

Villager Mood

Each villager tracks a mood from its living conditions — a claimed bed, a workstation, recent sleep, a stocked food inventory, staying unharmed, and not witnessing another villager's death. The score drifts gradually toward what conditions dictate and settles into one of four tiers: Miserable, Unhappy, Content, or Happy.

Mood is a gentle nudge, not a gate: Happy villagers offer a small discount and restock sooner; Miserable ones add a small markup and restock later. The current tier shows in Jade/WTHIT tooltips and the trade-GUI info panel, and the price effect appears as its own "Mood" line in the demand price breakdown — stacking with, never replacing, gossip and reputation. Happy villagers occasionally emit happy particles; Miserable ones emit angry ones.

Mood belongs to the villager and is the same for every player; it persists across save/reload and pickup/place.

Config: enableMood, moodPriceModifierPercent (default 5), moodRestockSpeedPercent (default 20), moodAmbientParticles

Memorials, Mourning & Fear

Villager deaths carry weight. When a named villager dies, it drops a memorial keepsake — a custom skull glyph whose tooltip records the villager's name, profession, level, and how they died. A keepsake, not a resurrection token; unnamed villagers drop nothing.

Nearby villagers mourn: for a few seconds they stop what they're doing, turn toward where their neighbor fell, and shed pale-blue grief tears. Purely cosmetic — no AI or schedule changes.

And villages remember who did it. Killing several villagers in the same village within a short window (default 3 kills in 10 minutes) makes that village's survivors afraid of you: a price markup (default 25% of base price) applies to the killer only, in that village only — keyed to the village bell — and fades linearly over a few in-game days. It shows as its own red "Fear" line in the price breakdown, on top of the reputation penalty.

Config: enableMemorials, enableMourning, enableFearMarkup, fearKillThreshold, fearKillWindowMinutes, fearMarkupPercent, fearMarkupDurationDays

Smarter Pathfinding

Villagers properly open fence gates and double doors, navigate multi-step staircases and slab transitions, climb ladders when the path calls for it, and prefer dry routes over water.

Each fix is independently toggleable.

Config: enablePathfindingFixes, enablePathfindingDoors, enablePathfindingStairs, enablePathfindingLadders, enablePathfindingWater

Trade Cycling

Pay 6 emeralds (configurable) to re-roll a villager's unlocked trades from the profession pool — no more breaking and replacing workstations. Trades become locked once purchased; locked trades are preserved across cycles.

The "Re-roll Trades" button sits in the villager info panel. It stays visible but grays out when you have no emeralds, or when the villager's profession is locked — hovering the disabled button explains which. Cycling also grants a small reputation gain.

Config: enableTradeCycling, tradeCycleEmeraldCost (default 6), reputationCycleGain (default +1)

Bulk Trading

Shift-click a trade output slot to repeat the trade automatically. Stops when input runs out, the trade goes out of stock, the inventory fills up, or 64 trades are executed.

Price stays locked for the duration of a single bulk operation — no mid-loop repricing. Demand counters update correctly for all completed trades.

Config: enableBulkTrading

Restock Indicator

The trade GUI shows estimated time until the next restock in ~M:SS format, plus a counter for restocks remaining today. Shows "Fully stocked" when all trades are at max, or "No workstation" in red when the villager is unbound.

Config: enableRestockIndicator

Trade Pinning

Pin the trades you're waiting on. Each row in the merchant screen carries a small pin toggle — dimmed until you hover the row, filled once pinned; pinned trades are remembered per player and survive relogging. When a villager restocks a pinned trade that was sold out and you're within range (default 128 blocks, same dimension), an action-bar note names the villager and the trade — "Aldric restocked: Emerald x3 → Mending I".

/mercantile pins lists your pins numbered with each trade's current stock status; /mercantile pins remove <n> drops one and /mercantile pins clear empties the list. The same list, with live stock coloring, also appears in the hold-to-peek reputation detail panel so you can review pins without opening a screen. Pins are capped per player (default 10), and pins pointing at villagers that died or re-rolled away the trade are pruned silently.

Config: enableTradePinning, maxPinnedTradesPerPlayer (default 10), pinRestockNotifyRange (default 128)

Demand Transparency

Hover over a trade price to see a breakdown: base price, demand adjustment, reputation modifier, mood modifier, gossip modifier, market-day discount, fear markup, final price. Discounts appear in green, markups in red.

Config: enableDemandTransparency

Market Day

Every 7 in-game days (configurable) the whole world holds a market day from dawn to dusk. Every villager trade gets a global discount (default 5% of base price) that stacks with reputation and gossip and shows as its own line in the price breakdown, and villagers gain one extra restock cycle — the restock indicator reads “Restocks: x/3 today — market day”.

The day opens with a bell ring, happy-villager particles, and an action-bar announcement for everyone online. The schedule is shared world-wide, so market day is predictable and easy to plan around.

Config: enableMarketDay, marketDayIntervalDays, marketDayDiscountPercent

Villager Info Panel

A side panel in the merchant screen showing the villager's name, profession and level with XP progress bar, your reputation standing with them, total trades completed, workstation status (bound/unbound and type), the villager’s mood tier, and the profession-locked indicator.

Small-screen fallback: when the window is too narrow to fit the side panel next to the trade GUI, a small i icon appears beside the villager title. Click it to open the same info as a centered overlay; press Esc or the x in the corner to close.

Client config: enableInfoPanel

Score Events

• Trade: +1 per 5 trades
• Cure zombie villager: +5 (one-time per UUID)
• Attack a villager: −15
• Kill a villager: −40
• Trade cycling: +1
• Proximity: +1 per 10 min (capped at +1/day)
• Gift a profession item: +1 (daily-capped)
• Defend a village from a raid: +10 (bypasses the daily cap)

Config: reputationTradeGain, reputationCureGain, reputationAttackLoss, reputationKillLoss, reputationCycleGain, reputationGiftGain, reputationRaidWinGain

Redemption Path

Climb back from Reviled without grinding refused trades. Toss a profession-appropriate item near a villager — crops to a Farmer, iron to an Armorer — and it walks over, accepts the gift, and rewards you with reputation and happy particles.

Negative reputation also recovers on its own: scores below 0 drift back toward Neutral by a configurable amount each in-game day. Positive reputation never decays.

Config: enableGifting, reputationDailyMaxGiftRep, reputationNegativeDecayPerDay · Datapack: data/mercantile/gift_mappings/

Gratitude Gifts

At Honored standing the gifting flows both ways: spend time near villagers and one will occasionally walk over and toss you a small profession-flavored thank-you — bread from a farmer, arrows from a fletcher — with happy particles and a villager "yes". Professions without a table draw from a generic pool of bread and seeds.

It's flavor, not income: at most one gift per player per in-game day by default, and the shipped tables contain only modest items. Datapacks can override or extend tables per profession via data/mercantile/gratitude_gifts/<profession>.json with the same replace/append semantics as the gift mappings.

Config: enableGratitudeGifts, gratitudeGiftsPerDay (default 1)

Nitwit Rehabilitation

Nitwits stop being dead weight. At Trusted standing and above, use a golden apple on an adult nitwit and pay an emerald fee (default 16, drawn from your inventory) — after a short pause it sheds the green robe and becomes an unemployed villager, ready to claim a workstation like any other. Happy particles and a villager "yes" mark the moment; name and gossip carry over.

The conversion is one-way and checked at use time: below Trusted you're told what standing it takes, baby nitwits must grow up first, and nothing is charged on a denied attempt. If the reputation system is disabled the tier gate is skipped and only the apple + emerald cost applies.

Config: enableNitwitRehab, nitwitRehabEmeraldCost (default 16)

Delivery Contracts

Villagers finally ask something of you. An employed villager occasionally rolls a delivery request — a speech-bubble cue floats over its head — and sneak + using paper on it signs the contract (a plain paper click still trades as vanilla): one paper becomes a unique contract item recording a profession-appropriate request (32 wheat for a farmer, coal for an armorer), the emerald payment, the villager's name and last-known spot, and a deadline (default 2 in-game days). Right-click the contract in the air any time to print the full terms and live time remaining to chat.

While the contract is in your hand its villager glows — an outline only you see, visible through walls, matched by contract id so it survives save/reload and even the pickup/place cycle. Deliver by right-clicking the payee with the contract in hand and the goods anywhere in your inventory: the items and contract are consumed, the emeralds are paid, and you earn a reputation bonus that — like curing and raid defense — bypasses the daily cap, bounded instead by its own per-day award count (default 3; later deliveries still pay emeralds). The wrong villager politely refuses, a short stock refuses without taking anything, and an expired contract simply crumbles away, no penalty.

Request pools are data-driven per profession via data/mercantile/contracts/<profession>.json with the same replace/append semantics as the mod's other loaders — packs can retune requests, counts, payments, and weights, or give modded professions their own pools.

Config: enableContracts, contractOfferChance (default 50), contractPaymentScale (default 100), contractRepGain (default 3), contractRepPerDay (default 3), contractDeadlineDays (default 2)

Raid Defense & Traders

Earn back standing the heroic way: any player vanilla awards Hero of the Village for breaking a raid also gains reputation — granted in full, outside the daily cap.

Wandering traders reward loyalty too. At Trusted tier and above, a wandering trader rolls one exclusive bonus offer (rare blocks and materials); the offer sticks to that trader so it stays put across re-opens.

Config: enableRaidReputation, enableWanderingTraderRep

Reputation HUD

A compact indicator in the top-left HUD strip shows your current standing when a villager is nearby (default 32-block radius). Auto-stacks with other rfizzle suite mods at priority 2.

Hidden during F1, open screens, and death. A custom balance-scale glyph sits over a 2px bar tinted by standing — emerald at the top tiers, fading to orange and red as you slip — that fills toward the next standing.

Client config: enableReputationHud

Reputation Detail Panel

The always-on badge tells you roughly where you stand; hold the Peek Reputation Detail keybind and a framed panel tells you everything. While held it overlays your exact score, your standing in the standing color, a progress bar toward the next standing with the precise figures, and how much reputation you've banked against today's cap. Release to dismiss — it behaves like vanilla's hold-Tab player list, never capturing the mouse or pausing the game.

Below the progress block it lists the perks your current standing grants — the trade discount or markup, and which exclusive-trade pools have opened (profession-specific at Trusted, cross-profession at Honored). Those lines are generated from the same reputation rules the server prices and gates trades with, so the panel can never lie about what your standing is worth: retune a threshold in config and the panel follows.

Between the perks and the crowd sits a status strip: whether market day is on right now — with the live discount, running until dusk — or how many days until the next one, plus a Following: N / max line whenever villagers are trailing you. The market-day line is computed from the same schedule math the server discounts with, and the follow count is pushed straight from the server, so both read true even on a dedicated server.

When you've pinned trades, a Pinned trades block lists them across the whole village — each pin's trade summary above the villager who sells it, colored by live stock: green for in stock, rust for sold out, ash while the villager is out of range. It's the same source of truth as /mercantile pins, synced per player rather than tied to an open screen, so it stays right after you pin or unpin and across relogs. A long list pages with the same cross-fade as the crowd below; the block hides entirely when trade pinning is off or you have no pins.

Last, grouped by profession, it shows the villagers actually around you right now — a cached proximity scan throttled so it costs nothing per frame — and whether your standing has unlocked their exclusive trades yet. A crowd of professions pages through with a soft cross-fade and page dots, so the panel never overflows or scrolls. Framed in the mod's slate theme with emerald and standing-colored accents. Entirely client-side, hidden during F1, open screens, and spectator mode.

Controls → Mercantile → Peek Reputation Detail — bound to Left Alt by default, rebindable

Tier-Change Notices

Cross into a new standing and a chat line tells you the moment it happens — "Villagers now consider you Trusted — new exclusive trades unlocked. Hold Left Alt for details." — naming the standing you reached and pointing at the detail-panel keybind so the payoff is one keypress away. Slip backward and it warns you the moment your standing falls, so a slide toward higher prices never goes unnoticed.

The hint always names your live keybind, not a hardcoded key, and drops the hint cleanly if you've unbound the panel. No message fires on the first sync when you join a world, and standing changes are rare enough that the notice never spams.

Client config: enableTierChangeMessages

Iron-Fueled Defense Block

A placeable block that detects hostile mobs within a 32-block radius (configurable) and spawns temporary iron golems to defend your village. Right-click with iron blocks to fuel — up to 8 stored. Each golem costs 1 iron block to summon. Maximum 3 active sentries per pylon. The pylon only reacts to threats it has a clear line of sight to, so a mob in a cave or behind a wall won't summon a golem underground, ring the bell endlessly, or keep a sentry stranded on a threat nothing can reach.

Sentry golems attack any hostile the pylon detects — including creepers, which ordinary iron golems ignore. A creeper won't detonate while fighting a sentry, so the golem can put it down without cratering what it's guarding. They leash to the pylon, drop nothing on death, and don't count toward the mob cap. Once the fighting stops they walk back to the pylon and idle beside it — no more strolling off after the village or pacing the radius edge — and despawn 30 seconds after the last threat clears, cracking apart where they stand. The countdown holds while the pylon still sees a hostile, or while a sentry is still fighting one out of the pylon's own sight, and over its final seconds the golem visibly cracks and fades before it goes. Breaking the pylon dismisses its sentries on the spot with the same effect, so none is left stranded once the block is gone.

Three blockstate variants — idle, active, empty — each with distinct particles. A redstone signal disables the pylon: it stops scanning and spawning, and winds any active sentries down on the normal despawn countdown rather than holding them. Comparator output is proportional to fuel level (0–15). Crafted from carved pumpkin, iron blocks, bell, and stone bricks.

Bell alarm: on spotting a threat the pylon rings the nearest village bell within its radius — the standard vanilla ring, drawing players to the fight. Because a bell ring lights nearby villagers with a see-through-walls glow that carries to 96 blocks while the vanilla ring only sounds out to ~16–32, the ring itself is amplified to the full 96-block radius — so a distant player hears it and isn't left with a silent glow. This louder ring applies to every bell, not just pylon-triggered ones, and follows the glow toggle (enableBellRadiusVis). The pylon's ring is rate-limited to once every 10 seconds. Toggle the pylon alarm with enablePylonBellAlarm.

Hopper & pipe fueling: hoppers attached to any face (top, sides, bottom) feed iron blocks into the pylon one at a time, up to the fuel cap. Non-iron items are rejected, so hoppers cycling mixed inventories don't deadlock, and overflow is left in the hopper rather than destroyed. Hoppers cannot extract — fuel only flows in. Modded item pipes (Pipez, etc.) work via the Fabric Transfer API (ItemStorage.SIDED). Disabled when enableSentryPylon is off.

Config: enableSentryPylon, enablePylonBellAlarm, pylonDetectionRadius (4–128), pylonMaxFuel, pylonMaxGolems, sentryDespawnSeconds (min 5)

Tribulation Threat Scaling

With Tribulation installed, the pylon reads the local threat tier (from the nearest player within its radius) and scales its defense to match: each tier raises the golem cap and widens the detection radius, so village defense keeps pace with Tribulation's harder raids. A hard cap keeps a max-tier pylon from fielding an unkillable golem army, and each extra golem still costs its iron block of fuel.

This is a soft integration — without Tribulation the pylon behaves exactly as configured, and Tribulation is never required.

Config: pylonTribulationGolemBonusPerTier, pylonTribulationRadiusBonusPerTier, pylonTribulationMaxGolems — only active when Tribulation is installed

Tutorial Advancement Tree

A dedicated Mercantile advancement tab teaches the mod's gestures as you play. Every advancement's description spells out the exact gesture that grants it, so Mercantile's hidden interactions are discoverable in-game without a wiki.

The tree branches from a root earned by trading with any villager: pick up a villager, make one follow you with an emerald, have one accept a tossed gift, accept a delivery contract, reach the Trusted reputation tier, fuel a Sentry Pylon, assign a work order, and start nitwit rehabilitation.

Each grant lives inside the feature it teaches, so an advancement whose feature is disabled in config is simply never earned.

No config — the advancement tab is always present and costs nothing to complete.

Workstation Links

While holding a bell: profession-colored dust-particle lines connect each villager to their claimed workstation within 64 blocks. Unemployed villagers get a pulsing angry-villager particle. Each workstation floats a status marker — a green check when it's claimed, a white question mark when it's unclaimed.

Client config: enableWorkstationVis

Bell Radius

While holding a bell: a gold particle circle is drawn around each nearby placed bell, at the 48-block gathering radius measured from that bell — so a two-bell village shows two circles and their overlap is real coverage. A dim-white circle around you is a placement preview: the coverage a bell dropped where you stand would have, kept visually distinct so a hypothetical is never mistaken for actual coverage. Every adult villager in range glows with a vanilla outline for as long as the bell is held — a through-wall locator for your villagers. Ringing a placed bell instead gives a brief bell-centered glow pulse.

Client config: enableBellRadiusVis

Jade / WTHIT Tooltips

Look at a villager with Jade or WTHIT installed to see a single color-coded breeding line — Ready, Hungry (with food progress), Needs bed, or Cooldown; babies show a Growing countdown on WTHIT, while on Jade its native growing-time line is used instead — plus a color-coded mood tier line and contextual state icons: "Needs workstation", "Panicking", "Trading with <player>", "Profession: Locked". Sentry golems show their parent pylon coordinates, despawn countdown, and a "No Drops" indicator. Both plugins work simultaneously without conflict.

Config: enableBreedingTooltip, enableStateIndicators, enableMood

Mod Menu + Cloth Config

An in-game settings GUI accessible from Mod Menu's mod list. Categorized sections for Server and Client config with sliders, toggles, and input validation that mirrors the server-side clamp() bounds.

Optional dependencies: Mod Menu, Cloth Config API

Jade / WTHIT

Both tooltip mods supported simultaneously with no conflict. Mercantile registers its own provider classes that read brain memories server-side and sync data to the tooltip plugin.

Either, both, or neither — Mercantile loads cleanly without them.

EMI / REI / JEI

A unified, searchable trade index across all professions and levels with profession-head icons. Filter by profession, level, or reputation requirement. Each entry also shows the workstation block that unlocks the profession — click a workstation (lectern, composter, smoker, …) in your recipe viewer to list every trade for that profession. Exclusive trades show tier badges. Bidirectional item lookup — "Villager sells this" and "Villager buys this".

Optional — install any one of the three recipe viewers.

Meridian enchanting

With Meridian installed, librarians become an economic on-ramp into its enchanting endgame. High-standing librarians sell salvage tomes and shelf materials — including Dragon's Breath, which only appears once you've slain the Ender Dragon — and, the centerpiece, rolled Meridian enchanted books: each purchase draws one enchantment at random from Meridian's rarity pools. The available pools widen with your reputation — common books need no standing, uncommon unlock at Trusted, and rare at Honored — while treasure and top-rarity enchants stay behind Meridian's own progression.

Pure data, gated on Meridian being present — nothing changes when it isn't installed.

Optional integration: Meridian

Sound Volume Slider

A client-side volume slider (0%–100%) controls all villager sounds independently: ambient, hurt, death, trade, yes, and no. Set to 0% for full silence without affecting any other audio category.

Client config: villagerSoundVolume (default 1.0)