Unreal:LightingTroubleshootingGuide

From wiki.vg
Jump to navigation Jump to search

About This Guide

Often the difference between a good game and a great game can come down to light. Even the best model rendered with poor shadow resolution and not taking advantage of the right post process settings will look poor. In the Unreal Engine, it means digging in to our robust lighting, reflection and post process settings. This Troubleshooting guide attempts to cover some of the more common problems that people come across when they first dig into the lighting and rendering systems. This guide is by no means meant to be completely comprehensive but a living document as the engine changes so too can we add and alter advice presented here. The guide is meant to be a great first step for artist trying to get the most out of the engine's rendering system.

Common Lighting Documentation pages for reference:

Lightmass Global Illumination
Lighting Basics
Lighting the Environment
Lighting Content Examples
Lighting for Mobile Platforms
Rendering & Graphics

General Lighting

Why Are My Shadows Black?

In lighting terms, deep black shadows usually mean you have no fill light. This can often happen when doing outdoor environments where a single directional light is meant to represent the sun. UE4 has a built in method to provide a world effecting fill light, we refer to it as a Sky Light. Want to know more about Sky Lights?


Invalid Lightmap Settings When Converting BSP to Static Mesh

When you convert your BSP geometry to a static mesh, you will likely see the following result:

Static Mesh Converted from a BSP Box


Static Mesh Editor Details Panel

Don’t worry, this is normal! Since we’ve now converted our BSP to a Static mesh we need to make sure the right lightmap channel is assigned. To make things easier, when you convert the BSP it will automatically generate your lightmapping UVs for you. The only thing that is not setup is automatically is making sure the right channel and resolution are assigned.

  • To do this, open the newly created Static Mesh. Look to the details panel on the right and locate the tab Static Mesh Settings.
  • Here you’ll need to set the Lightmap Resolution. This should be any power of two increment (ie. 32, 64, 128, etc). This will be the resolution of your lightmap texture. Higher lightmap resolutions will result in better shadow quality baked into the texture, but it will also increase memory foot print and light build times.
  • Next we’ll set the Lightmap Coordinate Index to 1 (This is the lightmap UV channel in most cases). This is the location of our lightmap UV that will have no overlapping faces.
  • If you want to see what the lightmap UV looks like you can click the button for the UV in the toolbar and choose UV Channel 1 from the drop down to the right of the button.



What if I don’t want to have lightmaps at all or my game doesn’t need them

There may be times where a game doesn’t need lightmaps at all, because it’s been opted to use only Movable (Dynamic) lighting. There is an option to disable lightmaps all together by opening the world settings and checking the option for “Force No Precomputed Lighting.” When lighting is rebuilt it will remove all lightmaps that have been previously cooked.

There are two methods to disable Static Lighting:

Project Settings, Rendering Tab, Lighting Tab

Project Specific: Disable Static Lighting

  1. Menu > Edit > Project Settings
  2. Go to the Rendering Tab > Lighting Tab
  3. Uncheck the option for Allow Static Lighting
  4. To enable this option fully you will need to Restart the Editor


Level Specific: Disable Static Lighting

World Settings

1. Open World Settings


Lightmass Settings

2. Go to the Lightmass Tab
3. Uncheck Force No Precomputed Lighting


Force No Precomputed Warning

4. You will get a warning. Click OK.
5. Build Lighting to wipe lighting data already stored.



Two-Sided Lighting for Single Sided Meshes, or Why does my light come through the roof?

Created Assets in 3DS Max

So, you’ve had fun and created some awesome new assets for your game like I’ve done here.

In this image you’ll see I’ve made myself an awesome wall and a tube that when I turn on its side can be a creepy tunnel for me to walk through!


Created Assets in UE4

All seems well and good and I can see that I’ve got my awesome work and I can see both sides of my mesh in my modeling program of choice. However, when it’s imported into Unreal Engine 4 it’s messed up!

So, what gives, because this surely cannot be right?!

This is actually 100% normal. Even though the plane looks good the back face is not being rendered just like the closest faces of our tube mesh.


Wireframe of Created Assets in UE4

When you create your geometry in your modeling program by default the software has set it so that you can see both sides of your geometry.

