Spatial: surfaces, lighting, alpha and depth

A spatial shader defines a 3D mesh surface. Assign a Shader to a ShaderMaterial, then to a MeshInstance3D surface or MaterialOverride. vertex() changes geometry/attributes, fragment() defines material properties, and optional light() replaces direct-light calculation.

First material and assignment

This complete opaque material uses a texture and tint. source_color identifies color data; hint_default_white makes tint work without a separate texture:

shader_type spatial;
uniform sampler2D albedo_texture : source_color, hint_default_white;
uniform vec4 tint : source_color = vec4(1.0);
void fragment() {
    ALBEDO = texture(albedo_texture, UV).rgb * tint.rgb;
    METALLIC = 0.0;
    ROUGHNESS = 0.7;
}

ALBEDO is base color, not guaranteed final RGB: lighting, a dielectric white highlight, reflections, fog and tonemapping change the pixel. Red ALBEDO can therefore produce nonzero G/B from specular lighting. Use unshaded diagnostically to inspect base color alone.

A complete C# helper creates a QuadMesh with the material:

using Reckfell;

public static class SpatialSetup
{
    public static MeshInstance3D Create(Shader shader)
    {
        return new MeshInstance3D
        {
            Mesh = new QuadMesh { Size = new Vector2(1, 1) },
            MaterialOverride = new ShaderMaterial { Shader = shader },
        };
    }
}

Load the Shader using ResourceLoader.Load<Shader>("asset://PbrSurface.reckfellshader"), call SpatialSetup.Create(shader) and add the result to the tree. A camera at (0,0,5) looking along −Z sees this quad's front. A shaded material needs lights or suitable environment lighting.

Material selection priority is object MaterialOverride → per-surface override → the Mesh resource surface material. GetSurfaceOverrideMaterial returns the stored override, which may be inactive under MaterialOverride. GetActiveMaterial helps inspect the selected base material. GetSurfaceOverrideMaterialCount counts surface slots, not non-null overrides.

MaterialOverlay adds a draw pass governed by its queue, blending and depth, not an unconditional top layer. In the check, an opaque equal-depth overlay was not on top, while a transparent overlay blended with the base. Do not rely on the overlay name alone to fix transparency ordering.

Vertex and normal spaces

By default VERTEX, NORMAL, TANGENT and BINORMAL enter vertex() in mesh-local space. MODEL_MATRIX maps position to world, VIEW_MATRIX to view, and PROJECTION_MATRIX to clip. In fragment(), VERTEX and the ordinary NORMAL are already view-space values. A shadow pass matrix can refer to a light camera; MAIN_CAM_INV_VIEW_MATRIX refers to the viewport's main camera.

Nonuniform scale requires the inverse-transpose normal transform. Multiplying a normal by ordinary MODELVIEW_MATRIX as a direction gives the wrong angle. A complete manual-path diagnostic:

shader_type spatial;
render_mode unshaded, skip_vertex_transform;
void vertex() {
    VERTEX = (MODELVIEW_MATRIX * vec4(VERTEX, 1.0)).xyz;
    NORMAL = normalize(MODELVIEW_NORMAL_MATRIX * NORMAL);
    TANGENT = normalize(mat3(MODELVIEW_MATRIX) * TANGENT);
    BINORMAL = normalize(mat3(MODELVIEW_MATRIX) * BINORMAL);
}
void fragment() {
    ALBEDO = normalize(NORMAL) * 0.5 + 0.5;
}

skip_vertex_transform disables automatic model→view position/basis transformation; projection remains. NORMAL uses MODELVIEW_NORMAL_MATRIX, while tangent vectors use the linear MODELVIEW_MATRIX part. Complex deformation/nonorthogonal TBN can require rebuilding a consistent tangent basis. This is not a universal fix for every normal-mapped/skinned mesh.

world_vertex_coords supplies world-space attributes to user vertex(); do not apply MODEL_MATRIX twice. Writing POSITION requires a complete clip-space vec4 on every branch: automatic position projection is replaced, while fragment VERTEX still derives from VERTEX. Those outputs are not the same space. Normalized texture UV, viewport SCREEN_UV and pixel FRAGCOORD are also distinct.

Transparency and cutout

blend_mix is the spatial blend default, but ALPHA usage also determines the pipeline. PbrSurface does not use tint.a: setting the color's alpha to zero does not make it transparent. Reading/writing ALPHA can select the transparent queue even at 1, changing sorting and participation in other effects.

Write ALPHA for smooth transparency. Use ALPHA_SCISSOR_THRESHOLD for a cutout boundary. This complete shader keeps the quad's right half opaque:

shader_type spatial;
render_mode unshaded;
void fragment() {
    ALBEDO = vec3(1.0, 0.0, 0.0);
    ALPHA = UV.x;
    ALPHA_SCISSOR_THRESHOLD = 0.5;
}

Alpha hash uses ALPHA_HASH_SCALE for stochastic coverage. Alpha-to-coverage needs appropriate MSAA and antialiasing configuration; it does not replace texture detail. Transparent surfaces have sorting limitations, not arbitrary per-pixel layer ordering. depth_prepass_alpha helps some cases rather than solving all intersecting transparency.

