SKILL.md as plain Markdown, for agents.

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

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:

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:

dependencies { compileOnly("net.ccbluex:minecraft-agent-server-paper:1.0.0") }
# plugin.yml
depend: [MinecraftAgent]
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:

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

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/