AI Players
Type to search documentation.

Building an economy

Villages and trading

How bots discover villages, trade with villagers, and why the Boomer moves in next door.

Bots know a good deal when they see one. They remember the villages they find, sell what they don’t need and buy what’s cheaper to trade for than to make.

Discovering villages

When a bot sees a villager, it remembers the village: where its center (the bell) is, who lives there, what jobs they have, and what each villager offers once the bot has looked at their trades. It shares all this with its faction, so its friends know about the village too.

A bot that likes trading and doesn’t know any village nearby goes out exploring to find one.

Selling

A bot sells its surplus (whatever it has beyond what it wants to keep) to villagers who want it. It walks up to the villager, opens the trading screen and makes the trades one at a time, like you would. By default bots sell crops, coal, sticks, rotten flesh and string.

Buying

Whenever a bot needs something, it weighs mining and crafting it against buying it with emeralds from a villager it knows. If the villager is closer than the ore, it buys. By default, bots buy bread, arrows, tools and armor. They only buy from offers they’ve already seen, and never buy emeralds.

Trading up

A village is the fastest legit road from iron to diamond, and a trading bot knows it. While it knows an armorer, a toolsmith or a weaponsmith that sells (or could sell, once leveled up) an iron or diamond piece it still lacks, up to its gear goal, it does three things:

  • It starts hoarding emeralds (32 of them). It sells more eagerly to get them (sticks, crops, coal and string, and a fletcher pays an emerald for 32 sticks) and stows them with its other valuables. It still won’t dig for emerald ore unless its own hoard names emeralds.
  • It buys its next piece instead of making it. Its tool ladder buys the next tier’s pickaxe, sword or axe from a recorded offer, one piece at a time in that order, before it waits for its mine. An armor piece is bought whenever the offer is nearer than the ore. Either way, the bot puts the piece on right away.
  • When the smith’s offers don’t have the piece yet, it levels the smith up by selling, never by buying things it doesn’t want. A visit trades each offer once, and the new offers a level-up brings are recorded on the spot. Then the villager is left alone for half a day until its offers restock, so prices stay low.

The shipped Boomer is the one that does this most, since it lives next to its village and gives its villagers the smithing jobs first.

The Boomer moves in next door

A bot with the Boomer play style settles next to a village instead of only visiting:

  • If no village is in sight on its first day, it raises a starter hut as soon as it has stone tools, so it has a roof over its head. Once it discovers a village near home, it founds its permanent base beside the village, on natural ground and clear of the village’s streets, fields and buildings. If three in-game days pass without finding a village, its starter hut becomes the base.
  • It gives jobless villagers a job by placing a workstation next to them, one profession after another. An armorer comes first (a blast furnace), then a toolsmith (a smithing table), a farmer and a fletcher. If no villager takes the workstation, the bot picks it up and tries again later.
  • It protects its villagers, fighting monsters that come within 8 blocks of them.

Bots trade fairly: they use the same trading screen you do, pay the same prices and are bound by the same restocks.

Technical details

Trading settings in the play style

Every key is optional. These are the defaults, which every shipped play style uses:

playstyle.json (excerpt)
"trade": {
"sells": ["minecraft:wheat", "minecraft:carrot", "minecraft:potato", "minecraft:beetroot",
"minecraft:coal", "minecraft:stick", "minecraft:rotten_flesh", "minecraft:string"],
"buys": ["minecraft:bread", "#minecraft:arrows", "#minecraft:swords", "#minecraft:pickaxes",
"#minecraft:axes", "#minecraft:hoes", "#minecraft:shovels", "#minecraft:head_armor",
"#minecraft:chest_armor", "#minecraft:leg_armor", "#minecraft:foot_armor"],
"professions": ["minecraft:armorer", "minecraft:toolsmith", "minecraft:farmer", "minecraft:fletcher"]
}
  • sells: what the bot may sell (sticks only beyond the eight it keeps; nothing crafts sticks just to sell).
  • buys: item ids or #tags the bot may buy. An empty list buys nothing. It also bounds what trading up may buy.
  • professions: jobs the bot wants in its village, in order. An empty list never hands out a workstation.

Village settling is the village_expansion base style. See Play style files.

What counts as surplus

The surplus is everything in sells above the bot’s reserves: its stockpile targets, its farm.stock and the food its herd needs for breeding. Before a bot has opened a villager’s trading screen, it guesses what that villager might buy from its profession’s possible trades. An offer that was out of stock is assumed restocked half an in-game day later.

Settling rules

A village_expansion bot settles beside the first village it knows within its roaming radius. Once it holds a stone pickaxe with no village in reach, it raises its starter hut right away. That starter hut doesn’t found a base, but the house it later builds beside the village does. After three in-game days of play without a village, its starter shelter founds the base where it stands. A workstation that no villager claims is taken back and placed again after 2400 ticks (two minutes).

Trading up in detail

The wanted gear is every iron and diamond sword, axe, pickaxe and armor piece up to the gear goal that the bot neither holds nor wears at that tier or better, within buys (villagers sell no copper or netherite gear). A wanted trader is an armorer, toolsmith or weaponsmith whose recorded offers, or whose profession’s trade sets up to master, give one. This is decided by the gear goal (not the current pickaxe), so leveling starts early. The emerald target is 32 (or the style’s own hoard count when higher). Any shortfall raises the trade objective’s sales once a sale is affordable, and mine leaves emeralds alone. A smith is leveled only below master and only while its offers hold no wanted piece. A visit that leveled it marks it for the restock period in transient memory, so a restart costs at most one extra visit. Limits: a bought pickaxe can leave that tier’s sword and axe unmade for a while, and leveling a master armorer from novice by coal alone takes days.

Inspecting villages

/aiplayer info <bot> lists known villages on its villages: line. Operators can trigger a trading run with /aiplayer debug <bot> task trade.

Known limits
  • Bots only buy offers they’ve seen, so a villager who wants none of their goods never sells them anything.
  • No wandering trader, villager breeding, zombie villager curing or reputation yet, and no enchanted books from librarians until bots own an anvil.
  • Villages are remembered forever, even after they’re gone.

Last updated Nov 9, 2026