godot-3d-lighting

What this skill does

# 3D Lighting

Expert guidance for realistic 3D lighting with shadows and global illumination.

## NEVER Do

- **NEVER use VoxelGI without setting a proper extents** — Unbound VoxelGI tanks performance. Always set `size` to tightly fit your scene.
- **NEVER enable shadows on every light** — Each shadow-casting light is expensive. Use shadows sparingly: 1-2 DirectionalLights, ~3-5 OmniLights max.
- **NEVER forget directional_shadow_mode** — Default is ORTHOGONAL. For large outdoor scenes, use PARALLEL_4_SPLITS for better shadow quality at distance.
- **NEVER use LightmapGI for fully dynamic scenes** — Lightmaps are baked. Moving geometry won't receive updated lighting. Use VoxelGI or SDFGI instead.
- **NEVER set omni_range too large** — Light attenuation is quadratic. A range of 500 affects 785,000 sq units. Keep range as small as visually acceptable.
- **NEVER hide a Light node using the Visible property to exclude it from a Lightmap bake** — Hiding a light has no effect on the baker. You must change the light's Bake Mode to Disabled.
- **NEVER use VoxelGI with paper-thin walls** — VoxelGI evaluates lighting using a 3D grid. Thin walls (less than one voxel thick) will cause severe light leaking. Seal your geometry or place hidden thick MeshInstance3D blocks around the exterior.
- **NEVER leave shadow bias at default for cascades** — Default bias often causes Peter Panning or light leaking at split transitions. Tune bias per-light based on your scene's scale.
- **NEVER bake LightmapGI without a Denoiser** — Godot's baked lightmaps are noisy by default. Use OIDN or JNLM (in Project Settings) for professional results.
- **NEVER use real-time SDFGI on Mobile/Compatibility renderers** — It is a Forward+ exclusive feature. Use fake GI bounce lights for lower-end platforms.
- **NEVER use 'Update Continuity' in ReflectionProbes for performance** — Keep ReflectionProbes on 'Update Once' and trigger manual updates only when necessary.

---

## Available Scripts

> **MANDATORY**: Read the appropriate script before implementing the corresponding pattern.

### [day_night_cycle.gd](scripts/day_night_cycle.gd)
Dynamic sun position and color based on time-of-day. Handles DirectionalLight3D rotation, color temperature, and intensity curves. Use for outdoor day/night systems.

### [light_probe_manager.gd](scripts/light_probe_manager.gd)
VoxelGI and SDFGI management for global illumination setup.

### [lighting_manager.gd](scripts/lighting_manager.gd)
Dynamic light pooling and LOD. Manages light culling and shadow toggling based on camera distance. Use for performance optimization with many lights.

### [volumetric_fx.gd](scripts/volumetric_fx.gd)
Volumetric fog and god ray configuration. Runtime fog density/color adjustments and light shaft setup. Use for atmospheric effects.

### [shadow_cascade_tuner.gd](scripts/shadow_cascade_tuner.gd)
Expert logic for adjusting DirectionalLight3D shadow split distances dynamically based on sun angle and camera tilt.

### [lightmap_bake_helper.gd](scripts/lightmap_bake_helper.gd)
Advanced LightmapGI configuration pattern using Shadowmasking mode for hybrid static/dynamic shadowing.

### [sdfgi_probe_manager.gd](scripts/sdfgi_probe_manager.gd)
Dynamic quality scaler for real-time Global Illumination (SDFGI). Adjusts cell size and occlusion for performance/quality trade-offs.

### [volumetric_fog_zones.gd](scripts/volumetric_fog_zones.gd)
Smoothly transitioning localized fog density for cave entrances or forest clearings using Tweens and Area3D triggers.

### [fake_gi_bounce.gd](scripts/fake_gi_bounce.gd)
Efficient 'Mobile-GI' pattern. Simulates light bouncing off the floor using non-shadowed directional fill lights.

### [environment_blender.gd](scripts/environment_blender.gd)
Architectural pattern for transitioning WorldEnvironment parameters (Sky, Ambient, Tonemap) during gameplay.

### [shadow_bias_tuner.gd](scripts/shadow_bias_tuner.gd)
Optimization script for correcting 'Peter Panning' and 'Shadow Acne' on high-fidelity directional lights.

### [light_lod_optimizer.gd](scripts/light_lod_optimizer.gd)
Distance-based shadow and visibility culling for OmniLight3D nodes in dense environments.

