@gnsx/three 0.186.9 → 0.186.11

package/build/three.webgpu.js

@@ -76,7 +76,8 @@ const refreshUniforms = [
 	'steps',
 	'thickness',
 	'transmission',
-	'transmissionMap'
+	'transmissionMap',
+	'wireframe'
 ];
 
 
@@ -271,14 +272,12 @@ class NodeMaterialObserver {
 
 			}
 
-			if ( renderObject.material.transmission > 0 ) {
+			// global data
 
-				const { width, height } = renderObject.context;
-
-				data.bufferWidth = width;
-				data.bufferHeight = height;
+			const { width, height } = renderObject.context;
 
-			}
+			data.bufferWidth = width;
+			data.bufferHeight = height;
 
 			const { environmentIntensity, environmentRotation } = renderObject.scene;
 
@@ -599,18 +598,14 @@ class NodeMaterialObserver {
 
 		}
 
-		if ( materialData.transmission > 0 ) {
+		const { width, height } = renderObject.context;
 
-			const { width, height } = renderObject.context;
+		if ( renderObjectData.bufferWidth !== width || renderObjectData.bufferHeight !== height ) {
 
-			if ( renderObjectData.bufferWidth !== width || renderObjectData.bufferHeight !== height ) {
-
-				renderObjectData.bufferWidth = width;
-				renderObjectData.bufferHeight = height;
-
-				return false;
+			renderObjectData.bufferWidth = width;
+			renderObjectData.bufferHeight = height;
 
-			}
+			return false;
 
 		}
 
@@ -21853,7 +21848,7 @@ const LIGHTING_COMPLEXITY_SHADOW_WEIGHT = 0.5;
  *
  * @type {Array<Array<number>>}
  */
-const SHADER_COMPLEXITY_COLORS = [
+const SHADER_COMPLEXITY_COLORS$1 = [
 	[ 0.0, 1.0, 0.127 ],
 	[ 0.0, 1.0, 0.0 ],
 	[ 0.046, 0.52, 0.0 ],
@@ -21890,7 +21885,7 @@ const QUAD_COMPLEXITY_COLORS = [
  *
  * @type {Array<Array<number>>}
  */
-const LIGHT_COMPLEXITY_COLORS = [
+const LIGHT_COMPLEXITY_COLORS$1 = [
 	[ 0.0, 0.0, 0.0 ],
 	[ 0.0, 0.0, 0.4 ],
 	[ 0.0, 0.3, 1.0 ],
@@ -21941,7 +21936,7 @@ const colorizeLinear = ( cost, colors ) => {
  * @param {Node<float>} cost - Accumulated light weight.
  * @return {Node<vec3>} The ramp color.
  */
-const colorizeLightComplexity = ( cost ) => colorizeLinear( cost, LIGHT_COMPLEXITY_COLORS );
+const colorizeLightComplexity = ( cost ) => colorizeLinear( cost, LIGHT_COMPLEXITY_COLORS$1 );
 
 /**
  * Unreal's stair sample for quad overdraw (`CS_STAIR`).
@@ -22036,33 +22031,33 @@ function debugViewSkipsToneMapping( view ) {
 const colorizeShaderComplexity = /*@__PURE__*/ Fn( ( [ complexity ] ) => {
 
 	const c = complexity.clamp( 0, 0.999 );
-	const expanded = min$1( float( SHADER_COMPLEXITY_COLORS.length - 2 ), c.mul( 18 ) );
+	const expanded = min$1( float( SHADER_COMPLEXITY_COLORS$1.length - 2 ), c.mul( 18 ) );
 	const color = vec3( 0 ).toVar();
 	const frac = fract( expanded );
 
 	If( expanded.lessThan( 1 ), () => {
 
-		color.assign( mix( rgb( SHADER_COMPLEXITY_COLORS, 0 ), rgb( SHADER_COMPLEXITY_COLORS, 1 ), frac ) );
+		color.assign( mix( rgb( SHADER_COMPLEXITY_COLORS$1, 0 ), rgb( SHADER_COMPLEXITY_COLORS$1, 1 ), frac ) );
 
 	} ).ElseIf( expanded.lessThan( 2 ), () => {
 
-		color.assign( mix( rgb( SHADER_COMPLEXITY_COLORS, 1 ), rgb( SHADER_COMPLEXITY_COLORS, 2 ), frac ) );
+		color.assign( mix( rgb( SHADER_COMPLEXITY_COLORS$1, 1 ), rgb( SHADER_COMPLEXITY_COLORS$1, 2 ), frac ) );
 
 	} ).ElseIf( expanded.lessThan( 3 ), () => {
 
-		color.assign( mix( rgb( SHADER_COMPLEXITY_COLORS, 2 ), rgb( SHADER_COMPLEXITY_COLORS, 3 ), frac ) );
+		color.assign( mix( rgb( SHADER_COMPLEXITY_COLORS$1, 2 ), rgb( SHADER_COMPLEXITY_COLORS$1, 3 ), frac ) );
 
 	} ).ElseIf( expanded.lessThan( 4 ), () => {
 
-		color.assign( mix( rgb( SHADER_COMPLEXITY_COLORS, 3 ), rgb( SHADER_COMPLEXITY_COLORS, 4 ), frac ) );
+		color.assign( mix( rgb( SHADER_COMPLEXITY_COLORS$1, 3 ), rgb( SHADER_COMPLEXITY_COLORS$1, 4 ), frac ) );
 
 	} ).ElseIf( expanded.lessThan( 5 ), () => {
 
-		color.assign( mix( rgb( SHADER_COMPLEXITY_COLORS, 4 ), rgb( SHADER_COMPLEXITY_COLORS, 5 ), frac ) );
+		color.assign( mix( rgb( SHADER_COMPLEXITY_COLORS$1, 4 ), rgb( SHADER_COMPLEXITY_COLORS$1, 5 ), frac ) );
 
 	} ).ElseIf( expanded.lessThan( 6 ), () => {
 
-		color.assign( mix( rgb( SHADER_COMPLEXITY_COLORS, 5 ), rgb( SHADER_COMPLEXITY_COLORS, 6 ), frac ) );
+		color.assign( mix( rgb( SHADER_COMPLEXITY_COLORS$1, 5 ), rgb( SHADER_COMPLEXITY_COLORS$1, 6 ), frac ) );
 
 	} ).Else( () => {
 
@@ -22072,11 +22067,11 @@ const colorizeShaderComplexity = /*@__PURE__*/ Fn( ( [ complexity ] ) => {
 
 		If( upper.lessThanEqual( 1 ), () => {
 
-			color.assign( mix( rgb( SHADER_COMPLEXITY_COLORS, 6 ), rgb( SHADER_COMPLEXITY_COLORS, 7 ), upperFrac ) );
+			color.assign( mix( rgb( SHADER_COMPLEXITY_COLORS$1, 6 ), rgb( SHADER_COMPLEXITY_COLORS$1, 7 ), upperFrac ) );
 
 		} ).Else( () => {
 
-			color.assign( mix( rgb( SHADER_COMPLEXITY_COLORS, 7 ), rgb( SHADER_COMPLEXITY_COLORS, 8 ), upperFrac ) );
+			color.assign( mix( rgb( SHADER_COMPLEXITY_COLORS$1, 7 ), rgb( SHADER_COMPLEXITY_COLORS$1, 8 ), upperFrac ) );
 
 		} );
 
@@ -23133,6 +23128,165 @@ function applyShadowCasterDebug( builder, material ) {
 
 }
 
+// WITH_GENESYS
+// LOD coloration. Each drawn LOD tier gets a fixed color from the palette, then lit.
+// !WITH_GENESYS
+
+
+/**
+ * LOD coloration. Colors geometry by its active LOD index, then lights that color.
+ * Matches Unreal `LODColorationColors` from `BaseEngine.ini`.
+ *
+ * @type {string}
+ */
+const DEBUG_VIEW_LOD_COLORATION = 'lodColoration';
+
+/**
+ * Default palette when `renderer.debug.lodColorationColors` is not set.
+ * Unreal: white, red, green, blue, yellow, fuchsia, cyan, purple.
+ *
+ * @type {Color[]}
+ */
+const DEFAULT_LOD_COLORATION_COLORS = [
+	new Color( 1, 1, 1 ),
+	new Color( 1, 0, 0 ),
+	new Color( 0, 1, 0 ),
+	new Color( 0, 0, 1 ),
+	new Color( 1, 1, 0 ),
+	new Color( 1, 0, 1 ),
+	new Color( 0, 1, 1 ),
+	new Color( 0.5, 0, 0.5 ),
+];
+
+const INVALID_LOD_COLOR = new Color( 1, 0, 1 );
+
+/**
+ * Resolves the LOD index used for coloration on a drawn object.
+ * `userData.lodColorationIndex` on the object or an ancestor wins (Genesys instanced LOD tiers).
+ * Otherwise the nearest `THREE.LOD` parent is consulted: the level object that owns the draw,
+ * or the parent's current level as a fallback.
+ *
+ * @param {?Object3D} object - The drawn object.
+ * @return {number} LOD index, or `-1` when no palette entry should be used.
+ */
+function resolveLODColorationIndex( object ) {
+
+	if ( object === null ) return -1;
+
+	let node = object;
+
+	while ( node !== null ) {
+
+		const tagged = node.userData.lodColorationIndex;
+
+		if ( typeof tagged === 'number' && Number.isFinite( tagged ) ) {
+
+			return tagged;
+
+		}
+
+		node = node.parent;
+
+	}
+
+	node = object;
+
+	while ( node !== null ) {
+
+		const parent = node.parent;
+
+		if ( parent !== null && parent.isLOD === true ) {
+
+			const levels = parent.levels;
+
+			for ( let i = 0; i < levels.length; i ++ ) {
+
+				const levelObject = levels[ i ].object;
+
+				if ( levelObject === object || levelObject.getObjectById( object.id ) !== undefined ) {
+
+					return i;
+
+				}
+
+			}
+
+			return parent.getCurrentLevel();
+
+		}
+
+		node = parent;
+
+	}
+
+	return 0;
+
+}
+
+/**
+ * @param {Color} color - Destination color.
+ * @param {?Object3D} object - The drawn object.
+ * @param {Renderer~DebugConfig} debug - Renderer debug state.
+ * @return {Color} `color`.
+ */
+function writeLODColorationColor( color, object, debug ) {
+
+	const index = resolveLODColorationIndex( object );
+	const palette = debug.lodColorationColors ?? DEFAULT_LOD_COLORATION_COLORS;
+
+	if ( index < 0 || index >= palette.length ) {
+
+		return color.copy( INVALID_LOD_COLOR );
+
+	}
+
+	return color.copy( palette[ index ] );
+
+}
+
+/**
+ * Replaces albedo with the LOD palette color after the material has written its channels.
+ *
+ * @param {NodeBuilder} builder - The current node builder.
+ * @param {NodeMaterial} material - The node material being set up.
+ */
+function applyLODColorationDebug( builder, material ) {
+
+	const colorNode = uniform( new Color() ).onObjectUpdate( ( { object }, self ) => {
+
+		if ( object === null ) return;
+
+		return writeLODColorationColor( self.value, object, builder.renderer.debug );
+
+	} );
+
+	diffuseColor.rgb.assign( colorNode );
+
+	if ( material.lights !== true ) return;
+
+	metalness.assign( float( 0 ) );
+	diffuseContribution.assign( colorNode );
+	roughness.assign( float( 1 ) );
+	specularColor.assign( vec3( 0 ) );
+	specularColorBlended.assign( vec3( 0 ) );
+	specularF90.assign( float( 0 ) );
+
+	builder.context.ambientOcclusion = null;
+
+	if ( material.useClearcoat === true ) clearcoat.assign( float( 0 ) );
+
+	if ( material.useSheen === true ) sheen.assign( vec3( 0 ) );
+
+	if ( material.useIridescence === true ) iridescence.assign( float( 0 ) );
+
+	if ( material.useAnisotropy === true ) anisotropy.assign( float( 0 ) );
+
+	if ( material.useTransmission === true ) transmission.assign( float( 0 ) );
+
+	if ( material.useRetroreflection === true ) retroreflectivity.assign( float( 0 ) );
+
+}
+
 // WITH_GENESYS
 // Double sided. Gray is a single-sided surface or the front of a double-sided one.
 // Blue is a double-sided back face you can see. Red is a double-sided back face hidden behind the front.
@@ -23830,6 +23984,10 @@ class NodeMaterial extends Material {
 
 				applyShadowCasterDebug( builder, this );
 
+			} else if ( renderer.debug.view === DEBUG_VIEW_LOD_COLORATION && this.isShadowPassMaterial !== true ) {
+
+				applyLODColorationDebug( builder, this );
+
 			} else if ( renderer.debug.view === DEBUG_VIEW_DOUBLE_SIDE && this.isShadowPassMaterial !== true ) {
 
 				applyDoubleSideDebug( builder, this );
@@ -24292,7 +24450,7 @@ class NodeMaterial extends Material {
 	setupNormal( builder ) {
 
 		// WITH_GENESYS
-		if ( ( builder.renderer.debug.view === DEBUG_VIEW_LIGHTING_ONLY || builder.renderer.debug.view === DEBUG_VIEW_DRAW_CALL || builder.renderer.debug.view === DEBUG_VIEW_FRONT_BACK_FACE || builder.renderer.debug.view === DEBUG_VIEW_SHADOW_CASTER || builder.renderer.debug.view === DEBUG_VIEW_DOUBLE_SIDE ) && this.isShadowPassMaterial !== true && this.fragmentNode === null ) {
+		if ( ( builder.renderer.debug.view === DEBUG_VIEW_LIGHTING_ONLY || builder.renderer.debug.view === DEBUG_VIEW_DRAW_CALL || builder.renderer.debug.view === DEBUG_VIEW_FRONT_BACK_FACE || builder.renderer.debug.view === DEBUG_VIEW_SHADOW_CASTER || builder.renderer.debug.view === DEBUG_VIEW_LOD_COLORATION || builder.renderer.debug.view === DEBUG_VIEW_DOUBLE_SIDE ) && this.isShadowPassMaterial !== true && this.fragmentNode === null ) {
 
 			return lightingOnlyNormal();
 
@@ -24497,7 +24655,7 @@ class NodeMaterial extends Material {
 			// WITH_GENESYS
 			// Lighting only and draw call substitute a plain lit material, so emissive is dropped.
 			// Detail lighting keeps it.
-			if ( ( builder.renderer.debug.view === DEBUG_VIEW_LIGHTING_ONLY || builder.renderer.debug.view === DEBUG_VIEW_DRAW_CALL || builder.renderer.debug.view === DEBUG_VIEW_FRONT_BACK_FACE || builder.renderer.debug.view === DEBUG_VIEW_SHADOW_CASTER || builder.renderer.debug.view === DEBUG_VIEW_DOUBLE_SIDE ) && this.isShadowPassMaterial !== true ) {
+			if ( ( builder.renderer.debug.view === DEBUG_VIEW_LIGHTING_ONLY || builder.renderer.debug.view === DEBUG_VIEW_DRAW_CALL || builder.renderer.debug.view === DEBUG_VIEW_FRONT_BACK_FACE || builder.renderer.debug.view === DEBUG_VIEW_SHADOW_CASTER || builder.renderer.debug.view === DEBUG_VIEW_LOD_COLORATION || builder.renderer.debug.view === DEBUG_VIEW_DOUBLE_SIDE ) && this.isShadowPassMaterial !== true ) {
 
 				return outgoingLightNode;
 
@@ -34279,6 +34437,8 @@ class Geometries extends DataMap {
 
 			this._geometryDisposeListeners.delete( geometry );
 
+			this.delete( geometry );
+
 		};
 
 		geometry.addEventListener( 'dispose', onDispose );
@@ -43351,7 +43511,7 @@ class VelocityNode extends TempNode {
 		 * @type {UniformNode<mat4>}
 		 * @default null
 		 */
-		this.previousCameraViewMatrix = uniform( new Matrix4() );
+		this.previousCameraViewMatrix = uniform( new Matrix4() ).setGroup( renderGroup );
 
 	}
 
@@ -56085,6 +56245,8 @@ class NodeBuilder {
 		delete context.getAO;
 		delete context.getGI;
 		delete context.getShadow;
+		delete context.nodeLoop;
+		delete context.nodeBlock;
 
 		return context;
 
@@ -64162,6 +64324,565 @@ class CanvasTarget extends EventDispatcher {
 
 }
 
+// WITH_GENESYS
+// Viewport legend for renderer.debug views that use fixed ramps or symbolic colors.
+// !WITH_GENESYS
+
+const SHADER_COMPLEXITY_COLORS = [
+	[ 0.0, 1.0, 0.127 ],
+	[ 0.0, 1.0, 0.0 ],
+	[ 0.046, 0.52, 0.0 ],
+	[ 0.215, 0.215, 0.0 ],
+	[ 0.52, 0.046, 0.0 ],
+	[ 0.7, 0.0, 0.0 ],
+	[ 1.0, 0.0, 0.0 ],
+	[ 1.0, 0.0, 0.5 ],
+	[ 1.0, 0.9, 0.9 ]
+];
+
+const QUAD_OVERDRAW_COLORS = [
+	[ 0.0, 0.0, 0.0 ],
+	[ 0.0, 0.0, 0.4 ],
+	[ 0.0, 0.3, 1.0 ],
+	[ 0.0, 0.7, 0.4 ],
+	[ 0.0, 1.0, 0.0 ],
+	[ 0.8, 0.8, 0.0 ],
+	[ 1.0, 0.3, 0.0 ],
+	[ 0.7, 0.0, 0.0 ],
+	[ 0.5, 0.0, 0.5 ],
+	[ 0.7, 0.3, 0.7 ],
+	[ 1.0, 0.9, 0.9 ]
+];
+
+const LIGHT_COMPLEXITY_COLORS = QUAD_OVERDRAW_COLORS;
+
+const DEFAULT_LOD_LABELS = [
+	'LOD 0',
+	'LOD 1',
+	'LOD 2',
+	'LOD 3',
+	'LOD 4',
+	'LOD 5',
+	'LOD 6',
+	'LOD 7'
+];
+
+const DEFAULT_LOD_COLORS = [
+	[ 1, 1, 1 ],
+	[ 1, 0, 0 ],
+	[ 0, 1, 0 ],
+	[ 0, 0, 1 ],
+	[ 1, 1, 0 ],
+	[ 1, 0, 1 ],
+	[ 0, 1, 1 ],
+	[ 0.5, 0, 0.5 ]
+];
+
+const LEGEND_DEBUG_KEYS = new Set( [
+	'view',
+	'buffer',
+	'shaderComplexityBudget',
+	'quadOverdrawBudget'
+] );
+
+let _stylesInjected = false;
+
+function injectStyles() {
+
+	if ( _stylesInjected === true || typeof document === 'undefined' ) return;
+
+	_stylesInjected = true;
+
+	const style = document.createElement( 'style' );
+	style.textContent = `
+.three-debug-view-legend {
+	position: absolute;
+	left: 12px;
+	bottom: 12px;
+	z-index: 900;
+	max-width: min( 420px, calc( 100% - 24px ) );
+	padding: 10px 12px;
+	border-radius: 8px;
+	border: 1px solid rgba( 74, 74, 90, 0.55 );
+	background: rgba( 30, 30, 36, 0.88 );
+	color: #e0e0e0;
+	font: 12px/1.35 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+	pointer-events: none;
+	backdrop-filter: blur( 8px );
+	box-shadow: 0 4px 15px rgba( 0, 0, 0, 0.35 );
+}
+
+.three-debug-view-legend[ hidden ] {
+	display: none !important;
+}
+
+.three-debug-view-legend-title {
+	font-size: 11px;
+	font-weight: 600;
+	letter-spacing: 0.02em;
+	text-transform: uppercase;
+	color: #9a9aab;
+	margin-bottom: 6px;
+}
+
+.three-debug-view-legend-caption {
+	margin-top: 6px;
+	color: #9a9aab;
+	font-size: 11px;
+}
+
+.three-debug-view-legend-ramp {
+	height: 10px;
+	border-radius: 4px;
+	border: 1px solid rgba( 255, 255, 255, 0.12 );
+	margin: 4px 0 6px;
+}
+
+.three-debug-view-legend-items {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 8px 12px;
+}
+
+.three-debug-view-legend-item {
+	display: inline-flex;
+	align-items: center;
+	gap: 6px;
+	white-space: nowrap;
+}
+
+.three-debug-view-legend-swatch {
+	width: 10px;
+	height: 10px;
+	border-radius: 2px;
+	border: 1px solid rgba( 255, 255, 255, 0.2 );
+	flex-shrink: 0;
+}
+
+.three-debug-view-legend-textonly {
+	color: #c8c8d4;
+}
+`;
+
+	document.head.appendChild( style );
+
+}
+
+function rgbToCss( rgb ) {
+
+	const r = Math.round( rgb[ 0 ] * 255 );
+	const g = Math.round( rgb[ 1 ] * 255 );
+	const b = Math.round( rgb[ 2 ] * 255 );
+
+	return `rgb( ${ r }, ${ g }, ${ b } )`;
+
+}
+
+function rampGradient( colors ) {
+
+	const stops = colors.map( ( c, i ) => `${ rgbToCss( c ) } ${ ( i / ( colors.length - 1 ) ) * 100 }%` );
+
+	return `linear-gradient( to right, ${ stops.join( ', ' ) } )`;
+
+}
+
+function legendRamp( labelLow, labelHigh, colors, caption ) {
+
+	return {
+		title: null,
+		ramp: rampGradient( colors ),
+		rampLabels: [ labelLow, labelHigh ],
+		items: null,
+		caption
+	};
+
+}
+
+function legendItems( title, items, caption ) {
+
+	return {
+		title,
+		ramp: null,
+		rampLabels: null,
+		items,
+		caption
+	};
+
+}
+
+/**
+ * @param {Renderer~DebugConfig} debug
+ * @return {?object}
+ */
+function getLegendSpec( debug ) {
+
+	const view = debug.view;
+	const buffer = debug.buffer;
+
+	if ( view === 'shaderComplexity' || view === 'shaderComplexityAndOverdraw' ) {
+
+		const budget = debug.shaderComplexityBudget ?? 800;
+
+		return legendRamp(
+			'Low cost',
+			`Budget (${ budget })`,
+			SHADER_COMPLEXITY_COLORS,
+			view === 'shaderComplexityAndOverdraw'
+				? 'Shader cost multiplied by overlapping fragment count.'
+				: 'Estimated material shading cost.'
+		);
+
+	}
+
+	if ( view === 'lightingComplexity' ) {
+
+		return legendRamp(
+			'No lights',
+			'~10 lights',
+			LIGHT_COMPLEXITY_COLORS,
+			'Direct lights per pixel. Shadow casters count as 1.5.'
+		);
+
+	}
+
+	if ( view === 'overdraw' ) {
+
+		const budget = debug.quadOverdrawBudget ?? 10;
+
+		return legendRamp(
+			'1 fragment',
+			`Budget (${ budget })`,
+			QUAD_OVERDRAW_COLORS,
+			'Fragments that pass the depth test per pixel.'
+		);
+
+	}
+
+	if ( view === 'lodColoration' ) {
+
+		const palette = debug.lodColorationColors;
+		const items = [];
+
+		for ( let i = 0; i < DEFAULT_LOD_LABELS.length; i ++ ) {
+
+			const color = palette && palette[ i ] ? palette[ i ] : DEFAULT_LOD_COLORS[ i ];
+			const rgb = color.isColor ? [ color.r, color.g, color.b ] : DEFAULT_LOD_COLORS[ i ];
+
+			items.push( { color: rgbToCss( rgb ), label: DEFAULT_LOD_LABELS[ i ] } );
+
+		}
+
+		return legendItems( 'LOD coloration', items, 'Palette matches Unreal LODColorationColors.' );
+
+	}
+
+	if ( view === 'doubleSide' ) {
+
+		return legendItems( 'Double side', [
+			{ color: rgbToCss( [ 0.5, 0.5, 0.5 ] ), label: 'Single-sided or front' },
+			{ color: rgbToCss( [ 0.25, 0.45, 0.85 ] ), label: 'Visible back face' },
+			{ color: rgbToCss( [ 0.85, 0.12, 0.1 ] ), label: 'Hidden back face' }
+		], null );
+
+	}
+
+	if ( view === 'drawCall' ) {
+
+		return {
+			title: 'Draw call',
+			ramp: null,
+			rampLabels: null,
+			items: null,
+			caption: 'Each color is one submitted draw. Instanced meshes share one color.'
+		};
+
+	}
+
+	if ( view === 'shadowCaster' ) {
+
+		return legendItems( 'Shadow caster', [
+			{ color: rgbToCss( [ 0, 1, 0 ] ), label: 'Casts shadows' },
+			{ color: rgbToCss( [ 0.5, 0.5, 0.5 ] ), label: 'Does not cast' }
+		], null );
+
+	}
+
+	if ( view === 'frontBackFace' ) {
+
+		return legendItems( 'Front / back face', [
+			{ color: rgbToCss( [ 0.72, 0.70, 0.66 ] ), label: 'Facing camera' },
+			{ color: rgbToCss( [ 0.25, 0.45, 0.85 ] ), label: 'Opposite winding' }
+		], null );
+
+	}
+
+	if ( view === 'bufferVisualization' ) {
+
+		if ( buffer === 'worldNormal' ) {
+
+			return legendItems( 'World normal', [
+				{ color: rgbToCss( [ 0.5, 0.5, 1 ] ), label: '+X' },
+				{ color: rgbToCss( [ 0.5, 1, 0.5 ] ), label: '+Y (up)' },
+				{ color: rgbToCss( [ 1, 0.5, 0.5 ] ), label: '+Z' }
+			], 'Encoded as normal × 0.5 + 0.5.' );
+
+		}
+
+		if ( buffer === 'roughness' ) {
+
+			return legendRamp( 'Smooth', 'Rough', [[ 0, 0, 0 ], [ 1, 1, 1 ]], null );
+
+		}
+
+		if ( buffer === 'metallic' ) {
+
+			return legendRamp( 'Dielectric', 'Metal', [[ 0, 0, 0 ], [ 1, 1, 1 ]], null );
+
+		}
+
+		if ( buffer === 'ambientOcclusion' ) {
+
+			return legendRamp( 'Occluded', 'None', [[ 0.2, 0.2, 0.2 ], [ 1, 1, 1 ]], 'White when no AO map is applied.' );
+
+		}
+
+		if ( buffer === 'emissive' ) {
+
+			return legendRamp( 'None', 'Bright', [[ 0, 0, 0 ], [ 1, 1, 1 ]], 'Emissive color only, no lighting.' );
+
+		}
+
+	}
+
+	return null;
+
+}
+
+function renderSpec( root, spec ) {
+
+	root.replaceChildren();
+
+	if ( spec.title ) {
+
+		const title = document.createElement( 'div' );
+		title.className = 'three-debug-view-legend-title';
+		title.textContent = spec.title;
+		root.appendChild( title );
+
+	}
+
+	if ( spec.ramp ) {
+
+		const ramp = document.createElement( 'div' );
+		ramp.className = 'three-debug-view-legend-ramp';
+		ramp.style.background = spec.ramp;
+		root.appendChild( ramp );
+
+		if ( spec.rampLabels ) {
+
+			const labels = document.createElement( 'div' );
+			labels.className = 'three-debug-view-legend-items';
+			labels.style.justifyContent = 'space-between';
+			labels.style.width = '100%';
+
+			for ( const label of spec.rampLabels ) {
+
+				const item = document.createElement( 'span' );
+				item.className = 'three-debug-view-legend-item';
+				item.textContent = label;
+				labels.appendChild( item );
+
+			}
+
+			root.appendChild( labels );
+
+		}
+
+	}
+
+	if ( spec.items ) {
+
+		const row = document.createElement( 'div' );
+		row.className = 'three-debug-view-legend-items';
+
+		for ( const entry of spec.items ) {
+
+			const item = document.createElement( 'span' );
+			item.className = 'three-debug-view-legend-item';
+
+			const swatch = document.createElement( 'span' );
+			swatch.className = 'three-debug-view-legend-swatch';
+			swatch.style.background = entry.color;
+
+			const text = document.createElement( 'span' );
+			text.textContent = entry.label;
+
+			item.append( swatch, text );
+			row.appendChild( item );
+
+		}
+
+		root.appendChild( row );
+
+	}
+
+	if ( spec.caption ) {
+
+		const caption = document.createElement( 'div' );
+		caption.className = spec.items === null && spec.ramp === null
+			? 'three-debug-view-legend-textonly'
+			: 'three-debug-view-legend-caption';
+		caption.textContent = spec.caption;
+		root.appendChild( caption );
+
+	}
+
+}
+
+/**
+ * Wraps `renderer.debug` so legend-related assignments refresh the overlay immediately.
+ *
+ * @param {Renderer} renderer
+ * @param {Renderer~DebugConfig} debug
+ * @return {Renderer~DebugConfig}
+ */
+function wrapDebugConfigForLegend( renderer, debug ) {
+
+	return new Proxy( debug, {
+
+		set( target, prop, value ) {
+
+			const changed = target[ prop ] !== value;
+
+			target[ prop ] = value;
+
+			if ( changed === true && LEGEND_DEBUG_KEYS.has( prop ) ) {
+
+				renderer._syncDebugViewLegend();
+
+			}
+
+			return true;
+
+		}
+
+	} );
+
+}
+
+/**
+ * DOM overlay that explains the active `renderer.debug` view.
+ */
+class DebugViewLegend {
+
+	constructor() {
+
+		if ( typeof document === 'undefined' ) {
+
+			this.domElement = null;
+			this._parent = null;
+			this._signature = '';
+			return;
+
+		}
+
+		injectStyles();
+
+		this.domElement = document.createElement( 'div' );
+		this.domElement.className = 'three-debug-view-legend';
+		this.domElement.hidden = true;
+
+		this._parent = null;
+		this._signature = '';
+
+	}
+
+	/**
+	 * @param {HTMLElement} parent - Usually the canvas container.
+	 */
+	_mountParent( parent ) {
+
+		if ( this.domElement === null || parent === this._parent ) return;
+
+		if ( this._parent !== null ) {
+
+			this.domElement.remove();
+
+		}
+
+		this._parent = parent;
+
+		if ( getComputedStyle( parent ).position === 'static' ) {
+
+			parent.style.position = 'relative';
+
+		}
+
+		parent.appendChild( this.domElement );
+
+	}
+
+	/**
+	 * @param {Renderer} renderer
+	 */
+	sync( renderer ) {
+
+		if ( this.domElement === null ) return;
+
+		if ( renderer === null || renderer.debug === undefined ) {
+
+			this.domElement.hidden = true;
+			return;
+
+		}
+
+		const parent = renderer.domElement.parentElement;
+
+		if ( parent !== null ) {
+
+			this._mountParent( parent );
+
+		}
+
+		const debug = renderer.debug;
+		const signature = `${ debug.view }:${ debug.buffer ?? '' }:${ debug.shaderComplexityBudget }:${ debug.quadOverdrawBudget }`;
+
+		const spec = getLegendSpec( debug );
+
+		if ( spec === null ) {
+
+			this.domElement.hidden = true;
+			this._signature = '';
+			return;
+
+		}
+
+		this.domElement.hidden = false;
+
+		if ( signature !== this._signature ) {
+
+			renderSpec( this.domElement, spec );
+			this._signature = signature;
+
+		}
+
+	}
+
+	dispose() {
+
+		if ( this.domElement !== null ) {
+
+			this.domElement.remove();
+
+		}
+
+		this._parent = null;
+		this._signature = '';
+
+	}
+
+}
+
 const _scene = /*@__PURE__*/ new Scene();
 const _drawingBufferSize = /*@__PURE__*/ new Vector2();
 const _screen = /*@__PURE__*/ new Vector4();
@@ -64862,7 +65583,8 @@ class Renderer {
 		 * @property {?Function} onNodeBuilderCreated - A callback function that is executed after a node builder has been created and before it is built.
 		 * @property {?Function} onShaderError - A callback function that is executed when a shader error happens. Only supported with WebGL 2 right now.
 		 * @property {Function} getShaderAsync - Allows the get the raw shader code for the given scene, camera and 3D object.
-		 * @property {string} view - Debug view. `shaderComplexity`, `lightingComplexity`, `overdraw`, and `shaderComplexityAndOverdraw` replace the shaded color with a heatmap. `shaderComplexityAndOverdraw` multiplies the shader cost by the overdraw count. `bufferVisualization` shows one material channel. `lightingOnly` and `detailLighting` light a flat gray surface. `drawCall` lights each submitted draw with its own diffuse color. `frontBackFace` draws both windings and tints the side facing the camera. `shadowCaster` lights a mesh green when it casts shadows and gray when it does not. `doubleSide` lights a single-sided surface gray, a visible double-sided back face blue, and a hidden double-sided back face red. `wireframe` draws each mesh as lines along its triangle edges. Lighting stays the same as the shaded view. Shadow passes and fullscreen quads stay triangles.
+		 * @property {string} view - Debug view. `shaderComplexity`, `lightingComplexity`, `overdraw`, and `shaderComplexityAndOverdraw` replace the shaded color with a heatmap. `shaderComplexityAndOverdraw` multiplies the shader cost by the overdraw count. `bufferVisualization` shows one material channel. `lightingOnly` and `detailLighting` light a flat gray surface. `drawCall` lights each submitted draw with its own diffuse color. `lodColoration` lights geometry with the palette entry for its LOD index. `frontBackFace` draws both windings and tints the side facing the camera. `shadowCaster` lights a mesh green when it casts shadows and gray when it does not. `doubleSide` lights a single-sided surface gray, a visible double-sided back face blue, and a hidden double-sided back face red. `wireframe` draws each mesh as lines along its triangle edges. Lighting stays the same as the shaded view. Shadow passes and fullscreen quads stay triangles.
+		 * @property {Color[]} lodColorationColors - Palette for `lodColoration`. Defaults to Unreal `LODColorationColors`.
 		 * @property {string} buffer - Channel drawn by `bufferVisualization`: `baseColor`, `worldNormal`, `roughness`, `metallic`, `ambientOcclusion`, or `emissive`.
 		 * @property {number} shaderComplexityBudget - Proxy budget that fills the shader-complexity ramp.
 		 * @property {number} quadOverdrawBudget - Overlapping fragments that fill the quad-overdraw ramp.
@@ -64887,6 +65609,7 @@ class Renderer {
 			quadOverdrawBudget: DEFAULT_QUAD_OVERDRAW_BUDGET,
 			doubleSideHidden: false,
 			doubleSideBack: false,
+			lodColorationColors: DEFAULT_LOD_COLORATION_COLORS.map( color => color.clone() ),
 			// !WITH_GENESYS
 			getShaderAsync: async ( scene, camera, object ) => {
 
@@ -64909,8 +65632,30 @@ class Renderer {
 			}
 		};
 
+		this._debugViewLegend = typeof document !== 'undefined' ? new DebugViewLegend() : null;
+		this.debug = wrapDebugConfigForLegend( this, this.debug );
+
+	}
+
+	// WITH_GENESYS
+
+	/**
+	 * Keeps the debug-view legend aligned with `renderer.debug`.
+	 *
+	 * @private
+	 */
+	_syncDebugViewLegend() {
+
+		if ( this._debugViewLegend !== null ) {
+
+			this._debugViewLegend.sync( this );
+
+		}
+
 	}
 
+	// !WITH_GENESYS
+
 	/**
 	 * Initializes the renderer so it is ready for usage.
 	 *
@@ -64978,6 +65723,10 @@ class Renderer {
 			this._animation.start();
 			this._initialized = true;
 
+			// WITH_GENESYS
+			this._syncDebugViewLegend();
+			// !WITH_GENESYS
+
 			resolve( this );
 
 		} );
@@ -66927,6 +67676,15 @@ class Renderer {
 
 			this.info.dispose();
 
+			// WITH_GENESYS
+			if ( this._debugViewLegend !== null ) {
+
+				this._debugViewLegend.dispose();
+				this._debugViewLegend = null;
+
+			}
+			// !WITH_GENESYS
+
 			this._inspector.dispose();
 			this._animation.dispose();
 			this._objects.dispose();