EliteMobs Java API

產生的 Java 參考提供可搜尋的類別、方法與簽章，並記錄各模組的原始碼版本與提交。

本指南介紹 EliteMobs 10.9 API。目前的公開 Maven 版本為 com.magmaguy:EliteMobs:10.9.13。使用 provided 或 compileOnly，並宣告 depend: [EliteMobs]。相依版本應符合已安裝插件。開發者索引包含 Maven 與 Gradle 設定。

入口

套件或型別	用途
`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 表示由插件擁有的活動角色。它們公開的實作細節比事件介面更多。只在角色存在期間保留參照，不要直接修改追蹤器集合。

監聽技能 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) 拒絕負值。取消事件或最終值為零時，不發放獎勵，也不顯示獲得回饋。

EliteMobs 負責提交接受的數值、持久化及升級效果。不要在該監聽器中另外寫入玩家 XP。管理員修改 XP 和職業 XP 使用其他路徑，不屬於該事件表示的戰鬥技能獎勵。

其他事件各有自己的約定。特別是，取消 EliteMobSpawnEvent 會阻止建構並移除底層活體實體，而不是留下普通生物。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 的關閉方法。

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) 將角色的整個技能集合替換為按指定順序建立的新執行個體。每個鍵必須屬於該擁有者，重複鍵會遭拒。此操作不是向 Boss 現有技能附加內容。事件分派依 executionPriority() 由小到大執行技能，指定的順序只用於決定同優先度時的先後。

inspectPowers 按附加順序傳回服務管理的程式。inspectPowerActivity 提供執行活動資訊。unregisterOwner(owner) 刪除該擁有者的目錄項目，並從活動角色上移除其執行個體；在服務仍可用時，於整合插件停用時呼叫。

所有修改操作都在伺服器執行緒執行。該服務刻意避免跨插件類別載入器公開 MagmaCore 腳本型別。請傳遞 EliteMobs API 型別，而不是私有 shade 版 MagmaCore 的物件。

Lua 掛鉤與內容編寫見共用腳本參考。Java 服務協調附加與擁有權；技能生命週期仍由 EliteMobs 管理。

Lua Mind 程式

com.magmaguy.elitemobs.api.mind.EliteMindService 在 EliteMobs 角色上執行以 Lua 編寫的 AI。與技能服務相同，請在 EliteMobsInitializedEvent 之後從 Bukkit 的服務管理器載入它。只有當伺服器的 NMS 轉接器能承載原生 Mind 時，EliteMobs 才會註冊此服務；否則查詢會傳回 null。

先以 registerLuaModule(owner, key, revision, source) 註冊模組，再註冊使用這些模組的程式；程式以 registerLuaProgram 註冊。每個鍵的命名空間必須屬於你的插件，Lua 定義中的 id 與 revision 也必須與你傳入的鍵與 revision 相符。程式的 id 不能與它的任何模組的 id 相同。重複相同的註冊不會有任何作用。原始碼有變更時需要更高的 revision。Lua 格式（包括 EliteMobs 不會讀取的模組 settings）請見行為程式。

spawn(EliteMindSpawnRequest) 會以原生 Mind 身體建立執行指定程式的角色，等級為 1 或以上。setProgram 替換已具有 Mind 身體之角色的程式；它不會轉換一般精英。setPaused 會停止與恢復 Mind tick 以及角色的技能回呼，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 wrapper。在儲存庫根目錄執行：

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 環境變數或 mcDistDir Gradle 屬性，建置時也會把 EliteMobs.jar 複製到該資料夾。

此 jar 會 shade MagmaCore、bStats 和 commons-io。MagmaCore、其 Lua 執行階段、其 reflections 函式庫和 easyminecraftgoals 會被重新定位到 com.magmaguy.elitemobs 之下，因此 EliteMobs 帶有自己的副本，與其他 shade MagmaCore 的插件互不影響。bStats 會被重新定位到 com.magmaguy.shaded.bstats。建置時會優先從 Maven Local 解析 com.magmaguy:MagmaCore:2.2.0-SNAPSHOT，再使用 MagmaGuy 的 Maven 儲存庫；-PmagmacoreVersion=<version> 可選擇另一個已發布的 MagmaCore 版本。當原始碼需要比已發布版本更新的 MagmaCore 變更時，請先將 MagmaCore 發布到 Maven Local，做法請見在函式庫變更後建置使用方。在本機修改過的 FreeMinecraftModels 也是如此，建置會以版本 2.12.2 針對它編譯。

test 任務在 JDK 25 工具鏈上編譯並執行測試，因為 Paper 測試 API 需要 Java 25。插件本身以 Java 21 為目標。

入口​

監聽技能 XP 獎勵​

取得受追蹤實體​

初始化與重新載入​

Lua 技能整合​

Lua Mind 程式​

從原始碼建置​

入口