---
name: minecraft-agent
description: Add Minecraft Agent (pathfinding, navigation, bot skills and game modes for Minecraft 26.3, server bots also on Spigot 1.8.8) to a Fabric mod or a Bukkit plugin, and drive bots with it.
---

# Minecraft Agent

Kotlin library for Minecraft 26.3 (Mojang names, Java 25). Group `net.ccbluex`, repository
`https://maven.ccbluex.net/releases` (snapshots: `/snapshots`).

| Artifact | Use it for |
|---|---|
| `minecraft-agent-world` | The game's blocks, entities and items as the libraries see them, on every game version |
| `minecraft-agent-simulation` | Predicting player movement (`PlayerMotion`, `SimulatedPlayer`) |
| `minecraft-agent-pathfinder` | Route searches without moving anything |
| `minecraft-agent-navigation` | `Navigator`: follows routes with a `Body` |
| `minecraft-agent-skills` | `Agent`: fighting, eating, looting, gear, shop, void rescue, game modes |
| `minecraft-agent-vanilla` | The libraries on Minecraft 26.3: `toAgent()`/`toMinecraft()`, `defineGameTypes()` |
| `minecraft-agent-client-common` | The local player as a body, for every mod loader |
| `minecraft-agent-client-fabric` | The local player as a body (Fabric mod) |
| `minecraft-agent-server-common` | Server bots as Bukkit sees them: `MinecraftAgent`, `Bots`, `Bot`, `BotBody` |
| `minecraft-agent-server-paper` | Server bots on Paper 26.3 (plugin `MinecraftAgent`), with minigames |
| `minecraft-agent-server-legacy` | Server bots on Spigot 1.8.8 (plugin `MinecraftAgent`) |

Each one brings what it builds on: `simulation` brings `world`, `navigation` brings `pathfinder` and `simulation`,
`skills` brings `navigation`, `vanilla` brings `pathfinder`, `client/fabric` brings `client/common`, `navigation` and
`vanilla`, `server/paper` and `server/legacy` bring `server/common` and `skills`.
Everything public is callable from Java.

## Fabric mod

```kotlin
repositories { maven("https://maven.ccbluex.net/releases") }
dependencies {
    implementation("net.ccbluex:minecraft-agent-client-fabric:1.0.0")
    // Jar-in-jar is not transitive: every module goes into the mod jar
    for (module in listOf("world", "simulation", "pathfinder", "navigation", "vanilla", "client-common", "client-fabric")) {
        include("net.ccbluex:minecraft-agent-$module:1.0.0")
    }
}
```

Call `defineGameTypes()` (`net.ccbluex.agent.vanilla`) once the game's registries are loaded (on client start), before
any other library call. Library calls take the library's types; `toAgent()` and `toMinecraft()` convert, and
`Terrain.live(level)` also takes the game's level.

The mod needs Fabric API and Fabric Language Kotlin. Walk the local player somewhere:

```kotlin
val navigation = ClientNavigation()                      // keep it: it hears the world while kept
navigation.navigator.moveTo(Vec3(100.5, 64.0, -20.5)) { ending -> println(ending) }   // ARRIVED, UNREACHABLE, STOPPED
navigation.navigator.follow { target?.position() }       // a goal that moves; null pauses
navigation.navigator.stop()                             // stops
```

In suspend code, `TickScope` (package `net.ccbluex.agent.tick`) runs coroutines on the tick of whoever calls
`scope.tick()`; inside, `navigator.walkTo(goal)` returns the `Ending`, `waitTicks(n)` waits, and `requires { … }` /
`unchanged { body.level }` end the run quietly once they fail. A host with its own tick loop puts its own `Ticker`
into the context instead (LiquidBounce: `object : Ticker { override suspend fun tickUntil(stopAt: IntPredicate) =
net.ccbluex.liquidbounce.event.tickUntil(stopAt) }`), so its guards apply to every library wait.

