AI Players
Type to search documentation.

For server admins

Server configuration

Every setting in config/aiplayers.json, with its default and what it does.

The server configuration lives in config/aiplayers.json. It’s created with default values the first time the server starts with AI Players. Edit it, then run /aiplayer config reload (or restart the server) to apply your changes. Unknown keys and invalid values are reported as warnings, and the default is used instead. A file that isn’t valid JSON is moved aside as aiplayers.json.broken-<time> and the defaults are written in its place. On a config reload the configuration in use stays as it was.

config/aiplayers.json (defaults)
{
"max_bots": 8,
"bot_view_distance": 4,
"ai_tick_budget_ms": 12.0,
"ai_tick_budget_ms_per_bot": 1.5,
"show_in_tab_list": true,
"show_in_server_list": false,
"count_toward_max_players": false,
"announce_bot_advancements": false,
"default_relation": "neutral",
"default_respawn_mode": "respawn",
"respawn_delay_ticks": 60,
"cheats_allowed": false,
"default_skins": [],
"skin_cache_days": 7,
"debug_logging": false,
"order_timeout_minutes": 20,
"bot_tick_rate": 20,
"show_other_factions_on_locator_bar": false,
"client": {
"skins_allowed": true,
"skin_max_bytes": 16384
}
}

Bots and performance

KeyDefaultDescription
max_bots8The most bots that can be active at once (at least 1).
ai_tick_budget_ms12.0The server-wide ceiling on how many milliseconds per server tick all bots’ AI may use together (at least 0.1), however many bots are active.
ai_tick_budget_ms_per_bot1.5How many milliseconds per server tick each live bot adds to the AI budget (at least 0.1). The budget in force is live_bots × ai_tick_budget_ms_per_bot, capped at ai_tick_budget_ms. Expensive work beyond the budget waits for the next tick. /aiplayer stats shows the active budget, the cap, and how often it runs out.
bot_tick_rate20The bot clock, which sets how fast bots think as a tick rate (a number from 1 to 10000, or "game"). See below. Any other value takes the default with a warning. /aiplayer tick rate changes it until the next restart or config reload.
bot_view_distance4The view distance a bot reports, in chunks (2 to 32). It limits the chunks and entities the server tracks for the bot. Chunk loading still follows the server’s view distance, like for a real player.

Upgrading from an older config file

Config files created by earlier versions of AI Players have "ai_tick_budget_ms": 4.0 and keep 4.0 as the server-wide cap until you raise it to 12.0 (or delete the line so it takes the new default). A file without bot_tick_rate runs at 20, so nothing changes until you set it.

The bot clock

Everything a bot does counts server ticks (its waits, its orders, the stall guard, the AI budget), except for how long it may search for a path. That’s the difficulty’s path_max_millis (200 ms on Normal), and it’s the one limit that runs on the bot clock. bot_tick_rate sets the bot clock as a tick rate, the same way /tick rate sets the server’s:

  • 20, the default, is the wall clock, as on any server. When you raise /tick rate, bots keep thinking at a human pace like players do, so they take more ticks to decide.
  • Any other number n scales the limit by 20/n. At 40 a bot decides in half the wall time (twice as fast in ticks), at 100 in a fifth of it, and at 10 it takes double, which is a handicap.
  • "game" makes the clock follow the server’s tick rate, read every tick, so a bot decides in the same number of ticks at any rate, like a mob. Under /tick sprint the nominal rate counts, so a sprint changes nothing. Under /tick freeze bots stay frozen like mobs, whatever the clock.

path_max_millis is in the bot clock’s milliseconds. With the clock at "game" and /tick rate 100, Normal’s 200 ms is 40 ms of wall time. The AI budget (ai_tick_budget_ms and the per-bot figure) stays off the clock as a share of each server tick, since it caps what the bots cost the server, while the clock sets how fast they think.

A faster clock leaves a search less wall time. On a slow machine at a high rate, searches hit their limit more often and bots take worse paths. A slow clock delays every bot’s paths, since all bots share one search thread. At 1, Normal’s 200 ms becomes 4 seconds per search, and the other bots wait behind it.

