--- name: godot-3d-lighting description: "Expert patterns for Godot 3D lighting including DirectionalLight3D shadow cascades, OmniLight3D attenuation, SpotLight3D projectors, VoxelGI vs SDFGI, and LightmapGI baking. Use when implementing realistic 3D lighting, shadow optimization, global illumination, or light probes. Trigger keywords: DirectionalLight3D, OmniLight3D, SpotLight3D, shadow_enabled, directional_shadow_mode, directional_shadow_split, omni_range, omni_attenuation, spot_range, spot_angle, VoxelGI, SDFGI, LightmapGI, ReflectionProbe, Environment, WorldEnvironment." ---

# 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. - **NEVER overflow the clustered shadow atlas** — WHY: Forward+ packs Omni/Spot shadows into a shared atlas. Too many shadowed positional lights → atlas thrash, flickering, or silent quality collapse. Cap shadowed Omni (~3–5) and Spot (~2–4); use `light_lod_optimizer.gd` / distance fade before raising atlas size. - **NEVER stack dozens of overlapping shadowed Omni/Spot in one cluster cell** — WHY: Clustered light iteration cost scales with overlapping lights per tile. Prefer non-shadowed fills, tighter `omni_range`/`spot_range`, and `distance_fade_*` so far lights leave the cluster.

---

## Available Scripts

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

### Golden path (pick one — Do NOT Load peers) | Scene | Load | Do NOT Load | |-------|------|-------------| | **Outdoor** Forward+ | `shadow_cascade_tuner.gd` + `sdfgi_probe_manager.gd` (+ `day_night_cycle.gd` if time-of-day) | `fake_gi_bounce.gd`, indoor VoxelGI bake unless hybrid; `environment_blender.gd` / fog unless atmosphere task | | **Indoor** sealed geometry | **MANDATORY** VoxelGI via `light_probe_manager.gd` + `lighting_manager.gd` + ReflectionProbes | SDFGI on tiny interiors; Mobile fake GI unless targeting Mobile; sky/fog scripts unless zone blend | | **Mobile / Compatibility** | **MANDATORY** `fake_gi_bounce.gd` + light budgets in `light_lod_optimizer.gd` | Real-time SDFGI (Forward+ only); HDR sky/volumetric body recipes | | **Lightmap bake / hybrid static** | **MANDATORY** `lightmap_bake_helper.gd` (+ Shadowmasking for outdoor) | Runtime SDFGI as bake substitute; disabling lights via Visible | | **Sky / Environment blend only** | `environment_blender.gd` | Cascade/GI managers when only tonemap/ambient/sky changes | | **Volumetric fog / shafts** | `volumetric_fx.gd` (+ `volumetric_fog_zones.gd` for localized density) | Pure light-budget / shadow-atlas tuning tasks | | **Pure light budget / shadow LOD** | `light_lod_optimizer.gd`, `shadow_bias_tuner.gd` | **Do NOT Load** `environment_blender.gd`, `volumetric_fx.gd`, day-night unless required |

### [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).

### [light_volume_trigger.gd](scripts/light_volume_trigger.gd) Area3D-driven camera `Environment` blend for cave/desert transitions (duplicate env resource; tween exposure/ambient).

### [lighting_quality_manager.gd](scripts/lighting_quality_manager.gd) Runtime `RenderingServer` profile: half-res SDFGI, shadow atlas size, volumetric fog density.

---

## 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

**MANDATORY** [`day_night_cycle.gd`](scripts/day_night_cycle.gd) — do not re-inline sun energy/color recipes here.

---

## OmniLight3D (Point Light)

Keep `omni_range` tight; prefer quadratic attenuation. Flicker/campfire loops belong in scene scripts — not this body. Shadowed Omni count is a hard budget (see NEVER).

---

## SpotLight3D (Flashlight/Headlights)

**MANDATORY** [`spotlight_projector_setup.gd`](scripts/spotlight_projector_setup.gd) for range/angle/projector cookies and camera-follow flashlights. Do not paste Spot setup here.

---

## Global Illumination (script-first)

Use the golden-path table above. Body decision only:

