AI Players
Type to search documentation.

Getting started

Installation

What you need to run AI Players, and how to install it on a server or in singleplayer.

Requirements

WhatVersion
MinecraftJava Edition 26.3
Mod loaderFabric Loader 0.19.5 or newer
Fabric API0.161.0+26.3 or newer
Java25 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.

  1. Set up a Fabric server for Minecraft 26.3, if you don’t have one yet. The Fabric installer does it for you.

  2. Download AI Players from CurseForge or Modrinth, along with Fabric API if your server doesn’t have it already.

  3. Drop both jars into the server’s mods folder and start the server.

  4. Spawn a bot. As a server operator, run /aiplayer spawn Steve in 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.

  1. Install Fabric for Minecraft 26.3 with the Fabric installer.

  2. Put AI Players and Fabric API into your .minecraft/mods folder.

  3. Launch Minecraft with the Fabric profile and create (or open) a world with cheats allowed. You need cheats to use the /aiplayer command. 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 while debug_logging is 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 to roster.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 copy roster.dat_old back over roster.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.json in 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