API

PracticeBotService es con lo que otro plugin pide un bot: una forma de pelear, a un nivel de destreza, en el sitio que elijas. Todo lo que un jugador ajusta desde /bot — treinta y pico opciones, deslizadores, piezas de armadura — se queda fuera del contrato a propósito. Tú pides una pelea; el bot decide cómo de bien se ejecuta.

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

Todo lo de abajo vive en net.exylia.lib.api.practicebot, dentro del artefacto exylia-api de ExyliaLib — no en el jar del plugin de bots. Eso es lo que hace que la interfaz sea una sola clase y no dos: el razonamiento completo está en la página de la API pública.

Comprobar que está

PracticeBots.get() es la puerta de entrada, y es un Optional porque de verdad puede venir vacío:

• el plugin no está instalado,
• está instalado pero deshabilitado,
• o todavía está arrancando y aún no registró su servicio.

Todo el que llame tiene que contemplarlo, y esa es justo la gracia de una dependencia blanda: una integración con una es una función que quizá no esté, no un error que reportar.

if (!PracticeBots.available()) {
    // Ofrece otra cosa. No lo registres en el log.
}

available() es la misma pregunta cuando solo quieres un sí o un no.

Generar un bot

spawn(BotSpec) devuelve un CompletableFuture<BotHandle>.

Falla, en lugar de devolver vacío, en dos casos:

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("El servidor está corriendo " + full.capacity() + " bots. Prueba en un momento.");
        }
        return null;
    });

active() y capacity() están ahí para que puedas preguntar antes de ofrecer una pelea que no puedes empezar. Cada bot piensa una vez por tick y busca su propia ruta, así que el techo es real y no una formalidad. Ver Límites.

El servicio

Qué generar: BotSpec

Un record inmutable. owner, spawn, mode y difficulty son obligatorios; uno nulo se rechaza al construirlo, igual que una ubicación de spawn sin mundo.

Tres atajos cubren casi todas las llamadas:

new BotSpec(owner, spawn, mode, difficulty, respawn);                 // vestido por su modo
new BotSpec(owner, spawn, mode, difficulty, respawn, name, skin);     // con nombre y skin
BotSpec.duel(owner, spawn, mode, difficulty);                         // pelea contra su dueño, no reaparece
BotSpec.duel(owner, spawn, mode, difficulty, name, skin);             // lo mismo, con identidad propia

withKit(BotKit) y withLimits(BotLimits) devuelven una copia con esa única cosa cambiada, así que un spec construido una vez por arena se termina de rellenar por partida.

Un kit manda sobre el modo

Un modo viene con su propio equipo, y eso está bien para el /bot del propio plugin: quien pide crystal PvP en un sandbox quiere aquello alrededor de lo que crystal PvP está balanceado. Está mal para una partida de práctica, donde se supone que los dos lados pelean con el mismo kit — el que montaron los administradores del servidor, con su armadura, sus encantamientos y su cuenta de pociones.

Así que cuando un spec lleva un BotKit, gana el kit. El modo pasa a ser solo la escuela con la que pelea el bot: qué técnicas conoce, cómo se mueve, cuándo se retira. Lo que lleva en las manos sale de los ítems.

En concreto, un kit no vacío reemplaza la mano principal, la mano secundaria, la cuenta de tótems y el daño del arma que el modo asumía, leyendo cada cosa de los propios ítems — y borra los buffs gratis del modo. Fuerza, Velocidad y resistencia al fuego son el atajo de un equipo para pociones que un bot de sandbox nunca se iba a beber; un kit que quiera al bot buffeado pone las pociones en el kit.

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

Así es exactamente como ExyliaPracticeCore lleva sus partidas contra bots: el kit de la arena, las distancias de la arena, y el modo decidiendo solo cómo se juega la pelea.

BotKit

