Search public documentation:


Interested in the Unreal Engine?
Visit the Unreal Technology site.

Looking for jobs and company info?
Check out the Epic games site.

Questions about support via UDN?
Contact the UDN Staff

UE3 Home > Lighting & Shadows > Light Environments
UE3 Home > Level Designer > Light Environments
UE3 Home > Lighting Artist > Light Environments

Light Environments

Document Changelog: Created by Daniel Wright.


Light environments provide Level Designers with an automated way of controlling dynamic lighting by approximating the effect of relevant static lights. Together with modulated shadows, light environments were used on all characters and vehicles and most other dynamic objects in Gears of War and Unreal Tournament 3.

Why Light Environments are Needed

Without light environments, Level Designers are forced to maintain at least 2 sets of lights, static-only lights and lights affecting dynamic objects. Overlapping between these is often not possible because too many lights affecting the dynamic objects incurs a performance hit, and only using some of the static lights on dynamic objects results in incorrect lighting on dynamic objects and reduces the flexibility of the lighting system.

How Light Environments Work

A light environment gathers the static and dynamic lights that affect its subject, and reproduces those lights on the subject with a fixed rendering cost. It approximates all the lights affecting the character with a spherical harmonic light and a directional light.

The environment culls lights that wouldn't affect the character due to shadowing by using a ray check from the light to a point in the subject's bounds. By default, only one ray is used, but the DynamicLightEnvironmentComponent's NumVolumeVisibilitySamples can be used to specify that multiple rays should be checked to allow for fractional visibility.

For each light the environment finds that affects the character, it projects that light into a low order spherical harmonic basis. The projection maintains the light intensity and color, but blurs the angle they are incident on the subject from. The information lost in the blurring is essential to the spherical harmonic basis's ability to represent an unlimited number of lights in a fixed set of spherical harmonic coefficients.

Once the environment has projected all relevant lights into the spherical harmonic basis, it approximates the bounced lighting from those direct lights that would affect the subject. The approximation is to simply take a fraction of the direct lighting, saturate it, reflect the angle it comes from, and add it with the direct lighting to get the total lighting. The bounced lighting approximation is controlled by DynamicLightEnvironment's BouncedLightingIntensity and BouncedLightingDesaturation members.

The directional light is used to synthesize the lighting coming from the dominant lighting angle, where the dominant lighting angle is the angle that has the highest luminance in the spherical harmonic projection of the lighting incident on the subject.

The spherical harmonic light is used to synthesize all the light that the directional light doesn't account for. Because of the angular blurring of the spherical harmonic basis used to represent the composite lighting, the SH light cannot accurately reproduce high frequency specular reflections, so specular reflections from the SH light are ignored entirely as an optimization.

Light environments also optionally cast a single modulated shadow from a composite of the subset of the lights affecting the environment that have bCastCompositeShadow=True. The environment's spherical harmonic light isn't affected by the environment's modulated shadow, but the environment's directional light is.



These are the relevant settings available to each light:



For a light to affect the shadow direction it must have bCastCompositeShadow=True. The default is true for all light types; prior to Epic changelist 208754 it was false by default on point lights and spot lights. For lights with this set to false they will be used to affect the light environment's composite lighting but not its composite shadow.

bCastCompositeShadow also controls whether non-light-mapped lights are affected by modulated shadows; a dynamic light with bCastCompositeShadow=False won't be affected by modulated shadows from any light. bCastCompositeShadow is ignored on light-mapped lights, since the light will be rendered as part of the composite light-map; all light-mapped lights are affected by modulated shadows.

CompositeDynamic channel

All lights are in the CompositeDynamic channel by default, however you still need to have lights in the dynamic lighting channel if you have any primitives which don't use the composite light environment. Note that the CompositeDynamic channel is a separate flag from the Dynamic lighting channel as an optimization. There will typically be many lights that are CompositeDynamic but not Dynamic, and lights in the Dynamic lighting channel need to be checked for relevance whenever a primitive is reattached to the scene.

Primitive's LightEnvironment

These are the settings available in the LightEnvironment, which can be set on SkeletalMeshActors for example.



  • AmbientGlow - Ambient color added in addition to the level's lighting.
  • AmbientShadowColor - The color of the ambient shadow.
  • AmbientShadowSourceDirection - The direction of the ambient shadow source.
  • bCastShadows - Whether the light environment should cast shadows
  • bDynamic - Whether the light environment should be dynamically updated.
  • bFreeze - Whether the light environment state should be frozen. (This property is no longer editable in newer builds.)
  • BouncedLightingIntensity - The intensity of the simulated bounced light, as a fraction of the direct incident lighting.
  • BouncedLightingDesaturation - The desaturation blend to apply to the simulated bounced light. Typically this will be negative to make the bounced lighting more saturated.
  • bSynthesizeDirectionalLight - Whether a directional light should be used to synthesize the dominant lighting in the environment.
  • bSynthesizeSHLight - Whether a spherical harmonic light should be used to synthesize all light not accounted for by the synthesized directional light. If not, a sky light is used instead.
  • InvisibleUpdateTime - The number of seconds between light environment updates for actors which aren't visible.
  • LightDesaturation - Desaturation percentage of level lighting, which can be used to help team colored characters stand out better under colored lighting.
  • LightDistance - The distance to create the light from the owner's origin, in radius units.
  • LightShadowMode - Type of shadowing to apply for the light.
  • MinTimeBetweenFullUpdates - Minimum amount of time that needs to pass between full environment updates.
  • ModShadowFadeoutExponent - Exponent that controls mod shadow fadeout curve.
  • ModShadowFadeoutTime - Time since the caster was last visible at which the mod shadow will fade out completely.
  • NumVolumeVisibilitySamples - The number of visibility samples to use within the primitive's bounding volume.
  • ShadowDistance - The distance for the shadow to project beyond the owner's origin, in radius units.
  • ShadowFilterQuality - Quality of shadow buffer filtering to use on the light environment


  • bEnabled - Enables the LightEnvironmentComponent. When the LightEnvironmentComponent is enabled, the DynamicLightEnvironment treats the primitives that are in the Dynamic lighting channel as being in the CompositeDynamic lighting channel instead. The dynamic channel is unique in this regard, no other channels are reinterpreted by the DynamicLightEnvironmentComponent.


Shadow pointing down after enabling LightEnvironmentComponent.bEnabled

If no lights affecting the environment's subject have bCastCompositeShadows=True, the object's shadow will point straight down (or whatever direction is specified by the environment's AmbientShadowDirection property).