VillagersTradingPlus

VillagerTradingPlus allows you to fully customize villager trading for your world.

Add, replace or delete the trades of any villager, change the currency, gate trades behind conditions and reprice them, all from a datapack.

Versions: 1.20.1, 1.21.1, 1.21.8

Loader: Fabric, Neoforge (since 1.21.1), Forge (1.20.1 only)

Support my work on

What this is

VillagerTradingPlus is a library. On its own it adds no villagers, blocks or items: it replaces the machinery behind villager trading so that mods and datapacks can define trades in JSON.

Install it if a mod asks for it, or if you want to rewrite villager trading in your own pack. VillagersPlus is the reference mod built on top of it.

What you can do with it

• Add, delete or overwrite trades for every villager profession, the vanilla ones included.
• Change the currency from emeralds to any item you like.
• Set the amount, max usages, villager experience and price behaviour of each trade.
• Gate trades behind conditions: biome, dimension, weather, time of day, moon phase, gamerule, job site block or a config flag.
• Fourteen trade types, from a plain item sale to weighted pools, structure maps and enchanted books drawn from a weighted list you define.
• Merge multiple datapacks that modify the same villager, instead of letting the last one win.
• Customize the wandering trader the same way, with its own common and rare tiers.

Configuration

config/villagertradingplus/villagertradingplus-1.0-config.json5

These apply to every trade the library builds, no matter which mod or datapack defined it.

Trades

Trading screen controls

All three are off by default. When on, any player can use them, so they are meant for creative building and testing rather than survival servers.

Making a datapack

Trade files go into a datapack under your own namespace. Three folders are read:

A profession file names the profession and holds five tier arrays:

{
    "profession": "minecraft:butcher",
    "trades": {
        "novice": [],
        "apprentice": [],
        "journeyman": [],
        "expert": [],
        "master": []
    }
}

Every snippet below is a single trade object that goes inside one of those five arrays.

Notice: the vanilla trades aren't in JSON form yet, so replacing those means writing out the tiers you want to keep.

Fields every trade type accepts

These are left out of the examples below to keep them short:

Trade types are namespaced villagertradingplus:. The old villagersplus: namespace is still accepted for datapacks written before the split, but it logs a deprecation warning on load, so write new files against the new one.

Trade types

sell_item

The villager sells an item for a price.

{
  "type": "villagertradingplus:sell_item",
  "sell": { "item": "minecraft:oxeye_daisy", "count": 1 },
  "priceIn": { "item": "minecraft:emerald", "count": 2 }
}

buy_item

The villager buys an item and pays you.

{
  "type": "villagertradingplus:buy_item",
  "buy": { "item": "minecraft:wheat_seeds", "count": 4 },
  "reward": { "item": "minecraft:emerald", "count": 1 }
}

sell_tagged_item

Sells one random member of an item tag. The member is chosen when the offer is generated, so two villagers with this trade will usually sell different things. Vanilla trades match a concrete item, so this is not an "any of" match at the counter.

{
  "type": "villagertradingplus:sell_tagged_item",
  "sell": { "tag": "minecraft:saplings", "count": 1 },
  "priceIn": { "item": "minecraft:emerald", "count": 3 }
}

buy_tagged_item

The same idea for buying.

{
  "type": "villagertradingplus:buy_tagged_item",
  "buy": { "tag": "minecraft:flowers", "count": 8 },
  "reward": { "item": "minecraft:emerald", "count": 1 }
}

process_item

Takes convertible plus priceIn and returns sell, the classic "bring me raw material" trade.

{
  "type": "villagertradingplus:process_item",
  "convertible": { "item": "minecraft:dead_tube_coral", "count": 1 },
  "priceIn": { "item": "minecraft:emerald", "count": 5 },
  "sell": { "item": "minecraft:tube_coral", "count": 1 }
}

multi_input

Two inputs, one output. Vanilla has exactly two buy slots, so one of the two inputs is the currency.

