# Installation

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

import { AccordionItem, Accordions, Steps } from '@prosefly/astro-components';

## Requirements

| What                 | Version                                  |
| :------------------- | :--------------------------------------- |
| Minecraft            | Java Edition **26.3**                    |
| Mod loader           | [Fabric](https://fabricmc.net/use/) 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.

<Steps>

1. **Set up a Fabric server** for Minecraft 26.3, if you don't have one yet. The
   [Fabric installer](https://fabricmc.net/use/server/) does it for you.

2. **Download AI Players** from [CurseForge](https://www.curseforge.com/minecraft/mc-mods/minecraft-ai-players) or
   [Modrinth](https://modrinth.com/mod/minecraft-ai-players), along with [Fabric API](https://modrinth.com/mod/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](/ai-players/guide/first-bot/) for what to do next.

</Steps>

## In singleplayer

AI Players works in singleplayer too, since a singleplayer world runs a small server behind the scenes.

<Steps>

1. **Install Fabric** for Minecraft 26.3 with the [Fabric installer](https://fabricmc.net/use/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.

</Steps>

:::tip
Installing AI Players on your own game, and not just on the server, is optional. It turns the jar into the
[client add-on](/ai-players/guide/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

<Accordions>
  <AccordionItem title="Files the mod creates">
    - `config/aiplayers.json`: the server configuration, written with default values on first start. See
      [Server configuration](/ai-players/reference/server-config/).
    - `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.
  </AccordionItem>
  <AccordionItem title="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](/ai-players/guide/client-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.
  </AccordionItem>
  <AccordionItem title="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](/ai-players/reference/server-config/) for the related settings.
  </AccordionItem>
</Accordions>
