SDFGI: configuring cascades and lighting

SDFGI

SDFGI builds a representation of static geometry around the camera and updates indirect lighting during runtime. No separate VoxelGI volume or baked data file is required, but results accumulate over frames. It runs in Forward+; Mobile and Compatibility do not provide this SDFGI path.

A large world does not mean infinite GI distance: a finite set of cascades surrounds the camera. A moving door can receive indirect light without becoming a correct dynamic SDFGI occluder. Evaluate VoxelGI for dynamic geometry.

Enable it in a level

1. Confirm the actual renderer is Forward+, rather than a fallback.
2. Set participating stationary geometry to MeshInstance3D.GIMode = Static. Dynamic and Disabled do not add it to SDFGI's static representation.
3. Create a WorldEnvironment with an Environment. Check whether the active Camera3D overrides it with its own resource.
4. Enable SdfgiEnabled in the Environment actually used. For a closed room start without sky contribution or feedback; add them after verifying the base result.
5. Allow lighting to accumulate after loading or moving the camera. Compare settled frames while keeping exposure and other effects identical.

Example configuration for an existing indoor Environment; WorldEnvironment assignment and geometry must already be prepared:

using Reckfell;

public static class GiSettingsExample
{
    // Apply to the Environment actually used by the active camera.
    public static void ConfigureIndoorSdfgi(Environment environment)
    {
        environment.SdfgiEnabled = true;
        environment.SdfgiCascades = 4;
        environment.SdfgiMinCellSize = 0.2f;
        environment.SdfgiReadSkyLight = false;
        environment.SdfgiUseOcclusion = true;
        environment.SdfgiBounceFeedback = 0f;
        environment.SdfgiEnergy = 1f;
    }
}

This is a diagnostic starting point, not a maximum preset for every game. SdfgiUseOcclusion adds cost and may reduce leaks; inspect your own geometry. SdfgiReadSkyLight = false does not disable direct lighting or other ambient-light sources.

Set coverage and detail

Three properties are linked in the current API:

With 4 cascades and cell size 0.2, for example, the distances are 12.8 and 204.8 units. Do not assign all three as independent settings: the last distance assignment changes the previously selected cell size. Valid cascade counts are 1…8; more cascades require additional data and work, rather than guaranteeing a better image.

Choose coverage for the visible region and level detail. Do not treat cell size as a promise of arbitrary world scale at no cost.

Changing objects and lights

Static geometry enters a cascade representation when it updates. Moving that geometry near the camera may leave the old representation in place. For layout changes check SDFGI recreation or cascade updates; this is not a method for continuously animated doors and walls.

Dynamic lights and dynamic occluders are different capabilities. Use the appropriate dynamic BakeMode for a moving light; this does not enable dynamic geometry. Indirect contribution also depends on the light's IndirectEnergy. Static emission participates; do not rely on a moving emissive surface as a correct dynamic SDFGI source.

Diagnose overexposure and instability

• The room becomes brighter over several seconds: start with SdfgiBounceFeedback = 0, then check energy and emission. Add feedback gradually. Do not compensate for runaway lighting only by lowering exposure.
• Light leaks through a thin wall: check thickness and closed geometry relative to cell size. Compare UseOcclusion, then small NormalBias/ProbeBias adjustments. Excessive bias can increase leaks.
• Wrong lighting after moving an object: confirm you are not expecting a dynamic SDFGI occluder. Switching GIMode to Dynamic does not remove this limitation.
• Splotches after loading: allow accumulation and check ray count/convergence frames. More frames mean slower response, not instant improvement.
• Popping during fast camera motion: check cascade boundaries, coverage and GPU budget. Fog or a transition fade can conceal the effect but does not repair wrong lighting.
• Settings change without a frame change: check the active Environment, renderer, static meshes and whether another effect obscures the result.

Project settings are rendering/global_illumination/sdfgi/probe_ray_count, frames_to_converge, frames_to_update_lights; shared GI-buffer resolution is controlled by rendering/global_illumination/gi/use_half_resolution. Ray/frame-count settings use enumerated choices: do not supply an arbitrary count as an enum index. Measure quality and frame time on the target GPU, especially during camera movement.

Verified scope

The installed Forward+/Vulkan runtime was checked for the example's settings, cascade-distance relationships and actual indirect light from static emission using an SDFGI on/off comparison. The functional GPU run used one cascade with occlusion disabled to isolate the effect; it does not validate the entire four-cascade configuration, a large world or dynamic lights.

See the GI overview for method comparison.