API 与集成

EmakiLevel 对外公开的是静态门面 EmakiLevelApi。第三方插件应依赖 emaki-level-api，由服务器上安装的 EmakiLevel 插件在启用时安装 bridge、停用时卸载 bridge。

依赖方式

Maven：

<dependency>
  <groupId>emaki.jiuwu.craft</groupId>
  <artifactId>emaki-level-api</artifactId>
  <version>1.4.0</version>
  <scope>provided</scope>
</dependency>

Gradle：

dependencies {
    compileOnly("emaki.jiuwu.craft:emaki-level-api:1.4.0")
}

服务器端只需要安装：

EmakiCoreLib-*.jar
EmakiLevel-1.4.0.jar

不要把 emaki-level-api-*.jar 放进 plugins/。运行时插件 jar 已经包含自己的 API。

获取 API

直接调用静态门面：

if (EmakiLevelApi.available()) {
    int level = EmakiLevelApi.getLevel(player.getUniqueId(), "main");
    double exp = EmakiLevelApi.getExp(player.getUniqueId(), "main");
}

如果你更喜欢先做可用性检查，可以配合 provider 辅助类：

if (!EmakiLevelApiProvider.available()) {
    return;
}

EmakiLevelApiProvider.requireAvailable();
LevelOperationResult result = EmakiLevelApi.addExp(player.getUniqueId(), "main", 50.0, "quest_reward");

推荐在 paper-plugin.yml 中声明可选依赖：

dependencies:
  server:
    EmakiLevel:
      load: BEFORE
      required: false
      join-classpath: true

如果你的插件没有 EmakiLevel 就无法运行，可以把 required 改为 true。

EmakiLevelApi 方法

方法	说明
available()	判断 API 是否已安装。
type(String typeId)	查询一个等级类型定义。
types()	获取所有已加载等级类型。
getPlayerData(UUID uuid)	获取玩家等级数据视图。
getLevel(UUID uuid, String typeId)	获取玩家指定类型等级。
getExp(UUID uuid, String typeId)	获取当前等级内经验。
getTotalExp(UUID uuid, String typeId)	获取总经验。
getRequiredExp(UUID uuid, String typeId, int targetLevel)	获取升到目标等级所需经验。
addExp(UUID uuid, String typeId, double amount, String reason)	增加经验，按类型配置触发自动升级。
removeExp(UUID uuid, String typeId, double amount, String reason)	扣除当前等级内经验，不降级。
setExp(UUID uuid, String typeId, double amount, String reason)	设置当前等级内经验。
addLevel(UUID uuid, String typeId, int amount, String reason)	直接增加等级，并清空当前等级内经验。
removeLevel(UUID uuid, String typeId, int amount, String reason)	直接扣除等级，并清空当前等级内经验。
setLevel(UUID uuid, String typeId, int level, String reason)	直接设置等级，并清空当前等级内经验。
levelUp(UUID uuid, String typeId, LevelUpCause cause)	按升级需求、消耗和奖励尝试升一级。

reason 建议使用稳定的英文 ID，例如 quest_reward、dungeon_clear、daily_task。它会进入升级动作变量 %reason%。

数据视图

LevelTypeView

LevelTypeView 用来读取等级类型的展示信息、上下限、升级模式和属性配置，是只读视图。

PlayerLevelView

PlayerLevelView 用来查看某个玩家的所有等级类型数据。

PlayerLevelEntryView

PlayerLevelEntryView 表示某个等级类型的单项数据，包括 level、exp、totalExp、requiredExp 和 progress。

LevelOperationResult

操作返回值包含：

• 是否成功。
• 失败原因 ID。
• 操作类型。
• 类型 ID。
• 操作前后等级和经验。
• 额外数据字段。

建议始终检查 success()：

LevelOperationResult result = EmakiLevelApi.addExp(player.getUniqueId(), "combat", 25.0, "arena_win");
if (!result.success()) {
    plugin.getLogger().warning("Failed to add level exp: " + result.reason());
    return;
}

常见失败原因包括：player_not_found、type_not_found、type_disabled、invalid_amount、upgrade_disabled、manual_upgrade_disabled、max_level、not_enough_exp、not_enough_money、not_enough_material、invalid_requirement。

CoreLib Action

EmakiLevel 注册了 CoreLib Action，其他模块、脚本或第三方接入层可以通过动作修改等级数据。当前 Action ID 只使用规范名，不再注册旧别名；完整动作页见 CoreLib 动作。

动作 ID

操作	Action ID
增加经验	emakileveladdexp
设置经验	emakilevelsetexp
扣除经验	emakilevelremoveexp
增加等级	emakileveladdlevel
设置等级	emakilevelsetlevel
扣除等级	emakilevelremovelevel
重置等级类型	emakilevelreset
手动升级	emakilevellevelup

参数

参数	必填	默认	说明
type	是	primary_type	等级类型 ID。
amount	是	0	经验或等级数量。等级操作会四舍五入为整数。
target	否	动作上下文玩家	在线玩家名或 UUID。未填写时使用 ActionContext.player()。
reason	否	action	操作原因。
auto_upgrade	否	true	仅增加经验时有意义；是否允许本次经验触发自动升级。
silent	否	false	静默标记，传入等级服务。

示例

actions:
  - 'emakileveladdexp type="cooking" amount="25" reason="recipe_success"'

actions:
  - 'emakileveladdexp target="Steve" type="main" amount="100" reason="admin_reward"'

actions:
  - 'emakileveladdexp type="mining" amount="500" auto_upgrade="false" reason="event_reward"'

actions:
  - 'emakilevelsetlevel target="Steve" type="combat" amount="30" reason="migration"'

动作执行成功时，ActionResult 数据包含 type、old_level、new_level、old_exp、new_exp 和 amount。失败时会返回 CoreLib Action 失败结果，并带上 EmakiLevel 的失败原因 ID。

MythicMobs Drop 接入

MythicMobs 非实物 Drop 属于运行时集成，不需要开发者 API：

Drops:
  - emakilevel_exp{type=main;amount=120}
  - elv_exp{type=combat;amount=80;reason=mythic_drop}

详细参数见 MythicMobs 集成。

不要依赖实现类

第三方插件不应引用这些实现类或包：DefaultEmakiLevelApi、PlayerLevelService、PlayerLevelDataStore、LevelTypeLoader、RequirementLoader、SourceRuleLoader、LevelOperationAction，以及任何 emaki.jiuwu.craft.level.service / loader / listener / bridge 包下的类。对外稳定入口只保留 emaki.jiuwu.craft.level.api.*。