# 用生命周期选择位置

你要的时机	常见挂载点	返回值
显示/进入前判断	控件显示需求、场景解锁、事件需求	true / false
页面或组合属性读取时计算	组合属性脚本	数值
动态文本读取时生成	动态字符串脚本	字符串
点击、提交或事件真正发生	js_g、事件脚本、控件动作	通常不依赖返回值
指针进入/离开/按下/释放/移动/长按/拖放	js_enter、js_leave、js_press、js_release、js_move、js_long、js_drop	通常不依赖返回值
地图格子生命周期	js_n、js_c、js_g	按挂载点约定
AI 输入/输出联动	输入前、输出后、后悔、重置脚本	判断或动作结果

编辑器 AI 应先查询目标控件/事件的真实字段，再生成对应脚本；不要把一个动作脚本复制到所有生命周期。

# 完整编辑器脚本字段索引

控件拥有下面的完整字段集合；事件、地图、智能体和其他资源只显示适合自身生命周期的子集。

字段	运行时合同	返回/边界
js_n	使用前的只读需求/显示判断	真/假或所属需求结果；不能写入/异步
js_t	配置触发条件通过后的最终触发校验	true/空值继续；false 或其他结果拒绝/报告
js_c	配置花费提交前的自定义花费阶段脚本	忽略动作返回；必须明确事务所有权
js_g	配置获得提交前的自定义获得/触发后脚本	通常忽略返回；也可作为 Canvas 直接动作 binding
js_sort	只读对象列表排序规则	[{ property, desc }]；desc 为布尔；[] 按对象 ID
js_enter	指针进入/旧移动端按下兼容	动作/Promise，只做轻量反馈
js_leave	指针离开/旧移动端释放兼容	清理动作/Promise
js_press	跨设备指针按下	动作/Promise
js_release	跨设备指针释放/取消	动作/Promise 与清理
js_move	按住指针移动	高频，只提交最新轻量状态
js_long	达到长按阈值	一次延迟交互动作
js_drop	其他控件在当前目标区域释放	校验来源并提交一次投放动作

地图格子复用 js_n 表示显示/可达判断、js_c 表示离开后、js_g 表示进入后。名称相同，但必须按所属生命周期理解；不能把地图离开脚本当成控件花费阶段。

# 读写权限矩阵

脚本类型	可读	可写/异步
组合属性、动态字符串、场景解锁、显示需求	属性、对象、表格、上下文	不可写，不发请求
点击、事件、进入/离开、地图移动	全部运行时代理	可写；异步需处理失败
渲染布局	状态快照、只读代理	同步返回 HTML；不写状态
Canvas	传入快照和 Canvas API	只改画布节点，不改游戏状态

# 判断脚本必须返回布尔值

const level = Number(player.getPro("等级") || 0);
const chapter = Number(player.getPro("章节") || 0);
return level >= 10 && chapter >= 3;

不要在判断脚本里扣费、弹窗或调用 AI。它可能在显示列表时被执行很多次。

# 计算脚本必须返回确定类型

const attack = Number(player.getPro("攻击") || 0);
const defense = Number(player.getPro("防御") || 0);
return Math.max(0, attack * 2 + defense);

组合属性只能返回数值；动态字符串只能返回字符串。缺失值、除数为零和空对象都要有明确回退。

# 触发脚本负责提交动作

if (player.getPro("体力") < 5) {
  tools.showToast(tools.tr("体力不足"), "warning");
  return;
}

player.addPro("体力", -5);
player.addPro("探索经验", 10);
tools.showToast(tools.tr("探索完成"), "success");

需要 Promise 的操作使用 await 或 then/catch。控件快速点击、网络重试和页面销毁都可能让回调晚于原始动作返回，脚本应设置幂等标记。

# 指针挂载点的上下文

交互脚本可以读取：

const trigger = tools.kwargs.triggerType;
const pointer = tools.kwargs.pointer;
const target = tools.kwargs.effectTargetId;

move 触发频率很高，只做轻量视觉反馈；真正写状态放到 press、release 或 drop，并在离开时清理特效。

# 对象排序返回合同

return [
  { property: "品质属性ID", desc: true },
  { property: "等级属性ID", desc: false }
];

每项必须包含存在的属性 ID/名称和布尔值 desc；任一结构无效会拒绝整份排序定义。多条规则按顺序比较，返回 [] 保持稳定对象 ID 顺序。排序脚本只读，比较过程中不能修改实例。

# 常见错误定位

现象	优先检查
页面显示空白	是否 return，返回类型是否正确
点击没有改变数值	是否挂到了判断/只读脚本，而不是动作脚本
每次刷新奖励都增加	是否把写入放进动态字符串或渲染脚本
异步结果偶尔覆盖新状态	是否缺少请求序号或幂等标记
拖放特效残留	leave、release、drop 是否都清理

# 验收清单

• 每个脚本都写明触发时机、上下文和返回类型。
• 只读脚本没有副作用。
• 异步脚本处理取消、失败、重复提交和离线跳过。
• 高频指针/渲染脚本不会全量扫描对象或表格。
• 成功、条件不足、刷新恢复和移动端交互都已验证。

下一步阅读：组合属性脚本、动态字符串脚本 和 tools 对象。