3D lights and shadows

Introduction

Light sources emit light that mixes with the materials and produces a visible result. Light can come from several types of sources in a scene:

  • From the material itself, in the form of the emission color (though it does not affect nearby objects unless baked or screen-space indirect lighting is enabled).

  • Light nodes: DirectionalLight3D, OmniLight3D and SpotLight3D.

  • Ambient light in the Environment or Reflection probes.

  • Global illumination (LightmapGI, VoxelGI or SDFGI).

The emission color is a material property. You can read more about it in the Standard Material 3D and ORM Material 3D tutorial.

See also

You can compare various types of lights in action using the 3D Lights and Shadows demo project.

Light nodes

There are three types of light nodes: DirectionalLight3D, OmniLight3D and SpotLight3D. Let's take a look at the common parameters for lights:

../../_images/light_params.png

Each property has a specific function:

  • Color: Base color for emitted light.

  • Energy: Energy multiplier. This is useful for saturating lights or working with High dynamic range lighting.

  • Indirect Energy: Secondary multiplier used with indirect light (light bounces). This works with Using Lightmap global illumination, VoxelGI or SDFGI.

  • Volumetric Fog Energy: Secondary multiplier used with volumetric fog. This only has an effect when volumetric fog is enabled.

  • Negative: Light becomes subtractive instead of additive. It's sometimes useful to manually compensate some dark corners.

  • Specular: Affects the intensity of the specular blob in objects affected by this light. At zero, this light becomes a pure diffuse light.

  • Bake Mode: Sets the bake mode for the light. See Using Lightmap global illumination.

  • Cull Mask: Objects that are in the selected layers below will be affected by this light. Note that objects disabled via this cull mask will still cast shadows. If you don't want disabled objects to cast shadows, adjust the Cast Shadow property on the GeometryInstance3D to the desired value.

See also

See Physical light and camera units if you wish to use real world units to configure your lights' intensity and color temperature.

Light number limits

When using the Forward+ renderer, Godot uses a clustering approach for real-time lighting. As many lights as desired can be added (as long as performance allows). However, there's still a default limit of 512 clustered elements that can be present in the current camera view. A clustered element is an omni light, a spot light, a decal or a reflection probe. This limit can be increased by adjusting the Rendering > Limits > Cluster Builder > Max Clustered Elements advanced project setting.

When using the Forward Mobile renderer, there is a limitation of 8 OmniLights + 8 SpotLights per mesh resource. There is also a limit of 256 OmniLights + 256 SpotLights that can be rendered in the current camera view. These limits currently cannot be changed.

When using the Compatibility renderer, up to 8 OmniLights + 8 SpotLights can be rendered per mesh resource. This limit can be increased in the advanced Project Settings by adjusting Rendering > Limits > OpenGL > Max Renderable Lights and/or Rendering > Limits > OpenGL > Max Lights Per Object at the cost of performance and longer shader compilation times. The limit can also be decreased to reduce shader compilation times and improve performance slightly.

With all rendering methods, up to 8 DirectionalLights can be visible at a time. However, each additional DirectionalLight with shadows enabled will reduce the effective shadow resolution of each DirectionalLight. This is because directional shadow atlas is shared between all lights.

If the rendering limit is exceeded, lights will start popping in and out during camera movement, which can be distracting. Enabling Distance Fade on light nodes can help reduce this issue while also improving performance. Splitting your meshes into smaller portions can also help, especially for level geometry (which also improves culling efficiency).

If you need to render more lights than possible in a given rendering backend, consider using baked lightmaps with lights' bake mode set to Static. This allows lights to be fully baked, which also makes them much faster to render. You can also use emissive materials with any global illumination technique as a replacement for light nodes that emit light over a large area.

Shadow mapping