In UE4 the the backface of a polygon is automatically culled to save on performance, because every little bit helps! It’s not always necessary to have extra polygons or render sides that may not be needed, otherwise there would be extra draw calls that could slow down your performance. with a few instances this probably wouldn’t matter much, but when you’re developing for specific platforms or have a lot going on every draw call starts to matter.

To also understand why we can only see one side we can open our mesh in the static mesh editor and tick the toolbar option for “Normals.” You will see Green lines that point in the direction the face of the polygon is directed. In the image below for our tube asset we can see that the faces where it’s invisible have the lines going towards the center of the mesh. This is the direction that the visible face can be seen.


Static Mesh Editor

Pro Tip: While in UE4 if you have any meshes that have what appears to be invisible geometry or missing faces you can check the normals here before fixing the issue in your modeling software.


Now that we have all the boring stuff out of the way we can get right to fixing our invisible faces with some checkboxes and Materials.

1. (STATIC ONLY)Light as if Two-Sided

  • Enabled this option via the details panel for the selected asset in the Level Viewport.
  • With this option selected, when lights are built lightmass will calculate that geometry into its bake. It will cast a shadow, even though we cannot see it from this angle, to bake into the lightmap texture. This will not work with a movable/dynamic light though since Unreal Engine 4 uses a deferred rendering pipeline.

2. Creating a Two-Sided Material

  • Open the material editor and in the details panel on the left select the option for “Two-sided”.
  • Save and compile your material for this to take effect.
  • This method can be used with Static/Stationary/Movable lighting. Since the material is now being rendered the faces of that were not visible before are no longer being culled and can block the light. Be aware though that this now renders both sides of the mesh adding to your draw calls. As mentioned earlier this won’t necessarily affect performance in smaller scenes or setups, but if you’re targeting hardware where every bit of performance counts this can affect that.


Why does this look nothing like it did before, or Engine Scalability and you

File:1 EngineScalability.png
Engine Scalability Settings

The Engine Scalability settings can be accessed via the Settings > Engine Scalability option in the Toolbar.

The purpose of this is to scale the engine rendering settings to fit machines that may have a more difficult time running smoothly. By default the editor will lower settings here if the FPS drops too low.

There is a option for “Shadows” that will directly affect the shadowing distance of any movable (dynamic) shadows. This is true when the list is set to “Movable” or when lighting has not been built for the static lights yet, since those are using dynamic shadows as temporary indication until your lights are built and baked into lightmaps.


The images below will demonstrate the shadow distance of each Shadow setting in the Engine Scalability tab.

If there are no shadows in your level this is the best place to check first. Even if your system is top of the line these settings can still be automatically set to a lower setting and stay there if the FPS drops too low. It’s a good place to always check before looking at other issues that may be a factor.

If there is a need to not have the auto-scaling on it can be disabled by unchecking the option at the bottom of the Engine Scalability settings window. Do realize that this can cause performance issues as the editor will no longer monitor when there is a need to adjust this to a lower settings to help keep performance up.

Want to know more about Engine Scalability?


Why is there a red “X” over my light?

File:OverlappingLights.jpg
Overlapping Stationary Lights

Stationary lights are limited to a maximum of 4 shadow casting lights being overlapped. When the 5th is added there will be a red ‘X’ indicating that the light in this area of overlapping with the smallest radius will revert to a dynamic light. This can cause performance issue because dynamic lighting that casts shadows is more expensive to use then baked lighting.


If lighting is built with any stationary lights that are overlapping offenders there will be a warning detailing which light is the offender and the ramifications.


To correct this make sure that there are no more than 4 shadow casting overlapping Stationary lights in a single area. This may require the removal of a light, disabling the Cast Shadows flag or adjusting the radius so that it’s no longer overlapping.

If there are only three placed stationary lights and there is a red X over the 4th light make sure that you have no other stationary lights in your level that would be overlapping. Often times this would be the Directional light set to Stationary that is causing this issue.

Want to know more about Stationary Lights?


Dynamic (Movable) Lighting


Shadow bleed or Incorrect Shadow Quality

In this guide we’ll look at areas that will help improve the quality so that the shadows more accurately fit the meshes. This will also help in offering tips to improve dynamic lighting at a distance.

