VoxelGI: baking and diagnosing light leaks
Size, static geometry, .rbin data and result checks.
VoxelGI
VoxelGI computes indirect lighting inside a defined volume. Static geometry is prepared by baking; using the result and evaluating lighting happens during rendering. It does not provide fully dynamic geometry without preparation.
Use Forward+. VoxelGI is not a way to obtain the same result in Mobile or Compatibility. See the GI overview for method selection.
Prepare the volume
- Open the
.rscenelevel and check lighting, materials and normals without GI. Fix duplicate lights and intersecting geometry first. - Set participating static MeshInstance3D objects to
GIMode = Static. An empty MeshInstance3D, hidden geometry or an object outside the volume will not produce the required bake data. - Add a VoxelGI Entity beneath the common level root, alongside the geometry. By default baking traverses the VoxelGI parent and its descendants. With the API, pass the intended root to
Bake(root). - Position the volume and set
Size. This is the full box length on each axis, not half-extents. Size = (8, 4, 8), for example, covers −4…+4 on X/Z and −2…+2 on Y relative to its center. - Choose Subdiv. Values 64/128/256/512 determine the longest-axis detail; shorter axes adjust accordingly. Do not enlarge the volume to cover the world for one room: its cells become coarser.
- Select VoxelGI and use
Bake VoxelGI. On the first bake save external.rbindata. The editor proposes this extension; do not follow the old.resrecipe. - Confirm
Datacontains VoxelGIData, then save the level. The data should remain assigned after reopening.
Missing Data means no prepared volume. Do not compensate for an empty bake by increasing Energy. Hiding VoxelGI for comparison is valid; hiding geometry before baking and expecting it to remain in the bake is not.
When to bake again
Rebake after changing static meshes, their placement, materials, emission, volume bounds or subdivision. Merely saving the level does not rebuild old data.
| Geometry mode | Behavior |
|---|---|
Static | Participates in VoxelGI preparation and receives indirect light. |
Dynamic | Excluded from static baking; dynamic VoxelGI participation requires additional rendering work and is not free. |
Disabled | Excluded from baked geometry. This is not a universal switch disabling receipt of GI or direct light. |
The checks here used static MeshInstance3D objects with StandardMaterial3D. Do not assume arbitrary ShaderMaterial results are fully reproduced during static baking: the voxelizer extracts BaseMaterial3D properties. Check a small representative region for a complex material first.
Data settings
| VoxelGIData property | Purpose |
|---|---|
Interior | Exclude sky contribution from VoxelGI in a closed room. Does not fix holes or direct light. |
Energy | Scale indirect light. Configure lights and emission first; increasing Energy does not repair geometry. |
Bias, NormalBias | Offset sampling to reduce self-occlusion. Excessive offset may increase leaks through walls. |
Propagation, UseTwoBounces | Light propagation and additional bounces. Compare the frame and cost on the target GPU; there is no universal free improvement. |
DynamicRange | Representable energy range. Do not use as an arbitrary substitute for camera exposure. |
Keep the camera, exposure, lights and postprocessing identical for comparisons. Disable only the contribution being tested.
Diagnose an artifact
- Light passes through the ceiling: check closed geometry, ceiling thickness, normals and actual cell size, then Bias. A wall thinner than a cell may be poorly represented.
- The upper room is overexposed: isolate direct lighting from GI, then check sky contribution, emission and exposure.
Interiordoes not disable a direct DirectionalLight3D. - A moved static object retains old lighting: rebake and confirm the assigned Data resource is the one saved.
- No volume contribution: check the actual Forward+ renderer, Data, VoxelGI visibility and overlap with receivers.
- Dirty or striped details: first shrink unnecessarily large bounds and check sufficient subdivision; increase Bias in small steps while inspecting leaks on the other side of surfaces.
- Lighting changes when turning the camera: avoid excessive volume overlap. Current Forward+ stores up to 8 VoxelGI instances in its GI buffer; do not design many overlaps as infinitely blended lighting.
The global rendering/global_illumination/gi/use_half_resolution setting affects both VoxelGI and SDFGI. Lower resolution may save GPU time but needs thin-detail inspection. Measure image quality and frame time separately.
Verified scope
The installed Forward+/Vulkan runtime was checked for static emissive-geometry baking, nonempty VoxelGIData, .rbin saving and independent reloading, indirect light appearing on previously dark surfaces, and its removal when hiding the volume. This is a functional check, not acceptance of every model, performance or dynamic geometry.
For a larger world with static geometry consider SDFGI; for precomputed lighting see LightmapGI.