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
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
abiVersion | required | const=1 |
contentGroups | optional here | type="array"; maxItems=1024; items=#/$defs/materialGroup |
definitions | required | type="array"; maxItems=4096; items=#/$defs/materialDefinition |
fallback | required | $ref="#/$defs/dataId" |
mappings | optional here | type="array"; maxItems=4096; items=#/$defs/materialMapping |
properties | optional here | type="array"; maxItems=32; items=#/$defs/materialProperty |
tags | optional here | type="array"; maxItems=64; items=#/$defs/materialTag |
完整结构规则: #/$defs/materials
{
"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
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
abiVersion | required | const=1 |
contentGroups | optional here | type="array"; maxItems=1024; items=#/$defs/materialGroup |
definitions | optional here | type="array"; maxItems=4096; items=#/$defs/materialDefinition |
fallback | optional here | $ref="#/$defs/dataId" |
mappings | optional here | type="array"; maxItems=4096; items=#/$defs/materialMapping |
properties | optional here | type="array"; maxItems=32; items=#/$defs/materialProperty |
tags | optional here | type="array"; maxItems=64; items=#/$defs/materialTag |
完整结构规则: #/$defs/materialsFragment
{
"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
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
default | required | — |
glsl | required | $ref="#/$defs/glslIdentifier" |
id | required | $ref="#/$defs/dataId" |
range | optional here | type="array"; minItems=2; maxItems=2 |
space | optional here | $ref="#/$defs/nonEmptyString" |
type | required | enum=["bool","int","uint","float","vec2","vec3","vec4"] |
unit | optional here | $ref="#/$defs/nonEmptyString" |
完整结构规则: #/$defs/materialProperty
{
"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
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
glsl | required | $ref="#/$defs/glslIdentifier" |
id | required | $ref="#/$defs/dataId" |
完整结构规则: #/$defs/materialTag
{
"additionalProperties": false,
"properties": {
"glsl": {
"$ref": "#/$defs/glslIdentifier"
},
"id": {
"$ref": "#/$defs/dataId"
}
},
"required": [
"id",
"glsl"
],
"type": "object"
}materialDefinition · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
id | required | $ref="#/$defs/dataId" |
shaderId | required | type="integer"; minimum=0; maximum=4294967295 |
tags | optional here | type="array"; maxItems=64; uniqueItems=true; items=#/$defs/dataId |
values | optional here | type="object"; additionalProperties={"$ref":"#/$defs/materialValue"} |
完整结构规则: #/$defs/materialDefinition
{
"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
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
effectiveIds | optional here | type="array"; maxItems=65536; uniqueItems=true; items=#/$defs/contentId |
geometryIds | optional here | type="array"; maxItems=65536; uniqueItems=true; items=#/$defs/dataId |
groups | optional here | type="array"; maxItems=65536; uniqueItems=true; items=#/$defs/dataId |
id | required | $ref="#/$defs/dataId" |
ids | optional here | type="array"; maxItems=65536; uniqueItems=true; items=#/$defs/contentId |
owners | optional here | type="array"; maxItems=65536; uniqueItems=true; items=#/$defs/contentOwner |
完整结构规则: #/$defs/materialGroup
{
"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
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
enabledWhen | optional here | type="array"; items=#/$defs/condition |
id | required | $ref="#/$defs/dataId" |
match | required | $ref="#/$defs/materialSelector" |
material | required | $ref="#/$defs/dataId" |
onMissing | optional here | enum=["error","warnAndSkip","skip"] |
priority | optional here | type="integer"; minimum=-2147483648; maximum=2147483647 |
完整结构规则: #/$defs/materialMapping
{
"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
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
effectiveIds | optional here | type="array"; maxItems=65536; uniqueItems=true; items=#/$defs/contentId |
geometryIds | optional here | type="array"; maxItems=65536; uniqueItems=true; items=#/$defs/dataId |
groups | optional here | type="array"; maxItems=65536; uniqueItems=true; items=#/$defs/dataId |
ids | optional here | type="array"; maxItems=65536; uniqueItems=true; items=#/$defs/contentId |
owners | optional here | type="array"; maxItems=65536; uniqueItems=true; items=#/$defs/contentOwner |
完整结构规则: #/$defs/materialSelector
{
"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
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
option | required | $ref="#/$defs/dataId" |
完整结构规则: #/$defs/materialOption
{
"additionalProperties": false,
"properties": {
"option": {
"$ref": "#/$defs/dataId"
}
},
"required": [
"option"
],
"type": "object"
}materialValue · v5
anyOf: 8
完整结构规则: #/$defs/materialValue
{
"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
{
"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
{
"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