AI Players
Type to search documentation.

For pack makers

Play style files

The JSON format of play styles, every key with its default, and the shipped presets.

A play style is a JSON file in a data pack, at:

Path
data/<namespace>/aiplayers/playstyle/<id>.json

Its id is <namespace>:<id>: the file data/mypack/aiplayers/playstyle/builder.json defines mypack:builder. See Data packs for how to package it.

Every key is optional, and a missing key takes the default listed below. The loader is strict, though. An unknown or misspelled key, or a value out of range, makes the whole file fail. A failed file is skipped, /aiplayer profile list shows why, and bots using it fall back to aiplayers:neutral.

A complete example

data/mypack/aiplayers/playstyle/builder.json
{
"display_name": "The Builder",
"weights": { "build": 1.8, "fortify": 1.4, "hunt": 0.0, "explore": 0.5 },
"aggression": 0.0,
"risk_tolerance": 0.3,
"roaming_radius": 96,
"grudge_minutes": 5,
"gear_goal": "iron",
"hoard": { "minecraft:iron_ingot": 36 },
"combat": { "weapons": ["sword"], "retreat_below_health": 0.6 },
"base": { "style": "hut", "walls": true, "lighting": true, "golems": 1 },
"mining": { "strategy": "cave", "ores": ["#c:ores/iron", "#c:ores/coal"] }
}

Top-level keys

KeyTypeDefaultDescription
display_namestring""Human-readable name.
weightsmap of family → number ≥ 0all 1.0How much the bot cares about each kind of work, see Weights.
aggression0 to 10Engagement range against enemies (aggression × perception_radius), boldness in the gear comparison and eagerness to hunt. 0 never engages or hunts on sight.
risk_tolerance0 to 10.5How much risk (threats, distance from home) lowers an objective’s score.
roaming_radius16 to 1024128How far from home the bot explores, gathers and settles.
grudge_minutes0 to 144010How long a grudge lasts. At 0 the bot never holds one, not even for an offense.
offenseslist of theft, vandalism, tramplingall threeWhich offenses in its base a bot holds a grudge for when it sees a neutral player commit them. Theft is opening a recorded chest, vandalism is breaking a block of a house, storehouse, enchanting corner or wall, and trampling is trampling a plot’s farmland. [] answers none, and an unknown offense fails the file.
enemy_memory_minutes1 to 144030How long an enemy sighting is remembered.
gear_goalrung"diamond"The rung of the gear ladder the bot climbs to, and its armor: wood, stone, copper, iron, diamond or netherite (a bare name is the vanilla rung), or a mod’s rung id such as mymod:drill. An id no plugin registered fails the file, naming it. Copper adds copper to the tool ladder, and copper and above also make armor. Diamond and netherite also enchant at the base’s enchanting corner. netherite upgrades diamond gear at a smithing table using ancient debris and a bastion smithing template.
hoardlist or mapnoneStockpile targets, see Hoard.
combatobjectsee belowCombat.
baseobjectsee belowBase.
miningobjectsee belowMining.
farmobjectsee belowFarming and trading.
tradeobjectsee belowFarming and trading.
netherobjectsee belowNether.
endobjectsee belowEnd: whether the bot’s faction goes to the End with it, and how many bots must be ready.
tacticslist[]Special moves the style can use: chest_raid, block_theft, ender_pearl, tnt_trap, potions, invisibility, strip_for_invisibility and elytra. An unknown tactic fails the whole file. See Tactics.

Weights

Weights multiply an objective family’s score. A missing family is 1.0, and 0 turns that kind of work off. The raid family works differently. Its raid and loot_bastion objectives stay off unless the raid weight is listed explicitly (see Tactics).

