清单

manifest.json 是 Studio 唯一会在不执行你的代码的情况下读取的文件。它声明插件提供了什么，而安装提示中显示的一切都由它计算得出

{
  "manifestVersion": 2,
  "id": "yourname.hello",
  "name": "Hello",
  "version": "1.0.0",
  "publisher": "Your Name",
  "description": "A starter plugin.",
  "entries": { "studio": "main.js", "runtime": "runtime.js" },
  "contributes": {
    "blueprintNodes": ["yourname.hello.log"],
    "runtimeCapabilities": ["store"]
  },
  "permissions": []
}

顶层字段

入口路径不能是绝对路径，也不能包含 ..、.、空字节、? 或 #

contributes

contributes 是插件能做什么的唯一真相来源。Studio 无需运行插件代码就能据此校验一个项目，安装时的权限集合也由它派生而来

每一个节点类型、控件类型、存储命名空间、sidecar id、构建时依赖 id、保留存档 id 和结构 id 都必须以你的插件 id 为前缀。contributes 下出现未知的键会被拒绝，而不是被忽略

blueprintNodes 与 widgets

注册一个你没有声明的类型会在加载时抛错，两个入口都是如此。正是这份声明，让 Studio 能在构建之前就告诉作者：项目里用到的某个节点没有 runtime 提供方——而不是发布一个带着无效节点的游戏

widgetText

控件里有玩家读到的文字（例如标题或说明）时，按控件类型列出存放这些文字的属性：

{
  "contributes": {
    "widgets": ["yourname.hello.badge"],
    "widgetText": {
      "yourname.hello.badge": [
        { "prop": "title", "label": "Title", "localized": { "zh": "标题", "ja": "タイトル" } },
        { "prop": "caption", "multiline": true }
      ]
    }
  }
}

Studio 像对待自己的文本与按钮控件的文字那样处理每个声明的属性：属性面板在内容一节中提供直接输入或翻译键的选择，画布绘制键的文字，这些文字进入翻译表与导出，项目检查报告缺少的译文或键，字形检查也会读取它们。在游戏中，render 收到的属性已是玩家语言中的文字，控件自己从不解析键

两个入口都读取这份声明：studio 入口的控件按它编辑，runtime 入口的控件按它绘制。这里列出的每个类型也必须在 contributes.widgets 中，且至少有一项。prop 与 keyProp 须是标识符，不能是 runtimeTextOrigin 或 runtimeTextUnit，同一控件内名称不能重复。widgetText 不派生任何安装权限

runtimeData

插件存储位于项目的编辑器目录下，而那个目录永远不会被打包。如果你的 runtime 入口需要作者在 Studio 中编写的数据——一份目录表、一张查找表——就把这些命名空间列在这里，并用 app.game.data.readJson(namespace) 读取

{ "contributes": { "runtimeData": ["yourname.hello.catalog"] } }

这个列表是一份显式白名单，这样纯编辑器的插件状态就不会意外泄漏进发布的游戏。readJson 是同步的——数据随包一起分发——当命名空间未被声明、项目从未写入过，或游戏早于该数据被发布时，它返回 null。请优雅降级；不要假定作者数据一定存在

runtimeCapabilities

十三个能力域，每一个对应 app.game 的一个命名空间。未声明的域在对象上根本不存在，而不是一个会抛错的方法。声明了它却没有 entries.runtime 是清单错误

{ "contributes": { "runtimeCapabilities": ["store", "events", "state.read"] } }

store · events · state.read · state.write · saves.read · saves.write · ui.overlay · assets · locale · menu · story.compile · diagnostics · process.memory

完整模型、每个能力具体授予什么，以及各环境如何进一步收窄它：Runtime API

sidecars 与 buildDependencies

两个重量级声明。sidecar 是随作者构建的游戏一起发布的原生子进程；构建时依赖 是 Studio 在构建时下载、校验并缓存的外部二进制文件。两者都以 <platform>-<arch> 为键，也都必须提供 sha256

locales

一个 Studio 语言包——插件新增的语言，或它为内置语言补上的缺口。参见 创建第一个插件。只包含 contributes.locales、没有任何入口代码的清单也是一个有效的插件