| Path | Script | When | |------|--------|------| | Indoor / sealed | **MANDATORY** [`light_probe_manager.gd`](scripts/light_probe_manager.gd) (+ [`lighting_manager.gd`](scripts/lighting_manager.gd)) | Tight VoxelGI extents per room; never paper-thin walls | | Outdoor Forward+ | **MANDATORY** [`sdfgi_probe_manager.gd`](scripts/sdfgi_probe_manager.gd) | Real-time GI; **Do NOT Load** on Mobile/Compatibility | | Static / Mobile bake | **MANDATORY** [`lightmap_bake_helper.gd`](scripts/lightmap_bake_helper.gd) | LightmapGI + Shadowmasking; bake mode ≠ Visible hide | | No GI budget | **MANDATORY** [`fake_gi_bounce.gd`](scripts/fake_gi_bounce.gd) | Fill lights only |

Do not re-inline VoxelGI/SDFGI/Lightmap property setup here.

---

## Environment & Sky

Sky/ambient/tonemap transitions → **MANDATORY** [`environment_blender.gd`](scripts/environment_blender.gd). Volumetric fog / shafts → **MANDATORY** [`volumetric_fx.gd`](scripts/volumetric_fx.gd) (+ [`volumetric_fog_zones.gd`](scripts/volumetric_fog_zones.gd) for caves/forests).

**Do NOT Load** these for pure light-budget / shadow-atlas / cascade tuning — stay on `light_lod_optimizer.gd` / `shadow_cascade_tuner.gd`.

---

## ReflectionProbe

For localized reflections (mirrors, shiny floors):

```gdscript # reflection_probe.gd extends ReflectionProbe

func _ready() -> void: # Capture area size = Vector3(10, 5, 10) # Quality resolution = ReflectionProbe.RESOLUTION_512 # Update mode update_mode = ReflectionProbe.UPDATE_ONCE # Bake once # or UPDATE_ALWAYS for dynamic reflections (expensive) ```

---

## Performance Optimization

### Light Budgets

```gdscript # Recommended limits: # - DirectionalLight3D with shadows: 1-2 # - OmniLight3D with shadows: 3-5 # - SpotLight3D with shadows: 2-4 # - OmniLight3D without shadows: 20-30 # - SpotLight3D without shadows: 15-20

# Disable shadows on minor lights @onready var candle_lights: Array = [$Candle1, $Candle2, $Candle3]

func _ready() -> void: for light in candle_lights: light.shadow_enabled = false # Save performance ```

### Per-Light Shadow Distance

```gdscript # Disable shadows for distant lights extends OmniLight3D

@export var shadow_max_distance := 50.0

func _process(delta: float) -> void: var camera := get_viewport().get_camera_3d() if camera: var dist := global_position.distance_to(camera.global_position) shadow_enabled = (dist < shadow_max_distance) ```

---

## Edge Cases

### Shadows Through Floors

```gdscript # Problem: Thin floors let shadows through # Solution: Increase shadow bias

extends DirectionalLight3D

func _ready() -> void: shadow_enabled = true shadow_bias = 0.1 # Increase if shadows bleed through shadow_normal_bias = 2.0 ```

### Light Leaking in Indoor Scenes

```gdscript # Problem: VoxelGI light bleeds through walls # Solution: Place VoxelGI nodes per-room, don't overlap

# Also: Ensure walls have proper thickness (not paper-thin) ```

---

## Expert Techniques & Optimizations

### 1. Shadowmasking for Large Outdoor Scenes Rendering real-time shadows for distant objects is too expensive. Use **Shadowmasking** by setting a Dire

--- name: godot-3d-lighting description: "Expert patterns for Godot 3D lighting including DirectionalLight3D shadow cascades, OmniLight3D attenuation, SpotLight3D projectors, VoxelGI vs SDFGI, and LightmapGI baking. Use when implementing realistic 3D lighting, shadow optimization, global illumination, or light probes. Trigger keywords: DirectionalLight3D, OmniLight3D, SpotLight3D, shadow_enabled, directional_shadow_mode, directional_shadow_split, omni_range, omni_attenuation, spot_range, spot_angle, VoxelGI, SDFGI, LightmapGI, ReflectionProbe, Environment, WorldEnvironment." ---

# 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. - **NEVER overflow the clustered shadow atlas** — WHY: Forward+ packs Omni/Spot shadows into a shared atlas. Too many shadowed positional lights → atlas thrash, flickering, or silent quality collapse. Cap shadowed Omni (~3–5) and Spot (~2–4); use `light_lod_optimizer.gd` / distance fade before raising atlas size. - **NEVER stack dozens of overlapping shadowed Omni/Spot in one cluster cell** — WHY: Clustered light iteration cost scales with overlapping lights per tile. Prefer non-shadowed fills, tighter `omni_range`/`spot_range`, and `distance_fade_*` so far lights leave the cluster.