41 huecos en la disposición que Bukkit le da a un jugador: 0-35 almacenamiento (0-8 la hotbar), 36-39 armadura empezando por las botas, tal y como los ordena getArmorContents(), y 40 la mano secundaria. Es el mismo array que un plugin de práctica ya guarda por kit, así que no hay que traducir nada al salir. Una longitud distinta se rechaza.

Los ítems se copian en profundidad al entrar y al salir. Un kit es la descripción de una pelea; quien siguiera editando el array que entregó estaría editando una pelea que ya empezó.

No nombras la mano principal. El bot descubre qué ítems puede sostener, cuáles puede beber y cuáles no significan nada para él — quien tuviera que decidirlo estaría adivinando una pregunta que el otro lado responde mejor, y habría que actualizarlo cada vez que el bot aprende a usar algo nuevo.

BotLimits

Dos distancias, en bloques, y la razón de que estén en la API: las cifras del propio plugin están afinadas para un muñeco que está de pie junto a su dueño, y una partida es lo contrario en las dos cosas.

Si no se envían, se aplican los valores configurados del plugin y no cambia nada para nadie. Si se envían, son los que rigen al bot — un bot generado al otro lado de la arena con los límites de sandbox se queda quieto esperando a que se le acerquen, y uno cuyo rival cruza el mapa se elimina en silencio a mitad de la pelea.

El handle

BotHandle es el bot visto desde fuera — un handle, no el bot. La entidad que conduce y la máquina de estados que decide sus golpes se quedan dentro del plugin que lo posee. No vuelve a ser válido una vez que el bot ya no está: guárdalo mientras dure la pelea, suéltalo después, y consulta isAlive() en vez de darlo por hecho.

Que health() sea una foto es deliberado. Las entidades pertenecen al hilo dueño de su región, y algo que dibuja una barra de vida cada par de ticks desde otro sitio no tiene por qué meter mano en una.

Modos y dificultades

CombatMode es cómo pelea, Difficulty es cómo de bien. Juntos son toda la superficie de configuración que un usuario normal llega a tocar.

CombatMode.playable() son todos los modos menos NONE, en orden de declaración — monta un selector con eso y crece solo el día que se añada un modo. next() y previous() recorren los dos enums para un botón cíclico.

Los dos tienen un parse(String) que absorbe los nombres que usaban versiones y configuraciones anteriores, y ninguno lanza nunca: un nombre desconocido se lee como NONE en un modo y como NORMAL en una dificultad. Nada persiste un ordinal, así que el orden de declaración puede cambiar sin romper una fila guardada.

Eventos

Un evento, net.exylia.lib.api.practicebot.event.PracticeBotDeathEvent. Extiende Event y no es cancelable — no implementa Cancellable y no hay nada que frenar. Para cuando se ejecuta el bot ya no está; el handle está ahí para decir cuál era y de quién era, no para guardarlo.

Se dispara al morir, reaparezca o no el bot — y también cuando el bucle de tick de un bot falla, porque un bot así abandona el mundo y hay que reportarlo como ido en vez de dejarlo de pie como una estatua invulnerable en la arena de alguien. No se dispara con las eliminaciones normales: remove(), la muerte del dueño, el cambio de mundo o alejarse más allá de la correa. Una partida que necesite saber de eso vigila sus propias condiciones, o llama a remove() ella misma.

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

Compara con event.bot().entityId() en vez de guardar el handle: es lo único de un bot muerto que todavía vale algo.

Lo que no expone

Ningún acceso a las treinta y pico opciones que un jugador ajusta desde /bot, ninguna forma de leer o escribir la fila guardada de alguien, ningún abridor de menús, y ningún evento aparte de la muerte de arriba. Una integración pide una forma de pelear a un nivel de destreza y deja que el bot decida el resto — un método público por cada deslizador sería un contrato que se rompe cada vez que la IA aprende algo.

BotKit y BotLimits son más nuevos que el resto: llegaron en ExyliaLib 1.84.0 y 1.86.0, mientras que todo lo demás está desde 1.73.0. Compila contra un exylia-api reciente si los quieres.

Si de verdad te falta algo, pregunta en Discord.