公开 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.6.6</version><scope>provided</scope></dependency>

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

仅编译依赖

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