rayzee 5.1.1 → 5.2.0

package/package.json

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

package/src/EngineDefaults.js

@@ -80,6 +80,7 @@ export const ENGINE_DEFAULTS = {
 	renderLimitMode: 'frames',
 	renderTimeLimit: 30,
 	renderMode: 0,
+	enableAlphaShadows: false,
 	tiles: 3,
 	tilesHelper: false,
 	showLightHelper: false,
@@ -337,6 +338,80 @@ export const TRIANGLE_DATA_LAYOUT = {
 	UV_C_MAT_OFFSET: 28
 };
 
+// Material data layout constants — single source of truth for material buffer offsets.
+// Shared between CPU writers (TextureCreator, MaterialDataManager) and GPU readers (Common.js getMaterial).
+export const MATERIAL_DATA_LAYOUT = {
+
+	SLOTS_PER_MATERIAL: 27, // vec4 slots per material
+	FLOATS_PER_MATERIAL: 108, // total floats per material (27 × 4)
+
+	// ── Flat float offsets (CPU side) ────────────────────────────────
+	// Used as: data[ materialIndex * FLOATS_PER_MATERIAL + offset ]
+	// Ordered for cache-line coherence: shadow/culling → BxDF core → maps → extended → transforms
+
+	// Slot 0: ior + transmission + thickness + emissiveIntensity   [shadow]
+	IOR: 0, TRANSMISSION: 1, THICKNESS: 2, EMISSIVE_INTENSITY: 3,
+	// Slot 1: attenuationColor.rgb + attenuationDistance            [shadow]
+	ATTENUATION_COLOR: 4, ATTENUATION_DISTANCE: 7,
+	// Slot 2: opacity + side + transparent + alphaTest              [shadow + culling]
+	OPACITY: 8, SIDE: 9, TRANSPARENT: 10, ALPHA_TEST: 11,
+	// Slot 3: alphaMode + depthWrite + normalScale                  [shadow]
+	ALPHA_MODE: 12, DEPTH_WRITE: 13, NORMAL_SCALE: 14,
+	// Slot 4: color.rgb + metalness                                 [BxDF core]
+	COLOR: 16, METALNESS: 19,
+	// Slot 5: emissive.rgb + roughness                              [BxDF core]
+	EMISSIVE: 20, ROUGHNESS: 23,
+	// Slot 6: map indices (albedo, normal, roughness, metalness)    [maps]
+	ALBEDO_MAP_INDEX: 24, NORMAL_MAP_INDEX: 25, ROUGHNESS_MAP_INDEX: 26, METALNESS_MAP_INDEX: 27,
+	// Slot 7: map indices (emissive, bump) + clearcoat              [maps]
+	EMISSIVE_MAP_INDEX: 28, BUMP_MAP_INDEX: 29, CLEARCOAT: 30, CLEARCOAT_ROUGHNESS: 31,
+	// Slot 8: dispersion + visible + sheen + sheenRoughness         [extended BxDF]
+	DISPERSION: 32, VISIBLE: 33, SHEEN: 34, SHEEN_ROUGHNESS: 35,
+	// Slot 9: sheenColor.rgb + (reserved)                           [extended BxDF]
+	SHEEN_COLOR: 36,
+	// Slot 10: specularIntensity + specularColor.rgb                [extended BxDF]
+	SPECULAR_INTENSITY: 40, SPECULAR_COLOR: 41,
+	// Slot 11: iridescence + iridescenceIOR + iridescenceThicknessRange [extended BxDF]
+	IRIDESCENCE: 44, IRIDESCENCE_IOR: 45, IRIDESCENCE_THICKNESS_RANGE: 46,
+	// Slot 12: bumpScale + displacementScale + displacementMapIndex + (padding)
+	BUMP_SCALE: 48, DISPLACEMENT_SCALE: 49, DISPLACEMENT_MAP_INDEX: 50,
+
+	// ── Transform float offsets (8 floats each: 7 matrix values + 1 padding) ──
+	ALBEDO_TRANSFORM: 52,
+	NORMAL_TRANSFORM: 60,
+	ROUGHNESS_TRANSFORM: 68,
+	METALNESS_TRANSFORM: 76,
+	EMISSIVE_TRANSFORM: 84,
+	BUMP_TRANSFORM: 92,
+	DISPLACEMENT_TRANSFORM: 100,
+
+	// ── Vec4 slot indices (GPU/TSL side) ─────────────────────────────
+	// Used with getDatafromStorageBuffer( buf, matIdx, int(slot), int(SLOTS_PER_MATERIAL) )
+	SLOT: {
+		IOR_TRANSMISSION: 0, // [shadow] ior, transmission, thickness, emissiveIntensity
+		ATTENUATION: 1, // [shadow] attenuationColor, attenuationDistance
+		OPACITY_ALPHA: 2, // [shadow+culling] opacity, side, transparent, alphaTest
+		ALPHA_MODE: 3, // [shadow] alphaMode, depthWrite, normalScale
+		COLOR_METALNESS: 4, // [BxDF] color.rgb, metalness
+		EMISSIVE_ROUGHNESS: 5, // [BxDF] emissive.rgb, roughness
+		MAP_INDICES_A: 6, // [maps] albedo, normal, roughness, metalness
+		MAP_INDICES_B: 7, // [maps] emissive, bump, clearcoat, clearcoatRoughness
+		DISPERSION_SHEEN: 8, // [extended] dispersion, visible, sheen, sheenRoughness
+		SHEEN_COLOR: 9, // [extended] sheenColor, reserved
+		SPECULAR: 10, // [extended] specularIntensity, specularColor
+		IRIDESCENCE: 11, // [extended] iridescence, iridescenceIOR, iridescenceThicknessRange
+		BUMP_DISPLACEMENT: 12, // bumpScale, displacementScale, displacementMapIndex
+		ALBEDO_TRANSFORM_A: 13, ALBEDO_TRANSFORM_B: 14,
+		NORMAL_TRANSFORM_A: 15, NORMAL_TRANSFORM_B: 16,
+		ROUGHNESS_TRANSFORM_A: 17, ROUGHNESS_TRANSFORM_B: 18,
+		METALNESS_TRANSFORM_A: 19, METALNESS_TRANSFORM_B: 20,
+		EMISSIVE_TRANSFORM_A: 21, EMISSIVE_TRANSFORM_B: 22,
+		BUMP_TRANSFORM_A: 23, BUMP_TRANSFORM_B: 24,
+		DISPLACEMENT_TRANSFORM_A: 25, DISPLACEMENT_TRANSFORM_B: 26,
+	},
+
+};
+
 // BVH node leaf markers
 export const BVH_LEAF_MARKERS = {
 	TRIANGLE_LEAF: - 1, // Leaf containing triangle references
@@ -364,14 +439,14 @@ export const DEFAULT_TEXTURE_MATRIX = [ 0, 0, 1, 1, 0, 0, 0, 1 ];
 // Render mode configurations
 export const FINAL_RENDER_CONFIG = {
 	maxSamples: 30, bounces: 20, transmissiveBounces: 8, samplesPerPixel: 1,
-	renderMode: 1, tiles: 3, tilesHelper: false,
+	renderMode: 1, enableAlphaShadows: true, tiles: 3, tilesHelper: false,
 	enableOIDN: true, oidnQuality: 'balance',
 	interactionModeEnabled: false,
 };
 
 export const PREVIEW_RENDER_CONFIG = {
 	maxSamples: ENGINE_DEFAULTS.maxSamples, bounces: ENGINE_DEFAULTS.bounces,
-	samplesPerPixel: ENGINE_DEFAULTS.samplesPerPixel, renderMode: ENGINE_DEFAULTS.renderMode,
+	samplesPerPixel: ENGINE_DEFAULTS.samplesPerPixel, renderMode: ENGINE_DEFAULTS.renderMode, enableAlphaShadows: ENGINE_DEFAULTS.enableAlphaShadows,
 	transmissiveBounces: ENGINE_DEFAULTS.transmissiveBounces,
 	tiles: ENGINE_DEFAULTS.tiles, tilesHelper: ENGINE_DEFAULTS.tilesHelper,
 	enableOIDN: false, oidnQuality: 'fast',

package/src/PathTracerApp.js

@@ -730,6 +730,7 @@ export class PathTracerApp extends EventDispatcher {
 		}, { silent: true } );
 
 		this.stages.pathTracer?.setUniform( 'renderMode', parseInt( config.renderMode ) );
+		this.stages.pathTracer?.setUniform( 'enableAlphaShadows', config.enableAlphaShadows ?? false );
 		this.stages.pathTracer?.tileManager?.setTileCount( config.tiles );
 
 		const tileHelper = this.overlayManager?.getHelper( 'tiles' );

package/src/Processor/ShaderBuilder.js

@@ -17,6 +17,7 @@ import { TextureNode } from 'three/webgpu';
 import { LinearFilter, DataArrayTexture } from 'three';
 import { pathTracerMain } from '../TSL/PathTracer.js';
 import { setMeshVisibilityBuffer } from '../TSL/BVHTraversal.js';
+import { setShadowAlbedoMaps, setAlphaShadowsUniform } from '../TSL/LightsDirect.js';
 import { BuildTimer } from './BuildTimer.js';
 
 const WG_SIZE = 8;
@@ -192,6 +193,9 @@ export class ShaderBuilder {
 		// Set per-mesh visibility buffer (module-level in BVHTraversal.js, read during graph construction)
 		setMeshVisibilityBuffer( stage.meshVisibilityStorageNode );
 
+		// Set alpha-shadow uniform (module-level in LightsDirect.js, read at runtime)
+		setAlphaShadowsUniform( stage.uniforms.get( 'enableAlphaShadows' ) );
+
 		const envTex = texture( stage.environment.environmentTexture );
 
 		// Adaptive sampling texture
@@ -228,6 +232,11 @@ export class ShaderBuilder {
 		const emissiveMapsTex = mat.emissiveMaps ? texture( mat.emissiveMaps ) : createArrayPlaceholder();
 		const displacementMapsTex = mat.displacementMaps ? texture( mat.displacementMaps ) : createArrayPlaceholder();
 
+		// Set albedo texture array for alpha-aware shadow rays (module-level in LightsDirect.js).
+		// Always pass the texture node (real or placeholder) so alpha-cutout code is emitted
+		// into the shader at graph construction time. Runtime albedoMapIndex >= 0 guards sampling.
+		setShadowAlbedoMaps( albedoMapsTex );
+
 		const result = {
 			triStorage, bvhStorage, matStorage, emissiveTriStorage, lightBVHStorage,
 			envTex, adaptiveSamplingTex, marginalCDFStorage, conditionalCDFStorage,

package/src/Processor/TextureCreator.js

@@ -1,5 +1,5 @@
 import { DataArrayTexture, RGBAFormat, LinearFilter, UnsignedByteType, SRGBColorSpace } from "three";
-import { TEXTURE_CONSTANTS, MEMORY_CONSTANTS, DEFAULT_TEXTURE_MATRIX } from '../EngineDefaults.js';
+import { TEXTURE_CONSTANTS, MEMORY_CONSTANTS, DEFAULT_TEXTURE_MATRIX, MATERIAL_DATA_LAYOUT } from '../EngineDefaults.js';
 
 // Canvas pooling for efficient reuse of canvas elements
 class CanvasPool {
@@ -858,9 +858,9 @@ export class TextureCreator {
 	 */
 	createMaterialRawData( materials ) {
 
-		const pixelsRequired = TEXTURE_CONSTANTS.PIXELS_PER_MATERIAL;
-		const dataInEachPixel = TEXTURE_CONSTANTS.RGBA_COMPONENTS;
-		const dataLengthPerMaterial = pixelsRequired * dataInEachPixel;
+		// Layout is defined by MATERIAL_DATA_LAYOUT in EngineDefaults.js.
+		// The inline array below must match that layout exactly (positional order = canonical layout).
+		const dataLengthPerMaterial = MATERIAL_DATA_LAYOUT.FLOATS_PER_MATERIAL;
 		const totalMaterials = materials.length;
 
 		const size = totalMaterials * dataLengthPerMaterial;
@@ -879,19 +879,34 @@ export class TextureCreator {
 			const bumpMapMatrices = mat.bumpMapMatrices ?? DEFAULT_TEXTURE_MATRIX;
 			const displacementMapMatrices = mat.displacementMapMatrices ?? DEFAULT_TEXTURE_MATRIX;
 
+			// Slot order: shadow/culling → BxDF core → maps → extended → displacement → transforms
+			// Must match MATERIAL_DATA_LAYOUT in EngineDefaults.js exactly.
 			const materialData = [
-				mat.color.r, 				mat.color.g, 				mat.color.b, 				mat.metalness,
-				mat.emissive.r, 			mat.emissive.g, 			mat.emissive.b, 			mat.roughness,
+				// Slot 0: shadow core (ior, transmission, thickness, emissiveIntensity)
 				mat.ior, 					mat.transmission, 			mat.thickness, 				mat.emissiveIntensity,
+				// Slot 1: shadow (attenuationColor, attenuationDistance)
 				mat.attenuationColor.r, 	mat.attenuationColor.g, 	mat.attenuationColor.b, 	mat.attenuationDistance,
+				// Slot 2: shadow + culling (opacity, side, transparent, alphaTest)
+				mat.opacity, 				mat.side, 					mat.transparent, 			mat.alphaTest,
+				// Slot 3: shadow (alphaMode, depthWrite, normalScale)
+				mat.alphaMode, 				mat.depthWrite, 			mat.normalScale?.x ?? 1, 	mat.normalScale?.y ?? 1,
+				// Slot 4: BxDF core (color, metalness)
+				mat.color.r, 				mat.color.g, 				mat.color.b, 				mat.metalness,
+				// Slot 5: BxDF core (emissive, roughness)
+				mat.emissive.r, 			mat.emissive.g, 			mat.emissive.b, 			mat.roughness,
+				// Slot 6: map indices A (albedo, normal, roughness, metalness)
+				mat.map, 					mat.normalMap, 				mat.roughnessMap, 			mat.metalnessMap,
+				// Slot 7: map indices B (emissive, bump, clearcoat, clearcoatRoughness)
+				mat.emissiveMap, 			mat.bumpMap, 				mat.clearcoat, 				mat.clearcoatRoughness,
+				// Slot 8: extended BxDF (dispersion, visible, sheen, sheenRoughness)
 				mat.dispersion, 			mat.visible, 				mat.sheen, 					mat.sheenRoughness,
+				// Slot 9: extended BxDF (sheenColor, reserved)
 				mat.sheenColor.r, 			mat.sheenColor.g, 			mat.sheenColor.b, 			1,
+				// Slot 10: extended BxDF (specularIntensity, specularColor)
 				mat.specularIntensity, 		mat.specularColor.r, 		mat.specularColor.g, 		mat.specularColor.b,
+				// Slot 11: extended BxDF (iridescence)
 				mat.iridescence, 			mat.iridescenceIOR, 		mat.iridescenceThicknessRange[ 0 ], mat.iridescenceThicknessRange[ 1 ],
-				mat.map, 					mat.normalMap, 				mat.roughnessMap, 			mat.metalnessMap,
-				mat.emissiveMap, 			mat.bumpMap, 				mat.clearcoat, 				mat.clearcoatRoughness,
-				mat.opacity, 				mat.side, 					mat.transparent, 			mat.alphaTest,
-				mat.alphaMode, 				mat.depthWrite, 			mat.normalScale?.x ?? 1, 	mat.normalScale?.y ?? 1,
+				// Slot 12: displacement
 				mat.bumpScale,				mat.displacementScale,		mat.displacementMap,		0,
 				mapMatrix[ 0 ], 			mapMatrix[ 1 ], 			mapMatrix[ 2 ], 			mapMatrix[ 3 ],
 				mapMatrix[ 4 ], 			mapMatrix[ 5 ], 			mapMatrix[ 6 ], 			1,

package/src/RenderSettings.js

@@ -31,6 +31,7 @@ const SETTING_ROUTES = {
 	anamorphicRatio: { uniform: 'anamorphicRatio', reset: true },
 	samplingTechnique: { uniform: 'samplingTechnique', reset: true },
 	fireflyThreshold: { uniform: 'fireflyThreshold', reset: true },
+	enableAlphaShadows: { uniform: 'enableAlphaShadows', reset: true },
 	enableEmissiveTriangleSampling: { uniform: 'enableEmissiveTriangleSampling', reset: true },
 	emissiveBoost: { uniform: 'emissiveBoost', reset: true },
 	visMode: { uniform: 'visMode', reset: true },

package/src/TSL/BVHTraversal.js

@@ -26,7 +26,7 @@ import {
 } from 'three/tsl';
 
 import { Ray, HitInfo } from './Struct.js';
-import { getDatafromStorageBuffer, MATERIAL_SLOTS } from './Common.js';
+import { getDatafromStorageBuffer, MATERIAL_SLOTS, MATERIAL_SLOT } from './Common.js';
 import { RandomPointInCircle } from './Random.js';
 
 // ================================================================================
@@ -136,7 +136,7 @@ const fastRayAABBDst = wgslFn( `
 // Per-mesh visibility handled at BLAS-pointer level; material visibility always 1.
 export const passesSideCulling = Fn( ( [ materialIndex, rayDirection, normal, materialBuffer ] ) => {
 
-	const sideData = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 10 ), int( MATERIAL_SLOTS ) );
+	const sideData = getDatafromStorageBuffer( materialBuffer, materialIndex, int( MATERIAL_SLOT.OPACITY_ALPHA ), int( MATERIAL_SLOTS ) );
 	const side = int( sideData.g );
 	const rayDotNormal = rayDirection.dot( normal );
 	const doubleSide = side.equal( int( 2 ) );
@@ -268,7 +268,7 @@ export const traverseBVH = Fn( ( [
 				} );
 
 				// If we found a very close hit, we can terminate early
-				If( closestHit.didHit.and( closestHit.dst.lessThan( 1e-6 ) ), () => {
+				If( closestHit.didHit.and( closestHit.dst.lessThan( 0.001 ) ), () => {
 
 					Break();
 
@@ -451,6 +451,12 @@ export const traverseBVHShadow = Fn( ( [
 						closestHit.hitPoint.assign( ray.origin.add( ray.direction.mul( triResult.x ) ) );
 						closestHit.normal.assign( normalize( cross( pB.sub( pA ), pC.sub( pA ) ) ) );
 
+						// Store barycentrics + triangle index for deferred UV computation.
+						// Actual UV interpolation happens in traceShadowRay only when
+						// the material needs alpha testing — zero overhead for opaque hits.
+						closestHit.uv.assign( vec2( triResult.y, triResult.z ) );
+						closestHit.triangleIndex.assign( triIndex );
+
 						// Shadow ray only needs any hit — skip remaining triangles in leaf
 						Break();
 

package/src/TSL/Common.js

@@ -5,6 +5,7 @@ import {
 	MaterialClassification,
 	MISStrategy,
 	RayTracingMaterial,
+	ShadowMaterial,
 } from './Struct.js';
 
 export const PI = 3.14159;
@@ -16,7 +17,11 @@ export const MIN_CLEARCOAT_ROUGHNESS = 0.089;
 export const MAX_ROUGHNESS = 1.0;
 export const MIN_PDF = 0.001;
 export const REC709_LUMINANCE_COEFFICIENTS = vec3( 0.2126, 0.7152, 0.0722 );
-export const MATERIAL_SLOTS = 27;
+import { MATERIAL_DATA_LAYOUT } from '../EngineDefaults.js';
+
+export const MATERIAL_SLOTS = MATERIAL_DATA_LAYOUT.SLOTS_PER_MATERIAL;
+export const MATERIAL_SLOT = MATERIAL_DATA_LAYOUT.SLOT;
+const S = MATERIAL_SLOT;
 
 // XYZ to sRGB color space conversion matrix
 export const XYZ_TO_REC709 = mat3(
@@ -313,33 +318,33 @@ export const arrayToMat3 = wgslFn( `
 
 export const getMaterial = Fn( ( [ materialIndex, materialBuffer ] ) => {
 
-	const data0 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 0 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data1 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 1 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data2 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 2 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data3 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 3 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data4 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 4 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data5 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 5 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data6 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 6 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data7 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 7 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data8 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 8 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data9 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 9 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data10 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 10 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data11 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 11 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data12 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 12 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data13 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 13 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data14 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 14 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data15 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 15 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data16 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 16 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data17 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 17 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data18 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 18 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data19 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 19 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data20 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 20 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data21 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 21 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data22 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 22 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data23 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 23 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data24 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 24 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data25 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 25 ), int( MATERIAL_SLOTS ) ).toVar();
-	const data26 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( 26 ), int( MATERIAL_SLOTS ) ).toVar();
+	const data0 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.COLOR_METALNESS ), int( MATERIAL_SLOTS ) ).toVar();
+	const data1 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.EMISSIVE_ROUGHNESS ), int( MATERIAL_SLOTS ) ).toVar();
+	const data2 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.IOR_TRANSMISSION ), int( MATERIAL_SLOTS ) ).toVar();
+	const data3 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ATTENUATION ), int( MATERIAL_SLOTS ) ).toVar();
+	const data4 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.DISPERSION_SHEEN ), int( MATERIAL_SLOTS ) ).toVar();
+	const data5 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.SHEEN_COLOR ), int( MATERIAL_SLOTS ) ).toVar();
+	const data6 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.SPECULAR ), int( MATERIAL_SLOTS ) ).toVar();
+	const data7 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.IRIDESCENCE ), int( MATERIAL_SLOTS ) ).toVar();
+	const data8 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.MAP_INDICES_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data9 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.MAP_INDICES_B ), int( MATERIAL_SLOTS ) ).toVar();
+	const data10 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.OPACITY_ALPHA ), int( MATERIAL_SLOTS ) ).toVar();
+	const data11 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ALPHA_MODE ), int( MATERIAL_SLOTS ) ).toVar();
+	const data12 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.BUMP_DISPLACEMENT ), int( MATERIAL_SLOTS ) ).toVar();
+	const data13 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ALBEDO_TRANSFORM_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data14 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ALBEDO_TRANSFORM_B ), int( MATERIAL_SLOTS ) ).toVar();
+	const data15 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.NORMAL_TRANSFORM_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data16 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.NORMAL_TRANSFORM_B ), int( MATERIAL_SLOTS ) ).toVar();
+	const data17 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ROUGHNESS_TRANSFORM_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data18 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ROUGHNESS_TRANSFORM_B ), int( MATERIAL_SLOTS ) ).toVar();
+	const data19 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.METALNESS_TRANSFORM_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data20 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.METALNESS_TRANSFORM_B ), int( MATERIAL_SLOTS ) ).toVar();
+	const data21 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.EMISSIVE_TRANSFORM_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data22 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.EMISSIVE_TRANSFORM_B ), int( MATERIAL_SLOTS ) ).toVar();
+	const data23 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.BUMP_TRANSFORM_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data24 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.BUMP_TRANSFORM_B ), int( MATERIAL_SLOTS ) ).toVar();
+	const data25 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.DISPLACEMENT_TRANSFORM_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data26 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.DISPLACEMENT_TRANSFORM_B ), int( MATERIAL_SLOTS ) ).toVar();
 
 	return RayTracingMaterial( {
 		color: vec4( data0.rgb, 1.0 ),
@@ -390,6 +395,35 @@ export const getMaterial = Fn( ( [ materialIndex, materialBuffer ] ) => {
 
 } );
 
+// ── Shadow material thin reader (7 slot reads instead of 27) ─────────────
+// Only fetches fields needed by traceShadowRay: alpha, transmission, attenuation, albedo transform.
+
+export const getShadowMaterial = Fn( ( [ materialIndex, materialBuffer ] ) => {
+
+	const data2 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.IOR_TRANSMISSION ), int( MATERIAL_SLOTS ) ).toVar();
+	const data3 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ATTENUATION ), int( MATERIAL_SLOTS ) ).toVar();
+	const data8 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.MAP_INDICES_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data10 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.OPACITY_ALPHA ), int( MATERIAL_SLOTS ) ).toVar();
+	const data11 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ALPHA_MODE ), int( MATERIAL_SLOTS ) ).toVar();
+	const data13 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ALBEDO_TRANSFORM_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data14 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.ALBEDO_TRANSFORM_B ), int( MATERIAL_SLOTS ) ).toVar();
+
+	return ShadowMaterial( {
+		color: vec4( 1.0 ), // Shadow path never samples full textures; color.a is always 1.0
+		ior: data2.r,
+		transmission: data2.g,
+		attenuationColor: data3.rgb,
+		attenuationDistance: data3.a,
+		albedoMapIndex: int( data8.r ),
+		opacity: data10.r,
+		transparent: data10.b,
+		alphaTest: data10.a,
+		alphaMode: int( data11.r ),
+		albedoTransform: arrayToMat3( { data1: data13, data2: data14 } ),
+	} );
+
+} );
+
 // ── Edge-stopping weight (normal + depth) ──────────────────────────────────
 // Used by ASVGF and SSRC for temporal/spatial reprojection edge-stopping.
 

