JavaScript 脚本

EmakiCooking 通过 CoreLib 的脚本系统注册脚本模块，模块 ID 为 cooking。脚本中通过 emaki.module("cooking") 获取模块门面，用于注册烹饪产物规则和烹饪完成钩子。

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

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

获取模块

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

基础探针方法

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

烹饪产物规则

产物规则在产物发放前执行，可以替换或追加产出、替换或追加动作、取消发放。

方法	返回	说明
registerResultRule(definition)	boolean	注册一条产物规则。
registerResultRule(id, definition)	boolean	重载：把 id 合并进 definition 后注册。
unregisterResultRule(id)	void	按 id 注销规则。
registeredResultRules()	list	返回已注册产物规则 id 列表。

规则 definition 字段

字段	类型	必填	默认	说明
id	string	是	无	规则唯一 id，会被规范化；为空注册失败。
function	string	否	modifyCookingResult	规则回调函数名，也可用 execute。
priority	int	否	0	优先级，数值小者先执行；相同按 id 排序。
stations	string / list	否	空（全部工位）	限定生效的工位类型，也可用 station；fermenter / fermentation 会归一化为 fermentation_barrel。
recipeIds	string / list	否	空（全部配方）	限定生效的配方 id，也可用 recipes。
timeoutMillis	long	否	引擎默认超时	单次脚本超时。

规则回调的 ctx 字段

字段	类型	说明
ruleId	string	当前规则 id。
recipeId	string	配方 id。
recipeName	string	配方显示名。
stationType	string	工位类型。
playerUuid	string	玩家 UUID。
playerName	string	玩家名。
phase	string	当前阶段。
world	string	世界名。
x / y / z	int	坐标。
inputs	list	本次消耗的输入材料列表，每项含 source（物品来源 shorthand）/ amount（消耗数量）。果汁机供应、炒锅失败兜底等无明确输入的路径为空列表。
outputs	list	当前产出列表，每项为 Map。
actions	list	当前动作列表。
placeholders	map	发放时传入的占位符。
traces	list	之前规则的执行轨迹，每项含 id / message。

规则回调的返回字段

返回值必须是对象，否则只记录轨迹、不改变产物。

返回字段	类型	说明
outputs	list	替换整个产出列表。每项常见键 item_sources、amount。
extraResults	list	在产出列表后追加。
actions	list	替换动作列表。
extraActions	list	追加动作。
cancel	boolean	是否取消发放，取消后停止后续规则。
message	string	写入轨迹的消息。

烹饪完成钩子

完成钩子在产物发放后触发，用于播报、统计等副作用。

方法	返回	说明
onComplete(definition)	boolean	注册一个完成钩子。
onComplete(id, definition)	boolean	重载：把 id 合并进 definition 后注册。
unregisterCompleteHook(id)	void	按 id 注销完成钩子。
registeredCompleteHooks()	list	返回已注册完成钩子 id 列表。

钩子 definition 字段

字段	类型	必填	默认	说明
id	string	是	无	钩子唯一 id；为空注册失败。
function	string	否	onCookingComplete	回调函数名，也可用 execute。
stations	string / list	否	空（全部工位）	限定生效的工位类型，也可用 station；fermenter / fermentation 会归一化为 fermentation_barrel。
recipeIds	string / list	否	空（全部配方）	限定生效的配方 id，也可用 recipes。
timeoutMillis	long	否	引擎默认超时	单次脚本超时。

完成钩子无 priority 字段，多个钩子按 id 字典序依次触发。回调入参 event 字段与产物规则 ctx 相同。

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

动作行中可用的占位符：

占位符	说明
%cooking_recipe_id%	烹饪配方 id。
%cooking_station_type%	工位类型。

返回 actions 的示例：

function onCookingComplete(event) {
  return {
    actions: [
      "sendmessage text=\"<green>烹饪完成：%cooking_recipe_id%\"",
      "playsound sound=minecraft:entity.villager.yes volume=1 pitch=1"
    ]
  };
}

完整示例

EmakiCooking 自带示例脚本 scripts/examples/cooking_reward.js：

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

  cooking.registerResultRule({
    id: "example_oven_bonus",
    station: "oven",
    function: "modifyCookingResult"
  });

  cooking.onComplete({
    id: "example_complete_notice",
    function: "onCookingComplete"
  });
}

function modifyCookingResult(ctx) {
  // ctx.inputs 本次消耗的输入材料，每项 {source, amount}（果汁机供应等无输入路径为空列表）
  const inputCount = (ctx.inputs || []).reduce(function (sum, it) { return sum + it.amount; }, 0);
  emaki.logger.info("Cooking result rule: station=" + ctx.stationType
    + ", inputs=" + (ctx.inputs ? ctx.inputs.length : 0) + " (" + inputCount + " items)");
  return {
    extraResults: [{
      item_sources: "minecraft:cookie",
      amount: 1
    }],
    message: "示例：烤炉产物额外附赠 1 个曲奇"
  };
}

function onCookingComplete(event) {
  emaki.logger.info("Cooking complete hook: recipe=" + event.recipeId + ", station=" + event.stationType + ", outputs=" + event.outputs.length);
}

启用扩展脚本

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

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

/corelib script reload

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

脚本调试

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

开启命令：

/ec debug module script

trace 输出字段：规则 id 和 message。烹饪规则改的是产物/动作/取消，没有数值 before/after，因此 trace 不包含 before / after。该输出位于服务端控制台，面向服务器管理员调试，不会发送给玩家。

注意事项

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