`navigation.Options` (digging, bridging, parkour, sprinting, look-ahead, `minPressTicks`/`minReleaseTicks` for
human key timing on plain walks) go in the constructor or `navigation.options`. `ClientBody(turning)` sets how
movement and aim rotations are turned to (`Turning.linear(degrees)`, `skillLevel.turning()` from `skills`, or
`Turning.instant()` when a rotation system of the host paces the turns).
The navigator presses the keys once per tick (`Body.press(input, exact)`); exact keys (jumps, climbs, block
actions, flight) must reach the player unchanged, plain walks may be changed by host features.

## Server plugin

Install the `MinecraftAgent` plugin jar on the server (`minecraft-agent-server-paper-<version>-plugin.jar` on Paper
26.3, `minecraft-agent-server-legacy-<version>-plugin.jar` on Spigot 1.8.8), then:

```kotlin
dependencies { compileOnly("net.ccbluex:minecraft-agent-server-paper:1.0.0") }
```

```yaml
# plugin.yml
depend: [MinecraftAgent]
```

```kotlin
val bot = MinecraftAgent.bots().spawn(location, "Steve")
bot.moveTo(target, 1.0)
bot.follow(player)
bot.fight(enemy)                 // with whatever it holds
bot.play(gameMode)               // a skills.games mode, see below
bot.remove()
```

`Games.get()` (Paper only) fills SkyWarsReloaded and BedWars2023 arenas with bots and starts Phoenix Duels against bots
when those plugins are installed. `/agent` does the same from the console.

A plugin can bundle the library instead of depending on the plugin: shade `minecraft-agent-server-paper` or
`minecraft-agent-server-legacy` (their jars have no plugin.yml), start with `MinecraftAgent.start(this)` in `onEnable`,
call `MinecraftAgent.stop()` in `onDisable`, and list the Kotlin libraries of the Paper plugin jar's plugin.yml in its
own (1.8.8 has no `libraries`: shade Kotlin and coroutines too). `start(this)` runs bots only; on Paper,
`Games.start(this, gamesSection)` after it adds minigames and hooks into minigame plugins, and `stop()` stops them too.
`MinecraftAgent`, `Bots`, `Bot`, `BotSettings` and `BotBody` are in `net.ccbluex.agent.server` (`server-common`), the
same on every server platform.

## Bots on your own host

Implement `Body` (navigation) or `AgentBody` (skills) for whatever moves: keys, turning, digging, item use, inventory.
Conventions: inventory indices as in `Inventory` (0-8 hotbar, 36-39 armor feet to head, 40 offhand); the last `press`
in a tick wins; `players()` returns every player the body can see, bots included, if your bots are not in the
level's player list. Then:

```kotlin
val navigator = Navigator(body, Options(), listener)
navigator.navigate(goal, radius)   // once per tick, before the player moves
navigator.halt()
navigator.options = navigator.options.copy(canPlace = false)   // takes effect on the next tick
```

A `navigation.Listener` gets routes (`routeFound`), steps, stuck spots, arrivals and failures, and what a renderer
draws (`routeSearching`, `routeFollowing`, `blocksAhead`, `routeDone`, `routeInvalid`, `routeCleared`). Hosts feed world
changes: `navigator.blockChanged`, `levelChanged`, `positionCorrected`, and `SectionCache.blockChanged`,
`columnChanged`, `forget` for block and chunk updates. A client host calls `navigator.turnView()` after the movement
packet, so the camera turns where the walk looks ahead.

## Skills and game modes

```kotlin
val skills = Skills.builtIn(body, SkillLevel.NORMAL, Personality.BALANCED)
val agent = Agent(body, navigator, skills)
agent.game = SkyWars(senses)       // null: only the abilities run
agent.tick()                       // once per tick, instead of navigator.navigate
```

Game modes take senses the host supplies (round state, teams, chests, beds): `SkyWars(skywars.Senses)`,
`Blitz(blitz.Senses)`, `BedWars(bedwars.Senses)`, `Duels(duels.Senses)`. They are `@ExperimentalAgentApi`: game modes
change while the bots get better; hosts opt in. A null ability in `Skills` leaves it to the host. Kits are never
built in; bots use what they hold.

API docs: https://ccbluex.github.io/Minecraft-Agent/api/
