Material format

VGAI Reference 0.3

Planned versioned generated-schema truth covering Scene materials and material registry.

planned · generated · immutable Reference 0.3

Lifecycle and constraints

Detailed constraints will publish with the generated or reviewed entry.

Runnable Learn material

Generated format inventory

Inventory only — AC-REF-002 is not passed. Valid parser-verified examples, narrative guidance, complete cross-field/runtime constraints, and version history remain deferred. This page must not be treated as a complete format contract.

Source: packages/engine/schemas/mat.schema.json · 51 branch-sensitive field records · 49 source-described. This source intentionally supersedes the frozen study boundary.

material · file · 51 fields

Field / branch	Type	Required	Default	Constraints	Description
# `$`	`object`	yes	`none`	`{"additionalProperties":false}`	Shared material asset file (.mat.json)
# `$.version`	`number`	yes	`none`	`none`	File format version
# `$.name`	`string`	yes	`none`	`none`	Human-readable material name
# `$.material`	`object`	yes	`none`	`{"additionalProperties":false}`	Material definition
# `$.material.type`	`enum (4)`	yes	`none`	`{"enum":["standard","physical","basic","toon"]}`	Material shading model
# `$.material.color`	`string`	no	`none`	`none`	Base color as CSS hex string (e.g. "#ff0000")
# `$.material.metalness`	`number`	no	`none`	`none`	Metalness factor 0–1 (standard/physical only)
# `$.material.roughness`	`number`	no	`none`	`none`	Roughness factor 0–1 (standard/physical only)
# `$.material.map`	`string`	no	`none`	`none`	Path to albedo/diffuse texture image
# `$.material.normalMap`	`string`	no	`none`	`none`	Path to normal map texture image
# `$.material.emissive`	`string`	no	`none`	`none`	Emissive color as CSS hex string
# `$.material.emissiveIntensity`	`number`	no	`none`	`none`	Emissive light intensity multiplier
# `$.material.emissiveMap`	`string`	no	`none`	`none`	Path to emissive map texture image
# `$.material.aoMap`	`string`	no	`none`	`none`	Path to ambient occlusion map texture image
# `$.material.lightMap`	`string`	no	`none`	`none`	Path to a baked lightmap texture (uses the mesh's second UV set). Applies the pre-baked GI/shadow result on top of the material.
# `$.material.lightMapIntensity`	`number`	no	`none`	`none`	Lightmap intensity multiplier (default 1).
# `$.material.roughnessMap`	`string`	no	`none`	`none`	Path to roughness map texture image
# `$.material.metalnessMap`	`string`	no	`none`	`none`	Path to metalness map texture image
# `$.material.opacity`	`number`	no	`none`	`none`	Opacity 0–1. Set transparent: true to enable
# `$.material.transparent`	`boolean`	no	`none`	`none`	Enable alpha blending for this material
# `$.material.side`	`enum (3)`	no	`none`	`{"enum":["front","back","double"]}`	Which face sides to render
# `$.material.flatShading`	`boolean`	no	`none`	`none`	Use flat (faceted) shading instead of smooth
# `$.material.clearcoat`	`object`	no	`none`	`{"additionalProperties":false}`	Clearcoat layer (physical only)
# `$.material.clearcoat.clearcoat`	`number`	yes	`none`	`none`	Clearcoat layer intensity 0–1
# `$.material.clearcoat.clearcoatRoughness`	`number`	no	`none`	`none`	Clearcoat roughness 0–1
# `$.material.clearcoat.clearcoatMap`	`string`	no	`none`	`none`	Path to clearcoat intensity map
# `$.material.clearcoat.clearcoatRoughnessMap`	`string`	no	`none`	`none`	Path to clearcoat roughness map
# `$.material.transmission`	`object`	no	`none`	`{"additionalProperties":false}`	Light transmission (physical only)
# `$.material.transmission.transmission`	`number`	yes	`none`	`none`	Transmission intensity 0–1 (glass, liquid)
# `$.material.transmission.ior`	`number`	no	`none`	`none`	Index of refraction (default 1.5)
# `$.material.transmission.thickness`	`number`	no	`none`	`none`	Volume thickness for refraction
# `$.material.transmission.attenuationColor`	`string`	no	`none`	`none`	Color absorbed over distance
# `$.material.transmission.attenuationDistance`	`number`	no	`none`	`none`	Distance at which attenuation color takes full effect
# `$.material.transmission.transmissionMap`	`string`	no	`none`	`none`	Path to transmission map
# `$.material.sheen`	`object`	no	`none`	`{"additionalProperties":false}`	Sheen layer (physical only)
# `$.material.sheen.sheen`	`number`	yes	`none`	`none`	Sheen intensity 0–1 (fabric, velvet)
# `$.material.sheen.sheenColor`	`string`	no	`none`	`none`	Sheen tint color
# `$.material.sheen.sheenRoughness`	`number`	no	`none`	`none`	Sheen roughness 0–1
# `$.material.sheen.sheenColorMap`	`string`	no	`none`	`none`	Path to sheen color map
# `$.material.sheen.sheenRoughnessMap`	`string`	no	`none`	`none`	Path to sheen roughness map
# `$.material.iridescence`	`object`	no	`none`	`{"additionalProperties":false}`	Iridescence thin-film (physical only)
# `$.material.iridescence.iridescence`	`number`	yes	`none`	`none`	Iridescence intensity 0–1 (soap bubbles, oil slick)
# `$.material.iridescence.iridescenceIOR`	`number`	no	`none`	`none`	Thin-film IOR (default 1.3)
# `$.material.iridescence.iridescenceThicknessRange`	`array`	no	`none`	`none`	Min/max thin-film thickness in nm
# `$.material.iridescence.iridescenceThicknessRange[0]`	`number`	yes	`none`	`none`	Missing source description
# `$.material.iridescence.iridescenceThicknessRange[1]`	`number`	yes	`none`	`none`	Missing source description
# `$.material.iridescence.iridescenceMap`	`string`	no	`none`	`none`	Path to iridescence intensity map
# `$.material.iridescence.iridescenceThicknessMap`	`string`	no	`none`	`none`	Path to iridescence thickness map
# `$.material.displacementMap`	`string`	no	`none`	`none`	Path to displacement/height map
# `$.material.displacementScale`	`number`	no	`none`	`none`	Displacement height multiplier
# `$.material.displacementBias`	`number`	no	`none`	`none`	Displacement offset