Directional Light ONLY: Cascaded Shadow Maps Settings:

Dynamic Shadow Distance Movable: This is the distance from the camera that shadows will cover. A value of 0 disables this.

Dynamic Shadow Distance Stationary: This is the distance from the camera that shadows will cover. This is set to 0 by default for Directional Stationary Lights

Num Dynamic Shadow Cascades: This is the number of cascades the view frustum will be split into. More cascades will result in better shadow resolution, but will add significant rendering cost. To read more on view frustums take a look at this article: http://en.wikipedia.org/wiki/Viewing_frustum

Cascade Distribution Exponent: This controls whether the cascades are distributed closer (higher value) or further away (lower value) from the camera. A value of 1 means the transition will happen proportional to their resolution.

Cascade Transition Exponent: This controls the proportion of the fade region between cascades. Lower values will give a hard edges between the shadow cascades whereas higher values will blend between the two.

Shadow Distance Fadeout Fraction: This controls the how the shadows fade out at distances. Higher values will fade the shadow out whereas lower values will leave a darker shadow at distances.

Far Shadow Cascade Count: Coming in 4.8. More information to follow soon.

Far Shadow Distance: Coming in 4.8. More information to follow soon.


Adjusting Cascades for better Quality:

Shadow bleed and accuracy can be finely tuned with adjusting a combination of the settings demonstrated above. This next section will attempt to adjust the values that work best to get better accuracy with the shadows while in close proximity and as the camera moves away. Finding a balance that works with any particular game will require time, effort, and lots of testing with what works and what does not.

File:1AdjustingSettings1.png
Basic Scene, Default Settings

Here is the basic scene with only default settings:


There are already a few problems that are prevalent in this scene with shadows accuracy around edges.


File:1AdjustingSettings2 ProblemAreasCloser.png
Highlighted Problem Areas, close-up

More clearly demonstrated here.


File:1AdjustingSettings2 finalResult.png
Default Scene, Final Results

By focusing on the most of the effort around the Cascade Distribution Exponent the shadow bleed can be minimized, within reason of course. The default distance for Dynamic shadows is set to 20,000 units. This isn’t always necessary to which this can be set to a lower value to better utilize the cascades.

If the game level is to use indoor and outdoor scenes finding a combination that fits all or most areas will be difficult and require lots of tweaking. There is no one setting that will make everything look perfect.

In this scene by adjusting the settings for the Distribution, the Shadows Distance, and Number of Cascades the bleed and accuracy are acceptable.


All Dynamic Lights (Light Tab Settings):

Lastly, there are two other settings under the light tab in our light source that can benefit lighting accuracy as well.

These settings can be found here:

Shadow Bias will control how accurate shadows are in the scene, but will generate artifacts if set to a value that is too low. The default value is 0.5 which is a good trade off between how accurate and effective it is.

Shadow Filter Sharpness can help mask some of the artifacting that occurs with lower values and this directly contributes to how sharp the edges of the shadows are as well.

Taking into account that none of the previous settings have been adjusted for these images these are some examples to demonstrate Shadow Bias and Shadow Filter Sharpen.

The key here is to find a good balance without going too low and using the setting under the tab for Cascaded Shadows.

Most notably the higher the value for the sharpen filter the shaper your shadows. The soft edge created by the lower values will now be lost.


Why does my Movable light shine through my mesh at far distances?

Dynamic lights, especially point lights, cause this kind of issue to crop up. Unreal Engine 4 does a good job of trying to optimize things so that you don’t have to worry about it so much. The problem is sometimes it gets carried away and can cause things like this to happen that may not be obvious how to fix.

So, what gives?!

To explain this we need to discuss that awesome optimizing the engine does for you. The engine uses scene depth to determine what should be visible and what shouldn't be visible for rendering. Since we have a point light here that shoots light throughout it’s set radius when the mesh is beyond its bounds it will be occluded or no longer rendered. This causes the issue that we’re seeing with our light starting to cast in all directions.

You can see from this image that as the camera is further away the occlusion of parts of the mesh start to halo around the outer edge until the light is free to cast in all directions.

You may notice that if you select the mesh when far away that the light returns to normal. This is expected as you have just selected the mesh and it is now focused.

