AI Players
Type to search documentation.

Under the hood

Mod integration

Detect bots from your mod, and teach bots your mod's ores, crops, tools, machines and creatures through a plugin.

AI Players has a public API in the package dev.gga.aiplayers.api. Use it to tell bots apart from human players, or to write a plugin that teaches bots what your mod adds: its ores, its tools and armor as rungs of the gear ladder, its machines as stations bots work by hand, and what its creatures drop. Since version 1.0.0 that package is the stable surface. The types a plugin builds or names (AIPlayersPlugin, AIPlayersExtensions, AIPlayersApi, AIPlayer, Rung, Station, SupplyKind, StructureNeed, Charge, RecipeSource and ToolKind) keep working across releases. Everything outside it may move.

AI Players itself names no other mod. Support for a specific mod lives in a companion module (an adapter), a separate jar built on this API. The first one, for Tech Reborn, is in the works (see the roadmap).

What works without any integration

Bots read the game’s own data, so a lot of modded content works out of the box:

  • Recipes in the server’s recipe manager (crafting and smelting), modded ones included.
  • Foods with the vanilla food component.
  • Logs in #minecraft:logs (felled only with their tree’s own leaves nearby), and iron and copper ores in #minecraft:iron_ores and #minecraft:copper_ores.
  • Ores in the conventional #c:ores/<name> tags. Every such tag becomes an ore the bots know, mined with the lowest vanilla pickaxe that gets its drops, at the height a play style’s mining.ore_heights gives it (Mining).
  • Crops in #minecraft:crops that have an age and no half. A play style can list their planting item in farm.crops (Farming and animals).
  • Fuel: when a bot plans a smelt it gathers coal, charcoal or vanilla planks, but it burns any stackable fuel it already holds, modded ones included.

Bots are real players, so your mod’s player events, permissions and protections apply to them too. A data pack can also extend AI Players’ tags. A modded machine is the one thing that needs a plugin: a bot only works it once a plugin describes it as a station.

Detecting bots

Every bot entity implements the AIPlayer marker interface:

Detecting a bot
import dev.gga.aiplayers.api.AIPlayer;
import dev.gga.aiplayers.api.AIPlayersApi;
if (AIPlayersApi.isBot(entity)) {
AIPlayer bot = AIPlayersApi.asBot(entity).orElseThrow();
String name = bot.botName();
UUID id = bot.botId();
Optional<String> faction = bot.factionId();
}

AIPlayersApi.isBot(Entity) and asBot(Entity) accept null. You can also check entity instanceof AIPlayer.

The plugin entrypoint

A mod extends the AI through a class implementing AIPlayersPlugin, declared under the aiplayers entrypoint in its fabric.mod.json.

fabric.mod.json (excerpt)
{
"entrypoints": {
"aiplayers": ["com.example.mymod.MyAIPlayersPlugin"]
}
}
MyAIPlayersPlugin.java
public final class MyAIPlayersPlugin implements AIPlayersPlugin {
@Override
public void register(AIPlayersExtensions extensions) {
// A modded ore bots mine on purpose: needs an iron pickaxe, richest at y = -20
extensions.registerOre(
Identifier.fromNamespaceAndPath("mymod", "mythril_ore"),
Identifier.parse("aiplayers:iron"),
-20);
// A modded animal bots can hunt for its meat (also add it to #aiplayers:prey)
extensions.preyDrops(
Identifier.fromNamespaceAndPath("mymod", "boar"),
entity -> Set.of(Identifier.fromNamespaceAndPath("mymod", "raw_boar")));
}
}

The contract: AI Players calls each plugin’s register once, inside its own initialization and before any server starts, in the order the loader lists the entrypoints. Register during that call only. Every registration made while a server runs is refused with an IllegalStateException. If a plugin throws, or its classes fail to link because its target mod is missing, it’s logged with its mod id and skipped, and what it registered before the error stays.

Optional integrations

If your integration is for a mod that may be absent, check FabricLoader.getInstance().isModLoaded(...) before registering anything for it. Resolve that mod’s blocks and items lazily (an id in the registration, a lookup inside your predicates, readers and drop functions), because register may run before that mod’s own initializer has registered them.

The extension points

