Lighting System

Glitter supports directional, point, spot, and (planned) area lights with physically-based units. The engine ships with a database of 21 real-world light source profiles ranging from candle flames to cinema fixtures.

Data source

All light source profiles are sourced from the Physically Based open database by Anton Palmqvist.

---

Scene node format

A light is added to a scene as a node with "type": "light":

{
  "name": "sun",
  "type": "light",
  "light": { ... },
  "transform": { "translate": [0.0, 4.0, 0.0] }
}

---

Light types

Directional light

Infinite-distance light (e.g. sun). No position — only direction matters. Uses cascaded shadow maps (4-cascade CSM).

"light": {
  "type":        "directional",
  "direction":   [-0.4, -1.0, -0.6],
  "color":       [1.0, 0.88, 0.70],
  "intensity":   400.0,
  "unit":        "lx",
  "temperature": 5778.0,
  "castShadow":  true
}

Point light

Omnidirectional light that falls off with distance. Uses cubemap shadows.

"light": {
  "type":        "point",
  "color":       [1.0, 0.6, 0.2],
  "intensity":   800.0,
  "unit":        "lm",
  "temperature": 2700.0,
  "radius":      5.0,
  "sourceSize":  [3.0],
  "castShadow":  true
}

Spot light

Cone-shaped light with inner/outer falloff angles.

"light": {
  "type":           "spot",
  "color":          [1.0, 1.0, 1.0],
  "intensity":      12.0,
  "radius":         10.0,
  "cone_inner_deg": 15.0,
  "cone_outer_deg": 30.0,
  "castShadow":     true
}

---

Field reference

Field	Applies to	Default	Description
type	all	—	"directional", "point", or "spot"
color	all	[1,1,1]	Linear RGB colour (0–1 each channel)
intensity	all	1.0	Brightness value — meaning depends on unit
unit	all	"artist"	Physical unit — see Physical light units
temperature	all	—	Correlated colour temperature in Kelvin — overrides color when set
direction	directional	[-0.4,-1,-0.6]	World-space direction vector
radius	point, spot	5.0	Influence radius / attenuation falloff distance
cone_inner_deg	spot	0.0	Inner (full-brightness) cone half-angle in degrees
cone_outer_deg	spot	90.0	Outer (falloff-to-zero) cone half-angle in degrees
sourceSize	point, area	—	Physical emitter size in cm — [radius] for point, [width, height] for area
angle	directional, area	—	Angular diameter in degrees (e.g. sun ≈ 0.53°) or beam spread
castShadow	all	false	Whether the light casts shadows

---

Physical light units

When "unit" is set, the engine converts the raw intensity to its internal representation:

Unit	Meaning	Conversion
"artist"	Engine-scaled (no conversion)	Pass-through
"lm"	Lumens — total luminous flux	Point: $\text{candela} = \frac{\text{lm}}{4\pi}$; Spot: adjusted for cone solid angle
"lx"	Lux — illuminance (lm/m²)	Pass-through — used directly for directional lights
"cd/m2"	Nits — luminance	Pass-through

Spot light conversion

For spot lights, luminous flux is converted to candela accounting for the cone's solid angle:

$\text{candela} = \frac{\text{lm}}{2\pi \times (1 - \cos(\theta / 2))}$

where $\theta$ is the full outer cone angle in radians.

---

Colour temperature

When temperature is specified (in Kelvin), the engine converts it to an RGB colour using the Tanner Helland approximation, replacing the color field. This is useful for matching real-world light sources.

Temperature	Light source	Appearance
1,850 K	Candle flame	Deep orange-red
2,200 K	Warm incandescent bulb	Orange
2,700 K	Soft white LED	Warm white
3,200 K	Halogen / tungsten	Yellowish white
5,000 K	Direct sunlight	Neutral white
5,778 K	Sun (astronomical)	Slightly warm white
6,500 K	Overcast sky	Cool white
10,000+ K	Blue sky	Bluish

The valid range is 1,000–40,000 K.

---

Light source profiles

The engine ships with physically-based light profiles in engine_defaults/lights/physicallybased/. These can be referenced from the lights:// scheme.

Profile format

{
  "description": "Physically Based — Sun",
  "type":        "directional",
  "unit":        "lx",
  "color":       [1.0, 0.877, 0.822],
  "temperature": 5778.0,
  "intensity":   400.0,
  "angle":       0.5332,
  "castShadow":  true,
  "sources":     [ ... ],
  "_tags":       ["Natural"]
}

Some profiles include variants — alternative configurations of the same fixture:

{
  "description": "Physically Based — Household Light Bulb",
  "type":        "point",
  "unit":        "lm",
  "temperature": 2200.0,
  "intensity":   400.0,
  "variants": [
    {
      "name":        "5000 K",
      "temperature": 5000.0,
      "intensity":   400.0
    }
  ]
}

Natural light sources

Profile	Type	Unit	Intensity	Temp
Sun	directional	lx	400	5,778 K
Moon	directional	lx	0.27	4,100 K
Sky	directional	lx	—	12,000 K
Candle flame	point	lm	13	1,850 K
Firefly	point	lm	0.05	5,600 K
Kerosene lamp	point	lm	100	2,200 K

Artificial light sources

Profile	Type	Unit	Intensity	Temp
Household light bulb	point	lm	400	2,200 K
Fluorescent tube	area	lm	2,850	6,500 K
Street light	point	lm	16,000	4,000 K
Car headlight	spot	lm	3,200	6,000 K
Photo flash	point	lm	190,000	5,500 K
Digital display	area	cd/m²	500	6,500 K

Cinema / studio fixtures

Profile	Type	Unit	Intensity	Temp
ARRI SkyPanel X	area	lm	48,000	1,500–5,600 K
ARRI SkyPanel S60 Pro	area	lm	9,350	2,800 K
ARRI M-Series M8	point	lm	68,500	5,600 K
Aputure Storm 1200x	point	lm	171,000	5,600 K
Aputure Amaran 300c	point	lm	4,700	2,500 K
Kino Flo Mimik 120	area	lm	9,300	2,700 K
ROE Carbon CB5 MkII	area	cd/m²	5,000	6,500 K