Emaki Series

Appearance

公开 API ​

编译依赖 ​

xml
<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-codex-api</artifactId><version>1.0.5</version><scope>provided</scope></dependency>
kotlin
repositories { maven("https://repo.crypticlib.com/repository/maven-public/") }
dependencies { compileOnly("emaki.jiuwu.craft:emaki-codex-api:1.0.5") }

仅编译依赖

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

门面与分层 ​

检查 EmakiCodexApi.status().usable()。真实非 null 层为 catalog()、operations() 与 extensions()。install、uninstall、Bridge 仅属于 runtime。

当前公开 API 只覆盖原版 Advancement 层：catalog()、operations() 与 extensions() 处理已注册 advancement 与真实 Minecraft progress。分类条目图鉴（codex/*.yml 的解锁、激活、领取）目前没有公开 API 契约，只能通过命令、GUI 与配置管理；不要按 advancement 方法名推断存在对应的条目方法。

catalog() 提供 advancement/page 查询、总数与在线玩家完成状态；实时 progress 读取需要玩家 owner thread。

operations().grant(UUID,id) / revoke(UUID,id) 是同步 owner-thread 写操作。无变化可用 Partial(false, reasonKey) 表示；事件取消为 CANCELLED。

Extensions ​

extensions().registerAdvancement(Plugin,AdvancementSpec) 在 owner namespace 注册外部 advancement，要求 server global thread，返回 AdvancementRegistration，owner disable 时自动移除。

AdvancementSpec 字段为：id、icon、title、description、AdvancementFrameType、可空 parent key、hidden、showToast、announce；空 icon 默认 minecraft:book，空 frame 默认 TASK。

registerTrigger(Plugin,AdvancementTrigger) 注册 owner-scoped trigger provider。provider 以 id() 标识、按较小 priority() 优先，在 AdvancementTriggerContext(player,triggerId,variables) 的玩家 owner thread 同步执行，返回要授予的 advancement id 集合；不得返回 null，重复 id 在变更前折叠。

结果语义 ​

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