manifest.json

每个 Mod 都必须有一个 manifest.json。上传到服务器时填写的表单字段与这里的字段一一对应。

字段

字段	类型	必填	默认	说明
id	string	✅	—	唯一标识。仅允许 a-z、0-9、-，且首字符为字母或数字（正则 ^[a-z0-9][a-z0-9-]*$，大小写不敏感）
name	string	✅	—	显示名称
version	string		1.0.0	语义化版本，用于缓存与更新判断
author	string		anonymous / unknown	作者名
description	string		''	一句话说明，浏览页会显示
main	string		index.js	入口文件名（相对 /mods/<id>/）；也允许是绝对 URL（上传的 Mod 走这条）
tags	string[]		[]	标签，用于浏览页搜索与展示
permissions	string[]		[]	声明需要的能力（声明式，便于审计与后续校验）
dependencies	string[]		[]	依赖的其他 Mod id；安装时会检查它们是否已安装
hash	string		null	代码哈希（上传接口字段，可选，用于完整性校验）

完整示例

{
  "id": "auto-highlight",
  "name": "自动高亮敌人",
  "version": "1.0.0",
  "author": "findor-team",
  "description": "进入战斗时自动高亮所有敌人",
  "main": "index.js",
  "tags": ["战斗", "高亮", "自动化"],
  "permissions": ["features", "models", "events", "commands", "storage"],
  "dependencies": []
}

permissions 可声明项

值	对应能力
features	通过 ctx.features 挂载自己的功能开关
models	ctx.models（访问游戏 Model 实例与 gameObject）
events	ctx.events（订阅全局事件，见事件清单）
commands	ctx.commands（注册 / <modId>:name 聊天命令）
storage	ctx.storage（按 Mod 隔离的 localStorage 存储）
protocol	ctx.protocol（C→S 发包、S→C 本地调用、包钩子）
ui	ctx.ui（通知、自定义页面、对话框）
actions	ctx.actions（拦截/改写游戏 Action）

权限目前是声明式的

加载器会保存 permissions 字段，但当前不做强制拦截——即声明了什么并不限制调用什么。请自觉只声明并只使用你真正需要的能力。

依赖与加载顺序

dependencies 里的 Mod 必须已安装，否则安装会被拒绝并提示 缺少依赖: <id>。加载器会在启用时按依赖关系做拓扑排序，被依赖者先启用。

id 冲突

同一个 id 不能重复：

• 种子目录：mods/<id>/ 目录名即 id，与 registry.json 中的条目一一对应
• 上传接口：服务端会先查 KV mod:<id>，已存在则返回 409 Mod already exists（并在响应里带上已存在的记录）

下一步：ctx 全量 API · 发布与安装