JavaScript 脚本

EmakiForge 通过 CoreLib 的脚本系统注册自己的脚本模块，模块 ID 为 forge。脚本中通过 emaki.module("forge") 获取模块门面，用于注册锻造成功率规则和锻造结果钩子。

本页只介绍 EmakiForge 专属的脚本方法、注册字段、上下文和示例。通用脚本机制（runjs 动作、emaki.player、emaki.logger、安全配置、线程模型等）请阅读 CoreLib JavaScript 脚本系统。

调用任何业务方法前，先用 available() 守卫。EmakiForge 是 CoreLib 的 softdepend，未安装或未就绪时模块不可用。

获取模块

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

基础探针方法

方法	返回	说明
available()	boolean	模块是否可用。
ready()	boolean	模块是否完成初始化。
apiVersion()	string	EmakiForge API 版本。
pluginName()	string	插件名。

锻造成功率规则

锻造规则在锻造结算时执行，可以读取上下文并修改成功率或取消锻造。

方法	返回	说明
registerForgeRule(definition)	boolean	注册一条锻造规则。
registerForgeRule(id, definition)	boolean	重载：把 id 合并进 definition 后注册。
unregisterForgeRule(id)	void	按 id 注销规则。
registeredForgeRules()	list	返回已注册规则 id 列表。

规则 definition 字段

字段	类型	必填	默认	说明
id	string	是	无	规则唯一 id，会被规范化；为空注册失败。
function	string	否	modifyForge	规则回调函数名，也可用 execute 作为等价键。
priority	int	否	0	优先级，数值小者先执行；相同按 id 排序。
recipeIds	string / list	否	空（全部配方）	限定生效的配方 id 集合，也可用 recipes。
timeoutMillis	long	否	引擎默认超时	单次脚本超时，受全局超时上限钳制。

规则回调的 ctx 字段

字段	类型	说明
ruleId	string	当前规则 id。
recipeId	string	配方 id。
recipeName	string	配方显示名。
playerUuid	string	玩家 UUID。
playerName	string	玩家名。
originalSuccessRate	double	原始成功率。
successRate	double	当前累积修改后的成功率。
cancelled	boolean	是否已被取消。
message	string	当前消息。
targetItem	map	主输入物品摘要：type / amount / displayName，可选 lore / customModelData。
requiredMaterials	list	必需材料输入列表，每项为物品摘要并附带 slot。
optionalMaterials	list	可选材料输入列表，字段同上。
traces	list	之前规则的执行轨迹，每项含 id / before / after / message。

规则回调的返回字段

返回字段	类型	说明
successRate 或 chance	number	直接设定成功率（优先生效，覆盖 bonus / multiplier）。
successBonus	number	在当前成功率上加值（无 successRate 时生效）。
successMultiplier	number	在当前成功率上乘系数（在 bonus 之后应用）。
cancel	boolean	是否取消锻造。
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	否	onForgeResult	回调函数名，也可用 execute。
recipeIds	string / list	否	空（全部配方）	限定生效的配方 id，也可用 recipes。
timeoutMillis	long	否	引擎默认超时	单次脚本超时。

钩子回调的 event 字段

字段	类型	说明
hookId	string	钩子 id。
playerUuid	string	玩家 UUID。
playerName	string	玩家名。
recipeId	string	配方 id。
recipeName	string	配方显示名。
success	boolean	锻造是否成功。
errorKey	string	失败错误键。
quality	string	锻造品质。
multiplier	double	倍率。
resultItem	map	产物物品摘要 { type, amount, displayName, lore?, customModelData? }，只读；仅锻造成功时非空，失败时为 {}。
actionFailureReason	string	动作失败原因。
replacements	map	文本替换映射。

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

动作行中可用的占位符：

占位符	说明
%success%	本次是否成功。
%forge_recipe_id%	锻造配方 id。
%forge_quality%	锻造品质。
%forge_multiplier%	倍率。

返回 actions 的示例：

function onForgeResult(event) {
  if (event.success) {
    return {
      actions: [
        "sendmessage text=\"<green>锻造成功，品质 %forge_quality%\"",
        "playsound sound=minecraft:block.anvil.use volume=1 pitch=1"
      ]
    };
  }
  return {};
}

完整示例

注册规则和结果钩子的扩展脚本通过 register() 入口完成。EmakiForge 自带示例脚本 scripts/examples/forge_success.js：

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

  forge.registerForgeRule({
    id: "example_moon_bonus",
    priority: 10,
    function: "modifyForge"
  });

  forge.onResult({
    id: "example_result_notice",
    function: "onForgeResult"
  });
}

function modifyForge(ctx) {
  return {
    successBonus: 3,
    message: "示例：锻造成功率额外增加 3%"
  };
}

function onForgeResult(event) {
  emaki.logger.info("Forge result hook: recipe=" + event.recipeId + ", success=" + event.success + ", quality=" + event.quality);
}

启用扩展脚本

注册类脚本通过 register() 入口加载。把脚本放到 CoreLib 的全局扩展目录后重载即可：

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

/corelib script reload

示例文件默认释放到 plugins/EmakiCoreLib/scripts/examples/，不会自动启用。需要启用时复制到 extensions/global/ 再重载。

脚本调试

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

开启命令：

/ef debug module script

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

注意事项

• 所有注册方法都要求 CoreLib 脚本系统已启用（script.enabled: true），否则注册返回 false 或静默跳过。
• CoreLib 缺失时模块自动降级，规则和钩子不生效但不会报错。
• 规则按优先级升序执行（数值小者先），这与 EmakiAttribute 伤害钩子的降序方向相反，混用时请注意。