Skip to main content

Material Descriptors

A material descriptor is a JSON file in the materials/ directory. It binds a shader and PBR property values together, and is referenced by glitter_primitive model descriptors via materials:// URIs.

The engine ships with 100+ physically-based material presets (metals, dielectrics, organics, liquids, skin tones) sourced from real-world measured data, plus a set of prototype materials for scene layout.

Format overview​

Glitter uses a v2 flat format where all scalar factors live at the top level and textures live in a "textures" block. This mirrors the glTF 2.0 material model extended with all supported KHR extensions plus engine-specific features like subsurface scattering.

materials/example.json
{
  "description":      "Human-readable label",
  "shader":           "shaders://pbr.json",

  "baseColorFactor":  [1.0, 1.0, 1.0, 1.0],
  "metallicFactor":   0.0,
  "roughnessFactor":  0.9,
  "emissiveFactor":   [0.0, 0.0, 0.0],

  "alphaMode":        "OPAQUE",
  "alphaCutoff":      0.5,

  "textures": {
    "baseColor":   "textures://wall_albedo.ktx2",
    "metalRough":  "textures://wall_mr.ktx2",
    "normal":      "textures://wall_normal.ktx2",
    "occlusion":   "textures://wall_ao.ktx2",
    "emissive":    "textures://wall_emissive.ktx2"
  }
}

Core PBR fields​

FieldDefaultDescription
shader—shaders:// URI to the shader descriptor (required)
description—Human-readable label
baseColorFactor[1,1,1,1]RGBA tint — multiplied with baseColor texture when present
metallicFactor1.00 = dielectric, 1 = fully metallic
roughnessFactor1.00 = mirror, 1 = fully rough
emissiveFactor[0,0,0]Emissive RGB multiplier
alphaMode"OPAQUE""OPAQUE", "MASK" (hard cutout), or "BLEND" (translucent)
alphaCutoff0.5Alpha threshold for MASK mode

Texture block​

All textures are specified inside a "textures" object using textures:// URIs:

"textures": {
  "baseColor":          "textures://albedo.ktx2",
  "metalRough":         "textures://mr.ktx2",
  "normal":             "textures://normal.ktx2",
  "occlusion":          "textures://ao.ktx2",
  "emissive":           "textures://emissive.ktx2",
  "specular":           "textures://specular.ktx2",
  "specularColor":      "textures://specular_color.ktx2",
  "clearcoat":          "textures://clearcoat.ktx2",
  "clearcoatRoughness": "textures://clearcoat_rough.ktx2",
  "clearcoatNormal":    "textures://clearcoat_normal.ktx2",
  "transmission":       "textures://transmission.ktx2"
}

All texture fields are optional. When a texture is absent, the corresponding scalar factor is used as a constant value.

Extended PBR properties​

These mirror the standard glTF 2.0 KHR material extensions supported by the engine.

KHR_materials_emissive_strength​

"emissiveStrength": 5.0

Multiplier on top of emissiveFactor for HDR emissive surfaces (default 1.0).

KHR_materials_ior​

"ior": 1.52

Index of refraction (default 1.5). Affects Fresnel reflectance at normal incidence. Common values:

MaterialIOR
Air1.0
Water1.333
Glass1.52
Diamond2.42
Skin1.4

KHR_materials_specular​

"specularFactor":      1.0,
"specularColorFactor": [1.0, 1.0, 1.0]

KHR_materials_clearcoat​

"clearcoatFactor":          0.5,
"clearcoatRoughnessFactor": 0.1

Adds a second specular lobe for clear-coated surfaces (car paint, varnish).

KHR_materials_transmission​

"transmissionFactor": 1.0

Makes the surface transmit light (glass, water). Set alphaMode to "BLEND" for correct rendering.

KHR_materials_volume​

"thicknessFactor":     0.5,
"attenuationDistance":  2.0,
"attenuationColor":    [0.8, 1.0, 0.8]

Controls light absorption through a volume. Used with transmission for coloured glass, liquids, etc.

KHR_materials_dispersion​

"dispersion": 64.0

Chromatic dispersion — splits transmitted light into a rainbow. Higher values = stronger effect. Used for glass, diamonds, water.

Subsurface scattering​

Engine-specific extension for skin, wax, marble, and other translucent materials:

"scatteringDistance":   0.253,
"scatteringColor":     [0.482, 0.169, 0.109],
"scatteringAnisotropy": 0.0
FieldDefaultDescription
scatteringDistance0.0Mean free path — how far light travels inside the material
scatteringColor[1,1,1]Colour tint of the scattered light
scatteringAnisotropy0.0Directionality: 0 = isotropic, positive = forward scatter, negative = back scatter

Material inheritance​

A material can inherit from a base material using the "base" field. The child overrides any scalar values from the parent, up to 4 levels deep. Textures are not inherited — only the leaf material's textures are used.

materials/polished_gold.json
{
  "base":            "materials://physicallybased/gold.json",
  "roughnessFactor": 0.05
}

This inherits gold's baseColorFactor and metallicFactor but overrides roughness.

Examples​

Pure metal (gold)​

materials/physicallybased/gold.json
{
  "description":     "Physically Based — Gold",
  "shader":          "shaders://pbr.json",
  "baseColorFactor": [1.059, 0.773, 0.307, 1.0],
  "metallicFactor":  1.0,
  "roughnessFactor": 0.0
}

Transparent dielectric (glass)​

