Minecraft Villager Trade Guide

Why custom villagers matter on a story server

A custom villager is not just a cheaper shop GUI. It is an in-world delivery system. The player walks up to a person, not a menu, and the exchange can carry tone: a blacksmith selling weapons, an archivist trading clues, a customs officer checking papers, or a faction merchant taking rare tokens instead of emeralds.

That is why this builder matters. A summon command that defines appearance, behavior, and trade payload all at once becomes painful very fast if you try to type it by hand.

What the tool does

The builder creates a long /summon minecraft:villager command. The command defines the villager's appearance and behavior, then adds an Offers block with a list of Recipes.

Main structure

Every trade has at least two item stacks: buy and sell. If the price uses two items, the command also includes buyB.

Offers:{
  Recipes:[
    {
      buy:{id:"minecraft:emerald",count:8},
      sell:{id:"minecraft:paper",count:1},
      maxUses:999999
    }
  ]
}

Once you read it this way, the builder becomes much less mysterious. It is really arranging three layers: villager identity, trade economics, and item syntax.

Three version modes are there for a reason

The builder shows three version choices because the item syntax changed twice, not once. Minecraft 1.20.5 moved item data to Data Components, and Minecraft 1.21.4 refined the modern format again for fields such as custom_model_data.

• 1.21.4+ still uses count and components, but newer component payloads can become more structured. In this builder that mainly matters for how minecraft:custom_model_data is written.
• 1.20.5-1.21.3 already uses count and components, but keeps the simpler earlier component syntax.
• Before 1.20.5 uses Count and the older tag compound with legacy NBT-style item stacks.

So the three choices are not cosmetic. They decide how the buy, buyB, and sell stacks are serialized inside the summon command. The command block helper mirrors the same version split mostly for clarity and consistency, even though the plain /give command for a command block changes much less than the villager trade payload itself.

{id:"minecraft:paper",count:1,components:{"minecraft:custom_model_data":{floats:[12f]}}}
{id:"minecraft:paper",count:1,components:{"minecraft:custom_model_data":12}}
{id:"minecraft:paper",Count:1b,tag:{CustomModelData:12}}

Villager fields

• Profession controls the villager outfit and work style.
• Biome type changes the visual variant: plains, desert, taiga, swamp, and more.
• Level changes the badge shown on the villager's belt.
• NoAI keeps the villager in place, which is useful for server NPC shops.
• Invulnerable protects the trader from accidental damage.

Trade fields

• Buy item is the main price, such as emerald.
• Second buy item is an optional extra price, such as diamond or a quest item.
• Sell item is the reward the player receives.
• CustomModelData lets the villager sell an item with a custom resource-pack model.
• Max uses controls how many times the trade can be used.

How to use it on a live server

1. Choose the syntax mode that matches the server version.
2. Lock the villager identity first: profession, biome, level, and whether the NPC should move.
3. Build one trade completely before cloning the pattern into multiple rows.
4. Test the generated summon command once in-game before giving it to staff or hiding it inside data files.
5. If the command grows beyond chat limits, move straight to a command block.

Using it on a server

Copy the generated command into a command block or an operator console.

Important: if the command is longer than 256 characters, use a command block. Minecraft chat can cut off longer summon commands.

Practical ideas

• A pass vendor that accepts quest tokens.
• An NPC blacksmith that sells CustomModelData weapons.
• An archivist that exchanges found documents for clues.
• A faction trader with items locked behind story currency.

Common mistakes

• Picking the wrong version mode and blaming the trade logic when the real problem is item syntax.
• Testing five trades at once instead of proving one row first.
• Leaving NoAI off for a stationary NPC and then chasing the villager around the build.
• Forgetting that long summon commands belong in command blocks.
• Using CustomModelData on sold items without confirming the pack-side visual hook exists.

FAQ