API

PracticeBotService is how another plugin asks for a bot: a way of fighting, at a level of skill, in a place you choose. Everything a player tunes from /bot — thirty-odd settings, sliders, armour pieces — stays out of the contract on purpose. You ask for a fight; the bot decides how well it is executed.

PracticeBots.get().ifPresent(bots ->
    bots.spawn(BotSpec.duel(player, arena.spawn(), CombatMode.CRYSTAL_PVP, Difficulty.HARD))
        .thenAccept(bot -> match.track(bot)));

Everything below lives in net.exylia.lib.api.practicebot, in ExyliaLib's exylia-api artifact — not in the bot plugin's own jar. That is what makes the interface one class rather than two: see the public API page for the whole of that reasoning.

Checking it is there

PracticeBots.get() is the way in, and it is an Optional because it can genuinely be empty:

• the plugin is not installed,
• it is installed but disabled,
• or it is still enabling and has not registered its service yet.

Every caller has to handle that, which is the point of a soft dependency — an integration with one is a feature that may simply not be there, not an error to report.

if (!PracticeBots.available()) {
    // Offer something else. Do not log this.
}

available() is the same question when you only want a yes or no.

Spawning

spawn(BotSpec) returns a CompletableFuture<BotHandle>.

It fails, rather than returning empty, in two cases:

bots.spawn(spec)
    .thenAccept(bot -> scheduler.runAtEntity(bot.entityId(), () -> ready(bot)))
    .exceptionally(failure -> {
        Throwable cause = failure.getCause() != null ? failure.getCause() : failure;
        if (cause instanceof BotLimitReachedException full) {
            player.sendMessage("The server is running " + full.capacity() + " bots. Try again shortly.");
        }
        return null;
    });

active() and capacity() are there so you can ask before offering somebody a fight you cannot start. Every bot thinks once per tick and searches for a path of its own, so the ceiling is real rather than a formality. See Limits.

The service

What to spawn: BotSpec

An immutable record. owner, spawn, mode and difficulty are required; a null one is rejected on construction, as is a spawn location with no world.

Three shorthands cover most calls:

new BotSpec(owner, spawn, mode, difficulty, respawn);                 // dressed by its mode
new BotSpec(owner, spawn, mode, difficulty, respawn, name, skin);     // named and skinned
BotSpec.duel(owner, spawn, mode, difficulty);                         // fights its owner, never respawns
BotSpec.duel(owner, spawn, mode, difficulty, name, skin);             // the same, with its own identity

withKit(BotKit) and withLimits(BotLimits) return a copy with that one thing changed, so a spec built once per arena can be finished per match.

A kit outranks the mode

A mode ships with a loadout of its own, and that is right for the plugin's own /bot: somebody asking for crystal PvP in a sandbox wants whatever crystal PvP is balanced around. It is wrong for a practice match, where both sides are supposed to be fighting the same kit — the one the server's admins built, with their armour, their enchantments, their potion count.

So when a spec carries a BotKit, the kit wins. The mode is then only the school the bot fights with: which techniques it knows, how it moves, when it retreats. What it is holding comes off the items.

Concretely, a non-empty kit replaces the mode's main hand, off hand, totem count and weapon damage, reading each of them back off the items themselves — and it clears the mode's free buffs. Strength, Speed and fire resistance are a loadout's shorthand for potions a sandbox bot was never going to drink; a kit that wants the bot buffed puts the potions in the kit.

BotSpec spec = BotSpec.duel(player, arena.spawn(), CombatMode.POT_PVP, Difficulty.HARD)
                      .withKit(BotKit.of(kit.contents()))
                      .withLimits(BotLimits.unlimited());

That is exactly how ExyliaPracticeCore drives its bot matches: the arena's kit, the arena's distances, and the mode left to decide only how the fight is played.

BotKit

41 slots in the layout Bukkit gives a player: 0-35 storage (0-8 the hotbar), 36-39 armour boots-first as getArmorContents() orders it, 40 the off hand. It is the same array a practice plugin already stores per kit, so nothing has to be translated on the way out. A wrong length is rejected.

Items are deep-copied on the way in and on the way out. A kit is a description of a fight; a caller that kept editing the array it handed over would be editing a fight that already started.

You do not name the main hand. The bot works out which items it can hold, which it can drink and which mean nothing to it — a sender that had to decide would be guessing at a question the other side answers better, and would need updating every time the bot learns to use something new.

BotLimits

Two distances, in blocks, and the reason they are in the API at all: the plugin's own figures are tuned for a dummy standing next to its owner, and a match is the opposite of that on both counts.

Left unsent, the plugin's configured values apply and nothing changes for anybody else. Sent, they are the ones the bot runs on — a bot spawned across an arena under sandbox limits stands still waiting to be approached, and one whose opponent runs the length of the map is quietly removed mid-fight.

The handle

BotHandle is the bot from the outside — a handle, not the bot. The entity it drives and the state machine deciding its swings stay inside the plugin that owns it. It never becomes valid again once the bot is gone: hold it for as long as the fight lasts, drop it after, and check isAlive() rather than assuming.

health() being a snapshot is deliberate. Entities belong to the thread that owns their region, and something drawing a health bar every couple of ticks from somewhere else has no business reaching into one.

Modes and difficulties

CombatMode is how it fights, Difficulty is how well. Together they are the whole configuration surface a normal user ever touches.

CombatMode.playable() is every mode except NONE, in declaration order — build a picker from it and it grows on its own the day a mode is added. next() and previous() step through both enums for a cycling button.

Both have a parse(String) that absorbs the names older versions and configurations used, and neither ever throws: an unknown name reads as NONE for a mode and NORMAL for a difficulty. Nothing persists an ordinal, so the declaration order can change without breaking a stored row.

Events

One event, net.exylia.lib.api.practicebot.event.PracticeBotDeathEvent. It extends Event and is not cancellable — there is no Cancellable on it and nothing to gate. By the time it runs the bot is already gone; the handle is there to say which one it was and who it belonged to, not to be kept.

It fires on death, whether or not the bot was set to respawn — and also when a bot's own tick loop fails, because such a bot leaves the world and has to be reported gone rather than left standing as an invulnerable statue in somebody's arena. It does not fire for the ordinary removals: remove(), the owner dying, changing world, or walking past the leash. A match that needs to know about those watches its own conditions, or calls remove() itself.

@EventHandler
public void onBotDeath(PracticeBotDeathEvent event) {
    matches.byBot(event.bot().entityId())
           .ifPresent(match -> match.finish(event.lastTarget()));
}

Compare event.bot().entityId() rather than holding the handle: it is the one thing about a dead bot that is still worth anything.

What it does not expose

No access to the thirty-odd settings a player tunes from /bot, no way to read or write somebody's saved row, no menu openers, and no event other than the death above. An integration asks for a way of fighting at a level of skill and lets the bot decide the rest — a public method for every slider would be a contract that breaks every time the AI learns something.

BotKit and BotLimits are newer than the rest: they arrived in ExyliaLib 1.84.0 and 1.86.0, while everything else has been there since 1.73.0. Build against a recent exylia-api if you want them.

If something you genuinely need is still missing, ask on Discord.