FamilyObjectives
gatherLogs, food, torches and sticks stockpiles (gather_log, gather_food, gather_torch, gather_stick), sugar cane for the enchanting corner (gather_sugar_cane), fishing (fish), blaze rods at a fortress (gather_rods), the hoard’s crafted items (hoard, see Hoard), and, for a style that goes to the End, the eyes of ender and their pearls (gather_pearls, which then also covers the ender_pearl tactic’s two pearls).
mineCobblestone and coal stockpiles (gather_cobblestone, gather_coal), and dedicated mining for the hoard (mine).
gearTools, shield, bucket and boat (gear_up), armor (gear_armor), dedicated mining for the ore that tools and armor need (mine), the enchanting corner (enchanting_corner) and enchanting (enchant), brewing (brew), the bow and 16-arrow stockpile (gather_bow, gather_arrow), ender pearls for a raider that doesn’t go to the End (gather_pearls), TNT traps (gather_trap), the End trip’s kit (gather_kit) and firework rockets for a bot holding an elytra (gather_rockets).
buildBuilding, furnishing and repairing the house (establish_base), looking for a place to live (settle), storehouses (expand_base), and the Nether camp shelter (make_camp).
farmCrop fields, bone meal, the soul sand wart plot, and animals (farm).
tradeSelling, buying, trading up and handing out workstations (trade).
fortifyWalls or the fortress, yard lighting, the bush ring, the lava moat, the decoy, golems (fortify).
huntHunting remembered enemies (hunt_enemies).
exploreExploring (explore).
raidScouting enemy bases (scout), raiding them (raid), and looting Nether bastions (loot_bastion). scout and raid need the chest_raid tactic; raid and loot_bastion also need this weight listed explicitly. A base that was robbed scouts and raids the thief’s faction without either (the counter-raid).
endGoing to the End with the faction (the_end, with end.travel) and back for the outer islands (outer_islands, with end.outer too). Once one of them scores, it ranks above every gear, mine, build and explore objective, whatever their weights. This weight only scales it against the other families.
sabotageReserved for a later update. Accepted, no effect yet.

Surviving, fighting, recovering dropped items after death, orders, the load of held ore (smelt_ore) and storing surplus have fixed priorities and aren’t weighted. Once a bot holds a stone pickaxe, two more needs skip the weights too: a homeless bot’s first house, and a food stock below 16 hunger points. The scoring formula is explained in How the AI works.

Faction roles

A bot’s role in its faction lives outside the play style file. It’s set per bot (/aiplayer set <bot> role) or handed out by the faction (/aiplayer faction roles <id> auto), and saved on the bot’s record. After the file is read, the role multiplies the weights above:

RoleMultipliers
minermine ×2, build ×0.5
farmerfarm ×2, trade ×1.5, mine ×0.3
guardfortify ×2, hunt ×1.5, explore ×0, and it keeps to its base’s yard
raiderraid ×2, explore ×1.5, mine ×0.3 (raid only where the style lists it)
freenone (the default)

A family the file leaves out counts as 1.0 before the multiplier. Under auto, each role goes to the bot whose style weighs its family most (fortify for the guard, farm for the farmer, mine for the miner), so your weights decide who gets what.

Hoard

Extra stockpile targets, counted across the bot’s inventory and its base’s (or Nether camp’s) chests:

List form: 32 of each
"hoard": ["minecraft:diamond", "minecraft:netherite_ingot"]
Map form: explicit counts
"hoard": { "minecraft:iron_ingot": 72, "minecraft:diamond": 8 }

Hoarded ores drive mining (at half the deficit). Listing minecraft:blaze_rod enables gather_rods at a Nether fortress, and listing minecraft:nether_wart (here or in farm.stock) enables the 5×5 soul sand wart plot. Every style with bow in weapons automatically keeps 16 arrows (gather_arrow) whether or not minecraft:arrow is in hoard. While a trading bot knows a smith that sells gear it wants, 32 emeralds join its hoard on their own (trading up). The bot earns them by selling and doesn’t dig for them, unless the hoard names minecraft:emerald itself.

Each hoard item has one filler. An ore’s products, raw or smelted, are mine’s and smelt_ore’s; emeralds are trade’s, blaze rods gather_rods’, gold ingots loot_bastion’s and nether wart farm’s. Every other item (a ladder, TNT, a modded machine part) is the hoard objective’s, which a style gets only when its hoard lists such an item. It fills one item at a time, the first in the file’s order that’s short of its target, at half the urgency of the shortfall: it makes up to a stack of it from what the world gives and stores it in the storehouse.