MethodWhat it adds
blockCategory(id, predicate, harvestTool, sampleDrops[, dimension])A block category bots can search for and mine (/aiplayer debug <bot> task mine "<id>"), in the Overworld or in the dimension given (Level.NETHER, say). The predicate runs often on the server thread, so keep it cheap and never let it throw. harvestTool is the tool kind the drop sampler tries (null means by hand), and sampleDrops says whether the category’s drops are sampled. A category is also what a station or a supply kind stands on.
registerOre(block, rung, bestY[, product][, dimension])An ore bots mine on purpose, with the rung of the pickaxe it needs (aiplayers:iron, say), the Y level where it’s richest, optionally the item it gives and the dimension it generates in. A plan that needs it from another dimension goes there through a portal first. An ore in a #c:ores/<name> tag needs none of this. Register it only for what the tag can’t say, and the plugin’s entry then wins for its blocks.
recipeSource(server -> source)Extra ways to obtain items, indexed with vanilla’s recipes at server start and data pack reload. A source lists crafting entries (naming a crafting recipe), cooking entries (a smelting recipe) and machine entries (a station, its inputs, its outputs and the time one batch takes).
rung(rung) and rung(rung, charge)A rung of the gear ladder: the tools and armor a mod’s tier gives, where it sits between the vanilla tiers, and how it wears.
toolTier(item, rung, kind)The rung and kind of a tool whose id doesn’t follow the vanilla <tier>_<kind> pattern (a drill as an iron pickaxe, say). An id no rung has is refused. Register the rung before the tools that name it.
station(station)A mod’s machine, worked by hand through its menu or by using an item on a block (stations).
supply(kind)What a machine needs standing beside it, such as a generator for power (supplies).
structureNeed(id, template, casings, reader)A shell of blocks built round a machine, read as a level (structure needs).
preyDrops(entityType, entity -> drops)What an animal drops when killed, as a function of the live entity (like a sheep’s wool color), so bots plan to hunt it. The animal must also be in #aiplayers:prey.
monsterDrops(entityType[, dimension], entity -> drops)The same for a monster bots hunt, which must be in #aiplayers:huntable_monsters, in the Overworld or in the dimension given.
targetWeight(item, bonus)How much a modded weapon adds to its holder’s weight in the gear comparison. For reference, a diamond sword adds 0.6.

Rungs

A tool’s place on the gear ladder is a rung, named by id. The six built-in rungs are the vanilla tiers: aiplayers:wood, aiplayers:stone, aiplayers:copper, aiplayers:iron, aiplayers:diamond and aiplayers:netherite. A plugin adds its own with extensions.rung(new Rung(...)):

FieldWhat it is
idThe rung’s id, mymod:drill.
toolsThe item of each tool kind it fills (SWORD, PICKAXE, AXE, SHOVEL), at least one. One item may fill several kinds.
armorThe item of each armor slot it fills (HEAD, CHEST, LEGS, FEET): all four or none. Optional.
materialThe ingredient gathered for it (the iron ingot for iron), or empty for a rung made by machines.
miningLevelWhat its tools mine: wood 0, stone and copper 1, iron 2, diamond and netherite 3.
rankIts place on the ladder. The built-in rungs rank 100 (wood), 200, 300, 400, 500 and 600 (netherite), so a drill ranked 450 comes after iron and before diamond.
detourWhether the ladder climbs it only when it’s a play style’s goal, like copper.
targetBonusWhat its weapon adds to its holder’s threat weight (iron 0.4, diamond 0.6).
wearDURABILITY, or CHARGE for a tool that runs on charge. Optional, durability by default.

A rung whose id, rank, tool or armor item another rung already has, or whose id is in the aiplayers namespace, is refused with an IllegalArgumentException naming it. What a rung’s tools can mine follows from its mining level, so a level 2 drill mines diamond ore and never obsidian, and a plan that needs a pickaxe for a block makes the lowest-ranked rung’s that reaches it. The ladder climbs rungs by rank. A rung that fills no sword or axe is climbed by its pickaxe alone, with the sword and axe staying the best lower rung’s. A rung with no material is planned through the recipes alone. A bot wears the armor set of the rung it has climbed, capped at its style’s gear_goal, and a rung with no armor (a drill) wears the best set ranked below it.

