EliteMobs Java API

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

このガイドは EliteMobs 10.9 API を扱います。現在の公開 Maven バージョンは com.magmaguy:EliteMobs:10.9.13 です。provided または compileOnly を使い、depend: [EliteMobs] を宣言してください。依存関係はインストール済みのプラグインに合わせます。Maven と Gradle の設定は開発者向け目次にあります。

入口となる API

パッケージまたは型	用途
com.magmaguy.elitemobs.api	戦闘、クエスト、NPC、テレポート、ダンジョン、初期化の Bukkit イベント
com.magmaguy.elitemobs.api.instanced	インスタンス対戦のライフサイクルイベント
com.magmaguy.elitemobs.api.utils.EliteItemManager	エリートアイテムの識別、レベル、ダメージ、防御のヘルパー
com.magmaguy.elitemobs.entitytracker.EntityTracker	Bukkit エンティティから追跡中の EliteMobs エンティティを取得
com.magmaguy.elitemobs.api.power.EliteLuaPowerService	EliteMobs ランタイムを通じて Lua パワーを登録・付与
com.magmaguy.elitemobs.api.mind.EliteMindService	Lua の Mind プログラムを登録し、それを実行するアクターを生成

EliteEntity、CustomBossEntity、RegionalBossEntity は、プラグインが所有する実行中のアクターを表します。イベント API よりも内部実装を多く公開しています。アクターが存在する間だけ参照を保持し、追跡用コレクションを直接変更しないでください。

スキル XP の付与を監視する

次の完全なプラグインクラスは、連携プラグインの example.blockskillxp 権限を持つプレイヤーへの戦闘スキル XP をキャンセルします。自分の plugin.yml の main に、このクラスの完全修飾名を指定します。

SkillXpIntegration.java

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 は、戦闘の対象条件とネイティブ・権限の倍率を適用した後に同期実行されます。getOriginalXp() はイベント作成時の量で、getXp() には先行リスナーの変更が含まれます。setXp(long) は負数を拒否します。キャンセルまたは最終値が 0 の場合、付与と獲得表示を行いません。

EliteMobs が確定した量を反映し、永続化とレベルアップ効果を処理します。このリスナーから別途 XP を書き込まないでください。管理者による XP の変更とクラス XP は別の経路を通り、このイベントが表す戦闘スキル XP には含まれません。

他のイベントにはそれぞれの仕様があります。特に EliteMobSpawnEvent をキャンセルすると生成を止め、元の生体エンティティも削除します。通常の Mob を残す動作ではありません。EliteMobDeathEvent と EliteMobRemoveEvent は異なるライフサイクル遷移です。すべての削除を死亡や報酬と扱う前に、イベントと発火元のコードを確認してください。

追跡中のエンティティを取得する

Lookup inside your integration

EliteEntity elite = EntityTracker.getEliteMobEntity(bukkitEntity);
if (elite == null) {
    return;
}

com.magmaguy.elitemobs.entitytracker.EntityTracker と com.magmaguy.elitemobs.mobconstructor.EliteEntity をインポートします。戻り値は null の場合があります。Bukkit エンティティが必ず現在追跡中の EliteMob とは限りません。存在する非 null の Bukkit エンティティを渡し、サーバースレッドで検索してください。

装備は EliteItemManager.isEliteMobsItem(itemStack) で確認し、必要な値に応じて getItemLevel、getEliteDefense、getTotalDPS などを使います。これらは異なる量であり、アイテムレベルは最終ダメージではありません。空のアイテムをすべてのヘルパーが受け付けると仮定せず、各メソッドの null 処理を確認してください。

初期化と再読み込み

EliteMobs は非同期初期化の後にサーバースレッドで初期化します。対応する再読み込みを含め、一連の処理が成功すると EliteMobsInitializedEvent を発火します。イベントを受け取れるようリスナーを早めに登録してください。イベント後に有効化される連携では、すでに初期化済みの場合も処理する必要があります。

再読み込みによって、エンティティ参照、付与状態、キャッシュしたサービスが無効になる場合があります。初期化完了後に必要なものを取得し直してください。EliteMobs の代わりに onEnable、onDisable、MagmaCore の shutdown を呼ばないでください。

Lua パワーとの連携

EliteMobs の初期化後、Bukkit からサービスを取得します。

Service lookup

EliteLuaPowerService powers = Bukkit.getServicesManager()
        .load(EliteLuaPowerService.class);
if (powers == null) {
    return;
}

org.bukkit.Bukkit と com.magmaguy.elitemobs.api.power.EliteLuaPowerService をインポートします。サービスがなければ利用不可として扱い、実装を自分で生成しないでください。

registerLuaPower(owner, key, revision, source) は、自分のプラグインが所有するプログラムを登録します。setPowers(owner, eliteEntity, orderedPowerKeys) は、アクターのパワー全体を指定順の新しいランタイムに置き換えます。すべてのキーはその所有者に属している必要があり、重複したキーは拒否されます。既存のボスパワーへの追記ではありません。イベントの配信では executionPriority() の昇順にパワーを実行し、指定した順序は同順位の決定にのみ使います。

