Getting Started

1. Installation

Mercantile is a Fabric mod for Minecraft 1.21.1. Like every Fabric mod, you'll need:

1. Install Fabric Loader 0.16+ via the official Fabric installer.
2. Download Fabric API from Modrinth and drop it into your mods/ folder.
3. Download Mercantile from Modrinth or CurseForge and drop the jar into mods/.
4. Launch Minecraft once. The first run generates .minecraft/config/mercantile.json with default values.

For an in-game settings GUI (recommended), also install:

• Mod Menu — adds an entry point on the mods list.
• Cloth Config API — provides the settings UI builder.

All other integrations (Jade, WTHIT, EMI, REI, JEI) are optional. Mercantile loads cleanly without any of them. See the full config reference for every available setting.

2. Your First Villager Pickup

Mercantile turns villagers into portable items, preserving everything about them — profession, trades, gossip, name, even their inventory. Try it:

1. Find an adult villager (any profession, or unemployed) or a wandering trader.
2. Make sure you have 5 XP levels available (creative mode waives the cost). The cost is configurable via pickupXpCost.
3. Empty your main hand, then Sneak + Right-Click the villager.
4. A green particle burst and sweep sound confirm the pickup. The villager vanishes; a profession-styled player head appears in your hand.
5. The head item's tooltip shows the villager's profession, level, and trades. Each trade includes lock indicators and a strikethrough for out-of-stock entries.
6. To place the villager again, Right-Click the head item on a block. The villager respawns facing you with all original data intact.

Pickup is blocked during raids, while another player is trading with the villager, and while the villager is following someone. Wandering traders use the same flow — their despawn countdown is frozen while held and resumes on placement, and any leashed trader llamas drop their lead and stay put. Read more →

3. Understanding Reputation

Mercantile tracks a persistent global reputation score per player, from −100 to +200. The score affects pricing across every villager in the world and survives death.

The five tiers

Ways to gain reputation

• Complete a trade: +1
• Cure a zombie villager: +15 (one-time per villager UUID)
• Cycle a villager's trades: +2
• Stand near a villager for 10 minutes: +1 (capped at +1/day total)

Ways to lose reputation

• Attack a villager: −10
• Kill a villager: −25

Knowing where you stand

A compact HUD overlay appears in the top-left corner when a villager is within 32 blocks, showing your current tier. The icon is the Mercantile balance scale; the text is your tier name.

For a precise score, run:

/mercantile reputation

See the commands reference for op-restricted set/add variants, and features → Reputation for the full details.

4. Trade Cycling Basics

Tired of breaking and replacing workstations to chase a Mending book? Cycle the villager's trades for 6 emeralds (configurable) instead.

1. Find any villager with at least one profession (Librarian for enchant books, Cleric for glowstone, etc.).
2. Right-click to open the trade GUI. Look for the "Re-roll Trades" button in the villager info panel.
3. Make sure you have at least tradeCycleEmeraldCost emeralds in your inventory or offhand.
4. Click the button. Six emeralds are consumed (the cost is waived in creative). All unlocked trades are re-rolled from the profession's trade pool.
5. You'll see a gold-diamond particle flash and hear a villager "yes" sound on success.

Locked trades are preserved. A trade becomes locked once you've purchased it at least once. Lock state is tracked by a stable hash of the trade's input/output items, so the same trade keeps the same lock across cycles. The button disables when every trade is locked.

Cycling also grants +2 reputation per cycle, so chasing trades helps your standing too. Read more →