---

## Available Scripts

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

### Golden path (pick one — Do NOT Load peers) | Scene | Load | Do NOT Load | |-------|------|-------------| | **Outdoor** Forward+ | `shadow_cascade_tuner.gd` + `sdfgi_probe_manager.gd` (+ `day_night_cycle.gd` if time-of-day) | `fake_gi_bounce.gd`, indoor VoxelGI bake unless hybrid; `environment_blender.gd` / fog unless atmosphere task | | **Indoor** sealed geometry | **MANDATORY** VoxelGI via `light_probe_manager.gd` + `lighting_manager.gd` + ReflectionProbes | SDFGI on tiny interiors; Mobile fake GI unless targeting Mobile; sky/fog scripts unless zone blend | | **Mobile / Compatibility** | **MANDATORY** `fake_gi_bounce.gd` + light budgets in `light_lod_optimizer.gd` | Real-time SDFGI (Forward+ only); HDR sky/volumetric body recipes | | **Lightmap bake / hybrid static** | **MANDATORY** `lightmap_bake_helper.gd` (+ Shadowmasking for outdoor) | Runtime SDFGI as bake substitute; disabling lights via Visible | | **Sky / Environment blend only** | `environment_blender.gd` | Cascade/GI managers when only tonemap/ambient/sky changes | | **Volumetric fog / shafts** | `volumetric_fx.gd` (+ `volumetric_fog_zones.gd` for localized density) | Pure light-budget / shadow-atlas tuning tasks | | **Pure light budget / shadow LOD** | `light_lod_optimizer.gd`, `shadow_bias_tuner.gd` | **Do NOT Load** `environment_blender.gd`, `volumetric_fx.gd`, day-night unless required |

### [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).

### [light_volume_trigger.gd](scripts/light_volume_trigger.gd) Area3D-driven camera `Environment` blend for cave/desert transitions (duplicate env resource; tween exposure/ambient).

### [lighting_quality_manager.gd](scripts/lighting_quality_manager.gd) Runtime `RenderingServer` profile: half-res SDFGI, shadow atlas size, volumetric fog density.

---

## 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

**MANDATORY** [`day_night_cycle.gd`](scripts/day_night_cycle.gd) — do not re-inline sun energy/color recipes here.

---

## OmniLight3D (Point Light)

Keep `omni_range` tight; prefer quadratic attenuation. Flicker/campfire loops belong in scene scripts — not this body. Shadowed Omni count is a hard budget (see NEVER).

---

## SpotLight3D (Flashlight/Headlights)

**MANDATORY** [`spotlight_projector_setup.gd`](scripts/spotlight_projector_setup.gd) for range/angle/projector cookies and camera-follow flashlights. Do not paste Spot setup here.

---

## Global Illumination (script-first)

Use the golden-path table above. Body decision only:

| Path | Script | When | |------|--------|------| | Indoor / sealed | **MANDATORY** [`light_probe_manager.gd`](scripts/light_probe_manager.gd) (+ [`lighting_manager.gd`](scripts/lighting_manager.gd)) | Tight VoxelGI extents per room; never paper-thin walls | | Outdoor Forward+ | **MANDATORY** [`sdfgi_probe_manager.gd`](scripts/sdfgi_probe_manager.gd) | Real-time GI; **Do NOT Load** on Mobile/Compatibility | | Static / Mobile bake | **MANDATORY** [`lightmap_bake_helper.gd`](scripts/lightmap_bake_helper.gd) | LightmapGI + Shadowmasking; bake mode ≠ Visible hide | | No GI budget | **MANDATORY** [`fake_gi_bounce.gd`](scripts/fake_gi_bounce.gd) | Fill lights only |

Do not re-inline VoxelGI/SDFGI/Lightmap property setup here.

---

## Environment & Sky

Sky/ambient/tonemap transitions → **MANDATORY** [`environment_blender.gd`](scripts/environment_blender.gd). Volumetric fog / shafts → **MANDATORY** [`volumetric_fx.gd`](scripts/volumetric_fx.gd) (+ [`volumetric_fog_zones.gd`](scripts/volumetric_fog_zones.gd) for caves/forests).

