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.