{
  "type": "villagertradingplus:multi_input",
  "input_a": { "item": "minecraft:emerald", "count": 5 },
  "input_b": { "item": "minecraft:book", "count": 1 },
  "sell": {
    "item": "minecraft:enchanted_book",
    "enchantments": [ { "id": "minecraft:mending", "lvl": 1 } ]
  }
}

weighted_pool

Picks one of several trades by weight when the offer is generated. Below, the daisy is ten times as likely as the wither rose.

{
  "type": "villagertradingplus:weighted_pool",
  "pool": [
    {
      "weight": 10,
      "trade": {
        "type": "villagertradingplus:sell_item",
        "sell": { "item": "minecraft:oxeye_daisy", "count": 1 },
        "priceIn": { "item": "minecraft:emerald", "count": 1 }
      }
    },
    {
      "weight": 1,
      "trade": {
        "type": "villagertradingplus:sell_item",
        "sell": { "item": "minecraft:wither_rose", "count": 1 },
        "priceIn": { "item": "minecraft:emerald", "count": 8 }
      }
    }
  ]
}

sell_potion

Takes convertible plus priceIn and returns sell, for potion-shaped trades.

{
  "type": "villagertradingplus:sell_potion",
  "convertible": { "item": "minecraft:potion", "count": 3 },
  "priceIn": { "item": "minecraft:emerald", "count": 5 },
  "sell": { "item": "minecraft:splash_potion", "count": 7 }
}

sell_map

Sells a filled map pointing at a structure. structure_id is a structure tag.

{
  "type": "villagertradingplus:sell_map",
  "structure_id": "minecraft:on_woodland_explorer_maps",
  "name": "filled_map",
  "buy": { "item": "minecraft:compass", "count": 1 },
  "priceIn": { "item": "minecraft:emerald", "count": 2 },
  "price_multiplier": 0.2
}

sell_enchanted_tool

Sells a tool with a random enchantment, vanilla-style. The price scales with what was rolled.

{
  "type": "villagertradingplus:sell_enchanted_tool",
  "sell": { "item": "minecraft:diamond_pickaxe", "count": 1 },
  "basePriceIn": { "item": "minecraft:emerald", "count": 2 }
}

sell_specific_enchanted_tool

Sells a tool with a fixed enchantment at a fixed level, a guaranteed result rather than a roll. enchantment defaults to minecraft:fortune, level to 1.

{
  "type": "villagertradingplus:sell_specific_enchanted_tool",
  "sell": { "item": "minecraft:diamond_pickaxe", "count": 1 },
  "basePriceIn": { "item": "minecraft:emerald", "count": 32 },
  "enchantment": "minecraft:efficiency",
  "level": 4
}

sell_enchanted_book

Sells a randomly enchanted book, vanilla-style.

{
  "type": "villagertradingplus:sell_enchanted_book",
  "currency": { "item": "minecraft:emerald" },
  "price_multiplier": 0.2
}

sell_specific_enchanted_book

Sells a book with a fixed enchantment and level. There is no sell field, the item is always a book. enchantment defaults to minecraft:unbreaking, level to 1.

{
  "type": "villagertradingplus:sell_specific_enchanted_book",
  "basePriceIn": { "item": "minecraft:emerald", "count": 20 },
  "enchantment": "minecraft:mending",
  "level": 1
}

sell_enchanted_book_from_list

Sells an enchanted book drawn from a weighted list you define, so you control exactly which enchantments a librarian can offer. Cost is base_cost + cost_per_level * level, multiplied by treasure_multiplier for treasure enchantments.

{
  "type": "villagertradingplus:sell_enchanted_book_from_list",
  "currency": { "item": "minecraft:emerald" },
  "enchantments": [
    { "id": "minecraft:sharpness",  "min_level": 1, "max_level": 3, "weight": 5 },
    { "id": "minecraft:unbreaking", "min_level": 1, "max_level": 3, "weight": 5 },
    { "id": "minecraft:mending",    "min_level": 1, "max_level": 1, "weight": 1 }
  ],
  "base_cost": 2,
  "cost_per_level": 3,
  "treasure_multiplier": 2,
  "price_multiplier": 0.2
}

Conditions

