Local reflections: configure ReflectionProbe

ReflectionProbe stores a local environment capture for materials using reflected light. It approximates the scene from one capture origin; it is not an exact mirror image from every pixel position. The probe influence volume and the objects included in its capture are configured separately.

For an isolated reflection test without ambient, use a material with DisableSpecularOcclusion = true. The reason and scope of this setting are explained below.

Place a probe in a room

1. Add a ReflectionProbe Entity to the intended 3D world. Place it inside the room and outside solid geometry.
2. Set Size to full X/Y/Z dimensions. For example, (8,4,6) means width 8, height 4 and depth 6, not half-extents. Do not scale the Entity instead of setting Size.
3. Set Origin Offset, the capture-origin offset from the center. It does not move the influence box. For valid positive Size, the engine constrains it inside the bounds with a 0.01 inset; reducing Size can change the stored OriginOffset.
4. Try Box Projection for a rectangular room. Direction correction helps fit the reflection to a box, but does not reconstruct actual room geometry or remove every parallax error.
5. For diagnosis, use an opaque material with low Roughness and a visible reflection response. An unshaded material is unsuitable for testing lighting received from a probe.

Distinguish the two masks

Masks contain bits, not layer numbers: 1u selects layer one, 2u layer two, and 3u both. Hiding an object from a reflection and preventing it from receiving reflections are different operations. To exclude the reflector itself from capture, configure CullMask; keep its layer in ReflectionMask if it should receive the result.

Configure it from C#

This helper creates interior-probe settings: no additional ambient contribution, box correction and Once updates. It validates dimensions before passing them to the engine. Construction alone does not confirm GPU capture completion.

using System;
using Reckfell;

public static class ReflectionRoom
{
    public static StandardMaterial3D ReflectiveMaterial(Color color)
    {
        return new StandardMaterial3D
        {
            AlbedoColor = color,
            Metallic = 1.0f,
            Roughness = 0.15f,
            DisableSpecularOcclusion = true,
        };
    }

    public static ReflectionProbe Create(Vector3 size, uint captureLayers, uint receiverLayers)
    {
        if (!float.IsFinite(size.X) || !float.IsFinite(size.Y) || !float.IsFinite(size.Z) ||
            size.X < 0.02f || size.Y < 0.02f || size.Z < 0.02f)
            throw new ArgumentOutOfRangeException(nameof(size), "Use finite positive full dimensions of at least 0.02 units.");
        return new ReflectionProbe
        {
            Size = size,
            BoxProjection = true,
            Interior = true,
            AmbientMode = ReflectionProbe.AmbientModeEnum.Disabled,
            UpdateMode = ReflectionProbe.UpdateModeEnum.Once,
            CullMask = captureLayers,
            ReflectionMask = receiverLayers,
            MaxDistance = 0,
        };
    }
}

Call ReflectionRoom.Create(new Vector3(8, 4, 6), 2u, 1u) and AddChild the returned Entity to the intended 3D world, then place it in the room. This is a configuration example: successfully checking its fields does not replace inspecting a completed reflection. Do not free internal RIDs owned by the probe.

What the parameters change

MaxDistance defaults to 0. The effective far plane also accounts for Size and OriginOffset, so 0 does not disable the probe. This is not the probe visibility distance from the main camera.

AmbientMode.Disabled adds no diffuse probe ambient contribution. Environment uses captured environment information; Color uses AmbientColor multiplied by AmbientColorEnergy. This contribution is not a complete multiple-bounce lighting simulation. Do not compensate for an unlit interior by arbitrarily increasing probe brightness.

Black reflections with zero ambient

In current Forward+ and Mobile, default specular occlusion without a bent-normal map estimates reflection visibility from ambient luminance. If both environment and probe ambient are disabled, the multiplier becomes zero: even a valid capture or explicit RADIANCE can disappear. This does not test whether capture data exists.

For an isolated test, assign ReflectionRoom.ReflectiveMaterial(Colors.White) to the receiver. The helper enables DisableSpecularOcclusion on that material. ShaderMaterial uses the equivalent specular_occlusion_disabled render mode. Switching the option off → on → off reproducibly gives black → visible reflection → black.

For a production scene, first provide meaningful ambient and lighting. Disabling this correction removes approximate indirect-specular occlusion; it does not create light, disable direct shadows or cancel diffuse AO. Do not treat globally disabling it as a universal quality setting. The global rendering/reflections/specular_occlusion/enabled setting and the material setting are separate controls.

Accept the result

Change one variable at a time. The reflector must be within the influence volume and on a ReflectionMask layer; captured geometry needs a CullMask layer. First confirm a contrasting object is actually reflected. Then test probe movement, a moving captured object, boundary transitions and overlapping probes separately.

For a black reflection, check capture lighting, OriginOffset placement, both masks, the receiving material, an active 3D world and update completion. For stale surroundings, check UpdateMode. For a misplaced reflected wall, check Size, OriginOffset and BoxProjection. Do not change brightness, exposure, masks and update mode together: that prevents diagnosis.

Controls confirm constant-color ambient, its exclusion through ReflectionMask, and captured-sky diffuse contribution. Separate control shaders confirm why indirect specular disappeared: disabling material specular occlusion restores it with zero ambient.

Increasing the influence size does not increase capture detail. Atlas resolution and entry count are separate settings: rendering/reflections/reflection_atlas/reflection_size and rendering/reflections/reflection_atlas/reflection_count. Check the selected renderer budget; a universal promise of four probes everywhere is inappropriate. Raising probe count, resolution and update frequency is not a free quality improvement.

Known resource-release limitation

On the installed runtime, switching Once → Always and then deleting the test world produces a warning about 14 remaining Texture RIDs. Image checks pass, but this scenario does not pass GPU-texture release acceptance. Account for this separately when repeatedly creating and deleting worlds; a successful reflection does not prove memory usage will remain stable.

Windows Forward+/Vulkan checks cover the complete C# helper, settings and size constraints, reflection of geometry hidden from the main camera, Once retaining a changed material capture, refresh after probe movement, Always refresh, Intensity=0 and both masks. The black-indirect-specular cause is additionally checked without a probe in Forward+ and Mobile. Small functional frames are not graphics-quality demonstrations. Editor UI, shadow quality, parallax and ambient accuracy, multiple-probe blending, performance and other platforms are not separately accepted.

Related material: ReflectionProbe API, 3D materials, global illumination.