Getting started
The client add-on
Install AI Players on your own game for a management screen, an orders screen, a debug overlay and custom skins for your bots.
The same AI Players jar works on your own game too. On the server it’s the mod. In your client’s mods folder
it’s an add-on that talks to any server running the mod, so you get screens for your bots instead of chat
replies. You never need it. A vanilla client joins a server with bots and sees nothing different, and every
command still works from chat.
Installing it
-
Put the AI Players jar and Fabric API in your client’s
.minecraft/modsfolder, with Fabric Loader 0.19.5 or newer for Minecraft 26.3. It’s the same file that goes in the server’smodsfolder (see Installation). -
Join a server running AI Players, or open a singleplayer world. In singleplayer the add-on talks to the game’s own integrated server, so the bots and the screens work with nothing else installed.
-
Press K. As an operator you get the management screen. Any other player gets the orders screen.
What happens when you join
When you join a world, the add-on and the server greet each other once. Your client says which version of the add-on it runs, and the server answers with its own version, your permission level and what it allows (custom skins, cheats). Nothing shows in chat when the two match.
- A server without AI Players: the add-on sends nothing and shows nothing. Pressing K or typing
/aipcsays “this server does not run AI Players”. The options still open. - A server with the same version: everything works. K and
/aipc screenopen the screen your permission level allows, and/aipcalone shows the server’s version and your level. - A server with a different version: one chat line at join names both versions and which side has to update
(“your add-on (x) is older than the server’s mod (y); update the add-on”, or the other way round). The add-on
then stays quiet for that session, and K or
/aipcrepeat the line. Chat commands keep working meanwhile.
When an operator gives you /op or takes it away, your add-on hears about it within a second, without
reconnecting. The add-on never decides anything by itself. What it shows is filtered by the server for your
permission level, and everything it does goes through the same /aiplayer commands you could have typed, checked
the same way.
The management screen
An operator (permission level 2 or more) opens it with K (under “AI Players” in the controls) or
/aipc screen. The screen doesn’t pause a singleplayer world, and it keeps nothing of its own: close it and open
it again and it shows what the server says now.
Every button sends the matching command as if you had typed it, so the server checks it as usual and answers in chat. The last three replies also show at the foot of the screen for ten seconds. The Orders button at the foot opens the orders screen, Options the add-on’s options and Done closes.
- Bots: the roster as
/aiplayer listshows it, with each bot’s dimension, position and health. Click a bot to select it. Its state shows under the list, updated twice a second: its path (which node of how many, and whether the path is partial), the block it’s breaking or placing, and the lines/aiplayer infoprints. Three pages on the right act on the selected bot:- Actions: set any field (style, difficulty, faction, respawn, cheats, skin, role) from the server’s lists and apply it; remove, remove and purge (each asks first), respawn a retired bot, teleport to it or bring it to you, list its chests or the enemy bases it knows, and upload or remove a custom skin.
- Debug: toggle its brain (
auto), its particle trail and its overlay, stop it, call it to the block you stand on, run one objective once, or type a task command with the same completion chat offers. - Spawn: a name, a style, a faction and a skin, and a Spawn button that keeps the style and faction for the next one.
- Factions: every faction with its color, members, whether it hands out roles by size, and its relations. Create, remove, set colors and relations, and add or remove members.
- Profiles: the play styles and difficulties with the pack each came from, the files the last load skipped with their errors, every objective id, and buttons to reload the profiles or the config.
- Stats: the numbers of
/aiplayer stats, refreshed once a second while the tab is open.
If your permission level drops below 2 while the screen is open, it closes within a second.
The orders screen
A player below permission level 2 opens it with K or /aipc screen. An operator opens it with the Orders
button at the foot of the management screen (Esc goes back). The world goes on behind it.
- Bots: the bots you may order, which is those of your faction and of allied factions (every bot for an operator). Each row shows whether the bot is live, dead or retired, its faction, whether its brain is on, what it’s doing and its active order with how many wait behind it.
- To: whom the buttons order: the bot you selected, a faction, or every bot (operators only). Until you pick one, every button is grayed out, so a click never orders a whole faction by mistake.
- Verbs: Follow (your own name, or type another player’s), Stay, Home, The End, Outer islands, Free, Free all, Defend here, Defend where it is, Attack (the creature or player you were looking at when you opened the screen, or a name you type) and Bring (an item id and a count up to 64). Each sends the matching order. A bot that isn’t taking orders has its buttons grayed out with the reason.
- Calls for help: your faction’s open calls, each with the
caller, why (outmatched, raiding, a big job, going to the End, stuck), where, the seconds left and your answer.
Yes and No send
/teammsg yesornoto the oldest call still waiting.
The screen sends one command per click, so clicking too fast hits the server’s chat spam limit like typing would.
The debug overlay
An operator can watch what a bot is doing, drawn in the world on their own screen only:
- a line along the bot’s planned path, white, or yellow while the path is partial;
- a green box on the next block of the path;
- a red box on the block the bot is breaking or placing;
- a label over its name tag with its objective, its task, where its walk stands (
navigator: following, path 3/17) and, for ten seconds after a walk fails, why. These are the lines/aiplayer infoprints.
The colors are the particle trail’s (/aiplayer debug <bot> trail on), which every nearby operator sees, add-on
or not. The overlay is drawn through blocks, so you can follow a bot in a cave or a tunnel from outside (the
options can hide the line and boxes behind blocks instead).
Look at a bot within 64 blocks and press U to turn its overlay on, and U again to turn it off. Pressing U with
no bot under the crosshair turns every overlay off. /aipc overlay <bot> does the same by name, and
/aipc overlay off clears them all. The Bots tab’s Debug page has the same toggle for the selected bot. You can
watch up to eight bots at once. The drawing updates every half second, and it goes away when the bot is removed,
when you move more than 128 blocks from it or into another dimension (it comes back when you return), when you log
out, or when you lose permission level 2.
Custom skins
An operator can give a bot a skin of their own from the Bots tab’s Actions page. Select the bot (in the world or
retired), type the path to a PNG on your computer (64×64, or the older 64×32 layout; ~/ stands for your home
folder), pick the model (classic or slim) and press Upload skin. The add-on checks the file first and names
what’s wrong with it. The server checks it again and answers in chat, with
Ann now wears the custom skin 1a2b3c4d (slim) or the reason it refused (too large, not a PNG, wrong size, an
upload less than a second after your last one, or custom skins turned off on that server).
Every player with the add-on sees the bot wear it within a moment. Players on a vanilla client keep seeing the bot’s Mojang or default skin, since only skins Mojang signed can reach a vanilla client.
Remove skin on the form deletes it (/aiplayer set <bot> custom_skin none does the same from any client).
/aiplayer set <bot> skin <username|default> deletes it too, so the skin info reports is the one everyone sees. A
retired bot keeps its custom skin, and remove <bot> purge deletes it. A custom skin belongs to the world it was
uploaded in. A bot of the same name in another world doesn’t wear it.
Options
The add-on’s options are your client’s own. The server never sees them and they apply on every server. Open them
with the Options button at the foot of the management screen, with /aipc options (on any server), or from AI
Players’ entry in Mod Menu if you have it (it’s never required).
| Option | Default | What it does |
|---|---|---|
| Overlay Through Walls | on | Draw the overlay’s path line and boxes on top of the world. Off, they hide behind blocks. The label is always on top. |
| Overlay Key Reach | 64 blocks (8 to 128) | How far the U key looks for a bot under the crosshair. A short reach on a crowded server keeps it from toggling a bot behind the one you look at. |
| Reply Time | 10 seconds (1 to 60) | How long a server reply stays at the foot of the add-on’s screens. Replies always reach chat too. |
A change takes effect at once and is saved when you leave the screen, in config/aiplayers-client.json in your
game folder. You can edit that file by hand while the game is closed. A missing key keeps its default, a number out
of range is brought into it, and a broken file is noted in the game’s log and the defaults are used.
Commands
| Command | What it does |
|---|---|
/aipc | The add-on’s line: the server’s version and your level, the version mismatch, or that the server doesn’t run the mod. Runs on your client only. |
/aipc screen | Opens what K opens: the management screen at level 2 or more, the orders screen below it. |
/aipc overlay <bot> | Turns the debug overlay on for the bot, or off if it’s on. |
/aipc overlay off | Turns the overlay off for every bot. |
/aipc options | Opens the add-on’s options, on any server. |
For server operators
Nothing needs configuring. The server answers modded clients and ignores vanilla ones. Two keys in the client
block of config/aiplayers.json say what the add-on may do: skins_allowed and skin_max_bytes
(server configuration). A player whose add-on is a
different version is logged once at join, with both versions.
What the add-on shows reaches it only while a screen asks for it, at most once a second and only when it changed.
The roster, factions, profiles, statistics and the overlay need permission level 2, as their commands do, and a
player below it only gets the bots it may order. This work runs at the end of each server tick, outside the AI
budget. /aiplayer stats shows its cost on its Client sync line.
Custom skins are files in the world folder, under aiplayers/skins/ (world/aiplayers/skins/ on a dedicated
server, saves/<world>/aiplayers/skins/ in singleplayer), one per bot named after it in lower case. A world copied
or backed up takes its skins along. The bot’s record keeps the file’s checksum, so a file that goes missing or is
edited by hand is dropped at the next start (with a line in the log) and the bot wears its Mojang or default skin
again. skins_allowed: false hides every custom skin and refuses uploads without deleting anything.
Technical details
The protocol
The add-on and the server exchange one hello and one welcome per connection, carrying the mod version, the
player’s permission level and the server’s features. A mismatch is one chat line at join, and the add-on stays
quiet after it. Reads come as snapshots the server builds once a second and pushes only when they changed, each
filtered by the player’s permission level. Writes are plain /aiplayer commands, so the server’s command tree
stays the one authority and the permission model needs no new write path.
Known limits
- The overlay’s 128-block range is fixed. The options are saved when the screen closes, so a change made while the game quits with it open is lost.
- The skin’s path is typed, since the game’s client libraries have no file dialog.
- Players can’t join a bot party to the End from the orders screen or otherwise.
Last updated Nov 10, 2026