Emaki Series

API 接入 ​

**坐标: ** emaki.jiuwu.craft:emaki-strengthen-api:4.8.7
**Maven 仓库: ** https://repo.crypticlib.com/repository/maven-public/

xml
<repositories><repository><id>jiuwu-releases</id><url>https://repo.crypticlib.com/repository/maven-public/</url></repository></repositories>
<dependencies><dependency><groupId>emaki.jiuwu.craft</groupId><artifactId>emaki-strengthen-api</artifactId><version>4.8.7</version><scope>provided</scope></dependency></dependencies>
kotlin
repositories { maven("https://repo.crypticlib.com/repository/maven-public/") }
dependencies { compileOnly("emaki.jiuwu.craft:emaki-strengthen-api:4.8.7") }

API Jar 只用于编译

API Jar 只能作为 Maven provided / Gradle compileOnly 依赖; 不得放入 plugins/, 也不得 shade 或 relocate. EmakiStrengthen-4.8.9.jar 已内嵌未 relocate 的 API 类; 另一份副本会由不同 ClassLoader 定义为不同类型, 破坏事件与 bridge

探测与降级 ​

java
if (!EmakiStrengthenApi.status().usable()) {
    // 禁用强化联动, 不影响插件其余功能
    return;
}

catalog(), operations(), mastery() 的返回值永不为 null; 模块不可用时目录为空, 结果型调用返回 EmakiResult.unavailable()

catalog() ​

  • readState(ItemStack): StrengthenState; 不合格物品仍可成功读取, 检查 eligible()
  • recipes(), recipe(id): StrengthenRecipe 目录
  • preview(player, AttemptContext): 不提交的 AttemptPreview; 业务拒绝用 eligible=false 表达
  • successRate(player, context): 可执行预览的最终成功率

operations() ​

  • attempt(player, context): 返回 AttemptResult. 一次已提交但摇点失败是 Success<AttemptResult> 且 result.success()==false; 取消, 校验, 扣费或重建失败才是外层 Failure; 已扣费但补偿未结清时返回 Partial
  • attemptEnhancement(player, context): 通用强化框架的尝试, 返回 EnhancementAttemptOutcome; 材料/费用/成功率/保底由 Strengthen 处理, 目标等级写回由 Target Provider 负责
  • transfer(player, source, target, decayRate): StrengthenTransferOutcome
  • rebuild(item), refreshItem(item): 返回新 stack; 无强化层可为 Partial. rebuild 对"配方已不存在"更严格, 返回 NOT_FOUND, 而 refreshItem 返回 Partial
  • openGui(player), refreshPlayer(player)
  • registerEnhancementTarget(provider) / unregisterEnhancementTarget(providerId): 注册或移除 Target Provider; 重复注册同 ID 会替换, 移除未注册 ID 返回 NOT_FOUND
  • enhancementOperation(operationId) / enhancementOperations(): 查询事务记录中的通用强化操作
  • pityStates(group) / setPityCounter(scope, group, ownerKey, counter) / clearPityGroup(group): 读取, 覆盖或清空保底计数器; scope 为 player 或 item
  • setMastery(item, totalExp) / clearMastery(item): 写入或清除物品熟练度层 (详见下方 mastery())

主要模型还包括 AttemptCost, AttemptMaterial, AttemptOutcome, StrengthenState, StrengthenRecipe, EnhancementAttemptContext, EnhancementAttemptOutcome, EnhancementOperationView, EnhancementPityStateView. 调用方必须把返回的新物品写回原槽位; 输入引用不会被原地替换

mastery() ​

只读的物品熟练度层, 返回 ItemMastery

  • snapshot(ItemStack): EmakiResult<ItemMasteryView>, 等价于 snapshot(null, itemStack)
  • snapshot(Player, ItemStack): EmakiResult<ItemMasteryView>, 两个参数均可为 null

bridge 或其熟练度提供方缺失时返回不可用实现, 此时调用仍安全. 写入侧不在这一层: operations() 提供 setMastery(ItemStack, double) 与 clearMastery(ItemStack)

当前未公开 extensions()

结果约定 ​

穷尽处理 EmakiResult.Success, Partial, Failure. 无负载成功使用 EmakiResult<Unit>, 通用可选负载访问器是 optionalValue(). FailureKind 精确包括 UNAVAILABLE, NOT_FOUND, INVALID_INPUT, REJECTED, CANCELLED, TARGET_OFFLINE, WRONG_THREAD, INTERNAL_ERROR. 外层成功只表示流程正确完成, 不保证强化摇点成功

线程与 Folia ​

玩家方法必须在玩家 entity-owner thread; 持有物品的方法必须在其库存/实体/区域 owner thread, 分离的克隆可在当前线程处理. 错线程返回 WRONG_THREAD, 不要依赖"异步路径跳过事件"的旧行为

稳定性限制 ​

install/uninstall 为 @ApiStatus.Internal; Bridge, catalog, operations 为 @ApiStatus.NonExtendable. 第三方不得调用, 实现或缓存内部 bridge