# 一条完整的数据流

属性 / 表格 / 对象保存权威状态
        -> 事件与控件脚本校验并提交变化
        -> 组合属性计算派生数值
        -> 动态字符串整理可读文本
        -> 渲染布局和 Canvas 展示结果
        -> tools 连接存档、AI、地图、弱联网和特效

表现层不应反过来修改状态。玩家看到的按钮、卡片和 Canvas 节点只是状态的投影；真正的扣费、奖励和对象变化必须发生在动作脚本中。

# 先给 AI 一份脚本契约

目标：点击“探索”后消耗 5 点体力并增加 10 点经验。
读取：玩家属性“体力”。写入：体力、探索经验。
失败：体力不足时不写入，显示可翻译提示。
重复：快速点击不能重复扣费；脚本完成后显示成功提示。
位置：控件动作脚本，不要放在动态字符串或渲染脚本。

AI 生成代码后，检查它是否使用真实资源 ID、是否把写入放在动作层、是否处理异步失败和重复提交。

# 四类脚本

层	典型位置	责任	禁止事项
判断	需求、解锁、显示条件	返回 true/false	扣费、奖励、弹窗、请求
规则	控件点击、事件、地图动作	校验并修改状态	把结果只写在界面上
计算	组合属性	返回数值	任何副作用或递归依赖
文本	动态字符串	返回字符串	修改状态、发网络请求

渲染脚本和 Canvas 模块只消费快照并返回 HTML/绘图操作，不是替代规则脚本的另一条状态通道。

# 运行时提供什么

脚本入口函数通常收到三个代理：

function script(player, objects, tools) {
  // player: 当前玩家
  // objects: 当前玩家的对象集合
  // tools: 弹窗、场景、AI、地图、存档、特效和弱联网
}

对象行脚本还会从 tools.kwargs 获得当前 object、objID、控件 ID、屏幕索引和指针快照。不要把这些上下文写死在 HTML 或全局变量里。

# 读写边界

• player.getPro、objects.getObjects、player.getTable 等读取可以出现在判断和渲染相关脚本。
• setPro、addPro、newObject、delObjectByID 只能放在明确的行为脚本。
• tools.queryWeakOnline、AI 请求、弹窗和存档都是异步或有外部副作用的能力，必须处理失败和离线跳过。
• tools.runClientEffect 和 tools.runClientAudio 只改变客户端表现，不保存游戏状态。

# 不要使用浏览器环境逃逸

运行时禁止用 fetch、setTimeout、setInterval、直接 DOM 操作或未公开的 Worker API 绕过脚本代理。需要延迟使用 tools.delay；需要联网使用文档列出的 tools 方法。

# 调试一段脚本的顺序

1. 在调试区确认挂载点和 tools.kwargs。
2. 用最小输入验证返回类型。
3. 先测试条件不足，再测试成功路径。
4. 连续点击、刷新、切换场景，确认不会重复写入。
5. 对 AI、弱联网和存档制造失败，确认玩家能看到可理解的提示。
6. 在窄屏和 PC 三屏布局检查对象/特效目标是否正确。

# 阅读顺序

1. player：玩家状态 API
2. objects：对象集合 API
3. tools：外部能力 API
4. 脚本挂载点与返回值
5. 组合属性脚本

完成主线后，再进入 弱联网脚本、AI 智能体脚本 和 地图格子脚本。