@needle-tools/engine 4.11.5 → 4.12.0-beta.1

package/src/engine-components/RendererInstancing.ts

@@ -29,8 +29,9 @@ export class InstancingHandler {
      * (The instancing mesh renderer will grow x2 if the max instance count is reached)
      * @default 4
      * @returns The initial instance count
-     * */
-    static getStartInstanceCount = (_obj: Object3D) => {
+     */
+    // @ts-ignore (ignore the unused parameter warning)
+    static getStartInstanceCount = (obj: Object3D) => {
         return 4;
     };
 
@@ -45,20 +46,24 @@ export class InstancingHandler {
         if (res) {
             if (handlesArray === null) handlesArray = [];
             handlesArray.push(res);
-            // load texture lods
-            NEEDLE_progressive.assignTextureLOD(res.renderer.material, 0);
-
-            // Load mesh lods
-            // TODO: technically for multi meshes we do this work multiple times (we search for meshes in children and then use the renderer sharedMeshes... that doesnt make sense)
-            for (let i = 0; i < renderer.sharedMeshes.length; i++) {
-                const mesh = renderer.sharedMeshes[i];
-                const geometry = mesh.geometry;
-                NEEDLE_progressive.assignMeshLOD(mesh, 0).then(lod => {
-                    if (lod && renderer.activeAndEnabled && geometry != lod) {
-                        res.setGeometry(lod);
-                    }
-                });
+
+            // Load LOD for textures
+            const mat = res.object.material;
+            if(Array.isArray(mat)) {
+                mat.forEach(m => NEEDLE_progressive.assignTextureLOD(m, 0));
+            }
+            else {
+                NEEDLE_progressive.assignTextureLOD(mat, 0);
             }
+
+            // Load LOD for geometry
+            const mesh = res.object;
+            const geometry = mesh.geometry;
+            NEEDLE_progressive.assignMeshLOD(mesh, 0).then(lod => {
+                if (lod && geometry != lod) {
+                    res.setGeometry(lod);
+                }
+            });
         }
 
         else if (level <= 0 && obj.type !== "Mesh") {
@@ -349,7 +354,7 @@ class InstancedMeshRenderer {
     private _context: Context;
     private _batchedMesh: BatchedMesh;
     private _handles: (InstanceHandle | null)[] = [];
-    private readonly _geometryIds: Map<BufferGeometry, number> = new Map();
+    private _geometryIds = new WeakMap<BufferGeometry, number>();
     private _maxInstanceCount: number;
 
     private _currentInstanceCount = 0;
@@ -439,6 +444,10 @@ class InstancedMeshRenderer {
     private _needUpdateBounds: boolean = false;
     private _debugMaterial: MeshStandardMaterial | null = null;
 
+    private getBatchedMeshName() {
+        return this.name ? `${this.name} (BatchedMesh)` : "BatchedMesh";
+    }
+
     constructor(name: string, geo: BufferGeometry, material: Material, initialMaxCount: number, context: Context) {
         this.name = name;
         this.geometry = geo;
@@ -452,6 +461,7 @@ class InstancedMeshRenderer {
         this._maxVertexCount = estimate.vertexCount;
         this._maxIndexCount = estimate.indexCount;
         this._batchedMesh = new BatchedMesh(this._maxInstanceCount, this._maxVertexCount, this._maxIndexCount, this._debugMaterial ?? this.material);
+        this._batchedMesh.name = this.getBatchedMeshName();
         // this.inst = new InstancedMesh(geo, material, count);
         this._batchedMesh[$instancingAutoUpdateBounds] = true;
         // this.inst.count = 0;
@@ -475,7 +485,7 @@ class InstancedMeshRenderer {
         context.post_render_callbacks.push(this.onAfterRender);
 
         if (debugInstancing) {
-            console.log(`Instanced renderer created with ${this._maxInstanceCount} instances, ${this._maxVertexCount} max vertices and ${this._maxIndexCount} max indices for \"${name}\"`)
+            console.log(`Instanced renderer (${this.name}) created with ${this._maxInstanceCount} instances, ${this._maxVertexCount} max vertices and ${this._maxIndexCount} max indices for \"${name}\"`)
         }
     }
 
@@ -522,7 +532,8 @@ class InstancedMeshRenderer {
             return false;
         }
 
-        if (this.mustGrow(geo)) {
+        const newInstanceCount = this._currentInstanceCount + 1;
+        if (newInstanceCount > this._maxInstanceCount || this.mustGrow(geo)) {
             if (this.allowResize) {
                 this.grow(geo);
             }
@@ -644,34 +655,42 @@ class InstancedMeshRenderer {
     private mustGrow(geo?: BufferGeometry): boolean {
         if (this.count >= this._maxInstanceCount) return true;
         if (!geo || !geo.attributes) return false;
+
+        const isKnownGeometry = this._geometryIds.has(geo);
+        if (isKnownGeometry) return false;
+
         const meshInfo = getMeshInformation(geo);
         const newVertexCount = meshInfo.vertexCount;
         const newIndexCount = meshInfo.indexCount;
         return this._currentVertexCount + newVertexCount > this._maxVertexCount || this._currentIndexCount + newIndexCount > this._maxIndexCount;
     }
 
+    private _growId = 0;
     private grow(geometry: BufferGeometry) {
+        const id = ++this._growId;
         const growFactor = 2;
         const newSize = Math.ceil(this._maxInstanceCount * growFactor);
 
         // create a new BatchedMesh instance
+        // TODO: we should keep track of how many instances for each geometry we have and consider that when estimating new space
         const estimatedSpace = this.tryEstimateVertexCountSize(newSize, [geometry]);// geometry.attributes.position.count;
         // const indices = geometry.index ? geometry.index.count : 0;
         const newMaxVertexCount = Math.max(this._maxVertexCount, estimatedSpace.vertexCount);
-        const newMaxIndexCount = Math.max(this._maxIndexCount, estimatedSpace.indexCount, Math.ceil(this._maxVertexCount * growFactor));
+        const newMaxIndexCount = Math.max(this._maxIndexCount, estimatedSpace.indexCount);//, Math.ceil(this._maxVertexCount * growFactor));
 
         if (debugInstancing) {
             const geometryInfo = getMeshInformation(geometry);
-            console.warn(`[Instancing] Growing Buffer\nMesh: \"${this.name}${geometry.name?.length ? "/" + geometry.name : ""}\"\n${geometryInfo.vertexCount} vertices, ${geometryInfo.indexCount} indices\nMax count ${this._maxInstanceCount} → ${newSize}\nMax vertex count ${this._maxVertexCount} -> ${newMaxVertexCount}\nMax index count ${this._maxIndexCount} -> ${newMaxIndexCount}`);
+            console.warn(`[Instancing] Growing Buffer\nMesh: \"${this.name}${geometry.name?.length ? "/" + geometry.name : ""}\" (${geometryInfo.vertexCount.toLocaleString()} vertices, ${geometryInfo.indexCount.toLocaleString()} indices)\nMax count ${this._maxInstanceCount.toLocaleString()} → ${newSize.toLocaleString()}\nMax vertex count ${this._maxVertexCount.toLocaleString()} -> ${newMaxVertexCount.toLocaleString()}\nMax index count ${this._maxIndexCount.toLocaleString()} -> ${newMaxIndexCount.toLocaleString()}`);
             this._debugMaterial = createDebugMaterial();
         }
         else if (isDevEnvironment()) {
-            console.debug(`[Instancing] Growing Buffer\nMesh: \"${this.name}${geometry.name?.length ? "/" + geometry.name : ""}\"\nMax count ${this._maxInstanceCount} → ${newSize}\nMax vertex count ${this._maxVertexCount} -> ${newMaxVertexCount}\nMax index count ${this._maxIndexCount} -> ${newMaxIndexCount}`);
+            console.debug(`[Instancing] Growing Buffer\nMesh: \"${this.name}${geometry.name?.length ? "/" + geometry.name : ""}\"\nMax count ${this._maxInstanceCount} → ${newSize}\nMax vertex count ${this._maxVertexCount.toLocaleString()} -> ${newMaxVertexCount.toLocaleString()}\nMax index count ${this._maxIndexCount.toLocaleString()} -> ${newMaxIndexCount.toLocaleString()}`);
         }
 
         this._maxVertexCount = newMaxVertexCount;
         this._maxIndexCount = newMaxIndexCount;
         const newInst = new BatchedMesh(newSize, this._maxVertexCount, this._maxIndexCount, this._debugMaterial ?? this.material);
+        newInst.name = this.getBatchedMeshName();
         newInst.layers = this._batchedMesh.layers;
         newInst.castShadow = this._batchedMesh.castShadow;
         newInst.receiveShadow = this._batchedMesh.receiveShadow;
@@ -686,7 +705,7 @@ class InstancedMeshRenderer {
         // dispose the old batched mesh
         this._batchedMesh.dispose();
         this._batchedMesh.removeFromParent();
-        this._geometryIds.clear();
+        this._geometryIds = new WeakMap<BufferGeometry, number>();
 
         this._batchedMesh = newInst;
         this._maxInstanceCount = newSize;
@@ -698,6 +717,11 @@ class InstancedMeshRenderer {
         const original = [...this._handles];
         this._handles = [];
         for (const handle of original) {
+            if (id !== this._growId) {
+                // another grow happened in the meantime
+                if (debugInstancing) console.warn("[Instancing] Aborting grow since another grow happened in the meantime");
+                return;
+            }
             if (handle && handle.__instanceIndex >= 0) {
                 this.addGeometry(handle);
                 this._handles[handle.__instanceIndex] = handle;
@@ -722,23 +746,31 @@ class InstancedMeshRenderer {
                     entry.count += 1;
                 }
 
+                if (_newGeometries && _newGeometries?.length > 0) {
+                    const index = _newGeometries.indexOf(handle.object.geometry as BufferGeometry);
+                    if (index !== -1) {
+                        _newGeometries.splice(index, 1);
+                    }
+                }
             }
         }
 
         // then calculate the total vertex count
         let totalVertices = 0;
         let totalIndices = 0;
+        let totalGeometries = 0;
         // let maxVertices = 0;
         for (const [_geo, data] of usedGeometries) {
-            totalVertices += data.vertexCount * data.count;
-            totalIndices += data.indexCount * data.count;
+            totalGeometries += 1;
+            totalVertices += data.vertexCount;
+            totalIndices += data.indexCount;
             // maxVertices = Math.max(maxVertices, geo.attributes.position.count * count);
         }
         // we calculate the average to make an educated guess of how many vertices will be needed with the new buffer count
-        const averageVerts = Math.ceil(totalVertices / Math.max(1, this._currentInstanceCount));
-        let maxVertexCount = averageVerts * newMaxInstances;
-        const averageIndices = Math.ceil(totalIndices / Math.max(1, this._currentInstanceCount));
-        let maxIndexCount = averageIndices * newMaxInstances * 2;
+        const averageVerts = Math.ceil(totalVertices / Math.max(1, totalGeometries));
+        let maxVertexCount = averageVerts * totalGeometries;
+        const averageIndices = Math.ceil(totalIndices / Math.max(1, totalGeometries));
+        let maxIndexCount = averageIndices * totalGeometries;
 
         // if new geometries are provided we *know* that they will be added
         // so we make sure to include them in the calculation
@@ -753,6 +785,10 @@ class InstancedMeshRenderer {
             }
         }
 
+        if (debugInstancing) {
+            console.log(`[Instancing] Estimated size for new buffer ${this.name}\nGeometries: ${totalGeometries} (New: ${_newGeometries?.length || 0})\nInstances: ${newMaxInstances}\nEstimated Vertices: ${maxVertexCount.toLocaleString()}\nEstimated Indices: ${maxIndexCount.toLocaleString()}`);
+        }
+
         return { vertexCount: maxVertexCount, indexCount: maxIndexCount };
     }
 
@@ -770,16 +806,16 @@ class InstancedMeshRenderer {
         let geometryId = this._geometryIds.get(geo);
         if (geometryId === undefined || geometryId === null) {
             if (debugInstancing)
-                console.debug(`[Instancing] > ADD NEW GEOMETRY \"${handle.name} (${geo.name}; ${geo.uuid})\"\n${this._currentInstanceCount} instances, ${handle.maxVertexCount} max vertices, ${handle.maxIndexCount} max indices`);
+                console.warn(`[Instancing] > ADD NEW GEOMETRY \"${handle.name} (${geo.name}; ${geo.uuid})\"\nCurrent Instances: ${this._currentInstanceCount}\nMax Vertices: ${handle.maxVertexCount.toLocaleString()}\nMax Indices: ${handle.maxIndexCount.toLocaleString()}\nMax Triangles: ${(handle.maxIndexCount / 3).toLocaleString()}`);
 
             geometryId = this._batchedMesh.addGeometry(geo, handle.maxVertexCount, handle.maxIndexCount);
             this._geometryIds.set(geo, geometryId);
+            this._currentVertexCount += handle.maxVertexCount;
+            this._currentIndexCount += handle.maxIndexCount;
         }
         else {
             if (debugInstancing === "verbose") console.log(`[Instancing] > ADD INSTANCE \"${handle.name}\"\nGEOMETRY_ID=${geometryId}\n${this._currentInstanceCount} instances`);
         }
-        this._currentVertexCount += handle.maxVertexCount;
-        this._currentIndexCount += handle.maxIndexCount;
         const i = this._batchedMesh.addInstance(geometryId);
         handle.__geometryIndex = geometryId;
         handle.__instanceIndex = i;
@@ -787,7 +823,7 @@ class InstancedMeshRenderer {
         handle.__reservedIndexRange = handle.maxIndexCount;
         this._batchedMesh.setMatrixAt(i, handle.object.matrixWorld);
         if (debugInstancing)
-            console.debug(`[Instancing] > ADDED INSTANCE \"${handle.name}\"\nGEOMETRY_ID=${geometryId}\n${this._currentInstanceCount} instances\nIndex: ${handle.__instanceIndex}`);
+            console.debug(`[Instancing] > ADDED INSTANCE \"${handle.name}\"\nGEOMETRY_ID=${geometryId}\n${this._currentInstanceCount} instances\nIndex: ${handle.__instanceIndex}\nVertices: ${this._currentVertexCount.toLocaleString()}/${this._maxVertexCount.toLocaleString()},\nIndices: ${this._currentIndexCount.toLocaleString()}/${this._maxIndexCount.toLocaleString()}`);
 
     }
 
@@ -803,7 +839,7 @@ class InstancedMeshRenderer {
         //     this.inst.deleteGeometry(handle.__instanceIndex);
         // else 
         // this._batchedMesh.setVisibleAt(handle.__instanceIndex, false);
-        if(debugInstancing) {
+        if (debugInstancing) {
             console.debug(`[Instancing] < REMOVE INSTANCE \"${handle.name}\" at [${handle.__instanceIndex}]\nGEOMETRY_ID=${handle.__geometryIndex}\n${this._currentInstanceCount} instances\nIndex: ${handle.__instanceIndex}`);
         }
         this._batchedMesh.deleteInstance(handle.__instanceIndex);

package/src/engine-components/RigidBody.ts

@@ -140,6 +140,7 @@ class TransformWatch {
  * - Example: https://samples.needle.tools/physics-playground
  * - Example: https://samples.needle.tools/physics-&-animation
  * 
+ * @summary Rigidbody for physical interactions
  * @category Physics 
  * @group Components
  */

package/src/engine-components/SceneSwitcher.ts

@@ -108,6 +108,7 @@ export interface ISceneEventListener {
  * });
  * ```
  * 
+ * @summary Dynamically loads and switches between multiple scenes
  * @category Asset Management
  * @group Components
  */

package/src/engine-components/ScreenCapture.ts

@@ -70,6 +70,7 @@ export declare type ScreenCaptureOptions = {
  * By default the component will start sharing the screen when the user clicks on the object this component is attached to. You can set {@link device} This behaviour can be disabled by setting `allowStartOnClick` to false.  
  * It is also possible to start the stream manually from your code by calling the {@link share} method.
  * 
+ * @summary Share screen, camera or microphone in a networked room
  * @category Networking
  * @group Components
 */

package/src/engine-components/SeeThrough.ts

@@ -40,6 +40,7 @@ let i = 0;
  * 
  * - Example https://see-through-walls-z23hmxbz1kjfjn.needle.run/
  * 
+ * @summary Makes objects fade out when obscuring a reference point from the camera
  * @category Rendering
  * @group Components
  */

package/src/engine-components/ShadowCatcher.ts

@@ -22,6 +22,8 @@ enum ShadowMode {
  * If the GameObject is a Mesh, it will apply a shadow-catching material to it - otherwise it will create a quad with the shadow-catching material.  
  * 
  * Note that ShadowCatcher meshes are not raycastable by default; if you want them to be raycastable, change the layers in `onEnable()`.
+ * 
+ * @summary Creates a shadow mask or a light occluder 
  * @category Rendering
  * @group Components
  */

package/src/engine-components/Skybox.ts

@@ -1,16 +1,14 @@
-import { CompressedCubeTexture, CubeRefractionMapping, CubeTexture, CubeUVReflectionMapping, EquirectangularRefractionMapping, SRGBColorSpace, Texture, TextureLoader } from "three"
-import { EXRLoader } from "three/examples/jsm/loaders/EXRLoader.js";
-import { KTX2Loader } from "three/examples/jsm/loaders/KTX2Loader.js";
-import { RGBELoader } from 'three/examples/jsm/loaders/RGBELoader.js';
+import { CompressedCubeTexture, CubeTexture, CubeUVReflectionMapping, EquirectangularRefractionMapping, Texture } from "three"
 
+import { isDevEnvironment } from "../engine/debug/debug.js";
 import { ContextEvent, ContextRegistry } from "../engine/engine_context_registry.js";
 import { syncField } from "../engine/engine_networking_auto.js";
 import { loadPMREM } from "../engine/engine_pmrem.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { type IContext } from "../engine/engine_types.js";
-import { addAttributeChangeCallback, getParam, PromiseAllWithErrors, removeAttributeChangeCallback, toSourceId } from "../engine/engine_utils.js";
+import { addAttributeChangeCallback, getParam, removeAttributeChangeCallback, toSourceId } from "../engine/engine_utils.js";
 import { registerObservableAttribute } from "../engine/webcomponents/needle-engine.extras.js";
-import { Camera, ClearFlags } from "./Camera.js";
+import { Camera } from "./Camera.js";
 import { Behaviour, GameObject } from "./Component.js";
 
 const debug = getParam("debugskybox");
@@ -18,6 +16,29 @@ const debug = getParam("debugskybox");
 registerObservableAttribute("background-image");
 registerObservableAttribute("environment-image");
 
+
+type MagicSkyboxName = "studio" | "blurred-skybox" | "quicklook-ar" | "quicklook";
+const MagicSkyboxNames: Record<MagicSkyboxName, { url: string, url_low: string }> = {
+    "studio": {
+        url: "https://cdn.needle.tools/static/skybox/modelviewer-Neutral.pmrem4x4.ktx2?pmrem",
+        url_low: "https://cdn.needle.tools/static/skybox/modelviewer-Neutral-small.pmrem4x4.ktx2?pmrem"
+    },
+    "blurred-skybox": {
+        url: "https://cdn.needle.tools/static/skybox/blurred-skybox.pmrem4x4.ktx2?pmrem",
+        url_low: "https://cdn.needle.tools/static/skybox/blurred-skybox-small.pmrem4x4.ktx2?pmrem"
+    },
+    "quicklook-ar": {
+        url: "https://cdn.needle.tools/static/skybox/QuickLook-ARMode.pmrem4x4.ktx2?pmrem",
+        url_low: "https://cdn.needle.tools/static/skybox/QuickLook-ARMode-small.pmrem4x4.ktx2?pmrem"
+    },
+    "quicklook": {
+        url: "https://cdn.needle.tools/static/skybox/QuickLook-ObjectMode.pmrem4x4.ktx2?pmrem",
+        url_low: "https://cdn.needle.tools/static/skybox/QuickLook-ObjectMode-small.pmrem4x4.ktx2?pmrem"
+    }
+} as const;
+type AnyString = string & { _brand?: never };
+
+
 function createRemoteSkyboxComponent(context: IContext, url: string, skybox: boolean, environment: boolean, attribute: "background-image" | "environment-image") {
 
     // when the user sets the attribute to a color we can not handle it as a skybox url.
@@ -91,8 +112,9 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, () => {
 });
 
 
+
 /**
- * RemoteSkybox is a component that allows you to set the skybox of a scene from a URL or a local file.  
+ * RemoteSkybox is a component that allows you to set the skybox or environment texture of a scene from a URL, a local file or a static skybox name.  
  * It supports .hdr, .exr, .jpg, .png files.
  * 
  * ### Events
@@ -121,14 +143,20 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, () => {
  * skybox.setSkybox("https://example.com/skybox.hdr");
  * ```
  * 
+ * @summary Sets the skybox or environment texture of a scene
  * @category Rendering
  * @group Components
  */
 export class RemoteSkybox extends Behaviour {
 
     /**
-     * URL to a remote skybox. This value can also use a magic skybox name. Options are "quicklook", "quicklook-ar", "studio", "blurred-skybox".  
-     * To update the skybox/environment map use `setSkybox(url)`
+     * URL to a remote skybox.   
+     * To update the skybox/environment map use `setSkybox(url)`. 
+     * 
+     * The url can also be set to a magic skybox name.   
+     * Magic name options are: "quicklook", "quicklook-ar", "studio", "blurred-skybox".     
+     * These will resolve to built-in skyboxes hosted on the Needle CDN that are static, optimized for the web and will never change.  
+     * 
      * @example
      * ```ts
      * skybox.url = "https://example.com/skybox.hdr";
@@ -136,7 +164,7 @@ export class RemoteSkybox extends Behaviour {
      */
     @syncField(RemoteSkybox.prototype.urlChangedSyncField)
     @serializable(URL)
-    url?: string;
+    url: MagicSkyboxName | AnyString = "studio";
 
     /**
      * When enabled a user can drop a link to a skybox image on the scene to set the skybox.
@@ -208,7 +236,7 @@ export class RemoteSkybox extends Behaviour {
      * @param name Define name of the file with extension if it isn't apart of the url
      * @returns Whether the skybox was successfully set
      */
-    async setSkybox(url: string | undefined | null, name?: string) {
+    async setSkybox(url: MagicSkyboxName | AnyString | undefined | null, name?: string) {
         if (!this.activeAndEnabled) return false;
 
         url = tryParseMagicSkyboxName(url, this.environment, this.background);
@@ -404,38 +432,22 @@ export class RemoteSkybox extends Behaviour {
 
 
 
-
 function tryParseMagicSkyboxName(str: string | null | undefined, environment: boolean, background: boolean): string | null {
 
     if (str === null || str === undefined) return null;
 
     const useLowRes = environment && !background;
 
-    switch (str.toLowerCase()) {
-        case "studio":
-            if (useLowRes) {
-                return "https://cdn.needle.tools/static/skybox/modelviewer-Neutral-small.pmrem4x4.ktx2?pmrem";
-            }
-            return "https://cdn.needle.tools/static/skybox/modelviewer-Neutral.pmrem4x4.ktx2?pmrem";
-
-        case "blurred-skybox":
-            if (useLowRes) {
-                return "https://cdn.needle.tools/static/skybox/blurred-skybox-small.pmrem4x4.ktx2?pmrem";
-            }
-            return "https://cdn.needle.tools/static/skybox/blurred-skybox.pmrem4x4.ktx2?pmrem";
-        case "quicklook-ar":
-            if (useLowRes) {
-                return "https://cdn.needle.tools/static/skybox/QuickLook-ARMode-small.pmrem4x4.ktx2?pmrem";
-            }
-            return "https://cdn.needle.tools/static/skybox/QuickLook-ARMode.pmrem4x4.ktx2?pmrem";
-        case "quicklook":
-            if (useLowRes) {
-                return "https://cdn.needle.tools/static/skybox/QuickLook-ObjectMode-small.pmrem4x4.ktx2?pmrem";
-            }
-            return "https://cdn.needle.tools/static/skybox/QuickLook-ObjectMode.pmrem4x4.ktx2?pmrem";
+    const value = MagicSkyboxNames[str.toLowerCase() as MagicSkyboxName];
+    if (value) {
+        return useLowRes ? value.url_low : value.url;
+    }
+    else if (typeof str === "string" && str?.length && (isDevEnvironment() || debug)) {
+        const noUrlOrFile = !str.startsWith("http") && !str.startsWith("file:") && !str.startsWith("blob:") && !str.startsWith("data:");
+        if(noUrlOrFile) {
+            console.warn(`RemoteSkybox: Unknown magic skybox name "${str}". Valid names are: ${Object.keys(MagicSkyboxNames).map(n => `"${n}"`).join(", ")}`);
+        }
     }
-
-
 
     return str;
 }

package/src/engine-components/SmoothFollow.ts

@@ -9,6 +9,7 @@ import { Behaviour } from "./Component.js";
 /**
  * SmoothFollow makes the {@link Object3D} (`GameObject`) smoothly follow another target {@link Object3D}.  
  * It can follow the target's position, rotation, or both.   
+ * @summary Smoothly follows a target object
  * @category Interactivity
  * @group Components
  */

package/src/engine-components/SpatialTrigger.ts

@@ -26,6 +26,7 @@ function testMask(mask1, mask2) {
 /**
  * Component that receives and responds to spatial events, like entering or exiting a trigger zone.
  * Used in conjunction with {@link SpatialTrigger} to create interactive spatial events.
+ * @summary Receives spatial trigger events
  * @category Interactivity
  * @group Components
  */

package/src/engine-components/SpectatorCamera.ts

@@ -35,6 +35,7 @@ const debug = getParam("debugspectator");
  * 
  * Debug mode can be enabled with the URL parameter `?debugspectator`, which provides additional console output.
  * 
+ * @summary Spectator camera for following other users
  * @category Networking
  * @group Components
  */

package/src/engine-components/SpriteRenderer.ts

@@ -86,6 +86,7 @@ function updateTextureIfNecessary(tex: Texture) {
 
 /**
  * A sprite is a mesh that represents a 2D image. Used by the {@link SpriteRenderer} to render 2D images in the scene.
+ * @summary 2D image renderer 
  * @category Rendering
  * @group Components
  */

package/src/engine-components/SyncedCamera.ts

@@ -63,6 +63,8 @@ declare type UserCamInfo = {
 /**
  * SyncedCamera is a component that syncs the camera position and rotation of all users in the room.  
  * A prefab can be set to represent the remote cameras visually in the scene.
+ * 
+ * @summary Syncs camera position and rotation of users in a networked room
  * @category Networking
  * @group Components
  */

package/src/engine-components/SyncedRoom.ts

@@ -33,6 +33,7 @@ const debug = utils.getParam("debugsyncedroom");
  * myObject.addComponent(SyncedRoom, { joinRandomRoom: true, roomPrefix: "myApp_" });
  * ```
  * 
+ * @summary Joins a networked room based on URL parameters or a random room
  * @category Networking
  * @group Components
  */

package/src/engine-components/SyncedTransform.ts

@@ -57,6 +57,8 @@ onUpdate((ctx) => {
 /**
  * SyncedTransform synchronizes the position and rotation of a game object over the network.
  * It handles ownership transfer, interpolation, and network state updates automatically.
+ * 
+ * @summary Synchronizes object transform over the network with ownership management
  * @category Networking
  * @group Components
  */

package/src/engine-components/TransformGizmo.ts

@@ -10,6 +10,8 @@ import { SyncedTransform } from "./SyncedTransform.js";
 /**
  * TransformGizmo displays manipulation controls for translating, rotating, and scaling objects in the scene.
  * It wraps three.js {@link TransformControls} and provides keyboard shortcuts for changing modes and settings.
+ * 
+ * @summary Object manipulation gizmo for translating, rotating, and scaling
  * @category Helpers
  * @group Components
  */

package/src/engine-components/VideoPlayer.ts

@@ -54,6 +54,7 @@ export enum VideoRenderMode {
  *    playOnAwake: true,
  * });
  * ```
+ * @summary Plays video clips from URLs or streams
  * @category Multimedia
  * @group Components
  */

package/src/engine-components/Voip.ts

@@ -14,6 +14,7 @@ const debugParam = getParam("debugvoip");
 /**
  * The Voice over IP component (VoIP) allows you to send and receive audio streams to other users in the same networked room.  
  * It requires a networking connection to be working (e.g. by having an active SyncedRoom component in the scene or by connecting to a room manually).  
+ * @summary Voice over IP for networked audio communication
  * @category Networking
  * @group Components
  */

package/src/engine-components/export/gltf/GltfExport.ts

@@ -30,6 +30,11 @@ export class GltfExportBox extends BoxHelperComponent {
 }
 
 /**
+ * GltfExport is a component that enables exporting selected 3D objects from the scene to the glTF format.  
+ * You can specify whether to export in binary format (.glb) or JSON format (.gltf), and select specific objects to include in the export.
+ * The exported glTF file can be used in various 3D applications and engines that support the glTF standard.
+ * 
+ * @summary Export selected 3D objects to glTF format
  * @category Asset Management
  * @group Components
  */

package/src/engine-components/export/usdz/USDZExporter.ts

@@ -1,5 +1,5 @@
 import { NEEDLE_progressive } from "@needle-tools/gltf-progressive";
-import { Euler, EventDispatcher, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "three";
+import { Euler, Material, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "three";
 
 import { isDevEnvironment, showBalloonMessage, showBalloonWarning } from "../../../engine/debug/index.js";
 import { hasProLicense } from "../../../engine/engine_license.js";
@@ -53,6 +53,23 @@ export class CustomBranding {
     callToActionURL?: string;
 }
 
+type BeforeLODExportArguments = {
+    readonly exporter: USDZExporter;
+    /** The type of LOD being exported, either a texture or a mesh */
+    readonly type: "texture" | "mesh";
+    /** The Renderer gameobject */
+    readonly object: Object3D;
+    /** The mesh being exported, if applicable */
+    readonly mesh?: Mesh;
+    /** The material being exported, if applicable */
+    readonly material?: Material;
+    /** By default LOD 0 will be exported (highest quality). 
+     * Set to a different LOD level if needed. 
+     * Set to -1 to disable LOD export and simply export the current version.
+    */
+    overrideLevel?: number;
+}
+
 /**
  * Exports the current scene or a specific object as USDZ file and opens it in QuickLook on iOS/iPadOS/visionOS.  
  * The USDZ file is generated using the Needle Engine ThreeUSDZExporter.  
@@ -67,13 +84,18 @@ export class CustomBranding {
  * usdz.autoExportAudioSources = true;
  * usdz.exportAsync();
  * ```
+ * @summary Export 3D objects as USDZ files for QuickLook
  * @category XR
  * @group Components
  */
 export class USDZExporter extends Behaviour {
 
-    static readonly beforeExport = new EventList<{ exporter: USDZExporter }>();
-    static readonly afterExport = new EventList<{ exporter: USDZExporter }>();
+    /** Called before the USDZ file is exported */
+    static readonly beforeExport = new EventList<{ readonly exporter: USDZExporter }>();
+    /** Called after the USDZ file has been exported */
+    static readonly afterExport = new EventList<{ readonly exporter: USDZExporter }>();
+    /** Called before LOD level are exported. Can be used to override the LOD export settings */
+    static readonly beforeLODExport = new EventList<BeforeLODExportArguments>();
 
     /**
      * Assign the object to export as USDZ file. If undefined or null, the whole scene will be exported.
@@ -329,7 +351,20 @@ export class USDZExporter extends Behaviour {
         for (const rend of renderers) {
             for (const mesh of rend.sharedMeshes) {
                 if (mesh) {
-                    const task = NEEDLE_progressive.assignMeshLOD(mesh, 0);
+                    let lodLevel = 0;
+                    const args: BeforeLODExportArguments = { exporter: this, type: "mesh" as const, object: rend.gameObject, mesh: mesh, };
+                    USDZExporter.beforeLODExport.invoke(args);
+                    if (args.overrideLevel !== undefined) {
+                        if (args.overrideLevel === -1) {
+                            if (debug) console.warn("Skipping LOD export for mesh due to overrideLevel -1", rend.gameObject, mesh);
+                            continue; // skip LOD assignment
+                        }
+                        else if (args.overrideLevel >= 0) {
+                            lodLevel = args.overrideLevel;
+                            if (debug) console.log("Overriding LOD level for mesh export to level " + lodLevel + " " + mesh.name);
+                        }
+                    }
+                    const task = NEEDLE_progressive.assignMeshLOD(mesh, lodLevel);
                     if (task instanceof Promise)
                         progressiveLoading.push(new Promise<void>((resolve, reject) => {
                             task.then(() => {
@@ -342,7 +377,20 @@ export class USDZExporter extends Behaviour {
             }
             for (const mat of rend.sharedMaterials) {
                 if (mat) {
-                    const task = NEEDLE_progressive.assignTextureLOD(mat, 0);
+                    let lodLevel = 0;
+                    const args: BeforeLODExportArguments = { exporter: this, type: "texture" as const, object: rend.gameObject, material: mat };
+                    USDZExporter.beforeLODExport.invoke(args);
+                    if (args.overrideLevel !== undefined) {
+                        if (args.overrideLevel === -1) {
+                            if (debug) console.warn("Skipping LOD assignment due to overrideLevel -1", rend.gameObject, mat);
+                            continue; // skip LOD assignment
+                        }
+                        else if (args.overrideLevel >= 0) {
+                            lodLevel = args.overrideLevel;
+                            if (debug) console.log("Overriding LOD level for texture export to level " + lodLevel + " " + mat.name);
+                        }
+                    }
+                    const task = NEEDLE_progressive.assignTextureLOD(mat, lodLevel);
                     if (task instanceof Promise)
                         progressiveLoading.push(new Promise<void>((resolve, reject) => {
                             task.then(() => {