rayzee 7.26.0 → 7.26.2

package/package.json

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

package/src/PathTracerApp.js

@@ -57,6 +57,8 @@ const _appsByCanvas = new WeakMap();
  * - `app.settings`           — {@link RenderSettings} (all render parameters)
  * - `app.stages`             — Named pipeline stages for advanced control
  * - `app.sceneMeshes`        — meshes backing the BVH, in buffer order (see {@link refitBVH})
+ * - `app.sceneModel`         — root of the rendered model (a copy, for {@link loadObject3D})
+ * - `app.getSceneObject(id)` — the rendered root for an appended object's id
  *
  * Extends EventDispatcher for event-driven communication with stores/UI.
  */
@@ -626,8 +628,6 @@ export class PathTracerApp extends EventDispatcher {
 		this.interactionManager?.deselect();
 		this.transformManager?.detach?.();
 
-		// Release the loaded model. If loaded via loadObject3D(), the caller owns it —
-		// we only detach it from the scene. Otherwise dispose geometries/materials/textures.
 		this.assetLoader?.releaseTargetModel();
 
 		// Clear lights in the WebGPU light scene
@@ -665,7 +665,13 @@ export class PathTracerApp extends EventDispatcher {
 	/**
 	 * Loads a Three.js Object3D directly into the path tracer scene.
 	 * Builds BVH from the object's meshes and uploads scene data.
-	 * @param {import('three').Object3D} object3d - The Object3D to render
+	 *
+	 * Renders a copy: `object3d` is never reparented, rewritten or disposed, so passing a
+	 * subtree of a scene the host still renders is safe. Geometry/material/texture are shared
+	 * by reference, and any ancestor transform is baked in. Later edits to `object3d` do not
+	 * reach the render — mutate {@link sceneModel}, then {@link refitBVH}/{@link refitBLASes}.
+	 *
+	 * @param {import('three').Object3D} object3d - The Object3D to render; left untouched.
 	 * @param {string} [name='object3d'] - Display name for the object
 	 */
 	async loadObject3D( object3d, name = 'object3d' ) {
@@ -1134,10 +1140,9 @@ export class PathTracerApp extends EventDispatcher {
 	/** Tag the primary (replace-loaded) model as a removable scene object (read by the Outliner + removeSceneObject). Idempotent. */
 	_tagPrimarySceneObject() {
 
-		const m = this.assetLoader?.targetModel;
+		const m = this.sceneModel;
 		if ( ! m ) return;
 		m.userData.__rayzeeSceneObject = true;
-		m.userData.__rayzeeExternal = ( m === this.assetLoader._externalModel );
 
 	}
 
@@ -1147,12 +1152,12 @@ export class PathTracerApp extends EventDispatcher {
 		const scene = this.meshScene;
 		if ( ! scene ) return;
 		const floor = this.assetLoader?.floorPlane;
-		const primary = this.assetLoader?.targetModel;
+		const primary = this.sceneModel;
 		for ( const child of [ ...scene.children ] ) {
 
 			if ( child === floor || child === primary ) continue;
 			if ( ! child.userData?.__rayzeeSceneObject ) continue;
-			this.assetLoader.removeModelRoot( child, { external: !! child.userData.__rayzeeExternal } );
+			this.assetLoader.removeModelRoot( child );
 
 		}
 
@@ -1191,7 +1196,6 @@ export class PathTracerApp extends EventDispatcher {
 
 			const { root } = await this.assetLoader.appendModel( url );
 			root.userData.__rayzeeSceneObject = true;
-			root.userData.__rayzeeExternal = false;
 			if ( name ) root.userData.__rayzeeName = name;
 			await this._finishRebuildNoReframe( { type: 'ModelAdded', url, id: root.uuid } );
 			return root.uuid;
@@ -1207,7 +1211,7 @@ export class PathTracerApp extends EventDispatcher {
 
 	/**
 	 * Append a caller-owned Object3D to the current scene, then rebuild (no reframe).
-	 * The caller retains ownership — removal only detaches it.
+	 * Appends a copy; the object passed in is never mutated. Same rules as {@link loadObject3D}.
 	 * @param {import('three').Object3D} object3d
 	 * @param {Object} [opts]
 	 * @param {string} [opts.name]
@@ -1227,7 +1231,6 @@ export class PathTracerApp extends EventDispatcher {
 
 			const { root } = this.assetLoader.appendObject3D( object3d, name || 'object3d' );
 			root.userData.__rayzeeSceneObject = true;
-			root.userData.__rayzeeExternal = true;
 			if ( name ) root.userData.__rayzeeName = name;
 			await this._finishRebuildNoReframe( { type: 'ModelAdded', id: root.uuid } );
 			return root.uuid;
@@ -1254,7 +1257,7 @@ export class PathTracerApp extends EventDispatcher {
 		const floor = this.assetLoader?.floorPlane;
 		if ( floor && floor.uuid === id ) return false; // Ground is not deletable
 
-		const root = scene.children.find( c => c.uuid === id && c.userData?.__rayzeeSceneObject );
+		const root = this.getSceneObject( id );
 		if ( ! root ) return false;
 
 		if ( this._loadingInProgress ) {
@@ -1269,13 +1272,13 @@ export class PathTracerApp extends EventDispatcher {
 			this.interactionManager?.deselect();
 			this.transformManager?.detach?.();
 
-			if ( root === this.assetLoader.targetModel ) {
+			if ( root === this.sceneModel ) {
 
 				this.assetLoader.releaseTargetModel();
 
 			} else {
 
-				this.assetLoader.removeModelRoot( root, { external: !! root.userData.__rayzeeExternal } );
+				this.assetLoader.removeModelRoot( root );
 
 			}
 
@@ -1378,6 +1381,32 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Root of the model actually being rendered. For {@link loadObject3D} this is the engine's
+	 * copy, not the object you passed — mutate this one, then {@link refitBVH}/{@link refitBLASes}.
+	 *
+	 * @returns {import('three').Object3D|null} Live reference, or null when nothing is loaded.
+	 */
+	get sceneModel() {
+
+		return this.assetLoader?.targetModel ?? null;
+
+	}
+
+	/**
+	 * Resolve an id from {@link addModel}/{@link addModelFromObject3D} to the root being
+	 * rendered for it — for an appended Object3D, the engine's copy.
+	 *
+	 * @param {string} id
+	 * @returns {import('three').Object3D|null} Live reference, or null if no such object.
+	 */
+	getSceneObject( id ) {
+
+		const root = this.meshScene?.children.find( c => c.uuid === id );
+		return root?.userData?.__rayzeeSceneObject ? root : null;
+
+	}
+
 	/**
 	 * Update vertex positions for animation without full BVH rebuild.
 	 * O(N) bottom-up AABB refit instead of O(N log N) SAH rebuild.
@@ -2839,7 +2868,7 @@ export class PathTracerApp extends EventDispatcher {
 		const animations = this.assetLoader?.animations || [];
 		if ( animations.length > 0 ) {
 
-			const mixerRoot = this.assetLoader?.targetModel || this.meshScene;
+			const mixerRoot = this.sceneModel || this.meshScene;
 			this.animationManager.init( this.meshScene, mixerRoot, this._sdf.meshes, animations );
 			this.animationManager.onFinished = () => {
 

package/src/Processor/AssetLoader.js

@@ -1,4 +1,4 @@
-import { Box3, Vector3, RectAreaLight, Color, FloatType, LinearFilter, EquirectangularReflectionMapping,
+import { Box3, BufferGeometry, Vector3, RectAreaLight, Color, FloatType, LinearFilter, EquirectangularReflectionMapping,
 	TextureLoader, Texture, SRGBColorSpace, RepeatWrapping, Mesh, MeshStandardMaterial, MeshPhysicalMaterial,
 	CircleGeometry, Points, PointsMaterial, LoadingManager, EventDispatcher
 } from 'three';
@@ -8,9 +8,10 @@ import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
 import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
 import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
 import { createMeshesFromMultiMaterialMesh } from 'three/addons/utils/SceneUtils.js';
+import { clone as cloneWithSkeletons } from 'three/addons/utils/SkeletonUtils.js';
 import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
 import { unzipSync, zipSync, strFromU8 } from 'three/addons/libs/fflate.module.js';
-import { disposeObjectFromMemory, updateLoading } from './utils';
+import { disposeEngineOwnedResources, disposeObjectFromMemory, updateLoading } from './utils';
 import { BuildTimer } from './BuildTimer.js';
 import { getAssetConfig } from '../AssetConfig.js';
 import { loadPBRTScene, pickEntryPath } from './PBRT/index.js';
@@ -36,6 +37,18 @@ const SUPPORTED_FORMATS = {
 // layers and the image assets they reference.
 const USD_LAYER_RE = /\.(usd|usda|usdc)$/i;
 const USD_IMAGE_RE = /\.(png|jpg|jpeg|avif)$/i;
+// A throwaway stand-in for a geometry the engine must not mutate: the split's mergeGroups()
+// reorders and disposes what it is given, but never writes the attributes.
+function standInForSplit( source ) {
+
+	const geometry = new BufferGeometry();
+	for ( const name in source.attributes ) geometry.setAttribute( name, source.attributes[ name ] );
+	if ( source.index ) geometry.setIndex( source.index );
+	for ( const group of source.groups ) geometry.addGroup( group.start, group.count, group.materialIndex );
+	return geometry;
+
+}
+
 /**
  * AssetLoader class - handles loading of 3D models, environment maps, and archives
  */
@@ -48,7 +61,6 @@ export class AssetLoader extends EventDispatcher {
 		this.camera = camera;
 		this.controls = controls;
 		this.targetModel = null;
-		this._externalModel = null;
 		this.floorPlane = null;
 		this.sceneScale = 1.0;
 		this.loaderCache = {};
@@ -132,29 +144,58 @@ export class AssetLoader extends EventDispatcher {
 	}
 
 	/**
-	 * Releases the current targetModel. If it was supplied by the caller via
-	 * loadObject3D(), we only detach it from its parent — the caller still owns
-	 * that Object3D and may reuse it. Otherwise we disposeObjectFromMemory() to
-	 * free geometry/material/texture GPU resources.
+	 * Deep-clones a caller-owned Object3D so the engine never mutates the host's tree.
+	 * Geometry/material/texture ride along by reference, so release frees only what the engine
+	 * allocated — see removeModelRoot().
+	 *
+	 * @param {import('three').Object3D} object3d - the caller's object; left untouched.
+	 * @returns {import('three').Object3D} the engine-owned copy.
 	 */
-	releaseTargetModel() {
+	_adoptExternalObject( object3d ) {
 
-		this.sceneMetadata = null;
+		// Not Object3D.clone(): that leaves SkinnedMeshes bound to the source's bones.
+		let model;
+		try {
 
-		if ( ! this.targetModel ) return;
+			model = cloneWithSkeletons( object3d );
 
-		if ( this.targetModel === this._externalModel ) {
+		} catch ( error ) {
 
-			this.targetModel.parent?.remove( this.targetModel );
+			// Object3D.copy() round-trips userData through JSON, so a back-reference throws.
+			throw new Error(
+				`Cannot render "${object3d.name || object3d.type}": its userData must be JSON-serializable.`,
+				{ cause: error }
+			);
 
-		} else {
+		}
 
-			disposeObjectFromMemory( this.targetModel );
+		model.userData.__rayzeeExternal = true;
+
+		// Carried through as the scene-object id, unless a second copy already took it.
+		if ( ! this.scene?.children.some( c => c.uuid === object3d.uuid ) ) model.uuid = object3d.uuid;
+
+		// The copy sits under the engine's identity root, which keeps only a local transform.
+		if ( object3d.parent ) {
+
+			object3d.parent.updateWorldMatrix( true, false );
+			model.applyMatrix4( object3d.parent.matrixWorld );
 
 		}
 
+		return model;
+
+	}
+
+	/** Releases the current targetModel. See removeModelRoot() for what gets freed. */
+	releaseTargetModel() {
+
+		this.sceneMetadata = null;
+
+		if ( ! this.targetModel ) return;
+
+		this.removeModelRoot( this.targetModel );
+
 		this.targetModel = null;
-		this._externalModel = null;
 		// Drop the released model's animation clips so a later rebuild doesn't rebind
 		// a mixer to disposed nodes. Every load path re-populates this.animations after.
 		this.animations = [];
@@ -1180,21 +1221,32 @@ export class AssetLoader extends EventDispatcher {
 
 	}
 
-	// Append a caller-owned Object3D without releasing prior models or reframing.
+	// Append a copy of a caller-owned Object3D without releasing prior models or reframing.
 	appendObject3D( object3d, name = 'object3d' ) {
 
-		object3d.name = object3d.name || name;
-		this._processAndParent( object3d );
-		return { root: object3d };
+		const root = this._adoptExternalObject( object3d );
+		root.name = object3d.name || name;
+		this._processAndParent( root );
+		return { root };
 
 	}
 
-	// Detach + dispose an appended root. External (caller-owned) roots are only detached.
-	removeModelRoot( root, { external = false } = {} ) {
+	// Detach + dispose a model root. An adopted root's geometry/materials belong to the
+	// caller, so only the engine's own allocations go.
+	removeModelRoot( root ) {
 
 		if ( ! root ) return;
-		if ( external ) root.parent?.remove( root );
-		else disposeObjectFromMemory( root );
+
+		if ( root.userData.__rayzeeExternal ) {
+
+			disposeEngineOwnedResources( root );
+			root.parent?.remove( root );
+
+		} else {
+
+			disposeObjectFromMemory( root );
+
+		}
 
 	}
 
@@ -1510,17 +1562,18 @@ export class AssetLoader extends EventDispatcher {
 
 	async loadObject3D( object3d, name = 'object3d' ) {
 
-		object3d.name = object3d.name || name;
-
 		this.releaseTargetModel();
-		this.targetModel = object3d;
-		this._externalModel = object3d;
+
+		const model = this._adoptExternalObject( object3d );
+		model.name = object3d.name || name;
+
+		this.targetModel = model;
 
 		updateLoading( { isLoading: true, status: "Processing Data...", progress: 10 } );
 		await this.onModelLoad( this.targetModel );
 
-		this.dispatchEvent( { type: 'load', model: object3d, filename: name } );
-		return object3d;
+		this.dispatchEvent( { type: 'load', model, filename: name } );
+		return model;
 
 	}
 
@@ -1656,6 +1709,9 @@ export class AssetLoader extends EventDispatcher {
 	processModelObjects( model ) {
 
 		let visitedAreaLights = [];
+		// Split after the walk: traverse() caches children.length, so splitting in place
+		// shifts later siblings down a slot and skips one.
+		const multiMaterialMeshes = [];
 		model.traverse( ( object ) => {
 
 			const userData = object.userData;
@@ -1709,19 +1765,29 @@ export class AssetLoader extends EventDispatcher {
 			// Handle multi-material meshes
 			if ( object.isMesh && Array.isArray( object.material ) ) {
 
-				console.log( 'Found multi-material mesh:', object.name );
-				const group = createMeshesFromMultiMaterialMesh( object );
+				multiMaterialMeshes.push( object );
 
-				if ( object.parent ) {
+			}
 
-					object.parent.add( group );
-					object.parent.remove( object );
+		} );
 
-				}
+		const shared = model.userData.__rayzeeExternal === true;
 
-			}
+		for ( const object of multiMaterialMeshes ) {
 
-		} );
+			if ( ! object.parent ) continue;
+
+			console.log( 'Found multi-material mesh:', object.name );
+			if ( shared ) object.geometry = standInForSplit( object.geometry );
+
+			const group = createMeshesFromMultiMaterialMesh( object );
+			// Fresh geometry per group; tag it so an adopted model's release can free it.
+			for ( const child of group.children ) child.geometry.userData.__rayzeeOwned = true;
+
+			object.parent.add( group );
+			object.parent.remove( object );
+
+		}
 
 	}
 

package/src/Processor/GeometryExtractor.js

@@ -183,29 +183,6 @@ export class GeometryExtractor {
 			materialIndex = this.materials.length - 1;
 			this._materialUuidMap.set( material.uuid, materialIndex );
 
-			// Detect material features for shader optimization (strict > 0 check)
-			if ( newMaterial.clearcoat > 0 ) this.sceneFeatures.hasClearcoat = true;
-			if ( newMaterial.transmission > 0 ) this.sceneFeatures.hasTransmission = true;
-			if ( newMaterial.dispersion > 0 ) this.sceneFeatures.hasDispersion = true;
-			if ( newMaterial.iridescence > 0 ) this.sceneFeatures.hasIridescence = true;
-			if ( newMaterial.sheen > 0 ) this.sceneFeatures.hasSheen = true;
-			if ( newMaterial.transparent || newMaterial.opacity < 1.0 || newMaterial.alphaTest > 0 ) this.sceneFeatures.hasTransparency = true;
-			if ( newMaterial.subsurface > 0 ) this.sceneFeatures.hasSubsurface = true;
-
-			// Detect multi-lobe materials (require multi-lobe MIS for optimal sampling)
-			const featureCount = [
-				newMaterial.clearcoat > 0,
-				newMaterial.transmission > 0,
-				newMaterial.iridescence > 0,
-				newMaterial.sheen > 0
-			].filter( Boolean ).length;
-
-			if ( featureCount >= 2 ) {
-
-				this.sceneFeatures.hasMultiLobeMaterials = true;
-
-			}
-
 		}
 
 		return materialIndex;
@@ -846,19 +823,6 @@ export class GeometryExtractor {
 		this._materialUuidMap = new Map();
 		this._textureIndexCache = new WeakMap();
 
-		// Reset scene-wide feature detection flags
-		this.sceneFeatures = {
-			hasClearcoat: false,
-			hasTransmission: false,
-			hasDispersion: false,
-			hasIridescence: false,
-			hasSheen: false,
-			hasTransparency: false,
-			hasSubsurface: false,
-			hasMultiLobeMaterials: false, // Materials with 2+ BRDF lobes
-			hasMRTOutputs: true // Always enabled for ASVGF/adaptive sampling support
-		};
-
 	}
 
 	getExtractedData() {
@@ -888,8 +852,7 @@ export class GeometryExtractor {
 			specularIntensityMaps: this.specularIntensityMaps,
 			specularColorMaps: this.specularColorMaps,
 			directionalLights: this.directionalLights,
-			cameras: this.cameras,
-			sceneFeatures: this.sceneFeatures // Scene-wide material feature flags
+			cameras: this.cameras
 		};
 
 	}

package/src/Processor/SceneProcessor.js

@@ -324,7 +324,6 @@ export class SceneProcessor {
 
 			// Store other extracted data
 			this.materials = extractedData.materials;
-			this.materialCount = this.materials.length; // Store material count for feature scanning
 			this.materialTriangleCounts = extractedData.materialTriangleCounts; // Per-material tri count for sort-bin remap
 			this.meshes = extractedData.meshes;
 			this.meshTriangleRanges = extractedData.meshTriangleRanges; // Per-mesh { start, count } for TLAS/BLAS
@@ -347,7 +346,6 @@ export class SceneProcessor {
 			this.specularColorMaps = extractedData.specularColorMaps;
 			this.directionalLights = extractedData.directionalLights;
 			this.cameras = extractedData.cameras;
-			this.sceneFeatures = extractedData.sceneFeatures; // Store material feature flags for shader optimization
 
 			const duration = performance.now() - startTime;
 			this._log( `Geometry extraction complete (${duration.toFixed( 2 )}ms)`, {
@@ -1157,7 +1155,6 @@ export class SceneProcessor {
 
 			// Update material arrays (but keep existing triangle data)
 			this.materials = extractedData.materials;
-			this.materialCount = this.materials.length; // Update material count
 			this.meshes = extractedData.meshes; // Update mesh data
 			this.maps = extractedData.maps;
 			this.normalMaps = extractedData.normalMaps;
@@ -1166,7 +1163,6 @@ export class SceneProcessor {
 			this.metalnessMaps = extractedData.metalnessMaps;
 			this.emissiveMaps = extractedData.emissiveMaps;
 			this.displacementMaps = extractedData.displacementMaps;
-			this.sceneFeatures = extractedData.sceneFeatures; // Update material feature flags
 
 			// Bucket textures, remap material indices, regenerate raw material data, and
 			// build the consolidated bucket arrays — same path as the initial build.

package/src/Processor/utils.js

@@ -177,6 +177,17 @@ export function disposeObjectFromMemory( object, exeptions = [] ) {
 
 }
 
+/** Frees only geometry the engine allocated inside an adopted model; the rest is the host's. */
+export function disposeEngineOwnedResources( object ) {
+
+	object?.traverse( ( child ) => {
+
+		if ( child.geometry?.userData?.__rayzeeOwned ) child.geometry.dispose();
+
+	} );
+
+}
+
 
 
 /**

package/src/Stages/PathTracerStage.js

@@ -453,9 +453,6 @@ export class PathTracerStage extends RenderStage {
 		await this.sdfs.buildBVH( scene );
 		this.cameras = this.sdfs.cameras;
 
-		// Inject shader defines based on detected material features
-		this.materialData.injectMaterialFeatureDefines();
-
 		// Update uniforms with scene data
 		this.updateSceneUniforms();
 		this.updateLights();