JavaScript 脚本

EmakiStrengthen 通过 CoreLib 的脚本系统注册脚本模块，模块 ID 为 strengthen。脚本中通过 emaki.module("strengthen") 获取模块门面，用于读取强化状态、注册强化几率规则和强化结果钩子。

本页只介绍 EmakiStrengthen 专属的脚本方法、注册字段、上下文和示例。通用脚本机制请阅读 CoreLib JavaScript 脚本系统。

调用任何业务方法前，先用 available() 守卫。EmakiStrengthen 是 CoreLib 的 softdepend。

获取模块

function main(ctx) {
  const strengthen = emaki.module("strengthen");
  if (!strengthen.available()) {
    return { skipped: true, message: "EmakiStrengthen 不可用" };
  }
  // ...
  return true;
}

基础探针方法

方法	返回	说明
available()	boolean	模块是否可用。

EmakiStrengthen 模块门面只提供 available() 探针，没有 ready() / apiVersion() / pluginName()。

物品查询与重建

以下方法接收 itemKey，表示从当前动作上下文中按 attribute key 解析出的 ItemStack。具体可用的 key 由触发脚本的模块决定。

方法	返回	说明
canStrengthen(itemKey)	boolean	该物品是否可强化。
readState(itemKey)	map	读取强化状态摘要。
rebuild(itemKey)	map	重建物品并返回物品摘要（type / amount / displayName）。

readState(itemKey) 返回的字段：

字段	类型	说明
eligible	boolean	是否可强化。
eligibleReason	string	不可强化时的原因键。
hasLayer	boolean	是否已有强化层。
baseSource	string	基础物品来源。
baseSourceSignature	string	基础物品来源签名。
recipeId	string	匹配到的强化配方 id。
currentStar	int	当前星级。
crackLevel	int	锻印等级。
milestoneFlags	list	已达到过的里程碑星级。
successCount	int	累计成功次数。
failureCount	int	累计失败次数。
lastAttemptAt	long	最后一次尝试的时间戳。
branchPath	string	分支路径。
fractureLevel	int	断裂等级。

在脚本 worker 边界内调用时返回空 map。

强化几率规则

几率规则在强化结算时执行，可读取上下文并修改成功率、失败后星级、失败后淬炼值、是否应用保护。

方法	返回	说明
registerChanceRule(definition)	boolean	注册一条几率规则。
registerChanceRule(id, definition)	boolean	重载：把 id 合并进 definition 后注册。
unregisterChanceRule(id)	void	按 id 注销规则。
registeredChanceRules()	list	返回已注册几率规则 id 列表。

规则 definition 字段

字段	类型	必填	默认	说明
id	string	是	无	规则唯一 id，会被规范化；为空注册失败。
function	string	否	modifyChance	规则回调函数名，也可用 execute。
priority	int	否	0	优先级，数值小者先执行；相同按 id 排序。
timeoutMillis	long	否	引擎默认超时	单次脚本超时。

规则回调的 ctx 字段

字段	类型	说明
ruleId	string	当前规则 id。
playerUuid	string	玩家 UUID。
playerName	string	玩家名。
recipeId	string	强化配方 id。
currentStar	int	当前星级。
targetStar	int	目标星级。
temperLevel	int	当前淬炼/裂纹值。
originalSuccessRate	double	原始成功率。
successRate	double	当前累积修改后的成功率。
failureStar	int	失败后星级。
failureTemper	int	失败后淬炼值。
protectionApplied	boolean	是否已应用保护。
targetItem	map	被强化物品摘要：type / amount / displayName，可选 lore（纯文本行）/ customModelData。
requiredMaterials	list	必需材料列表，每项含 item / requiredAmount / availableAmount / consumedAmount / optional / protection / temperBoost。
optionalMaterials	list	可选材料列表，字段同 requiredMaterials。
traces	list	之前规则的执行轨迹，每项含 id / before / after / message。

规则仅在本次强化预览满足资格时才执行。

规则回调的返回字段

返回字段	类型	说明
successRate 或 chance	number	直接设定成功率（优先生效）。
successBonus	number	在当前成功率上加值（无 successRate 时生效）。
successMultiplier	number	在当前成功率上乘系数（在 bonus 之后应用）。
failureStar	int	覆盖失败后星级。
failureTemper	int	覆盖失败后淬炼值。
protectionApplied	boolean	覆盖是否应用保护。
failureProtected	boolean	失败保护语义别名：命中即应用保护并把失败后星级钉在当前星级。
downgradeProtected	boolean	降级保护语义别名，效果同 failureProtected。
extraCosts	list	额外消耗清单（只读暴露，供展示/审计；本批不参与实际扣减）。
message	string	写入轨迹的消息。