Lights can optionally cast shadows. This gives them greater realism (light does not reach occluded areas), but it can incur a bigger performance cost. There is a list of generic shadow parameters, each also has a specific function:

  • Enabled: Check to enable shadow mapping in this light.

  • Opacity: Areas occluded are darkened by this opacity factor. Shadows are fully opaque by default, but this can be changed to make shadows translucent for a given light.

  • Bias: When this parameter is too low, self-shadowing occurs. When too high, shadows separate from the casters. Tweak to what works best for you.

  • Normal Bias: When this parameter is too low, self-shadowing occurs. When too high, shadows appear misaligned from the casters. Tweak to what works best for you.

  • Transmittance Bias: When this parameter is too low, self-shadowing occurs on materials that have transmittance enabled. When too high, shadows will not affect materials that have transmittance enabled consistently. Tweak to what works best for you.

  • Reverse Cull Face: Some scenes work better when shadow mapping is rendered with face-culling inverted.

  • Blur: Multiplies the shadow blur radius for this light. This works with both traditional shadow mapping and contact-hardening shadows (lights with Angular Distance or Size greater than 0.0). Higher values result in softer shadows, which will also appear to be more temporally stable for moving objects. The downside of increasing shadow blur is that it will make the grainy pattern used for filtering more noticeable. See also Shadow filter mode.

Below is an image of what tweaking bias looks like. Default values work for most cases, but in general, it depends on the size and complexity of geometry.

If the Shadow Bias or Shadow Normal Bias is set too low for a given light, the shadow will be "smeared" onto the objects. This will cause the light's intended appearance to darken, and is called shadow acne:

../../_images/lights_and_shadows_acne.webp

On the other hand, if the Shadow Bias or Shadow Normal Bias is set too high for a given light, the shadow may appear to be disconnected from the object. This is called peter-panning:

../../_images/lights_and_shadows_peter_panning.webp

In general, increasing Shadow Normal Bias is preferred over increasing Shadow Bias. Increasing Shadow Normal Bias does not cause as much peter-panning as increasing Shadow Bias, but it can still resolve most shadow acne issues efficiently. The downside of increasing Shadow Normal Bias is that it can make shadows appear thinner for certain objects.

Any sort of bias issues can be fixed by increasing the shadow map resolution, at the cost of decreased performance.

Note

Tweaking shadow mapping settings is an art – there are no "one size fits all" settings. To achieve the best visuals, you may need to use different shadow bias values on a per-light basis.

Directional light

This is the most common type of light and represents a light source very far away (such as the sun). It is also the cheapest light to compute and should be used whenever possible (although it's not the cheapest shadow-map to compute, but more on that later).

Directional light models an infinite number of parallel light rays covering the whole scene. The directional light node is represented by a big arrow which indicates the direction of the light rays. However, the position of the node does not affect the lighting at all and can be anywhere.

../../_images/light_directional.png

Every face whose front-side is hit by the light rays is lit, while the others stay dark. Unlike most other light types directional lights, don't have specific parameters.

The directional light also offers a Angular Distance property, which determines the light's angular size in degrees. Increasing this above 0.0 will make shadows softer at greater distances from the caster, while also affecting the sun's appearance in procedural sky materials. This is called a contact-hardening shadow (also known as PCSS).

For reference, the angular distance of the Sun viewed from the Earth is approximately 0.5. This kind of shadow is expensive, so check the recommendations in PCSS recommendations if setting this value above 0.0 on lights with shadows enabled.

Directional shadow mapping

To compute shadow maps, the scene is rendered (only depth) from an orthogonal point of view that covers the whole scene (or up to the max distance). There is, however, a problem with this approach because objects closer to the camera receive low-resolution shadows that may appear blocky.

To fix this, a technique named Parallel Split Shadow Maps (PSSM) is used. This splits the view frustum in 2 or 4 areas. Each area gets its own shadow map. This allows small areas close to the viewer to have the same shadow resolution as a huge, far-away area.

../../_images/lights_and_shadows_pssm_explained.webp

With this, shadows become more detailed:

../../_images/lights_and_shadows_directional_mode.webp

To control PSSM, a number of parameters are exposed:

../../_images/lights_and_shadows_directional_shadow_params.webp

Each split distance is controlled relative to the camera far (or shadow Max Distance if greater than 0.0). 0.0 is the eye position and 1.0 is where the shadow ends at a distance. Splits are in-between. Default values generally work well, but tweaking the first split a bit is common to