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 必须与传入的键和修订号一致。程序的 id 不能是它任何一个模块的 id。重复进行完全相同的注册不会产生任何效果。源码有改动时需要更高的修订号。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 程序​

从源码构建​

入口