Merchant Module

The Merchant module expands trading without making workstation breaking the best strategy forever.

It adds trade locks, paid rerolls, auto-search, auto-trade, merchant stats, payment integrations, and Trading Hall support.

Merchant Controls RerollAutoInfo

Paper → EmeraldLocked

Emerald → LanternOpen

Emerald → BookshelfOpen

Right-clicking a trade row marks it with a green lock outline. Manual rerolls and auto-search preserve locked rows while replacing the open ones.

Auto-Search Settlement PayDecline

Requested resultMending

Rerolls completed18

Tracked V costEmeralds

Auto-search has a live hourly preview while it runs, then presents a settlement based on the requested targets it actually found.

Trade Locks

Right-click a trade row to lock or unlock that offer.

Locked offers get a green outline.
Locked offers are preserved during manual rerolls.
Locked state survives world saves.
Lock masks are sanitized if the villager's offer count changes.
Auto-search checks unlocked offers when deciding whether it found a requested result.

tip

Lock the trade you care about before rerolling. Rerolls replace only unlocked offers.

Manual Reroll

Use the reroll button in the merchant screen.

Left-click rerolls immediately.
The result slot must be empty.
Unsupported merchants are ignored.
Rerolling can be blocked by cooldown, daily cap, or server config.
If allowAfterTradeUsed is disabled, villagers with used trade XP cannot be rerolled.
Rerolls rebuild the unlocked offers, then reapply Hoarder and Generosity adjustments.

Manual Cost

Manual reroll cost is based on unlocked offers.

unlockedOffers = totalOffers - lockedOffers
paidOffers = max(0, unlockedOffers - freeOffers)
baseCost = paidOffers * costPerOffer
finalCost = baseCost after Generosity

Generosity is a discount-style stat: positive Generosity lowers cost, negative Generosity raises it.

Payment Sources

Villager Overhaul uses the server-configured cost item or tag.

Cost Config	Behavior
Exact item id	Consumes that exact item.
Item tag	Consumes any item matching the tag.
`minecraft:emerald`	Can withdraw from EZ Emerald Pouch first, then inventory.
Lightman's Currency item	Can prefer wallet payment when enabled.

If Lightman's Currency is installed and the server allows auto-preference, the default emerald cost can switch to the Lightman's emerald coin.

Auto-Search

Right-click the reroll button to open the auto-search catalog.

Pick one or more target results.
Start auto-search.
The villager becomes busy and keeps rerolling over time.
When a requested result appears in an unlocked offer, the search completes.
You pay or decline the settlement.

While busy:

The villager is frozen with a movement-speed modifier.
The villager uses a green glowing team outline nearby.
Normal merchant opening is replaced by a busy/payment screen.
Search tasks and settlements survive save/load.

Auto-Search Hourly Preview

Auto-search starts from the manual paid-offer model, then turns it into an hourly rate.

manual = max(0, unlockedOffers - freeOffers) * costPerOffer
hourlyBase = manual * 10
steps = paidOffers - autoHourlyThreshold
factor = max(0, 1 - steps * autoHourlyDiscountOrIncreasePct / 100)
hourly = ceil(hourlyBase * factor)
finalHourly = hourly after Generosity

If paid offers are below the threshold, steps is negative and the factor goes above 1, making the hourly cost higher. If paid offers are above the threshold, the hourly cost drops.

Auto-Search Settlement

Auto-search also tracks player-specific "V" units per requested result.

Each successful auto-search reroll adds V equal to the number of offers rerolled at search start.
V is split across all requested target items.
Final settlement cost is based on stored V for the requested targets times costPerOffer.
Declining or cancelling does not refund accumulated V.
Paying a settlement can clear those target V values.
Server config can clamp the final settlement cost to hourlyCost * maxAutoSearchCostMultiplier.

Note

The hourly preview tells you the rate of the search. The final payment is settlement-based, using the tracked V values for the requested items.

Auto-Search XP

Villager XP is awarded only after settlement payment succeeds.

xp = autoSearchXpPerOffer * offersRerolledAtStart * successfulRerollCount

Intellect modifies the XP result. Level-ups use the vanilla villager level-up flow, then Hoarder and Generosity are applied again.

Auto-Trade

Auto-trade is started from the merchant screen with a control-click interaction on a valid trade.

It is server-driven through the vanilla MerchantMenu click path.
It clears stale input slots before starting.
It tries up to 5 trades per tick.
It stops if the menu closes, the offer disappears, the offer is out of stock, there is no output, a click fails, no progress is made for about 40 ticks, or the session lasts longer than 60 seconds.

Auto-trade is most useful for bulk trades that produce emeralds or need repeated vanilla trading.

Merchant Stats

Stat	Effect
Generosity	Reduces or increases reroll costs and generated emerald prices.
Timeliness	Reduces or increases reroll and auto-search cooldowns.
Intellect	Increases or reduces villager XP from merchant activity.
Hoarder	Adds or removes offers within the configured min/max clamp.

Deep dive: Hoarder

Hoarder is reapplied after offer rebuilds and vanilla level-up changes. This prevents offer counts from drifting permanently after rerolls, auto-search, or level changes.

Limits and Safety

Limit	Behavior
Manual cooldown	Per-villager manual reroll cooldown, modified by Timeliness.
Auto cooldown	Per-villager auto-search reroll cooldown, modified by Timeliness.
Daily cap	Optional per-villager daily reroll cap. `0` disables it.
Used trades	Server can block rerolling after trades were used.
Result slot	Manual reroll is refused if the result slot has an item.

Technical note: rebuild order

After a manual reroll, the mod rebuilds offers, normalizes Hoarder offers, applies Generosity prices, grants XP if configured, then schedules a next-tick offer recheck because vanilla can append or refresh offers after the immediate call stack.