rayzee 7.2.1 → 7.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.2.1",
+  "version": "7.3.0",
   "type": "module",
   "description": "Real-time WebGPU path tracing engine built on Three.js",
   "main": "dist/rayzee.umd.js",

package/src/EngineDefaults.js

@@ -23,6 +23,12 @@ export const ENGINE_DEFAULTS = {
 	groundProjectionEnabled: false,
 	groundProjectionRadius: 100,
 	groundProjectionHeight: 15,
+	// World Y of the projected ground plane; auto-seeded to the scene floor (min-Y) on model
+	// load so models that aren't authored at y=0 sit ON the ground instead of sinking into it.
+	groundProjectionLevel: 0,
+	// Analytic ground-plane shadow catcher (primary-ray holdout; no geometry)
+	enableGroundCatcher: false,
+	groundCatcherHeight: 0,
 	globalIlluminationIntensity: 1,
 
 	// Environment Mode System

package/src/PathTracerApp.js

@@ -1,7 +1,7 @@
 import { WebGPURenderer, RectAreaLightNode, SRGBColorSpace } from 'three/webgpu';
 import { texture as _tslTexture, cubeTexture as _tslCubeTexture } from 'three/tsl';
 import {
-	ACESFilmicToneMapping, Scene, EventDispatcher
+	ACESFilmicToneMapping, Scene, EventDispatcher, Box3
 } from 'three';
 import { RectAreaLightTexturesLib } from 'three/addons/lights/RectAreaLightTexturesLib.js';
 import { SceneHelpers } from './SceneHelpers.js';
@@ -777,6 +777,12 @@ export class PathTracerApp extends EventDispatcher {
 
 		}
 
+		// Seed the ground-projection plane AND the shadow-catcher plane to the scene floor so models
+		// that aren't authored at y=0 sit on the ground (not sunk) — auto-updates on every model change.
+		const sceneMinY = this.getSceneMinY();
+		this.settings.set( 'groundProjectionLevel', sceneMinY, { reset: false } );
+		this.settings.set( 'groundCatcherHeight', sceneMinY, { reset: false } );
+
 		// Apply all settings to stages in one shot
 		timer.start( 'Apply settings' );
 		this.settings.applyAll();
@@ -1178,6 +1184,19 @@ export class PathTracerApp extends EventDispatcher {
 	 * @param {string} property
 	 * @param {*} value
 	 */
+	/**
+	 * World-space minimum Y of the loaded scene (the floor). Used to seed the
+	 * analytic ground-plane shadow catcher height. Returns 0 if no scene is loaded.
+	 * @returns {number}
+	 */
+	getSceneMinY() {
+
+		if ( ! this.meshScene ) return 0;
+		const box = new Box3().setFromObject( this.meshScene );
+		return Number.isFinite( box.min.y ) ? box.min.y : 0;
+
+	}
+
 	setMaterialProperty( materialIndex, property, value ) {
 
 		this.stages.pathTracer?.materialData.updateMaterialProperty( materialIndex, property, value );

package/src/RenderSettings.js

@@ -26,6 +26,9 @@ const SETTING_ROUTES = {
 	groundProjectionEnabled: { uniform: 'groundProjectionEnabled', reset: true },
 	groundProjectionRadius: { uniform: 'groundProjectionRadius', reset: true },
 	groundProjectionHeight: { uniform: 'groundProjectionHeight', reset: true },
+	groundProjectionLevel: { uniform: 'groundProjectionLevel', reset: true },
+	enableGroundCatcher: { uniform: 'enableGroundCatcher', reset: true },
+	groundCatcherHeight: { uniform: 'groundCatcherHeight', reset: true },
 	globalIlluminationIntensity: { uniform: 'globalIlluminationIntensity', reset: true },
 	enableDOF: { uniform: 'enableDOF', reset: true },
 	focusDistance: { uniform: 'focusDistance', reset: false },

package/src/Stages/PathTracer.js

@@ -726,6 +726,9 @@ export class PathTracer extends PathTracerStage {
 			groundProjectionEnabled: this.groundProjectionEnabled,
 			groundProjectionRadius: this.groundProjectionRadius,
 			groundProjectionHeight: this.groundProjectionHeight,
+			groundProjectionLevel: this.groundProjectionLevel,
+			enableGroundCatcher: this.enableGroundCatcher,
+			groundCatcherHeight: this.groundCatcherHeight,
 			envTotalSum: this.envTotalSum,
 			envResolution: this.envResolution,
 			directionalLightsBuffer: this.directionalLightsBufferNode,

package/src/TSL/Common.js

@@ -400,6 +400,68 @@ export const getMaterial = Fn( ( [ materialIndex, materialBuffer ] ) => {
 
 } );
 
+// Synthetic diffuse-white material for the analytic ground-plane shadow catcher.
+// No geometry/material buffer is involved — the plane is shaded as a matte Lambertian
+// so the direct-lighting estimator yields an irradiance-weighted shadow ratio (the
+// diffuse BRDF is constant and cancels in shadowed/unoccluded). All fields are set to
+// inert defaults; only color/roughness/metalness/transmission affect the lighting path.
+export const diffuseGroundMaterial = Fn( () => {
+
+	const idn = mat3( 1, 0, 0, 0, 1, 0, 0, 0, 1 );
+	return RayTracingMaterial( {
+		color: vec4( 1.0, 1.0, 1.0, 1.0 ),
+		emissive: vec3( 0.0 ),
+		emissiveIntensity: float( 0.0 ),
+		roughness: float( 1.0 ),
+		metalness: float( 0.0 ),
+		ior: float( 1.5 ),
+		transmission: float( 0.0 ),
+		thickness: float( 0.0 ),
+		clearcoat: float( 0.0 ),
+		clearcoatRoughness: float( 0.0 ),
+		opacity: float( 1.0 ),
+		transparent: float( 0.0 ),
+		attenuationColor: vec3( 1.0 ),
+		attenuationDistance: float( 0.0 ),
+		dispersion: float( 0.0 ),
+		sheen: float( 0.0 ),
+		sheenRoughness: float( 1.0 ),
+		sheenColor: vec3( 0.0 ),
+		specularIntensity: float( 1.0 ),
+		specularColor: vec3( 1.0 ),
+		alphaTest: float( 0.0 ),
+		alphaMode: int( 0 ),
+		side: int( 0 ),
+		depthWrite: int( 1 ),
+		albedoMapIndex: int( - 1 ),
+		emissiveMapIndex: int( - 1 ),
+		normalMapIndex: int( - 1 ),
+		bumpMapIndex: int( - 1 ),
+		bumpScale: float( 1.0 ),
+		displacementScale: float( 0.0 ),
+		metalnessMapIndex: int( - 1 ),
+		roughnessMapIndex: int( - 1 ),
+		displacementMapIndex: int( - 1 ),
+		normalScale: vec2( 1.0, 1.0 ),
+		albedoTransform: idn,
+		emissiveTransform: idn,
+		normalTransform: idn,
+		bumpTransform: idn,
+		metalnessTransform: idn,
+		roughnessTransform: idn,
+		displacementTransform: idn,
+		iridescence: float( 0.0 ),
+		iridescenceIOR: float( 1.3 ),
+		iridescenceThicknessRange: vec2( 100.0, 400.0 ),
+		subsurface: float( 0.0 ),
+		subsurfaceColor: vec3( 1.0 ),
+		subsurfaceRadius: vec3( 1.0, 0.2, 0.1 ),
+		subsurfaceRadiusScale: float( 1.0 ),
+		subsurfaceAnisotropy: float( 0.0 ),
+	} );
+
+} );
+
 // ── Shadow material thin reader (7 slot reads instead of 27) ─────────────
 // Only fetches fields needed by traceShadowRay: alpha, transmission, attenuation, albedo transform.
 

package/src/TSL/Environment.js

@@ -1,4 +1,4 @@
-import { Fn, wgslFn, vec2, vec4, ivec2, float, int, If, texture, dot, sin, sqrt, floor, fract, min, max, mix, clamp } from 'three/tsl';
+import { Fn, wgslFn, vec2, vec3, vec4, ivec2, float, int, If, texture, dot, sin, sqrt, floor, fract, min, max, mix, clamp } from 'three/tsl';
 
 import { REC709_LUMINANCE_COEFFICIENTS } from './Common.js';
 
@@ -211,3 +211,24 @@ export const getGroundProjectedDirection = Fn( ( [ rayOrigin, rayDirection, radi
 	return projected;
 
 } );
+
+// Primary-ray environment lookup direction: bends onto the ground-projection sphere/disk when
+// ground projection is enabled, else returns the ray direction unchanged. Shared by the background
+// miss branch AND the shadow catcher so they can never disagree on the projection (the source of a
+// past horizon-seam bug when only one path bent the direction).
+export const groundProjectedEnvDir = Fn( ( [ rayOrigin, rayDirection, enabled, radius, height, level ] ) => {
+
+	const dir = rayDirection.toVar();
+	If( enabled, () => {
+
+		// Relocate the projected ground plane from y=0 to world y=level (the scene floor) so a model
+		// authored off the origin still sits ON the ground instead of sinking. Shifting the projection
+		// origin down by `level` puts the disk at y=level and the sphere at y=level+height; the internal
+		// horizontal radius test stays correct because the shifted disk point lands at y'=0.
+		const shiftedOrigin = vec3( rayOrigin.x, rayOrigin.y.sub( level ), rayOrigin.z );
+		dir.assign( getGroundProjectedDirection( shiftedOrigin, rayDirection, radius, height ) );
+
+	} );
+	return dir;
+
+} );

package/src/TSL/LightsSampling.js

@@ -58,7 +58,7 @@ import {
 	sampleIESProfile,
 } from './LightsCore.js';
 
-import { MISStrategy, DotProducts } from './Struct.js';
+import { MISStrategy, DotProducts, DirectLightingDual } from './Struct.js';
 import {
 	calculateDirectionalLightImportance,
 	estimateLightImportance,
@@ -707,9 +707,14 @@ export const calculateDirectLightingUnified = Fn( ( [
 	envCDFTexture,
 	envTotalSum, envCompensationDelta, envResolution,
 	enableEnvironmentLight,
+	// Shadow catcher: when true, also accumulate the unoccluded (visibility=1) reference
+	// at every light/env site so the caller can form a shadow ratio. Dead path otherwise.
+	wantUnoccluded,
 ] ) => {
 
 	const totalContribution = vec3( 0.0 ).toVar();
+	// Unoccluded reference (visibility forced to 1) — only filled when wantUnoccluded.
+	const unoccludedContribution = vec3( 0.0 ).toVar();
 	const rayOrigin = hitPoint.add( hitNormal.mul( 0.001 ) ).toVar();
 
 	// Binds BVH params so shadow-ray sites at varying call depths use a 3-arg call
@@ -819,7 +824,7 @@ export const calculateDirectLightingUnified = Fn( ( [
 					const shadowDistance = min( lightSample.distance.sub( 0.001 ), float( 1000.0 ) );
 					const visibility = shadow( rayOrigin, lightSample.direction, shadowDistance );
 
-					If( visibility.greaterThan( 0.0 ), () => {
+					If( visibility.greaterThan( 0.0 ).or( wantUnoccluded ), () => {
 
 						// Share H + dot products between BRDF eval and PDF — otherwise each
 						// would recompute normalize(V+L) + 5 dot products independently.
@@ -846,9 +851,15 @@ export const calculateDirectLightingUnified = Fn( ( [
 
 						} );
 
-						// Guard division
-						const lightContribution = lightSample.emission.mul( brdfValue ).mul( NoL ).mul( visibility ).mul( misW ).div( max( lightSample.pdf, 1e-10 ) );
-						totalContribution.addAssign( lightContribution.mul( totalSamplingWeight ).div( max( lightWeight, 1e-10 ) ) );
+						// Base contribution WITHOUT visibility; shadowed = base × visibility (identical to the
+						// pre-dual-sum math), unoccluded = base × 1 (shadow-catcher reference only).
+						const baseContribution = lightSample.emission.mul( brdfValue ).mul( NoL ).mul( misW ).div( max( lightSample.pdf, 1e-10 ) ).mul( totalSamplingWeight ).div( max( lightWeight, 1e-10 ) );
+						totalContribution.addAssign( baseContribution.mul( visibility ) );
+						If( wantUnoccluded, () => {
+
+							unoccludedContribution.addAssign( baseContribution );
+
+						} );
 
 					} );
 
@@ -918,7 +929,7 @@ export const calculateDirectLightingUnified = Fn( ( [
 								const shadowDistance = min( hitDistance.sub( 0.001 ), float( 1000.0 ) );
 								const visibility = shadow( rayOrigin, brdfSampleDirection, shadowDistance );
 
-								If( visibility.greaterThan( 0.0 ), () => {
+								If( visibility.greaterThan( 0.0 ).or( wantUnoccluded ), () => {
 
 									const lightFacing = max( float( 0.0 ), dot( brdfSampleDirection, light.normal ).negate() ).toVar();
 
@@ -934,9 +945,14 @@ export const calculateDirectLightingUnified = Fn( ( [
 										const misW = powerHeuristic( { pdf1: brdfPdfWeighted, pdf2: lightPdfWeighted } ).toVar();
 
 										const lightEmission = light.color.mul( light.intensity );
-										// Guard division
-										const brdfContribution = lightEmission.mul( brdfSampleValue ).mul( NoL ).mul( visibility ).mul( misW ).div( max( brdfSamplePdf, 1e-10 ) );
-										totalContribution.addAssign( brdfContribution.mul( totalSamplingWeight ).div( max( brdfWeight, 1e-10 ) ) );
+										// Base contribution WITHOUT visibility (see discrete-light site).
+										const baseContribution = lightEmission.mul( brdfSampleValue ).mul( NoL ).mul( misW ).div( max( brdfSamplePdf, 1e-10 ) ).mul( totalSamplingWeight ).div( max( brdfWeight, 1e-10 ) );
+										totalContribution.addAssign( baseContribution.mul( visibility ) );
+										If( wantUnoccluded, () => {
+
+											unoccludedContribution.addAssign( baseContribution );
+
+										} );
 
 									} );
 
@@ -984,7 +1000,7 @@ export const calculateDirectLightingUnified = Fn( ( [
 
 					const visibility = shadow( rayOrigin, envDirection, float( 1000.0 ) );
 
-					If( visibility.greaterThan( 0.0 ), () => {
+					If( visibility.greaterThan( 0.0 ).or( wantUnoccluded ), () => {
 
 						// Share H + dots between env BRDF/PDF — same redundancy fix as the
 						// discrete-light path above.
@@ -1000,9 +1016,14 @@ export const calculateDirectLightingUnified = Fn( ( [
 							float( 1.0 )
 						).toVar();
 
-						// Guard division — no stochastic scaling needed (deterministic estimator)
-						const envContribution = envColor.mul( brdfValue ).mul( NoL ).mul( visibility ).mul( misW ).div( max( envPdf, 1e-10 ) );
-						totalContribution.addAssign( envContribution );
+						// Base contribution WITHOUT visibility (deterministic estimator; no stochastic scaling).
+						const baseContribution = envColor.mul( brdfValue ).mul( NoL ).mul( misW ).div( max( envPdf, 1e-10 ) );
+						totalContribution.addAssign( baseContribution.mul( visibility ) );
+						If( wantUnoccluded, () => {
+
+							unoccludedContribution.addAssign( baseContribution );
+
+						} );
 
 					} );
 
@@ -1018,6 +1039,6 @@ export const calculateDirectLightingUnified = Fn( ( [
 	// NOTE: Emissive triangle sampling is handled separately in pathtracer_core.fs
 	// to bypass firefly suppression. Do not add it here to avoid double-counting.
 
-	return totalContribution;
+	return DirectLightingDual( { shadowed: totalContribution, unoccluded: unoccludedContribution } );
 
 } );

package/src/TSL/ShadeKernel.js

@@ -6,6 +6,7 @@
 
 import {
 	Fn, float, vec2, vec3, vec4, int, uint,
+	bool as tslBool,
 	If, normalize, max, exp, log, clamp, dot, length, select,
 	instanceIndex,
 	sampler,
@@ -13,8 +14,9 @@ import {
 	Return,
 } from 'three/tsl';
 
-import { sampleEnvironment, sampleEquirectProbability, sampleEquirect, getGroundProjectedDirection } from './Environment.js';
-import { getMaterial, powerHeuristic, balanceHeuristic, classifyMaterial } from './Common.js';
+import { sampleEnvironment, sampleEquirectProbability, sampleEquirect, groundProjectedEnvDir } from './Environment.js';
+import { getMaterial, powerHeuristic, balanceHeuristic, classifyMaterial, REC709_LUMINANCE_COEFFICIENTS, PI_INV, EPSILON, diffuseGroundMaterial } from './Common.js';
+import { cosineWeightedSample } from './MaterialSampling.js';
 import { sampleAllMaterialTextures } from './TextureSampling.js';
 import { evaluateMaterialResponse } from './MaterialEvaluation.js';
 import { calculateDirectLightingUnified, calculateMaterialPDF } from './LightsSampling.js';
@@ -40,6 +42,7 @@ import {
 	MaterialClassification,
 	BRDFWeights,
 	MaterialCache,
+	DirectLightingDual,
 } from './Struct.js';
 import { RandomValue, getRandomSample } from './Random.js';
 import { RAY_FLAG, COUNTER } from '../Processor/QueueManager.js';
@@ -57,6 +60,14 @@ import {
 const WG_SIZE = 256;
 const MISS_DIST = 1e19;
 
+// Shadow-catcher thresholds (named so the two distinct 1e-4 uses don't read as one value)
+const CATCHER_T_MIN = 1e-4; // min ray-t for the analytic plane hit (skip behind/at the camera)
+const CATCHER_LUMA_FLOOR = 1e-4; // denominator floor for the shadow ratio
+const CATCHER_COVERAGE_MIN = 1e-3; // below this incident luma there is no shadow to catch
+// Reserved G-buffer surface ID for catcher pixels (no real triangle); stable across frames so the
+// denoiser treats the analytic plane as one coherent surface, not a background miss.
+const CATCHER_SURFACE_ID = 0xFFFFFFFE;
+
 export function buildShadeKernel( params ) {
 
 	const {
@@ -71,7 +82,8 @@ export function buildShadeKernel( params ) {
 		displacementMaps,
 		envTexture, environmentIntensity, envMatrix,
 		enableEnvironmentLight, useEnvMapIS,
-		groundProjectionEnabled, groundProjectionRadius, groundProjectionHeight,
+		groundProjectionEnabled, groundProjectionRadius, groundProjectionHeight, groundProjectionLevel,
+		enableGroundCatcher, groundCatcherHeight,
 		envTotalSum, envCompensationDelta, envResolution,
 		directionalLightsBuffer, numDirectionalLights,
 		areaLightsBuffer, numAreaLights,
@@ -136,6 +148,111 @@ export function buildShadeKernel( params ) {
 		const sssSteps = readSssSteps( rayBufferRW, rayID ).toVar();
 		const sampleIndex = int( rayID.div( maxRaysPerSample ) ).toVar();
 
+		// ── Analytic ground-plane shadow catcher (primary ray only, no geometry) ──
+		// A horizontal plane at y = groundCatcherHeight. For a bounce-0 ray that crosses it
+		// closer than any BVH hit (hitDist is MISS_DIST on sky rays, so the plane wins over the
+		// bare environment), shade it as a diffuse Lambertian holdout: output a monochrome shadow
+		// ratio in alpha (rgb = 0) so it composites as bg·ratio over a transparent background.
+		// Shadows are caught by the EXISTING NEE shadow ray into real geometry — the plane itself
+		// never enters the BVH. Secondary bounces ignore it entirely.
+		If( enableGroundCatcher.and( bounceIndex.equal( 0 ) ), () => {
+
+			const dirY = direction.y.toVar();
+			If( dirY.abs().greaterThan( float( EPSILON ) ), () => {
+
+				const tPlane = groundCatcherHeight.sub( origin.y ).div( dirY ).toVar();
+				If( tPlane.greaterThan( float( CATCHER_T_MIN ) ).and( tPlane.lessThan( hitDist ) ), () => {
+
+					const planePoint = origin.add( direction.mul( tPlane ) ).toVar();
+					const planeN = vec3( 0.0, 1.0, 0.0 );
+					const planeV = direction.negate().toVar();
+					const planeMat = RayTracingMaterial.wrap( diffuseGroundMaterial() ).toVar();
+
+					// Cosine-weighted hemisphere BRDF sample about the plane normal (0,1,0); the helper
+					// puts cosθ along N, so bDir.y == cosθ. Per-component .toVar() on the two randoms
+					// (vec2(RandomValue,RandomValue) would collapse to u==v — TSL pitfall).
+					const u1 = RandomValue( rngState ).toVar();
+					const u2 = RandomValue( rngState ).toVar();
+					const bDir = cosineWeightedSample( planeN, vec2( u1, u2 ) ).toVar();
+					const bPdf = bDir.y.mul( PI_INV ).toVar(); // cosθ / π
+					const bVal = vec3( PI_INV ); // albedo(1) / π
+
+					// Reuse the full NEE estimator; the diffuse BRDF is constant and cancels in the
+					// ratio, so this yields an irradiance-weighted shadow density across all lights + env.
+					const dual = DirectLightingDual.wrap( calculateDirectLightingUnified(
+						planePoint, planeN, planeMat, planeV,
+						bDir, bPdf, bVal,
+						bounceIndex, rngState,
+						directionalLightsBuffer, numDirectionalLights,
+						areaLightsBuffer, numAreaLights,
+						pointLightsBuffer, numPointLights,
+						spotLightsBuffer, numSpotLights,
+						bvhBuffer, triangleBuffer, materialBuffer,
+						envTexture, environmentIntensity, envMatrix,
+						envCDFTexture,
+						envTotalSum, envCompensationDelta, envResolution,
+						enableEnvironmentLight,
+						tslBool( true ), // wantUnoccluded
+					) ).toVar();
+
+					const lumShad = max( dot( dual.shadowed, REC709_LUMINANCE_COEFFICIENTS ), float( 0.0 ) );
+					const lumLit = max( dot( dual.unoccluded, REC709_LUMINANCE_COEFFICIENTS ), float( 0.0 ) ).toVar();
+					const ratio = clamp( lumShad.div( max( lumLit, float( CATCHER_LUMA_FLOOR ) ) ), 0.0, 1.0 ).toVar();
+					// Coverage gate: where no light reaches the plane there is no shadow to catch —
+					// force ratio=1 (no darkening) so unlit ground reads as plain background, not spurious black.
+					If( lumLit.lessThan( float( CATCHER_COVERAGE_MIN ) ), () => {
+
+						ratio.assign( 1.0 );
+
+					} );
+
+					// Adaptive output (matches Arnold's scene_background / Cycles shadow catcher): the catcher
+					// respects the current background mode instead of forcing transparency.
+					//  • Transparent background → emit a matte (rgb=0, alpha=1−ratio); the shadow rides alpha
+					//    and composites as backplate·ratio over an external plate.
+					//  • Visible background     → composite the shadow into RGB: show the environment this
+					//    camera ray would otherwise see, darkened by the shadow ratio (alpha=1). The HDRI stays
+					//    visible; at the horizon ratio→1 so the catcher meets the sky with no seam.
+					// Sample the background via the SAME shared helper the miss branch uses, so the
+					// catcher seamlessly continues the visible environment (with ground projection on it
+					// must bend identically, else a bright horizon seam / mismatched ground appears).
+					const catcherEnvDir = groundProjectedEnvDir(
+						origin, direction, groundProjectionEnabled, groundProjectionRadius, groundProjectionHeight, groundProjectionLevel,
+					).toVar();
+					const envBehind = sampleEnvironment( {
+						tex: envTexture,
+						samp: sampler( envTexture ),
+						direction: catcherEnvDir,
+						environmentMatrix: envMatrix,
+						environmentIntensity,
+						enableEnvironmentLight,
+					} ).xyz.toVar();
+					const bgColor = select( showBackground, envBehind.mul( backgroundIntensity ), vec3( 0.0 ) );
+					const outRgb = select( transparentBackground, vec3( 0.0 ), bgColor.mul( ratio ) );
+					const outAlpha = select( transparentBackground, float( 1.0 ).sub( ratio ), float( 1.0 ) );
+
+					// The catcher is a real ground surface for the denoiser — write the plane's normal/depth
+					// + a neutral albedo (black albedo would break OIDN demodulation) and mark the pixel a
+					// valid surface, so OIDN/ASVGF don't smear the caught shadow as a background miss.
+					If( sampleIndex.equal( int( 0 ) ), () => {
+
+						const planeDepth = computeNDCDepth( { worldPos: planePoint, cameraProjectionMatrix, cameraViewMatrix } );
+						writeGBuffer( gBufferRW, pixelIndex, planeN, planeDepth, vec3( 1.0 ) );
+						writeGBufferSurfaceID( gBufferRW, pixelIndex, uint( CATCHER_SURFACE_ID ), uint( CATCHER_SURFACE_ID ), 0.5, 0.5, uint( 1 ) );
+
+					} );
+
+					writeRayRadiance( rayBufferRW, rayID, vec4( outRgb, outAlpha ) );
+					writeRayDirFlags( rayBufferRW, rayID, direction, flags.bitAnd( uint( ~ RAY_FLAG.ACTIVE ) ) );
+					rngBufferRW.element( rayID ).assign( rngState );
+					Return();
+
+				} );
+
+			} );
+
+		} );
+
 		If( hitDist.greaterThan( MISS_DIST ), () => {
 
 			If( enableEnvironmentLight, () => {
@@ -143,11 +260,12 @@ export function buildShadeKernel( params ) {
 				// Ground projection bends the primary ray's background lookup onto a
 				// projected sphere+disk so the lower env hemisphere reads as a ground
 				// plane. Primary ray only; secondary bounces see the raw envmap as a light.
+				// Shared helper (also used by the shadow catcher) keeps the two in lockstep.
 				const envDir = direction.toVar();
-				If( bounceIndex.equal( 0 ).and( groundProjectionEnabled ), () => {
+				If( bounceIndex.equal( 0 ), () => {
 
-					envDir.assign( getGroundProjectedDirection(
-						origin, direction, groundProjectionRadius, groundProjectionHeight,
+					envDir.assign( groundProjectedEnvDir(
+						origin, direction, groundProjectionEnabled, groundProjectionRadius, groundProjectionHeight, groundProjectionLevel,
 					) );
 
 				} );
@@ -689,7 +807,7 @@ export function buildShadeKernel( params ) {
 
 		} );
 
-		const directLight = calculateDirectLightingUnified(
+		const directLight = DirectLightingDual.wrap( calculateDirectLightingUnified(
 			hitPoint, N, material, V,
 			brdfDir, brdfPdf, brdfValue,
 			bounceIndex, rngState,
@@ -702,7 +820,8 @@ export function buildShadeKernel( params ) {
 			envCDFTexture,
 			envTotalSum, envCompensationDelta, envResolution,
 			enableEnvironmentLight,
-		);
+			tslBool( false ), // wantUnoccluded: false on real surfaces — dead-codes the unoccluded sum
+		) ).shadowed.toVar();
 
 		const giScale = select( bounceIndex.greaterThan( 0 ), globalIlluminationIntensity, float( 1.0 ) );
 		// Per-term firefly suppression (megakernel parity: PathTracerCore.js:1164) — wrap the direct-light add

package/src/TSL/Struct.js

@@ -73,6 +73,14 @@ export const ShadowMaterial = struct( {
 	albedoTransform: 'mat3',
 } );
 
+// Dual direct-lighting result: shadowed (the normal NEE estimate) + unoccluded
+// (same estimator with visibility forced to 1). Used by the shadow catcher to
+// derive a shadow ratio = luma(shadowed) / luma(unoccluded).
+export const DirectLightingDual = struct( {
+	shadowed: 'vec3',
+	unoccluded: 'vec3',
+} );
+
 export const Sphere = struct( {
 	position: 'vec3',
 	radius: 'float',

package/src/managers/UniformManager.js

@@ -188,6 +188,9 @@ export class UniformManager {
 		ub( 'groundProjectionEnabled', DEFAULT_STATE.groundProjectionEnabled );
 		u( 'groundProjectionRadius', DEFAULT_STATE.groundProjectionRadius, 'float' );
 		u( 'groundProjectionHeight', DEFAULT_STATE.groundProjectionHeight, 'float' );
+		u( 'groundProjectionLevel', DEFAULT_STATE.groundProjectionLevel, 'float' );
+		ub( 'enableGroundCatcher', DEFAULT_STATE.enableGroundCatcher );
+		u( 'groundCatcherHeight', DEFAULT_STATE.groundCatcherHeight, 'float' );
 
 		// Sun parameters
 		u( 'sunDirection', new Vector3( 0, 1, 0 ), 'vec3' );