rayzee 7.29.0 → 7.30.1

package/package.json

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

package/src/EngineDefaults.js

@@ -224,6 +224,10 @@ export const ENGINE_DEFAULTS = {
 	asvgfQualityPreset: 'medium',
 	showAsvgfHeatmap: false,
 
+	// NRD (ReBLUR port) real-time denoiser — see NRD_DEFAULTS / NRD_QUALITY_PRESETS.
+	nrdQualityPreset: 'medium',
+	nrdDebugMode: 0,
+
 	// Auto-exposure settings
 	autoExposure: false,
 	autoExposureKeyValue: 0.18,
@@ -233,6 +237,16 @@ export const ENGINE_DEFAULTS = {
 	autoExposureAdaptSpeedDark: 0.5,
 };
 
+// Ray distance NormalDepth writes on a miss. Max finite half-float, so miss−miss diffs stay 0
+// rather than Inf−Inf=NaN.
+export const GBUFFER_MISS_DEPTH = 65504.0;
+export const GBUFFER_MISS_THRESHOLD = 6e4;
+
+// normHitDist = hitDist / (A + B·viewZ). A constant, not a uniform: the Shade write and the NRD
+// decode must agree, and the normalization is a pure round trip.
+export const NRD_HIT_DIST_A = 3.0;
+export const NRD_HIT_DIST_B = 0.1;
+
 // Albedo demodulation safety floor. ASVGF and BilateralFilter MUST use the
 // same value — demod (`color / safeAlbedo`) and remod (`lighting * safeAlbedo`)
 // only round-trip exactly when both sides agree.
@@ -307,6 +321,67 @@ export const ASVGF_QUALITY_PRESETS = {
 	}
 };
 
