跳转到正文

Materials ABI v1 ​

行为与约束 ​

fallback 对应 definition 的 shaderId 必须为 0,其他 definition 的 shaderId 必须非零。materialTable 的所有命令消费者必须是指定 Program 的 readOnly storageBuffer;即使只读 header,也不允许 uniformBuffer。额外声明一条合法 SSBO 不会使非法 UBO 合法。

仅 Manifest v5。materials 声明 abiVersion=1、properties、tags、definitions、contentGroups、mappings、fallback。property 的 id/type/default/glsl 定义布局,range/unit/space 补充数值合同;tag 的 id/glsl 决定 64-bit 标志域。definition 的 id 与 shaderId 是不同身份,values 以已声明 property ID 为键,可引用兼容 option。fallback 必须指向合法定义。

logicalId 是内容声明,effectiveId/effectiveOwner 是最终覆盖者,geometry/RenderIdentifier 是几何身份,材质 record index 和作者 uint32 shaderId 又是两个域。不得从 2050 一类旧几何数字反推树种或动态 BlockIndex。aliases/replacement chain 只来自宿主世界快照。

selector 的 ids 选择 logical ID/alias,geometryIds/groups 扩展候选,effectiveIds/owners 再约束最终身份;contentGroups 自身也有 ids/effectiveIds/geometryIds/groups/owners。mappings 使用 match/material/priority/enabledWhen/onMissing,同级最高 priority 冲突应失败;onMissing 为 error、warnAndSkip、skip,未匹配内容走 fallback。没有同世界 WorldFinal 快照时 mappingStatus=deferred,不能假装已经解析运行时槽位。

materialTable buffer 从最终布局算大小。头部 16 B,lookup 从 byte 16 开始,record 起点取决于最终 identifier count;每条 record 有 16 B 身份/tag 区,每个 property 另占 16 B。宿主虚拟 include /dawnlight/materials-v1.glsl 提供 LookupMaterial、MaterialShaderId、MaterialHasTag;block 名和 binding 来自当前 invocation。使用 readonly/std430、高精度 uvec4,identifier varying 用 flat highp uint,tag 保留完整 64 bits。

definitions/layout hash、mapping hash 和 payload hash 分别描述定义/ABI、当前世界映射和精确 words,不能互换。option 或 Mod 内容改变需重新解析对应 generation。离线 materials layout/explain 不证明 SSBO 已被真实驱动消费;W4 的教学材质字节也不是本 ABI 的材质表。

自动生成的 v5 结构 ​

必需性只针对所展示的对象/分支。Schema 没写 default 不表示运行时没有默认值。完整定义保留条件规则;Loader 另行解析 ID、所有权、预算及设备约束。

materials · v5 ​

字段 / 分支本对象必需性结构约束
abiVersionrequiredconst=1
contentGroupsoptional heretype="array"; maxItems=1024; items=#/$defs/materialGroup
definitionsrequiredtype="array"; maxItems=4096; items=#/$defs/materialDefinition
fallbackrequired$ref="#/$defs/dataId"
mappingsoptional heretype="array"; maxItems=4096; items=#/$defs/materialMapping
propertiesoptional heretype="array"; maxItems=32; items=#/$defs/materialProperty
tagsoptional heretype="array"; maxItems=64; items=#/$defs/materialTag
完整结构规则: #/$defs/materials
json
{
  "additionalProperties": false,
  "properties": {
    "abiVersion": {
      "const": 1
    },
    "contentGroups": {
      "items": {
        "$ref": "#/$defs/materialGroup"
      },
      "maxItems": 1024,
      "type": "array"
    },
    "definitions": {
      "items": {
        "$ref": "#/$defs/materialDefinition"
      },
      "maxItems": 4096,
      "type": "array"
    },
    "fallback": {
      "$ref": "#/$defs/dataId"
    },
    "mappings": {
      "items": {
        "$ref": "#/$defs/materialMapping"
      },
      "maxItems": 4096,
      "type": "array"
    },
    "properties": {
      "items": {
        "$ref": "#/$defs/materialProperty"
      },
      "maxItems": 32,
      "type": "array"
    },
    "tags": {
      "items": {
        "$ref": "#/$defs/materialTag"
      },
      "maxItems": 64,
      "type": "array"
    }
  },
  "required": [
    "abiVersion",
    "fallback",
    "definitions"
  ],
  "type": "object"
}

