dh.material

Extension: .dh-mat — Type ID: dh.material

Materials define surface appearance — textures, PBR properties, tint, and transparency. DigitalHeaven materials use semantic properties that map to platform-specific shaders at build time.

Properties

Property	Type	Required	Description
$type	"dh.material"	no	Type identifier
name	string	no	Display name
description	string	no	Description
inherits	string	no	Barcode of the material to inherit from
textures	object	no	Texture channel assignments
properties	object	no	Float material properties
tint	color	no	Base color multiplier (RGBA)
alphaMode	string	no	Alpha rendering mode
alphaCutoff	float	no	Cutoff threshold for "mask" mode (default: 0.5)

The type is inferred from the file extension — $type is not needed in source files. The compiler adds it automatically during builds.

Full Example

glass.dh-mat

{
  "name": "Glass",
  "textures": {
    "baseColor": "textures/glass-albedo.png",
    "normal": "textures/glass-normal.png",
    "metallicRoughness": "textures/glass-pbr.png"
  },
  "properties": {
    "metallic": 0.0,
    "smoothness": 0.95
  },
  "tint": [0.9, 0.95, 1.0, 0.5],
  "alphaMode": "blend"
}

Texture Channels

The textures object maps semantic channel names to texture file paths:

Channel	Description
baseColor	Albedo / diffuse color
normal	Normal map
metallicRoughness	Combined metallic-roughness (glTF style)
occlusion	Ambient occlusion
emissive	Emissive / glow map

Paths are relative to the pallet root, or barcodes for cross-pallet references.

@channel Extraction

You can reference individual channels from packed textures using @channel syntax:

skin.dh-mat

{
  "textures": {
    "metallic": "textures/packed-orm.png@b",
    "roughness": "textures/packed-orm.png@g",
    "occlusion": "textures/packed-orm.png@r"
  }
}

The compiler extracts the specified channel at build time and generates a separate grayscale texture. Valid channels: r, g, b, a.

See dh.texture for more on channel operations.

Float Properties

Property	Range	Description
metallic	0.0 – 1.0	How metallic the surface is
roughness	0.0 – 1.0	Surface roughness (1.0 = fully rough)
smoothness	0.0 – 1.0	Inverse of roughness (1.0 = mirror-smooth)
normalScale	any	Normal map intensity multiplier
occlusionStrength	0.0 – 1.0	Ambient occlusion strength
emissiveIntensity	any	Emissive brightness multiplier

Use either roughness or smoothness, not both. They’re inverses of each other.

Tint

The tint property is an RGBA color multiplier applied to the base color texture. If there’s no base color texture, tint defines the solid color.

finalColor = texture * tint

Two formats:

Array (RGBA floats, 0–1):

{ "tint": [1.0, 0.5, 0.5, 0.8] }

Hex string (RGB or RGBA):

{ "tint": "#FF8080CC" }

{ "tint": "#FF8080" }

Hex without alpha defaults to fully opaque (FF).

Alpha Modes

The alphaMode property controls transparency rendering. Follows the glTF specification.

Mode	Description
"opaque"	Fully opaque, alpha is ignored (default)
"mask"	Binary transparency — pixels are either fully visible or fully invisible based on alphaCutoff
"blend"	Smooth alpha blending with the background

Cutout (foliage, hair cards):

{
  "alphaMode": "mask",
  "alphaCutoff": 0.5
}

Transparent (glass, water):

{
  "alphaMode": "blend",
  "tint": [1.0, 1.0, 1.0, 0.5]
}

Auto-Inference

When alphaMode is omitted, platform loaders may auto-infer:

• Unity: If tint alpha is less than 1.0, automatically uses blend mode
• To override, explicitly set alphaMode

Unity Platform Overrides

For Unity-specific shader settings, use platform overrides with raw shader property names:

materials/glass.dh-mat                      # Universal material
platforms/unity/materials/glass.dh-mat       # Unity-specific overrides

Unity override example:

platforms/unity/materials/glass.dh-mat

{
  "shader": "Standard",
  "properties": {
    "_Metallic": 0.0,
    "_Mode": "transparent"
  },
  "colors": {
    "_Color": [1.0, 1.0, 1.0, 0.5]
  }
}

The _Mode property accepts string values:

Value	Description
"opaque"	Standard opaque rendering
"cutout"	Binary transparency using alpha cutoff
"fade"	Alpha blending (fades out specular/reflections)
"transparent"	Alpha blending (preserves specular/reflections)

Numeric values (0–3) also work.