Manifest 根与组合
行为与约束
单文件根提供包的 id、name、version、可选 author/description,以及 options/resources/programs/passes。id 是 namespaced 作者身份,目录名是外置来源选择器,version 是作者版本文本;三者不互换。shaderRoot 缺省为 shaders,文件和 include 冻结在对应 source owner 内。settings 是包内 JSON 路径,与 shaderRoot 分开解析。
组合根同时声明 sourceFormatVersion=1 与显式 fragments 数组。元数据、settings、frameTarget、sceneAbiVersion 和 expectedCatalogSha256 属于根;options/resources/programs/passes/sceneCategories 属于 fragment,v5 还允许 materials/customData。materialsFragment 只要求 abiVersion,但合成后的完整 materials 仍须满足 fallback/definitions 等要求。fragment 不递归包含其他 fragment。不要直接套用只描述 v3 的旧组合指南白名单。
路径拒绝绝对路径、盘符、空段、点/双点、自引用、重复规范化路径、目录和逃出包根的链接。fragments 按声明顺序、数组按各文件内部顺序合并;引用在合并后解析,可前向引用,ID 冲突不会被“后写覆盖”。任一文件失败,整个候选失败;诊断保留作者文件与局部 pointer。
Loader 允许 JSON 注释和尾逗号,但拒绝重复键、未知字段与非法组合。编辑器 Schema 不能替代 Loader。canonical manifest hash 排除物理文件名、fragment 边界、空白和注释,保留逻辑声明及数组顺序;它与 ZIP、源码清单、UI、generation 和驱动报告哈希各有身份域。expectedCatalogSha256 只核对对应 Catalog 身份,不是 release approval。
v4/v5 通过 Scene ABI 版本与路由声明决定场景所有权。v3 的传统隐式行为单列在兼容页,不得补写成 v5 默认。
自动生成的 v5 结构
必需性只针对所展示的对象/分支。Schema 没写 default 不表示运行时没有默认值。完整定义保留条件规则;Loader 另行解析 ID、所有权、预算及设备约束。
manifest · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
author | optional here | type="string" |
customData | optional here | $ref="#/$defs/customData" |
description | optional here | type="string" |
expectedCatalogSha256 | optional here | type="string"; pattern="^[0-9a-f]{64}$" |
frameTarget | optional here | $ref="#/$defs/frameTarget" |
id | required | $ref="#/$defs/identifier" |
manifestVersion | required | const=5 |
materials | optional here | $ref="#/$defs/materials" |
name | required | $ref="#/$defs/nonEmptyString" |
options | required | type="array"; items=#/$defs/option |
passes | optional here | type="array"; items=#/$defs/pass |
programs | optional here | type="array"; items=#/$defs/program |
resources | required | type="array"; items=#/$defs/resource |
sceneAbiVersion | required | const=2 |
sceneCategories | required | type="array"; items=#/$defs/sceneRoute |
settings | optional here | $ref="#/$defs/relativePath" |
shaderRoot | optional here | $ref="#/$defs/relativePath" |
version | required | $ref="#/$defs/nonEmptyString" |
完整结构规则: #/$defs/manifest
{
"additionalProperties": false,
"properties": {
"author": {
"type": "string"
},
"customData": {
"$ref": "#/$defs/customData"
},
"description": {
"type": "string"
},
"expectedCatalogSha256": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
"frameTarget": {
"$ref": "#/$defs/frameTarget"
},
"id": {
"$ref": "#/$defs/identifier"
},
"manifestVersion": {
"const": 5
},
"materials": {
"$ref": "#/$defs/materials"
},
"name": {
"$ref": "#/$defs/nonEmptyString"
},
"options": {
"items": {
"$ref": "#/$defs/option"
},
"type": "array"
},
"passes": {
"items": {
"$ref": "#/$defs/pass"
},
"type": "array"
},
"programs": {
"items": {
"$ref": "#/$defs/program"
},
"type": "array"
},
"resources": {
"items": {
"$ref": "#/$defs/resource"
},
"type": "array"
},
"sceneAbiVersion": {
"const": 2
},
"sceneCategories": {
"items": {
"$ref": "#/$defs/sceneRoute"
},
"type": "array"
},
"settings": {
"$ref": "#/$defs/relativePath"
},
"shaderRoot": {
"$ref": "#/$defs/relativePath"
},
"version": {
"$ref": "#/$defs/nonEmptyString"
}
},
"required": [
"manifestVersion",
"id",
"name",
"version",
"options",
"resources",
"sceneAbiVersion",
"sceneCategories"
],
"type": "object"
}sourceManifest · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
author | optional here | type="string" |
description | optional here | type="string" |
expectedCatalogSha256 | optional here | type="string"; pattern="^[0-9a-f]{64}$" |
fragments | required | type="array"; minItems=1; uniqueItems=true; items=#/$defs/relativePath |
frameTarget | optional here | $ref="#/$defs/frameTarget" |
id | required | $ref="#/$defs/identifier" |
manifestVersion | required | const=5 |
name | required | $ref="#/$defs/nonEmptyString" |
sceneAbiVersion | required | const=2 |
settings | optional here | $ref="#/$defs/relativePath" |
shaderRoot | optional here | $ref="#/$defs/relativePath" |
sourceFormatVersion | required | const=1 |
version | required | $ref="#/$defs/nonEmptyString" |
完整结构规则: #/$defs/sourceManifest
{
"additionalProperties": false,
"properties": {
"author": {
"type": "string"
},
"description": {
"type": "string"
},
"expectedCatalogSha256": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
"fragments": {
"items": {
"$ref": "#/$defs/relativePath"
},
"minItems": 1,
"type": "array",
"uniqueItems": true
},
"frameTarget": {
"$ref": "#/$defs/frameTarget"
},
"id": {
"$ref": "#/$defs/identifier"
},
"manifestVersion": {
"const": 5
},
"name": {
"$ref": "#/$defs/nonEmptyString"
},
"sceneAbiVersion": {
"const": 2
},
"settings": {
"$ref": "#/$defs/relativePath"
},
"shaderRoot": {
"$ref": "#/$defs/relativePath"
},
"sourceFormatVersion": {
"const": 1
},
"version": {
"$ref": "#/$defs/nonEmptyString"
}
},
"required": [
"sourceFormatVersion",
"manifestVersion",
"id",
"name",
"version",
"fragments",
"sceneAbiVersion"
],
"type": "object"
}fragment · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
customData | optional here | $ref="#/$defs/customData" |
materials | optional here | $ref="#/$defs/materialsFragment" |
options | optional here | type="array"; items=#/$defs/option |
passes | optional here | type="array"; items=#/$defs/pass |
programs | optional here | type="array"; items=#/$defs/program |
resources | optional here | type="array"; items=#/$defs/resource |
sceneCategories | optional here | type="array"; items=#/$defs/sceneRoute |
完整结构规则: #/$defs/fragment
{
"additionalProperties": false,
"properties": {
"customData": {
"$ref": "#/$defs/customData"
},
"materials": {
"$ref": "#/$defs/materialsFragment"
},
"options": {
"items": {
"$ref": "#/$defs/option"
},
"type": "array"
},
"passes": {
"items": {
"$ref": "#/$defs/pass"
},
"type": "array"
},
"programs": {
"items": {
"$ref": "#/$defs/program"
},
"type": "array"
},
"resources": {
"items": {
"$ref": "#/$defs/resource"
},
"type": "array"
},
"sceneCategories": {
"items": {
"$ref": "#/$defs/sceneRoute"
},
"type": "array"
}
},
"type": "object"
}identifier · v5
type="string"; pattern="^[a-z0-9][a-z0-9_.-]*:[a-z0-9][a-z0-9_./-]*$"
完整结构规则: #/$defs/identifier
{
"pattern": "^[a-z0-9][a-z0-9_.-]*:[a-z0-9][a-z0-9_./-]*$",
"type": "string"
}relativePath · v5
type="string"; minLength=1
完整结构规则: #/$defs/relativePath
{
"minLength": 1,
"type": "string"
}nonEmptyString · v5
type="string"; minLength=1
完整结构规则: #/$defs/nonEmptyString
{
"minLength": 1,
"type": "string"
}positiveVersion · v5
type="integer"; minimum=1
完整结构规则: #/$defs/positiveVersion
{
"minimum": 1,
"type": "integer"
}完整示例
来源与机器记录
字段归属清单 · Schema v5 · Catalog v2 · Completion v2
schema-v3 · schema-v4 · schema-v5 · completion-v1 · completion-v2 · temporal · settings-guide ·