rayzee 11.2.0 → 11.3.0

package/package.json

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

package/src/EngineDefaults.js

@@ -77,7 +77,7 @@ export const ENGINE_DEFAULTS = deepFreeze( {
 
 	// Read when a model loads
 	maxTextureSize: 4096, // longest edge of a material texture; clamped to the hardware ceiling
-	areaLightIntensityScale: 1, // power of a glTF model's placeholder area lights (RectAreaLight extras)
+	areaLightIntensityScale: 0.1, // power of a glTF model's placeholder area lights (RectAreaLight extras)
 
 	// Debug
 	visMode: 0, // a debug view (TSL/Debugger.js); 0 renders normally

package/src/PathTracerApp.js

@@ -189,7 +189,8 @@ export class PathTracerApp extends RayzeeRenderer {
 			canvas: this.canvas,
 			assetLoader: this.assetLoader,
 			pathTracer: null,
-			floorPlane: this.assetLoader.floorPlane
+			floorPlane: this.assetLoader.floorPlane,
+			isGeometryOnDisk: () => this.geometryOnDisk,
 		} );
 
 		this.interactionManager.wireAppEvents( this );
@@ -678,7 +679,7 @@ export class PathTracerApp extends RayzeeRenderer {
 
 			this._notePlacementsMoving( meshIndices );
 			this._sdf.updateMeshTransforms( meshIndices );
-			this.stages.pathTracer?.updateBufferRanges( [], [ this._sdf.computeTLASDirtyRange() ] );
+			this.stages.pathTracer?.updateBufferRanges( [], this._sdf.takeMoveRanges() );
 			if ( this._sdf.movesEmitters( meshIndices ) ) {
 
 				this._emittersMoved = true;
@@ -717,7 +718,7 @@ export class PathTracerApp extends RayzeeRenderer {
 
 			const run = table.placementRunOf( meshIndex );
 			if ( ! run ) continue;
-			for ( let p = run.start; p < run.start + run.count; p ++ ) dm.notePlacementMoving( table.tlasLeafIndex[ p ], table.world, p * 16 );
+			for ( let p = run.start; p < run.start + run.count; p ++ ) dm.notePlacementMoving( table.tlasLeafIndex[ p ], () => table.matrixWorldOf( p ) );
 
 		}
 

package/src/Processor/ArchiveImporter.js

@@ -10,7 +10,7 @@
 import { FloatType, EquirectangularReflectionMapping, Texture, SRGBColorSpace, RepeatWrapping, LoadingManager } from 'three';
 import { HDRLoader } from 'three/addons/loaders/HDRLoader.js';
 import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
-import { zipSync, strFromU8 } from 'three/addons/libs/fflate.module.js';
+import { strFromU8 } from 'three/addons/libs/fflate.module.js';
 import {
 	detectArchiveKind, readTarGz, elementFilter, listArchiveElements, openTar, indexTarHeaders, openFolder } from './ArchiveReader.js';
 import { openZip, readZipDirectory } from './ZipReader.js';
@@ -23,16 +23,13 @@ import { worthStoring } from '../Storage/sceneCachePolicy.js';
 import { VERSION } from '../version.js';
 import { updateLoading } from './utils';
 import { loadPBRTScene, pickEntryPath, VirtualFS, PBRT_BUILD_REVISION } from './PBRT/index.js';
+import { loadUSDScene, listUSDRootLayers, listUSDParts, USDFiles, USDStage, USD_LAYER } from './USD/index.js';
 import { pfmTexture } from './PBRT/PFM.js';
 import { extractSceneMetadata } from './SceneMetadata.js';
 import { ISSUE_CODES, ISSUE_SEVERITY } from '../EngineIssues.js';
 import { ARCHIVE_FORMATS } from './archiveFormats.js';
 import { withHostWorker } from '../Platform.js';
 
-// Loose USD layers inside a ZIP compose into one scene; these pick out the
-// layers and the image assets they reference.
-const USD_LAYER_RE = /\.(usd|usda|usdc)$/i;
-const USD_IMAGE_RE = /\.(png|jpg|jpeg|avif)$/i;
 const MTL_TEXTURE_TIMEOUT_MS = 30000;
 const MAIN_MODEL_FILES = [ 'scene.gltf', 'scene.glb', 'model.gltf', 'model.glb', 'main.gltf', 'main.glb', 'asset.gltf', 'asset.glb' ];
 
@@ -72,6 +69,9 @@ const bufferOf = async entry => {
  */
 export const ARCHIVE_ELEMENT_PROMPT_BYTES = 4_000_000_000;
 
+/** The same question for a USD scene, in USD layer bytes: binary layers hold far more geometry a byte than pbrt text. */
+export const USD_ELEMENT_PROMPT_BYTES = 1_000_000_000;
+
 export class ArchiveImporter {
 
 	/** The archive formats it adds to the loader's. */
@@ -83,6 +83,7 @@ export class ArchiveImporter {
 		this.loader = loader;
 		this._pendingGraph = null;
 		this.lastPBRTStats = null;
+		this.lastUSDStats = null;
 
 	}
 
@@ -274,7 +275,7 @@ export class ArchiveImporter {
 		);
 
 		const archiveId = this.loader.storage ? identityKey( await folderIdentity( folder ) ) : null;
-		return await this._loadSource( source, folder.name, { element, pbrtEntry, pbrt, archiveId, kind: 'folder' } );
+		return await this._loadSource( source, folder.name, { element, pbrtEntry, pbrt, archiveId, promptBytes, kind: 'folder' } );
 
 	}
 
@@ -294,12 +295,12 @@ export class ArchiveImporter {
 	async _loadSeekable( file, filename, { element, promptBytes, pbrtEntry, pbrt, index = null, zip = false, archiveId = null } ) {
 
 		const source = await this._openSeekableArchive( file, filename, element, promptBytes, { index, zip } );
-		return await this._loadSource( source, filename, { element, pbrtEntry, pbrt, archiveId } );
+		return await this._loadSource( source, filename, { element, pbrtEntry, pbrt, archiveId, promptBytes } );
 
 	}
 
 	/** Loads what an opened archive or folder holds. @private */
-	async _loadSource( source, filename, { element, pbrtEntry, pbrt, archiveId, kind = 'archive' } ) {
+	async _loadSource( source, filename, { element, pbrtEntry, pbrt, archiveId, promptBytes, kind = 'archive' } ) {
 
 		source.archiveId = archiveId;
 		source.elements = ( Array.isArray( element ) ? element : [ element ] ).filter( Boolean );
@@ -311,7 +312,9 @@ export class ArchiveImporter {
 
 		const entries = Object.create( null );
 		for ( const e of source.listing ) if ( e.offset !== undefined ) entries[ e.path ] = source.entries[ e.path ] ?? await source.slice( e.path );
-		const result = await this._loadNonPBRTArchive( entries, filename );
+		const result = this._mainModelPath( Object.keys( entries ) )?.usd
+			? await this.loadUSDScene( entries, filename, { ...pbrt, element, promptBytes, listing: source.listing } )
+			: await this._loadNonPBRTArchive( entries, filename );
 		this.loader._sourceKey = this.loader._keyed( kind, archiveId );
 		return result;
 
@@ -628,39 +631,8 @@ export class ArchiveImporter {
 		}
 
 		const plyParser = ( buf ) => this.loader.loaderCache.ply.parse( buf );
-
-		// Texture maps — decode by extension (pbrt uses .png/.jpg but also .exr/.hdr/.tga). Tagged
-		// with their archive path so a stored scene can read them back instead of keeping pixels.
-		const imageFromBytes = async ( bytes, fname ) => {
-
-			const texture = await this._pbrtTextureFromBytes( bytes, fname );
-			if ( texture ) texture.userData[ ARCHIVE_PATH ] = fname;
-			return texture;
-
-		};
-
-		// Infinite-light maps → HDR/EXR/LDR via the shared environment decoder.
-		const envFromBytes = async ( bytes, fname ) => {
-
-			const ext = fname.split( '.' ).pop().toLowerCase();
-			const blob = new Blob( [ bytes ] );
-			const url = ext === 'pfm' ? null : URL.createObjectURL( blob );
-			try {
-
-				const texture = url ? await this.loader.loadEnvironmentByExtension( url, ext, { loader: ext === 'exr' ? this._exrLoader() : null } ) : pfmTexture( bytes );
-				texture.mapping = EquirectangularReflectionMapping;
-				setEnvironmentSource( texture, `bytes:${await sampleHash( blob )}` );
-				texture.userData[ ARCHIVE_PATH ] = fname;
-				texture.userData[ ARCHIVE_LOADER ] = 'environment';
-				return texture;
-
-			} finally {
-
-				if ( url ) URL.revokeObjectURL( url );
-
-			}
-
-		};
+		const imageFromBytes = ( bytes, fname ) => this._archiveImage( bytes, fname );
+		const envFromBytes = ( bytes, fname ) => this._archiveEnvironment( bytes, fname );
 
 		const pbrtStart = performance.now();
 		const shape = {
@@ -754,6 +726,150 @@ export class ArchiveImporter {
 
 	}
 
+	/** A texture map from an archive, tagged with its path so a stored scene can read it back. @private */
+	async _archiveImage( bytes, fname ) {
+
+		const texture = await this._pbrtTextureFromBytes( bytes, fname );
+		if ( texture ) texture.userData[ ARCHIVE_PATH ] = fname;
+		return texture;
+
+	}
+
+	async _archiveEnvironment( bytes, fname ) {
+
+		const ext = fname.split( '.' ).pop().toLowerCase();
+		const blob = new Blob( [ bytes ] );
+		const url = ext === 'pfm' ? null : URL.createObjectURL( blob );
+		try {
+
+			const texture = url ? await this.loader.loadEnvironmentByExtension( url, ext, { loader: ext === 'exr' ? this._exrLoader() : null } ) : pfmTexture( bytes );
+			texture.mapping = EquirectangularReflectionMapping;
+			setEnvironmentSource( texture, `bytes:${await sampleHash( blob )}` );
+			texture.userData[ ARCHIVE_PATH ] = fname;
+			texture.userData[ ARCHIVE_LOADER ] = 'environment';
+			return texture;
+
+		} finally {
+
+			if ( url ) URL.revokeObjectURL( url );
+
+		}
+
+	}
+
+	/**
+	 * A USD scene from a folder's or archive's files (path → bytes or Blob), each layer read as composition reaches it.
+	 * @param {object} [options] - `element`, `promptBytes`, `listing` (every file, loaded or not), and loadArchiveFromFile's budgets
+	 */
+	async loadUSDScene( entries, filename, options = {} ) {
+
+		updateLoading( { isLoading: true, status: 'Reading USD scene...', progress: 5 } );
+		const paths = Object.keys( entries );
+		const omitted = ( options.listing ?? [] ).filter( e => ! ( e.path in entries ) ).map( e => e.path );
+		const files = new USDFiles( paths, async path => ( entries[ path ] ? bytesOf( entries[ path ] ) : null ), { omitted } );
+		const candidates = listUSDRootLayers( paths );
+		if ( candidates.length === 0 ) throw new Error( `No USD layer found in ${filename}` );
+		const entryPath = candidates[ 0 ];
+		if ( candidates.length > 1 ) {
+
+			console.warn( `${filename} holds ${candidates.length} top-level USD layers; loaded "${entryPath}". Others: ${candidates.slice( 1 ).join( ', ' )}` );
+			this.loader._issues?.record(
+				ISSUE_CODES.ASSET_AMBIGUOUS_ENTRY,
+				`${filename} holds ${candidates.length} top-level USD layers; loaded "${entryPath}"`,
+				{ loaded: entryPath, alternatives: candidates.slice( 1 ) },
+				ISSUE_SEVERITY.WARNING
+			);
+
+		}
+
+		const chosen = ( Array.isArray( options.element ) ? options.element : [ options.element ] ).filter( Boolean );
+		if ( chosen.length === 0 ) await this._requireUSDPartChoice( filename, files, entryPath, options.listing ?? paths.map( path => ( { path, size: entries[ path ]?.size ?? entries[ path ]?.byteLength ?? 0 } ) ), options.promptBytes );
+
+		const start = performance.now();
+		const built = await loadUSDScene( {
+			files, entryPath,
+			resolveImage: async path => {
+
+				const bytes = await files.read( path );
+				return bytes ? this._archiveImage( bytes, path ) : null;
+
+			},
+			resolveEnvironment: async path => {
+
+				const bytes = await files.read( path );
+				return bytes ? this._archiveEnvironment( bytes, path ) : null;
+
+			},
+			maxTriangles: options.maxTriangles, maxPlacements: options.maxPlacements, mergeShapesAbove: options.mergeShapesAbove,
+			curveSteps: options.curveSteps, curveSides: options.curveSides, curveTolerance: options.curveTolerance,
+		} );
+
+		const { group, environment, warnings, triangleCount, placementCount, skippedForBudget, meshCount, parseMs, buildMs, fitNote } = built;
+		this.lastUSDStats = { parseMs, buildMs, loaderMs: performance.now() - start, triangleCount, placementCount, skippedForBudget, meshCount, fitNote };
+		if ( fitNote || skippedForBudget > 0 ) this.loader._issues?.record(
+			ISSUE_CODES.SCENE_MEMORY_BUDGET,
+			fitNote ?? `${skippedForBudget.toLocaleString()} placements past the scene budgets left out`,
+			{ triangleCount, placementCount, skippedForBudget },
+			ISSUE_SEVERITY.WARNING
+		);
+		if ( warnings.length ) {
+
+			console.warn( `USD loader: ${warnings.length} warning(s) loading "${entryPath}"` );
+			warnings.forEach( w => console.warn( '  •', w ) );
+
+		}
+
+		if ( environment?.texture ) {
+
+			environment.texture.generateMipmaps = true;
+			this.loader.applyEnvironmentToScene( environment.texture );
+
+		}
+
+		group.name = entryPath.split( '/' ).pop();
+		this.loader.releaseTargetModel();
+		this.loader.targetModel = group;
+		this.loader.animations = [];
+		// Without a dome light the current environment stays: USD assets are usually lit by whatever views them.
+		this.loader.sceneMetadata = environment?.texture ? { environment: { rotation: environment.rotation, intensity: environment.intensity } } : null;
+
+		updateLoading( { isLoading: true, status: 'Processing USD geometry...', progress: 10 } );
+		await this.loader.onModelLoad( group );
+		this.loader.dispatchEvent( { type: 'load', model: group, filename: `${entryPath} (from ${filename})` } );
+		return group;
+
+	}
+
+	/** Asks which parts of a large USD scene to load. @private */
+	async _requireUSDPartChoice( filename, files, entryPath, listing, promptBytes = USD_ELEMENT_PROMPT_BYTES ) {
+
+		const layerBytes = listing.reduce( ( n, e ) => n + ( USD_LAYER.test( e.path ) ? e.size : 0 ), 0 );
+		if ( layerBytes < promptBytes ) return;
+
+		const stage = new USDStage( files );
+		await stage.open( entryPath );
+		const elements = await listUSDParts( stage, listing );
+		if ( elements.length < 2 ) return;
+
+		const totalBytes = listing.reduce( ( n, e ) => n + e.size, 0 );
+		const error = new Error(
+			`"${filename}" holds ${( layerBytes / 1e9 ).toFixed( 1 )} GB of USD across ${elements.length} parts. ` +
+			'Choose which to load — loading all of them at once may exhaust memory.'
+		);
+		error.code = 'ARCHIVE_NEEDS_ELEMENT';
+		error.root = entryPath.includes( '/' ) ? entryPath.slice( 0, entryPath.lastIndexOf( '/' ) ) : '';
+		error.elements = elements;
+		error.totalBytes = totalBytes;
+		this.loader._issues?.record(
+			ISSUE_CODES.ASSET_ARCHIVE_TOO_LARGE,
+			`USD scene holds ${( layerBytes / 1e9 ).toFixed( 1 )} GB of layers across ${elements.length} parts; choose which to load`,
+			{ root: error.root, elements: elements.map( e => e.prefix ), totalBytes },
+			ISSUE_SEVERITY.WARNING
+		);
+		throw error;
+
+	}
+
 	/**
 	 * Decodes a pbrt texture map from raw bytes, picking a decoder by extension.
 	 * ImageBitmap can't handle EXR/HDR/TGA, which pbrt scenes use freely.
@@ -891,24 +1007,29 @@ export class ArchiveImporter {
 
 	}
 
-	async findAndLoadModelFromZip( zip, filename = 'the ZIP archive' ) {
+	/** The model an archive or folder loads as: a conventional main file, else the shallowest, glTF first. @private */
+	_mainModelPath( paths ) {
 
-		const paths = Object.keys( zip );
 		const top = paths[ 0 ]?.split( '/' )[ 0 ];
 		const root = top !== undefined && paths.every( p => p.startsWith( top + '/' ) ) ? top + '/' : '';
 		const models = paths.filter( p => p.split( '.' ).pop().toLowerCase() === 'obj' || this.loader.getFileFormat( p )?.type === 'model' );
-		if ( models.length === 0 ) throw new Error( `No supported model files found in ${filename}` );
-
-		// Shallowest first, glTF before other formats at the same depth.
+		if ( models.length === 0 ) return null;
 		const rank = p => p.split( '/' ).length * 2 + ( /\.(gltf|glb)$/i.test( p ) ? 0 : 1 );
-		const main = MAIN_MODEL_FILES.map( name => root + name ).find( p => zip[ p ] );
+		const have = new Set( paths );
+		const main = MAIN_MODEL_FILES.map( name => root + name ).find( p => have.has( p ) );
 		const path = main ?? models.reduce( ( best, p ) => ( rank( p ) < rank( best ) ? p : best ) );
+		return { path, models, main: !! main, usd: ! main && USD_LAYER.test( path ) };
+
+	}
 
-		// A loose layer is only one slice of a USD scene — hand the whole
-		// archive over so its references and payloads can resolve.
-		if ( ! main && USD_LAYER_RE.test( path ) ) return await this.loadUSDHierarchyFromZip( zip );
+	async findAndLoadModelFromZip( zip, filename = 'the ZIP archive' ) {
+
+		const found = this._mainModelPath( Object.keys( zip ) );
+		if ( ! found ) throw new Error( `No supported model files found in ${filename}` );
+		if ( found.usd ) return await this.loadUSDScene( zip, filename );
 
-		const others = models.filter( p => p !== path && ! USD_LAYER_RE.test( p ) );
+		const { path, models } = found;
+		const others = models.filter( p => p !== path && ! USD_LAYER.test( p ) );
 		if ( others.length > 0 ) {
 
 			console.warn( `${filename} holds ${others.length + 1} models; loaded "${path}". Others: ${others.join( ', ' )}` );
@@ -926,48 +1047,6 @@ export class ArchiveImporter {
 
 	}
 
-	// USDLoader only builds a cross-layer asset map on its USDZ branch, so repack
-	// the archive as USDZ — root layer first, per AOUSD core spec 16.4.1.2 — and
-	// let the loader resolve the references/payloads itself.
-	async loadUSDHierarchyFromZip( zip ) {
-
-		const layers = Object.keys( zip ).filter( name => USD_LAYER_RE.test( name ) );
-		if ( layers.length === 0 ) throw new Error( 'No USD layers found in the ZIP archive' );
-
-		const root = ArchiveImporter._pickUSDRootLayer( layers );
-		console.log( `Loading USD scene from ZIP: ${root} (${layers.length} layers)` );
-
-		const packed = { [ root ]: [ await bytesOf( zip[ root ] ), { level: 0 } ] };
-		for ( const name of Object.keys( zip ) ) {
-
-			if ( name === root ) continue;
-			if ( USD_LAYER_RE.test( name ) || USD_IMAGE_RE.test( name ) ) packed[ name ] = [ await bytesOf( zip[ name ] ), { level: 0 } ];
-
-		}
-
-		return await this.loader._loadModelFileByExtension( new File( [ zipSync( packed ) ], root ), root );
-
-	}
-
-	// Shallowest layer wins; among ties prefer the <dir>/<dir>.usd convention so a
-	// set's entry point beats its sibling variants.
-	static _pickUSDRootLayer( layers ) {
-
-		const depth = name => name.split( '/' ).length;
-		const minDepth = Math.min( ...layers.map( depth ) );
-		const candidates = layers.filter( name => depth( name ) === minDepth );
-
-		const conventional = candidates.find( name => {
-
-			const parts = name.split( '/' );
-			return parts.length > 1 && parts[ parts.length - 1 ].replace( USD_LAYER_RE, '' ) === parts[ parts.length - 2 ];
-
-		} );
-
-		return conventional || candidates[ 0 ];
-
-	}
-
 	async loadModelFromZipEntry( fileContent, filePath, extension, zipContents, from = 'ZIP' ) {
 
 		try {

package/src/Processor/ArchiveReader.js

@@ -656,44 +656,41 @@ export async function readTar( source, options = {} ) {
 /**
  * Retain-predicate for one or several subtrees of a scene archive.
  *
- * Keeps each chosen element plus everything above it — the top-level scene file, the shared
- * material library, and any `textures` folder hanging off an ancestor — so the entry .pbrt
- * still parses with its siblings absent. An Include pointing at a subtree that was left out
- * only warns, which is what makes a partial load work at all.
+ * Leaves out only the chosen elements' siblings (a `textures` folder excepted) and keeps everything else: the scene
+ * file, a material library beside it (pbrt) or in a directory of its own (USD), textures. An Include or reference
+ * pointing at a subtree that was left out only warns, which is what makes a partial load work at all.
  *
  * @param {string|string[]} prefixes - one element path, or several to load together
  */
 export function elementFilter( prefixes ) {
 
-	const wanted = ( Array.isArray( prefixes ) ? prefixes : [ prefixes ] )
-		.filter( Boolean )
-		.map( prefix => {
+	const chosen = ( Array.isArray( prefixes ) ? prefixes : [ prefixes ] ).filter( Boolean ).map( normalizeTarPath );
+	if ( chosen.length === 0 ) return () => true;
 
-			const p = normalizeTarPath( prefix );
-			return { p, inside: p + '/' };
+	const siblings = new Map();
+	for ( const p of chosen ) {
 
-		} );
+		const cut = p.lastIndexOf( '/' );
+		const parent = cut < 0 ? '' : p.slice( 0, cut + 1 );
+		if ( ! siblings.has( parent ) ) siblings.set( parent, new Set() );
+		siblings.get( parent ).add( p.slice( cut + 1 ) );
 
-	if ( wanted.length === 0 ) return () => true;
+	}
 
 	return path => {
 
-		const cut = path.lastIndexOf( '/' );
-		const dir = cut < 0 ? '' : path.slice( 0, cut );
-		if ( dir === '' ) return true;
-
-		const tex = dir.lastIndexOf( '/textures' );
-		const texRoot = tex >= 0 && tex === dir.length - 9 ? dir.slice( 0, tex ) + '/' : null;
-
-		for ( const { p, inside } of wanted ) {
+		for ( const [ parent, names ] of siblings ) {
 
-			if ( path === p || path.startsWith( inside ) ) return true;
-			if ( inside.startsWith( dir + '/' ) ) return true;
-			if ( texRoot !== null && inside.startsWith( texRoot ) ) return true;
+			if ( ! path.startsWith( parent ) ) continue;
+			const rest = path.slice( parent.length );
+			const slash = rest.indexOf( '/' );
+			if ( slash < 0 ) continue;
+			const name = rest.slice( 0, slash );
+			if ( ! names.has( name ) && name !== 'textures' ) return false;
 
 		}
 
-		return false;
+		return true;
 
 	};
 

package/src/Processor/AssetLoader.js

@@ -18,6 +18,9 @@ import { decodersOnDemand } from './GLTFDecoders.js';
 import { extractSceneMetadata } from './SceneMetadata.js';
 import { ISSUE_CODES } from '../EngineIssues.js';
 import { ENGINE_DEFAULTS } from '../EngineDefaults.js';
+import { createLogger } from '../utils/Logger.js';
+
+const log = createLogger( 'assets' );
 
 // Define supported file formats
 // What the core reads itself; every other format is registered (registerFormat) or comes with an add-on.
@@ -534,7 +537,9 @@ export class AssetLoader extends EventDispatcher {
 	async loadModelFromFile( file, filename ) {
 
 		const key = this.storage ? this._keyed( 'file', identityKey( await fileIdentity( file ) ) ) : null;
-		const result = await this._loadModelFileByExtension( file, filename );
+		// three's USDLoader misreads crate files from 0.8.0 on; a .usdz package stays with it.
+		const usd = /\.(usd|usda|usdc)$/i.test( filename ) ? await this._archiveImporter() : null;
+		const result = usd ? await usd.loadUSDScene( { [ filename ]: file }, filename ) : await this._loadModelFileByExtension( file, filename );
 		this._sourceKey = key;
 		return result;
 
@@ -739,6 +744,7 @@ export class AssetLoader extends EventDispatcher {
 
 		this._downloadComplete( "Processing Environment...", 62 );
 
+		if ( this.maxEnvironmentWidth ) limitEnvironmentWidth( texture, this.maxEnvironmentWidth );
 		texture.mapping = EquirectangularReflectionMapping;
 		texture.minFilter = LinearFilter;
 		texture.magFilter = LinearFilter;
@@ -1375,3 +1381,44 @@ export class AssetLoader extends EventDispatcher {
 
 }
 
+/**
+ * Shrinks a float environment wider than `maxWidth` by a whole factor, each texel the mean of the block it covers, so
+ * the sky keeps its light. In place, then the buffer is cut to size: Moana's 14K sky is 1.6 GB as RGBA floats.
+ */
+export function limitEnvironmentWidth( texture, maxWidth ) {
+
+	const { data, width, height } = texture.image ?? {};
+	if ( ! ( data instanceof Float32Array ) || width <= maxWidth || data.length !== width * height * 4 ) return;
+
+	const f = Math.ceil( width / maxWidth );
+	const w = Math.ceil( width / f ), h = Math.ceil( height / f );
+	for ( let y = 0; y < h; y ++ ) {
+
+		const y1 = Math.min( height, ( y + 1 ) * f );
+		for ( let x = 0; x < w; x ++ ) {
+
+			const x1 = Math.min( width, ( x + 1 ) * f );
+			let r = 0, g = 0, b = 0, a = 0, n = 0;
+			for ( let sy = y * f; sy < y1; sy ++ ) for ( let sx = x * f; sx < x1; sx ++ ) {
+
+				const i = ( sy * width + sx ) * 4;
+				r += data[ i ]; g += data[ i + 1 ]; b += data[ i + 2 ]; a += data[ i + 3 ];
+				n ++;
+
+			}
+
+			// Never past an unread texel: this block's first is at ( y·f·width + x·f )·4 ≥ the write.
+			const o = ( y * w + x ) * 4;
+			data[ o ] = r / n; data[ o + 1 ] = g / n; data[ o + 2 ] = b / n; data[ o + 3 ] = a / n;
+
+		}
+
+	}
+
+	const bytes = w * h * 16;
+	const whole = data.byteOffset === 0 && data.byteLength === data.buffer.byteLength && data.buffer.transfer;
+	texture.image = { data: whole ? new Float32Array( data.buffer.transfer( bytes ) ) : data.slice( 0, w * h * 4 ), width: w, height: h };
+	texture.needsUpdate = true;
+	log.info( `environment ${width}×${height} shrunk to ${w}×${h} (memory spill)` );
+
+}