跳转到正文

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 ​

字段 / 分支本对象必需性结构约束
authoroptional heretype="string"
customDataoptional here$ref="#/$defs/customData"
descriptionoptional heretype="string"
expectedCatalogSha256optional heretype="string"; pattern="^[0-9a-f]{64}$"
frameTargetoptional here$ref="#/$defs/frameTarget"
idrequired$ref="#/$defs/identifier"
manifestVersionrequiredconst=5
materialsoptional here$ref="#/$defs/materials"
namerequired$ref="#/$defs/nonEmptyString"
optionsrequiredtype="array"; items=#/$defs/option
passesoptional heretype="array"; items=#/$defs/pass
programsoptional heretype="array"; items=#/$defs/program
resourcesrequiredtype="array"; items=#/$defs/resource
sceneAbiVersionrequiredconst=2
sceneCategoriesrequiredtype="array"; items=#/$defs/sceneRoute
settingsoptional here$ref="#/$defs/relativePath"
shaderRootoptional here$ref="#/$defs/relativePath"
versionrequired$ref="#/$defs/nonEmptyString"
完整结构规则: #/$defs/manifest
json
{
  "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 ​

字段 / 分支本对象必需性结构约束
authoroptional heretype="string"
descriptionoptional heretype="string"
expectedCatalogSha256optional heretype="string"; pattern="^[0-9a-f]{64}$"
fragmentsrequiredtype="array"; minItems=1; uniqueItems=true; items=#/$defs/relativePath
frameTargetoptional here$ref="#/$defs/frameTarget"
idrequired$ref="#/$defs/identifier"
manifestVersionrequiredconst=5
namerequired$ref="#/$defs/nonEmptyString"
sceneAbiVersionrequiredconst=2
settingsoptional here$ref="#/$defs/relativePath"
shaderRootoptional here$ref="#/$defs/relativePath"
sourceFormatVersionrequiredconst=1
versionrequired$ref="#/$defs/nonEmptyString"
完整结构规则: #/$defs/sourceManifest
json
{
  "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 ​

字段 / 分支本对象必需性结构约束
customDataoptional here$ref="#/$defs/customData"
materialsoptional here$ref="#/$defs/materialsFragment"
optionsoptional heretype="array"; items=#/$defs/option
passesoptional heretype="array"; items=#/$defs/pass
programsoptional heretype="array"; items=#/$defs/program
resourcesoptional heretype="array"; items=#/$defs/resource
sceneCategoriesoptional heretype="array"; items=#/$defs/sceneRoute
完整结构规则: #/$defs/fragment
json
{
  "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
json
{
  "pattern": "^[a-z0-9][a-z0-9_.-]*:[a-z0-9][a-z0-9_./-]*$",
  "type": "string"
}

relativePath · v5 ​

type="string"; minLength=1

完整结构规则: #/$defs/relativePath
json
{
  "minLength": 1,
  "type": "string"
}

nonEmptyString · v5 ​

type="string"; minLength=1

完整结构规则: #/$defs/nonEmptyString
json
{
  "minLength": 1,
  "type": "string"
}

positiveVersion · v5 ​

type="integer"; minimum=1

完整结构规则: #/$defs/positiveVersion
json
{
  "minimum": 1,
  "type": "integer"
}

完整示例 ​

来源与机器记录 ​

字段归属清单 · Schema v5 · Catalog v2 · Completion v2

schema-v3 · schema-v4 · schema-v5 · completion-v1 · completion-v2 · temporal · settings-guide ·

ShaderPackManifestLoader.cs · ShaderPackManifestComposer.cs

作者文档 · Manifest v5 / Scene ABI v2