Custom Villager Trades — Guide

How Custom Trades Are Organised

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.

Building a Trade

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.

Wandering Trader Trades

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.

Adding To or Replacing Default Trades

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.