API 接入

EmakiStrengthen 对外公开的是静态门面 EmakiStrengthenApi，用于读取强化状态、预览强化尝试、执行强化和重建强化层展示。普通强化玩法建议优先使用配置和 GUI，只有跨插件联动时才需要 API。

接入前提

yaml

dependencies:
  server:
    EmakiStrengthen:
      load: BEFORE
      required: false
      join-classpath: true

调用方应在插件启用后先用 available() 判断，并在模块缺失时降级处理。不要假设所有服务器都安装 Strengthen。

EmakiStrengthenApi

方法	返回值	说明
`available()`	`boolean`	判断 API 桥接是否已安装。
`canStrengthen(ItemStack)`	`boolean`	判断物品是否可强化。传入 `null` 返回 `false`。
`readState(ItemStack)`	`StrengthenState`	读取物品当前强化状态。永不返回 `null`。
`preview(Player, AttemptContext)`	`AttemptPreview`	计算一次不提交的强化预览。永不返回 `null`。
`attempt(Player, AttemptContext)`	`AttemptResult`	执行一次强化尝试并扣除经济费用。永不返回 `null`。
`rebuild(ItemStack)`	`ItemStack`	按已存状态重建强化层展示。不可用时返回原物品。

模型类位于 emaki.jiuwu.craft.strengthen.model 包。API 不可用时，readState 返回不合格状态，preview / attempt 返回携带 strengthen.error.api_unavailable 的结果。

读取强化状态

java

ItemStack item = player.getInventory().getItemInMainHand();
if (!EmakiStrengthenApi.available() || !EmakiStrengthenApi.canStrengthen(item)) {
    return;
}

StrengthenState state = EmakiStrengthenApi.readState(item);
player.sendMessage("当前强化等级: +" + state.currentStar());

StrengthenState 常用方法：eligible()、eligibleReason()、recipeId()、currentStar()、temperLevel()、crackLevel()、successCount()、failureCount()、branchPath()、hasLayer()、firstReachFlags()。

预览与执行强化

java

AttemptPreview preview = EmakiStrengthenApi.preview(player, context);
if (!preview.eligible()) {
    player.sendMessage("无法强化: " + preview.errorKey());
    return;
}

AttemptResult result = EmakiStrengthenApi.attempt(player, context);
if (result.resultItem() != null) {
    player.getInventory().setItemInMainHand(result.resultItem());
}

attempt 把 AttemptContext 当作只读输入：它不会修改或移除上下文中的目标物品与材料物品堆。调用方必须自行应用返回的 resultItem()，并自行处理外部背包中的材料消耗。内置 GUI 会读取结果预览中的逐槽消耗量后再消耗或返还自己托管的材料堆。

AttemptResult 通过 success() 判定成败，通过 outcome() 区分是否已提交（AttemptOutcome），通过 operationId() 关联同一次操作。

线程安全

强化会修改 ItemStack 和玩家背包，必须在主线程执行。
StrengthenPreAttemptEvent 和 StrengthenTransferEvent 只在玩家 owner 线程被触发；非 owner 线程路径会跳过事件。
经济、数据库记录可以异步准备，但回写装备前要切回主线程。
API 返回的新物品应替换原物品，避免旧引用继续被其他逻辑修改。

使用边界

固定强化概率、材料和保护材料：使用配方配置。
玩家手动强化：使用 GUI。
任务或成就监听：使用事件 API。
修改成功率或追加结果副作用：使用事件或 JavaScript 规则。

JavaScript 调用

CoreLib JavaScript 脚本中可通过 emaki.module("strengthen") 读取强化状态。脚本封装只暴露安全的读取与展示重建能力；真正执行强化涉及材料、经济与 GUI 流程，仍建议走 Strengthen 配置或插件 API。

方法	说明
`available()`	判断 Strengthen API 是否可用。
`canStrengthen(itemKey)`	判断上下文物品是否可强化。
`readState(itemKey)`	返回强化状态摘要。
`rebuild(itemKey)`	返回重建后的物品摘要，不自动写回背包。

注册成功率规则和结果钩子的脚本方法见 JavaScript 脚本。

function main(ctx) {
  if (!emaki.module("strengthen").available()) {
    return { skipped: true, message: "Strengthen not installed" };
  }

  const state = emaki.module("strengthen").readState("target_item");
  if (state.eligible) {
    emaki.player.sendMessage("当前强化等级: +" + state.currentStar);
  }
  return true;
}

API 接入 ​

接入前提 ​

EmakiStrengthenApi ​

读取强化状态 ​

预览与执行强化 ​

线程安全 ​

使用边界 ​

JavaScript 调用 ​