NOVA 模块开发与 JSON 规范文档

NOVA Client 采用解耦式插件架构。所有功能模块均独立存储于客户端工作区目录下的 models/*.json 中。客户端内置热重载引擎，无需重新编译 Rust 二进制文件即可实时动态加载、解析并渲染自定义模组界面。

1. 架构总览

模块系统具备完整的双向生命周期：

启动初始化：客户端启动时自动扫描 models/ 文件夹，将所有有效的 .json 解析为面板组件。
后台监听：绑定 keybind 的模块由 Win32 GetAsyncKeyState 后台全局侦听，无论游戏窗口是否置顶均可灵敏开关。
云端广场下发：通过 https://nova.bilibili.forum 边缘网络，随时随地一键拉取社区模块并持久化存储。

2. 模组 JSON 规范结构

每个模块均为一个顶层 JSON 对象，必须包含以下核心字段：

字段 (Field)	类型 (Type)	必填	说明
`id`	String	是	唯一标识符，对应保存的文件名 `models/{id}.json`。只允许小写英文字母、数字和下划线。
`name`	String	是	在 ClickGUI 界面与 HUD 模块列表中展示的主标题名称。
`category`	String	是	所属分类。可选值：`Combat`、`Movement`、`Render`、`Player`、`Custom`、`Misc`。
`suffix`	String	否	副标题徽标（例如 `Strafe`、`Silent`、`VIP`）。
`description`	String	否	模块的详细作用说明。
`enabled`	Boolean	是	模块初始是否开启。
`keybind`	String \| null	否	绑定的物理按键（如 `"R"`、`"F"`、`"X"`），不绑定则为 `null`。
`settings`	Array	否	子参数配置列表，定义在 ClickGUI 展开抽屉中显示的控件。

3. 控件参数类型 (settings)

settings 数组内的对象支持三种交互控件：

3.1 滑块数值控件 (slider)

用于调节浮点数或整数，如距离、倍率、延迟等：

{
  "type": "slider",
  "id": "range",
  "name": "Attack Range (攻击距离)",
  "value": 3.8,
  "min": 2.0,
  "max": 6.0,
  "step": 0.1
}

3.2 开关控件 (toggle)

布尔值开关，如静默转头、自动格挡等：

{
  "type": "toggle",
  "id": "autoblock",
  "name": "Auto Block (自动格挡)",
  "value": true
}

3.3 模式单选控件 (mode)

预定义字符串选项列表：

{
  "type": "mode",
  "id": "mode",
  "name": "Target Mode (攻击模式)",
  "value": "Single",
  "options": ["Single", "Switch", "Multi"]
}

4. 完整模组模板范例

您可以直接复制以下标准范例代码作为模板，在本地 models/ 目录下创建 fastplace.json 进行实验：

{
  "id": "fastplace",
  "name": "FastPlace",
  "category": "Player",
  "suffix": "Speed",
  "description": "消除方块放置右键内置冷却时间",
  "enabled": false,
  "keybind": null,
  "settings": [
    {
      "type": "slider",
      "id": "speed",
      "name": "Placement Speed (放置速度)",
      "value": 20.0,
      "min": 5.0,
      "max": 40.0,
      "step": 1.0
    },
    {
      "type": "toggle",
      "id": "blocks_only",
      "name": "Blocks Only (仅方块有效)",
      "value": true
    }
  ]
}

5. 热重载与实时调试技巧

开发调试技巧： 客户端运行时无需退出！直接在 models/ 文件夹中新建或修改 .json 文件，随后在键盘上按下 Insert 键，客户端将立即执行全量重新载入并在屏幕上刷新渲染！

6. 广场同步机制

在编写完成测试无误后，您可以登录本站并点击广场首页右上角的 [发布新模块] 按钮，将您的模块发布给全网其他用户。其他用户不仅可以直接在网页上下载 .json 放置在自己的 models/ 文件夹中，也可以通过游戏客户端内 CloudflareSync 模块的一键拉取功能自动同步载入！

返回模块广场