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.
Whether this component participates in simulation and rendering. When false,
the GameObject skips its update/updateRender and the scene's
render collectors (mesh renderers, camera, lights, …) ignore it — the
component stays attached and keeps its state, like Unity's Behaviour.enabled
/ Renderer.enabled. Defaults to true.
The owning GameObject; assigned by addComponent before onAttach runs.
True between onAttach and onDetach — i.e. while this component sits on a GameObject that is part of a live Scene. Managed by GameObject. Internal — do not set directly.
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).
Connect to a Signal with automatic disconnect when this component is removed from its GameObject — the safe default for cross-object listening, so a destroyed component never leaks into (or gets called by) a signal it once observed. Typically called from onAttach:
onAttach(): void {
const health = this.gameObject.getComponent(Health)!;
this.listen(health.died, () => this.playDeathEffect());
}
The signal to connect to.
Listener, forwarded to Signal.connect.
Optionalopts: SignalConnectOptionsSee SignalConnectOptions.
The unsubscribe function, for listeners that also want to disconnect early; calling it is optional and idempotent.
Disconnect every signal connection made through listen. Called by GameObject.removeComponent after onDetach (so it runs even when a subclass overrides onDetach without calling super). Internal — do not call directly.
Called when the component joins a live scene — from addComponent when the
GameObject is already in a scene, otherwise when the GameObject is added to
one. this.gameObject.scene (and scene.engine) is always set here.
Override to acquire references to siblings/children or initialize resources.
Called when the component leaves the scene — removed via GameObject.removeComponent, or its GameObject removed from the scene. Override to release resources or unsubscribe from events.
Called every frame by the GameObject's update traversal.
Frame delta time in seconds.
Called when this component's GameObject begins touching another body, with the GameObject it collided with. Dispatched by the physics system after each world step (only while playing), so handlers may freely mutate the scene. Requires a physics body (RigidBody / CharacterBody) on the object.
The other GameObject involved in the contact.
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.