---
title: "Lighting"
description: "Gessa supports directional, point, spot, rectangle area, and disc area lights. Lighting is projected from ECS light components into the runtime `SceneSnapshot`."
engineVersion: v1.0.234
date: 2026-09-28
license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/."
canonical: https://gessa.ai/docs/creator/graphics/lighting/
---
# Lighting

Gessa supports directional, point, spot, rectangle area, and disc area lights. Lighting is projected from ECS light components into the runtime `SceneSnapshot`.

## 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.