Lighting Components

DirectionalLightComponent

Simulates an infinitely distant light source with parallel rays — typically used for sun or moonlight.

Property	Type	Default	Description
`direction`	Vec3	`{x:0, y:-1, z:0}`	Direction vector pointing FROM the light source toward the scene
`color`	Vec3	`{x:1, y:1, z:1}`	RGB color in linear color space (0-1 per channel)
`intensity`	Float	`1.0`	Light intensity multiplier. Supports HDR values > 1.0. Range: 0-10
`casts_shadows`	Bool	`true`	Whether this light casts shadows
`shadow_resolution`	UInt	`2048`	Shadow map resolution in pixels. Range: 512-4096

Direction Examples

Direction	Meaning
`{x:0, y:-1, z:0}`	Straight down (midday sun)
`{x:-0.5, y:-0.7, z:-0.5}`	Angled afternoon sun
`{x:0, y:-0.3, z:-0.95}`	Low sunset angle

Example: Warm Sunset Light

{
  "op": "CreateDirectionalLight",
  "params": {
    "entity_name": "SunsetLight",
    "direction": [-0.3, -0.4, -0.85],
    "color": [1.0, 0.85, 0.6],
    "intensity": 1.5,
    "casts_shadows": true,
    "shadow_resolution": 2048
  }
}

PointLightComponent

An omnidirectional light that emits from a single point and attenuates with distance.

Property	Type	Default	Description
`color`	Vec3	`{x:1, y:1, z:1}`	RGB color in linear color space (0-1 per channel)
`intensity`	Float	`1.0`	Light intensity multiplier. Supports HDR values > 1.0. Range: 0-10
`radius`	Float	`10.0`	Falloff radius in world units. Light reaches zero at this distance. Range: 0.1-100
`casts_shadows`	Bool	`false`	Whether this light casts shadows (expensive for point lights)

Example: Torch Light

{
  "op": "CreatePointLight",
  "params": {
    "entity_name": "Torch",
    "position": [5, 3, -2],
    "color": [1.0, 0.7, 0.3],
    "intensity": 2.0,
    "radius": 15
  }
}

Lighting Presets

The ApplyLightingPreset operation provides quick lighting setups:

Preset	Description
`OutdoorSunny`	Warm directional sun (intensity 1.5, shadows on)
`OutdoorCloudy`	Cool overcast sky (intensity 0.8, no shadows)
`IndoorBright`	Two white ceiling point lights (intensity 1.2 each)
`IndoorDim`	Two warm ambient point lights (intensity 0.4 each)
`StudioThreePoint`	Directional key + point fill + point rim lights
`NightMoonlight`	Blue moonlight (intensity 0.15, shadows on)

{
  "op": "ApplyLightingPreset",
  "params": { "preset": "StudioThreePoint" }
}

Multi-light presets create a parent group entity — delete the group to remove all preset lights at once.

Rendering Pipeline

Razorbill uses a modern PBR rendering pipeline:

Cook-Torrance BRDF

The GGX microfacet distribution with Fresnel-Schlick approximation and energy-conserving diffuse/specular split. Materials use the metallic/roughness workflow.

Cascaded Shadow Maps

Directional lights use 4-cascade shadow mapping with Practical Split Scheme for balanced near/far coverage:

5-tap PCF soft shadow edges
Front-face culling to reduce shadow acne
Configurable resolution (512-4096 per cascade)

Image-Based Lighting (IBL)

HDR environment maps provide ambient lighting:

Irradiance convolution — Diffuse ambient from environment
GGX pre-filtered specular — 5 mip levels for roughness-dependent reflections
BRDF LUT — Split-sum integration lookup for energy conservation
Separate metal/dielectric ambient paths for correct Fresnel behavior

Load HDR environment maps through the editor's environment settings.

GPU-Driven Rendering

The renderer uses modern GPU-driven architecture:

Argument buffers for bindless resource access
Indirect draw buffers — CPU builds commands, GPU consumes
Instanced batching — N instances of M unique meshes
Triple-buffered transform and material uploads with semaphore synchronization
Two-stage material lookup — instance_id → material_id → MaterialData