脚本开发教程

本教程面向 要在 BetterNTE 里编写 JavaScript 脚本 的开发者：说明目录约定、manifest.json、任务与触发器差异、以及如何查阅完整 API。示例以常见本地路径为准，实际以你配置的 数据根目录 为准。

0. 终端用户环境（必须交代）

脚本与模板默认按 1920×1080 游戏分辨率标定。请在 manifest.description 或单独用户文档中明确要求该设置，并引导阅读：游戏画面设置（必须）。

1. 脚本放哪里

两类最常见路径（本地订阅）：

类型	目录	用途
独立任务 / 公共库	data/local/scripts/<脚本名>/	用户手动运行的任务、或被依赖的库
触发器	data/local/triggers/<触发器名>/	由引擎按帧/策略调度的自动逻辑

每个脚本一个文件夹，至少包含：

• manifest.json — 元数据与入口声明（必需）
• main.js（或 manifest 里 entry 指定的文件）

data/local/scripts/my_task/
├── manifest.json
├── main.js
└── templates/          # findTemplate 使用的 PNG 放在此目录
    └── example.png

ctx.findTemplate("example") / findTemplate("example.png") 均读取 templates/example.png。刷新或重启客户端后，引擎会重新扫描并加载脚本（具体热重载行为以版本为准）。

2. 最小 manifest.json（独立任务）

{
  "schema_version": 1,
  "name": "my_task",
  "display_name": "我的任务",
  "version": "1.0.0",
  "type": "solo_task",
  "entry": "main.js"
}

• type：solo_task（手动运行）、trigger（自动触发）、library（仅被依赖，不可直接运行）。
• entry：相对当前脚本目录的入口文件路径。

3. 最小 main.js（独立任务）

独立任务由用户在界面点击「运行」触发，引擎会调用你的异步入口（常见约定为 start；以当前引擎与模板为准，完整说明见下方 API 文档）。

function init() {
  ctx.logInfo("脚本已加载");
}

async function start() {
  ctx.logInfo("任务开始");
  // 在此编写：截图、找图、点击等逻辑
  ctx.logInfo("任务结束");
}

界面里配置的 运行参数 会注入到全局 config（对象形态），可直接读取：

async function start() {
  ctx.logInfo(JSON.stringify(config));
}

4. 触发器脚本（概念）

触发器用于 持续检测 某类条件（如某按钮出现）并自动响应。入口形态与任务脚本不同，通常实现 onTrigger 等钩子；具体签名与节流策略以引擎版本为准。

请先阅读：脚本开发指南 中的 「5. 触发器脚本」 一节。

5. 公共库与依赖

type: "library" 的脚本不单独运行，供其它脚本引用：

• 推荐在消费方的 manifest.json 中声明 dependencies，运行时将导出挂载到 ctx.<库name>。
• 未声明时仍可能通过 ctx.call("库名", "函数", args) 调用（兼容旧写法）。

详见：脚本开发指南 「2. 脚本类型」。

6. 参数表单：params_schema

若希望用户在运行前通过表单配置参数，在 manifest.json 中增加 params_schema（JSON Schema 风格）。客户端会根据 schema 渲染控件，并把结果作为 config 传入。

完整字段与示例见：脚本开发指南 「3. 脚本清单」。

7. 常用能力速查（实现均在 Rust 侧）

以下方法名以 当前仓库实现的 ScriptContext 为准，完整列表、参数与返回值见 脚本开发指南 「6. ctx API 完整参考」。

• 日志：ctx.logInfo / ctx.logWarn / ctx.logError
• 等待：ctx.sleep(ms) 等
• 截图 / 找图 / 颜色 / OCR：如 findTemplate、ocr 等（名称与选项以 API 文档为准）
• 输入：键盘、鼠标点击、移动等
• 运行其它脚本：ctx.runScript（若权限与引擎策略允许）

8. 调试建议

1. 先写日志：在 init、start、关键分支打 logInfo，确认生命周期是否按预期执行。
2. 缩小范围：用固定 ROI、单张模板验证找图阈值，再拼回完整流程。
3. 参数单一来源：运行路径应始终带上用户在界面保存的 config；多入口（任务组、调试运行）时避免手写空对象覆盖配置。
4. 版本与权限：manifest 中的 permissions、min_engine_version 与客户端能力对齐，避免线上无法运行。

9. 下一步：完整 API

• 必读：脚本开发指南（完整 ctx 与 manifest）

若你维护的是 官方脚本包，建议同时为用户撰写简短说明（见 使用教程）。