A play style’s gear_goal and nether.min_tier take a rung id, so a pack aims its bots at a mod’s rung with "gear_goal": "mymod:drill". A bare name ("iron") is the vanilla rung. A rung id no plugin registered fails the style’s load with a message naming it (Play style files).

Tools that run on charge

An electric tool is never broken, only empty. Its rung says so with Rung.Wear.CHARGE and is registered with its charge, extensions.rung(rung, new Charge(reader, stations, chargers)):

FieldWhat it is
readerA function of an item stack giving its charge from 0 (empty) to 1 (full), read through the mod’s own energy API.
stationsThe ids of the charging stations that recharge it, tried in order. Each needs a charge slot in its slot map.
chargersItems that charge the tool while carried (a battery the mod ticks in the inventory), each with a reader of its own charge.

A tool below a tenth of its charge counts as worn, and one at zero as empty: it’s never thrown away or stowed, it still counts as the rung climbed, and the best-tool choice passes over it while a charged tool of its kind is held. A worn tool is recharged rather than made again. The bot takes it to the charging station it remembers (else the nearest, else it places the station’s item), puts the tool in the charge slot with its own click, waits while the reader shows the charge rising and takes it out full. A charge that stops rising for 200 ticks ends the wait. One that would take longer than a short smelt is left, and the bot comes back for it once it should be full. While a charger above a tenth of its own charge is carried, no recharge is made, and a worn charger is recharged like a tool. A reader that throws is logged once and its tool read as charged.

Stations and machine recipes

A mod’s machine is worked by hand, as a furnace is. A plugin describes it as a station and its recipes as machine entries, and the core never names the mod’s classes. Register a station with extensions.station(...) before any server starts. A second station with the same id is refused.

A menu station, new Station.Menu(id, category, item, slots), is a block with a menu:

FieldWhat it is
idThe station’s id, mymod:kiln. A bot remembers the station it uses under this id.
categoryThe id of the block category whose blocks are the station (register it with blockCategory).
itemThe item that places it, or empty for one that’s only found.
slotsThe slot map, below.

The slot map, new Station.SlotMap(menuType, inputs, outputs, supplies, progress, total), says how the menu is laid out: the menu type’s registry id, the input slot indices in the order of a recipe’s inputs, the output slot indices, the supply slots (new Station.SupplySlot(slot, items): a fuel slot and the items it takes, the first listed preferred), and the indices of the data slots holding the progress and its total (both or neither). Indices are menu slot indices, so the player’s 36 inventory slots after the machine’s own don’t count. A seventh argument names a charge slot for a charging station, which may then have no input and no output.

A bot works a menu station the way it works a furnace. It uses the one it remembers, else the nearest block of the category, else places the station’s item. It opens it with its own click, checks that the menu’s type and slots are the ones the map names before moving anything (if not, the step fails the <station> menu is not the one expected), puts the inputs in slot by slot and one listed item per batch into each supply slot, waits for the progress to run and takes the outputs. A load longer than a short smelt is left, and the bot comes back when it’s due, as with a furnace. Hoppers, side configuration, fluids and recipes chosen in the menu aren’t used. A bot of a faction that places a menu station at its base puts it in the base’s machine yard, where every member uses it and a raider can carry it off, so the station’s block should drop its own item when broken.

An item-on-block station, new Station.ItemOnBlock(id, category, tool, face, yields), is worked by using an item on a block: the item used (kept, like a tool), a function of the block’s state naming the face to use it on (empty while the block isn’t ready, and the step then fails the <station> is not ready), and what one use yields.

A machine entry goes in a recipe source’s machine() list: new RecipeSource.MachineEntry(station, inputs, outputs, time), with the station’s id, the inputs in the order of the input slots (new MachineEntry.Input(items, count): the item ids the slot accepts and how many one batch takes), the outputs of one batch with their counts, and the ticks one batch takes. A fifth argument is the structure level the entry needs (0 by default). An entry with a missing field, no input, no output or a count below 1 leaves its whole source out of that build. A plan makes an item through a machine when that’s cheaper than the other ways, counting each batch’s time, the station’s item and placing when none is known, and a supply item per batch. An entry whose station nobody registered fails needs a machine this bot cannot operate before any block is touched.

Supplies

