04 – Examples Guide

PostedNovember 4, 2026

UpdatedNovember 4, 2026

ByRed

Real trades taken from the mod’s own files (all values already tested in game). Full reference of the options: Configuring-Trades.md.

1. Wood family (buy)

The lumberjack buys one log shuffled from any wood type — one entry covers the 8 woods with <wood>_log (bamboo/crimson/warped have their own names and stay out):

Before (repetitive):

{ "cost": { "id": "minecraft:oak_log", "count": 16 }, ... },
{ "cost": { "id": "minecraft:spruce_log", "count": 16 }, ... },
{ "cost": { "id": "minecraft:birch_log", "count": 16 }, ... }

After (family):

{
  "cost": { "family": "log", "count": 16 },
  "result": { "id": "minecraft:emerald", "count": 1 },
  "max_uses": 10,
  "xp": 2
}

In game: the NPC shuffles one concrete log (e.g., Cherry Log) and the player must deliver exactly that one. With /visitors reloadtrades the requirement may become a different wood.
Species filter: use variants — { "family": "log", "variants": ["oak", "spruce", "birch"], "count": 16 } (that’s what the default visitor uses).

2. Color family (buy, any color)

The glassworker buys 16 dyes in any color:

"cost": { "family": "dye", "count": 16 }

Without color/colors, the shuffle uses all 16 colors of DyeColor — the same works for wool, banner, terracotta, candle…

3. Restricted color family (sell)

Selling stained glass only in the listed colors:

"result": { "family": "stained_glass", "colors": ["white", "light_gray", "gray", "black"], "count": 3 }

Single fixed color: replace the array with "color": "red".

4. Fixed variant (sell)

Change the species being sold with variant:

"result": { "family": "sapling", "variant": "cherry", "count": 1 }

The same family without variant ({ "family": "sapling", "count": 1 }) shuffles among the 7 species of SAPLING_TYPES (mangrove is mangrove_propagule).

5. `one_of` — flower group (buy)

The default visitor accepts one flower shuffled out of 4:

{
  "cost": { "one_of": ["minecraft:dandelion", "minecraft:poppy", "minecraft:blue_orchid", "minecraft:lily_of_the_valley"], "count": 12 },
  "result": { "id": "minecraft:emerald", "count": 1 },
  "max_uses": 3,
  "xp": 2
}

The buy requires the item shown on the offer (ItemCost doesn’t accept tags).

6. `one_of` — consumables (sell)

A food tray: the item being sold is shuffled per offer:

{
  "cost": { "id": "minecraft:emerald", "count": 1 },
  "result": { "one_of": ["minecraft:bread", "minecraft:apple", "minecraft:cookie",
                "minecraft:cooked_beef", "minecraft:melon_seeds"], "count": 4 },
  "max_uses": 12,
  "xp": 1
}

7. Data components (personalized item)

components accepts any vanilla data component — enchantments, names, damage. In costs, the component is part of the charge: the player must deliver exactly that personalized item.

Enchanted book (Sharpness III):

"result": {
  "id": "minecraft:enchanted_book",
  "count": 1,
  "components": {
    "minecraft:stored_enchantments": { "levels": { "minecraft:sharpness": 3 } }
  }
}

Named, damaged sword (a unique collector’s item):

"result": {
  "id": "minecraft:diamond_sword",
  "count": 1,
  "components": {
    "minecraft:custom_name": "Old Relic",
    "minecraft:damage": 120
  }
}

8. Special types (random result)

In the random_* types, type replaces result and the cost must be emeralds — the count becomes the base price:

{ "type": "random_enchanted_book", "xp": 15 }

An assortment rocket in the showcase:

{
  "type": "random_rocket",
  "cost": { "id": "minecraft:emerald", "count": 2 },
  "max_uses": 12,
  "xp": 5
}

The 4 available types: random_enchanted_book, random_suspicious_stew, random_firework_star, and random_rocket (details in section 5 of Configuring-Trades.md).

9. Full example file

Putting everything together — a valid trades file in the style of the mushroom gardener (mycologist), with a one_of buy, a filtered wood buy, and mixed sells:

{
  "variant": "mycologist",

  "buys": {
    "select": 3,
    "trades": [
      {
        "cost":   { "one_of": ["minecraft:crimson_fungus", "minecraft:warped_fungus",
                    "minecraft:glow_lichen", "minecraft:moss_block"], "count": 12 },
        "result": { "id": "minecraft:emerald", "count": 1 },
        "max_uses": 3,
        "xp": 2
      },
      {
        "cost":   { "family": "log", "variants": ["oak", "birch"], "count": 12 },
        "result": { "id": "minecraft:emerald", "count": 1 },
        "max_uses": 4,
        "xp": 2
      }
    ]
  },

  "sells": {
    "select": 2,
    "trades": [
      {
        "cost":   { "id": "minecraft:emerald", "count": 3 },
        "result": { "family": "sapling", "count": 2 },
        "max_uses": 5,
        "xp": 2
      },
      {
        "cost": { "id": "minecraft:emerald", "count": 6 },
        "type": "random_enchanted_book",
        "xp": 10
      }
    ]
  }
}

Rules baked into the example:

type has no result — the result is shuffled at sale time.
Each pool’s select chooses how many offers are shuffled from the total listed; components combined with family/one_of isn’t supported in this version.
Save as config/visitingvillagers/trades/mycologist.json and apply with /visitors reloadtrades.

Reminder

After editing the JSON in config/visitingvillagers/trades/, reload with:

/visitors reloadtrades

Visiting Villagers