Materials ABI v1
Behavior and constraints
The fallback definition must use shaderId 0; every other definition must use a nonzero shaderId. Every materialTable command consumer must be a readOnly storageBuffer attached to a Program. Even header-only uniformBuffer access is rejected; an additional valid SSBO cannot legalize an invalid UBO.
Manifest v5 only. materials declares abiVersion=1, properties, tags, definitions, contentGroups, mappings and fallback. A property's id/type/default/glsl defines layout, with range/unit/space for numeric contracts. Tag id/glsl names a 64-bit flag domain. Definition id differs from shaderId; values is keyed by declared property IDs and may reference compatible options. fallback must resolve to a valid definition.
logicalId identifies declared content, effectiveId/effectiveOwner its final replacement, and geometry/RenderIdentifier geometry. Material record index and author uint32 shaderId are two more domains. Never infer a species or dynamic BlockIndex from a legacy geometry number such as 2050. Aliases and replacement chains come only from the host's world snapshot.
Selector ids matches logical IDs/aliases; geometryIds/groups expands candidates; effectiveIds/owners constrains final identity. contentGroups has the same identity selectors plus its own group ID. Mappings uses match/material/priority/enabledWhen/onMissing. Equal highest-priority conflicts fail. onMissing is error, warnAndSkip or skip; unmatched content uses fallback. Without the same world's WorldFinal snapshot, mappingStatus stays deferred rather than inventing runtime slots.
materialTable buffer size comes from final layout. The header is 16 B, lookup starts at byte 16, and record offset depends on final identifier count. Each record has 16 B identity/tag data plus 16 B per property. Virtual /dawnlight/materials-v1.glsl supplies LookupMaterial, MaterialShaderId and MaterialHasTag, using the invocation's block name/binding. Use readonly/std430, high-precision uvec4 and flat highp uint identifiers; retain all 64 tag bits.
Definition/layout, world mapping and exact-word payload hashes identify different domains. Option/Mod changes require generation-specific resolution. Offline materials layout/explain does not prove actual SSBO consumption. W4's teaching material bytes are separate from this table ABI.
Generated v5 structure
Required applies to the displayed object/branch. Absence of a Schema default does not establish a runtime default. Conditional rules remain in the complete definition below; Loader validation also resolves IDs, ownership, budgets and device limits.
materials · v5
| Field / branch | Presence in this object | Structural constraints |
|---|---|---|
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 |
Full structural rule: #/$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
| Field / branch | Presence in this object | Structural constraints |
|---|---|---|
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 |
Full structural rule: #/$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
| Field / branch | Presence in this object | Structural constraints |
|---|---|---|
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" |
Full structural rule: #/$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
| Field / branch | Presence in this object | Structural constraints |
|---|---|---|
glsl | required | $ref="#/$defs/glslIdentifier" |
id | required | $ref="#/$defs/dataId" |
Full structural rule: #/$defs/materialTag
{
"additionalProperties": false,
"properties": {
"glsl": {
"$ref": "#/$defs/glslIdentifier"
},
"id": {
"$ref": "#/$defs/dataId"
}
},
"required": [
"id",
"glsl"
],
"type": "object"
}materialDefinition · v5
| Field / branch | Presence in this object | Structural constraints |
|---|---|---|
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"} |
Full structural rule: #/$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
| Field / branch | Presence in this object | Structural constraints |
|---|---|---|
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 |
Full structural rule: #/$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
| Field / branch | Presence in this object | Structural constraints |
|---|---|---|
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 |
Full structural rule: #/$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
| Field / branch | Presence in this object | Structural constraints |
|---|---|---|
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 |
Full structural rule: #/$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
| Field / branch | Presence in this object | Structural constraints |
|---|---|---|
option | required | $ref="#/$defs/dataId" |
Full structural rule: #/$defs/materialOption
{
"additionalProperties": false,
"properties": {
"option": {
"$ref": "#/$defs/dataId"
}
},
"required": [
"option"
],
"type": "object"
}materialValue · v5
anyOf: 8
Full structural rule: #/$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})+$"
Full structural rule: #/$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})+$"
Full structural rule: #/$defs/contentOwner
{
"maxLength": 512,
"pattern": "^(?:[A-Za-z0-9_.-]|%[0-9A-F]{2})+$",
"type": "string"
}Complete examples
Sources and machine records
Coverage inventory · Schema v5 · Catalog v2 · Completion v2
schema-v3 · schema-v4 · schema-v5 · completion-v1 · completion-v2 · temporal · settings-guide ·
ShaderPackManifestDataLoader.cs · MaterialTableShaderContract.cs