Emaki Series

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

仅编译依赖

EmakiAttribute-4.8.7.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 入口

runtime 不可用时的降级契约: 结果型方法返回 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. 跨来源迁移时调用 copy 复制完整 payload, 避免丢失 conditions, schema version 和 metadata

结果说明 ​

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