API Java de EliteMobs
La referencia Java generada permite buscar clases, métodos y firmas, e indica la versión y el commit del código fuente de cada módulo.
Esta guía cubre la API de EliteMobs 10.9. La versión Maven pública actual es com.magmaguy:EliteMobs:10.9.13. Usa el ámbito provided o compileOnly y declara depend: [EliteMobs]. Usa la dependencia que corresponda al plugin instalado. El índice para desarrolladores contiene la configuración de Maven y Gradle.
Puntos de entrada
| Paquete o tipo | Propósito |
|---|---|
com.magmaguy.elitemobs.api | Eventos Bukkit de combate, misiones, NPC, teletransportes, mazmorras e inicialización |
com.magmaguy.elitemobs.api.instanced | Eventos del ciclo de vida de partidas instanciadas |
com.magmaguy.elitemobs.api.utils.EliteItemManager | Utilidades para identificar objetos de élite y consultar su nivel, daño y defensa |
com.magmaguy.elitemobs.entitytracker.EntityTracker | Obtener la entidad registrada en EliteMobs a partir de una entidad Bukkit |
com.magmaguy.elitemobs.api.power.EliteLuaPowerService | Registrar y asociar poderes Lua mediante el entorno de ejecución de EliteMobs |
com.magmaguy.elitemobs.api.mind.EliteMindService | Registrar programas Lua de Mind y generar actores que los ejecuten |
EliteEntity, CustomBossEntity y RegionalBossEntity representan actores activos que pertenecen al plugin. Exponen más detalles de implementación que los contratos de eventos. Conserva sus referencias solo mientras exista el actor y evita modificar directamente las colecciones del registro de entidades.
Escuchar la concesión de XP de habilidades
Esta clase completa de plugin cancela la concesión de XP de habilidades de combate para los jugadores con el permiso example.blockskillxp de tu integración. Añade el nombre completo de su clase a tu propio plugin.yml como main.
package example;
import com.magmaguy.elitemobs.api.EliteSkillXpGainEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.plugin.java.JavaPlugin;
public final class SkillXpIntegration extends JavaPlugin implements Listener {
@Override
public void onEnable() {
getServer().getPluginManager().registerEvents(this, this);
}
@EventHandler(ignoreCancelled = true)
public void onSkillXp(EliteSkillXpGainEvent event) {
if (event.getPlayer().hasPermission("example.blockskillxp")) {
event.setCancelled(true);
}
}
}
EliteSkillXpGainEvent se ejecuta de forma síncrona después de las comprobaciones de elegibilidad para el combate y de aplicar los multiplicadores nativos y por permisos. getOriginalXp() es la cantidad en el momento de crear el evento; getXp() incluye los cambios de los listeners anteriores. setXp(long) rechaza valores negativos. La cancelación o una cantidad final de cero impiden tanto la concesión como sus avisos de ganancia.
EliteMobs aplica la cantidad aceptada, gestiona su persistencia y ejecuta los efectos de subida de nivel. No escribas la XP del jugador por separado desde este listener. Las modificaciones administrativas de XP y la XP de clase usan rutas distintas y no corresponden a la concesión de XP de habilidades de combate de este evento.
Los demás eventos tienen sus propios contratos. En particular, cancelar EliteMobSpawnEvent impide la construcción y elimina la entidad viva subyacente; no deja un mob normal en su lugar. EliteMobDeathEvent y EliteMobRemoveEvent describen transiciones distintas del ciclo de vida. Comprueba el evento y el código que lo emite antes de tratar cada eliminación como una muerte o una recompensa.
Obtener una entidad registrada
EliteEntity elite = EntityTracker.getEliteMobEntity(bukkitEntity);
if (elite == null) {
return;
}
Importa com.magmaguy.elitemobs.entitytracker.EntityTracker y com.magmaguy.elitemobs.mobconstructor.EliteEntity. La búsqueda puede devolver null; una entidad Bukkit no tiene por qué ser un EliteMob registrado en ese momento. Pasa una entidad Bukkit existente y no nula, y realiza la búsqueda en el hilo del servidor.
Para el equipamiento, empieza por EliteItemManager.isEliteMobsItem(itemStack) y la utilidad correspondiente a la magnitud que necesitas, como getItemLevel, getEliteDefense o getTotalDPS. Son magnitudes distintas; el nivel de un objeto no es su daño final. Comprueba cómo trata los valores nulos cada método, en lugar de suponer que todas las utilidades aceptan un objeto vacío.
Inicialización y recargas
EliteMobs realiza una inicialización asíncrona seguida de otra en el hilo del servidor. EliteMobsInitializedEvent se emite después de completar correctamente la secuencia, incluida la inicialización correspondiente a una recarga. Registra los listeners a tiempo para recibirlo. Las integraciones habilitadas después de ese evento también deben contemplar que el plugin ya esté inicializado.
Las referencias a entidades, las asociaciones y los servicios almacenados en caché pueden quedar obsoletos durante una recarga. Vuelve a obtener lo que necesite tu integración cuando termine la inicialización. No llames a onEnable, onDisable ni al cierre de MagmaCore en nombre de EliteMobs.
Integración de poderes Lua
Obtén el servicio mediante Bukkit después de la inicialización de EliteMobs:
EliteLuaPowerService powers = Bukkit.getServicesManager()
.load(EliteLuaPowerService.class);
if (powers == null) {
return;
}
Importa org.bukkit.Bukkit y com.magmaguy.elitemobs.api.power.EliteLuaPowerService. Si el servicio está ausente, trátalo como no disponible en lugar de construir su implementación por tu cuenta.
registerLuaPower(owner, key, revision, source) registra un programa que pertenece a tu plugin. setPowers(owner, eliteEntity, orderedPowerKeys) sustituye toda la colección de poderes del actor por nuevas instancias de ejecución en el orden indicado. Todas las claves deben pertenecer a ese propietario, y se rechazan las claves duplicadas. Esta operación no añade poderes a los que ya tenía el jefe. El despacho de eventos ejecuta los poderes por executionPriority() ascendente y usa el orden indicado solo para deshacer empates.
inspectPowers devuelve los programas gestionados por el servicio en el orden de asociación. inspectPowerActivity expone su actividad de ejecución. unregisterOwner(owner) elimina las entradas del catálogo del propietario y desvincula sus instancias de ejecución de los actores activos; úsalo cuando se deshabilite tu integración si el servicio sigue disponible.
Todas las modificaciones se ejecutan en el hilo del servidor. El servicio evita expresamente exponer tipos de scripting de MagmaCore entre los cargadores de clases de los plugins. Pasa los tipos de la API de EliteMobs, en lugar de objetos de una copia privada de MagmaCore incluida en tu JAR.
Para crear hooks y contenido Lua, consulta la referencia compartida de scripting. El servicio Java coordina la asociación y la propiedad; EliteMobs sigue gestionando el ciclo de vida de los poderes.
Programas Lua de Mind
com.magmaguy.elitemobs.api.mind.EliteMindService ejecuta IA escrita en Lua sobre actores de EliteMobs. Obtenlo del gestor de servicios de Bukkit después de EliteMobsInitializedEvent, igual que el servicio de poderes. EliteMobs solo lo registra cuando el adaptador NMS del servidor puede alojar minds nativas; en caso contrario, la búsqueda devuelve null.
Registra los módulos con registerLuaModule(owner, key, revision, source) antes que los programas que los usan y después registra los programas con registerLuaProgram. El espacio de nombres de cada clave debe pertenecer a tu plugin, y el id y la revisión de la definición Lua deben coincidir con la clave y la revisión que pasas. El id de un programa no puede ser el id de uno de sus módulos. Repetir un registro idéntico no hace nada. Un código fuente modificado necesita una revisión mayor. El formato Lua, incluidos los settings de los módulos, que EliteMobs no lee, se describe en Programas de Comportamiento.
spawn(EliteMindSpawnRequest) crea un actor sobre un cuerpo Mind nativo que ejecuta el programa solicitado, con un nivel de 1 o superior. setProgram cambia el programa de un actor que ya tiene un cuerpo Mind; no convierte élites normales. setPaused detiene y reanuda los ticks de Mind y los callbacks de poderes del actor, inspect devuelve el estado actual y clearProgram elimina el actor. registerNaturalSpawnProvider permite a tu plugin dejar, suprimir o sustituir las apariciones naturales de élites antes de la conversión aleatoria propia de EliteMobs. unregisterOwner(owner) elimina tus módulos, programas y proveedores, y los actores que siguen ejecutando tus programas.
Las acciones de Mind llegan a los poderes asociados al actor mediante on_mind_action. Las integraciones Java también pueden gestionar una acción para uno de sus poderes con EliteLuaPowerService.registerActionHandler; los hooks Lua tienen la primera oportunidad de aceptarla. Consulta el contexto de programas Mind para la parte de Lua.
Compilar desde el código fuente
El repositorio de EliteMobs se compila con Gradle 9.1.0 y una toolchain de JDK 21. Incluye el wrapper de Gradle para Windows. Desde la raíz del repositorio, ejecuta:
.\gradlew.bat shadowJar
El repositorio no tiene un script gradlew de Unix. En otros sistemas, instala la versión de Gradle indicada en gradle/wrapper/gradle-wrapper.properties y ejecuta gradle shadowJar.
El plugin desplegable es build/libs/EliteMobs.jar. build/libs/EliteMobs-min.jar contiene solo las clases de EliteMobs y no es un plugin funcional. Si está definida la variable de entorno MC_DIST_DIR o la propiedad de Gradle mcDistDir, la compilación también copia EliteMobs.jar a esa carpeta.
El jar integra (shade) MagmaCore, bStats y commons-io. MagmaCore, su runtime de Lua, su biblioteca de reflexión y easyminecraftgoals se reubican bajo com.magmaguy.elitemobs, de modo que EliteMobs lleva su propia copia, aparte de otros plugins que integran MagmaCore. bStats se reubica en com.magmaguy.shaded.bstats. La compilación resuelve com.magmaguy:MagmaCore:2.2.0-SNAPSHOT desde Maven Local antes que desde el repositorio Maven de MagmaGuy; -PmagmacoreVersion=<version> selecciona otra versión publicada de MagmaCore. Cuando el código fuente necesita cambios de MagmaCore más recientes que la compilación publicada, publica primero MagmaCore en Maven Local, como se describe en Compilar un plugin tras modificar la biblioteca. Lo mismo se aplica a un FreeMinecraftModels modificado localmente, contra el que se compila el proyecto como versión 2.12.2.
La tarea test compila y ejecuta las pruebas en una toolchain de JDK 25, porque la API de pruebas de Paper necesita Java 25. El plugin en sí apunta a Java 21.