A plan takes a hoard item from the base’s chests before it makes one, but leaves a reserve there, half the item’s target rounded up. Only gear_up and gear_armor, whose tools and armor the stock is for, and a plan for the item itself may take all of it. A plan that would have to make a hoard item from scratch while the chests hold too few fails with needs <item> stocked instead of searching further, and the bot fills that item next at the full urgency of its shortfall, until it reaches its target or ten minutes pass. That’s how a mod’s ladder of plates and circuits is kept in stock (mod integration).

Combat

Defaults
"combat": {
"weapons": ["sword", "bow"],
"engage_range": 3.0,
"retreat_below_health": 0.5,
"shield_break_with_axe": false,
"hit_and_run": false
}
KeyDescription
weaponsWeapon kinds in order of preference: sword, axe, bow (crossbow and trident are accepted, not used yet). The first melee kind listed is preferred. With bow, the bot makes a bow and shoots from 8 to 16 blocks when it has arrows.
engage_rangeMelee standoff distance, 2.0 to 3.5 blocks. Monsters within 3× this are fought.
retreat_below_healthHealth ratio (0 to 1) below which the bot flees. It re-engages at this plus 0.25.
shield_break_with_axeSwing an axe at a raised shield to disable it.
hit_and_runBack off after each hit until the cooldown is ready.

Base

Defaults
"base": {
"style": "hut",
"walls": false,
"lighting": true,
"traps": [],
"golems": 0,
"structures": {}
}
KeyDescription
stylehut: a house in a base (the default). village_expansion: settle beside the first village found, give villagers workstations and guard them. fortress: a hut, then a cobblestone wall with an overhang, towers and doors around the base, whatever walls says. hidden: a room dug into a hillside behind a sealed tunnel, with nothing in the open (no wall, yard, traps, golems, farm, pen or corner). none: never build a home.
wallsBuild the fence ring around the base (ignored by fortress, which always walls, and by hidden).
lightingLight the house and the base’s yard.
trapsberry_bush: the thorn ring. lava: a lava moat along the foot of a fortress wall (a fence ring gets none). tnt: a decoy chest over TNT in the storehouse. These are defensive traps. A raider’s TNT trap is the tnt_trap tactic instead.
golemsPlayer-built iron golems to keep near the base, 0 to 8.
structuresCustom building templates by kind: house, storehouse. See Custom buildings. A wall entry is an error.

Mining

Defaults
"mining": {
"strategy": "none",
"ores": ["#c:ores/iron", "#c:ores/coal"],
"cave_by_day": false,
"ore_heights": {}
}
KeyDescription
strategynone, strip, branch or cave. Anything but none enables dedicated mining. A cave miner also falls back to a strip mine when no cave is found, and at night digs a dedicated night strip mine inside its lit yard.
oresBlock ids or #tags, in order of preference. The bot digs for the first one a need names that its best pickaxe can break (in the current dimension), and takes the whole vein of any listed ore it breaks. Every #c:ores/<name> tag is an ore the bots know without a plugin (modded ores).
cave_by_dayWhether a strip or branch miner looks for its iron in a cave by day, as a cave miner does, keeping its own mine for the night and for every other ore. The shipped Boomer sets it.
ore_heightsA map of #tag or block id to the height that ore is mined at, over the defaults (coal 96, copper 48, iron 16, lapis 0, gold −16, redstone and diamond −58, ancient debris 15). A block id no block has fails the file; a tag no block carries is logged as an error at every data pack load and ignored.

Farming and trading