File:Detailspanel.png
Object Bounds, Details Panel, Rendering Tab

To keep the mesh from being occluded you’ll need to select the mesh and go to the details panel. Here you can search or scroll for the “Bounds Scale” (Located under the Tab for Rendering.)


The default value is set to 1.0. When increasing this scale be sure to only use incremental small numbers. Using a value of 2.0 doubles what the distance was set to which can be overkill. Try increasing by smaller incremental values. (ie. 1.1, 1.2) There is no need in pushing to have more than you need as this can impact performance and shadow quality.

You can visualize your meshes bounds by going to the viewport > Show > Advanced > Bounds

You will see something like this:

Additional notes:

If you’re having issues with your mesh occluding, but don’t want to increase the bounds scale due to performance concerns you can try using a Spotlight. Since this only casts light in a single direction you won’t notice the light of a point light casting in all directions when the mesh is occluded. This works well for situations similar to what has been demonstrated, but testing may need to be done on your part to get things just right.

Alternatively, you could forego a fully movable/dynamic light and use a stationary light that bakes a lightmap texture, which can also save on performance by having zero overhead during runtime for rendering shadow information.


Static Lighting


Lightmap Resolution / Shadow Quality

Every project has its own unique art direction and goals, so this section is meant to present common concepts and give you a foundation to begin achieving what you want from your static lighting. By no means will the settings we present here work all the time for every project.

There are 3 objects in this scene; two walls and a floor mesh. Each object has is own shadows that are baked into a texture known as a lightmap. This lightmap stores any shadow/light information that is being cast on to it in this texture. It is normally handled by an artist in the asset creation. 'Want to know more about lightmaps and how to create them effectively?

In other words, If I wanted to increase the resolution of the shadow cast by the wall with the doorway, I would not adjust the doorway, but instead would adjust the floor’s lightmap resolution. This is where the shadow is being cast and baked into a lightmap.

Now with that out of the way, we may need to increase lightmap resolution for some meshes and not others. Each mesh has it’s own lightmap Resolution that can be set via the details panel when the mesh is selected or via the mesh editor.

For this lightmap quality demonstration we’ll look at the floor meshes lightmap resolution only.

When adjusting LM resolution make sure it is using a power of two (32 [default in engine], 64, 128, etc) with exception of BSPs (Covered below)

A lot of the quality in this lightmap resolution will depend on two factors: Size of the mesh and the size of the UV shells in the lightmap UV.

The key to difference to note about using lightmaps on BSPs versus Static Meshes is that it doesn't increase, but instead decreases to get better resolution.

While adjusting the lightmap resolution to get better results there are trade offs here. Using a smaller mesh will allow you to get better results for the floor with a lower lightmap resolution, while using this larger mesh you will need to increase the lightmap resolution and the texture will use more resources for your games.


What is this “Overlapping UV error” non-sense when I build lighting?

When using static or stationary lighting it is imperative to use two UVs for your meshes otherwise you will get the following warning when you build lighting:

This means that you’ll need to setup a second UV channel for your lightmap otherwise the editor will use the existing texture UV as the lightmap which can lead to these kinds of errors.

This can be fixed by adjusting the UV for the lightmap so that there are no overlapping faces.

This can be done in the editor via generating lightmaps or by using your modeling software of choice to create and edit your UVs.

Take notice that the the UV in the final result has no overlapping faces which allows shadow/light information to bake correctly for the texture that will be applied to our mesh after the light build.

With the overlapping faces these will give incorrect shading due to lighting information not being baked correctly.


How do I generate lightmap UVs in the editor?

With the release of 4.5 the editor will automatically generate UVs on import or by using the mesh editor.

We will assume you’re wanting to set them up from the mesh editor.

  • Open the mesh you’d like to create a lightmap with.
  • Locate the panel on the right that looks like this:

This panel will allow you to create your lightmap channel, but do note that this does not directly control your lightmap resolution or it’s coordinate index assignment. These will be covered a little later.

The settings here in the “Build Settings” tab that we will focus on are:

Generate Lightmap UVs = make sure this is checked.

Min Lightmap Resolution = This is the smallest size you would want your lightmap resolution to be.
Source Lightmap Index = This is the source which we will generate our lightmap UVs from.