materialsFragment · v5 ​

字段 / 分支本对象必需性结构约束
abiVersionrequiredconst=1
contentGroupsoptional heretype="array"; maxItems=1024; items=#/$defs/materialGroup
definitionsoptional heretype="array"; maxItems=4096; items=#/$defs/materialDefinition
fallbackoptional here$ref="#/$defs/dataId"
mappingsoptional heretype="array"; maxItems=4096; items=#/$defs/materialMapping
propertiesoptional heretype="array"; maxItems=32; items=#/$defs/materialProperty
tagsoptional heretype="array"; maxItems=64; items=#/$defs/materialTag
完整结构规则: #/$defs/materialsFragment
json
{
  "additionalProperties": false,
  "properties": {
    "abiVersion": {
      "const": 1
    },
    "contentGroups": {
      "items": {
        "$ref": "#/$defs/materialGroup"
      },
      "maxItems": 1024,
      "type": "array"
    },
    "definitions": {
      "items": {
        "$ref": "#/$defs/materialDefinition"
      },
      "maxItems": 4096,
      "type": "array"
    },
    "fallback": {
      "$ref": "#/$defs/dataId"
    },
    "mappings": {
      "items": {
        "$ref": "#/$defs/materialMapping"
      },
      "maxItems": 4096,
      "type": "array"
    },
    "properties": {
      "items": {
        "$ref": "#/$defs/materialProperty"
      },
      "maxItems": 32,
      "type": "array"
    },
    "tags": {
      "items": {
        "$ref": "#/$defs/materialTag"
      },
      "maxItems": 64,
      "type": "array"
    }
  },
  "required": [
    "abiVersion"
  ],
  "type": "object"
}

materialProperty · v5 ​