inspectPowers は、サービスが管理するプログラムを付与順に返します。inspectPowerActivity はその実行状況を返します。unregisterOwner(owner) は所有者のカタログ項目を削除し、稼働中のアクターからそのランタイムを取り外します。サービスが利用可能なうちに、連携プラグインの無効化時に呼び出してください。

すべての変更操作はサーバースレッドで実行します。このサービスは、プラグインのクラスローダーをまたいで MagmaCore のスクリプト型を公開しません。個別に shade した MagmaCore のオブジェクトではなく、EliteMobs API の型を渡してください。

Lua フックとコンテンツの記述は共通スクリプトリファレンスを参照してください。Java サービスは付与と所有関係を調整し、パワーのライフサイクルは引き続き EliteMobs が管理します。

Lua の Mind プログラム

com.magmaguy.elitemobs.api.mind.EliteMindService は、Lua で記述した AI を EliteMobs のアクター上で実行します。パワーサービスと同様に、EliteMobsInitializedEvent の後に Bukkit のサービスマネージャーから取得します。EliteMobs は、サーバーの NMS アダプターがネイティブの Mind をホストできる場合にのみこのサービスを登録します。それ以外の場合、取得結果は null になります。

registerLuaModule(owner, key, revision, source) でモジュールを、それを使うプログラムより先に登録し、その後 registerLuaProgram でプログラムを登録します。各キーの名前空間は自分のプラグインに属している必要があり、Lua 定義の id と revision は渡したキーと revision に一致しなければなりません。プログラムの id を、そのモジュールのいずれかの id と同じにすることはできません。同一の登録を繰り返しても何も起きません。ソースを変更した場合は、より大きな revision が必要です。EliteMobs が読み取らないモジュールの settings を含む Lua の形式は、行動プログラムで説明しています。

spawn(EliteMindSpawnRequest) は、要求したプログラムを実行するアクターを、ネイティブの Mind ボディ上に 1 以上のレベルで生成します。setProgram は、すでに Mind ボディを持つアクターのプログラムを入れ替えます。通常のエリートを変換するものではありません。setPaused は Mind のティックとアクターのパワーコールバックを停止・再開し、inspect は現在の状態を返し、clearProgram はアクターを削除します。registerNaturalSpawnProvider を使うと、EliteMobs 自身のランダム変換より前に、自然発生するエリートのスポーンをそのままにする、抑制する、または置き換えることができます。unregisterOwner(owner) は、自分のモジュール、プログラム、プロバイダーと、自分のプログラムを実行中のアクターを削除します。

Mind のアクションは、on_mind_action を通じてアクターに付与されたパワーに届きます。Java の連携では、EliteLuaPowerService.registerActionHandler を使って自分のパワーに対するアクションを処理することもできます。アクションを受け入れる機会は、Lua フックが先に得ます。Lua 側については Mind プログラムのコンテキストを参照してください。

ソースからのビルド

EliteMobs リポジトリは、Gradle 9.1.0 と JDK 21 ツールチェーンでビルドします。Windows 用の Gradle ラッパーが含まれています。リポジトリのルートで次を実行してください:

Windows

.\gradlew.bat shadowJar

リポジトリに Unix 用の gradlew スクリプトはありません。他のシステムでは、gradle/wrapper/gradle-wrapper.properties に記載された Gradle のバージョンをインストールし、gradle shadowJar を実行してください。

デプロイ可能なプラグインは build/libs/EliteMobs.jar です。build/libs/EliteMobs-min.jar には EliteMobs のクラスだけが入っており、動作するプラグインではありません。環境変数 MC_DIST_DIR または Gradle プロパティ mcDistDir が設定されている場合、ビルドはそのフォルダにも EliteMobs.jar をコピーします。

この jar は MagmaCore、bStats、commons-io を shade します。MagmaCore、その Lua ランタイム、リフレクションライブラリ、easyminecraftgoals は com.magmaguy.elitemobs 配下に relocate されるため、MagmaCore を shade する他のプラグインとは別に、EliteMobs は独自のコピーを持ちます。bStats は com.magmaguy.shaded.bstats に relocate されます。ビルドは com.magmaguy:MagmaCore:2.2.0-SNAPSHOT を、MagmaGuy の Maven リポジトリより先に Maven Local から解決します。-PmagmacoreVersion=<version> で、公開済みの別の MagmaCore バージョンを選べます。ソースが公開済みのビルドより新しい MagmaCore の変更を必要とする場合は、ライブラリ変更後の利用プラグインのビルドの説明に従い、先に MagmaCore を Maven Local に公開してください。ローカルで変更した FreeMinecraftModels も同様で、ビルドはこれをバージョン 2.12.2 としてコンパイルします。

test タスクは、JDK 25 ツールチェーンでテストをコンパイルして実行します。Paper のテスト API に Java 25 が必要なためです。プラグイン本体は Java 21 を対象としています。