Add a conditions array to any trade to gate it. The default logic is AND; set "logic": "or" on the trade to require only one of them.

Timing matters. Conditions are evaluated once, at the moment the offer is generated as the villager levels up, not continuously. Location conditions (biome, dimension, job_site_block, config_flag) are stable for a settled villager and therefore reliable. World-state conditions (weather, day_night, moon_phase, gamerule) are a snapshot of that moment: a trade gated on night stays available in broad daylight once it has been rolled.

Conditions can be switched off globally with enable_conditional_trades.

Note that biomes, blocks and phases take arrays, while tag, dimension and wood_variant take a single string.

{
  "type": "villagertradingplus:sell_item",
  "sell": { "item": "minecraft:heart_of_the_sea", "count": 1 },
  "priceIn": { "item": "minecraft:emerald", "count": 30 },
  "logic": "or",
  "conditions": [
    { "type": "biome", "tag": "minecraft:is_ocean" },
    { "type": "day_night", "time": "night" }
  ]
}

Pricing

price_multiplier and demand work on any trade and feed vanilla's own price machinery:

• price_multiplier - how strongly reputation and Hero of the Village move this trade's price.
• demand - seeds vanilla's demand tracking. The cost climbs as the trade is used and decays again over time.

Both are scaled server-wide by trade_price_multiplier_scale (swing size) and trade_cost_scale (base cost). Reputation and Hero of the Village discounts are applied by vanilla on top.

{
  "type": "villagertradingplus:sell_item",
  "sell": { "item": "minecraft:diamond", "count": 1 },
  "priceIn": { "item": "minecraft:emerald", "count": 12 },
  "price_multiplier": 0.1,
  "demand": 10
}

Custom items

Any item stack in any trade type accepts this sugar, no special trade type needed:

{
  "type": "villagertradingplus:sell_item",
  "sell": {
    "item": "minecraft:diamond_sword",
    "name": "{\"text\":\"Excalibur\",\"color\":\"gold\",\"italic\":false}",
    "lore": [ "A blade of legend" ],
    "enchantments": [ { "id": "minecraft:sharpness", "lvl": 5 } ],
    "nbt": "{Unbreakable:1b}"
  },
  "priceIn": { "item": "minecraft:emerald", "count": 40 }
}

Wandering trader trades

Create a datapack with this directory structure:

data/<namespace>/wandering_trader_trades

Any file name works. Instead of the five villager tiers, the wandering trader has two:

• common - level 1. Several are picked, the count is set by trade_offers_wandering_trader.
• rare - level 2. Exactly one is picked.

Set "replace": true to drop the vanilla wandering-trader trades and use only yours. Omit it (or set false) to add on top of vanilla. Every trade type, the conditions block and pricing all work here exactly as they do on villagers.

{
  "replace": false,
  "trades": {
    "common": [
      {
        "type": "villagertradingplus:sell_item",
        "sell": { "item": "minecraft:glowstone_dust", "count": 4 },
        "priceIn": { "item": "minecraft:emerald", "count": 2 },
        "conditions": [ { "type": "day_night", "time": "night" } ],
        "max_uses": 6,
        "villager_experience": 1
      }
    ],
    "rare": [
      {
        "type": "villagertradingplus:sell_item",
        "sell": {
          "item": "minecraft:trident",
          "name": "{\"text\":\"Traveler's Trident\",\"color\":\"aqua\",\"italic\":false}",
          "enchantments": [ { "id": "minecraft:loyalty", "lvl": 3 } ],
          "nbt": "{Unbreakable:1b}"
        },
        "priceIn": { "item": "minecraft:emerald", "count": 30 },
        "max_uses": 2,
        "villager_experience": 1
      }
    ]
  }
}

Ready-made example files

Inside the jar under data/villagertradingplus/available_trade_examples you will find complete, copyable files for the cases a snippet cannot show well:

• full_profession.json - one profession across all five tiers, mixing many trade types.
• conditions_and_pricing.json - conditions and pricing on realistic trades.
• wandering_trader.json - a complete wandering trader file.