VillagersTradingPlus

VillagersTradingPlus is a library that lets mods and datapacks define villager trades in JSON.

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

Versions: 1.20 to 1.20.1, 1.21 to 1.21.1, 1.21.6 to 1.21.8, 1.21.11, 26.1.2, 26.2, 26.3

Support my work on

What this is

VillagersTradingPlus 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.

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.
• 16 trade types (15 on 26.1 and newer), from a plain item sale to weighted pools, structure maps and enchanted books drawn from a weighted list you define. Trades can also use the vanilla merchant_predicate format, for example to limit a trade to one villager type (1.21.1 and newer).
• 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, plus a buying tier on 1.21.8 and newer (on 1.21.1 only with the Trade Rebalance experiment).

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 allow_ options are off by default. The catalog is open to any player. The re-roll buttons and the level control need the permission level in reroll_permission_level. 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 jar ships every vanilla trade in this format under data/villagertradingplus/vanilla_trades. Copy a file into your datapack to replace a profession.

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. sell.count sets the stack size.

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

sell_map

Sells a filled map pointing at a structure. structure_id is a structure tag. name is a translation key; leave it out to keep the vanilla map name.

{
  "type": "villagertradingplus:sell_map",
  "structure_id": "minecraft:on_woodland_explorer_maps",
  "name": "filled_map.mansion",
  "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 up to three:

• buying - the offers where the trader buys something for emeralds (1.21.8 and newer; on 1.21.1 only with the Trade Rebalance experiment). A file without this tier keeps the vanilla buying offers.
• 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. A tier without custom trades keeps the vanilla trades, even with replace set to true.

{
  "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.

Community

Questions, screenshots and help on Discord.

More mods by LithiumPlus

• The Graveyard: structures, mobs, blocks and a boss with a graveyard theme. Forge version: The Graveyard (Forge).
• VillagersPlus: new villager types, trades and workstations.
• Nyctophobia: dark, foggy and unsettling biomes for the Overworld.
• DataDrivenVillagers (CurseForge): create and change villager professions from JSON files or an in-game editor.

VanillaTales is a collection of small, independent mods that add little stories to vanilla content. Install only the ones you want. The links go to CurseForge.

• Golem Patrol: iron golems patrol by day, stand watch by night and rally to a ringing bell.
• Zombie Sieges: turns a vanilla zombie siege into a real event, with a ringing bell, a boss bar and two waves of zombies.
• Sherd Stories: gives every decorated pot a title and the story of where its sherds were found.
• Ghost Crews: gives every shipwreck a name and a crew of drowned that guard it until it is looted clean.
• Illager Scouts: a pillager scout watches your village and warns you two days before a patrol arrives.
• Occupied Villages: some new villages spawn already occupied by an illager garrison you can liberate.
• Bonded Pairs: binds two mobs from the same spawn group into a pair that avenges each other.
• Raid Aftermath: villagers repair the damage a raid or an explosion left in the village.
• Wayfarer's Landmarks: shows a title and helpful icons when you enter a structure.