字段 / 分支本对象必需性结构约束
defaultrequired—
glslrequired$ref="#/$defs/glslIdentifier"
idrequired$ref="#/$defs/dataId"
rangeoptional heretype="array"; minItems=2; maxItems=2
spaceoptional here$ref="#/$defs/nonEmptyString"
typerequiredenum=["bool","int","uint","float","vec2","vec3","vec4"]
unitoptional here$ref="#/$defs/nonEmptyString"
完整结构规则: #/$defs/materialProperty
json
{
  "additionalProperties": false,
  "allOf": [
    {
      "if": {
        "properties": {
          "type": {
            "const": "bool"
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "properties": {
          "default": {
            "type": "boolean"
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "type": {
            "const": "int"
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "properties": {
          "default": {
            "maximum": 2147483647,
            "minimum": -2147483648,
            "type": "integer"
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "type": {
            "const": "uint"
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "properties": {
          "default": {
            "maximum": 4294967295,
            "minimum": 0,
            "type": "integer"
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "type": {
            "const": "float"
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "properties": {
          "default": {
            "maximum": 3.4028234663852886e+38,
            "minimum": -3.4028234663852886e+38,
            "type": "number"
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "type": {
            "const": "vec2"
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "properties": {
          "default": {
            "items": {
              "maximum": 3.4028234663852886e+38,
              "minimum": -3.4028234663852886e+38,
              "type": "number"
            },
            "maxItems": 2,
            "minItems": 2,
            "type": "array"
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "type": {
            "const": "vec3"
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "properties": {
          "default": {
            "items": {
              "maximum": 3.4028234663852886e+38,
              "minimum": -3.4028234663852886e+38,
              "type": "number"
            },
            "maxItems": 3,
            "minItems": 3,
            "type": "array"
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "type": {
            "const": "vec4"
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "properties": {
          "default": {
            "items": {
              "maximum": 3.4028234663852886e+38,
              "minimum": -3.4028234663852886e+38,
              "type": "number"
            },
            "maxItems": 4,
            "minItems": 4,
            "type": "array"
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "type": {
            "const": "bool"
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "not": {
          "anyOf": [
            {
              "required": [
                "range"
              ]
            }
          ]
        }
      }
    }
  ],
  "properties": {
    "default": {},
    "glsl": {
      "$ref": "#/$defs/glslIdentifier"
    },
    "id": {
      "$ref": "#/$defs/dataId"
    },
    "range": {
      "items": {
        "type": "number"
      },
      "maxItems": 2,
      "minItems": 2,
      "type": "array"
    },
    "space": {
      "$ref": "#/$defs/nonEmptyString"
    },
    "type": {
      "enum": [
        "bool",
        "int",
        "uint",
        "float",
        "vec2",
        "vec3",
        "vec4"
      ]
    },
    "unit": {
      "$ref": "#/$defs/nonEmptyString"
    }
  },
  "required": [
    "id",
    "type",
    "default",
    "glsl"
  ],
  "type": "object"
}

materialTag · v5 ​

字段 / 分支本对象必需性结构约束
glslrequired$ref="#/$defs/glslIdentifier"
idrequired$ref="#/$defs/dataId"
完整结构规则: #/$defs/materialTag
json
{
  "additionalProperties": false,
  "properties": {
    "glsl": {
      "$ref": "#/$defs/glslIdentifier"
    },
    "id": {
      "$ref": "#/$defs/dataId"
    }
  },
  "required": [
    "id",
    "glsl"
  ],
  "type": "object"
}

materialDefinition · v5 ​

字段 / 分支本对象必需性结构约束
idrequired$ref="#/$defs/dataId"
shaderIdrequiredtype="integer"; minimum=0; maximum=4294967295
tagsoptional heretype="array"; maxItems=64; uniqueItems=true; items=#/$defs/dataId
valuesoptional heretype="object"; additionalProperties={"$ref":"#/$defs/materialValue"}
完整结构规则: #/$defs/materialDefinition
json
{
  "additionalProperties": false,
  "properties": {
    "id": {
      "$ref": "#/$defs/dataId"
    },
    "shaderId": {
      "maximum": 4294967295,
      "minimum": 0,
      "type": "integer"
    },
    "tags": {
      "items": {
        "$ref": "#/$defs/dataId"
      },
      "maxItems": 64,
      "type": "array",
      "uniqueItems": true
    },
    "values": {
      "additionalProperties": {
        "$ref": "#/$defs/materialValue"
      },
      "maxProperties": 32,
      "propertyNames": {
        "$ref": "#/$defs/dataId"
      },
      "type": "object"
    }
  },
  "required": [
    "id",
    "shaderId"
  ],
  "type": "object"
}

materialGroup · v5 ​

字段 / 分支本对象必需性结构约束
effectiveIdsoptional heretype="array"; maxItems=65536; uniqueItems=true; items=#/$defs/contentId
geometryIdsoptional heretype="array"; maxItems=65536; uniqueItems=true; items=#/$defs/dataId
groupsoptional heretype="array"; maxItems=65536; uniqueItems=true; items=#/$defs/dataId
idrequired$ref="#/$defs/dataId"
idsoptional heretype="array"; maxItems=65536; uniqueItems=true; items=#/$defs/contentId
ownersoptional heretype="array"; maxItems=65536; uniqueItems=true; items=#/$defs/contentOwner
完整结构规则: #/$defs/materialGroup
json
{
  "additionalProperties": false,
  "allOf": [
    {
      "anyOf": [
        {
          "properties": {
            "ids": {
              "minItems": 1
            }
          },
          "required": [
            "ids"
          ]
        },
        {
          "properties": {
            "effectiveIds": {
              "minItems": 1
            }
          },
          "required": [
            "effectiveIds"
          ]
        },
        {
          "properties": {
            "owners": {
              "minItems": 1
            }
          },
          "required": [
            "owners"
          ]
        },
        {
          "properties": {
            "geometryIds": {
              "minItems": 1
            }
          },
          "required": [
            "geometryIds"
          ]
        },
        {
          "properties": {
            "groups": {
              "minItems": 1
            }
          },
          "required": [
            "groups"
          ]
        }
      ]
    }
  ],
  "properties": {
    "effectiveIds": {
      "items": {
        "$ref": "#/$defs/contentId"
      },
      "maxItems": 65536,
      "type": "array",
      "uniqueItems": true
    },
    "geometryIds": {
      "items": {
        "$ref": "#/$defs/dataId"
      },
      "maxItems": 65536,
      "type": "array",
      "uniqueItems": true
    },
    "groups": {
      "items": {
        "$ref": "#/$defs/dataId"
      },
      "maxItems": 65536,
      "type": "array",
      "uniqueItems": true
    },
    "id": {
      "$ref": "#/$defs/dataId"
    },
    "ids": {
      "items": {
        "$ref": "#/$defs/contentId"
      },
      "maxItems": 65536,
      "type": "array",
      "uniqueItems": true
    },
    "owners": {
      "items": {
        "$ref": "#/$defs/contentOwner"
      },
      "maxItems": 65536,
      "type": "array",
      "uniqueItems": true
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

materialMapping · v5 ​

字段 / 分支本对象必需性结构约束
enabledWhenoptional heretype="array"; items=#/$defs/condition
idrequired$ref="#/$defs/dataId"
matchrequired$ref="#/$defs/materialSelector"
materialrequired$ref="#/$defs/dataId"
onMissingoptional hereenum=["error","warnAndSkip","skip"]
priorityoptional heretype="integer"; minimum=-2147483648; maximum=2147483647
完整结构规则: #/$defs/materialMapping
json
{
  "additionalProperties": false,
  "properties": {
    "enabledWhen": {
      "items": {
        "$ref": "#/$defs/condition"
      },
      "type": "array"
    },
    "id": {
      "$ref": "#/$defs/dataId"
    },
    "match": {
      "$ref": "#/$defs/materialSelector"
    },
    "material": {
      "$ref": "#/$defs/dataId"
    },
    "onMissing": {
      "enum": [
        "error",
        "warnAndSkip",
        "skip"
      ]
    },
    "priority": {
      "maximum": 2147483647,
      "minimum": -2147483648,
      "type": "integer"
    }
  },
  "required": [
    "id",
    "match",
    "material"
  ],
  "type": "object"
}

materialSelector · v5 ​

字段 / 分支本对象必需性结构约束
effectiveIdsoptional heretype="array"; maxItems=65536; uniqueItems=true; items=#/$defs/contentId
geometryIdsoptional heretype="array"; maxItems=65536; uniqueItems=true; items=#/$defs/dataId
groupsoptional heretype="array"; maxItems=65536; uniqueItems=true; items=#/$defs/dataId
idsoptional heretype="array"; maxItems=65536; uniqueItems=true; items=#/$defs/contentId
ownersoptional heretype="array"; maxItems=65536; uniqueItems=true; items=#/$defs/contentOwner
完整结构规则: #/$defs/materialSelector
json
{
  "additionalProperties": false,
  "allOf": [
    {
      "anyOf": [
        {
          "properties": {
            "ids": {
              "minItems": 1
            }
          },
          "required": [
            "ids"
          ]
        },
        {
          "properties": {
            "effectiveIds": {
              "minItems": 1
            }
          },
          "required": [
            "effectiveIds"
          ]
        },
        {
          "properties": {
            "owners": {
              "minItems": 1
            }
          },
          "required": [
            "owners"
          ]
        },
        {
          "properties": {
            "geometryIds": {
              "minItems": 1
            }
          },
          "required": [
            "geometryIds"
          ]
        },
        {
          "properties": {
            "groups": {
              "minItems": 1
            }
          },
          "required": [
            "groups"
          ]
        }
      ]
    }
  ],
  "properties": {
    "effectiveIds": {
      "items": {
        "$ref": "#/$defs/contentId"
      },
      "maxItems": 65536,
      "type": "array",
      "uniqueItems": true
    },
    "geometryIds": {
      "items": {
        "$ref": "#/$defs/dataId"
      },
      "maxItems": 65536,
      "type": "array",
      "uniqueItems": true
    },
    "groups": {
      "items": {
        "$ref": "#/$defs/dataId"
      },
      "maxItems": 65536,
      "type": "array",
      "uniqueItems": true
    },
    "ids": {
      "items": {
        "$ref": "#/$defs/contentId"
      },
      "maxItems": 65536,
      "type": "array",
      "uniqueItems": true
    },
    "owners": {
      "items": {
        "$ref": "#/$defs/contentOwner"
      },
      "maxItems": 65536,
      "type": "array",
      "uniqueItems": true
    }
  },
  "type": "object"
}

materialOption · v5 ​

字段 / 分支本对象必需性结构约束
optionrequired$ref="#/$defs/dataId"
完整结构规则: #/$defs/materialOption
json
{
  "additionalProperties": false,
  "properties": {
    "option": {
      "$ref": "#/$defs/dataId"
    }
  },
  "required": [
    "option"
  ],
  "type": "object"
}

materialValue · v5 ​

anyOf: 8

完整结构规则: #/$defs/materialValue
json
{
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "maximum": 2147483647,
      "minimum": -2147483648,
      "type": "integer"
    },
    {
      "maximum": 4294967295,
      "minimum": 0,
      "type": "integer"
    },
    {
      "maximum": 3.4028234663852886e+38,
      "minimum": -3.4028234663852886e+38,
      "type": "number"
    },
    {
      "items": {
        "maximum": 3.4028234663852886e+38,
        "minimum": -3.4028234663852886e+38,
        "type": "number"
      },
      "maxItems": 2,
      "minItems": 2,
      "type": "array"
    },
    {
      "items": {
        "maximum": 3.4028234663852886e+38,
        "minimum": -3.4028234663852886e+38,
        "type": "number"
      },
      "maxItems": 3,
      "minItems": 3,
      "type": "array"
    },
    {
      "items": {
        "maximum": 3.4028234663852886e+38,
        "minimum": -3.4028234663852886e+38,
        "type": "number"
      },
      "maxItems": 4,
      "minItems": 4,
      "type": "array"
    },
    {
      "$ref": "#/$defs/materialOption"
    }
  ]
}

contentId · v5 ​

type="string"; maxLength=512; pattern="^(?:[A-Za-z0-9_.-]|%[0-9A-F]{2})+:(?:[A-Za-z0-9_.-]|%[0-9A-F]{2})+$"

完整结构规则: #/$defs/contentId
json
{
  "maxLength": 512,
  "pattern": "^(?:[A-Za-z0-9_.-]|%[0-9A-F]{2})+:(?:[A-Za-z0-9_.-]|%[0-9A-F]{2})+$",
  "type": "string"
}

contentOwner · v5 ​

type="string"; maxLength=512; pattern="^(?:[A-Za-z0-9_.-]|%[0-9A-F]{2})+$"

完整结构规则: #/$defs/contentOwner
json
{
  "maxLength": 512,
  "pattern": "^(?:[A-Za-z0-9_.-]|%[0-9A-F]{2})+$",
  "type": "string"
}

完整示例 ​

来源与机器记录 ​

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

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

ShaderPackManifestDataLoader.cs · MaterialTableShaderContract.cs

作者文档 · Manifest v5 / Scene ABI v2