MagmaCore-Entwickleranleitung

Die generierte Java-Referenz enthält durchsuchbare Klassen, Methoden und Signaturen sowie die Quellversion und den Commit jedes Moduls.

MagmaCore ist eine Bibliothek, die per Shading in die verwendenden Plugins eingebettet wird. Sie ist kein eigenständiges Server-Plugin und sollte nicht in depend stehen, als könnten Spieler eine MagmaCore-Plugin-JAR installieren.

Abhängigkeit und Verpackung

Die aktuelle Entwicklungskoordinate lautet com.magmaguy:MagmaCore:2.2.0-SNAPSHOT und ist aus MagmaGuys Snapshot-Repository verfügbar. Snapshots können sich ändern, ohne dass sich diese Versionszeichenfolge ändert. Halte das aufgelöste Artefakt fest, wenn du reproduzierbare Builds benötigst.

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>

Diese Deklarationen lösen die Abhängigkeit auf. Konfiguriere die Shading-Aufgabe deines Builds so, dass sie in der endgültigen Plugin-JAR enthalten ist. Folge den Relocation-Regeln eines bestehenden Verbrauchers mit denselben Integrationsanforderungen und prüfe bei Paketumbenennungen reflektive Zugriffe über Zeichenfolgen. Die Distribution verschiebt org.luaj und org.reflections bereits nach com.magmaguy.shaded.

Jedes Plugin kann eine eigene geladene Kopie der Bibliothek haben. Java-Klassen gleichen Namens aus verschiedenen Plugin-Classloadern sind unterschiedliche Typen. Verwende die ausdrücklichen pluginübergreifenden Verträge, etwa den Dienst für Lua-Fähigkeiten von EliteMobs und die Adapter der Standort-Registry. Caste ein privates MagmaCore-Objekt eines anderen Plugins nicht auf den Typ deiner eigenen Kopie.

Module und Zuständigkeiten

Modul	Zuständigkeit
`core`	Plugin-Lebenszyklus, Konfiguration, Befehle, Menüs, Matches, Standortabfragen, Lua-Skripting, Nightbreak-Inhalte und gemeinsame Hilfsfunktionen
`nms:core`	`NMSManager`, `NMSAdapter` und die versionsunabhängigen EasyMinecraftGoals-Schnittstellen
`nms:v*`	Implementierungen des NMS-Vertrags für die jeweilige Serverversion
`dist`	Distribution mit eingebettetem Core und aktiven Adaptern

Gemeinsame Verzauberungen, Item-Aktionen, Kontoverwaltung, Einrichtungsmenüs, Kataloge und Updates gehören zu den Core-Diensten. Verwende die zuständige Komponente wieder, wenn du einem Verbraucher Verhalten hinzufügst.

Plugin-Lebenszyklus

Der minimale Core-Lebenszyklus folgt dem Muster bestehender Verbraucher:

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

Diese Initialisierung bewirkt mehr als das Bereitstellen eines Hilfsobjekts. Sie initialisiert Kontoverwaltung, gemeinsame Befehle, Listener und Unterstützung für temporäre Blöcke. Die Überladung createInstance(plugin, NightbreakPluginSpec) liefert pluginspezifische Texte für die gemeinsamen Befehle.

Bevorzuge Methoden, die das zuständige Plugin ausdrücklich entgegennehmen. getInstance() bezieht sich auf das Singleton der geladenen Bibliothekskopie, dessen anforderndes Plugin beim Erstellen dieser Instanz festgelegt wird. Daraus sollte nicht die Zuständigkeit für jeden Verbraucher abgeleitet werden.

shutdown(plugin) entfernt die Registrierungen dieses Plugins für Downloader, Inhaltsaktualisierung, Initialisierung und Updater und fährt anschließend auch die gemeinsame Laufzeit der geladenen Kopie herunter. Es entfernt also nicht nur einen Registry-Eintrag. Rufe es beim Herunterfahren deines Plugins für deine eigene eingebettete Bibliothek auf. Fahre niemals die Bibliothek eines anderen Plugins herunter, um deine Integration zurückzusetzen.