package/src/TSL/Debugger.js

@@ -356,8 +356,7 @@ export const TraceDebugMode = Fn( ( [
 			const bounceDir = cosineWeightedSample( { N: normalA, xi } ).toVar();
 
 			// Trace secondary ray from the hit point (offset along normal to avoid self-intersection)
-			const debugEps = max( float( 1e-4 ), length( hitInfo.hitPoint ).mul( 1e-6 ) );
-			const bounceOrigin = hitInfo.hitPoint.add( normalA.mul( debugEps ) ).toVar();
+			const bounceOrigin = hitInfo.hitPoint.add( normalA.mul( 0.001 ) ).toVar();
 			const bounceRay = Ray( { origin: bounceOrigin, direction: bounceDir } );
 
 			const bounceHit = HitInfo.wrap( traverseBVH(

package/src/TSL/EmissiveSampling.js

@@ -28,7 +28,7 @@ import {
 } from 'three/tsl';
 
 import { struct } from './structProxy.js';
-import { MIN_PDF, getDatafromStorageBuffer, powerHeuristic } from './Common.js';
+import { MIN_PDF, getDatafromStorageBuffer, powerHeuristic, MATERIAL_SLOTS, MATERIAL_SLOT } from './Common.js';
 import { RandomValue } from './Random.js';
 import { calculateMaterialPDF } from './LightsSampling.js';
 
@@ -326,9 +326,8 @@ export const calculateEmissiveLightPdf = Fn( ( [
 	const area = triangleArea( triData.v0, triData.v1, triData.v2 );
 
 	// Targeted material read: only fetch emissive data (2 vec4s instead of full 27)
-	const MATERIAL_SLOTS = int( 27 );
-	const matData1 = getDatafromStorageBuffer( materialBuffer, triData.materialIndex, int( 1 ), MATERIAL_SLOTS );
-	const matData2 = getDatafromStorageBuffer( materialBuffer, triData.materialIndex, int( 2 ), MATERIAL_SLOTS );
+	const matData1 = getDatafromStorageBuffer( materialBuffer, triData.materialIndex, int( MATERIAL_SLOT.EMISSIVE_ROUGHNESS ), MATERIAL_SLOTS );
+	const matData2 = getDatafromStorageBuffer( materialBuffer, triData.materialIndex, int( MATERIAL_SLOT.IOR_TRANSMISSION ), MATERIAL_SLOTS );
 	const avgEmissive = matData1.x.add( matData1.y ).add( matData1.z ).div( 3.0 );
 	const power = max( avgEmissive.mul( matData2.a ).mul( area ), float( 1e-10 ) );
 	const selectionPdf = power.div( max( emissiveTotalPower, float( 1e-10 ) ) );

package/src/TSL/LightsCore.js

@@ -257,7 +257,7 @@ export const intersectAreaLight = Fn( ( [ light, rayOrigin, rayDirection ] ) =>
 		const t = dot( light.position.sub( rayOrigin ), normal ).mul( invDenom ).toVar();
 
 		// Skip intersections behind the ray
-		If( t.greaterThan( 1e-5 ), () => {
+		If( t.greaterThan( 0.001 ), () => {
 
 			// Optimized rectangle test using vector rejection
 			const hitPoint = rayOrigin.add( rayDirection.mul( t ) );

package/src/TSL/LightsDirect.js

@@ -25,10 +25,11 @@ import {
 	clamp,
 	smoothstep,
 	select,
+	texture,
 } from 'three/tsl';
 
-import { Ray, RayTracingMaterial, HitInfo, DirectionSample, MaterialCache } from './Struct.js';
-import { PI, TWO_PI, EPSILON, REC709_LUMINANCE_COEFFICIENTS, powerHeuristic, getMaterial } from './Common.js';
+import { Ray, ShadowMaterial, HitInfo, DirectionSample, MaterialCache } from './Struct.js';
+import { PI, TWO_PI, EPSILON, REC709_LUMINANCE_COEFFICIENTS, powerHeuristic, getShadowMaterial, getDatafromStorageBuffer } from './Common.js';
 import { fresnelSchlickFloat } from './Fresnel.js';
 import { iorToFresnel0 } from './Fresnel.js';
 import {
@@ -37,6 +38,33 @@ import {
 } from './LightsCore.js';
 import { calculateBeerLawAbsorption, calculateShadowTransmittance } from './MaterialTransmission.js';
 import { RandomValue } from './Random.js';
+import { getTransformedUV } from './TextureSampling.js';
+
+// Module-level state for alpha-cutout shadow testing.
+// Set by ShaderBuilder before graph construction (same pattern as _meshVisibilityBuffer in BVHTraversal.js).
+let _shadowAlbedoMaps = null;
+let _enableAlphaShadows = null;
+
+/**
+ * Set the albedo texture array node for alpha-aware shadow rays.
+ * Must be called before the shader graph is constructed.
+ * @param {TextureNode} maps - TSL texture node for the albedo array
+ */
+export function setShadowAlbedoMaps( maps ) {
+
+	_shadowAlbedoMaps = maps;
+
+}
+
+/**
+ * Set the runtime uniform node that toggles alpha-cutout shadows.
+ * @param {UniformNode} node - TSL int uniform (0 = disabled, 1 = enabled)
+ */
+export function setAlphaShadowsUniform( node ) {
+
+	_enableAlphaShadows = node;
+
+}
 
 // ================================================================================
 // SHADOW RAY MATERIAL TRANSPARENCY
@@ -102,11 +130,82 @@ export const traceShadowRay = Fn( ( [
 
 		} );
 
-		// Fetch material for the hit surface
-		const shadowMaterial = RayTracingMaterial.wrap( getMaterial( shadowHit.materialIndex, materialBuffer ) );
+		// Fetch material for the hit surface (thin reader: 7 slots instead of 27)
+		const shadowMaterial = ShadowMaterial.wrap( getShadowMaterial( shadowHit.materialIndex, materialBuffer ) );
+
+		// ---------------------------------------------------------------
+		// Alpha-cutout handling (MASK / BLEND with albedo texture alpha)
+		// Gated by runtime uniform + alphaMode check — zero overhead for opaque materials.
+		// UV computation deferred here from BVH traversal: barycentrics stored in shadowHit.uv,
+		// triangle index in shadowHit.triangleIndex. Actual UV interpolation only when needed.
+		// ---------------------------------------------------------------
+		const alphaCutout = tslBool( false ).toVar();
+
+		if ( _enableAlphaShadows ) If( _enableAlphaShadows.equal( int( 1 ) ), () => {
+
+			// Sample texture alpha once (shared by MASK and BLEND paths).
+			// Deferred UV: barycentrics in shadowHit.uv, triangle index in shadowHit.triangleIndex.
+			const texAlpha = float( 1.0 ).toVar();
+
+			if ( _shadowAlbedoMaps ) {
+
+				If( shadowMaterial.albedoMapIndex.greaterThanEqual( int( 0 ) ), () => {
+
+					const baryU = shadowHit.uv.x;
+					const baryV = shadowHit.uv.y;
+					const baryW = float( 1.0 ).sub( baryU ).sub( baryV );
+					const TRI_STRIDE = int( 8 );
+					const uvData1 = getDatafromStorageBuffer( triangleBuffer, shadowHit.triangleIndex, int( 6 ), TRI_STRIDE );
+					const uvData2 = getDatafromStorageBuffer( triangleBuffer, shadowHit.triangleIndex, int( 7 ), TRI_STRIDE );
+					const hitUV = uvData1.xy.mul( baryW ).add( uvData1.zw.mul( baryU ) ).add( uvData2.xy.mul( baryV ) );
+					const albedoUV = getTransformedUV( { uv: hitUV, transform: shadowMaterial.albedoTransform } );
+					texAlpha.assign( texture( _shadowAlbedoMaps, albedoUV ).depth( int( shadowMaterial.albedoMapIndex ) ).a );
+
+				} );
+
+			}
+
+			If( shadowMaterial.alphaMode.equal( int( 1 ) ), () => {
+
+				// MASK mode: binary alpha cutout
+				const effectiveAlpha = shadowMaterial.color.a.mul( texAlpha );
+				const cutoff = select( shadowMaterial.alphaTest.greaterThan( 0.0 ), shadowMaterial.alphaTest, float( 0.5 ) );
+				If( effectiveAlpha.lessThan( cutoff ), () => {
+
+					alphaCutout.assign( true );
+
+				} );
+
+			} ).ElseIf( shadowMaterial.alphaMode.equal( int( 2 ) ), () => {
+
+				// BLEND mode: modulate transmittance by alpha
+				const blendAlpha = clamp( shadowMaterial.color.a.mul( shadowMaterial.opacity ).mul( texAlpha ), 0.0, 1.0 );
+				transmittance.mulAssign( float( 1.0 ).sub( blendAlpha ) );
+
+				If( transmittance.lessThan( 0.005 ), () => {
+
+					transmittance.assign( 0.0 );
+					Break();
+
+				} );
+
+				alphaCutout.assign( true );
+
+			} );
+
+		} );
+
+		// ---------------------------------------------------------------
+		// Surface interaction: alpha-skip, transmission, transparent, or opaque
+		// ---------------------------------------------------------------
+		If( alphaCutout, () => {
+
+			// Alpha-transparent surface — advance ray past it
+			const alphaEps = max( float( 1e-5 ), length( shadowHit.hitPoint ).mul( 1e-6 ) );
+			rayOrigin.assign( shadowHit.hitPoint.add( dir.mul( alphaEps ) ) );
+			remainingDist.subAssign( shadowHit.dst.add( alphaEps ) );
 
-		// Handle transmissive materials
-		If( shadowMaterial.transmission.greaterThan( 0.0 ), () => {
+		} ).ElseIf( shadowMaterial.transmission.greaterThan( 0.0 ), () => {
 
 			const entering = dot( dir, shadowHit.normal ).lessThan( 0.0 );
 			const N = select( entering, shadowHit.normal, shadowHit.normal.negate() );
@@ -142,9 +241,8 @@ export const traceShadowRay = Fn( ( [
 			} );
 
 			// Continue ray past transmissive surface
-			const transEps = max( float( 1e-5 ), length( shadowHit.hitPoint ).mul( 1e-6 ) );
-			rayOrigin.assign( shadowHit.hitPoint.add( dir.mul( transEps ) ) );
-			remainingDist.subAssign( shadowHit.dst.add( transEps ) );
+			rayOrigin.assign( shadowHit.hitPoint.add( dir.mul( 0.001 ) ) );
+			remainingDist.subAssign( shadowHit.dst.add( 0.001 ) );
 
 		} ).ElseIf( shadowMaterial.transparent, () => {
 
@@ -159,9 +257,8 @@ export const traceShadowRay = Fn( ( [
 			} );
 
 			// Continue ray past transparent surface
-			const alphaEps = max( float( 1e-5 ), length( shadowHit.hitPoint ).mul( 1e-6 ) );
-			rayOrigin.assign( shadowHit.hitPoint.add( dir.mul( alphaEps ) ) );
-			remainingDist.subAssign( shadowHit.dst.add( alphaEps ) );
+			rayOrigin.assign( shadowHit.hitPoint.add( dir.mul( 0.001 ) ) );
+			remainingDist.subAssign( shadowHit.dst.add( 0.001 ) );
 
 		} ).Else( () => {
 
@@ -259,7 +356,7 @@ export const estimateLightImportance = Fn( ( [ light, hitPoint, normal, material
 
 		If( lightFacing.greaterThan( 0.0 ), () => {
 
-			const solidAngle = light.area.div( max( distSq, 1e-4 ) );
+			const solidAngle = light.area.div( max( distSq, 0.1 ) );
 			const power = light.intensity.mul( dot( light.color, REC709_LUMINANCE_COEFFICIENTS ) ).mul( light.area );
 
 			// Material-aware weighting
@@ -661,7 +758,7 @@ export const calculatePointLightContribution = Fn( ( [
 			const rayOffset = calculateRayOffset( hitPoint, normal, material );
 			const rayOrigin = hitPoint.add( rayOffset );
 
-			const visibility = traceShadowRayFn( rayOrigin, lightDir, distance.mul( 0.999 ), rngState );
+			const visibility = traceShadowRayFn( rayOrigin, lightDir, distance.sub( 0.001 ), rngState );
 
 			If( visibility.greaterThan( 0.0 ), () => {
 
@@ -713,7 +810,7 @@ export const calculateSpotLightContribution = Fn( ( [
 				const rayOffset = calculateRayOffset( hitPoint, normal, material );
 				const rayOrigin = hitPoint.add( rayOffset );
 
-				const visibility = traceShadowRayFn( rayOrigin, lightDir, distance.mul( 0.999 ), rngState );
+				const visibility = traceShadowRayFn( rayOrigin, lightDir, distance.sub( 0.001 ), rngState );
 
 				If( visibility.greaterThan( 0.0 ), () => {
 

package/src/TSL/LightsSampling.js

@@ -71,7 +71,6 @@ import {
 	calculatePointLightImportance,
 	calculateSpotLightImportance,
 	traceShadowRay,
-	calculateRayOffset,
 } from './LightsDirect.js';
 
 import { traverseBVHShadow } from './BVHTraversal.js';
@@ -941,7 +940,7 @@ export const calculateDirectLightingUnified = Fn( ( [
 ] ) => {
 
 	const totalContribution = vec3( 0.0 ).toVar();
-	const rayOrigin = hitPoint.add( calculateRayOffset( hitPoint, hitNormal, material ) ).toVar();
+	const rayOrigin = hitPoint.add( hitNormal.mul( 0.001 ) ).toVar();
 
 	// Early exit for highly emissive surfaces
 	If( material.emissiveIntensity.lessThanEqual( 10.0 ), () => {
@@ -1042,7 +1041,7 @@ export const calculateDirectLightingUnified = Fn( ( [
 
 				If( NoL.greaterThan( 0.0 ).and( lightImportance.mul( NoL ).greaterThan( importanceThreshold ) ).and( isDirectionValid( { direction: lightSample.direction, surfaceNormal: hitNormal } ) ), () => {
 
-					const shadowDistance = min( lightSample.distance.mul( 0.999 ), float( 1000.0 ) ).toVar();
+					const shadowDistance = min( lightSample.distance.sub( 0.001 ), float( 1000.0 ) ).toVar();
 					const visibility = traceShadowRay(
 						rayOrigin, lightSample.direction, shadowDistance, rngState,
 						traverseBVHShadow,