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

仅编译依赖

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

门面、包与降级 ​

使用 EmakiAttributeApi.status().usable()。非 null 层为 catalog()、operations()、extensions()；install、uninstall、Bridge 只属于 runtime。

当前事件位于 emaki.jiuwu.craft.attribute.api.event，第三方扩展契约位于 emaki.jiuwu.craft.attribute.api.extension。不要继续导入旧根包、旧 gate 包或旧 provider 入口。

不可用时结果型方法返回 unavailable，定义为空，registration handle 不活动，PDC 访问安全降级；isItemContributionActive 特意返回 true，避免可选集成缺失反而禁用物品。

Catalog ​

attributeValue、resourceCurrent、resourceMax 需要玩家 owner thread；itemSnapshot 需要 stack holder owner thread；combatSnapshot 需要 entity owner thread。resources()、attributeIds()、damageTypeIds() 返回不可变定义，可任意线程。

Operations ​

  • consumeResource：玩家 owner thread，先触发 PlayerResourceConsumeEvent。
  • scheduleEquipmentSync：可任意线程提交，runtime 调度到玩家 owner thread。
  • calculateDamage：只计算，不触发应用事件；必须拥有两个实时 combatant。
  • applyDamage：计算、触发 EmakiAttributeDamageEvent 并应用；target owner thread 也必须拥有非 null attacker。
  • resyncPlayer：玩家 owner thread。

Extensions 与 PDC ​

registerContributionProvider(Plugin,AttributeContributionProvider) 与 registerItemContributionGate(Plugin,ItemContributionGate) 可任意线程注册，返回 owner-scoped closeable handle；陈旧 handle 不会删除替代注册。provider/gate 回调在收集线程同步运行，必须快速且遵守上下文中实时 Bukkit 对象的 owner thread。

extensions().pdc() 返回 PdcAttributeAccess，用于 source 注册以及 read、readAll、write、clear、clearAll、copy。复制完整 payload，避免丢失 conditions、schema version 和 metadata。

结果语义 ​

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