Skip to content

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 / branchPresence in this objectStructural constraints
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
Full structural rule: #/$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 ​

Field / branchPresence in this objectStructural constraints
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
Full structural rule: #/$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 ​

Field / branchPresence in this objectStructural constraints
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"
Full structural rule: #/$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 ​

Field / branchPresence in this objectStructural constraints
glslrequired$ref="#/$defs/glslIdentifier"
idrequired$ref="#/$defs/dataId"
Full structural rule: #/$defs/materialTag
json
{
  "additionalProperties": false,
  "properties": {
    "glsl": {
      "$ref": "#/$defs/glslIdentifier"
    },
    "id": {
      "$ref": "#/$defs/dataId"
    }
  },
  "required": [
    "id",
    "glsl"
  ],
  "type": "object"
}

materialDefinition · v5 ​

Field / branchPresence in this objectStructural constraints
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"}
Full structural rule: #/$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 ​

Field / branchPresence in this objectStructural constraints
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
Full structural rule: #/$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 ​

Field / branchPresence in this objectStructural constraints
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
Full structural rule: #/$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 ​

Field / branchPresence in this objectStructural constraints
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
Full structural rule: #/$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 ​

Field / branchPresence in this objectStructural constraints
optionrequired$ref="#/$defs/dataId"
Full structural rule: #/$defs/materialOption
json
{
  "additionalProperties": false,
  "properties": {
    "option": {
      "$ref": "#/$defs/dataId"
    }
  },
  "required": [
    "option"
  ],
  "type": "object"
}

materialValue · v5 ​

anyOf: 8

Full structural rule: #/$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})+$"

Full structural rule: #/$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})+$"

Full structural rule: #/$defs/contentOwner
json
{
  "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

Author documentation · Manifest v5 / Scene ABI v2