公开 API

编译依赖

<repositories><repository><id>jiuwu-releases</id><url>https://repo.crypticlib.com/repository/maven-public/</url></repository></repositories>
<dependency><groupId>emaki.jiuwu.craft</groupId><artifactId>emaki-level-api</artifactId><version>1.5.8</version><scope>provided</scope></dependency>

repositories { maven("https://repo.crypticlib.com/repository/maven-public/") }
dependencies { compileOnly("emaki.jiuwu.craft:emaki-level-api:1.5.8") }

仅编译依赖

runtime 已内嵌未 relocate 的 API 类。不要安装、bundle、shade 或 relocate API Jar；重复 ClassLoader 类型会破坏事件和 bridge。

门面与分层

检查 EmakiLevelApi.status().usable()。catalog()、operations()、extensions() 永不为 null；install、uninstall、Bridge 仅供 runtime 生命周期。

Catalog 与异步载入

types()、type(id)、内存快照 level/exp/totalExp/requiredExp、排行榜 top/topCount 和 previewAdjustment 均可任意线程读取。

loadPlayerDataAsync(UUID) 通过 EmakiLevel 异步数据存储加载完整 PlayerLevelView，可从任意线程调用，返回 CompletableFuture<EmakiResult<PlayerLevelView>>；完成线程未定义，callback 触碰 Bukkit 状态前必须重新调度到 owner thread。模块不可用时返回已完成的 unavailable future。

Operations

addExp（含 silent 重载）、removeExp、setExp、addLevel、removeLevel、setLevel、levelUp、reset、syncPlayer、openGui、openTopGui 都是同步 owner-thread 操作。

返回的 LevelOperationResult 记录 operation type、success、reason、变更前后值和附加数据；即使外层为 Success 也必须检查业务结果。玩家离线、未拥有线程或规则拒绝不会伪装成 0/false。

Extensions

registerExpSource(Plugin,ExpSourceProvider) 返回 owner-scoped ExpSourceRegistration。provider 接收 ExpSourceContext 并返回 ExpSourceGrant；注册和关闭 handle 可任意线程，回调遵守 runtime source 流的玩家 owner-thread 约束。

结果语义

无负载成功使用 EmakiResult<Unit>；通用可选访问器是 optionalValue()。FailureKind 精确为 UNAVAILABLE、NOT_FOUND、INVALID_INPUT、REJECTED、CANCELLED、TARGET_OFFLINE、WRONG_THREAD、INTERNAL_ERROR。