Optional initial property values. Omit to construct with defaults (white, intensity 1, 3 cascades) and set fields afterward.
Stable identity for this component, unique within a session. Auto-generated for runtime-created components; the editor overwrites it with a persistent id when projecting a saved document so references survive save / load / undo.
The owning GameObject; assigned by addComponent before onAttach runs.
Linear RGB color multiplier.
Scalar intensity multiplier applied to color. Under the physical-units convention this is illuminance in lux (a directional source's intensity already is illuminance — see lux).
Number of cascade splits used for shadow mapping.
Directional shadow mode.
'cascade' (default): classic cascaded shadow maps — frustum-fit,
camera-centered bounding spheres, selected by view-space depth split.'clipmap': UE5-style virtual-shadow-map clipmap (Phase 1). N concentric,
camera-position-centered, texel-snapped ortho levels, each covering 2× the
world extent of the level below, selected by which level's box contains the
receiver. Rotating the camera never changes a level's size or texel density
(tilt-stable), and resolution falls off with distance automatically. See
computeClipmapMatrices and TODO/virtual-shadow-maps.md.Clipmap: number of concentric levels (each 2× the extent of the prior).
Capped to MAX_SHADOW_LEVELS (8) by the shadow plumbing.
Clipmap: world-space extent (full box width) of level 0 — the finest,
camera-hugging level. Level i covers clipmapLevel0Extent · 2^i.
Re-latch threshold (radians) for the cascade shadow map's light direction, specified for a sun at its zenith. See computeCascadeMatrices.
A slowly-rotating sun (day/night cycle) otherwise re-rasterizes the shadow map every frame, which boils the soft PCSS penumbra even with a perfectly still camera. Latching keeps the cascade matrices bit-identical between re-latches, so the shadow map doesn't change. A re-latch steps the shadow by roughly this angle's worth of movement.
The effective threshold is scaled down as the sun drops toward the horizon (see computeCascadeMatrices), so the on-ground shadow step stays roughly constant instead of growing chunky at a low sun. Lower = more frequent, smaller steps; higher = rarer, larger steps. 0 disables latching.
Practical-split blend for the cascade partitioning, in [0, 1]. 1 is fully
logarithmic (tight near cascades — most shadow resolution where the eye
needs it), 0 is fully uniform. See computeCascadeSplitDepths.
Default 0.75.
The simulation clock of the scene this component belongs to. Read inside
update (or any time after the GameObject is added to a scene) for
absolute time, frame count, FPS, and timeScale-aware delta — e.g.
this.time.elapsed, this.time.delta, this.time.frameCount.
this.time.delta equals the dt argument passed to update, so
components can ignore that argument entirely and pull everything from here.
Illuminance in lux — an alias of intensity for symmetry with the
lumens accessors on point/spot lights. A directional light's intensity is
already illuminance, so no conversion is needed (directSun ≈ 100 000 lux).
Called once when the component is added to a GameObject. Override to acquire references to siblings/children or initialize resources.
Called once when the component is removed from its GameObject. Override to release resources or unsubscribe from events.
Called every frame by the GameObject's update traversal.
Frame delta time in seconds.
Called every frame by the GameObject's render traversal, after update and any input/controller mutations to the transform. Override to refresh per-frame state that render passes consume (e.g. Camera recomputes its cached view/projection matrices here).
Active render context (provides canvas width/height etc.).
World-space forward direction of the light — the GameObject's local -Z (Vec3.FORWARD) transformed into world space and normalized.
The light stores no direction of its own: orient it by rotating the owning
GameObject (e.g. go.rotation = Quaternion.fromForward(dir)), exactly like
SpotLight / PointLight. So rotating the transform — in code
or via the editor gizmo — is what aims the sun.
Computes per-cascade view-projection matrices for the cascaded shadow map.
Each cascade is fit to a bounding sphere centered on the camera position, not the view frustum. Anchoring on the camera makes the cascades fully independent of view direction: rotating the camera leaves every cascade unchanged, and casters beside or behind the camera stay inside the shadow map — so their shadows no longer pop in and out as the camera turns. The sphere radius reaches the far frustum corners, so every visible receiver is still covered. Texel-snapping keeps the map stable as the camera translates.
Camera whose view is being shadowed.
OptionalshadowFar: numberOptional override for the shadow-receiving distance; defaults to camera.far.
OptionaldepthBounds: { near: number; far: number } | nullOptional SDSM view-linear depth bounds of the visible
scene. When supplied, the cascade range is clamped to [near, far] instead
of [camera.near, shadowFar], so the cascades hug the on-screen depth slab
and gain a large texel-density boost. See SdsmFeature.
One CascadeData per cascade, in near-to-far order.
Computes clipmap level view-projection matrices for the virtual-shadow-map
shadow mode (shadowMode === 'clipmap').
Produces clipmapLevels concentric, camera-position-centered
orthographic levels in light space. Level i is a square box of world
extent clipmapLevel0Extent · 2^i — so each level covers 2× the area of the
level below and resolution falls off with distance automatically, with no
frustum fit and no view dependence. Each level is snapped to its own
world-space texel grid (only while the light is static — same rule as
computeCascadeMatrices), so translating the camera slides the box in
whole-texel steps and rotating the camera leaves every level bit-identical.
That tilt-stability is the whole point of the mode.
Returned as CascadeData[] (same shape as the cascade path) so the
shadow render + sampling pipeline is reused unchanged; splitFar carries the
level's selection radius. Levels are ordered finest (0) to coarsest.
Camera the clipmap is centered on (uses position only).
Shadow-map resolution per level (defaults to 2048, matching
the shadow pass) — sets each level's texelWorldSize.
Directional light component representing the sun.
Provides direction/color/intensity for the deferred lighting pass and computes cascade shadow-map matrices for the cascade shadow render pass. Only one DirectionalLight is typically active per scene (selected via Scene.findSunLight).
The light is aimed by its GameObject's transform (local -Z), like SpotLight / PointLight; see worldDirection. Construct with no arguments and set fields, or pass DirectionalLightOptions.