/aiplayer tick query and the second line of /aiplayer stats show the clock in force and the search limit it gives. The first line of stats counts the searches the time limit has cut since the server started. If that count climbs steadily, the clock or the difficulty gives searches too little time on this machine. The long searches that dig a mine’s stair are the first to be cut. On a fast-running server, keep the default 20 and only raise the tick rate.

Visibility

KeyDefaultDescription
show_in_tab_listtrueWhether bots appear in the tab list.
show_other_factions_on_locator_barfalseWhether a player’s locator bar shows the players of other factions. Off, a player in a faction sees only its own faction’s members on the bar, in the faction’s color, and is never sent anyone of another faction, whatever the relation. A player with no faction sees and is seen by everyone. Bots and real players alike. A change applies on config reload, and vanilla’s locatorBar game rule still turns the bar on or off.
show_in_server_listfalseWhether bots’ names appear in the server list’s player sample. When false, they’re shown as “Anonymous Player”. Bots always count toward the online number.
count_toward_max_playersfalseWhether bots take up player slots. When false, real players can join even if bots fill the server.
announce_bot_advancementsfalseWhether bots’ advancements are announced in chat. They earn them either way.

Gameplay

KeyDefaultDescription
default_relation"neutral"The relation between two factions that have none set: ally, neutral or enemy. Use enemy for free-for-all servers. With ally, faction players can also order bots of factions with no explicit relation to theirs.
default_respawn_mode"respawn"What happens when a bot set to inherit dies: respawn or permadeath.
respawn_delay_ticks60How long a dead bot waits before respawning, in ticks (20 ticks = 1 second).
cheats_allowedfalseMaster switch for cheats. While false, no bot gets any cheat, whatever its own setting.
order_timeout_minutes20How long an order lasts once active (at least 1).

The client add-on

KeyDefaultDescription
client.skins_allowedtrueWhether players with the client add-on may upload custom skins for bots, and whether modded clients are shown them. Turning it off hides the skins and refuses uploads but deletes nothing.
client.skin_max_bytes16384The largest custom skin upload, in bytes (1024 to 65536). A larger file is refused with a line in the uploader’s chat.

Skins and logging

KeyDefaultDescription
default_skins[]Minecraft account names whose skins are given to bots spawned without a skin. Each bot gets one picked from its name, so the same name always gets the same skin. When empty, bots use the default skin.
skin_cache_days7How long a looked-up skin is cached in config/aiplayers/skin-cache/ before it’s fetched again (at least 1).
debug_loggingfalseWrites a trace of every bot to logs/debug.log (see below). Takes effect on the next tick after config reload.

Debug logging

With "debug_logging": true, every bot writes a trace to logs/debug.log in the server directory (the server’s own debug log, which needs no other setting). Nothing extra goes to the console or logs/latest.log. Each bot writes:

  • a line every time its objective changes, like Ann objective: mine -> survive (score 0.85);
  • a line every time its task ends, with the steps it was at (as info’s task: line shows them), the outcome and why it failed, like Ann task ended: gear_up (selector > sequence > craft stone_pickaxe) -> failed (no cobblestone). The outcome can also be -> success, or -> stopped when something else replaced the task;
  • a state line every 30 seconds (and as soon as the key is turned on) with where it stands, its health, food, style and difficulty, the lines /aiplayer info shows (without the farm, corner and fortify lines) and its items, all on one line.

/aiplayer config reload switches it without a restart, and logs/latest.log notes each switch (Debug logging on, Debug logging off). With the key off the trace costs nothing. With many bots the file grows by a few lines a second per bot, and the server rotates it on restart. The mod’s first line in logs/latest.log names the build (AI Players 1.0.0 (commit a612abee) initialized (max_bots=8)). When you report a bug, send that line, the (aiplayers) lines and debug.log (see Inspecting and debugging bots).

  • /gamerule pvp false stops every bot from fighting players and other bots.
  • /tick rate speeds the world up. The bot clock decides whether bots keep up with it.
  • Server view and simulation distance apply to bots the same as players, so each bot keeps the chunks around it loaded and ticking.
  • Hardcore: a respawning bot becomes a spectator, so use permadeath.
  • player-idle-timeout never kicks bots.

Last updated Nov 9, 2026