Troubleshooting

Common issues and their solutions when using Umbra Soft Shadows.

Shadow Artifacts or Discontinuities Over Distance

If shadows show banding, softness changes, or visual breaks at different distances:

1. Adjust cascade splits in the URP asset — increase the distance for Split 1.
2. Reduce shadow bias / normal bias on the Directional Light and lower the Near Plane value.
3. Enable Blend Cascades in Umbra's Advanced section and tune the blending distance.
4. Adjust Cascade Scales to fine-tune the per-cascade calculation.

Objects Not Casting Shadows

If certain objects do not cast shadows under Umbra:

• Ensure the object's shader includes both ShadowCaster and DepthOnly passes.
• Test with Unity's Standard or Simple Lit shader to confirm the issue is shader-related.

Soft Shadows Appear Cut or Clipped

When the penumbra appears truncated at the edges:

• Increase Search Radius in the General Settings section. A low value can clip the soft edge calculation.

Flickering with Amplify Impostors

There is a known bug in the Octahedron shader included with Amplify Impostors that ignores shadow coordinates when shadows are set to screen space. To fix, edit the Amplify shader and locate these lines:

#if defined(_MAIN_LIGHT_SHADOWS)
    inputData.shadowCoord = TransformWorldToShadowCoord(inputData.positionWS);
#else
    // inputData.shadowCoord = float4(0, 0, 0, 0);   // BUG
    inputData.shadowCoord = float4(inputData.normalizedScreenSpaceUV, 0, 1);   // FIX
#endif

Volumetric Fog 2 — Receive Shadows Not Working

If the Receive Shadows feature on a Volumetric Fog 2 volume stops working when Umbra is enabled:

• Change the Render Pass Event on the Volumetric Fog 2 render feature from Before Rendering Transparents to Before Rendering Post Processing.

Shadow Lag During Fast Camera Movement

If shadows appear to trail behind during quick camera rotations:

• Disable Frame Skip Optimization in the Advanced section. This feature reuses the previous frame's shadow texture.

Custom or Third-Party Shaders Not Receiving Umbra Shadows

Umbra renders soft shadows into a screen-space texture (_ScreenSpaceShadowmapTexture) and activates the _MAIN_LIGHT_SHADOWS_SCREEN keyword so URP routes shadow sampling to that texture instead of the regular shadowmap. For any shader to receive Umbra shadows, it must support this keyword.

Requirements

1. Declare the screen-space shadow keyword in the shader's forward pass:

   #pragma multi_compile _ _MAIN_LIGHT_SHADOWS _MAIN_LIGHT_SHADOWS_CASCADE _MAIN_LIGHT_SHADOWS_SCREEN

   If the shader only declares _MAIN_LIGHT_SHADOWS or _MAIN_LIGHT_SHADOWS_CASCADE but not _MAIN_LIGHT_SHADOWS_SCREEN, it will ignore Umbra's texture and fall back to Unity's default hard shadows or no shadows at all.
2. Include URP's Shadows library:

   #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Shadows.hlsl"

3. Sample shadows using URP's built-in function:

   half shadowAtten = MainLightRealtimeShadow(shadowCoord);

   When _MAIN_LIGHT_SHADOWS_SCREEN is active, this function automatically reads from Umbra's screen-space texture. Do not sample the shadowmap directly.
4. Include ShadowCaster and DepthOnly passes — objects must also cast shadows into Unity's shadowmap for Umbra to process them.

Common Symptoms

• No shadows at all on objects using a custom shader — the shader is missing the _MAIN_LIGHT_SHADOWS_SCREEN keyword variant.
• Hard shadows instead of soft — the shader declares the shadow keywords but samples the shadowmap directly instead of using MainLightRealtimeShadow().
• Shadows disappear on transparent objects — this is expected. Umbra disables screen-space shadows before the transparent pass and reverts to cascade shadows. Use the Transparent Receiver Plane feature for transparent surfaces.

Check the included SimpleShader.shader in the Demo folder for a minimal working example.