Guía de MagmaCore para desarrolladores

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.

MagmaCore es una biblioteca que se incluye dentro del JAR de los plugins que la usan. No es un plugin de servidor independiente y no debe aparecer en depend como si los jugadores pudieran instalar un JAR de plugin de MagmaCore.

Dependencia y empaquetado

La coordenada de desarrollo actual es com.magmaguy:MagmaCore:2.2.0-SNAPSHOT, disponible en el repositorio de snapshots de MagmaGuy. Los snapshots pueden cambiar sin que cambie esa cadena de versión. Registra el artefacto resuelto cuando necesites compilaciones reproducibles.

Gradle Kotlin DSL

repositories {
    maven("https://repo.magmaguy.com/snapshots")
}

dependencies {
    implementation("com.magmaguy:MagmaCore:2.2.0-SNAPSHOT")
}

Maven sections

<repositories>
    <repository>
        <id>magmaguy-snapshots</id>
        <url>https://repo.magmaguy.com/snapshots</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.magmaguy</groupId>
        <artifactId>MagmaCore</artifactId>
        <version>2.2.0-SNAPSHOT</version>
    </dependency>
</dependencies>

Estas declaraciones resuelven la dependencia. Configura la tarea de empaquetado de dependencias de tu compilación para incluirla en el JAR final del plugin. Sigue las reglas de reubicación de un plugin existente con las mismas necesidades de integración y comprueba las búsquedas por reflexión basadas en cadenas al cambiar nombres de paquetes. La distribución ya reubica org.luaj y org.reflections en com.magmaguy.shaded.

Cada plugin puede cargar su propia copia de la biblioteca. Las clases Java con el mismo nombre procedentes de distintos cargadores de clases de plugins son tipos diferentes. Usa los contratos explícitos entre plugins, como el servicio de poderes Lua de EliteMobs y los adaptadores del registro de ubicaciones. No conviertas un objeto privado de MagmaCore de otro plugin al tipo de tu propia copia.

Módulos y responsabilidades

Módulo	Responsabilidad
core	Ciclo de vida del plugin, configuración, comandos, menús, partidas, consultas de ubicación, scripting Lua, contenido de Nightbreak y utilidades compartidas
nms:core	NMSManager, NMSAdapter e interfaces de EasyMinecraftGoals independientes de la versión
nms:v*	Implementaciones del contrato NMS para cada versión del servidor
dist	Distribución empaquetada que contiene el núcleo y los adaptadores activos

Los encantamientos compartidos, las acciones de objetos, la gestión de cuentas, los menús de configuración, los catálogos y las actualizaciones pertenecen a los servicios del núcleo. Reutiliza el componente responsable al añadir funciones a un plugin que consuma la biblioteca.

Ciclo de vida del plugin

El ciclo de vida mínimo del núcleo sigue el patrón de los plugins que ya lo usan:

CoreConsumer.java

package example;

import com.magmaguy.magmacore.MagmaCore;
import org.bukkit.plugin.java.JavaPlugin;

public final class CoreConsumer extends JavaPlugin {
    @Override
    public void onLoad() {
        MagmaCore.createInstance(this);
    }

    @Override
    public void onEnable() {
        MagmaCore.onEnable(this);
    }

    @Override
    public void onDisable() {
        MagmaCore.shutdown(this);
    }
}

Esta inicialización tiene efectos más allá de obtener un objeto de utilidades. Inicializa la gestión de cuentas, los comandos compartidos, los listeners y el soporte de bloques temporales. La sobrecarga createInstance(plugin, NightbreakPluginSpec) proporciona los textos de los comandos compartidos específicos del plugin.

Prefiere los métodos que reciben explícitamente el plugin propietario. getInstance() hace referencia al singleton de la copia cargada de la biblioteca, cuyo plugin solicitante se establece al crear esa instancia. No debe usarse para deducir la propiedad de todos los plugins que consumen la biblioteca.

