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.
{ "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
| Key | Default | Description |
|---|---|---|
max_bots | 8 | The most bots that can be active at once (at least 1). |
ai_tick_budget_ms | 12.0 | The 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_bot | 1.5 | How 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_rate | 20 | The 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_distance | 4 | The 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
nscales the limit by 20/n. At40a bot decides in half the wall time (twice as fast in ticks), at100in a fifth of it, and at10it 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 sprintthe nominal rate counts, so a sprint changes nothing. Under/tick freezebots 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
| Key | Default | Description |
|---|---|---|
show_in_tab_list | true | Whether bots appear in the tab list. |
show_other_factions_on_locator_bar | false | Whether 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_list | false | Whether 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_players | false | Whether bots take up player slots. When false, real players can join even if bots fill the server. |
announce_bot_advancements | false | Whether bots’ advancements are announced in chat. They earn them either way. |
Gameplay
| Key | Default | Description |
|---|---|---|
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_ticks | 60 | How long a dead bot waits before respawning, in ticks (20 ticks = 1 second). |
cheats_allowed | false | Master switch for cheats. While false, no bot gets any cheat, whatever its own setting. |
order_timeout_minutes | 20 | How long an order lasts once active (at least 1). |
The client add-on
| Key | Default | Description |
|---|---|---|
client.skins_allowed | true | Whether 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_bytes | 16384 | The 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
| Key | Default | Description |
|---|---|---|
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_days | 7 | How long a looked-up skin is cached in config/aiplayers/skin-cache/ before it’s fetched again (at least 1). |
debug_logging | false | Writes 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’stask:line shows them), the outcome and why it failed, likeAnn task ended: gear_up (selector > sequence > craft stone_pickaxe) -> failed (no cobblestone). The outcome can also be-> success, or-> stoppedwhen 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 infoshows (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).
Related vanilla settings
/gamerule pvp falsestops every bot from fighting players and other bots./tick ratespeeds 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-timeoutnever kicks bots.
Last updated Nov 9, 2026