godot-3d-lighting

Files (15)

• SKILL.md
• day_night_cycle.gd · scripts/
• environment_blender.gd · scripts/
• fake_gi_bounce.gd · scripts/
• light_lod_optimizer.gd · scripts/
• light_probe_manager.gd · scripts/
• lighting_manager.gd · scripts/
• lightmap_bake_helper.gd · scripts/
• reflection_probe_manager.gd · scripts/
• sdfgi_probe_manager.gd · scripts/
• shadow_bias_tuner.gd · scripts/
• shadow_cascade_tuner.gd · scripts/
• spotlight_projector_setup.gd · scripts/
• volumetric_fog_zones.gd · scripts/
• volumetric_fx.gd · scripts/

SKILL.md (first lines)

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

---

## Godot 4.7: AreaLight3D

- **AreaLight3D** provides rectangular area lights with soft shadows — prefer over emissive-material + GI workarounds for screens, glowing panels, and billboards.
- **HDR output** is supported on all major platforms; enable in Project Settings → Rendering → Viewport for true HDR display chain.
- **NEVER** use emissive-only fake panels when AreaLight3D gives correct falloff and shadow softness in Forward+.

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

From bgrenat/godot-game-dev-studio, LGPL-3.0.

More from bgrenat/godot-game-dev-studio