Custom Villager Trades Wiki

Custom Villager Trades lets you rewrite what villagers and wandering traders sell, using plain configuration files instead of code or datapacks. Every profession can be given its own set of trades, and every trade is described in a small, readable file that you can edit by hand.

A trade can be as simple as "one emerald for one diamond" or as elaborate as an enchanted, renamed weapon that costs a specific combination of items. You decide the price, the reward, how many times the trade can be used before it locks, how much experience the villager earns from it, and which of the villager's five career levels it appears at. You can add trades alongside the villager's normal ones, or clear the defaults and replace them entirely.

Because everything is defined in files, the same configuration can be dropped into any world or shared with anyone. Nothing needs to be crafted, and no new items are added to the game — the mod only changes what the traders you already have will offer.

When the mod first runs it creates a folder for its configuration and writes a fully working example inside it. Each villager profession has its own file, named after the profession — a farmer file controls farmers, a librarian file controls librarians, and so on. Wandering trader trades live in their own sub-folder.

To change a profession you open its file, edit the list of trades, and reload. A file that does not exist simply means that profession keeps its normal trades untouched, so you only ever need files for the professions you actually want to change.

Each file holds a small number of settings for the profession as a whole, followed by the list of trades themselves:

• Profession — which villager career the file applies to.
• Remove other trades — whether the villager's built-in trades are cleared before yours are added.
• Max trades — how many trades from the list a villager may offer at each level.
• Trades — the list of individual trades, described below.

A single trade is made of two halves: what the player pays and what the villager gives back.

• Offer — the item the villager hands over. This is the reward the player receives.
• Request — the main item the player must pay.
• Additional request — an optional second payment item, so a trade can cost two different things at once (for example emeralds and an ingot).

Each of those is an item entry with an id and an amount. On top of the price and reward, a trade carries a few numbers that control how it behaves:

• Trade level — which of the villager's career tiers (1 to 5, from Novice to Master) the trade unlocks at.
• Max uses — how many times the trade can be used before it locks until the villager restocks.
• Trade experience — how much trading experience the villager gains toward its next career level from this trade.
• Price multiplier — how strongly demand and low reputation push the price up.
• Demand — a starting demand value that nudges the price.

Any item in the game can be used on either side, so a trade can buy a cheap block and sell something far more valuable, or the reverse.

The item a trade gives out does not have to be a plain stack. Each item entry can be dressed up so the reward feels special:

• Custom name — rename the item, so a trade can sell a sword called "Villager's Bane" or a star called "Fallen Star".
• Enchantments — add one or more enchantments at chosen levels. You can pin an exact level, pick a random level within a range, or let the game roll a random enchantment for you. Enchantments work on tools, armour and weapons, and are stored correctly on enchanted books.
• Random enchantments with a blacklist — ask for a random enchantment but exclude ones you do not want, so a trade never rolls something useless.
• Potion effects — turn a potion, tipped arrow or similar item into one carrying the effects you list, at the duration and strength you choose, with an optional custom colour.
• Extra data — attach custom item data for items that need it, and point map items at a structure so they generate as explorer maps.

These options apply to the reward and to the payment items alike, so you can even require an enchanted or specifically named item as the price.

The wandering trader is handled separately from the professions, because it does not belong to a village and does not have career levels. Its trades live in their own file, and each entry uses the same item options as a normal trade — custom names, enchantments, effects and prices all work the same way.

Because the wandering trader appears anywhere and sells to everyone, it is a convenient place to put rare or novelty trades that you want available across a whole world rather than tied to a particular village.

Each profession file chooses whether your trades sit beside the villager's normal offers or replace them.

• Leave remove other trades off and your trades are simply added to the vanilla list, so a farmer still sells its usual crops but now also offers whatever you added.
• Turn remove other trades on and the vanilla trades are cleared first, leaving the villager selling only what you defined. This is how you build a completely bespoke merchant.

The max trades setting then controls how many of the listed trades a villager actually shows at each level, so a long list can still produce varied villagers that each offer a different subset.

Two commands make editing trades convenient while a world is running:

• Reload — re-reads the configuration files without restarting the game, so you can tweak a trade and see the result on newly created villagers straight away.
• Export — writes the currently loaded trades back out to an exports folder, which is a quick way to capture a working set of trades or to produce a template you can copy from.

Both commands are limited to operators by default, and the permission level required can be changed in the global configuration.

Alongside the per-profession files there is a single global configuration file for settings that apply to the mod as a whole, such as the operator permission level needed to use the commands.

Any mistakes in a trade file — an item id that does not exist, or an enchantment that cannot be applied to the chosen item — are reported when the configuration loads and again to operators when they join, so a broken trade is easy to find and fix rather than silently disappearing.