### [reflection_probe_manager.gd](scripts/reflection_probe_manager.gd)
Performance-aware ReflectionProbe handling using manual 'Update Once' triggers for large environmental changes.

### [spotlight_projector_setup.gd](scripts/spotlight_projector_setup.gd)
High-detail lighting using Projector textures to fake complex shadow patterns (grates, glass ripples).

---

## DirectionalLight3D (Sun/Moon)

### Shadow Cascades

```gdscript
# For outdoor scenes with camera moving from near to far
extends DirectionalLight3D

func _ready() -> void:
    shadow_enabled = true
    directional_shadow_mode = SHADOW_PARALLEL_4_SPLITS
    
    # Split distances (in meters from camera)
    directional_shadow_split_1 = 10.0   # First cascade: 0-10m
    directional_shadow_split_2 = 50.0   # Second: 10-50m
    directional_shadow_split_3 = 200.0  # Third: 50-200m
    # Fourth cascade: 200m - max shadow distance
    
    directional_shadow_max_distance = 500.0
    
    # Quality vs performance
    directional_shadow_blend_splits = true  # Smooth transitions
```

### Day/Night Cycle

```gdscript
# sun_controller.gd
extends DirectionalLight3D

@export var time_of_day := 12.0  # 0-24 hours
@export var rotation_speed := 0.1  # Hours per second

func _process(delta: float) -> void:
    time_of_day += rotation_speed * delta
    if time_of_day >= 24.0:
        time_of_day -= 24.0
    
    # Rotate sun (0° = noon, 180° = midnight)
    var angle := (time_of_day - 12.0) * 15.0  # 15° per hour
    rotation_degrees.x = -angle
    
    # Adjust intensity
    if time_of_day < 6.0 or time_of_day > 18.0:
        light_energy = 0.0  # Night
    elif time_of_day < 7.0:
        light_energy = remap(time_of_day, 6.0, 7.0, 0.0, 1.0)  # Sunrise
    elif time_of_day > 17.0:
        light_energy = remap(time_of_day, 17.0, 18.0, 1.0, 0.0)  # Sunset
    else:
        light_energy = 1.0  # Day
    
    # Color shift
    if time_of_day < 8.0 or time_of_day > 16.0:
        light_color = Color(1.0, 0.7, 0.4)  # Orange (dawn/dusk)
    else:
        light_color = Color(1.0, 1.0, 0.9)  # Neutral white
```

---

## OmniLight3D (Point Light)

### Attenuation Tuning

```gdscript
# torch.gd
extends OmniLight3D

func _ready() -> void:
    omni_range = 10.0  # Maximum reach
    omni_attenuation = 2.0  # Falloff curve (1.0 = linear, 2.0 = quadratic/realistic)
    
    # For "magical" lights, reduce attenuation
    omni_attenuation = 0.5  # Flatter falloff, reaches farther
```

### Flickering Effect

```gdscript
#  campfire.gd
extends OmniLight3D

@export var base_energy := 1.0
@export var flicker_strength := 0.3
@export var flicker_speed := 5.0

func _process(delta: float) -> void:
    var flicker := sin(Time.get_ticks_msec() * 0.001 * flicker_speed) * flicker_strength
    light_energy = base_energy + flicker
```

---

## SpotLight3D (Flashlight/Headlights)

### Setup

```gdscript
# flashlight.gd
extends SpotLight3D

func _ready() -> void:
    spot_range = 20.0
    spot_angle = 45.0  # Cone angle (degrees)
    spot_angle_attenuation = 2.0  # Edge softness
    
    shadow_enabled = true
    
    # Projector texture (optional - cookie/gobo)
    light_projector = load("res://textures/flashlight_mask.png")
```

### Follow Camera

```gdscript
# player_flashlight.gd
extends SpotLight3D

@onready var camera: Camera3D = get_viewport().get_camera_3d()

func _process(delta: float) -> void:
    if camera:
        global_transform = camera.global_transform
```

---

## Global Illumination: VoxelGI vs SDFGI

### Decision Matrix

| Feature | VoxelGI | SDFGI |
|---------|---------|-------|
| Setup | Manual bounds per room | Automatic, scene-wide |
| Dynamic objects | Fully supported | Partially supported |
| Performance | Moderate | Higher cost |
| Use case | Indoor, small-medium scenes | Large outdoor scenes |
| Godot