MagmaCore 開発者ガイド

生成された Java リファレンスではクラス、メソッド、シグネチャを検索でき、各モジュールのソースバージョンとコミットも確認できます。

MagmaCore は利用側のプラグインに shade して組み込むライブラリです。単独のサーバープラグインではないため、プレイヤーが MagmaCore のプラグイン JAR をインストールできるかのように depend に記述しないでください。

依存関係とパッケージ化

現在の開発用座標は com.magmaguy:MagmaCore:2.2.0-SNAPSHOT で、MagmaGuy のスナップショットリポジトリから取得できます。スナップショットはバージョン文字列が同じでも内容が変わります。再現可能なビルドが必要なら、解決されたアーティファクトを記録してください。

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>

この宣言で依存関係を解決します。最終プラグイン JAR に含めるよう、ビルドの shading タスクも設定してください。同じ連携要件を持つ既存の利用プラグインの relocation 規則に従い、パッケージ名を変える際は文字列によるリフレクション検索を確認します。配布物では org.luaj と org.reflections がすでに com.magmaguy.shaded へ移動されています。

各プラグインはライブラリを個別に読み込めます。異なるプラグインのクラスローダーに属する同名の Java クラスは、別の型です。EliteMobs の Lua パワーサービスや位置レジストリのアダプターなど、明示的なプラグイン間 API を使ってください。他のプラグインが持つ非公開の MagmaCore オブジェクトを、自分の型へキャストしないでください。

モジュールと責任範囲

モジュール	責任範囲
core	プラグインのライフサイクル、設定、コマンド、メニュー、対戦、位置照会、Lua、Nightbreak コンテンツ、共通ユーティリティ
nms:core	NMSManager、NMSAdapter、バージョン非依存の EasyMinecraftGoals インターフェース
nms:v*	NMS インターフェースのサーバーバージョン別実装
dist	core と有効なアダプターを含む shaded 配布物

共通エンチャント、アイテム操作、アカウント処理、セットアップメニュー、カタログ、更新は core サービスの担当です。利用プラグインに動作を追加する際も、既存の担当コンポーネントを再利用してください。

プラグインのライフサイクル

最小構成のライフサイクルは、既存の利用プラグインと同じパターンにします。

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

この初期化はユーティリティオブジェクトの取得だけではありません。アカウント処理、共通コマンド、リスナー、一時ブロック対応も初期化します。createInstance(plugin, NightbreakPluginSpec) のオーバーロードでは、プラグイン固有の共通コマンド文面を指定します。

所有元プラグインを明示的に受け取るメソッドを優先してください。getInstance() は読み込まれたライブラリのシングルトンを指し、その要求元プラグインはインスタンス作成時に決まります。すべての利用プラグインの所有関係をそこから推測しないでください。

shutdown(plugin) は、そのプラグインのダウンローダー、コンテンツ更新、初期化、更新サービスの登録を解除し、さらに読み込まれたライブラリの共通ランタイムを終了します。レジストリの項目を 1 つ消すだけではありません。自分のプラグインの終了時に、自分が組み込んだライブラリへ呼び出します。連携をリセットする目的で他のプラグインのライブラリを終了しないでください。

createInstance は onLoad から呼び、他のプラグインがコンテンツをインポートする前に設定アーカイブの所有元を登録します。アーカイブ処理は対象プラグイン自身の shaded 実装で実行されます。自分の MagmaCore で他のプラグインの廃止規則を解釈しないでください。

段階的な起動には startInitialization を使い、非同期処理、同期処理、成功・失敗コールバックを渡します。非同期初期化を呼ぶ前に、該当する廃止設定をアーカイブします。Bukkit のワールド・エンティティ操作は同期段階に置いてください。長時間の非同期処理では段階の間に isShutdownRequested(plugin) を確認します。getInitializationState と isPluginReady で初期化マネージャーの状態を取得できます。

NMS とパケットエンティティ

NMS が必要な場合だけ、com.magmaguy.easyminecraftgoals の NMSManager.initializeAdapter(plugin) で初期化します。アダプターに依存する処理の前に NMSManager.isEnabled() を確認してください。初期化が失敗したり、サーバーバージョンが未対応だったりする場合があります。

配布物には次のアダプター系統が含まれます。

アダプター	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、Spigot と Paper は別実装
v26	26.1 と現在の 26.x アダプター系統

アダプターの選択は、将来のサーバーリリース全体の互換性を保証しません。NMSManager の実行時選択が、そのサーバーで読み込めるかを決めます。1.21.4 より前は現在のアダプター対象外です。

EasyMinecraftGoals はパケット専用エンティティ、その表示・操作の振り分け、移動・経路探索ヘルパーを管理します。通常のワールドエンティティではありません。担当 API を通じて管理し、アダプターがまだ使える間に自分が作成したオブジェクトを破棄してください。

位置と保護の照会

com.magmaguy.magmacore.location.LocationQueryRegistry は、isInAnyDungeon、isInAnyProtectedRegion、canBuild などのダンジョン・領域保護照会を提供します。

独自プロバイダーは registerDungeonLocator または registerProtectionProvider で登録し、所有元の無効化時に同じプロバイダーを登録解除します。レジストリには既存プラグイン用アダプターがあり、利用側で同じ MagmaCore クラスローダーを共有せずにプラグイン間のダンジョンプロバイダーを検出します。

操作に合った照会を使ってください。ダンジョンの外であることと、その場所で建築できることは同じではありません。Bukkit や保護プラグインに触れる照会はサーバースレッドで実行します。

ライブラリ変更後に利用プラグインをビルドする

JDK 21 を使い、./gradlew publishToMavenLocal、Windows では .\gradlew.bat publishToMavenLocal で MagmaCore を Maven Local に公開します。利用側がそのリポジトリと意図したバージョンを解決することを確認し、shaded JAR を再ビルドします。Maven Local のライブラリを差し替えても、ビルド済みプラグインは更新されません。

インストール済みプラグインの API は開発者向け目次を参照してください。通常は provided または compileOnly を使いますが、MagmaCore は組み込みライブラリとして扱います。