**Do NOT Load** these for pure light-budget / shadow-atlas / cascade tuning — stay on `light_lod_optimizer.gd` / `shadow_cascade_tuner.gd`.

---

## ReflectionProbe

For localized reflections (mirrors, shiny floors):

```gdscript # reflection_probe.gd extends ReflectionProbe

func _ready() -> void: # Capture area size = Vector3(10, 5, 10) # Quality resolution = ReflectionProbe.RESOLUTION_512 # Update mode update_mode = ReflectionProbe.UPDATE_ONCE # Bake once # or UPDATE_ALWAYS for dynamic reflections (expensive) ```

---

## Performance Optimization

### Light Budgets

```gdscript # Recommended limits: # - DirectionalLight3D with shadows: 1-2 # - OmniLight3D with shadows: 3-5 # - SpotLight3D with shadows: 2-4 # - OmniLight3D without shadows: 20-30 # - SpotLight3D without shadows: 15-20

# Disable shadows on minor lights @onready var candle_lights: Array = [$Candle1, $Candle2, $Candle3]

func _ready() -> void: for light in candle_lights: light.shadow_enabled = false # Save performance ```

### Per-Light Shadow Distance

```gdscript # Disable shadows for distant lights extends OmniLight3D

@export var shadow_max_distance := 50.0

func _process(delta: float) -> void: var camera := get_viewport().get_camera_3d() if camera: var dist := global_position.distance_to(camera.global_position) shadow_enabled = (dist < shadow_max_distance) ```

---

## Edge Cases

### Shadows Through Floors

```gdscript # Problem: Thin floors let shadows through # Solution: Increase shadow bias

extends DirectionalLight3D

func _ready() -> void: shadow_enabled = true shadow_bias = 0.1 # Increase if shadows bleed through shadow_normal_bias = 2.0 ```

### Light Leaking in Indoor Scenes

```gdscript # Problem: VoxelGI light bleeds through walls # Solution: Place VoxelGI nodes per-room, don't overlap

# Also: Ensure walls have proper thickness (not paper-thin) ```

---

## Expert Techniques & Optimizations

### 1. Shadowmasking for Large Outdoor Scenes Rendering real-time shadows for distant objects is too expensive. Use **Shadowmasking** by setting a Dire

--- name: godot-3d-lighting description: "Expert patterns for Godot 3D lighting including DirectionalLight3D shadow cascades, OmniLight3D attenuation, SpotLight3D projectors, VoxelGI vs SDFGI, and LightmapGI baking. Use when implementing realistic 3D lighting, shadow optimization, global illumination, or light probes. Trigger keywords: DirectionalLight3D, OmniLight3D, SpotLight3D, shadow_enabled, directional_shadow_mode, directional_shadow_split, omni_range, omni_attenuation, spot_range, spot_angle, VoxelGI, SDFGI, LightmapGI, ReflectionProbe, Environment, WorldEnvironment." ---

# 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. - **NEVER overflow the clustered shadow atlas** — WHY: Forward+ packs Omni/Spot shadows into a shared atlas. Too many shadowed positional lights → atlas thrash, flickering, or silent quality collapse. Cap shadowed Omni (~3–5) and Spot (~2–4); use `light_lod_optimizer.gd` / distance fade before raising atlas size. - **NEVER stack dozens of overlapping shadowed Omni/Spot in one cluster cell** — WHY: Clustered light iteration cost scales with overlapping lights per tile. Prefer non-shadowed fills, tighter `omni_range`/`spot_range`, and `distance_fade_*` so far lights leave the cluster.

---

## Available Scripts

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

### Golden path (pick one — Do NOT Load peers) | Scene | Load | Do NOT Load | |-------|------|-------------| | **Outdoor** Forward+ | `shadow_cascade_tuner.gd` + `sdfgi_probe_manager.gd` (+ `day_night_cycle.gd` if time-of-day) | `fake_gi_bounce.gd`, indoor VoxelGI bake unless hybrid; `environment_blender.gd` / fog unless atmosphere task | | **Indoor** sealed geometry | **MANDATORY** VoxelGI via `light_probe_manager.gd` + `lighting_manager.gd` + ReflectionProbes | SDFGI on tiny interiors; Mobile fake GI unless targeting Mobile; sky/fog scripts unless zone blend | | **Mobile / Compatibility** | **MANDATORY** `fake_gi_bounce.gd` + light budgets in `light_lod_optimizer.gd` | Real-time SDFGI (Forward+ only); HDR sky/volumetric body recipes | | **Lightmap bake / hybrid static** | **MANDATORY** `lightmap_bake_helper.gd` (+ Shadowmasking for outdoor) | Runtime SDFGI as bake substitute; disabling lights via Visible | | **Sky / Environment blend only** | `environment_blender.gd` | Cascade/GI managers when only tonemap/ambient/sky changes | | **Volumetric fog / shafts** | `volumetric_fx.gd` (+ `volumetric_fog_zones.gd` for localized density) | Pure light-budget / shadow-atlas tuning tasks | | **Pure light budget / shadow LOD** | `light_lod_optimizer.gd`, `shadow_bias_tuner.gd` | **Do NOT Load** `environment_blender.gd`, `volumetric_fx.gd`, day-night unless required |

