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

仅编译依赖

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

门面与分层 ​

检查 EmakiGemApi.status().usable()。公开非 null 层只有 catalog() 与 operations()；没有 extensions()。install、uninstall、Bridge 是 runtime 内部契约。

catalog() 提供宝石定义、物品识别、开孔器判断、装备宝石状态、聚合属性/技能、共鸣以及镶嵌/拆卸关系校验。定义表可任意线程读取；实时 ItemStack 必须在 holder owner thread 读取。业务不允许由成功的 GemRelationshipCheck.allowed()==false 表示。

洗炼只有一个只读入口：catalog().rerollSession(operatorId) 返回 Optional<GemRerollSessionView>，无会话、运行时不可用或 operatorId 为 null 时返回空。该视图带 operationType、originalAffixes、candidateAffixes、stage、version、createdAt、expiryAt、terminalState，并有 open() 判定是否仍处于 open 终态。operations() 没有洗炼方法，生成与确认候选只能通过命令或 GUI；也没有洗炼相关事件。

Operations 与事务 ​

所有玩家操作必须在 actor owner thread；错误线程返回 WRONG_THREAD 且不修改状态。

  • inlay(Player, equipment, gemItem, slotIndex)：不原地修改 equipment，也不替调用方减少 gem stack。检查 GemInlayOutcome.updatedEquipment() 与 inputConsumed() 后自行写回/扣除。
  • extract(Player, equipment, slotIndex, bypassCost)：返回 GemExtractOutcome，调用方写回装备并处理可选 returned gem。
  • openSocket(Player, equipment, openerItem)：返回更新后的装备；成功时 opener stack 会按当前契约原地反映消耗。
  • createGemItem(id, level, amount)：构建分离物品，可任意线程。
  • clearGems(equipment)：移除整层宝石，须在物品 owner thread。
  • openGui / openSocketGui：玩家 owner thread。

镶嵌与拆卸结果内部先 commit 再返回，但匹配的 completed event 不是简单的“方法返回后立即触发”：它等待 success actions 完成且持久 operation journal 到达终态 COMPLETED。每次 pre/post 事件共享稳定的 operationId，用于关联同一事务。

GemInlayCompletedEvent 还可能在已完成补偿的失败终态触发，此时 successful=false 并携带 reasonKey；GemExtractCompletedEvent 仅携带终态装备、returned gem 与 return mode。

结果语义 ​

无负载成功使用 EmakiResult<Unit>。通用可选访问器是 optionalValue()。FailureKind 只有 UNAVAILABLE、NOT_FOUND、INVALID_INPUT、REJECTED、CANCELLED、TARGET_OFFLINE、WRONG_THREAD、INTERNAL_ERROR。业务摇点失败可由成功 outcome 表达，不等同基础设施失败。