JavaScript 脚本

EmakiGem 通过 CoreLib 的脚本系统注册脚本模块，模块 ID 为 gem。脚本中通过 emaki.module("gem") 获取模块门面，用于注册镶嵌规则和套装加成。

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

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

获取模块

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

基础探针方法

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

镶嵌规则

镶嵌规则在镶嵌结算时执行，可以读取上下文并修改成功率、允许/拒绝镶嵌、设置提示消息。

方法	返回	说明
registerSocketRule(definition)	boolean	注册一条镶嵌规则。
registerSocketRule(id, definition)	boolean	重载：把 id 合并进 definition 后注册。
unregisterSocketRule(id)	void	按 id 注销规则。
registeredSocketRules()	list	返回已注册镶嵌规则 id 列表。

规则 definition 字段

字段	类型	必填	默认	说明
id	string	是	无	规则唯一 id，会被规范化；为空注册失败。
function	string	否	checkSocket	规则回调函数名，也可用 execute。
priority	int	否	0	优先级，数值小者先执行；相同按 id 排序。
gemIds	string / list	否	空（全部宝石）	限定生效的宝石 id 集合，也可用 gems。
socketTypes	string / list	否	空（全部插槽）	限定生效的插槽类型集合，也可用 sockets。
timeoutMillis	long	否	引擎默认超时	单次脚本超时。

规则回调的 ctx 字段

字段	类型	说明
ruleId	string	当前规则 id。
playerUuid	string	玩家 UUID。
playerName	string	玩家名。
itemId	string	目标物品 id。
slotIndex	int	插槽索引。
socketType	string	插槽类型。
gemId	string	宝石 id。
gemType	string	宝石类型。
gemLevel	int	宝石等级。
inlaidGems	list	目标物品当前已镶嵌宝石列表（本次镶嵌前），每项含 slot / gemId / gemType / gemLevel。
inlaidGemCount	int	当前已镶嵌宝石数量。
allowed	boolean	当前是否允许镶嵌。
originalSuccessRate	double	原始成功率。
successRate	double	当前累积修改后的成功率。
messageKey	string	当前消息键，默认 gem.error.condition_not_met。
message	string	当前消息。
traces	list	之前规则的执行轨迹，每项含 id / before / after / message。

规则回调的返回字段

返回字段	类型	说明
cancel	boolean	true 则强制不允许镶嵌。
allowed	boolean	是否允许，与 !cancel 取与。
successRate	number	直接设定成功率（优先生效）。
successBonus	number	在当前成功率上加值（无 successRate 时生效）。
successMultiplier	number	在当前成功率上乘系数（在 bonus 之后应用）。
messageKey	string	覆盖消息键。
message	string	覆盖消息文本。

最终成功率会被钳制到 0~100。多条规则按优先级升序串行执行，一旦某规则结果不允许立即中断。

套装加成

套装加成对每件物品求值，可以追加名称动作和 Lore 动作。

方法	返回	说明
registerSetBonus(definition)	boolean	注册一个套装加成。
registerSetBonus(id, definition)	boolean	重载：把 id 合并进 definition 后注册。
unregisterSetBonus(id)	void	按 id 注销加成。
registeredSetBonuses()	list	返回已注册套装加成 id 列表。

加成 definition 字段

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

套装加成无 priority、无宝石/插槽过滤；所有加成按 id 字典序逐一对每件物品求值。

加成回调的 ctx 字段

字段	类型	说明
bonusId	string	当前加成 id。
itemId	string	物品 id。
gems	list	已镶嵌宝石列表，每项含 id / type / level。
gemIds	list	宝石 id 列表。
gemTypes	list	宝石类型列表。
socketCount	int	插槽分配数量。

加成回调的返回字段

返回字段	类型	说明
nameActions	list	物品名修改动作集，传给动作系统。
loreActions	list	物品 Lore 修改动作集，例如 {op:"append", value:"..."}。

仅当 nameActions 或 loreActions 至少一个非空时，结果才被收集应用。

完整示例

EmakiGem 自带示例脚本 scripts/examples/gem_status.js：

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

  gem.registerSocketRule({
    id: "example_socket_bonus",
    priority: 10,
    function: "checkSocket"
  });

  gem.registerSetBonus({
    id: "example_lore_bonus",
    function: "applySetBonus"
  });
}

function checkSocket(ctx) {
  if (ctx.gemLevel >= 3) {
    return {
      successBonus: 5,
      message: "示例：3 级以上宝石镶嵌成功率额外增加 5%"
    };
  }
  return {};
}

function applySetBonus(ctx) {
  if (ctx.gemIds.length >= 3) {
    return {
      loreActions: [{
        op: "append",
        value: "<gold>JavaScript 套装示例：已镶嵌 3 颗以上宝石"
      }]
    };
  }
  return {};
}

启用扩展脚本

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

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

/corelib script reload

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

脚本调试

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

开启命令：

/gem debug module script

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

注意事项

• 所有注册方法都要求 CoreLib 脚本系统已启用，否则注册返回 false 或静默跳过。
• CoreLib 缺失时模块自动降级，规则和加成不生效但不会报错。
• 镶嵌规则按优先级升序执行（数值小者先），某规则不允许镶嵌后立即中断后续规则。