For server admins
Inspecting and debugging bots
Read a bot's info report, measure AI performance, and drive bots by hand for testing.
AI Players has a set of operator tools to see what a bot is thinking and to make it do one specific thing. With the
client add-on on your own game, the same report shows on the management
screen’s Bots tab, and the debug overlay draws a bot’s path,
its work block and its info lines in the world.
The info report
/aiplayer info <bot> prints the bot’s settings (status, faction and role, style, difficulty, respawn mode,
cheats, skin and custom skin: 1a2b3c4d (slim) while it wears one, position, deaths, health) followed by what’s on
its mind. The lines you’ll see most:
| Line | Example | Meaning |
|---|---|---|
faction: | red, role: guard (auto) | Its faction and its role, with (auto) while the faction hands roles out by size. |
armor: | iron_helmet, iron_chestplate, iron_leggings, golden_boots, truce: golden_boots | Worn armor pieces head to feet, and in the Nether whether the piglin truce holds (truce: off without gold). |
effects: | fire_resistance 2:40, strength 1:10 | Active potion effects and their remaining time (shown after armor: while an effect is active). |
objective: | gear_up (score 0.94) | The running objective and the score it was chosen at. none means nothing is worth doing, auto off means decision making is off, and establish_base (forced) means it was started with debug <bot> objective. A raiding bot reports its progress on the same line, like raid (score 0.90), raid: reds loot via tunnel, spotted by Ann. It reads raid: reds prepare while it waits for dusk and raid: reds approach (flying) in the air. A bastion looter shows something like loot_bastion leave, spotted by Piglin. An End trip shows its step, like the_end (score 0.90), end: fight. The steps are calling, waiting for the party, fill, travel, fight and egg, plus gateway, find_city, raid_city, ship and return on the second trip. A city raid reads end: raiding the city (3 of 5 chests, 4 shulkers killed). |
| task line | obtain 1 wooden_pickaxe (step 5/5) > craft wooden_pickaxe 0/1 (table) | The task tree the bot is running, from the outermost task in. In a fight it reads fight Zombie (melee, health 0.80), where the state is approach, rush, pursue (chasing a runner), melee, ranged or heal. A pack fight shows tower (top, 2 placed) or doorway (hold). Other examples are dusk hunt string x1 (at dusk, for a bow), night hunt string x3 (a shield holder out for spiders at night), night walk for ender_pearl x3 (hunting pearls), enchant the chestplate (at the enchanting table), ... wall off skeleton, ... wall in (3 open) and ... walled in (hiding from an archer or walling in underground), ... watch after the respawn (waiting monsters out after a death) and, for a cave miner, cave mine iron (0 ore, 0 trips, 2 unreached, 2 failed, 640 idle), fell back to the strip or climb to (pillaring up to ore). In the End you’ll see things like slay the dragon (crystal) > shoot the caged crystal at 42, 79, 0 (aim), take the egg (punch, 2 punches) and loot the ship (elytra) or (down) (moving to another look-out). |
| last failure | establish_base (needs 2 more building blocks), 340 ticks ago | The last objective that failed, why, and how long ago. stalled means the stall guard ended it, and thrash means it kept ending within two seconds of starting. pending in the furnace ... is a bot waiting for a smelt it loaded and left. no cave reached means a cave miner gave up on its caves for a strip. needs <item> stocked means a plan wanted a hoard item the chests are short of, which the bot fills next. time limit of 400 ms (80.0 ms wall) means the difficulty’s limit cut a path search short (it’s retried, and not held against the bot). |
stuck: | relocate | Shown while the escape ladder is climbing: fail and cool, walk out, relocate, relocate again or help call. |
travel: | to the_nether (portal) | Shown while traveling through a portal (to overworld (haul) when hauling camp chests home). After a trip gate fails it shows refused: <reason> instead. |
| memory | house 5x5, bed, workstations, sightings | What the bot remembers about its home and surroundings. |
base: | (100, 64, -20), 2 buildings, 4 chests, portal: (108, 64, -20) lit, nether (14, 70, -3) | Its base: anchor, buildings, chests and Nether portal. |
corner: | table at (x, y, z), 2/15 shelves | The base’s enchanting corner, once its table stands. |
camp: | the_nether (14, 70, -3), 2 chests | Its faction’s camp beside the arrival portal in another dimension, one line per camp. |
mine: | strip at (x, y, z), face (x, y, z) east, 212 dug, for minecraft:diamond | Its current mine. A miner’s night strip inside the yard shows beside it as night mine:, and a mine dug from a night burrow shows as a strip at the burrow’s floor. |
box: | 12/27 stacks | The shulker box the bot carries on a trip and how full it is (the carried box). |
farm: | plot 9x9 (76/76 sown, 12 ripe), wart plot 5x5 (25/25 sown), pen 7x7 (4 cows) | Its crop fields, soul sand wart plot and animal pen. |
potions: | fire_resistance 2/2, strength 0/1 | For styles with nether.potions: held and base-chest counts over target. |
villages: | The villages it knows. | |
structures: | fortress (80, 68, -110) 1 spawner, 2 gardens, bastion (-60, 72, 40) 3 chests, warped_forest (120, 70, 30), end_city (1290, 81, -340) 5 chests | The Nether fortresses, bastions and warped forests the faction has discovered, plus its end cities. |
end: | stronghold (120, 30, -400), portal lit, dragon alive; ready | Shown for a style that goes to the End or a bot under an end order. It has where the bot is in the End, the faction’s End record, and whether the bot is ready or what it lacks (not ready: tier, enchantments). Once the End is finished, it shows the second trip’s record after outer:, then ready for the outer islands or what’s missing. A bot on the End’s platform with nothing to bridge with reads stranded, no blocks to bridge. See what info shows. |
stronghold: | (120, 30, -400), portal room (118, 28, -390) or bearing 212°, 2 legs | The stronghold as the faction knows it, or the leader’s latest eye bearing and the legs walked. |
eyes: | 5 of 8 (3 pearls, 10 powder) | The bot’s share of eyes of ender and what it holds toward the rest (a rod counts as two powder). |
flight: | flying to (120, -80) or landing | Shown while the bot flies an elytra. |
fortify: | wall 112/116 (building), gates 4, dark 3, golems 1/2, bushes 40/108 | Its defenses, for styles that use any. |
enemies: | Ben 30 blocks away (now, weight 1.0), Cal at (120, 64, -30) (4 min ago, weight 1.0) | Enemy sightings, with the gear weight each one had. |
enemy bases: | Reds at (120, 64, -30), 3 chests, 4 gates, 2 golems, trap at (118, 64, -27), guard 2.9 (seen 4 min ago) | Bases of enemy factions the bot’s faction has learned, newest first, with the traps it laid there and the guard that spotted a raider. An unconfirmed record is marked (suspected). Only printed when the bot knows one. |
grudges: | Alice (9 min, theft) | Grudges, how long they have left, and the offense that earned them when it wasn’t a hit. |
order: | defend (100, 64, -20) from Alice, 14 min left; queued: bring cobblestone 8 (last: done) | Its orders (assist Ann from Ann while answering a call for help). Shown for a dead bot too. |
/aiplayer info <bot> chests lists the base’s chests one per line, with their contents (read live when the chunk
is loaded, otherwise as last seen). Each Nether camp’s chests follow under its camp: line.
/aiplayer info <bot> enemy bases does the same for the other side. It prints each known enemy base the way its
enemy bases: line shows it, then one line per chest it knows there and one per gate. A chest only shows an item
count if a raid or the reveal cheat looked inside. Without a known base it prints none.
Performance stats
/aiplayer stats shows how much time the AI takes:
- First, the scheduler’s budget in force on the last tick (
ai_tick_budget_ms_per_bot× live bots, capped atai_tick_budget_ms), the per-bot figure, the live bots, the cap and how many ticks ran out of it. It also shows the pathfinder’s queue and nodes per second, and how many path searches the time limit has cut since the server started. A cut search ends with the part of the path it found. Lots of cuts mean the bot clock or the difficulty gives searches too little time on this machine. - Second, the bot clock in force and the path search limit it
gives (the same line
/aiplayer tick queryprints). - Third, the client add-on’s sync pass: its time on the last tick and on average since the server started (outside the AI budget), how many players watch something and how many bots are on overlays.
- Each bot’s brain time (last tick and average) and its current objective.
- The time spent building world snapshots for path searches.
- Perception load per bot, and the time the knowledge build took at startup.
If the budget runs out on many ticks, bots think more slowly (they never lag the server beyond the budget).
Reduce the number of bots or adjust ai_tick_budget_ms_per_bot and ai_tick_budget_ms in the
server configuration. The budget is a share of each server tick, whatever
the bot clock says. The clock only scales the search limit.
Debug logging
Set "debug_logging": true in the server configuration and
run /aiplayer config reload. Every bot then writes a trace to logs/debug.log. It logs a line on each change of
objective (Ann objective: mine -> survive (score 0.85)) and a line when each task ends, with the step it stood at
and why it ended (Ann task ended: gear_up (selector > sequence > craft stone_pickaxe) -> failed (no cobblestone)).
Every 30 seconds it also writes a state line with what info shows plus the bot’s items. Logging costs nothing
while it’s off.
To report a misbehaving bot, send:
- the output of
/aiplayer info <bot>and/aiplayer stats, taken while it misbehaves; - the
(aiplayers)lines oflogs/latest.log(the startup line names the build and its commit); logs/debug.log, with the key turned on before the bot went wrong so the trace covers the minutes leading up to it.
Objectives
/aiplayer debug <bot> objective <id> turns decision making off and runs one objective’s work once. info shows
its result. /aiplayer debug <bot> auto on hands control back. The ids:
| Id | Family (weight key) | What it does |
|---|---|---|
survive | (fixed) | Eat, heal, flee, take cover from or wall off archers, wall in underground, dig free when buried, drink Fire Resistance, pour the water bucket or step off fire/lava, shelter or burrow at night (and mine from the burrow or under the house’s floor), wait monsters out after a respawn, sleep when every player sleeps, surface for air, escape enclosures, walk out of a repeated stall, climb the escape ladder when stuck, and collect a furnace it loaded and left (survive[collect]). |
fight | (fixed) | Fight the best target: hit-and-step-back creeper fights, rushing archers, chasing runners, raising shields, healing at the retreat line, fighting a pack from a tower or a doorway, and looting defeated players. |
follow_order | (fixed) | Carry out an ally’s order (the assist order of a help call included). |
recover_drops | (fixed) | Walk back to the last death spot within 160 blocks in the same dimension (digging and building the way if need be, and at night within 64 blocks for a bot with no pickaxe) and pick up dropped items before they despawn. |
smelt_ore | (fixed) | At dusk, cook the raw meat or fish the bot carries and take it out, then load the raw ore it carries into a furnace with fuel and leave it. By day, the same load at a low urgency for three ore or more. At any hour, smelt the three ore of its next pickaxe where it stands and make the pickaxe. |
gear_up | gear | A sword before anything else when the bot holds no sword and no axe, then the next rung’s pickaxe first, then the shield (on the iron rung, from the next ingot), the sword and the axe from one furnace load (or buy one from a known smith), the miner’s spare pickaxe, replacements for worn tools (under 10% durability), a recharge for a tool that runs on charge, the water bucket, the boat, a golden apple when gold is plentiful, and smith netherite upgrades. |
gear_armor | gear | Make, buy and wear armor piece by piece, up to the gear goal. The armor follows the tier the bot has climbed (its pickaxe’s tier, once that tier’s sword and axe are held). In the Nether it also covers the piglin truce piece. |
enchant | gear | Enchant the best sword, the worn armor and the best pickaxe, in that order, at a known enchanting table, with experience and lapis lazuli. |
enchanting_corner | gear | Raise the base’s enchanting corner in the yard (a table and up to 15 bookshelves, one shelf per run) for a style whose gear goal is diamond or netherite. |
brew | gear | Brew the potions listed in nether.potions at a brewing stand. |
gather_log, gather_food, gather_torch, gather_stick | gather | Refill a stockpile. gather_food cooks hunted meat up to 64 hunger points, and goes unweighted below 16 hunger points once the bot holds a stone pickaxe. |
gather_sugar_cane | gather | Keep 16 sugar cane for the enchanting corner’s paper, from the diamond tools to the fifteenth shelf. |
hoard | gather | Fill the hoard items no other objective fills (a ladder, TNT, a modded machine part), one at a time, up to a stack a run, and store them in the storehouse. Only for a style whose hoard lists such an item. |
fish | gather | Fish from a bank of open water near home for food and experience (Farming and animals). |
gather_rods | gather | Hunt blazes at the nearest known Nether fortress for six blaze rods (styles with minecraft:blaze_rod in hoard), or for the blaze powder of its eyes of ender (styles that go to the End). |
gather_pearls | gather | For a style that goes to the End, craft the bot’s share of eyes of ender and hunt endermen (in sight, on night walks, or in a known warped forest) for the pearls still missing (the End). |
gather_kit | gear | Gather the End trip’s kit (blocks, bow, arrows, cooked food, a spare pickaxe, a water bucket, torches, and the outer kit’s pearls and blocks for the second trip), once the tools reach the gear goal. |
gather_rockets | gear | Craft and keep end.rockets firework rockets (three from a paper and a gunpowder) while holding a sound elytra. |
gather_cobblestone, gather_coal | mine | Refill a stockpile. |
gather_bow | gear | Make a bow and replace a worn one (styles with bow in weapons, hunting spiders at dusk when string is needed). |
gather_arrow | gear | Keep 16 arrows once a bow is held (every style with bow in weapons). |
gather_pearls | gear | Keep the two ender pearls a raider throws (styles with the ender_pearl tactic that don’t go to the End), hunted from endermen. |
gather_trap | gear | Keep one TNT and one stone pressure plate in hand (styles with the tnt_trap tactic), crafting them from gunpowder, sand and stone. |
establish_base | build | Build, furnish or repair the bot’s house, make its bed from the sheep it finds, or dig the hidden style’s room into a hill. For a homeless bot holding a stone pickaxe it’s unweighted, at 1.0. |
settle | build | Search outward in eight directions by day for a place to live when no buildable site is in reach. |
expand_base | build | Build a storehouse when chests fill up (a second room off the house for a hidden base). |
make_camp | build | Dig or wall in a 3×3 camp shelter with a door and chest behind the arrival portal in the Nether. |
fortify | fortify | The fence ring or the fortress wall, yard lighting, golems, the bush ring, the lava moat and the storehouse decoy. |
hunt_enemies | hunt | Hunt the freshest enemy sighting (a thief of the base first, whatever the weight). |
scout | raid | Look for an enemy faction’s base where its enemies were last seen, and watch a suspected base (styles with the chest_raid tactic, or any style scouting the faction that robbed it). |
raid | raid | Raid the chests of the freshest confirmed enemy base, by night and by tunnel when it can. Needs both the chest_raid tactic and an explicit raid weight, except for a counter-raid. Forced with debug objective raid, it runs right away, whatever the odds. |
loot_bastion | raid | Loot a known Nether bastion’s chests for a netherite upgrade smithing template or hoarded gold (needs an explicit raid weight and nether.loot_bastions: true). |
mine | mine / gear | Dig for ore with the style’s mining strategy (including cave-to-strip fallback, digging into caves and pillaring up to ore on their walls, night strip mines for cave miners, the day’s cave for a cave_by_day strip miner, following veins, and Nether ancient debris strips). |
farm | farm | Build, tend, bone-meal and harvest crop fields (the first a 5×5 plot sown on day one) and the 5×5 soul sand wart plot; pen, breed, shear and slaughter animals. |
trade | trade | Sell surplus to villagers, level up a smith whose gear the bot wants, or hand out a workstation. |
stow | (fixed, weight 1) | Cook raw meat in hand, and bring the surplus and the hoard to the base’s (or Nether camp’s) chests. |
guard_post | (fixed) | A guard walks back to its yard when it finds itself outside with nothing keeping it out. |
explore | explore | Walk to new places within the roaming radius (and discover Nether fortresses, bastions and warped forests), flying a long leg with an elytra. |
the_end | end | Call the faction’s ready bots together and lead them to the End: the stronghold search, the portal, the dragon fight and the egg (the End). Forced with debug objective the_end, it runs one trip now, ready or not. |
outer_islands | end | Once the End is finished, call the ready bots together and lead them back through the gateway for an end city and its ship’s elytra (the second trip). |
pick_up_egg | (fixed) | Pick up a dragon egg, an elytra or a dragon head lying within 16 blocks (dropped by a carrier that died), unless on an order other than end or outer. |
Orders run as a third interrupt after survive and fight, and smelt_ore as a fourth. Some objectives only
exist for styles that use them. For example, mine needs a mining strategy, and scout and raid need the raid
tactics. enchanting_corner and gather_sugar_cane need a
diamond or netherite gear goal with a base. the_end, outer_islands and gather_kit need a style with
end.travel or a bot under an end or outer order. Once the_end or outer_islands scores, it ranks above
every gear, mine, build and explore objective, whatever their weights.
Driving a bot by hand
The debug commands below give a bot one specific job. Each of them turns decision making off first, so the bot
stays idle afterwards until you run debug <bot> auto on.
Movement
| Command | Effect |
|---|---|
debug <bot> goto <pos> | Walk there (jumping, dropping, swimming, climbing, opening doors). |
debug <bot> follow <entity> | Follow a player or any entity. |
debug <bot> mine <pos> | Walk into reach and break the block with the best tool. |
debug <bot> place <pos> | Walk into reach and place a block from the inventory. |
debug <bot> use | Use the held item (eat, draw a bow). |
debug <bot> dig on|off | Let goto, mine and place dig through and build over obstacles (pillar, bridge). Off by default. |
debug <bot> trail on|off | Particle trail: white path, yellow partial path, green next node, red work. Its dust shows to the operators near the bot only. The client add-on’s overlay draws the same on your own screen, with a label of the info lines. |
debug <bot> stop | Stop. |
Tasks
| Command | Effect |
|---|---|
debug <bot> task mine <category> [<count>] | Break blocks of a category (log, stone, ore_iron…; a plugin’s category in quotes, "mymod:ore"). |
debug <bot> task obtain <item> [<count>] | Plan and get the item: from inventory, chests, mining, crafting, smelting, hunting or trading. |
debug <bot> task craft <recipe> [<times>] | Craft a recipe. |
debug <bot> task smelt <item> [<count>] | Smelt an item. |
debug <bot> task eat | Eat. |
debug <bot> task gear | Equip the best gear it holds. |
debug <bot> task travel nether|end|outer|home | Skip the normal trip gates and walk into a known or visible portal and arrive in the Nether (nether), step through the faction’s known lit end portal into the End (end), go on through the main island’s gateway to the outer islands by pearl (outer), or return to the home dimension (home). From the End, home goes through the open exit portal. From the outer islands, it goes back through their gateway first. |
debug <bot> task fill_frame | Fill the empty frames of the faction’s known portal room with the eyes of ender the bot holds. |
debug <bot> task cross_gateway | Throw a pearl through the nearest end gateway: out from the main island, back from the outer islands. |
debug <bot> task island_hop | On the outer islands, search for an end city in legs, bridging gaps within the style’s end.hop_gap. |
debug <bot> task raid_city | Raid the nearest end city the bot knows, alone. |
debug <bot> task loot_ship | Look out for the known city’s ship, bridge to it, fight its shulkers and take the elytra, the chests, the potions and the dragon head. |
debug <bot> task brew <potion> | Brew the potion’s shortfall (at least one batch of three) through its full brewing chain. |
debug <bot> task store <pos> | Store everything but tools, weapons, food and torches in that chest. |
debug <bot> task retrieve <pos> <item> [<count>] | Take items out of that chest (64 by default). |
debug <bot> task light <pos> [<radius>] | Place torches on dark floor within the radius (4 by default, at most 16). |
debug <bot> task attack <entity> | Fight it with the combat controller. |
debug <bot> task flee <entity> | Run from it until nothing threatening is near for three seconds. |
debug <bot> task hunt <item> [<count>] | Kill animals (or monsters) that drop the item. |
debug <bot> task pearl <pos> | Throw a held ender pearl at that cell, with real vanilla ballistics. |
debug <bot> task trap | Lay a TNT trap at the nearest known chest, from the TNT and stone pressure plate it holds. |
debug <bot> task sleep | Sleep in the remembered bed (at night). |
debug <bot> task shelter | Build a hut around the bot from what it holds. |
debug <bot> task build house|storehouse|farm|wart_plot|pen|wall|portal | Build the next structure of that kind where the site finder picks (wall and portal are recorded in the base; the others are standalone). |
debug <bot> task tend | Tend the base’s field (bone-mealing young crops as the objective does). |
debug <bot> task pen <type> | Lead one animal of that type into the pen. |
debug <bot> task breed <type> | Breed a pair in the pen. |
debug <bot> task trade | Trade at the best villager in reach, or place a workstation. |
debug <bot> task light yard | Light the dark spots of the base’s yard. |
debug <bot> task golem | Build an iron golem. |
debug <bot> task bushes | Plant the next side of the berry bush ring. |
Every task runs under a watchdog that fails it after 600 ticks without progress; the result shows in info.
A debug command checks that the position you give is loaded in your dimension, but the bot walks in its own. Run debug commands from the bot’s dimension.
Last updated Nov 9, 2026