跳至主要內容

EliteMobs Java API

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

本指南介紹 EliteMobs 10.9 API。本次更新確認的公開 Maven 版本為 com.magmaguy:EliteMobs:10.9.1。使用 provided 或 compileOnly，並宣告 depend: [EliteMobs]。相依版本應符合已安裝插件；目前原始碼為 10.9.5。開發者索引包含 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 技能

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 現有技能附加內容。

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

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

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