# Commands

Every /aiplayer subcommand, its arguments and who can use it.

All commands live under `/aiplayer`, with `/aip` as an alias. Every subcommand needs permission level 2
(operators, the server console, command blocks), except `order`, which a bot's allies can use at level 0 (see
[Giving orders](/ai-players/guide/orders/)).

In the tables below, `<bot>` is a bot's name, `<pos>` a block position (`x y z`, `~` allowed), `<item>` an item id
like `minecraft:cobblestone`, and `<entity>`/`<player>` an entity selector or name.

With the [client add-on](/ai-players/guide/client-add-on/), the management screen sends these same commands for
you, checked the same way, and its replies are the chat lines below. The add-on's own `/aipc` commands are listed
[there](/ai-players/guide/client-add-on/#commands).

## Bots

| Command | Effect |
| :------ | :----- |
| `spawn <name> [<style>] [<faction>] [<skin>]` | Creates a bot at your position. Defaults: `aiplayers:neutral`, no faction (`none` also means no faction), a skin from `default_skins` picked by name (else the default). `default` as the skin forces the default skin. Arguments are positional. |
| `remove <bot>` | Retires the bot: it leaves the world, keeping its player data and roster entry. |
| `remove <bot> purge` | Deletes the bot for good: roster entry, player data, statistics, advancements and custom skin. |
| `respawn <bot>` | Brings a retired bot back. Refused while the bot is in the world. |
| `list` | Lists every bot with its status, faction, role, style, difficulty and deaths. |
| `info <bot>` | The bot's full report, see [Inspecting and debugging bots](/ai-players/reference/debugging/#the-info-report). |
| `info <bot> chests` | The base's chests (and each Nether camp's chests under its `camp:` line), one line each, read live where loaded. |
| `info <bot> enemy bases` | Every enemy base the bot's faction has learned (position, chests, gates, golems, traps and guard), with each known chest and gate on its own line. |
| `tp <bot>` | Teleports you to the bot. |
| `tphere <bot>` | Teleports the bot to you. |

## Settings

