Lights & shadows

Lights are declared on an entity via the light schema (packages/engine/src/scene/schema/light.ts).

The four light types.

Types

type	Behavior	Key fields
directional	Parallel rays (a sun)	color, intensity
point	Omnidirectional from a point	color, intensity, distance (0 = infinite)
spot	A cone	color, intensity, distance, angle (radians), penumbra (0–1)
hemisphere	Sky/ground gradient ambient	color (sky), groundColor, intensity

distance (point/spot) caps the light’s range — 0 means infinite. A spot’s angle is the cone half-angle in radians, and penumbra softens the cone edge (0–1). The schema rejects a spot angle that isn’t positive.

Shadows

A light casts shadows via the shadow schema (packages/engine/src/scene/schema/shadow.ts):

• enabled — does this light cast shadows.
• mapSize — shadow map resolution in pixels (e.g. 1024, 2048).
• camera — { left, right, top, bottom } frustum bounds (directional lights).
• radius — blur radius for soft shadows.
• bias — offset to reduce shadow acne.

The renderer uses PCF soft shadow maps globally (see Rendering). An entity’s own shadow cast / receive flags are set in its shadow config.

One strong key light

For most scenes a single directional key light (with a tuned shadow-camera frustum) plus a hemisphere or ambient fill reads better and costs less than many point lights.

See also

• Environment — ambient, fog, and image-based lighting.
• Rendering — the shadow-map renderer settings.
• Scene Schema reference — every light/shadow field.