+// NRD ReBLUR port (Stages/NRD.js). Names follow nrd::ReblurSettings so NVIDIA's tuning notes apply.
+export const NRD_DEFAULTS = {
+	maxAccumulatedFrameNum: 30,
+	maxFastAccumulatedFrameNum: 6,
+	maxStabilizedFrameNum: 63,
+	historyFixFrameNum: 3,
+	historyFixBasePixelStride: 14,
+	prepassBlurRadius: 30,
+	minBlurRadius: 1,
+	maxBlurRadius: 30,
+	lobeAngleFraction: 0.15,
+	roughnessFraction: 0.15,
+	planeDistanceSensitivity: 0.02,
+	minHitDistanceWeight: 0.1,
+	fastHistoryClampingSigmaScale: 2.0,
+	fireflySuppressorMinRelativeScale: 2.0,
+	enableAntiFirefly: true,
+	antilagLuminanceSigmaScale: 2.0,
+	antilagLuminanceSensitivity: 3.0,
+	disocclusionThreshold: 0.01,
+	convergenceS: 1.0,
+	convergenceB: 0.2,
+	convergenceP: 0.8,
+	// Share of the lobe the normal weight accepts before any history exists. NRD's own constant is
+	// 0.75, which its source flags as probably too much; at that width it smears curved surfaces.
+	lobeVolumePercent: 0.1,
+	// Progressive handover: input sample count at which the denoiser passes the render through untouched.
+	// 0 = 2 · maxAccumulatedFrameNum.
+	handoverFrames: 0,
+};
+
+// Keys a preset may override. Applying one resets every key to its default first, so a preset only
+// states its deltas and `medium` can be empty.
+export const NRD_PRESET_KEYS = [
+	'maxAccumulatedFrameNum', 'maxFastAccumulatedFrameNum', 'maxStabilizedFrameNum',
+	'historyFixFrameNum', 'prepassBlurRadius', 'maxBlurRadius', 'enableAntiFirefly',
+];
+
+export const NRD_QUALITY_PRESETS = {
+	// Short history + no pre-pass: most responsive, noisiest.
+	low: {
+		maxAccumulatedFrameNum: 16,
+		maxFastAccumulatedFrameNum: 4,
+		maxStabilizedFrameNum: 16,
+		historyFixFrameNum: 2,
+		prepassBlurRadius: 0,
+		maxBlurRadius: 20,
+		enableAntiFirefly: false,
+	},
+	// nrd::ReblurSettings defaults.
+	medium: {},
+	// Longer history and wider kernels: smoother, more lag on lighting change.
+	high: {
+		maxAccumulatedFrameNum: 45,
+		maxFastAccumulatedFrameNum: 8,
+		historyFixFrameNum: 4,
+		prepassBlurRadius: 40,
+		maxBlurRadius: 40,
+	},
+};
+
 export const CAMERA_RANGES = {
 	fov: {
 		min: 10,
@@ -591,11 +666,11 @@ export const TEXTURE_CONSTANTS = {
 	MAX_TEXTURE_SIZE: 8192,
 	// Default cap applied when no maxTextureSize is supplied (engine standalone use).
 	DEFAULT_MAX_TEXTURE_SIZE: 4096,
-	// Max layers (textures) per bucket array. Also the packing stride for (bucket, layer).
-	MAX_TEXTURES_LIMIT: 128,
-	// Size buckets per colorSpace pool. Material maps are grouped into this many
-	// longest-edge size classes so a small map no longer pays a large neighbour's
-	// footprint. 4 → ~8 bound material arrays (4 sRGB + 4 linear).
+	// Per-map-type ceiling before bucketing; the real cap is per (pool, bucket) in _bucketTextures.
+	MAX_TEXTURES_LIMIT: 4 * 256,
+	// Array shapes per colorSpace pool. Material maps are grouped into this many
+	// (width, height) classes so a small or oddly-shaped map no longer pays a large
+	// neighbour's footprint. 4 → ~8 bound material arrays (4 sRGB + 4 linear).
 	MATERIAL_BUCKET_COUNT: 4,
 	// Packing stride: a map's stored index encodes bucketId * BUCKET_LAYER_STRIDE + layer.
 	// Also the per-bucket layer cap. Kept at the WebGPU portable maxTextureArrayLayers floor (256)
@@ -603,30 +678,208 @@ export const TEXTURE_CONSTANTS = {
 	BUCKET_LAYER_STRIDE: 256,
 };
 
-// Longest-edge size ladder for a given cap, ascending.
-// cap=4096, count=4 → [512, 1024, 2048, 4096].
-export function getTextureBucketSizes( maxTextureSize, count = TEXTURE_CONSTANTS.MATERIAL_BUCKET_COUNT ) {
+// An RGBA8 row upload must be a multiple of 256 bytes, so bucket widths land on 64 texels.
+const BUCKET_WIDTH_ALIGN = 64;
+
+export function alignBucketWidth( width, maxTextureSize ) {
+
+	const aligned = Math.ceil( Math.max( 1, width ) / BUCKET_WIDTH_ALIGN ) * BUCKET_WIDTH_ALIGN;
+	return Math.min( maxTextureSize, Math.max( TEXTURE_CONSTANTS.MIN_TEXTURE_WIDTH, aligned ) );
+
+}
+
+function bucketOf( units ) {
+
+	let width = 0, height = 0, count = 0;
+	for ( const unit of units ) {
+
+		width = Math.max( width, unit.width );
+		height = Math.max( height, unit.height );
+		count += unit.count;
+
+	}
+
+	return { units, width, height, count };
+
+}
+
+// Footprint times layer count.
+function bucketCost( bucket, maxTextureSize ) {
+
+	return alignBucketWidth( bucket.width, maxTextureSize ) * bucket.height * bucket.count * 4;
+
+}
+
+function totalCost( buckets, maxTextureSize ) {
+
+	return buckets.reduce( ( sum, b ) => sum + bucketCost( b, maxTextureSize ), 0 );
+
+}
+
+// Repeatedly fuse the pair of buckets whose union wastes least, until `count` remain.
+function mergeDown( buckets, count, maxTextureSize ) {
+
+	let current = buckets.slice();
+
+	while ( current.length > count ) {
+
+		let best = null;
+
+		for ( let i = 0; i < current.length; i ++ ) {
+
+			for ( let j = i + 1; j < current.length; j ++ ) {
+
+				const fused = bucketOf( current[ i ].units.concat( current[ j ].units ) );
+				const delta = bucketCost( fused, maxTextureSize )
+					- bucketCost( current[ i ], maxTextureSize ) - bucketCost( current[ j ], maxTextureSize );
+				if ( ! best || delta < best.delta ) best = { i, j, delta, fused };
+
+			}
+
+		}
+
+		current = current.filter( ( _, k ) => k !== best.i && k !== best.j ).concat( [ best.fused ] );
+
+	}
+
+	return current;
+
+}
+
+// The pre-shape-aware layout, kept as a rival opening: square scenes still do well on it.
+function ladderBuckets( units, count, maxTextureSize ) {
 
-	const sizes = [];
+	const ladder = [];
 	for ( let i = count - 1; i >= 0; i -- ) {
 
-		sizes.push( Math.max( TEXTURE_CONSTANTS.MIN_TEXTURE_WIDTH, Math.round( maxTextureSize / Math.pow( 2, i ) ) ) );
+		ladder.push( Math.max( TEXTURE_CONSTANTS.MIN_TEXTURE_WIDTH, Math.round( maxTextureSize / Math.pow( 2, i ) ) ) );
 
 	}
 
-	return sizes;
+	const bins = ladder.map( () => [] );
+
+	for ( const unit of units ) {
+
+		const longest = Math.pow( 2, Math.ceil( Math.log2( Math.max( unit.width, unit.height ) ) ) );
+		let slot = ladder.findIndex( size => longest <= size );
+		if ( slot < 0 ) slot = ladder.length - 1;
+		bins[ slot ].push( unit );
+
+	}
+
+	return bins.filter( bin => bin.length ).map( bucketOf );
 
 }
 
-// Bucket index for a texture, by its power-of-2 longest edge vs the cap's ladder.
-// Larger-than-cap maps land in the top bucket (downscaled to cap, as before).
-export function getTextureBucketId( width, height, maxTextureSize, count = TEXTURE_CONSTANTS.MATERIAL_BUCKET_COUNT ) {
+// Both openings above are greedy and stop short on mixed aspects; moving one shape at a time
+// to whichever bucket makes the pool cheapest recovers the difference.
+function refine( buckets, maxTextureSize ) {
+
+	let current = buckets;
+
+	for ( let pass = 0; pass < 8; pass ++ ) {
+
+		let improved = false;
+
+		for ( const unit of current.flatMap( b => b.units ) ) {
+
+			const from = current.findIndex( b => b.units.includes( unit ) );
+			if ( from < 0 ) continue;
+
+			for ( let to = 0; to < current.length; to ++ ) {
+
+				if ( to === from ) continue;
+
+				const moved = [];
+				for ( let i = 0; i < current.length; i ++ ) {
+
+					if ( i === from ) {
+
+						const rest = current[ i ].units.filter( u => u !== unit );
+						if ( rest.length ) moved.push( bucketOf( rest ) );
+
+					} else if ( i === to ) moved.push( bucketOf( current[ i ].units.concat( [ unit ] ) ) );
+					else moved.push( current[ i ] );
+
+				}
+
+				if ( totalCost( moved, maxTextureSize ) < totalCost( current, maxTextureSize ) ) {
+
+					current = moved;
+					improved = true;
+					break;
+
+				}
+
+			}
+
+		}
+
+		if ( ! improved ) break;
+
+	}
+
+	return current;
+
+}
+
+/**
+ * Choose up to `count` array shapes for one colorSpace pool. Grouping by longest edge alone
+ * forces a 2000x453 banner into a 2048x2048 array; grouping on both axes does not.
+ *
+ * @param {Array<{width: number, height: number}>} sizes - every texture in the pool
+ * @param {number} maxTextureSize
+ * @param {number} [count]
+ * @returns {Array<{width: number, height: number}>} ascending by footprint
+ */
+export function planTextureBuckets( sizes, maxTextureSize, count = TEXTURE_CONSTANTS.MATERIAL_BUCKET_COUNT ) {
+
+	const distinct = new Map();
+
+	for ( const { width, height } of sizes ) {
+
+		const w = Math.min( maxTextureSize, Math.max( 1, width || 1 ) );
+		const h = Math.min( maxTextureSize, Math.max( 1, height || 1 ) );
+		const key = `${w}x${h}`;
+		const seen = distinct.get( key );
+		if ( seen ) seen.count ++;
+		else distinct.set( key, { width: w, height: h, count: 1 } );
+
+	}
+
+	const units = [ ...distinct.values() ];
+	let buckets = units.map( unit => bucketOf( [ unit ] ) );
+
+	if ( buckets.length > count ) {
+
+		const ladder = ladderBuckets( units, count, maxTextureSize );
+		const merged = mergeDown( buckets, count, maxTextureSize );
+		buckets = totalCost( ladder, maxTextureSize ) < totalCost( merged, maxTextureSize ) ? ladder : merged;
+		buckets = refine( buckets, maxTextureSize );
+
+	}
+
+	return buckets
+		.map( b => ( { width: alignBucketWidth( b.width, maxTextureSize ), height: b.height } ) )
+		.sort( ( a, b ) => a.width * a.height - b.width * b.height );
+
+}
+
+/**
+ * Index of the cheapest planned bucket that can hold a texture at its native size.
+ * A texture larger than every bucket lands in the largest and is downscaled there.
+ *
+ * @param {number} width
+ * @param {number} height
+ * @param {Array<{width: number, height: number}>} shapes - from {@link planTextureBuckets}
+ * @returns {number}
+ */
+export function getTextureBucketId( width, height, shapes ) {
 
-	const longest = Math.max( width || 1, height || 1 );
-	const pot = Math.pow( 2, Math.ceil( Math.log2( longest ) ) );
-	const sizes = getTextureBucketSizes( maxTextureSize, count );
-	for ( let i = 0; i < sizes.length; i ++ ) if ( pot <= sizes[ i ] ) return i;
-	return sizes.length - 1;
+	const w = Math.max( 1, width || 1 );
+	const h = Math.max( 1, height || 1 );
+	for ( let i = 0; i < shapes.length; i ++ ) if ( shapes[ i ].width >= w && shapes[ i ].height >= h ) return i;
+	return Math.max( 0, shapes.length - 1 );
 
 }
 

package/src/EngineIssues.js

@@ -9,6 +9,7 @@ export const ISSUE_CODES = Object.freeze( {
 	ASSET_UNREACHABLE: 'asset.unreachable',
 	TEXTURE_BUILD_FAILED: 'texture.build_failed',
 	TEXTURE_PROCESSING_FALLBACK: 'texture.processing_fallback',
+	TEXTURE_LIMIT_EXCEEDED: 'texture.limit_exceeded',
 	ENVIRONMENT_LOAD_FAILED: 'environment.load_failed',
 	SETTING_UNKNOWN_KEY: 'setting.unknown_key',
 	RENDER_SIZE_DECLINED: 'render.size_declined',

package/src/PathTracerApp.js

@@ -9,6 +9,7 @@ import { PathTracer } from './Stages/PathTracer.js';
 import { NormalDepth } from './Stages/NormalDepth.js';
 import { MotionVector } from './Stages/MotionVector.js';
 import { ASVGF } from './Stages/ASVGF.js';
+import { NRD } from './Stages/NRD.js';
 import { Variance } from './Stages/Variance.js';
 import { BilateralFilter } from './Stages/BilateralFilter.js';
 import { EdgeFilter } from './Stages/EdgeFilter.js';
@@ -524,7 +525,12 @@ export class PathTracerApp extends EventDispatcher {
 		if ( this.pipeline ) {
 
 			this.pipeline.reset();
-			if ( ! soft ) this.pipeline.eventBus.emit( 'asvgf:reset' );
+			if ( ! soft ) {
+
+				this.pipeline.eventBus.emit( 'asvgf:reset' );
+				this.pipeline.eventBus.emit( 'denoiser:reset' );
+
+			}
 
 		}
 
@@ -2857,6 +2863,7 @@ export class PathTracerApp extends EventDispatcher {
 		this.pipeline.addStage( this.stages.pathTracer );
 		this.pipeline.addStage( this.stages.normalDepth );
 		this.pipeline.addStage( this.stages.motionVector );
+		this.pipeline.addStage( this.stages.nrd );
 		this.pipeline.addStage( this.stages.asvgf );
 		this.pipeline.addStage( this.stages.variance );
 		this.pipeline.addStage( this.stages.bilateralFilter );
@@ -3090,6 +3097,7 @@ export class PathTracerApp extends EventDispatcher {
 			pathTracer: this.stages.pathTracer
 		} );
 		this.stages.asvgf = new ASVGF( this.renderer, { enabled: false } );
+		this.stages.nrd = new NRD( this.renderer, { enabled: false, pathTracer: this.stages.pathTracer } );
 		this.stages.variance = new Variance( this.renderer, { enabled: false } );
 		this.stages.bilateralFilter = new BilateralFilter( this.renderer, { enabled: false } );
 		this.stages.edgeFilter = new EdgeFilter( this.renderer, { enabled: false } );
@@ -3114,6 +3122,7 @@ export class PathTracerApp extends EventDispatcher {
 				normalDepth: this.stages.normalDepth,
 				motionVector: this.stages.motionVector,
 				asvgf: this.stages.asvgf,
+				nrd: this.stages.nrd,
 				variance: this.stages.variance,
 				bilateralFilter: this.stages.bilateralFilter,
 				edgeFilter: this.stages.edgeFilter,

package/src/Processor/GeometryExtractor.js

@@ -1,10 +1,11 @@
 import { Vector3, Vector2, Color, Matrix3, Matrix4, FrontSide, BackSide, DoubleSide, RGBAFormat } from "three";
-import { TRIANGLE_DATA_LAYOUT } from '../EngineDefaults.js';
+import { TEXTURE_CONSTANTS, TRIANGLE_DATA_LAYOUT } from '../EngineDefaults.js';
+import { ISSUE_CODES } from '../EngineIssues.js';
 import { createLogger, fmt, warnOnce } from '../utils/Logger.js';
 
 const log = createLogger( 'geometry' );
 
-const MAX_TEXTURES_LIMIT = 128;
+const MAX_TEXTURES_LIMIT = TEXTURE_CONSTANTS.MAX_TEXTURES_LIMIT;
 
 /**
  * glTF 2.0 alphaMode for a three.js material: 0 OPAQUE, 1 MASK, 2 BLEND.
@@ -55,7 +56,11 @@ export function deriveAlphaMode( material ) {
 
 export class GeometryExtractor {
 
-	constructor() {
+	/** @param {{issues?: import('../EngineIssues.js').IssueLog}} [options] */
+	constructor( { issues = null } = {} ) {
+
+		this._issues = issues;
+		this._droppedTextures = 0;
 
 		// Object pools for reusing objects
 		this._vectorPool = {
@@ -528,6 +533,17 @@ export class GeometryExtractor {
 
 		}
 
+		this._droppedTextures ++;
+		if ( this._droppedTextures === 1 ) {
+
+			this._issues?.record(
+				ISSUE_CODES.TEXTURE_LIMIT_EXCEEDED,
+				`scene needs more than ${MAX_TEXTURES_LIMIT} distinct textures for one map type; the rest render untextured`,
+				{ limit: MAX_TEXTURES_LIMIT, firstDropped: texture.name || texture.source?.uuid }
+			);
+
+		}
+
 		return - 1;
 
 	}
@@ -800,6 +816,8 @@ export class GeometryExtractor {
 
 	resetArrays() {
 
+		this._droppedTextures = 0;
+
 		// Reset triangle data
 		this.triangleData = null;
 		this.triangleCount = 0;

package/src/Processor/PackedRayBuffer.js

@@ -16,9 +16,10 @@ export const RAY_STRIDE = 7;
 export const HIT_STRIDE = 2;
 // Per-pixel G-buffer (first-hit MRT staging): 1 uvec4/pixel — half-packed normal/depth/albedo
 // (pack2x16, no f32 bitcast); read by FinalWrite:
-//   .x=packSnorm2x16(normal.xy)  .y=packSnorm2x16(normal.z, depth)  .z=packUnorm2x16(albedo.rg)  .w=packUnorm2x16(albedo.b, 0)
+//   .x=packSnorm2x16(normal.xy)  .y=packSnorm2x16(normal.z, depth)  .z=packUnorm2x16(albedo.rg)
+//   .w=packUnorm2x16(albedo.b, normHitDist)
+// normHitDist is written by Shade; writeGBuffer preserves it so the DDFA albedo commits can't zero it.
 // Separate buffer from RAY (per-pixel, not per-ray×S) — written by Generate/Shade bounce-0.
-// (A second lane reserved for an A-SVGF Tier-1 surface ID was removed — write-only, never read.)
 export const GBUFFER_STRIDE = 1;
 
 export const RAY = {
@@ -162,15 +163,35 @@ export const readRayRadiance = ( buf, id ) =>
 // One uvec4 per pixel (stride 1); AoS base = pixelIndex * GBUFFER_STRIDE.
 const gbLane = ( pixelIndex ) => uint( pixelIndex ).mul( GBUFFER_STRIDE );
 
-export const writeGBuffer = ( buf, pixelIndex, normal, depth, albedo ) =>
-	buf.element( gbLane( pixelIndex ) ).assign( uvec4(
+// hitDist = null keeps the lane's current normHitDist.
+export const writeGBuffer = ( buf, pixelIndex, normal, depth, albedo, hitDist = null ) => {
+
+	const lane = gbLane( pixelIndex );
+	const h = hitDist === null ? unpackUnorm2x16( buf.element( lane ).w ).y : float( hitDist );
+	return buf.element( lane ).assign( uvec4(
 		packSnorm2x16( vec2( normal.x, normal.y ) ),
 		packSnorm2x16( vec2( normal.z, depth ) ),
 		packUnorm2x16( vec2( albedo.x, albedo.y ) ),
-		packUnorm2x16( vec2( albedo.z, 0.0 ) ),
+		packUnorm2x16( vec2( albedo.z, h ) ),
+	) );
+
+};
+
+export const writeGBufferHitDist = ( buf, pixelIndex, normHitDist ) => {
+
+	const lane = gbLane( pixelIndex );
+	const cur = buf.element( lane ).toVar();
+	return buf.element( lane ).assign( uvec4(
+		cur.x, cur.y, cur.z,
+		packUnorm2x16( vec2( unpackUnorm2x16( cur.w ).x, normHitDist ) ),
 	) );
+
+};
+
 export const readGBuffer = ( buf, pixelIndex ) => buf.element( gbLane( pixelIndex ) );
 
+export const gbDecodeHitDist = ( packed ) => unpackUnorm2x16( packed.w ).y;
+
 // Decode for FinalWrite. normalDepth.xyz matches the prior path (normal*0.5+0.5), .w = raw depth.
 export const gbDecodeNormalDepth = ( packed ) => {
 

package/src/Processor/SceneProcessor.js

@@ -11,7 +11,8 @@ import { updateLoading } from '../Processor/utils.js';
 import { BuildTimer } from './BuildTimer.js';
 import { createLogger, fmt, workerLogLevel } from '../utils/Logger.js';
 import { SRGBColorSpace } from 'three';
-import { TRIANGLE_DATA_LAYOUT, TEXTURE_CONSTANTS, getTextureBucketId, packTextureIndex } from '../EngineDefaults.js';
+import { TRIANGLE_DATA_LAYOUT, TEXTURE_CONSTANTS, getTextureBucketId, packTextureIndex, planTextureBuckets } from '../EngineDefaults.js';
+import { ISSUE_CODES } from '../EngineIssues.js';
 import BVHWorker from './Workers/BVHWorker.js?worker&inline';
 import BVHRefitWorker from './Workers/BVHRefitWorker.js?worker&inline';
 
@@ -145,7 +146,7 @@ export class SceneProcessor {
 	_initProcessors() {
 
 		// Create and configure geometry extractor
-		this.geometryExtractor = new GeometryExtractor();
+		this.geometryExtractor = new GeometryExtractor( { issues: this.config.issues } );
 
 		// Create and configure BVH builder
 		this.bvhBuilder = new BVHBuilder();
@@ -869,8 +870,9 @@ export class SceneProcessor {
 	/**
 	 * Group the extractor's seven per-type texture arrays into two consolidated colorSpace
 	 * pools (sRGB: albedo+emissive; linear: normal/bump/roughness/metalness/displacement),
-	 * each split into MATERIAL_BUCKET_COUNT longest-edge size buckets. Textures are deduped
-	 * across types within a (pool, bucket) so a shared image (e.g. ORM) costs one layer.
+	 * each split into at most MATERIAL_BUCKET_COUNT buckets whose shapes are planned from the
+	 * pool's own texture dimensions. Textures are deduped across types within a (pool, bucket)
+	 * so a shared image (e.g. ORM) costs one layer.
 	 * @returns {{ srgbLists: Array<Array>, linearLists: Array<Array>, remap: Object }}
 	 *          bucket lists + per-type remap arrays (old per-type layer → packed bucket index).
 	 * @private
@@ -881,6 +883,43 @@ export class SceneProcessor {
 		const K = TEXTURE_CONSTANTS.MATERIAL_BUCKET_COUNT;
 		const STRIDE = TEXTURE_CONSTANTS.BUCKET_LAYER_STRIDE;
 
+		const poolSizes = ( types ) => {
+
+			const seen = new Set();
+			const sizes = [];
+
+			for ( const arr of types ) {
+
+				for ( const tex of arr || [] ) {
+
+					if ( ! tex?.image ) continue;
+					const uuid = tex.source?.uuid ?? tex.uuid;
+					if ( seen.has( uuid ) ) continue;
+					seen.add( uuid );
+					sizes.push( { width: tex.image.width, height: tex.image.height } );
+
+				}
+
+			}
+
+			return sizes;
+
+		};
+
+		const srgbTypes = [ this.maps, this.emissiveMaps, this.sheenColorMaps, this.specularColorMaps ];
+		const linearTypes = [
+			this.normalMaps, this.bumpMaps, this.roughnessMaps, this.metalnessMaps, this.displacementMaps,
+			this.anisotropyMaps, this.transmissionMaps, this.clearcoatMaps, this.clearcoatRoughnessMaps,
+			this.sheenRoughnessMaps, this.iridescenceMaps, this.iridescenceThicknessMaps, this.specularIntensityMaps,
+		];
+
+		const srgbShapes = planTextureBuckets( poolSizes( srgbTypes ), cap, K );
+		const linearShapes = planTextureBuckets( poolSizes( linearTypes ), cap, K );
+		this._srgbBucketShapes = srgbShapes;
+		this._linearBucketShapes = linearShapes;
+
+		// Always K-length even when the plan needs fewer shapes: downstream nodes are built
+		// per MATERIAL_BUCKET_COUNT and a short array would leave stale bindings behind.
 		const srgbLists = Array.from( { length: K }, () => [] );
 		const linearLists = Array.from( { length: K }, () => [] );
 		const srgbDedup = Array.from( { length: K }, () => new Map() );
@@ -891,17 +930,25 @@ export class SceneProcessor {
 		this._srgbTexPacked = new Map();
 		this._linearTexPacked = new Map();
 
+		let bucketOverflowReported = false;
+
 		// Assign one texture to its (bucket, layer) within a pool; dedup by source uuid.
-		const assign = ( tex, lists, dedup, flat ) => {
+		const assign = ( tex, lists, dedup, flat, shapes ) => {
 
 			if ( ! tex || ! tex.image ) return - 1;
-			const bucket = getTextureBucketId( tex.image.width, tex.image.height, cap, K );
+			const bucket = getTextureBucketId( tex.image.width, tex.image.height, shapes );
 			const uuid = tex.source?.uuid ?? tex.uuid;
 			const seen = dedup[ bucket ].get( uuid );
 			if ( seen !== undefined ) return packTextureIndex( bucket, seen );
 			if ( lists[ bucket ].length >= STRIDE ) {
 
 				log.warn( `texture bucket ${bucket} full (${STRIDE}); dropping a map` );
+				if ( ! bucketOverflowReported ) this.config.issues?.record(
+					ISSUE_CODES.TEXTURE_LIMIT_EXCEEDED,
+					`texture bucket ${bucket} full (${STRIDE} layers); the rest render untextured`,
+					{ bucket, limit: STRIDE }
+				);
+				bucketOverflowReported = true;
 				return - 1;
 
 			}
@@ -917,27 +964,27 @@ export class SceneProcessor {
 
 		// Per-type arrays hold unique textures indexed by the layer the extractor assigned
 		// (= array position), so remap[type][oldLayer] = packed index.
-		const remapType = ( arr, lists, dedup, flat ) => ( arr || [] ).map( tex => assign( tex, lists, dedup, flat ) );
+		const remapType = ( arr, lists, dedup, flat, shapes ) => ( arr || [] ).map( tex => assign( tex, lists, dedup, flat, shapes ) );
 
 		const remap = {
-			albedo: remapType( this.maps, srgbLists, srgbDedup, this._srgbTexPacked ),
-			emissive: remapType( this.emissiveMaps, srgbLists, srgbDedup, this._srgbTexPacked ),
-			normal: remapType( this.normalMaps, linearLists, linearDedup, this._linearTexPacked ),
-			bump: remapType( this.bumpMaps, linearLists, linearDedup, this._linearTexPacked ),
-			roughness: remapType( this.roughnessMaps, linearLists, linearDedup, this._linearTexPacked ),
-			metalness: remapType( this.metalnessMaps, linearLists, linearDedup, this._linearTexPacked ),
-			displacement: remapType( this.displacementMaps, linearLists, linearDedup, this._linearTexPacked ),
-			anisotropy: remapType( this.anisotropyMaps, linearLists, linearDedup, this._linearTexPacked ),
+			albedo: remapType( this.maps, srgbLists, srgbDedup, this._srgbTexPacked, srgbShapes ),
+			emissive: remapType( this.emissiveMaps, srgbLists, srgbDedup, this._srgbTexPacked, srgbShapes ),
+			normal: remapType( this.normalMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			bump: remapType( this.bumpMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			roughness: remapType( this.roughnessMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			metalness: remapType( this.metalnessMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			displacement: remapType( this.displacementMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			anisotropy: remapType( this.anisotropyMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
 			// Extension maps — data maps → linear pool; color maps (sheenColor, specularColor) → sRGB pool.
-			transmission: remapType( this.transmissionMaps, linearLists, linearDedup, this._linearTexPacked ),
-			clearcoat: remapType( this.clearcoatMaps, linearLists, linearDedup, this._linearTexPacked ),
-			clearcoatRoughness: remapType( this.clearcoatRoughnessMaps, linearLists, linearDedup, this._linearTexPacked ),
-			sheenColor: remapType( this.sheenColorMaps, srgbLists, srgbDedup, this._srgbTexPacked ),
-			sheenRoughness: remapType( this.sheenRoughnessMaps, linearLists, linearDedup, this._linearTexPacked ),
-			iridescence: remapType( this.iridescenceMaps, linearLists, linearDedup, this._linearTexPacked ),
-			iridescenceThickness: remapType( this.iridescenceThicknessMaps, linearLists, linearDedup, this._linearTexPacked ),
-			specularIntensity: remapType( this.specularIntensityMaps, linearLists, linearDedup, this._linearTexPacked ),
-			specularColor: remapType( this.specularColorMaps, srgbLists, srgbDedup, this._srgbTexPacked ),
+			transmission: remapType( this.transmissionMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			clearcoat: remapType( this.clearcoatMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			clearcoatRoughness: remapType( this.clearcoatRoughnessMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			sheenColor: remapType( this.sheenColorMaps, srgbLists, srgbDedup, this._srgbTexPacked, srgbShapes ),
+			sheenRoughness: remapType( this.sheenRoughnessMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			iridescence: remapType( this.iridescenceMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			iridescenceThickness: remapType( this.iridescenceThicknessMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			specularIntensity: remapType( this.specularIntensityMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			specularColor: remapType( this.specularColorMaps, srgbLists, srgbDedup, this._srgbTexPacked, srgbShapes ),
 		};
 
 		return { srgbLists, linearLists, remap };