shutdown(plugin) elimina los registros del descargador, el actualizador de contenido, la inicialización y el actualizador de ese plugin, y después también cierra el entorno de ejecución compartido de la copia cargada. No se limita a eliminar una entrada de un registro. Llámalo para tu propia biblioteca integrada durante el cierre de tu plugin; nunca cierres la biblioteca de otro plugin para reiniciar tu integración.

Llama a createInstance desde onLoad para registrar el propietario del archivo de configuraciones del plugin antes de que otro plugin pueda importar contenido para él. El archivado se ejecuta mediante la propia implementación de MagmaCore incluida en el plugin de destino; no interpretes sus reglas de retirada con tu copia de MagmaCore.

Para un arranque por fases, startInitialization acepta trabajo asíncrono, trabajo síncrono y callbacks de éxito y fallo. Archiva los archivos de configuración que coincidan con formatos retirados antes de ejecutar el trabajo de inicialización asíncrono. Mantén las operaciones de mundos y entidades de Bukkit en la fase síncrona. El trabajo asíncrono prolongado debe comprobar isShutdownRequested(plugin) entre fases. getInitializationState e isPluginReady exponen el estado del gestor de inicialización.

NMS y entidades de paquetes

Inicializa NMS solo si tu plugin lo necesita, mediante NMSManager.initializeAdapter(plugin) de com.magmaguy.easyminecraftgoals. Comprueba NMSManager.isEnabled() antes de usar funciones que dependan del adaptador. La llamada de inicialización puede fallar o encontrar una versión de servidor no compatible.

La distribución incluye las siguientes familias de adaptadores:

Adaptador	Versiones de Minecraft
v1_21_R3	1.21.4
v1_21_R4	1.21.5
v1_21_R5	1.21.6, 1.21.7, 1.21.8
v1_21_R6	1.21.9, 1.21.10
v1_21_R7_spigot, v1_21_R7_paper	1.21.11, implementaciones separadas de Spigot/Paper
v26	26.1 y la familia actual de adaptadores 26.x

La selección de adaptadores no garantiza la compatibilidad general con futuras versiones del servidor. El selector de ejecución de NMSManager determina si el servidor instalado puede cargar un adaptador. Las versiones anteriores a 1.21.4 quedan fuera del conjunto actual de adaptadores.

EasyMinecraftGoals gestiona las entidades que solo existen mediante paquetes, su visibilidad, el enrutamiento de sus interacciones y las utilidades de movimiento y búsqueda de rutas. No son entidades normales del mundo. Gestiónalas mediante su API responsable y elimina los objetos que cree tu plugin mientras el adaptador siga disponible.

Consultas de ubicación y protección

com.magmaguy.magmacore.location.LocationQueryRegistry expone consultas de mazmorras y protección de regiones, incluidas isInAnyDungeon, isInAnyProtectedRegion y canBuild.

Registra proveedores personalizados con registerDungeonLocator o registerProtectionProvider; elimina el registro del mismo proveedor al deshabilitar su propietario. El registro incluye adaptadores para plugins existentes y descubre proveedores de mazmorras de otros plugins sin exigir que compartan un único cargador de clases de MagmaCore.

Comprueba la consulta que corresponda a la acción. Estar fuera de una mazmorra no equivale a tener permiso de construcción en una ubicación. Ejecuta las consultas que accedan a Bukkit o a plugins de protección en el hilo del servidor.

Compilar un plugin tras modificar la biblioteca

Usa JDK 21 y publica MagmaCore en Maven Local con ./gradlew publishToMavenLocal, o .\gradlew.bat publishToMavenLocal en Windows. Asegúrate de que el plugin resuelva ese repositorio y la versión prevista, y después vuelve a compilar su JAR con las dependencias integradas. Sustituir una biblioteca en Maven Local no actualiza un plugin ya compilado.

Consulta el índice para desarrolladores para las API de plugins instalados. Esas integraciones normalmente usan provided o compileOnly; el contrato de biblioteca integrada de MagmaCore es distinto.