| Command | Effect |
| :------ | :----- |
| `set <bot> style <id>` | Changes the [play style](/ai-players/guide/play-styles/), e.g. `aiplayers:rusher`. |
| `set <bot> difficulty <id>` | Changes the [difficulty](/ai-players/guide/difficulty/), e.g. `aiplayers:hard`. |
| `set <bot> faction <id>` | Moves the bot to a faction, or out of it with `none`. |
| `set <bot> role miner\|farmer\|guard\|raider\|free` | Sets the bot's [faction role](/ai-players/guide/factions/#faction-roles) by hand. On a bot of a faction that hands its roles out automatically, it also switches that faction back to manual roles (the reply says so). |
| `set <bot> respawn respawn\|permadeath\|inherit` | What happens on death. `inherit` uses `default_respawn_mode`. |
| `set <bot> cheats true\|false` | Enables the difficulty's cheats. Refused while `cheats_allowed` is `false`. |
| `set <bot> skin <username>` | Copies the skin of a Minecraft account, or `default`. Also deletes the bot's custom skin, so every client shows the skin you named. |
| `set <bot> custom_skin none` | Deletes the bot's [custom skin](/ai-players/guide/client-add-on/#custom-skins) and leaves its Mojang skin as it was. Uploading one is done from the add-on's screen, not by a command. |
| `config reload` | Re-reads `config/aiplayers.json` and shows you any warnings. Also puts the [bot clock](/ai-players/reference/server-config/#the-bot-clock) back to the file's `bot_tick_rate`. |
| `tick rate <n\|game>` | Sets the [bot clock](/ai-players/reference/server-config/#the-bot-clock) until the next restart or `config reload`: a number from 1 to 10000, or `game` to follow the server's `/tick rate`. Like vanilla's `/tick rate`, it isn't saved. Anything else is refused with the usage. |
| `tick query` | Shows the bot clock in force and the path search limit it gives, e.g. `Bot clock game at 100 ticks/s: a search limit of 200 ms on it (difficulty aiplayers:normal) is 40.0 ms of wall time`. |
| `profile list` | Lists loaded play styles and difficulties with their source pack, and the files that failed to load with the reason. |
| `profile reload` | Re-reads play styles and difficulties without a full `/reload`. |

## Factions

| Command | Effect |
| :------ | :----- |
| `faction create <id> [<color>]` | Creates a faction (a scoreboard team named `<id>`). |
| `faction remove <id>` | Deletes a faction. |
| `faction list` | Lists factions with their color, whether their roles are `auto` or `manual`, and their relations. |
| `faction join <id> <player>` | Adds a bot or a real player to a faction. |
| `faction leave <player>` | Removes a bot or player from their faction. |
| `faction relation <a> <b> ally\|neutral\|enemy` | Sets the (symmetric) relation between two factions. |
| `faction color <id> <color>` | Changes a faction's team color. |
| `faction roles <id> auto` | Makes the faction hand out its bots' [roles](/ai-players/guide/factions/#faction-roles) by its size, now and on every membership change; the reply lists each active member's role. `set <bot> role` on one of its bots turns it back to manual. |

A member's locator bar shows only its own faction. Players of another faction are never sent to it, whatever the
relation, and a player with no faction sees and is seen by everyone. The config key
`show_other_factions_on_locator_bar` gives vanilla's bar back
([server configuration](/ai-players/reference/server-config/#visibility)).

## Orders

```txt title="Syntax"
/aiplayer order <bot|@faction <id>|@all> <order>
```

| Order | Effect |
| :---- | :----- |
| `follow <player>` | Follow the player within about three blocks, fighting what hurts them. |
| `stay` | Hold the block where the order was given. |
| `attack <entity>` | Fight the entity until it dies, whatever its relation. |
| `defend [<pos>]` | Hold within 8 blocks of the post (default: the bot's position), fighting hostiles within 16. |
| `bring <item> [<count>]` | Obtain the item (1 to 64) and throw it to the issuer. |
| `home` | Walk home and stay there. |
| `end` | Go to [the End](/ai-players/guide/the-end/) with the faction's party once ready, as if the style's `end.travel` were on. Refused on a difficulty with `end_dragon: false`. |
| `outer` | Go on to the outer islands once the End is finished (the first trip first, if need be), as if `end.travel` and `end.outer` were on. |
| `free` | End the active order and start the next queued one. |
| `free all` | Clear every order. |

See [Giving orders](/ai-players/guide/orders/) for queueing, timeouts and refusals. A bot answering a faction
mate's [call for help](/ai-players/guide/factions/#calling-for-help) takes an `assist` order from the caller. That
order has no verb here, but `free` ends it like any other.

## Diagnostics

| Command | Effect |
| :------ | :----- |
| `stats` | AI timings. First the budget in force on the last tick (the per-bot figure, the live bots, the cap, how many ticks ran out, the pathfinder's queue and nodes per second, and how many path searches the time limit has cut since the server started). Then the bot clock in force and the search limit it gives (the `tick query` line). Then the client add-on's sync pass: its time on the last tick and on average, how many players watch something and how many bots are on overlays. Then, for each bot, its brain milliseconds, snapshot build time, perception load, knowledge build time and objective. |
| `debug <bot> auto on\|off` | Turns the bot's decision making on (the default, not saved) or off. `off` also stops its current task. |
| `debug <bot> objective <id>` | Turns `auto` off and runs one objective once. |
| `debug <bot> stop` | Stops the current debug task (and turns `auto` off). |

The `debug` subcommands that drive bots by hand (`goto`, `follow`, `mine`, `place`, `use`, `trail`, `dig` and the
`debug <bot> task` family) are documented in
[Inspecting and debugging bots](/ai-players/reference/debugging/#driving-a-bot-by-hand).
