rayzee 6.4.0 → 6.5.0

package/package.json

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

package/src/EngineDefaults.js

@@ -65,6 +65,7 @@ export const ENGINE_DEFAULTS = {
 	bounces: 3,
 	samplesPerPixel: 1,
 	transmissiveBounces: 5,
+	maxSubsurfaceSteps: 8, // interactive default: low cap (bounded random-walk SSS)
 	samplingTechnique: 3,
 	enableEmissiveTriangleSampling: false,
 	emissiveBoost: 1.0,
@@ -356,8 +357,8 @@ export const TRIANGLE_DATA_LAYOUT = {
 // 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)
+	SLOTS_PER_MATERIAL: 30, // vec4 slots per material
+	FLOATS_PER_MATERIAL: 120, // total floats per material (30 × 4)
 
 	// ── Flat float offsets (CPU side) ────────────────────────────────
 	// Used as: data[ materialIndex * FLOATS_PER_MATERIAL + offset ]
@@ -399,6 +400,14 @@ export const MATERIAL_DATA_LAYOUT = {
 	BUMP_TRANSFORM: 92,
 	DISPLACEMENT_TRANSFORM: 100,
 
+	// ── Subsurface scattering (3 slots appended after transforms) ────
+	// Slot 27: subsurfaceColor.rgb (scatter albedo) + subsurface weight
+	SUBSURFACE_COLOR: 108, SUBSURFACE: 111,
+	// Slot 28: subsurfaceRadius.rgb (mean free path) + radius scale
+	SUBSURFACE_RADIUS: 112, SUBSURFACE_RADIUS_SCALE: 115,
+	// Slot 29: anisotropy g (floats 117-119 reserved for future SSS)
+	SUBSURFACE_ANISOTROPY: 116,
+
 	// ── Vec4 slot indices (GPU/TSL side) ─────────────────────────────
 	// Used with getDatafromStorageBuffer( buf, matIdx, int(slot), int(SLOTS_PER_MATERIAL) )
 	SLOT: {
@@ -422,6 +431,9 @@ export const MATERIAL_DATA_LAYOUT = {
 		EMISSIVE_TRANSFORM_A: 21, EMISSIVE_TRANSFORM_B: 22,
 		BUMP_TRANSFORM_A: 23, BUMP_TRANSFORM_B: 24,
 		DISPLACEMENT_TRANSFORM_A: 25, DISPLACEMENT_TRANSFORM_B: 26,
+		SUBSURFACE_A: 27, // subsurfaceColor.rgb, subsurface weight
+		SUBSURFACE_B: 28, // subsurfaceRadius.rgb, subsurfaceRadiusScale
+		SUBSURFACE_C: 29, // subsurfaceAnisotropy, reserved
 	},
 
 };
@@ -434,7 +446,7 @@ export const BVH_LEAF_MARKERS = {
 
 // Texture processing constants
 export const TEXTURE_CONSTANTS = {
-	PIXELS_PER_MATERIAL: 27,
+	PIXELS_PER_MATERIAL: 30,
 	RGBA_COMPONENTS: 4,
 	VEC4_PER_TRIANGLE: 8,
 	VEC4_PER_BVH_NODE: 4,
@@ -454,7 +466,7 @@ export const DEFAULT_TEXTURE_MATRIX = [ 0, 0, 1, 1, 0, 0, 0, 1 ];
 // 'interactive' — low-sample, bounded bounces, no offline denoising, controls enabled.
 // 'production'  — high-sample, deep bounces, OIDN enabled, controls disabled.
 export const PRODUCTION_RENDER_CONFIG = {
-	maxSamples: 30, bounces: 20, transmissiveBounces: 8, samplesPerPixel: 1,
+	maxSamples: 30, bounces: 20, transmissiveBounces: 8, maxSubsurfaceSteps: 64, samplesPerPixel: 1,
 	renderMode: 1, enableAlphaShadows: true, tiles: 3, tilesHelper: true,
 	enableOIDN: true, oidnQuality: 'balance',
 	interactionModeEnabled: false,
@@ -464,6 +476,7 @@ export const INTERACTIVE_RENDER_CONFIG = {
 	maxSamples: ENGINE_DEFAULTS.maxSamples, bounces: ENGINE_DEFAULTS.bounces,
 	samplesPerPixel: ENGINE_DEFAULTS.samplesPerPixel, renderMode: ENGINE_DEFAULTS.renderMode, enableAlphaShadows: ENGINE_DEFAULTS.enableAlphaShadows,
 	transmissiveBounces: ENGINE_DEFAULTS.transmissiveBounces,
+	maxSubsurfaceSteps: ENGINE_DEFAULTS.maxSubsurfaceSteps,
 	tiles: ENGINE_DEFAULTS.tiles, tilesHelper: ENGINE_DEFAULTS.tilesHelper,
 	enableOIDN: false, oidnQuality: 'fast',
 	interactionModeEnabled: true,

package/src/PathTracerApp.js

@@ -922,6 +922,7 @@ export class PathTracerApp extends EventDispatcher {
 			maxBounces: config.bounces,
 			samplesPerPixel: config.samplesPerPixel,
 			transmissiveBounces: config.transmissiveBounces,
+			maxSubsurfaceSteps: config.maxSubsurfaceSteps,
 		}, { silent: true } );
 
 		this.stages.pathTracer?.setUniform( 'renderMode', parseInt( config.renderMode ) );

package/src/Processor/GeometryExtractor.js

@@ -160,6 +160,7 @@ export class GeometryExtractor {
 			if ( newMaterial.iridescence > 0 ) this.sceneFeatures.hasIridescence = true;
 			if ( newMaterial.sheen > 0 ) this.sceneFeatures.hasSheen = true;
 			if ( newMaterial.transparent || newMaterial.opacity < 1.0 || newMaterial.alphaTest > 0 ) this.sceneFeatures.hasTransparency = true;
+			if ( newMaterial.subsurface > 0 ) this.sceneFeatures.hasSubsurface = true;
 
 			// Detect multi-lobe materials (require multi-lobe MIS for optimal sampling)
 			const featureCount = [
@@ -259,7 +260,13 @@ export class GeometryExtractor {
 			normalScale: { x: 1, y: 1 },
 			bumpScale: 1.0,
 			displacementScale: 1.0,
-			alphaTest: 0.0
+			alphaTest: 0.0,
+			// Subsurface scattering (no native MeshPhysicalMaterial equivalent)
+			subsurface: 0.0,
+			subsurfaceColor: new Color( 0xffffff ),
+			subsurfaceRadius: [ 1.0, 0.2, 0.1 ], // skin-like: red travels furthest
+			subsurfaceRadiusScale: 1.0,
+			subsurfaceAnisotropy: 0.0
 		};
 
 	}
@@ -390,6 +397,13 @@ export class GeometryExtractor {
 			iridescenceIOR: material.iridescenceIOR ?? defaults.iridescenceIOR,
 			iridescenceThicknessRange: material.iridescenceThicknessRange ?? defaults.iridescenceThicknessRange,
 
+			// Subsurface scattering (custom props; MeshPhysicalMaterial has none)
+			subsurface: material.subsurface ?? defaults.subsurface,
+			subsurfaceColor: material.subsurfaceColor ?? defaults.subsurfaceColor,
+			subsurfaceRadius: material.subsurfaceRadius ?? defaults.subsurfaceRadius,
+			subsurfaceRadiusScale: material.subsurfaceRadiusScale ?? defaults.subsurfaceRadiusScale,
+			subsurfaceAnisotropy: material.subsurfaceAnisotropy ?? defaults.subsurfaceAnisotropy,
+
 			// Specular properties (for compatibility)
 			specularIntensity: legacyMapping.specularIntensity ?? material.specularIntensity ?? defaults.specularIntensity,
 			specularColor: legacyMapping.specularColor ?? material.specularColor ?? defaults.specularColor,
@@ -789,6 +803,7 @@ export class GeometryExtractor {
 			hasIridescence: false,
 			hasSheen: false,
 			hasTransparency: false,
+			hasSubsurface: false,
 			hasMultiLobeMaterials: false, // Materials with 2+ BRDF lobes
 			hasMRTOutputs: true // Always enabled for ASVGF/adaptive sampling support
 		};

package/src/Processor/ShaderBuilder.js

@@ -411,6 +411,7 @@ export class ShaderBuilder {
 					groundProjectionHeight: stage.groundProjectionHeight,
 					maxBounceCount: stage.maxBounces,
 					transmissiveBounces: stage.transmissiveBounces,
+					maxSubsurfaceSteps: stage.maxSubsurfaceSteps,
 					showBackground: stage.showBackground,
 					transparentBackground: stage.transparentBackground,
 					backgroundIntensity: stage.backgroundIntensity,

package/src/Processor/TextureCreator.js

@@ -965,6 +965,12 @@ export class TextureCreator {
 				bumpMapMatrices[ 4 ], 		bumpMapMatrices[ 5 ],	 	bumpMapMatrices[ 6 ], 		1,
 				displacementMapMatrices[ 0 ], displacementMapMatrices[ 1 ], displacementMapMatrices[ 2 ], displacementMapMatrices[ 3 ],
 				displacementMapMatrices[ 4 ], displacementMapMatrices[ 5 ], displacementMapMatrices[ 6 ], 1,
+				// Slot 27: subsurface (subsurfaceColor.rgb, subsurface weight)
+				mat.subsurfaceColor?.r ?? 1,	mat.subsurfaceColor?.g ?? 1,	mat.subsurfaceColor?.b ?? 1,	mat.subsurface ?? 0,
+				// Slot 28: subsurface (subsurfaceRadius.rgb, subsurfaceRadiusScale)
+				mat.subsurfaceRadius?.[ 0 ] ?? 1, mat.subsurfaceRadius?.[ 1 ] ?? 0.2, mat.subsurfaceRadius?.[ 2 ] ?? 0.1, mat.subsurfaceRadiusScale ?? 1,
+				// Slot 29: subsurface (anisotropy g, reserved)
+				mat.subsurfaceAnisotropy ?? 0,	0,	0,	0,
 			];
 
 			data.set( materialData, stride );

package/src/RenderSettings.js

@@ -18,6 +18,7 @@ const SETTING_ROUTES = {
 	maxBounces: { uniform: 'maxBounces', reset: true },
 	samplesPerPixel: { uniform: 'samplesPerPixel', reset: true },
 	transmissiveBounces: { uniform: 'transmissiveBounces', reset: true },
+	maxSubsurfaceSteps: { uniform: 'maxSubsurfaceSteps', reset: true },
 	environmentIntensity: { uniform: 'environmentIntensity', reset: true },
 	backgroundIntensity: { uniform: 'backgroundIntensity', reset: true },
 	showBackground: { uniform: 'showBackground', reset: true },

package/src/TSL/BVHTraversal.js

@@ -19,6 +19,7 @@ import {
 	lessThan,
 	mat3,
 	array,
+	bool as tslBool,
 } from 'three/tsl';
 
 import { Ray, HitInfo } from './Struct.js';
@@ -178,8 +179,13 @@ export const traverseBVH = Fn( ( [
 	ray,
 	bvhBuffer,
 	triangleBuffer,
+	insideMedium, // optional: when true (ray inside a medium), bypass front/back culling
 ] ) => {
 
+	// Interior medium rays (SSS/transmission) must be able to hit boundary faces from
+	// either side to find the exit; exterior rays honor the authored side as before.
+	const inMedium = insideMedium ?? tslBool( false );
+
 	const closestHit = HitInfo( {
 		didHit: false,
 		dst: float( 1e20 ),
@@ -280,7 +286,7 @@ export const traverseBVH = Fn( ( [
 
 						// Side culling (inline; per-mesh visibility is at the BLAS-pointer level).
 						// 0=front (reject back-facing), 1=back (reject front-facing), 2=double (pass).
-						const sidePass = side.equal( int( 2 ) )
+						const sidePass = inMedium.or( side.equal( int( 2 ) ) )
 							.or( side.equal( int( 0 ) ).and( rayDotNormal.lessThan( - 0.0001 ) ) )
 							.or( side.equal( int( 1 ) ).and( rayDotNormal.greaterThan( 0.0001 ) ) );
 						If( sidePass, () => {

package/src/TSL/Common.js

@@ -201,13 +201,14 @@ export const applySoftSuppressionRGB = wgslFn( `
 `, [ applySoftSuppression ] );
 
 // Pre-computed material classification for faster branching
-export const classifyMaterial = Fn( ( [ metalness, roughness, transmission, clearcoat, emissive ] ) => {
+export const classifyMaterial = Fn( ( [ metalness, roughness, transmission, clearcoat, emissive, subsurface ] ) => {
 
 	const isMetallic = metalness.greaterThan( 0.7 ).toVar();
 	const isRough = roughness.greaterThan( 0.8 );
 	const isSmooth = roughness.lessThan( 0.3 ).toVar();
 	const isTransmissive = transmission.greaterThan( 0.5 ).toVar();
 	const hasClearcoat = clearcoat.greaterThan( 0.5 ).toVar();
+	const isSubsurface = subsurface.greaterThan( 0.0 ); // only feeds complexityScore below
 
 	// Fast emissive check using sum
 	const emissiveMag = emissive.x.add( emissive.y ).add( emissive.z );
@@ -218,7 +219,8 @@ export const classifyMaterial = Fn( ( [ metalness, roughness, transmission, clea
 		.add( float( 0.25 ).mul( float( isSmooth ) ) )
 		.add( float( 0.45 ).mul( float( isTransmissive ) ) )
 		.add( float( 0.35 ).mul( float( hasClearcoat ) ) )
-		.add( float( 0.3 ).mul( float( isEmissive ) ) );
+		.add( float( 0.3 ).mul( float( isEmissive ) ) )
+		.add( float( 0.4 ).mul( float( isSubsurface ) ) ); // SSS walks are deep + high-value → keep alive in RR
 
 	// Add material interaction complexity
 	const interactionComplexity = float( 0.0 ).toVar();
@@ -340,6 +342,9 @@ export const getMaterial = Fn( ( [ materialIndex, materialBuffer ] ) => {
 	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();
+	const data27 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.SUBSURFACE_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data28 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.SUBSURFACE_B ), int( MATERIAL_SLOTS ) ).toVar();
+	const data29 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.SUBSURFACE_C ), int( MATERIAL_SLOTS ) ).toVar();
 
 	return RayTracingMaterial( {
 		color: vec4( data0.rgb, 1.0 ),
@@ -361,6 +366,11 @@ export const getMaterial = Fn( ( [ materialIndex, materialBuffer ] ) => {
 		iridescence: data7.r,
 		iridescenceIOR: data7.g,
 		iridescenceThicknessRange: data7.ba,
+		subsurfaceColor: data27.rgb,
+		subsurface: data27.a,
+		subsurfaceRadius: data28.rgb,
+		subsurfaceRadiusScale: data28.a,
+		subsurfaceAnisotropy: data29.r,
 		albedoMapIndex: int( data8.r ),
 		normalMapIndex: int( data8.g ),
 		roughnessMapIndex: int( data8.b ),

package/src/TSL/MaterialTransmission.js

@@ -27,6 +27,7 @@ import { iorToFresnel0, fresnelSchlickFloat } from './Fresnel.js';
 import { DistributionGGX } from './MaterialProperties.js';
 import { ImportanceSampleGGX } from './MaterialSampling.js';
 import { RandomValue, pcgHash } from './Random.js';
+import { handleSubsurfaceEntry, SubsurfaceEntryResult } from './Subsurface.js';
 
 // ================================================================================
 // STRUCTS (local to transmission)
@@ -43,6 +44,7 @@ export const MaterialInteractionResult = struct( {
 	continueRay: 'bool', // Whether the ray should continue without further BRDF evaluation
 	isTransmissive: 'bool', // Flag to indicate this was a transmissive interaction
 	isAlphaSkip: 'bool', // Flag to indicate this was an alpha skip
+	isSubsurface: 'bool', // Flag to indicate this entered/exited a subsurface medium
 	didReflect: 'bool', // Whether TIR/reflection occurred (for medium stack update)
 	entering: 'bool', // Whether ray is entering or exiting medium
 	direction: 'vec3', // New ray direction if continuing
@@ -493,6 +495,7 @@ export const handleMaterialTransparency = Fn( ( [
 		continueRay: false,
 		isTransmissive: false,
 		isAlphaSkip: false,
+		isSubsurface: false,
 		didReflect: false,
 		entering: false,
 		direction: ray.direction,
@@ -501,8 +504,9 @@ export const handleMaterialTransparency = Fn( ( [
 		pathWavelength: pathWavelength,
 	} ).toVar();
 
-	// Fast path for fully opaque materials (most common case)
-	If( material.alphaMode.equal( int( 0 ) ).and( material.transmission.lessThanEqual( 0.0 ) ), () => {
+	// Fast path for fully opaque, non-scattering materials (most common case).
+	// Subsurface materials are opaque (transmission==0) but must NOT take this path.
+	If( material.alphaMode.equal( int( 0 ) ).and( material.transmission.lessThanEqual( 0.0 ) ).and( material.subsurface.lessThanEqual( 0.0 ) ), () => {
 
 		// no interaction needed
 
@@ -584,6 +588,32 @@ export const handleMaterialTransparency = Fn( ( [
 
 		} );
 
+		// Subsurface (independent of transmission; works at transmission==0). Entry is a lottery
+		// (prob = weight) so 1-weight falls through to the opaque BRDF; exit is deterministic.
+		If( handled.not().and( material.subsurface.greaterThan( 0.0 ) ), () => {
+
+			const entering = dot( ray.direction, normal ).lessThan( 0.0 );
+			const doEnter = entering.not().or( RandomValue( rngState ).lessThan( material.subsurface ) );
+
+			If( doEnter, () => {
+
+				const ssResult = SubsurfaceEntryResult.wrap( handleSubsurfaceEntry(
+					ray.direction, normal, material, entering, rngState,
+					currentMediumIOR, previousMediumIOR,
+				) ).toVar();
+
+				result.direction.assign( ssResult.direction );
+				result.throughput.assign( ssResult.throughput );
+				result.continueRay.assign( true );
+				result.isSubsurface.assign( true );
+				result.didReflect.assign( ssResult.didReflect );
+				result.entering.assign( entering );
+				result.alpha.assign( 1.0 );
+
+			} );
+
+		} );
+
 	} );
 
 	return result;

package/src/TSL/PathTracer.js

@@ -151,7 +151,7 @@ export const pathTracerMain = ( params ) => {
 		envTotalSum, envCompensationDelta, envResolution,
 		enableEnvironmentLight, useEnvMapIS,
 		groundProjectionEnabled, groundProjectionRadius, groundProjectionHeight,
-		maxBounceCount, transmissiveBounces,
+		maxBounceCount, transmissiveBounces, maxSubsurfaceSteps,
 		showBackground, transparentBackground, backgroundIntensity,
 		fireflyThreshold, globalIlluminationIntensity,
 		enableEmissiveTriangleSampling,
@@ -299,7 +299,7 @@ export const pathTracerMain = ( params ) => {
 				envTotalSum, envCompensationDelta, envResolution,
 				enableEnvironmentLight, useEnvMapIS,
 				groundProjectionEnabled, groundProjectionRadius, groundProjectionHeight,
-				maxBounceCount, transmissiveBounces,
+				maxBounceCount, transmissiveBounces, maxSubsurfaceSteps,
 				backgroundIntensity, showBackground, transparentBackground,
 				fireflyThreshold, globalIlluminationIntensity,
 				enableEmissiveTriangleSampling,

package/src/TSL/PathTracerCore.js

@@ -77,6 +77,7 @@ import { sampleEnvironment, sampleEquirect, getGroundProjectedDirection } from '
 import { sampleAllMaterialTextures } from './TextureSampling.js';
 import { refineDisplacedIntersection, DisplacementResult } from './Displacement.js';
 import { handleMaterialTransparency, MaterialInteractionResult, sampleMicrofacetTransmission, MicrofacetTransmissionResult } from './MaterialTransmission.js';
+import { subsurfaceCoefficients, sampleChromaticCollision, sampleHenyeyGreenstein, MediumCoeffs, CollisionSample } from './Subsurface.js';
 import {
 	SheenDistribution,
 	calculateVNDFPDF,
@@ -140,7 +141,7 @@ export const getOrCreateMaterialClassification = Fn( ( [
 		result.assign( classifyMaterial(
 			material.metalness, material.roughness,
 			material.transmission, material.clearcoat,
-			material.emissive,
+			material.emissive, material.subsurface,
 		) );
 
 	} );
@@ -538,7 +539,7 @@ export const Trace = Fn( ( [
 	enableEnvironmentLight, useEnvMapIS,
 	groundProjectionEnabled, groundProjectionRadius, groundProjectionHeight,
 	// Rendering parameters
-	maxBounceCount, transmissiveBounces,
+	maxBounceCount, transmissiveBounces, maxSubsurfaceSteps,
 	backgroundIntensity, showBackground, transparentBackground,
 	fireflyThreshold, globalIlluminationIntensity,
 	enableEmissiveTriangleSampling,
@@ -584,6 +585,18 @@ export const Trace = Fn( ( [
 	const mediumStack_sigmaA_1 = vec3( 0.0 ).toVar();
 	const mediumStack_sigmaA_2 = vec3( 0.0 ).toVar();
 	const mediumStack_sigmaA_3 = vec3( 0.0 ).toVar();
+	// Subsurface: sigma_s>0 makes the medium scatter (random walk) rather than absorb straight.
+	const mediumStack_sigmaS_1 = vec3( 0.0 ).toVar();
+	const mediumStack_sigmaS_2 = vec3( 0.0 ).toVar();
+	const mediumStack_sigmaS_3 = vec3( 0.0 ).toVar();
+	const mediumStack_sigmaT_1 = vec3( 0.0 ).toVar();
+	const mediumStack_sigmaT_2 = vec3( 0.0 ).toVar();
+	const mediumStack_sigmaT_3 = vec3( 0.0 ).toVar();
+	const mediumStack_g_1 = float( 0.0 ).toVar();
+	const mediumStack_g_2 = float( 0.0 ).toVar();
+	const mediumStack_g_3 = float( 0.0 ).toVar();
+	// Walk-step budget for the whole path (bounded per render mode + RR).
+	const sssSteps = int( 0 ).toVar();
 
 	// Locked at the first dispersive transmission; reused for subsequent transmissions on
 	// the path so multi-bounce dispersion doesn't collapse under repeated colorWeight ×.
@@ -633,7 +646,7 @@ export const Trace = Fn( ( [
 	const rayDirection = ray.direction.toVar();
 
 	// Main bounce loop
-	Loop( { start: int( 0 ), end: maxBounceCount.add( transmissiveBounces ).add( 1 ), type: 'int', condition: '<' }, ( { i: bounceIndex } ) => {
+	Loop( { start: int( 0 ), end: maxBounceCount.add( transmissiveBounces ).add( maxSubsurfaceSteps ).add( 1 ), type: 'int', condition: '<' }, ( { i: bounceIndex } ) => {
 
 		// Update state
 		stateTraversals.assign( maxBounceCount.sub( effectiveBounces ) );
@@ -656,30 +669,82 @@ export const Trace = Fn( ( [
 			currentRay,
 			bvhBuffer,
 			triangleBuffer,
+			mediumStackDepth.greaterThan( int( 0 ) ), // inside a medium → bypass front/back culling
 		) ).toVar();
 
-		// KHR_materials_volume: apply Beer's law over the actual distance the ray
-		// traveled inside the current medium. Top-of-stack holds the medium the ray
-		// is currently in — depth==0 means air (no absorption). sigma_a was
-		// precomputed at push time, so this collapses to a single exp().
+		// In-medium transport: glass (sigma_s==0) absorbs along a straight line; subsurface
+		// (sigma_s>0) random-walks and may scatter mid-flight.
 		If( hitInfo.didHit.and( mediumStackDepth.greaterThan( int( 0 ) ) ), () => {
 
+			// Load current-medium coefficients (chained branch — divergence-safe).
 			const mSigmaA = vec3( 0.0 ).toVar();
+			const mSigmaS = vec3( 0.0 ).toVar();
+			const mSigmaT = vec3( 0.0 ).toVar();
+			const mG = float( 0.0 ).toVar();
 			If( mediumStackDepth.equal( int( 1 ) ), () => {
 
-				mSigmaA.assign( mediumStack_sigmaA_1 );
+				mSigmaA.assign( mediumStack_sigmaA_1 ); mSigmaS.assign( mediumStack_sigmaS_1 );
+				mSigmaT.assign( mediumStack_sigmaT_1 ); mG.assign( mediumStack_g_1 );
 
 			} ).ElseIf( mediumStackDepth.equal( int( 2 ) ), () => {
 
-				mSigmaA.assign( mediumStack_sigmaA_2 );
+				mSigmaA.assign( mediumStack_sigmaA_2 ); mSigmaS.assign( mediumStack_sigmaS_2 );
+				mSigmaT.assign( mediumStack_sigmaT_2 ); mG.assign( mediumStack_g_2 );
 
 			} ).ElseIf( mediumStackDepth.equal( int( 3 ) ), () => {
 
-				mSigmaA.assign( mediumStack_sigmaA_3 );
+				mSigmaA.assign( mediumStack_sigmaA_3 ); mSigmaS.assign( mediumStack_sigmaS_3 );
+				mSigmaT.assign( mediumStack_sigmaT_3 ); mG.assign( mediumStack_g_3 );
 
 			} );
 
-			throughput.mulAssign( exp( mSigmaA.mul( hitInfo.dst ).negate() ) );
+			If( maxComponent( { v: mSigmaS } ).lessThanEqual( 0.0 ), () => {
+
+				// Non-scattering medium (glass): straight-line Beer-Lambert absorption.
+				throughput.mulAssign( exp( mSigmaA.mul( hitInfo.dst ).negate() ) );
+
+			} ).Else( () => {
+
+				// Scattering medium (subsurface): chromatic distance sampling for this segment.
+				const coll = CollisionSample.wrap( sampleChromaticCollision(
+					mSigmaT, mSigmaS, throughput, hitInfo.dst, rngState,
+				) ).toVar();
+				throughput.mulAssign( coll.weight );
+
+				If( coll.didScatter, () => {
+
+					// Scatter: move to the collision point, redirect via the HG phase function,
+					// continue as a free bounce (no camera-bounce cost).
+					const xi2 = vec2( RandomValue( rngState ), RandomValue( rngState ) );
+					const scatterPoint = rayOrigin.add( rayDirection.mul( coll.t ) );
+					rayOrigin.assign( scatterPoint );
+					rayDirection.assign( sampleHenyeyGreenstein( rayDirection, mG, xi2 ) );
+					sssSteps.addAssign( 1 );
+					stateIsPrimaryRay.assign( tslBool( false ) );
+
+					// Per-mode step cap: bounded walk (terminate — energy-loss-only bias).
+					If( sssSteps.greaterThanEqual( maxSubsurfaceSteps ), () => {
+
+						Break();
+
+					} );
+
+					// Russian roulette so the walk self-terminates before the cap.
+					const rrP = clamp( maxComponent( { v: throughput } ), 0.02, 1.0 ).toVar();
+					If( RandomValue( rngState ).greaterThan( rrP ), () => {
+
+						Break();
+
+					} );
+					throughput.divAssign( rrP );
+
+					Continue();
+
+				} );
+
+				// No scatter: reached the boundary (weight applied); fall through to surface handling.
+
+			} );
 
 		} );
 
@@ -732,7 +797,7 @@ export const Trace = Fn( ( [
 
 		} );
 
-		// Get full material (27 reads). Lazy transform loading was tested but regressed
+		// Get full material (30 reads). Lazy transform loading was tested but regressed
 		// textured scenes due to identity-construct + conditional-assign overhead.
 		// Shadow rays use getShadowMaterial() (7 reads) — the real bandwidth win.
 		const material = RayTracingMaterial.wrap( getMaterial( hitInfo.materialIndex, materialBuffer ) ).toVar();
@@ -833,6 +898,7 @@ export const Trace = Fn( ( [
 								mediumStack_attColor_1.assign( material.attenuationColor );
 								mediumStack_attDist_1.assign( material.attenuationDistance );
 								mediumStack_sigmaA_1.assign( mSigmaA );
+								mediumStack_sigmaS_1.assign( vec3( 0.0 ) ); // glass: no scattering
 
 							} ).ElseIf( mediumStackDepth.equal( int( 2 ) ), () => {
 
@@ -840,6 +906,7 @@ export const Trace = Fn( ( [
 								mediumStack_attColor_2.assign( material.attenuationColor );
 								mediumStack_attDist_2.assign( material.attenuationDistance );
 								mediumStack_sigmaA_2.assign( mSigmaA );
+								mediumStack_sigmaS_2.assign( vec3( 0.0 ) ); // glass: no scattering
 
 							} ).ElseIf( mediumStackDepth.equal( int( 3 ) ), () => {
 
@@ -847,6 +914,7 @@ export const Trace = Fn( ( [
 								mediumStack_attColor_3.assign( material.attenuationColor );
 								mediumStack_attDist_3.assign( material.attenuationDistance );
 								mediumStack_sigmaA_3.assign( mSigmaA );
+								mediumStack_sigmaS_3.assign( vec3( 0.0 ) ); // glass: no scattering
 
 							} );
 
@@ -865,6 +933,65 @@ export const Trace = Fn( ( [
 
 				} );
 
+			} ).ElseIf( interaction.isSubsurface, () => {
+
+				// Subsurface boundary: free bounce (SSS step budget, not camera bounces). Push on enter, pop on exit.
+				isFreeBounce.assign( tslBool( true ) );
+				stateRayType.assign( int( RAY_TYPE_DIFFUSE ) );
+
+				If( interaction.didReflect.not(), () => {
+
+					If( interaction.entering, () => {
+
+						If( mediumStackDepth.lessThan( int( 3 ) ), () => {
+
+							mediumStackDepth.addAssign( 1 );
+
+							const ssCoeffs = MediumCoeffs.wrap( subsurfaceCoefficients(
+								material.subsurfaceColor, material.subsurfaceRadius, material.subsurfaceRadiusScale,
+							) ).toVar();
+							const ssG = clamp( material.subsurfaceAnisotropy, - 0.99, 0.99 ).toVar();
+
+							If( mediumStackDepth.equal( int( 1 ) ), () => {
+
+								mediumStack_ior_1.assign( material.ior );
+								mediumStack_sigmaA_1.assign( ssCoeffs.sigmaA );
+								mediumStack_sigmaS_1.assign( ssCoeffs.sigmaS );
+								mediumStack_sigmaT_1.assign( ssCoeffs.sigmaT );
+								mediumStack_g_1.assign( ssG );
+
+							} ).ElseIf( mediumStackDepth.equal( int( 2 ) ), () => {
+
+								mediumStack_ior_2.assign( material.ior );
+								mediumStack_sigmaA_2.assign( ssCoeffs.sigmaA );
+								mediumStack_sigmaS_2.assign( ssCoeffs.sigmaS );
+								mediumStack_sigmaT_2.assign( ssCoeffs.sigmaT );
+								mediumStack_g_2.assign( ssG );
+
+							} ).ElseIf( mediumStackDepth.equal( int( 3 ) ), () => {
+
+								mediumStack_ior_3.assign( material.ior );
+								mediumStack_sigmaA_3.assign( ssCoeffs.sigmaA );
+								mediumStack_sigmaS_3.assign( ssCoeffs.sigmaS );
+								mediumStack_sigmaT_3.assign( ssCoeffs.sigmaT );
+								mediumStack_g_3.assign( ssG );
+
+							} );
+
+						} );
+
+					} ).Else( () => {
+
+						If( mediumStackDepth.greaterThan( int( 0 ) ), () => {
+
+							mediumStackDepth.subAssign( 1 );
+
+						} );
+
+					} );
+
+				} );
+
 			} ).ElseIf( interaction.isAlphaSkip, () => {
 
 				isFreeBounce.assign( tslBool( true ) );

package/src/TSL/Struct.js

@@ -50,6 +50,11 @@ export const RayTracingMaterial = struct( {
 	iridescence: 'float',
 	iridescenceIOR: 'float',
 	iridescenceThicknessRange: 'vec2',
+	subsurface: 'float', // 0 = off, blends opaque BRDF → random-walk SSS
+	subsurfaceColor: 'vec3', // single-scatter albedo (tint light picks up inside)
+	subsurfaceRadius: 'vec3', // per-channel mean free path
+	subsurfaceRadiusScale: 'float', // scalar multiplier on radius
+	subsurfaceAnisotropy: 'float', // Henyey-Greenstein g (-1..1)
 } );
 
 // Lightweight material for shadow ray evaluation — only the fields needed