rayzee 8.5.0 → 8.6.0

package/src/Processor/GeometryExtractor.js

@@ -1,6 +1,6 @@
 import { BufferAttribute, Vector3, Vector2, Color, Matrix3, Matrix4, FrontSide, BackSide, DoubleSide, RGBAFormat } from "three";
 import {
-	TEXTURE_CONSTANTS, TRIANGLE_DATA_LAYOUT, packNormalOct, packTriangleFlags
+	TEXTURE_CONSTANTS, TRIANGLE_DATA_LAYOUT, MATERIAL_DEFAULTS, packNormalOct, packTriangleFlags
 } from '../EngineDefaults.js';
 import { ISSUE_CODES } from '../EngineIssues.js';
 import { ChunkedRecords, SHARED_MEMORY_AVAILABLE } from './ChunkedRecords.js';
@@ -10,6 +10,20 @@ const log = createLogger( 'geometry' );
 
 const MAX_TEXTURES_LIMIT = TEXTURE_CONSTANTS.MAX_TEXTURES_LIMIT;
 
+const COLOR_DEFAULTS = new Set( [ 'color', 'emissive', 'attenuationColor', 'sheenColor', 'specularColor', 'subsurfaceColor' ] );
+
+/**
+ * Where a packed material value came from: the three.js material carried it, a legacy-type
+ * conversion (Basic/Lambert/Phong/Toon) produced it, the engine filled it from
+ * MATERIAL_DEFAULTS, or a host set it at runtime through setMaterialProperty.
+ */
+export const MATERIAL_VALUE_SOURCE = Object.freeze( {
+	MATERIAL: 'material',
+	MAPPED: 'mapped',
+	DEFAULT: 'default',
+	HOST: 'host',
+} );
+
 const IDENTITY_ELEMENTS = [ 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1 ];
 
 function isIdentityElements( e ) {
@@ -19,6 +33,36 @@ function isIdentityElements( e ) {
 
 }
 
+/**
+ * The texture that feeds each GPU map slot. Re-packing texture indices without this loses the
+ * unlit routing (a MeshBasicMaterial's map is also its emission map).
+ * @param {import('three').Material} material
+ * @returns {Object<string, import('three').Texture|undefined>}
+ */
+export function resolveMaterialTextures( material ) {
+
+	return {
+		map: material.map,
+		normalMap: material.normalMap,
+		bumpMap: material.bumpMap,
+		roughnessMap: material.roughnessMap,
+		metalnessMap: material.metalnessMap,
+		emissiveMap: material.emissiveMap ?? ( material.isMeshBasicMaterial ? material.map : undefined ),
+		displacementMap: material.displacementMap,
+		anisotropyMap: material.anisotropyMap,
+		clearcoatMap: material.clearcoatMap,
+		clearcoatRoughnessMap: material.clearcoatRoughnessMap,
+		transmissionMap: material.transmissionMap,
+		sheenColorMap: material.sheenColorMap,
+		sheenRoughnessMap: material.sheenRoughnessMap,
+		specularIntensityMap: material.specularIntensityMap,
+		specularColorMap: material.specularColorMap,
+		iridescenceMap: material.iridescenceMap,
+		iridescenceThicknessMap: material.iridescenceThicknessMap,
+	};
+
+}
+
 /**
  * glTF 2.0 alphaMode for a three.js material: 0 OPAQUE, 1 MASK, 2 BLEND.
  *
@@ -734,43 +778,15 @@ export class GeometryExtractor {
 
 	getPhysicalDefaults() {
 
-		// Defaults optimized for physically-based path tracing
-		return {
-			emissive: new Color( 0, 0, 0 ),
-			emissiveIntensity: 1.0,
-			roughness: 1.0,
-			metalness: 0.0,
-			ior: 1.5, // Common dielectric IOR (glass, plastic)
-			opacity: 1.0,
-			transmission: 0.0,
-			thickness: 0.1,
-			attenuationColor: new Color( 0xffffff ),
-			attenuationDistance: Infinity, // No attenuation by default
-			dispersion: 0.0,
-			sheen: 0.0,
-			sheenRoughness: 1.0,
-			sheenColor: new Color( 0x000000 ),
-			specularIntensity: 1.0,
-			specularColor: new Color( 0xffffff ),
-			clearcoat: 0.0,
-			clearcoatRoughness: 0.0,
-			iridescence: 0.0,
-			iridescenceIOR: 1.3,
-			iridescenceThicknessRange: [ 100, 400 ],
-			normalScale: { x: 1, y: 1 },
-			bumpScale: 1.0,
-			displacementScale: 1.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,
-			// Surface specular anisotropy (native MeshPhysicalMaterial / KHR_materials_anisotropy)
-			anisotropy: 0.0,
-			anisotropyRotation: 0.0
-		};
+		const defaults = {};
+		for ( const [ key, value ] of Object.entries( MATERIAL_DEFAULTS ) ) {
+
+			defaults[ key ] = COLOR_DEFAULTS.has( key ) ? new Color().fromArray( value ) : Array.isArray( value ) ? [ ...value ] : value;
+
+		}
+
+		defaults.normalScale = { x: MATERIAL_DEFAULTS.normalScale[ 0 ], y: MATERIAL_DEFAULTS.normalScale[ 1 ] };
+		return defaults;
 
 	}
 
@@ -782,12 +798,13 @@ export class GeometryExtractor {
 		switch ( materialType ) {
 
 			case 'basic':
-				// MeshBasicMaterial -> Unlit/Emissive material
+				// Unlit (GLTFLoader's KHR_materials_unlit): colour and texture are emission, nothing reflects.
 				mapped.emissive = material.color.clone();
 				mapped.emissiveIntensity = 1.0;
-				mapped.color = new Color( 0x000000 ); // No diffuse reflection
+				mapped.color = new Color( 0x000000 );
 				mapped.roughness = 1.0;
 				mapped.metalness = 0.0;
+				mapped.specularIntensity = 0.0;
 				break;
 
 			case 'lambert':
@@ -807,14 +824,14 @@ export class GeometryExtractor {
 
 				}
 
-				// Convert specular color to specular intensity
+				// Strength in specularIntensity, hue alone in specularColor; carrying it in both squared it.
 				if ( material.specular ) {
 
-					const specularLuminance = material.specular.r * 0.299 +
-                                        material.specular.g * 0.587 +
-                                        material.specular.b * 0.114;
+					const s = material.specular;
+					const specularLuminance = s.r * 0.299 + s.g * 0.587 + s.b * 0.114;
+					const peak = Math.max( s.r, s.g, s.b );
 					mapped.specularIntensity = Math.min( specularLuminance * 2.0, 1.0 );
-					mapped.specularColor = material.specular.clone();
+					mapped.specularColor = peak > 0 ? s.clone().multiplyScalar( 1 / peak ) : new Color( 1, 1, 1 );
 
 				}
 
@@ -842,121 +859,117 @@ export class GeometryExtractor {
 		const defaults = this.getPhysicalDefaults();
 		const materialType = this.getMaterialType( material );
 		const legacyMapping = this.mapLegacyMaterialToPhysical( material, materialType );
+		const textures = resolveMaterialTextures( material );
+		const sources = {};
 
-		// A transmissive surface is a dielectric interface whose IOR drives refraction, so it wins
-		// over the metal Fresnel hack: glTF defaults metallicFactor to 1, which otherwise stamps
-		// 2.5 onto water/glass authored as MeshStandardMaterial.
-		const isTransmissive = ( material.transmission ?? 0.0 ) > 0.0;
-		const isMetallic = ( material.metalness ?? legacyMapping.metalness ?? 0.0 ) > 0.1;
-		const defaultIOR = ( isMetallic && ! isTransmissive ) ? 2.5 : defaults.ior;
+		const pick = ( key ) => {
 
-		// Handle color conversion for different material types
-		let baseColor = material.color || new Color( 0xffffff );
-		if ( materialType === 'basic' && ! material.map ) {
+			if ( legacyMapping[ key ] !== undefined ) {
 
-			// For basic materials without textures, treat color as emissive
-			baseColor = new Color( 0x000000 );
+				sources[ key ] = MATERIAL_VALUE_SOURCE.MAPPED;
+				return legacyMapping[ key ];
 
-		}
+			}
+
+			if ( material[ key ] !== undefined && material[ key ] !== null ) {
+
+				sources[ key ] = MATERIAL_VALUE_SOURCE.MATERIAL;
+				return material[ key ];
+
+			}
+
+			sources[ key ] = MATERIAL_VALUE_SOURCE.DEFAULT;
+			return defaults[ key ];
+
+		};
+
+		for ( const key of [ 'transparent', 'alphaMode', 'side', 'depthWrite' ] ) sources[ key ] = MATERIAL_VALUE_SOURCE.MATERIAL;
 
 		return {
 			uuid: material.uuid,
 
-			// Base material properties
-			color: baseColor,
-			emissive: legacyMapping.emissive ?? material.emissive ?? defaults.emissive,
-			emissiveIntensity: legacyMapping.emissiveIntensity ?? material.emissiveIntensity ?? defaults.emissiveIntensity,
+			color: pick( 'color' ),
+			emissive: pick( 'emissive' ),
+			emissiveIntensity: pick( 'emissiveIntensity' ),
 
-			// Surface properties
 			// Floor at 0.02 (the sampler's own VNDF-PDF clamp, MaterialProperties.js) rather than
 			// 0.05, so near-mirror metals stay sharp without entering a new firefly regime.
-			roughness: Math.max( 0.02, legacyMapping.roughness ?? material.roughness ?? defaults.roughness ),
-			metalness: legacyMapping.metalness ?? material.metalness ?? defaults.metalness,
-
-			// Optical properties
-			ior: material.ior ?? defaultIOR,
-			opacity: material.opacity ?? defaults.opacity,
-
-			// Transmission properties (MeshPhysicalMaterial only)
-			transmission: material.transmission ?? defaults.transmission,
-			thickness: material.thickness ?? defaults.thickness,
-			attenuationColor: material.attenuationColor ?? defaults.attenuationColor,
-			attenuationDistance: material.attenuationDistance ?? defaults.attenuationDistance,
-
-			// Advanced properties (MeshPhysicalMaterial only)
-			dispersion: material.dispersion ?? defaults.dispersion,
-			sheen: material.sheen ?? defaults.sheen,
-			sheenRoughness: material.sheenRoughness ?? defaults.sheenRoughness,
-			sheenColor: material.sheenColor ?? defaults.sheenColor,
-			clearcoat: material.clearcoat ?? defaults.clearcoat,
-			clearcoatRoughness: material.clearcoatRoughness ?? defaults.clearcoatRoughness,
-			iridescence: material.iridescence ?? defaults.iridescence,
-			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,
-
-			// Surface specular anisotropy (native MeshPhysicalMaterial / KHR_materials_anisotropy)
-			anisotropy: material.anisotropy ?? defaults.anisotropy,
-			anisotropyRotation: material.anisotropyRotation ?? defaults.anisotropyRotation,
-
-			// Specular properties (for compatibility)
-			specularIntensity: legacyMapping.specularIntensity ?? material.specularIntensity ?? defaults.specularIntensity,
-			specularColor: legacyMapping.specularColor ?? material.specularColor ?? defaults.specularColor,
-
-			// Surface detail properties
-			normalScale: material.normalScale ?? defaults.normalScale,
-			bumpScale: material.bumpScale ?? defaults.bumpScale,
-			displacementScale: material.displacementScale ?? defaults.displacementScale,
-
-			// Transparency and alpha
+			roughness: Math.max( 0.02, pick( 'roughness' ) ),
+			metalness: pick( 'metalness' ),
+
+			ior: pick( 'ior' ),
+			opacity: pick( 'opacity' ),
+
+			transmission: pick( 'transmission' ),
+			thickness: pick( 'thickness' ),
+			attenuationColor: pick( 'attenuationColor' ),
+			attenuationDistance: pick( 'attenuationDistance' ),
+
+			dispersion: pick( 'dispersion' ),
+			sheen: pick( 'sheen' ),
+			sheenRoughness: pick( 'sheenRoughness' ),
+			sheenColor: pick( 'sheenColor' ),
+			clearcoat: pick( 'clearcoat' ),
+			clearcoatRoughness: pick( 'clearcoatRoughness' ),
+			iridescence: pick( 'iridescence' ),
+			iridescenceIOR: pick( 'iridescenceIOR' ),
+			iridescenceThicknessRange: pick( 'iridescenceThicknessRange' ),
+
+			subsurface: pick( 'subsurface' ),
+			subsurfaceColor: pick( 'subsurfaceColor' ),
+			subsurfaceRadius: pick( 'subsurfaceRadius' ),
+			subsurfaceRadiusScale: pick( 'subsurfaceRadiusScale' ),
+			subsurfaceAnisotropy: pick( 'subsurfaceAnisotropy' ),
+
+			anisotropy: pick( 'anisotropy' ),
+			anisotropyRotation: pick( 'anisotropyRotation' ),
+
+			specularIntensity: pick( 'specularIntensity' ),
+			specularColor: pick( 'specularColor' ),
+
+			normalScale: pick( 'normalScale' ),
+			bumpScale: pick( 'bumpScale' ),
+			displacementScale: pick( 'displacementScale' ),
+
 			transparent: material.transparent ? 1 : 0,
-			alphaTest: material.alphaTest ?? defaults.alphaTest,
+			alphaTest: pick( 'alphaTest' ),
 			alphaMode: deriveAlphaMode( material ),
 
-			// Rendering properties
 			side: this.getMaterialSide( material ),
 			depthWrite: material.depthWrite ?? true ? 1 : 0,
 
-			// Texture processing
-			map: this.processTexture( material.map, this.maps ),
-			normalMap: this.processTexture( material.normalMap, this.normalMaps ),
-			bumpMap: this.processTexture( material.bumpMap, this.bumpMaps ),
-			roughnessMap: this.processTexture( material.roughnessMap, this.roughnessMaps ),
-			metalnessMap: this.processTexture( material.metalnessMap, this.metalnessMaps ),
-			emissiveMap: this.processTexture( material.emissiveMap, this.emissiveMaps ),
-			displacementMap: this.processTexture( material.displacementMap, this.displacementMaps ),
-			anisotropyMap: this.processTexture( material.anisotropyMap, this.anisotropyMaps ),
+			map: this.processTexture( textures.map, this.maps ),
+			normalMap: this.processTexture( textures.normalMap, this.normalMaps ),
+			bumpMap: this.processTexture( textures.bumpMap, this.bumpMaps ),
+			roughnessMap: this.processTexture( textures.roughnessMap, this.roughnessMaps ),
+			metalnessMap: this.processTexture( textures.metalnessMap, this.metalnessMaps ),
+			emissiveMap: this.processTexture( textures.emissiveMap, this.emissiveMaps ),
+			displacementMap: this.processTexture( textures.displacementMap, this.displacementMaps ),
+			anisotropyMap: this.processTexture( textures.anisotropyMap, this.anisotropyMaps ),
 
 			// Advanced texture maps (MeshPhysicalMaterial only). Folded into their scalar factors
 			// in ShadeKernel (applyExtensionMaps). thicknessMap stays dropped — thickness has no
 			// render effect yet (see gap-plan Phase 4.4).
-			clearcoatMap: this.processTexture( material.clearcoatMap, this.clearcoatMaps ),
-			clearcoatRoughnessMap: this.processTexture( material.clearcoatRoughnessMap, this.clearcoatRoughnessMaps ),
-			transmissionMap: this.processTexture( material.transmissionMap, this.transmissionMaps ),
+			clearcoatMap: this.processTexture( textures.clearcoatMap, this.clearcoatMaps ),
+			clearcoatRoughnessMap: this.processTexture( textures.clearcoatRoughnessMap, this.clearcoatRoughnessMaps ),
+			transmissionMap: this.processTexture( textures.transmissionMap, this.transmissionMaps ),
 			thicknessMap: this.processTexture( material.thicknessMap, [] ),
-			sheenColorMap: this.processTexture( material.sheenColorMap, this.sheenColorMaps ),
-			sheenRoughnessMap: this.processTexture( material.sheenRoughnessMap, this.sheenRoughnessMaps ),
-			specularIntensityMap: this.processTexture( material.specularIntensityMap, this.specularIntensityMaps ),
-			specularColorMap: this.processTexture( material.specularColorMap, this.specularColorMaps ),
-			iridescenceMap: this.processTexture( material.iridescenceMap, this.iridescenceMaps ),
-			iridescenceThicknessMap: this.processTexture( material.iridescenceThicknessMap, this.iridescenceThicknessMaps ),
-
-			// Texture transformation matrices
-			mapMatrix: this.getTextureMatrix( material.map ),
-			normalMapMatrices: this.getTextureMatrix( material.normalMap ),
-			bumpMapMatrices: this.getTextureMatrix( material.bumpMap ),
-			roughnessMapMatrices: this.getTextureMatrix( material.roughnessMap ),
-			metalnessMapMatrices: this.getTextureMatrix( material.metalnessMap ),
-			emissiveMapMatrices: this.getTextureMatrix( material.emissiveMap ),
-			displacementMapMatrices: this.getTextureMatrix( material.displacementMap ),
-
-			// Material type for debugging/optimization
+			sheenColorMap: this.processTexture( textures.sheenColorMap, this.sheenColorMaps ),
+			sheenRoughnessMap: this.processTexture( textures.sheenRoughnessMap, this.sheenRoughnessMaps ),
+			specularIntensityMap: this.processTexture( textures.specularIntensityMap, this.specularIntensityMaps ),
+			specularColorMap: this.processTexture( textures.specularColorMap, this.specularColorMaps ),
+			iridescenceMap: this.processTexture( textures.iridescenceMap, this.iridescenceMaps ),
+			iridescenceThicknessMap: this.processTexture( textures.iridescenceThicknessMap, this.iridescenceThicknessMaps ),
+
+			mapMatrix: this.getTextureMatrix( textures.map ),
+			normalMapMatrices: this.getTextureMatrix( textures.normalMap ),
+			bumpMapMatrices: this.getTextureMatrix( textures.bumpMap ),
+			roughnessMapMatrices: this.getTextureMatrix( textures.roughnessMap ),
+			metalnessMapMatrices: this.getTextureMatrix( textures.metalnessMap ),
+			emissiveMapMatrices: this.getTextureMatrix( textures.emissiveMap ),
+			displacementMapMatrices: this.getTextureMatrix( textures.displacementMap ),
+
+			sources,
 			originalType: materialType
 		};
 

package/src/Processor/LightSerializer.js

@@ -1,5 +1,6 @@
 import { Vector3, Quaternion } from 'three';
 import { blackbodyToLinearRGB } from './blackbody.js';
+import { convertLinearTriple } from '../Color/WorkingMatrix.js';
 
 // Point & spot lights specify Power in Watts; the shader uses radiant intensity
 // (W/sr) as `intensity / dist²`, so convert with I = P / 4π (isotropic emitter),
@@ -15,15 +16,19 @@ function effectiveEmission( light ) {
 	const exposure = Number.isFinite( ud.exposure ) ? ud.exposure : 0;
 	const intensity = light.intensity * Math.pow( 2, exposure );
 
-	let r = light.color.r, g = light.color.g, b = light.color.b;
+	const rgb = [ light.color.r, light.color.g, light.color.b ];
 	if ( ud.useTemperature ) {
 
 		const [ tr, tg, tb ] = blackbodyToLinearRGB( ud.temperature ?? 6500 );
-		r *= tr; g *= tg; b *= tb;
+		rgb[ 0 ] *= tr; rgb[ 1 ] *= tg; rgb[ 2 ] *= tb;
 
 	}
 
-	return { r, g, b, intensity };
+	// A light colour is authored against sRGB primaries, like everything else three.js hands over.
+	// Rendering in a wider working space without converting it tints every surface it touches.
+	convertLinearTriple( rgb );
+
+	return { r: rgb[ 0 ], g: rgb[ 1 ], b: rgb[ 2 ], intensity };
 
 }
 

package/src/Processor/MaterialPacking.js

@@ -0,0 +1,168 @@
+import { MATERIAL_DATA_LAYOUT as M, MATERIAL_DEFAULTS as D, normalizeAttenuationDistance } from '../EngineDefaults.js';
+
+// The first 8 Matrix3 elements; the GPU rebuilds the 9th (always 1).
+const IDENTITY_UV = [ 1, 0, 0, 0, 1, 0, 0, 0 ];
+
+const TRANSFORMS = [
+	[ 'mapMatrix', M.ALBEDO_TRANSFORM ],
+	[ 'normalMapMatrices', M.NORMAL_TRANSFORM ],
+	[ 'roughnessMapMatrices', M.ROUGHNESS_TRANSFORM ],
+	[ 'metalnessMapMatrices', M.METALNESS_TRANSFORM ],
+	[ 'emissiveMapMatrices', M.EMISSIVE_TRANSFORM ],
+	[ 'bumpMapMatrices', M.BUMP_TRANSFORM ],
+	[ 'displacementMapMatrices', M.DISPLACEMENT_TRANSFORM ],
+];
+
+/** Floats no field writes; the packer gives them fixed values. */
+export const MATERIAL_RESERVED_FLOATS = Object.freeze( [
+	M.VISIBLE, M.SHEEN_COLOR + 3, M.DISPLACEMENT_MAP_INDEX + 1,
+	M.SPECULAR_COLOR_MAP_INDEX + 1, M.SPECULAR_COLOR_MAP_INDEX + 2, M.SPECULAR_COLOR_MAP_INDEX + 3,
+] );
+
+/**
+ * Weights and roughnesses, [0, 1] in glTF and three.js. Past 1 an energy split like
+ * 1 − clearcoat·E goes negative: a glTF chrome with clearcoatFactor 4 added negative light.
+ */
+export const UNIT_RANGE_PROPERTIES = Object.freeze( new Set( [
+	'metalness', 'roughness', 'transmission', 'opacity', 'clearcoat', 'clearcoatRoughness',
+	'sheen', 'sheenRoughness', 'specularIntensity', 'iridescence', 'subsurface', 'anisotropy',
+] ) );
+
+export const clampUnit = ( value ) => Math.min( Math.max( value, 0 ), 1 );
+
+function num( value, fallback ) {
+
+	const n = typeof value === 'boolean' ? + value : value;
+	return Number.isFinite( n ) ? n : fallback;
+
+}
+
+function mapIndex( value ) {
+
+	return Number.isInteger( value ) ? value : - 1;
+
+}
+
+function writeTriple( data, at, value, fallback ) {
+
+	const r = value?.r ?? value?.[ 0 ] ?? value?.x;
+	const g = value?.g ?? value?.[ 1 ] ?? value?.y;
+	const b = value?.b ?? value?.[ 2 ] ?? value?.z;
+	data[ at ] = num( r, fallback[ 0 ] );
+	data[ at + 1 ] = num( g, fallback[ 1 ] );
+	data[ at + 2 ] = num( b, fallback[ 2 ] );
+
+}
+
+/**
+ * The one writer of a material block, for the scene upload and runtime edits alike. A missing or
+ * non-finite field gets MATERIAL_DEFAULTS.
+ * @param {Float32Array} data
+ * @param {number} base - float offset of the material's block
+ * @param {Object} mat - a GeometryExtractor.createMaterialObject() result, or any subset of it
+ */
+export function packMaterial( data, base, mat ) {
+
+	const s = ( offset, value, fallback ) => {
+
+		data[ base + offset ] = num( value, fallback );
+
+	};
+
+	const u = ( offset, value, fallback ) => {
+
+		data[ base + offset ] = clampUnit( num( value, fallback ) );
+
+	};
+
+	s( M.IOR, mat.ior, D.ior );
+	u( M.TRANSMISSION, mat.transmission, D.transmission );
+	s( M.THICKNESS, mat.thickness, D.thickness );
+	s( M.EMISSIVE_INTENSITY, mat.emissiveIntensity, D.emissiveIntensity );
+
+	writeTriple( data, base + M.ATTENUATION_COLOR, mat.attenuationColor, D.attenuationColor );
+	data[ base + M.ATTENUATION_DISTANCE ] = normalizeAttenuationDistance( mat.attenuationDistance ?? D.attenuationDistance );
+
+	u( M.OPACITY, mat.opacity, D.opacity );
+	s( M.SIDE, mat.side, D.side );
+	s( M.TRANSPARENT, mat.transparent, D.transparent );
+	s( M.ALPHA_TEST, mat.alphaTest, D.alphaTest );
+
+	s( M.ALPHA_MODE, mat.alphaMode, D.alphaMode );
+	s( M.DEPTH_WRITE, mat.depthWrite, D.depthWrite );
+	const normalScale = mat.normalScale;
+	const uniformScale = typeof normalScale === 'number' ? normalScale : undefined;
+	s( M.NORMAL_SCALE, uniformScale ?? normalScale?.x ?? normalScale?.[ 0 ], D.normalScale[ 0 ] );
+	s( M.NORMAL_SCALE + 1, uniformScale ?? normalScale?.y ?? normalScale?.[ 1 ], D.normalScale[ 1 ] );
+
+	writeTriple( data, base + M.COLOR, mat.color, D.color );
+	u( M.METALNESS, mat.metalness, D.metalness );
+
+	writeTriple( data, base + M.EMISSIVE, mat.emissive, D.emissive );
+	u( M.ROUGHNESS, mat.roughness, D.roughness );
+
+	data[ base + M.ALBEDO_MAP_INDEX ] = mapIndex( mat.map );
+	data[ base + M.NORMAL_MAP_INDEX ] = mapIndex( mat.normalMap );
+	data[ base + M.ROUGHNESS_MAP_INDEX ] = mapIndex( mat.roughnessMap );
+	data[ base + M.METALNESS_MAP_INDEX ] = mapIndex( mat.metalnessMap );
+
+	data[ base + M.EMISSIVE_MAP_INDEX ] = mapIndex( mat.emissiveMap );
+	data[ base + M.BUMP_MAP_INDEX ] = mapIndex( mat.bumpMap );
+	u( M.CLEARCOAT, mat.clearcoat, D.clearcoat );
+	u( M.CLEARCOAT_ROUGHNESS, mat.clearcoatRoughness, D.clearcoatRoughness );
+
+	s( M.DISPERSION, mat.dispersion, D.dispersion );
+	u( M.SHEEN, mat.sheen, D.sheen );
+	u( M.SHEEN_ROUGHNESS, mat.sheenRoughness, D.sheenRoughness );
+
+	writeTriple( data, base + M.SHEEN_COLOR, mat.sheenColor, D.sheenColor );
+
+	u( M.SPECULAR_INTENSITY, mat.specularIntensity, D.specularIntensity );
+	writeTriple( data, base + M.SPECULAR_COLOR, mat.specularColor, D.specularColor );
+
+	u( M.IRIDESCENCE, mat.iridescence, D.iridescence );
+	s( M.IRIDESCENCE_IOR, mat.iridescenceIOR, D.iridescenceIOR );
+	s( M.IRIDESCENCE_THICKNESS_RANGE, mat.iridescenceThicknessRange?.[ 0 ], D.iridescenceThicknessRange[ 0 ] );
+	s( M.IRIDESCENCE_THICKNESS_RANGE + 1, mat.iridescenceThicknessRange?.[ 1 ], D.iridescenceThicknessRange[ 1 ] );
+
+	s( M.BUMP_SCALE, mat.bumpScale, D.bumpScale );
+	s( M.DISPLACEMENT_SCALE, mat.displacementScale, D.displacementScale );
+	data[ base + M.DISPLACEMENT_MAP_INDEX ] = mapIndex( mat.displacementMap );
+
+	for ( const [ key, offset ] of TRANSFORMS ) {
+
+		const matrix = mat[ key ];
+		for ( let i = 0; i < 8; i ++ ) data[ base + offset + i ] = num( matrix?.[ i ], IDENTITY_UV[ i ] );
+
+	}
+
+	writeTriple( data, base + M.SUBSURFACE_COLOR, mat.subsurfaceColor, D.subsurfaceColor );
+	u( M.SUBSURFACE, mat.subsurface, D.subsurface );
+	writeTriple( data, base + M.SUBSURFACE_RADIUS, mat.subsurfaceRadius, D.subsurfaceRadius );
+	s( M.SUBSURFACE_RADIUS_SCALE, mat.subsurfaceRadiusScale, D.subsurfaceRadiusScale );
+
+	s( M.SUBSURFACE_ANISOTROPY, mat.subsurfaceAnisotropy, D.subsurfaceAnisotropy );
+	u( M.ANISOTROPY, mat.anisotropy, D.anisotropy );
+	s( M.ANISOTROPY_ROTATION, mat.anisotropyRotation, D.anisotropyRotation );
+	data[ base + M.ANISOTROPY_MAP_INDEX ] = mapIndex( mat.anisotropyMap );
+
+	data[ base + M.TRANSMISSION_MAP_INDEX ] = mapIndex( mat.transmissionMap );
+	data[ base + M.CLEARCOAT_MAP_INDEX ] = mapIndex( mat.clearcoatMap );
+	data[ base + M.CLEARCOAT_ROUGHNESS_MAP_INDEX ] = mapIndex( mat.clearcoatRoughnessMap );
+	data[ base + M.SHEEN_COLOR_MAP_INDEX ] = mapIndex( mat.sheenColorMap );
+
+	data[ base + M.SHEEN_ROUGHNESS_MAP_INDEX ] = mapIndex( mat.sheenRoughnessMap );
+	data[ base + M.IRIDESCENCE_MAP_INDEX ] = mapIndex( mat.iridescenceMap );
+	data[ base + M.IRIDESCENCE_THICKNESS_MAP_INDEX ] = mapIndex( mat.iridescenceThicknessMap );
+	data[ base + M.SPECULAR_INTENSITY_MAP_INDEX ] = mapIndex( mat.specularIntensityMap );
+
+	data[ base + M.SPECULAR_COLOR_MAP_INDEX ] = mapIndex( mat.specularColorMap );
+
+	data[ base + M.VISIBLE ] = 1;
+	data[ base + M.SHEEN_COLOR + 3 ] = 1;
+	data[ base + M.DISPLACEMENT_MAP_INDEX + 1 ] = 0;
+	data[ base + M.SPECULAR_COLOR_MAP_INDEX + 1 ] = 0;
+	data[ base + M.SPECULAR_COLOR_MAP_INDEX + 2 ] = 0;
+	data[ base + M.SPECULAR_COLOR_MAP_INDEX + 3 ] = 0;
+
+}

package/src/Processor/PackedRayBuffer.js

@@ -281,12 +281,16 @@ export const readHitMaterialIndex = ( buf, id ) =>
 export const readHitInstanceLeaf = ( buf, id ) =>
 	int( buf.element( soa( id, HIT.NORMAL_MAT ) ).z ).sub( int( 1 ) );
 
-export const writeHitPacked = ( buf, id, distance, triIndex, baryU, baryV, normal, matIndex, instanceLeaf ) => {
+/** Facet normal and terminator lift, packed by HitFacet.packHitFacet. */
+export const readHitFacet = ( buf, id ) =>
+	buf.element( soa( id, HIT.NORMAL_MAT ) ).w;
+
+export const writeHitPacked = ( buf, id, distance, triIndex, baryU, baryV, normal, matIndex, instanceLeaf, facet = uint( 0 ) ) => {
 
 	buf.element( soa( id, HIT.DIST_TRI_BARY ) )
 		.assign( uvec4( floatBitsToUint( distance ), triIndex, floatBitsToUint( baryU ), floatBitsToUint( baryV ) ) );
 	buf.element( soa( id, HIT.NORMAL_MAT ) )
-		.assign( uvec4( packNormalOct( normal ), matIndex, instanceLeaf, uint( 0 ) ) );
+		.assign( uvec4( packNormalOct( normal ), matIndex, instanceLeaf, facet ) );
 
 };
 

package/src/Processor/ProceduralSky.js

@@ -248,6 +248,10 @@ export class ProceduralSky {
 		}
 
 		this._texture.needsUpdate = true;
+		// Fresh linear Rec.709 pixels in a reused texture. Colour management records which space a
+		// texture's pixels hold so it never converts them twice; left in place, that record would
+		// claim these were already converted and they never would be.
+		delete this._texture.userData?.__rayzeeColorSpace;
 		this.lastRenderTime = performance.now() - startTime;
 
 		return this._texture;

package/src/Processor/SceneProcessor.js

@@ -2163,7 +2163,7 @@ export class SceneProcessor {
 
 		if ( this.materialData ) {
 
-			pathTracer.materialData.setMaterialData( this.materialData );
+			pathTracer.materialData.setMaterialData( this.materialData, this.materials.map( m => m.sources ) );
 
 		} else {
 
@@ -2240,6 +2240,30 @@ export class SceneProcessor {
 
 	}
 
+	/**
+	 * Re-read every emitter's colour, after the working space changed.
+	 *
+	 * `rebuildMaterials` re-packs the material buffer but leaves this list alone, and next-event
+	 * estimation lights the scene from this list — so without a rebuild, emitters would be seen in
+	 * the new space and cast light in the old one.
+	 *
+	 * @returns {object|null} GPU upload payload
+	 */
+	rebuildEmissiveColors() {
+
+		if ( ! this.emissiveTriangleBuilder || ! this.triangleCount ) return null;
+
+		this.emissiveTriangleBuilder.extractEmissiveTriangles(
+			this.triangles,
+			this.materials,
+			this.triangleCount,
+			this.instanceTable ?? null
+		);
+		this.emissiveTriangleBuilder.createEmissiveRawData();
+		return this._collectEmissivePayload();
+
+	}
+
 	/**
 	 * Re-derive the sampled emissive set from per-mesh visibility.
 	 * @param {Set<number>|Iterable<number>} hiddenMeshIndices - meshIndex values that are world-hidden

package/src/Processor/SimpleSky.js

@@ -87,6 +87,10 @@ export class SimpleSky {
 		}
 
 		this._texture.needsUpdate = true;
+		// Fresh linear Rec.709 pixels in a reused texture. Colour management records which space a
+		// texture's pixels hold so it never converts them twice; left in place, that record would
+		// claim these were already converted and they never would be.
+		delete this._texture.userData?.__rayzeeColorSpace;
 		this.lastRenderTime = performance.now() - startTime;
 		return this._texture;
 
@@ -120,6 +124,10 @@ export class SimpleSky {
 		}
 
 		this._texture.needsUpdate = true;
+		// Fresh linear Rec.709 pixels in a reused texture. Colour management records which space a
+		// texture's pixels hold so it never converts them twice; left in place, that record would
+		// claim these were already converted and they never would be.
+		delete this._texture.userData?.__rayzeeColorSpace;
 		this.lastRenderTime = performance.now() - startTime;
 		return this._texture;