Defaults
"farm": {
"crops": ["minecraft:wheat_seeds", "minecraft:carrot", "minecraft:potato", "minecraft:beetroot_seeds"],
"animals": ["minecraft:cow", "minecraft:sheep", "minecraft:pig", "minecraft:chicken"],
"plots": 2,
"stock": { "minecraft:wheat": 32 }
},
"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"]
}
KeyDescription
farm.cropsPlanting items in order of preference; each must plant a crop block or minecraft:nether_wart. The first is sought, the others planted when held. Stems (melons, pumpkins) are refused for now. A mod’s crop in #minecraft:crops with an age and no half needs no plugin; one whose block has no age or has a half fails the file, and one that passes but isn’t such a crop is logged at every load and never sown.
farm.animalsAnimal types for the pen. A pair of one of them seen together, with their food in hand, becomes the bot’s herd. A style that lists minecraft:sheep pens a pair and shears them for its bed’s wool.
farm.plots9×9 crop fields per base, 1 to 4 (the first plot, a 5×5 for food, and the 5×5 soul sand wart plot are separate).
farm.stockCrops to keep, in hand and in chests. Listing minecraft:nether_wart here (or in hoard) builds and tends a 5×5 wart plot. Listing minecraft:bone_meal sets how much meal the bot makes from its bones before a plot visit, when that’s more than its young crops take. No plot grows bone meal.
trade.sellsItems the bot may sell (sticks beyond the eight it keeps).
trade.buysItem ids or #tags the bot may buy (empty buys nothing). Emeralds are never bought. The list also bounds the gear trading up may buy.
trade.professionsProfessions to hand workstations out for, in order (a village_expansion style gives the first profession no villager holds yet); empty hands out none.

Nether

Defaults
"nether": {
"travel": false,
"min_tier": "diamond",
"lava_margin": 2,
"truce_piece": "minecraft:golden_boots",
"camp": true,
"loot_bastions": true,
"potions": {},
"spare_obsidian": 10
}
KeyDescription
travelWhether the bot travels to the Nether and builds its base a Nether portal.
min_tierThe rung of pickaxe required in hand before starting a Nether trip: wood, stone, copper, iron, diamond or netherite (a bare name is the vanilla rung), or a mod’s rung id.
lava_marginBlocks of clearance (0 to 16) that Nether paths and tunnel cuts keep from lava.
truce_pieceGold armor item worn in the Nether to keep piglins calm.
campWhether the bot founds a 3×3 shelter and chest camp beside its arrival portal in the Nether (false carries everything home).
loot_bastionsWhether the bot loots known bastions (loot_bastion, also requires weights.raid listed).
potionsMap of vanilla potion id to target count, kept in stock and brewed at a brewing stand (brew), e.g. {"minecraft:fire_resistance": 2, "minecraft:strength": 2}. The bot needs the potions tactic to drink them. minecraft:healing is brewed too and drunk in a fight at the retreat line, and stow keeps at least two healing potions whatever the count.
spare_obsidianObsidian (0 to 64) carried into the Nether with a flint and steel to repair or rebuild the return portal.

End

Defaults
"end": {
"travel": false,
"party": 2,
"eyes": 16,
"kit": { "blocks": 128, "minecraft:bow": 1, "minecraft:arrow": 64, "food": 16, "pickaxe": 1,
"minecraft:water_bucket": 1, "minecraft:torch": 4 },
"outer": true,
"outer_kit": { "minecraft:ender_pearl": 4, "blocks": 128 },
"hop_gap": 64,
"hop_blocks": 192,
"search_radius": 512,
"flight": 200,
"rockets": 8
}
KeyRangeDescription
travelbooleanWhether the bot goes to the End with its faction at all. The difficulty’s end_dragon must be true too.
party1 to 16How many of the faction’s bots must be ready before it goes. A faction with fewer bots needs all of them. Also sets the second trip’s party.
eyes12 to 64The party’s stock of eyes of ender. Each member carries eyes over party, rounded up, and at least 4.
kitmap of item to countWhat each member carries on the trip. It counts for readiness, gather_kit gathers it, and the bot keeps it in hand. A key is an item id or one of blocks (cobblestone or end stone), food (cooked food) and pickaxe (a spare pickaxe of the gear goal’s tier). A style’s kit replaces the default whole, and a key that isn’t an item fails the file.
outerbooleanWhether a style that travels goes back for the outer islands once its faction’s End is finished.
outer_kitmap of item to countWhat each member carries out there beyond kit, with keys in the same form as kit. When both name the same key, the bot wants their sum (256 blocks by default).
hop_gap1 to 128The widest gap of void the leader’s search for an end city bridges in one leg, in blocks.
hop_blocks0 to 512The blocks the leader lays over the whole search; 0 bridges nothing.
search_radius64 to 2048How far from its arrival on the outer islands the search for a city goes before it gives up, in blocks.
flight0, or 32 to 2000The shortest leg a bot holding a sound elytra flies, in blocks. At 0 the bot never flies. Applies to any bot with an elytra, travel or not.
rockets0 to 64The firework rockets a bot holding a sound elytra crafts (gather_rockets) and keeps. Applies to any bot with an elytra.

