Guide développeur MagmaCore

La référence Java générée permet de rechercher les classes, méthodes et signatures. La version des sources et le commit utilisés sont indiqués pour chaque module.

MagmaCore est une bibliothèque intégrée dans le JAR des plugins qui l'utilisent par shading. Ce n'est pas un plugin serveur autonome : ne l'ajoutez pas à depend comme si les joueurs pouvaient installer un JAR de plugin MagmaCore.

Dépendance et packaging

Les coordonnées de développement actuelles sont com.magmaguy:MagmaCore:2.2.0-SNAPSHOT, disponibles dans le dépôt de snapshots de MagmaGuy. Un snapshot peut changer sans que cette chaîne de version ne change. Conservez une trace de l'artefact résolu si vous avez besoin de builds reproductibles.

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>

Ces déclarations permettent de résoudre la dépendance. Configurez la tâche de shading de votre build pour l'inclure dans le JAR final du plugin. Suivez les règles de relocation d'un plugin existant ayant les mêmes besoins d'intégration et vérifiez les recherches réflexives basées sur des chaînes lorsque vous changez les noms de packages. La distribution relocalise déjà org.luaj et org.reflections sous com.magmaguy.shaded.

Chaque plugin peut charger sa propre copie de la bibliothèque. Deux classes Java de même nom, chargées par des chargeurs de classes de plugins distincts, sont des types différents. Utilisez les contrats explicites entre plugins, comme le service de pouvoirs Lua d'EliteMobs ou les adaptateurs du registre de localisations. Ne convertissez pas un objet MagmaCore privé d'un autre plugin vers le type de votre propre copie.

Modules et responsabilités

Module	Responsabilité
core	Cycle de vie des plugins, configuration, commandes, menus, parties, requêtes de localisation, scripts Lua, contenu Nightbreak et utilitaires partagés
nms:core	NMSManager, NMSAdapter et interfaces EasyMinecraftGoals indépendantes de la version
nms:v*	Implémentations du contrat NMS propres aux versions du serveur
dist	Distribution assemblée par shading, contenant le cœur et les adaptateurs actifs

Les enchantements partagés, les actions d'objets, la gestion du compte, les menus de configuration, les catalogues et les mises à jour relèvent des services du cœur. Réutilisez le composant responsable lorsque vous ajoutez un comportement à un plugin consommateur.

Cycle de vie du plugin

Le cycle de vie minimal du cœur suit le modèle des plugins existants :

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);
    }
}

Cette initialisation ne se limite pas à obtenir un objet utilitaire. Elle initialise la gestion du compte, les commandes partagées, les écouteurs et la prise en charge des blocs temporaires. La surcharge createInstance(plugin, NightbreakPluginSpec) fournit les textes des commandes partagées propres au plugin.

Préférez les méthodes qui prennent explicitement le plugin propriétaire en argument. getInstance() désigne le singleton de la copie chargée de la bibliothèque ; le plugin demandeur est fixé à la création de cette instance. Ne l'utilisez pas pour déduire le propriétaire de tous les consommateurs.

shutdown(plugin) supprime les enregistrements du téléchargeur, du rafraîchissement de contenu, de l'initialisation et des mises à jour de ce plugin, puis arrête également l'environnement d'exécution partagé de la copie chargée. Son action ne se limite pas au retrait d'une entrée de registre. Appelez cette méthode pour votre propre bibliothèque intégrée lors de l'arrêt de votre plugin ; n'arrêtez jamais la bibliothèque d'un autre plugin pour réinitialiser votre intégration.

Appelez createInstance depuis onLoad afin d'enregistrer le propriétaire des archives de configuration du plugin avant qu'un autre plugin puisse importer du contenu pour lui. L'archivage passe par l'implémentation intégrée au plugin cible ; n'interprétez pas ses règles de retrait de configuration avec votre copie de MagmaCore.

Pour un démarrage en plusieurs phases, startInitialization accepte du travail asynchrone, du travail synchrone et des callbacks de réussite et d'échec. Il archive les fichiers de configuration correspondant à un format retiré avant de lancer l'initialisation asynchrone. Réservez les opérations Bukkit sur les mondes et les entités à la phase synchrone. Un travail asynchrone long doit vérifier isShutdownRequested(plugin) entre ses phases. getInitializationState et isPluginReady exposent l'état du gestionnaire d'initialisation.

NMS et entités par paquets

Initialisez NMS uniquement si votre plugin en a besoin, avec NMSManager.initializeAdapter(plugin) de com.magmaguy.easyminecraftgoals. Vérifiez NMSManager.isEnabled() avant d'utiliser un comportement dépendant d'un adaptateur. L'initialisation peut échouer ou rencontrer une version de serveur non prise en charge.

La distribution contient les familles d'adaptateurs suivantes :

Adaptateur	Versions 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, implémentations Spigot/Paper distinctes
v26	26.1 et famille actuelle d'adaptateurs 26.x

La sélection d'un adaptateur ne garantit pas la compatibilité avec toutes les futures versions du serveur. Le sélecteur d'exécution de NMSManager détermine si le serveur installé peut charger un adaptateur. Les versions antérieures à 1.21.4 ne font pas partie de l'ensemble actuel d'adaptateurs.

EasyMinecraftGoals gère les entités qui n'existent que par paquets, leur visibilité, le routage de leurs interactions et les utilitaires de déplacement et de recherche de chemin. Ce ne sont pas des entités ordinaires du monde. Gérez-les via leur API responsable et nettoyez les objets créés par votre plugin tant que l'adaptateur est encore disponible.

Requêtes de localisation et de protection

com.magmaguy.magmacore.location.LocationQueryRegistry expose des requêtes sur les donjons et les protections de régions, notamment isInAnyDungeon, isInAnyProtectedRegion et canBuild.

Enregistrez les fournisseurs personnalisés avec registerDungeonLocator ou registerProtectionProvider, puis désenregistrez le même fournisseur à la désactivation de son propriétaire. Le registre contient des adaptateurs pour les plugins existants et découvre les fournisseurs de donjons entre plugins sans imposer aux consommateurs un même chargeur de classes MagmaCore.

Choisissez la requête correspondant à l'action. Être en dehors d'un donjon ne signifie pas avoir la permission de construire à cet endroit. Exécutez sur le thread du serveur les requêtes qui utilisent Bukkit ou des plugins de protection.

Recompiler un consommateur après modification de la bibliothèque

Utilisez le JDK 21 et publiez MagmaCore dans Maven Local avec ./gradlew publishToMavenLocal, ou .\gradlew.bat publishToMavenLocal sous Windows. Vérifiez que le plugin consommateur résout ce dépôt et la version voulue, puis reconstruisez son JAR avec shading. Remplacer une bibliothèque dans Maven Local ne met pas à jour un plugin déjà compilé.

Consultez l'index développeur pour les API des plugins installés. Ces intégrations utilisent généralement provided ou compileOnly ; le contrat de bibliothèque intégrée de MagmaCore est différent.