materials/physicallybased/glass.json
{
  "description":       "Physically Based — Glass",
  "shader":            "shaders://pbr.json",
  "baseColorFactor":   [1, 1, 1, 1.0],
  "metallicFactor":    0.0,
  "roughnessFactor":   0.0,
  "ior":               1.52,
  "transmissionFactor": 1.0,
  "dispersion":        64.0,
  "alphaMode":         "BLEND"
}

Subsurface scattering (skin)​

materials/physicallybased/skin_iii.json
{
  "description":        "Physically Based — Skin III",
  "shader":             "shaders://pbr.json",
  "baseColorFactor":    [0.623, 0.433, 0.343, 1.0],
  "metallicFactor":     0.0,
  "roughnessFactor":    0.5,
  "ior":                1.4,
  "scatteringDistance":  0.253,
  "scatteringColor":    [0.482, 0.169, 0.109]
}

Textured prototype​

materials/prototypes/green_shiny.json
{
  "description":     "Green shiny — polished metallic surface",
  "shader":          "shaders://pbr.json",
  "baseColorFactor": [1.0, 1.0, 1.0, 1.0],
  "metallicFactor":  0.85,
  "roughnessFactor": 0.1,
  "textures": {
    "baseColor": "textures://prototypes/green/texture_09.ktx2"
  }
}

Physically-based material database​

The engine ships with 100+ measured material presets in engine_defaults/materials/physicallybased/. These are ready to use via materials://physicallybased/ URIs.

Data source

All physically-based presets are sourced from the Physically Based open database by Anton Palmqvist.

Metals​

Aluminum, Beryllium, Brass, Cesium, Chromium, Cobalt, Copper, Germanium, Gold, Iridium, Iron, Lead, Lithium, Magnesium, Manganese, Mercury, Molybdenum, Nickel, Palladium, Platinum, Potassium, Rubidium, Silicon, Silver, Sodium, Stainless steel, Titanium, Tungsten, Vanadium, Zinc, plus coloured variants (aluminum anodized red, titanium anodized).

Dielectrics & crystals​

Amber, Diamond, Glass, Pearl, Porcelain, Quartz, Sapphire, Terracotta, plus plastics (acrylic, PC, PET, PP, PUR, PVC).

Organics & foods​

Banana, Blood, Bone, Carrot, Charcoal, Chocolate, Coffee, Egg shell (brown/white), Grass, Honey (liquid/crystallized), Ketchup, Lemon, Milk, Orange, Toothpaste.

Construction & surfaces​

Asphalt, Blackboard, Brick, Cardboard, Concrete, Marble, Office paper, Polystyrene foam, Salt, Sand, Snow, Toilet paper, Tire, Whiteboard.

Liquids & transparent​

Cooking oil, Gasoline, Ice, Petroleum, Soap bubble, Water.

Human​

Skin I–VI (Fitzpatrick scale with per-type scattering parameters), Eye (cornea, lens, sclera).

Reference targets​

Gray card, MIT Black, Musou Black, Spectralon, Toner black.

Special surfaces​

Car paint (metallic flake), Aluminum anodized red, Titanium anodized.

Prototype material catalogue​

Ready-made materials for scene layout and testing. All live under materials://prototypes/.

Orange​

FileBase textureNotes
orange_grid.jsonOrange/texture_02.pngGeneral structural surface
orange_grid_marker.jsonOrange/texture_07.pngGrid with marker squares
orange_metal.jsonOrange/texture_02.pngMetallic finish (metallicFactor: 1.0)
orange_panel.jsonOrange/texture_06.pngFlat panel / wall tile
orange_caution.jsonOrange/texture_11.pngHazard stripe
orange_stair.jsonOrange/texture_11.pngStaircase tread surface
orange_stair_side.jsonOrange/texture_02.pngStaircase riser / side face
orange_marker.jsonOrange/texture_07.pngLow-visibility marker

Green​

FileBase textureNotes
green_grid.jsonGreen/texture_02.pngGeneral structural surface
green_panel.jsonGreen/texture_06.pngFlat panel / wall tile
green_marker.jsonGreen/texture_07.pngMarker squares
green_shiny.jsonGreen/texture_02.pngShiny finish (roughnessFactor: 0.1)

Purple​

FileBase textureNotes
purple_grid.jsonPurple/texture_02.pngGeneral structural surface
purple_wall.jsonPurple/texture_01.pngWall tile with label
purple_marker.jsonPurple/texture_07.pngMarker squares
purple_shiny.jsonPurple/texture_02.pngShiny finish

Red​

FileBase textureNotes
red_grid.jsonRed/texture_02.pngGeneral structural surface
red_brick.jsonRed/texture_01.pngBrick-like wall tile
red_metal.jsonRed/texture_02.pngMetallic finish
red_marker.jsonRed/texture_07.pngMarker squares

Light / Dark​

FileBase textureNotes
light_floor.jsonLight/texture_01.pngPale stone / floor tile
light_trim.jsonLight/texture_02.pngTrim / edge marker
dark_ground.jsonDark/texture_01.pngDark ground / base surface
dark_wall.jsonDark/texture_02.pngDark wall surface

Relationship to model descriptors​

glitter_primitive model descriptors reference materials by URI:

"glitter_primitive": {
  "materials": [
    "materials://prototypes/orange_grid.json",
    "materials://prototypes/orange_metal.json"
  ],
  "elements": [ ... ]
}

See Model Descriptors for the full primitive format including per-face material assignment.

For gltf models, materials are embedded in the glTF asset — no separate material descriptor is used.