Lighting

Light Types

• Directional lights are best for sun and moon sources.
• Point lights are local omni lights.
• Spot lights are cones for lamps, flashlights, and highlights.
• Rectangle and disc area lights create broad soft sources and use Three RectAreaLight support.

IES profile references exist as schema slots. Runtime IES sampling is metadata-only; author profiles only where tooling requires the reference to be preserved.

Shadows

Quality determines the shadow strategy a tier requests. The canonical resolver (web_client/spa/src/render/shadows/shadowStrategyResolver.ts) then decides what actually runs and records a typed receipt for any downgrade:

• Low: one directional PCF shadow.
• Medium: one directional plus two point shadows.
• High: requests cascaded shadow maps (CSM) with three directional cascades plus a point shadow budget.
• Ultra and Cinematic: request four cascades and PCSS-style filtering for directional/spot lights.

Live shadow truth today: standard directional shadow maps with PCF/PCSS filtering are the running high-end path on both backends. WebGPU renders the primary directional with standard (non-cascaded) shadows by design (shouldUseWebGpuCsm returns false, quarantined against the three r184 WGSL CSM bug). The resolver also currently downgrades WebGL CSM requests to standard maps with a degraded receipt (webgl_csm_quarantined_r184) until the WebGL CSM path proves clean first-frame pixels; the CSM addon manager (cascadedShadowMaps.ts, WebGL only) is retained behind that gate. Variance shadow maps (VSM) are an unsupported-typed request that resolves to standard with an unsupported receipt, never a faked pass.

Point lights keep the standard point-shadow filter when PCSS is requested. The renderer reports this as a profiler label so the fallback is visible.

Contact shadows/GTAO are not active runtime tier features until both WebGL and WebGPU have pixel-proven implementations.

Budgets

The renderer prioritizes shadow-casting lights by type, distance, and importance. Lights over the active quality budget can still render without shadows or be suppressed. Suppression reasons appear in the profiler.

Image-Based Lighting

Environment maps and reflection probes feed PBR reflections. WebGL uses PMREM; WebGPU uses Three's TSL environment PMREM path. Reflection probes can be box or sphere shaped, and baked probe textures are stored as workspace texture assets.