reservedSaveIds

插件以自己的 id 写下的存档（例如快速存档位、检查点）和玩家的存档放在同一个存档库里。把这些 id 列在这里，它们就不会出现在玩家的存档列表里：List Saves、所有基于它的存档界面以及 Dev Mode 的存档面板都会略过它们，和略过自动存档一样。其余途径照常能用到它们：插件自己的 app.game.saves（它的 listIds 原样返回存档库），以及接收 id 的存档节点，例如 Load Save、Delete Save 和各个存档读取节点

{ "contributes": { "reservedSaveIds": ["yourname.quicksave.slot"] } }

每个 id 都必须以你的插件 id 开头，所以插件藏不掉作者自己用 Save Game 写下的存档位。只有插件在游戏里运行时这些 id 才是保留的；在不运行该插件的游戏里，这些存档会和其他存档一样被列出

structs

节点给出一组记录（画廊条目、成就、商店商品等）时，在这里声明记录的字段，并把输出引脚的类型写成该结构：

{
  "contributes": {
    "blueprintNodes": ["yourname.shop.getGoods"],
    "structs": [
      {
        "id": "yourname.shop.good",
        "name": "Shop item",
        "localized": { "zh": "商品", "ja": "商品" },
        "fields": [
          { "key": "id", "type": "string" },
          { "key": "name", "type": "string" },
          { "key": "price", "type": "number" },
          { "key": "icon", "type": "image" },
          { "key": "owned", "type": "boolean" }
        ]
      }
    ]
  }
}

{ id: "goods", kind: "output", semantic: "data", valueType: "array<struct:yourname.shop.good>", label: "Goods" }

声明的结构与引擎自己的结构（例如结局、存档条目）同等对待：

• 列表可以在编辑内容中把它选作结构。字段由插件提供，不能编辑，作者不必照着你的文档抄写字段名
• 从该引脚拖出连线时，添加节点菜单列出每个字段；Get Field 按名称读取字段，输出带有字段的类型
• 连入 Set List Content 的行缺少列表结构的字段时，画布上和项目检查中都会报告

字段的 key 同时就是它的 id，因此作者无法给插件结构的字段改名。编辑器、运行中的游戏和命令行检查都在执行插件代码之前从清单读取这些声明。插件未加载（被禁用或未安装）时，它的结构与它的节点一样不可用：使用该结构的列表不显示字段，项目的依赖检查会指出是哪个插件。structs 不派生安装权限

权限是派生的

安装权限分为两类，这个划分正是重点所在

作者声明的——由你写在 permissions[] 里。它们是与 contributes 无关的 Studio 提权控制项：

{
  "permissions": [
    { "kind": "filesystem", "path": "/absolute/path", "mode": "readwrite", "recursive": true },
    { "kind": "api", "capability": "bash.execute" }
  ]
}

这些只影响 studio 入口。授权按 pluginId@version 记录，所以提升版本号就需要作者重新批准一次

派生的——由 Studio 从 contributes 计算得出，绝不由你手写：

这正是安装提示能保持诚实的原因：一项能力只在一个地方声明，因此提示列出的内容与插件真正能触及的内容不可能漂移开来。它也让更新的行为变得正常——新增一项能力会扩大派生出的权限集，于是自动重新向作者索取批准；而没有扩大任何范围的版本则沿用已有的授权

校验失败

不派生任何权限的贡献

tests、buildConfig、reservedSaveIds 和 structs 是不会产生安装权限的贡献，且每一种都是裁定而不是漏掉。

其余每一种带代码的贡献，在插件装载那一刻就拿到了一项能力。而测试只有在作者打开 Run > Test、在对话框里挑中它、再按下 Start 时才会跑；安装时根本没有一项“环境里一直在”的能力需要同意，而测试跑起来之后能碰什么，由它自己的 requires 单独把关。而构建配置字段只是一个留给作者填的空，填了也不会让插件多碰到任何东西。而保留存档 id 只是把插件自己命名空间里的 id 从玩家的存档列表里拿掉。结构只描述插件节点本来就会给出的行有哪些字段。