### [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).

### [light_volume_trigger.gd](scripts/light_volume_trigger.gd) Area3D-driven camera `Environment` blend for cave/desert transitions (duplicate env resource; tween exposure/ambient).

### [lighting_quality_manager.gd](scripts/lighting_quality_manager.gd) Runtime `RenderingServer` profile: half-res SDFGI, shadow atlas size, volumetric fog density.

---

## 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

**MANDATORY** [`day_night_cycle.gd`](scripts/day_night_cycle.gd) — do not re-inline sun energy/color recipes here.

---

## OmniLight3D (Point Light)

Keep `omni_range` tight; prefer quadratic attenuation. Flicker/campfire loops belong in scene scripts — not this body. Shadowed Omni count is a hard budget (see NEVER).

---

## SpotLight3D (Flashlight/Headlights)

**MANDATORY** [`spotlight_projector_setup.gd`](scripts/spotlight_projector_setup.gd) for range/angle/projector cookies and camera-follow flashlights. Do not paste Spot setup here.

---

## Global Illumination (script-first)

Use the golden-path table above. Body decision only:

| Path | Script | When | |------|--------|------| | Indoor / sealed | **MANDATORY** [`light_probe_manager.gd`](scripts/light_probe_manager.gd) (+ [`lighting_manager.gd`](scripts/lighting_manager.gd)) | Tight VoxelGI extents per room; never paper-thin walls | | Outdoor Forward+ | **MANDATORY** [`sdfgi_probe_manager.gd`](scripts/sdfgi_probe_manager.gd) | Real-time GI; **Do NOT Load** on Mobile/Compatibility | | Static / Mobile bake | **MANDATORY** [`lightmap_bake_helper.gd`](scripts/lightmap_bake_helper.gd) | LightmapGI + Shadowmasking; bake mode ≠ Visible hide | | No GI budget | **MANDATORY** [`fake_gi_bounce.gd`](scripts/fake_gi_bounce.gd) | Fill lights only |

Do not re-inline VoxelGI/SDFGI/Lightmap property setup here.

---

## Environment & Sky

Sky/ambient/tonemap transitions → **MANDATORY** [`environment_blender.gd`](scripts/environment_blender.gd). Volumetric fog / shafts → **MANDATORY** [`volumetric_fx.gd`](scripts/volumetric_fx.gd) (+ [`volumetric_fog_zones.gd`](scripts/volumetric_fog_zones.gd) for caves/forests).

**Do NOT Load** these for pure light-budget / shadow-atlas / cascade tuning — stay on `light_lod_optimizer.gd` / `shadow_cascade_tuner.gd`.

---

## ReflectionProbe

For localized reflections (mirrors, shiny floors):

```gdscript # reflection_probe.gd extends ReflectionProbe

func _ready() -> void: # Capture area size = Vector3(10, 5, 10) # Quality resolution = ReflectionProbe.RESOLUTION_512 # Update mode update_mode = ReflectionProbe.UPDATE_ONCE # Bake once # or UPDATE_ALWAYS for dynamic reflections (expensive) ```

---

## Performance Optimization

### Light Budgets

```gdscript # Recommended limits: # - DirectionalLight3D with shadows: 1-2 # - OmniLight3D with shadows: 3-5 # - SpotLight3D with shadows: 2-4 # - OmniLight3D without shadows: 20-30 # - SpotLight3D without shadows: 15-20

# Disable shadows on minor lights @onready var candle_lights: Array = [$Candle1, $Candle2, $Candle3]

func _ready() -> void: for light in candle_lights: light.shadow_enabled = false # Save performance ```

