Godot 3D Lighting

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)

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

VoxelGI and SDFGI management for global illumination setup.

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

Volumetric fog and god ray configuration. Runtime fog density/color adjustments and light shaft setup. Use for atmospheric effects.

shadow_cascade_tuner.gd

Expert logic for adjusting DirectionalLight3D shadow split distances dynamically based on sun angle and camera tilt.

lightmap_bake_helper.gd

Advanced LightmapGI configuration pattern using Shadowmasking mode for hybrid static/dynamic shadowing.

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

Smoothly transitioning localized fog density for cave entrances or forest clearings using Tweens and Area3D triggers.

fake_gi_bounce.gd

Efficient 'Mobile-GI' pattern. Simulates light bouncing off the floor using non-shadowed directional fill lights.

environment_blender.gd

Architectural pattern for transitioning WorldEnvironment parameters (Sky, Ambient, Tonemap) during gameplay.

shadow_bias_tuner.gd

Optimization script for correcting 'Peter Panning' and 'Shadow Acne' on high-fidelity directional lights.

light_lod_optimizer.gd

Distance-based shadow and visibility culling for OmniLight3D nodes in dense environments.

reflection_probe_manager.gd

Performance-aware ReflectionProbe handling using manual 'Update Once' triggers for large environmental changes.

spotlight_projector_setup.gd

High-detail lighting using Projector textures to fake complex shadow patterns (grates, glass ripples).

light_volume_trigger.gd

Area3D-driven camera Environment blend for cave/desert transitions (duplicate env resource; tween exposure/ambient).

lighting_quality_manager.gd

Runtime RenderingServer profile: half-res SDFGI, shadow atlas size, volumetric fog density.

DirectionalLight3D (Sun/Moon)

Shadow Cascades

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

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

Environment & Sky

Sky/ambient/tonemap transitions → MANDATORY environment_blender.gd. Volumetric fog / shafts → MANDATORY volumetric_fx.gd (+ 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):

# 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

# 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

# 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

# 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

# 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 DirectionalLight3D to the Dynamic bake mode while baking a LightmapGI. This bakes distant shadows into a texture while allowing dynamic objects to cast real-time shadows up close, preventing "double shadowing" artifacts.