Tactics

Tactics are the style’s special moves for raiding, drinking potions and flying:

flanker.json (excerpt)
"tactics": ["chest_raid", "block_theft", "ender_pearl", "tnt_trap", "potions", "invisibility", "elytra"]
TacticEffect
chest_raidWakes up the Overworld raid objectives. The bot scouts for enemy factions’ bases (scout), watches suspected ones until they’re confirmed, and raids the chests of confirmed ones (raid). The raid objective also needs weights to list raid explicitly. Without it, the bot scouts but never raids.
block_theftAdds two ways into a walled base. The first is a tunnel dug under the wall straight to the chest (with a stone or better pickaxe, prepared while the raid waits for dusk). Failing that, the bot breaks a single fence post, fence gate or fortress door with a pickaxe and pockets it.
ender_pearlAdds a way over the wall, by throwing an ender pearl into the yard. The bot keeps two pearls in hand and hunts endermen to restock (gather_pearls, family gear). For a style that also goes to the End the family is gather, and the bot keeps the two beside its share of eyes.
tnt_trapTraps the looted chest with TNT and a stone pressure plate. When the floor in front of the chest won’t do, it traps the enemy’s gate nearest the chest instead. A raid that came in by tunnel lays no trap. The bot keeps one TNT and one plate in hand and crafts what’s missing (gather_trap, family gear). TNT takes five gunpowder (from a creeper hunt with a bow) and four sand, and the plate takes two stone.
potionsLets the bot drink potions it holds: Fire Resistance before entering a portal to the Nether or when on fire, Strength at the start of a tough fight, Healing at the retreat line of a fight, and Swiftness (plus Invisibility, with invisibility) on a raid’s approach. Any style eats a golden apple in a fight, tactic or not.
invisibilityOn a raid’s approach (with potions), drinks an Invisibility potion when wearing no armor, reducing the distance at which defenders spot the raider from 16 blocks to 8.
strip_for_invisibilityBefore drinking Invisibility on a raid’s approach, takes off all worn armor into the inventory, and puts it back on when leaving the looted chest (or if a fight starts or the raid is spotted).
elytraA raider that holds a sound elytra (and the rockets) flies its way in. It lands 24 blocks outside the enemy base, away from the defenders, and flies home from its landing. A scout flies one circuit over the enemy’s sightings instead of walking (raiding by air). The tactic changes neither a raid’s urgency nor its odds.

An unknown tactic name fails the whole file, like any other strict-loader mistake.

The shipped presets

data/aiplayers/aiplayers/playstyle/neutral.json
{
"display_name": "Neutral",
"weights": {},
"aggression": 0.0,
"risk_tolerance": 0.5,
"roaming_radius": 128,
"grudge_minutes": 10,
"gear_goal": "diamond",
"hoard": [],
"combat": {
"weapons": ["sword", "bow"],
"engage_range": 3.0,
"retreat_below_health": 0.5,
"shield_break_with_axe": false,
"hit_and_run": false
},
"base": { "style": "hut", "walls": false, "lighting": true, "traps": [], "golems": 0 },
"mining": { "strategy": "none", "ores": ["#c:ores/iron", "#c:ores/coal"] },
"tactics": []
}

Last updated Nov 9, 2026