最终成功率会被钳制到 0~100。多条规则按优先级升序串行叠加。

强化结果钩子

结果钩子在强化结算后触发，用于发奖励、播报等副作用。

方法	返回	说明
onResult(definition)	boolean	注册一个强化结果钩子。
onResult(id, definition)	boolean	重载：把 id 合并进 definition 后注册。
unregisterResultHook(id)	void	按 id 注销结果钩子。
registeredResultHooks()	list	返回已注册结果钩子 id 列表。

钩子 definition 字段

字段	类型	必填	默认	说明
id	string	是	无	钩子唯一 id；为空注册失败。
function	string	否	onStrengthenResult	回调函数名，也可用 execute。
timeoutMillis	long	否	引擎默认超时	单次脚本超时。

结果钩子无 priority 字段，多个钩子按 id 字典序依次触发。

钩子回调的 event 字段

字段	类型	说明
hookId	string	钩子 id。
playerUuid	string	玩家 UUID。
playerName	string	玩家名。
success	boolean	强化是否成功。
errorKey	string	失败错误键。
resultingStar	int	结算后星级。
resultingTemper	int	结算后淬炼值。
newlyReachedStars	list	本次新到达的星级。
replacements	map	文本替换映射。

当本次结算包含预览信息时，还会附加 recipeId、currentStar、targetStar、successRate、failureStar、failureTemper、protectionApplied、maxLevel（boolean，结算后星级是否已达配方最大星级）。

钩子回调可返回 { actions: [...] }，其中 actions 为动作行字符串数组，插件会用 CoreLib 的 ActionExecutor 依次执行。动作行语法与配方里的 actions 一致，例如 "sendmessage text=\"<green>...\""、"playsound sound=minecraft:... volume=1 pitch=1"。执行失败只在控制台记录 warning，不影响已完成的强化结果。

动作行中可用的占位符：

占位符	说明
%success%	本次是否成功。
%strengthen_star%	结算后星级。
%strengthen_temper%	结算后淬炼值。
%strengthen_recipe_id%	强化配方 id。

返回 actions 的示例：

function onStrengthenResult(event) {
  if (event.success) {
    return {
      actions: [
        "sendmessage text=\"<green>强化成功，当前 %strengthen_star% 星\"",
        "playsound sound=minecraft:entity.player.levelup volume=1 pitch=1"
      ]
    };
  }
  return {};
}

完整示例

EmakiStrengthen 自带示例脚本 scripts/examples/strengthen_success.js：

function register() {
  const strengthen = emaki.module("strengthen");

  strengthen.registerChanceRule({
    id: "example_vip_bonus",
    priority: 10,
    function: "modifyChance"
  });

  strengthen.onResult({
    id: "example_result_notice",
    function: "onStrengthenResult"
  });
}

function modifyChance(ctx) {
  if (ctx.playerName && ctx.targetStar >= 5) {
    return {
      successBonus: 2.5,
      message: "示例：5 星以上额外增加 2.5% 成功率"
    };
  }
  return {};
}

function onStrengthenResult(event) {
  emaki.logger.info("Strengthen result hook: recipe=" + event.recipeId + ", success=" + event.success + ", star=" + event.resultingStar);
}

启用扩展脚本

把脚本放到 CoreLib 的全局扩展目录后重载：

plugins/EmakiCoreLib/scripts/extensions/global/strengthen_success.js

/corelib script reload

示例文件默认释放到 plugins/EmakiCoreLib/scripts/examples/，不会自动启用。

脚本调试

开启名为 script 的调试子模块后，EmakiStrengthen 的 JS 规则每次执行都会把逐条规则的执行轨迹（trace）输出到服务端控制台，便于服务器管理员调试脚本规则。

开启命令：

/estrengthen debug module script

可用的调试子模块：attempt、state、gui、script、pdc。

trace 输出字段：规则 id、before（执行前值）、after（执行后值）、message。该输出位于服务端控制台，面向服务器管理员调试，不会发送给玩家。

注意事项

• 所有注册方法都要求 CoreLib 脚本系统已启用，否则注册返回 false 或静默跳过。
• CoreLib 缺失时模块自动降级，规则和钩子不生效但不会报错。
• 几率规则按优先级升序执行（数值小者先）。