### Per-Light Shadow Distance

```gdscript # Disable shadows for distant lights extends OmniLight3D

@export var shadow_max_distance := 50.0

func _process(delta: float) -> void: var camera := get_viewport().get_camera_3d() if camera: var dist := global_position.distance_to(camera.global_position) shadow_enabled = (dist < shadow_max_distance) ```

---

## Edge Cases

### Shadows Through Floors

```gdscript # Problem: Thin floors let shadows through # Solution: Increase shadow bias

extends DirectionalLight3D

func _ready() -> void: shadow_enabled = true shadow_bias = 0.1 # Increase if shadows bleed through shadow_normal_bias = 2.0 ```

### Light Leaking in Indoor Scenes

```gdscript # Problem: VoxelGI light bleeds through walls # Solution: Place VoxelGI nodes per-room, don't overlap

# Also: Ensure walls have proper thickness (not paper-thin) ```

---

## Expert Techniques & Optimizations

### 1. Shadowmasking for Large Outdoor Scenes Rendering real-time shadows for distant objects is too expensive. Use **Shadowmasking** by setting a Dire

--- name: godot-3d-lighting description: "Expert patterns for Godot 3D lighting including DirectionalLight3D shadow cascades, OmniLight3D attenuation, SpotLight3D projectors, VoxelGI vs SDFGI, and LightmapGI baking. Use when implementing realistic 3D lighting, shadow optimization, global illumination, or light probes. Trigger keywords: DirectionalLight3D, OmniLight3D, SpotLight3D, shadow_enabled, directional_shadow_mode, directional_shadow_split, omni_range, omni_attenuation, spot_range, spot_angle, VoxelGI, SDFGI, LightmapGI, ReflectionProbe, Environment, WorldEnvironment." ---

# 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. - **NEVER overflow the clustered shadow atlas** — WHY: Forward+ packs Omni/Spot shadows into a shared atlas. Too many shadowed positional lights → atlas thrash, flickering, or silent quality collapse. Cap shadowed Omni (~3–5) and Spot (~2–4); use `light_lod_optimizer.gd` / distance fade before raising atlas size. - **NEVER stack dozens of overlapping shadowed Omni/Spot in one cluster cell** — WHY: Clustered light iteration cost scales with overlapping lights per tile. Prefer non-shadowed fills, tighter `omni_range`/`spot_range`, and `distance_fade_*` so far lights leave the cluster.

---

## Available Scripts

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

### Golden path (pick one — Do NOT Load peers) | Scene | Load | Do NOT Load | |-------|------|-------------| | **Outdoor** Forward+ | `shadow_cascade_tuner.gd` + `sdfgi_probe_manager.gd` (+ `day_night_cycle.gd` if time-of-day) | `fake_gi_bounce.gd`, indoor VoxelGI bake unless hybrid; `environment_blender.gd` / fog unless atmosphere task | | **Indoor** sealed geometry | **MANDATORY** VoxelGI via `light_probe_manager.gd` + `lighting_manager.gd` + ReflectionProbes | SDFGI on tiny interiors; Mobile fake GI unless targeting Mobile; sky/fog scripts unless zone blend | | **Mobile / Compatibility** | **MANDATORY** `fake_gi_bounce.gd` + light budgets in `light_lod_optimizer.gd` | Real-time SDFGI (Forward+ only); HDR sky/volumetric body recipes | | **Lightmap bake / hybrid static** | **MANDATORY** `lightmap_bake_helper.gd` (+ Shadowmasking for outdoor) | Runtime SDFGI as bake substitute; disabling lights via Visible | | **Sky / Environment blend only** | `environment_blender.gd` | Cascade/GI managers when only tonemap/ambient/sky changes | | **Volumetric fog / shafts** | `volumetric_fx.gd` (+ `volumetric_fog_zones.gd` for localized density) | Pure light-budget / shadow-atlas tuning tasks | | **Pure light budget / shadow LOD** | `light_lod_optimizer.gd`, `shadow_bias_tuner.gd` | **Do NOT Load** `environment_blender.gd`, `volumetric_fx.gd`, day-night unless required |

### [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).

### [light_volume_trigger.gd](scripts/light_volume_trigger.gd) Area3D-driven camera `Environment` blend for cave/desert transitions (duplicate env resource; tween exposure/ambient).

### [lighting_quality_manager.gd](scripts/lighting_quality_manager.gd) Runtime `RenderingServer` profile: half-res SDFGI, shadow atlas size, volumetric fog density.

