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.

Available Scripts

MANDATORY

Read the appropriate script before implementing the corresponding pattern. 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. 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

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

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

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

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

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 version 4.0+ 4.0+ VoxelGI Setup

room_gi.gd - Place one VoxelGI per room/area

extends VoxelGI func _ready ( ) -> void :

Tightly fit the room

size

Vector3 ( 20 , 10 , 20 )

Quality settings

subdiv

VoxelGI . SUBDIV_128

Higher = better quality, slower

Bake GI data

bake ( ) SDFGI Setup

world_environment.gd

extends WorldEnvironment func _ready ( ) -> void : var env := environment

Enable SDFGI

env . sdfgi_enabled = true env . sdfgi_use_occlusion = true env . sdfgi_read_sky_light = true

Cascades (auto-scale based on camera)

env . sdfgi_min_cell_size = 0.2

Detail level

env . sdfgi_max_distance = 200.0 LightmapGI (Baked Static Lighting) When to Use Static architecture (buildings, dungeons) Mobile/low-end targets No dynamic geometry Setup

Scene structure:

- LightmapGI node

- StaticBody3D meshes with GeometryInstance3D.gi_mode = STATIC

lightmap_baker.gd

extends LightmapGI func _ready ( ) -> void :

Quality settings

quality

LightmapGI . BAKE_QUALITY_HIGH bounces = 3

Indirect light bounces

Bake (editor only, not runtime)

Click "Bake Lightmaps" button in editor

Environment & Sky HDR Skybox

world_env.gd

extends WorldEnvironment func _ready ( ) -> void : var env := environment env . background_mode = Environment . BG_SKY var sky := Sky . new ( ) var sky_material := PanoramaSkyMaterial . new ( ) sky_material . panorama = load ( "res://hdri/sky.hdr" ) sky . sky_material = sky_material env . sky = sky

Sky contribution to GI

env . ambient_light_source = Environment . AMBIENT_SOURCE_SKY env . ambient_light_sky_contribution = 1.0 Volumetric Fog extends WorldEnvironment func _ready ( ) -> void : var env := environment env . volumetric_fog_enabled = true env . volumetric_fog_density = 0.01 env . volumetric_fog_albedo = Color ( 0.9 , 0.9 , 1.0 )

Blueish

env . volumetric_fog_emission = Color . BLACK 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)

Reference Master Skill: godot-master