Rufe createInstance in onLoad auf, damit das Plugin als Eigentümer seines Konfigurationsarchivs registriert ist, bevor ein anderes Plugin Inhalte dafür importieren kann. Die Archivierung verwendet die im Ziel-Plugin eingebettete Implementierung. Wende dessen Regeln für ausgemusterte Konfigurationen nicht mit deiner eigenen MagmaCore-Kopie an.

Für einen Start in mehreren Phasen nimmt startInitialization asynchrone Arbeit, synchrone Arbeit sowie Erfolgs- und Fehler-Callbacks entgegen. Vor der asynchronen Initialisierung archiviert es Konfigurationsdateien, die einem ausgemusterten Format entsprechen. Bukkit-Arbeit an Welten und Entitäten gehört in die synchrone Phase. Lang laufende asynchrone Arbeit sollte zwischen den Phasen isShutdownRequested(plugin) beachten. getInitializationState und isPluginReady stellen den Zustand des Initialisierungsmanagers bereit.

NMS und Paket-Entitäten

Initialisiere NMS nur, wenn dein Plugin es benötigt, und verwende dafür NMSManager.initializeAdapter(plugin) aus com.magmaguy.easyminecraftgoals. Prüfe NMSManager.isEnabled(), bevor du adapterabhängiges Verhalten verwendest. Ein Initialisierungsaufruf kann fehlschlagen oder eine nicht unterstützte Serverversion vorfinden.

Die Distribution enthält folgende Adapterfamilien:

Adapter	Minecraft-Versionen
`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, getrennte Spigot-/Paper-Implementierungen
`v26`	26.1 und die aktuelle 26.x-Adapterfamilie

Die Adapterauswahl ist keine pauschale Kompatibilitätsgarantie für zukünftige Server-Releases. Die Laufzeitauswahl in NMSManager bestimmt, ob der installierte Server einen Adapter laden kann. Versionen vor 1.21.4 liegen außerhalb des aktuellen Adaptersatzes.

EasyMinecraftGoals verwaltet rein paketbasierte Entitäten, ihre Sichtbarkeit und Interaktionsweiterleitung sowie Hilfen für Bewegung und Wegfindung. Sie sind keine gewöhnlichen Welt-Entitäten. Verwalte sie über ihre zuständige API und entferne die von deinem Verbraucher erstellten Objekte, solange der Adapter noch verfügbar ist.

Standort- und Schutzabfragen

com.magmaguy.magmacore.location.LocationQueryRegistry stellt Dungeon- und Regionsschutzabfragen bereit, darunter isInAnyDungeon, isInAnyProtectedRegion und canBuild.

Registriere eigene Provider mit registerDungeonLocator oder registerProtectionProvider und melde denselben Provider ab, wenn sein Besitzer deaktiviert wird. Die Registry enthält Adapter für bestehende Plugins und erkennt pluginübergreifende Dungeon-Provider, ohne dass Verbraucher einen gemeinsamen MagmaCore-Classloader benötigen.

Verwende die zur Aktion passende Abfrage. Außerhalb eines Dungeons zu sein bedeutet nicht, an diesem Ort bauen zu dürfen. Führe Abfragen, die Bukkit oder Schutz-Plugins verwenden, im Serverthread aus.

Verbraucher nach Bibliotheksänderungen bauen

Verwende JDK 21 und veröffentliche MagmaCore mit ./gradlew publishToMavenLocal beziehungsweise unter Windows mit .\gradlew.bat publishToMavenLocal in Maven Local. Stelle sicher, dass der Verbraucher dieses Repository und die beabsichtigte Version auflöst, und baue dann seine JAR mit eingebetteten Abhängigkeiten neu. Das Ersetzen einer Bibliothek in Maven Local aktualisiert kein bereits gebautes Plugin.

APIs installierter Plugins findest du in der Entwicklerübersicht. Solche Integrationen verwenden normalerweise provided oder compileOnly; für die eingebettete MagmaCore-Bibliothek gelten andere Regeln.

Abhängigkeit und Verpackung​

Module und Zuständigkeiten​

Plugin-Lebenszyklus​

NMS und Paket-Entitäten​

Standort- und Schutzabfragen​

Verbraucher nach Bibliotheksänderungen bauen​