NORMAL_MAP expects an encoded normal map; NORMAL is a view-space normal vector. Do not assign unprocessed texture RGB to NORMAL. Mark color textures/parameters as source_color and classify data maps by purpose; do not apply sRGB conversion to vectors, masks and physical parameters.

Custom light()

Without light(), built-in lighting applies. A custom function operates for a light in view space. LIGHT points toward it, ATTENUATION accounts for falloff/shadows and LIGHT_COLOR includes color/energy. Accumulate contributions with +=.

A complete simple diffuse calculation:

shader_type spatial;
uniform vec3 base_color : source_color = vec3(1.0);
void fragment() {
    ALBEDO = base_color;
    ROUGHNESS = 1.0;
}
void light() {
    float ndotl = max(dot(NORMAL, LIGHT), 0.0);
    DIFFUSE_LIGHT += ndotl * ATTENUATION * LIGHT_COLOR / PI;
}

Current Forward+ multiplies the final diffuse by ALBEDO afterward. Multiplying by ALBEDO inside this light() example would darken it twice; the test confirms one application. source_color also converts entered color to linear space: an entered color component of 0.5 is not automatically linear intensity 0.5.

This example handles ordinary direct diffuse light, not a complete PBR model. Use specialized area-light data/multipliers for that path, and SPECULAR_LIGHT for a specular contribution. unshaded bypasses lighting; vertex_lighting can bypass the per-pixel custom light(). Verify the required path before extending a BRDF.

Depth depends on the pass

The checked Forward+/Vulkan path uses reverse-Z: DEPTH=0 is far and DEPTH=1 is near. CLIP_SPACE_FAR describes the renderer's far clip coordinate, not a world distance. Reconstruct screen-depth positions with the appropriate INV_PROJECTION_MATRIX and division by w; see screen-reading shaders.

If any branch writes DEPTH, provide a meaningful value on every branch. Check the depth prepass and shadows separately: they need not repeat an arbitrary fragment algorithm.

A specific installed Forward+ defect is reproduced: a simple opaque custom-DEPTH material can select a shared prepass that does not account for that write. Geometry occludes the rear object in the prepass, then its color fails the new-depth test, leaving a black region. Source selection of the shared prepass material does not check DEPTH writes. This is a configuration limitation, not evidence that reverse-Z is ordinary Z. A separate transparent path without depth writing confirms the 0/1 ordering against an opaque rear surface. Do not treat custom DEPTH as a universal overlay trick without checking every required pass.

Stencil mask writing and reading

Current syntax uses stencil_mode, a reference from 0 through 255, and write/read/write_depth_fail. The correct name is write_depth_fail, not write_if_depth_fail. Reading must use the transparent queue. These examples provide a blue mask writer and a red reader inside its mask:

shader_type spatial;
render_mode unshaded;
stencil_mode write, 1;
void fragment() {
    ALBEDO = vec3(0.0, 0.0, 1.0);
}

shader_type spatial;
render_mode unshaded, depth_test_disabled;
stencil_mode read, compare_equal, 1;
void fragment() {
    ALBEDO = vec3(1.0, 0.0, 0.0);
    ALPHA = 1.0;
}

Assign them to two meshes; the reader can be larger. The check sees red only inside the mask, which updates when the writer moves. The reader deliberately writes ALPHA=1 and disables depth testing. This is a minimal mask check, not a complete portal or outline effect.

Comparisons are compare_always, compare_equal, compare_not_equal, compare_less, compare_less_or_equal, compare_greater and compare_greater_or_equal. Reference is compared with stencil contents. Stencil is not an ordinary color texture: spatial has no built-in sampler for it. Check each renderer/pass separately.

Complete built-in registry

G is global; V is vertex(); F is fragment(); L is light(). A star marks a writable stage; unstarred stages are read-only. Initial values and output semantics depend on the field; conditional output writes need values on every relevant branch.

Render modes

Choose a coherent set rather than enabling every mode. Depth-write policy does not cancel depth testing or queue constraints.

TIME rolls over at rendering/limits/time/time_rollover_secs, default 3600 seconds. Supply a time uniform for pausable gameplay animation.

With ambient disabled, default specular occlusion can suppress indirect specular even with valid RADIANCE or ReflectionProbe data. Current Forward+ and Mobile use ambient luminance as a reflection-visibility approximation in the branch without a bent-normal map. Use specular_occlusion_disabled for an isolated check, or DisableSpecularOcclusion on StandardMaterial3D. This does not disable direct shadows or diffuse AO. Setup and checked conditions.

Troubleshooting

Installed Windows Forward+/Vulkan checks execute six complete shaders and the C# helper: base surface, normals, culling, ALPHA/scissor, direct light, DEPTH, stencil and material priority. The 95-name registry and remaining modes are source-reviewed. This is not complete acceptance of every BRDF, SSS, area-light, MSAA, deformation/skinning, streaming, XR, shadow or platform combination. Functional readbacks are not published beauty illustrations; the custom-DEPTH defect is retained in the checks.