Getting started
Installation
What you need to run AI Players, and how to install it on a server or in singleplayer.
Requirements
| What | Version |
|---|---|
| Minecraft | Java Edition 26.3 |
| Mod loader | Fabric Loader 0.19.5 or newer |
| Fabric API | 0.161.0+26.3 or newer |
| Java | 25 or newer |
AI Players needs nothing else. It doesn’t work on Bedrock Edition, and it doesn’t support other Minecraft versions.
On a server
AI Players only needs to be installed on the server. Players can join with a completely vanilla client and see bots as regular players, with their skins and names.
-
Set up a Fabric server for Minecraft 26.3, if you don’t have one yet. The Fabric installer does it for you.
-
Download AI Players from CurseForge or Modrinth, along with Fabric API if your server doesn’t have it already.
-
Drop both jars into the server’s
modsfolder and start the server. -
Spawn a bot. As a server operator, run
/aiplayer spawn Stevein game. Head over to Your first bot for what to do next.
In singleplayer
AI Players works in singleplayer too, since a singleplayer world runs a small server behind the scenes.
-
Install Fabric for Minecraft 26.3 with the Fabric installer.
-
Put AI Players and Fabric API into your
.minecraft/modsfolder. -
Launch Minecraft with the Fabric profile and create (or open) a world with cheats allowed. You need cheats to use the
/aiplayercommand. If your world doesn’t allow cheats, open it to LAN with “Allow Cheats” turned on.
Installing AI Players on your own game, and not just on the server, is optional. It turns the jar into the client add-on: a management screen for operators, an orders screen for players, a debug overlay and custom skins for bots. In singleplayer you get all of it with nothing else installed.
Updating and removing
To update, replace the old jar with the new one while the server is stopped. Your bots, factions and bases are saved with the world and carry over.
If you remove the mod, bots stop logging in. Their player data stays in the world folder, so they come back where they left off if you install the mod again.
Technical details
Files the mod creates
config/aiplayers.json: the server configuration, written with default values on first start. See Server configuration.config/aiplayers/skin-cache/: cached bot skins, so servers without internet access keep showing them.logs/debug.log: the server’s own debug log, where a trace of every bot lands whiledebug_loggingis on.<world>/data/aiplayers/roster.dat: the list of bots, factions, bases and everything bots remember. Each start that reads any bot or faction from it first copies it toroster.dat_old. If the log warns that the roster loaded no bots and no factions and you didn’t remove them all, stop the server and copyroster.dat_oldback overroster.dat.<world>/playerdata/<uuid>.dat: each bot’s inventory, position, health and so on, like a real player’s.<world>/aiplayers/skins/: the custom skins uploaded from the client add-on, one PNG per bot.config/aiplayers-client.jsonin a player’s game folder: the client add-on’s own options.
Why does the jar declare a client entrypoint?
AI Players ships as a single jar for both sides. On a server the client part never runs. On a client it’s the add-on, which talks to the server only once the server has answered its greeting, so a client with the jar can still join any server, with or without the mod.
Performance considerations
Bots load chunks around themselves like players do, which keeps their bases growing while nobody is around.
Each bot costs about as much as one more player standing in the world, plus the AI’s own time. That time is
capped by a per-tick budget (1.5 ms per live bot by default, up to a server-wide ceiling of 12 ms). Path
searches run on a background thread with a time limit you can scale with the bot clock. The mod
is designed for a handful of bots at a time (up to around eight). See
Server configuration for the related settings.
Last updated Nov 10, 2026