AI Players
Type to search documentation.

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:

LineExampleMeaning
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_bootsWorn 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:10Active 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 lineobtain 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 failureestablish_base (needs 2 more building blocks), 340 ticks agoThe 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:relocateShown 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.
memoryhouse 5x5, bed, workstations, sightingsWhat 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 shelvesThe base’s enchanting corner, once its table stands.
camp:the_nether (14, 70, -3), 2 chestsIts 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:diamondIts 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 stacksThe 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/1For 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 chestsThe Nether fortresses, bastions and warped forests the faction has discovered, plus its end cities.
end:stronghold (120, 30, -400), portal lit, dragon alive; readyShown 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 legsThe 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 landingShown while the bot flies an elytra.
fortify:wall 112/116 (building), gates 4, dark 3, golems 1/2, bushes 40/108Its 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 at ai_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 query prints).
  • 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 of logs/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:

IdFamily (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_upgearA 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_armorgearMake, 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.
enchantgearEnchant the best sword, the worn armor and the best pickaxe, in that order, at a known enchanting table, with experience and lapis lazuli.
enchanting_cornergearRaise 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.
brewgearBrew the potions listed in nether.potions at a brewing stand.
gather_log, gather_food, gather_torch, gather_stickgatherRefill 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_canegatherKeep 16 sugar cane for the enchanting corner’s paper, from the diamond tools to the fifteenth shelf.
hoardgatherFill 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.
fishgatherFish from a bank of open water near home for food and experience (Farming and animals).
gather_rodsgatherHunt 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_pearlsgatherFor 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_kitgearGather 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_rocketsgearCraft and keep end.rockets firework rockets (three from a paper and a gunpowder) while holding a sound elytra.
gather_cobblestone, gather_coalmineRefill a stockpile.
gather_bowgearMake a bow and replace a worn one (styles with bow in weapons, hunting spiders at dusk when string is needed).
gather_arrowgearKeep 16 arrows once a bow is held (every style with bow in weapons).
gather_pearlsgearKeep the two ender pearls a raider throws (styles with the ender_pearl tactic that don’t go to the End), hunted from endermen.
gather_trapgearKeep one TNT and one stone pressure plate in hand (styles with the tnt_trap tactic), crafting them from gunpowder, sand and stone.
establish_basebuildBuild, 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.
settlebuildSearch outward in eight directions by day for a place to live when no buildable site is in reach.
expand_basebuildBuild a storehouse when chests fill up (a second room off the house for a hidden base).
make_campbuildDig or wall in a 3×3 camp shelter with a door and chest behind the arrival portal in the Nether.
fortifyfortifyThe fence ring or the fortress wall, yard lighting, golems, the bush ring, the lava moat and the storehouse decoy.
hunt_enemieshuntHunt the freshest enemy sighting (a thief of the base first, whatever the weight).
scoutraidLook 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).
raidraidRaid 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_bastionraidLoot 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).
minemine / gearDig 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).
farmfarmBuild, 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.
tradetradeSell 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.
exploreexploreWalk to new places within the roaming radius (and discover Nether fortresses, bastions and warped forests), flying a long leg with an elytra.
the_endendCall 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_islandsendOnce 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

CommandEffect
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> useUse the held item (eat, draw a bow).
debug <bot> dig on|offLet goto, mine and place dig through and build over obstacles (pillar, bridge). Off by default.
debug <bot> trail on|offParticle 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> stopStop.

Tasks

CommandEffect
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 eatEat.
debug <bot> task gearEquip the best gear it holds.
debug <bot> task travel nether|end|outer|homeSkip 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_frameFill the empty frames of the faction’s known portal room with the eyes of ender the bot holds.
debug <bot> task cross_gatewayThrow a pearl through the nearest end gateway: out from the main island, back from the outer islands.
debug <bot> task island_hopOn the outer islands, search for an end city in legs, bridging gaps within the style’s end.hop_gap.
debug <bot> task raid_cityRaid the nearest end city the bot knows, alone.
debug <bot> task loot_shipLook 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 trapLay a TNT trap at the nearest known chest, from the TNT and stone pressure plate it holds.
debug <bot> task sleepSleep in the remembered bed (at night).
debug <bot> task shelterBuild a hut around the bot from what it holds.
debug <bot> task build house|storehouse|farm|wart_plot|pen|wall|portalBuild 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 tendTend 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 tradeTrade at the best villager in reach, or place a workstation.
debug <bot> task light yardLight the dark spots of the base’s yard.
debug <bot> task golemBuild an iron golem.
debug <bot> task bushesPlant 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