Destination Lightmap Index = This is the location we will store this UV when it is created.

For most assets this should be a good setup. The key here is making sure that we select the proper source lightmap index. This is the UV that is typically used for the textures. The UV shells/islands in this UV will be repacked so that there are no overlapping faces, which is integral to using lightmaps.

For the lightmap resolution setting a low value to begin with is not bad because we are not obligated to using that resolution. If you decide to use a higher resolution you do not need to come back to these settings unless you know it could improve the lightmap bake. In most cases it’s not necessary.

Once you’ve hit “Apply Changes” we can verify our lightmap has been created and see if there appears to be any errors.

You can do this by going to the mesh editor toolbar and clicking the UV icon to show the UV and using the drop down to the right to select UV channel 1 to view our newly created lightmap.

It should look something like this:

That’s not quite it though. We still need to assign the correct UV channel to be used for our Lightmap.

In the mesh editor in the details panel on the right locate the tab labeled “Static Mesh Settings”

File:LightmapUVSet.PNG
Static Mesh Editor Details, Lightmap Settings
  • In this tab we’ll need to adjust the lightmap resolution for what we’d like here.

32 is the default lightmap resolution. For smaller objects this would work well. For larger objects we would possibly need to use higher resolutions.

Make sure to adjust it by a power of 2. (ie. 32, 64, 128, 256, etc)

  • The next setting we’ll need to verify is that the Lightmap Coordinate Index is now pointing to the right channel. Make sure this is set to the channel that you set in the build settings above. Typically this should be set to 1.

After using these settings you will now have a proper lightmap resolution.


There are some caveats to this though that may require the use of a modeling program like Blender, 3Ds Max, or Maya to fully correct the issue.

The generated lightmaps will not split or cut seams in the existing UVs from UV channel 1 used for the texture. It will only repack the existing UV layout to better fit the needs of a lightmap UV.

As an example, think of a cylinder. If you wanted to lay these faces all out flat you would need to cut a line in the side of the cylinder to do so. In a modeling program this isn’t always necessary depending on how you’ve set up the texture UV to be used. If this side face was not cut to be laid out flat the generated UVs via the mesh editor will not work and will still result in overlapping UVs warning being generated after a light build.


How to control Global Illumination with Static Lighting?, or The Wonderful Thing About Bounce

When using static lighting you will need to build lighting to see the results. Lightmass is used to compile and generate textures that will store this light and shadow information for our scene by baking this information into a lightmap texture.

By default lightmass is set to use 3 light bounces to get GI with static lighting. If more is needed we will need to directly change the lightmass settings to get different results via our World Settings tab. We can affect our Global Illumination directly by changing the number of bounces that the light will cast.

To enable World Settings tab you’ll need to go to the Toolbar and select Settings > World Settings

File:LightmassSettings.png
Default Lightmass World Settings

Click on the the World Settings tab next to the Detail Panel tab on the right side.

Here you’ll see a lot of settings that can affect how our light is handled with lightmass that will directly affect our scene. For GI we’re only going to focus on the second option down “Num of Indirect Lighting Bounces.” The slider is clamped to be a value between 1 and 4. You can override this by manually typing in a value though.

The default settings are shown to the right.


The first bounce takes the longest to calculate. Successive bounces will have less impact on actual build times, but they will also have a much lower visual impact.


Want to know more about Lightmass and Global Illumination?

Why is there shadow splotches on my static mesh?, or How to clean those dirty lightmaps?

Show stains, splotches, dirtiness, or whatever name you have for it is a common issue with UE4 when using any type of static lighting. Fear not though because we can get rid of those dirty lightmaps with a little scrubbing through our lightmass settings.

First though, the reason you see something like this is related to the indirect light from our GI bounces that happen with our lightmass build.

To replicate this in a mostly effective way this simple scene will have two rooms.

This scene will be using PRODUCTION quality for our light builds. This scene is using assets from the Starter Content pack that can be added to any newly created project. All meshes in the scene will use a lightmap resolution of 256 unless otherwise noted. The post process effects are set to default with eye adaptation to make the darker room easier to see.

After building our lighting, here are the results:

Brute force can be used to remove some of the indirect lighting artifacts by increasing the lightmap resolution which effectively increases the size of the textures used to store the lighting and shadowing information, but that’s not always the best idea when a high quality result can be achieved using a lower resolution and adjusting the lightmass settings. When dealing with any rendering application in the engine and especially lighting just increasing a texture size, though it may appear to solve the issue is not always the most performance friendly way to handle an issue and may even result in more problems further along in your development process.

As any example this is the same 2nd Interior Room with lightmap resolution changed to be 1024:

In this example a lot of the artifacts have been reduced by using the higher lightmap resolution, but this also increases the texture memory footprint by a factor of 4. There is a more performance friendly solution to these Indirect Lighting Artifacts with some simple adjustments to the World Settings.

  • You can locate World Settings here:


  • Here the settings for Lightmass can be adjusted:


Indirect Lighting Quality: This will increase the Global Illumination solver counts to get a higher quality for levels that need it.

Indirect Lighting Smoothness: This is the smoothness factor to apply to Indirect Lighting.

WARNING: Using a Value greater than 1 in the Indirect Lighting Quality will GREATLY increase build times.


As mentioned in How to control Global Illumination with Static Lighting?, or The Wonderful Thing About Bounce, you may also want to adjust the number of indirect light bounces which will yield the following results:

At this point, the lighting settings have been adjusted enough that there may be room to hide any artifacts with some textures, but if that’s not the option there is the option to bump the lightmap resolution for each mesh up to a higher value. The value used here is 256 for the lightmap resolution. By changing it to be 512 we get the following result:

In the beginning of this tutorial there was a comparison shown using Lightmaps of 1024 that helped get rid of the artifacts. By adjusting a few lightmass settings the artifacts have been reduced and the assets are using a lower texture resolution with better results.

While this method is fully exploring the option of not having any light in this room and looking at ways to reduce the “dirtiness” artifacts that can be caused by Indirect Lighting it must be noted that using lighting can in these areas, even a very low intensity non-shadow casting light, can get results as well. The methods listed above are a starting point and may require a little trial and error to get the results that are more appealing.

Want to know more about Lightmass Basics?

Want to know more about Lightmass Global Illumination?


What is the “Lighting needs to be rebuilt” in the Top left corner error?

If this is appearing in your top left part of your viewport window when using PIE (Play in Editor), Simulate, or Standalone game this simply means that lighting needs to be rebuilt for your scene. This will only affect Static and Stationary lighting. Dynamically lit scenes do not need to have lighting built.

This warning is caused when lighting has been invalidated by moving or modifying a light Actor. This can cause problems because the rendered lighting in the level is not accurately representing the current state of lights in the level. This error can be solved by going to the Build menu and rebuilding lighting for a map.



Lighting Quality comparison, or Production > Preview

When lighting needs to be built for a level the quality of the light build for lightmaps can be set in the toolbar by going to the options for Build > Lighting Quality > and selecting a quality level.

By default the Quality is set to Preview. This setting has the fastest computation time whereas Production will have the slowest computational time, but be much more accurate.

The Lighting Quality settings can be found here:

For this demonstration there will be a enclosed room to show the quality of the shadows being built: (This will be the same scene setup used for #Why is there shadow splotches on my static mesh?, or How to clean those dirty lightmaps?

In this example it’s easy to see the difference between the default Preview setting and Production setting. With Production almost all of the light leaking that was prevalent in the previous quality settings is gone. This is a good way to troubleshoot your lighting issues if there is light leaking. If Production doesn’t get rid of the light leaking then it’s time to have a look at how the lightmap UVs are set up or possibly the placement of the meshes in your level.

With the Statue static mesh in this scene it’s not as easily noticeable that the shadow quality has been adjusted. There is slight differences in quality, but not enough to tell with the particular object.

File:11 StatueQuality.gif
Statue Lighting Quality

In this animated Gif the quality differences are minuscule from this perspective. This behavior is expected for more organic shapes. The human eye notices non-organic straight lines (like Architectural right angles) before curved or more organic shapes given the same color and brightness. As a note, the jaggedness of the shadows on the ground plane are the result of having a lower lightmap resolution for a larger mesh. Increasing the lightmap resolution will improve the quality of the shadow definition.