---

## 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

**MANDATORY** [`day_night_cycle.gd`](scripts/day_night_cycle.gd) — do not re-inline sun energy/color recipes here.

---

## OmniLight3D (Point Light)

Keep `omni_range` tight; prefer quadratic attenuation. Flicker/campfire loops belong in scene scripts — not this body. Shadowed Omni count is a hard budget (see NEVER).

---

## SpotLight3D (Flashlight/Headlights)

**MANDATORY** [`spotlight_projector_setup.gd`](scripts/spotlight_projector_setup.gd) for range/angle/projector cookies and camera-follow flashlights. Do not paste Spot setup here.

---

## Global Illumination (script-first)

Use the golden-path table above. Body decision only:

| Path | Script | When | |------|--------|------| | Indoor / sealed | **MANDATORY** [`light_probe_manager.gd`](scripts/light_probe_manager.gd) (+ [`lighting_manager.gd`](scripts/lighting_manager.gd)) | Tight VoxelGI extents per room; never paper-thin walls | | Outdoor Forward+ | **MANDATORY** [`sdfgi_probe_manager.gd`](scripts/sdfgi_probe_manager.gd) | Real-time GI; **Do NOT Load** on Mobile/Compatibility | | Static / Mobile bake | **MANDATORY** [`lightmap_bake_helper.gd`](scripts/lightmap_bake_helper.gd) | LightmapGI + Shadowmasking; bake mode ≠ Visible hide | | No GI budget | **MANDATORY** [`fake_gi_bounce.gd`](scripts/fake_gi_bounce.gd) | Fill lights only |

Do not re-inline VoxelGI/SDFGI/Lightmap property setup here.

---

## Environment & Sky

Sky/ambient/tonemap transitions → **MANDATORY** [`environment_blender.gd`](scripts/environment_blender.gd). Volumetric fog / shafts → **MANDATORY** [`volumetric_fx.gd`](scripts/volumetric_fx.gd) (+ [`volumetric_fog_zones.gd`](scripts/volumetric_fog_zones.gd) for caves/forests).

**Do NOT Load** these for pure light-budget / shadow-atlas / cascade tuning — stay on `light_lod_optimizer.gd` / `shadow_cascade_tuner.gd`.

---

## ReflectionProbe

For localized reflections (mirrors, shiny floors):

```gdscript # reflection_probe.gd extends ReflectionProbe

func _ready() -> void: # Capture area size = Vector3(10, 5, 10) # Quality resolution = ReflectionProbe.RESOLUTION_512 # Update mode update_mode = ReflectionProbe.UPDATE_ONCE # Bake once # or UPDATE_ALWAYS for dynamic reflections (expensive) ```

---

## Performance Optimization

### Light Budgets

```gdscript # Recommended limits: # - DirectionalLight3D with shadows: 1-2 # - OmniLight3D with shadows: 3-5 # - SpotLight3D with shadows: 2-4 # - OmniLight3D without shadows: 20-30 # - SpotLight3D without shadows: 15-20

# Disable shadows on minor lights @onready var candle_lights: Array = [$Candle1, $Candle2, $Candle3]

func _ready() -> void: for light in candle_lights: light.shadow_enabled = false # Save performance ```

### Per-Light Shadow Distance

```gdscript # Disable shadows for distant lights extends OmniLight3D

@export var shadow_max_distance := 50.0

func _process(delta: float) -> void: var camera := get_viewport().get_camera_3d() if camera: var dist := global_position.distance_to(camera.global_position) shadow_enabled = (dist < shadow_max_distance) ```

---

## Edge Cases

### Shadows Through Floors

```gdscript # Problem: Thin floors let shadows through # Solution: Increase shadow bias

extends DirectionalLight3D

func _ready() -> void: shadow_enabled = true shadow_bias = 0.1 # Increase if shadows bleed through shadow_normal_bias = 2.0 ```

### Light Leaking in Indoor Scenes

```gdscript # Problem: VoxelGI light bleeds through walls # Solution: Place VoxelGI nodes per-room, don't overlap

# Also: Ensure walls have proper thickness (not paper-thin) ```

---

## Expert Techniques & Optimizations

### 1. Shadowmasking for Large Outdoor Scenes Rendering real-time shadows for distant objects is too expensive. Use **Shadowmasking** by setting a Dire