A machine may need something beside it that isn’t in its menu: power from a generator standing on one of its six faces, say. A menu station names the supplies it needs by id (new Station.Menu(id, category, item, slots, supplies, structure), with supplies a list such as List.of(Identifier.parse("mymod:power"))), and a plugin registers the blocks that meet a supply as supply kinds with extensions.supply(...):

FieldWhat it is
supplyThe supply id it meets, as a station names it.
categoryThe id of the block category whose blocks are this kind.
itemThe item that places it.
menuTypeThe registry id of the menu it’s fed through.
feedsIts feed slots, each a Station.SupplySlot(slot, items): the slot index and the items it takes, one per batch.
readyThe readiness reader: a function from the live block entity to whether it gives the supply right now.

The reader is how the core learns that the block runs without naming its class. It runs on the server thread, and one that throws counts as not ready, is logged once and never stops a bot. Several kinds may meet one supply, and the first registered that a plan can obtain is used. A plan counts a supply the way it counts fuel: nothing for one standing ready beside the remembered station, one feed item per batch for one standing idle, else the kind’s item, its placing and its feed. Before loading the station the bot reads its six neighbors. It reuses a ready supply, feeds one standing idle, or places the carried supply item on a free side from within reach, opens its menu with its own click, feeds it and waits up to 200 ticks for the reader to say ready (else the step fails the <supply> beside the <station> is not ready). Cables, supplies not touching the station and side configuration aren’t used.

Structure needs: a shell round a station

Some machines only work inside a shell of blocks built round them, and read a level from it (a blast furnace’s heat from its casings). Register the shell with extensions.structureNeed(id, template, casings, reader) and name its id in the menu station:

ArgumentWhat it is
idThe need’s id, mymod:blast_furnace_shell.
templateA vanilla structure file, data/<namespace>/structure/<path>.nbt, in the plugin’s jar or a data pack (a pack may replace it under the same id).
casingsThe casings it accepts, worst first: new StructureNeed.Casing(block, level), a block id and the level a whole shell of it reads, strictly rising.
readerA function from the station’s block entity to its level, run on the server thread.

The template holds the station’s block exactly once, with the cell in front of it (the way it faces, north for a block with no facing) left as air for the way in. Every other block is a full cube: a casing cell when it’s one of the casings, any other block placed as it is. No door, roof or size rule applies. A template that breaks a rule is refused with one log line, and the station has no shell.

A plan for an entry whose shell reads less than it needs picks the worst casing that reaches the level, obtains one for each casing cell not already holding it or a better one, and builds the shell round the station (placing the station first when none stands), turned the way the station faces. The bot breaks a lesser casing or anything else in a cell before placing, clicks every block from a stand outside the shell, never touches the station’s cell or the way in, and picks up what it broke. Before it loads a job it reads the level. A shell that no longer reaches it (a casing broken) fails the load the shell reads <n>, needs <m>, and the next plan repairs it.

Stocked intermediates: the hoard

A mod’s ladder usually runs through parts that take several machines to make (plates, circuits, cables). A play style lists them in its hoard and the base keeps them in stock. Any hoard item that no other objective fills (an ore’s products, emeralds, blaze rods and nether wart have their own) is filled by the hoard objective, which makes up to a stack of it from what the world gives and stores it in the storehouse. A plan takes a hoard item from the chests before making one, but leaves a reserve of half the target there, and a plan that would have to make such an item from scratch when the stock is short fails with needs <item> stocked instead of searching deeper. The bot then fills that item next. See Play style files.

Companion modules

AI Players ships its adapters as separate jars, one per mod, built on this API. The core gains no runtime dependency from them, and a server runs the core alone, the core with an adapter, or an adapter without its mod (it logs and skips). An adapter can also ship a play style in its jar, like any data pack. The first adapter, for Tech Reborn, is in progress, with Tech Extensions and Farmer’s Delight planned after it (roadmap).

Technical details

Known limits
  • A modded hoe has no rung, a rung that fills no sword gives no miner’s spare, and an armor set needs all four pieces.
  • Ore categories discovered from tags aren’t in the cached site queries, so a cached search never looks for them.
  • A take from a chest moves whole stacks, so the hoard’s reserve holds in the plan, not in the chest.
  • A machine load and a charge job at one station replace each other.
  • A station’s pending output is read from its block entity as one container.

Last updated Nov 9, 2026