Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 36 ยท 3D Games

Lights, Shadows and Environment

Light a Godot 4 3D scene: DirectionalLight3D, OmniLight3D, SpotLight3D, shadows, WorldEnvironment sky, tonemapping, fog, SDFGI, VoxelGI, LightmapGI and the maths of attenuation.

A 3D scene without lights is black. Good lighting is also what makes a scene look professional, and it is one of the biggest costs of rendering. This lesson explains Godot's light nodes, shadows, the WorldEnvironment node (sky, fog, tonemapping) and the options for indirect (bounced) light.

The Godot renderer cannot run on this site, so node settings and scripts are read-only. The runnable blocks are Python stand-ins that model the underlying maths. Before this lesson read meshes and materials.

The three light nodes

Node Shape of the light Typical use
DirectionalLight3D Parallel rays from infinitely far away The sun or moon
OmniLight3D A point that shines in all directions Bulbs, torches, explosions
SpotLight3D A cone Flashlights, stage lights, lamps

All lights have light_color, light_energy (brightness), light_specular and shadow_enabled. Omni and spot lights also have a range in meters beyond which they contribute nothing, and an attenuation exponent controlling the fall-off. A spot light adds spot_angle.

GDSCRIPT
extends OmniLight3D

func _ready() -> void:
	light_color = Color("#ffb066")
	light_energy = 2.0
	omni_range = 8.0
	shadow_enabled = true

func _process(_delta: float) -> void:
	# a cheap torch flicker
	light_energy = 2.0 + randf_range(-0.3, 0.3)

A scene should have one directional light (the sun) and as few other shadow-casting lights as possible. Every shadowed light costs another render of the scene from its point of view.

Fall-off with distance

Real light follows an inverse-square law: double the distance, a quarter of the brightness. Games fade it to zero at the light's range so far-away lights can be skipped entirely.

Python Stand-in (Python, not Godot): inverse-square fall-off with a range cutoff

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The shape (a smooth window times inverse-square) is a common game-engine formulation, used here to explain the idea. Godot's exact curve differs and is tuned by the omni_attenuation property.

Spot lights are a cone test

A point is inside a spot light's cone when the angle between the light's forward axis and the direction to the point is less than the cone angle.

Python Stand-in (Python, not Godot): is a point inside a spotlight cone?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Shadows

Enable shadow_enabled on a light. For a DirectionalLight3D the shadow map is split into cascades (directional_shadow_mode): the area close to the camera gets sharp shadows, distant areas get coarse ones, and directional_shadow_max_distance limits how far shadows reach. If shadows show stripes ("shadow acne") adjust shadow_bias and shadow_normal_bias; if they float away from objects ("peter-panning") reduce the bias. Each MeshInstance3D has a cast_shadow setting (on, off, double-sided or shadows only), useful for hiding a mesh while keeping its shadow.

WorldEnvironment: sky, fog and tonemapping

A WorldEnvironment node holds an Environment resource that controls everything not tied to one object:

  • Background / Sky: a ProceduralSkyMaterial gives a gradient sky and a sun disc without any texture; PanoramaSkyMaterial uses an HDRI image.
  • Ambient light: sky or flat color light that reaches every surface, so shadows are not pitch black.
  • Tonemap: maps high-dynamic-range values to the screen (Filmic, ACES and others).
  • Glow: bloom around bright areas. Fog and volumetric fog add depth. SSAO darkens creases. SSR adds reflections.
  • Adjustments: brightness, contrast, saturation, color correction.
GDSCRIPT
func _ready() -> void:
	var env := Environment.new()
	env.background_mode = Environment.BG_SKY
	env.sky = Sky.new()
	env.sky.sky_material = ProceduralSkyMaterial.new()
	env.ambient_light_source = Environment.AMBIENT_SOURCE_SKY
	env.tonemap_mode = Environment.TONE_MAPPER_FILMIC
	env.fog_enabled = true
	env.fog_density = 0.01
	var we := WorldEnvironment.new()
	we.environment = env
	add_child(we)

Tonemapping compresses values above 1 so bright light does not clip to flat white. The simplest operator is Reinhard, c / (1 + c):

Python Stand-in (Python, not Godot): clipping vs a simple tonemap

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Values 1, 2, 4 and 8 all clip to 1.0 (a flat white blob), but they stay distinguishable after tonemapping. Godot's Filmic and ACES curves are more sophisticated versions of the same idea.

Indirect light: global illumination

Direct lights only shine on what they see. Global illumination (GI) adds bounced light and color bleeding. Choose by cost and flexibility:

  • SDFGI: real-time, no setup, good for big open worlds (Forward+ renderer only).
  • VoxelGI: real-time within a box you bake; good for interiors.
  • LightmapGI: baked into textures: best quality and fastest at run time, works on weak hardware, but static objects only and needs UV2 lightmap coordinates.
  • Reflection probes bake reflections for shiny surfaces.

For mobile and web, use the Mobile or Compatibility renderer and bake with LightmapGI. See profiling and performance to measure what your lighting costs.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which light node is right for the sun?

    A directional light sends parallel rays, like a sun far away, and lights the whole scene.
  2. 2. What does the WorldEnvironment node hold?

    Environment effects that apply to the whole scene live in the Environment resource.
  3. 3. Which GI option is baked into textures and works well on weak hardware?

    LightmapGI bakes light for static objects, so run-time cost is tiny.
  4. 4. Why limit the number of shadow-casting lights?

    Shadow maps are extra render passes. Use few shadowed lights and cheap unshadowed fill lights.

Summary

  • Use one directional light for the sun, omni and spot lights sparingly; every shadow costs time.
  • WorldEnvironment controls the sky, ambient light, tonemapping, glow, fog and SSAO.
  • Brightness falls off with distance and is cut at range; spot lights are cone tests.
  • SDFGI, VoxelGI and LightmapGI trade flexibility for speed; bake lightmaps for weak devices.

Next: Control Nodes and Containers