Needle Engine 3.36.3-beta

Files changed (20) hide show

src/engine/webcomponents/api.ts +1 -0
src/engine/xr/api.ts +2 -1
src/engine-components/ContactShadows.ts +8 -3
src/engine/engine_camera.ts +5 -5
src/engine/engine_components.ts +95 -4
src/engine/engine_element_loading.ts +0 -1
src/engine/engine_utils.ts +4 -0
src/engine/xr/events.ts +3 -3
src/engine-components/export/usdz/Extension.ts +14 -2
src/engine/extensions/NEEDLE_progressive.ts +35 -4
src/asap/needle-asap.ts +10 -3
src/engine/webcomponents/needle menu/needle-menu.ts +7 -0
src/engine/xr/NeedleXRSession.ts +3 -1
src/engine-components/OrbitControls.ts +41 -13
src/engine-components/Renderer.ts +53 -48
src/engine-components/ShadowCatcher.ts +1 -1
src/engine-components/export/usdz/ThreeUSDZExporter.ts +4 -5
src/engine-components/export/usdz/USDZExporter.ts +87 -18
src/engine-components/webxr/WebARSessionRoot.ts +12 -3
src/engine-components/webxr/WebXRButtons.ts +3 -7

src/engine/webcomponents/api.ts CHANGED Viewed

@@ -1,3 +1,4 @@
+export * from "./icons.js"
 export { type NeedleMenuPostMessageModel } from "./needle menu/needle-menu.js"

src/engine/xr/api.ts CHANGED Viewed

@@ -1,5 +1,6 @@
+export * from "./events.js";
 export * from "./NeedleXRController.js";
 export * from "./NeedleXRSession.js";
 export * from "./NeedleXRSync.js"
 export * from "./utils.js"
-export * from "./XRRig.js";
+export * from "./XRRig.js";

src/engine-components/ContactShadows.ts CHANGED Viewed

@@ -171,9 +171,6 @@
     /** @internal */
     onBeforeRender(_frame: XRFrame | null): void {
-        const scene = this.context.scene;
-        const renderer = this.context.renderer;
-        const initialRenderTarget = renderer.getRenderTarget();
         if (!this.renderTarget || !this.renderTargetBlur ||
             !this.depthMaterial || !this.shadowCamera ||
@@ -184,6 +181,10 @@
             return;
         }
+        const scene = this.context.scene;
+        const renderer = this.context.renderer;
+        const initialRenderTarget = renderer.getRenderTarget();
         // Idea: shear the shadowCamera matrix to add some light direction to the ground shadows
         /*
         const mat = this.shadowCamera.projectionMatrix.clone();
@@ -211,6 +212,9 @@
         const initialClearAlpha = renderer.getClearAlpha();
         renderer.setClearAlpha(0);
+        const prevXRState = renderer.xr.enabled;
+        renderer.xr.enabled = false;
         // render to the render target to get the depths
         renderer.setRenderTarget(this.renderTarget);
         renderer.render(scene, this.shadowCamera);
@@ -235,6 +239,7 @@
         renderer.setRenderTarget(initialRenderTarget);
         renderer.setClearAlpha(initialClearAlpha);
         scene.background = initialBackground;
+        renderer.xr.enabled = prevXRState;
     }
     // renderTarget --> blurPlane (horizontalBlur) --> renderTargetBlur --> blurPlane (verticalBlur) --> renderTarget

src/engine/engine_camera.ts CHANGED Viewed

@@ -3,7 +3,7 @@
 import type { ICameraController } from "./engine_types.js";
-const $cameraController = Symbol("cameraController");
+const $cameraController = "needle:cameraController";
 /** Get the camera controller for the given camera (if any)
  */
@@ -22,18 +22,18 @@
 }
-const $autofit = Symbol("camera autofit");
+const autofit = "needle:autofit";
 /** @internal */
 export function useForAutoFit(obj: Object3D): boolean {
     // if autofit is not defined we assume it may be included
-    if (obj[$autofit] === undefined) return true;
+    if (obj[autofit] === undefined) return true;
     // otherwise if anything is set except false we assume it should be included
-    return obj[$autofit] !== false;
+    return obj[autofit] !== false;
 }
 /** @internal */
 export function setAutoFitEnabled(obj: Object3D, enabled: boolean): void {
-    obj[$autofit] = enabled;
+    obj[autofit] = enabled;
 }

src/engine/engine_components.ts CHANGED Viewed

@@ -169,6 +169,16 @@
     return arr;
 }
+/**
+ * Searches for a given component type in the given object.
+ * @param obj The object to search in.
+ * @param componentType The type of the component to search for.
+ * @returns The first component of the given type found in the given object.
+ * @example
+ * ```typescript
+ * const myComponent = getComponent(myObject, MyComponent);
+ * ```
+ */
 export function getComponent<T extends IComponent>(obj: Object3D, componentType: Constructor<T>): T | null {
     const result = onGetComponent(obj, componentType);
     if (!result) return null;
@@ -176,6 +186,18 @@
     return result;
 }
+/**
+ * Searches for a given component type in the children of the given object.
+ * @param obj The object to start the search from - this object is also included in the search.
+ * @param componentType The type of the component to search for.
+ * @param arr An optional array to store the found components in. If not provided, a new array is created.
+ * @param clearArray If true, the array is cleared before storing the found components. Default is true.
+ * @returns An array of components of the given type found in the children of the given object.
+ * @example
+ * ```typescript
+ * const myComponents = getComponents(myObject, MyComponent);
+ * ```
+ */
 export function getComponents<T extends IComponent>(obj: Object3D, componentType: Constructor<T>, arr?: T[] | null, clearArray: boolean = true): T[] {
     if (!arr) arr = [];
     if (clearArray) arr.length = 0;
@@ -183,6 +205,17 @@
     return arr;
 }
+/**
+ * Searches for a given component type in the children of the given object.
+ * @param obj The object to start the search from - this object is also included in the search.
+ * @param componentType The type of the component to search for.
+ * @param includeInactive If true, also inactive components are returned. Default is true.
+ * @returns The first component of the given type found in the children of the given object.
+ * @example
+ * ```typescript
+ * const myComponent = getComponentInChildren(myObject, MyComponent);
+ * ```
+ */
 export function getComponentInChildren<T extends IComponent>(obj: Object3D, componentType: Constructor<T>, includeInactive?: boolean): T | null {
     const res = getComponent(obj, componentType) as IComponent | null;
     if (includeInactive === false && res?.enabled === false) return null;
@@ -194,6 +227,18 @@
     return null;
 }
+/**
+ * Searches for a given component type in the children of the given object.
+ * @param obj The object to start the search from - this object is also included in the search.
+ * @param componentType The type of the component to search for.
+ * @param arr An optional array to store the found components in. If not provided, a new array is created.
+ * @param clearArray If true, the array is cleared before storing the found components. Default is true.
+ * @returns An array of components of the given type found in the children of the given object.
+ * @example
+ * ```typescript
+ * const myComponents = getComponentsInChildren(myObject, MyComponent);
+ * ```
+ */
 export function getComponentsInChildren<T extends IComponent>(obj: Object3D, componentType: Constructor<T>, arr?: T[], clearArray: boolean = true): T[] | null {
     if (!arr) arr = [];
     if (clearArray) arr.length = 0;
@@ -205,6 +250,16 @@
     return arr;
 }
+/**
+ * Searches for a given component type in the parent hierarchy of the given object.
+ * @param obj The object to start the search from - this object is also included in the search.
+ * @param componentType The type of the component to search for.
+ * @returns The first component of the given type found in the parent hierarchy of the given object.
+ * @example
+ * ```typescript
+ * const myComponent = getComponentInParent(myObject, MyComponent);
+ * ```
+ */
 export function getComponentInParent<T extends IComponent>(obj: Object3D, componentType: Constructor<T>): T | null {
     if (!obj) return null;
     if (Array.isArray(obj)) {
@@ -223,6 +278,18 @@
     return null;
 }
+/**
+ * Searches for a given component type in the parent hierarchy of the given object.
+ * @param obj The object to start the search from - this object is also included in the search.
+ * @param componentType The type of the component to search for.
+ * @param arr An optional array to store the found components in. If not provided, a new array is created.
+ * @param clearArray If true, the array is cleared before storing the found components. Default is true.
+ * @returns An array of components of the given type found in the parent hierarchy of the given object.
+ * @example
+ * ```typescript
+ * const myComponents = getComponentsInParent(myObject, MyComponent);
+ * ```
+ */
 export function getComponentsInParent<T extends IComponent>(obj: Object3D, componentType: Constructor<T>, arr?: T[] | null, clearArray: boolean = true): T[] {
     if (!arr) arr = [];
     if (clearArray) arr.length = 0;
@@ -234,7 +301,19 @@
     return arr;
 }
-export function findObjectOfType<T extends IComponent>(type: Constructor<T>, contextOrScene: Object3D | { scene: Scene }, includeInactive): T | null {
+/**
+ * Searches the the scene for a component of the given type.
+ * If the contextOrScene is not provided, the current context is used.
+ * @param type The type of the component to search for.
+ * @param contextOrScene The context or scene to search in. If not provided, the current context is used.
+ * @param includeInactive If true, also inactive components are returned. Default is true.
+ * @returns The first component of the given type found in the scene or null if none was found.
+ * @example
+ * ```typescript
+ * const myComponent = findObjectOfType(MyComponent);
+ * ```
+ */
+export function findObjectOfType<T extends IComponent>(type: Constructor<T>, contextOrScene: undefined | Object3D | { scene: Scene } = undefined, includeInactive: boolean = true): T | null {
     if (!type) return null;
     if (!contextOrScene) {
         contextOrScene = Context.Current;
@@ -259,7 +338,17 @@
     return null;
 }
-export function findObjectsOfType<T extends IComponent>(type: Constructor<T>, array: T[], contextOrScene): T[] {
+/**
+ * Searches the the scene for all components of the given type.
+ * If the contextOrScene is not provided, the current context is used.
+ * @param type The type of the component to search for.
+ * @param contextOrScene The context or scene to search in. If not provided, the current context is used.
+ * @example
+ * ```typescript
+ * const myComponents = findObjectsOfType(MyComponent);
+ * ```
+ */
+export function findObjectsOfType<T extends IComponent>(type: Constructor<T>, array: T[], contextOrScene: undefined | Object3D | { scene: Scene } = undefined): T[] {
     if (!type) return array;
     if (!array) array = [];
     array.length = 0;
@@ -271,11 +360,13 @@
             return array;
         }
     }
-    const scene = contextOrScene.isScene === true || contextOrScene.isObject3D === true ? contextOrScene : contextOrScene?.scene;
+    if ("scene" in contextOrScene) contextOrScene = (contextOrScene as { scene: Scene }).scene;
+    const scene = contextOrScene;
     if (!scene) return array;
     for (const i in scene.children) {
         const child = scene.children[i];
-        if (child.constructor == type) return child;
         getComponentsInChildren(child, type, array, false);
     }
     return array;

src/engine/engine_element_loading.ts CHANGED Viewed

@@ -240,7 +240,6 @@
         const logoSize = 120;
         logo.style.width = `${logoSize}px`;
         logo.style.height = `${logoSize}px`;
-        logo.style.borderRadius = "80px";
         logo.style.padding = "20px";
         logo.style.margin = "-20px";
         logo.style.marginBottom = "-10px";

src/engine/engine_utils.ts CHANGED Viewed

@@ -515,6 +515,10 @@
     return (typeof window.orientation !== "undefined") || (navigator.userAgent.indexOf('IEMobile') !== -1);
 }
+export function isAndroidDevice() {
+    return /Android/.test(navigator.userAgent);
+}
 /** @returns `true` if we're currently using the mozilla XR browser */
 export function isMozillaXR() {
     return /WebXRViewer\//i.test(navigator.userAgent);

src/engine/xr/events.ts CHANGED Viewed

@@ -6,7 +6,7 @@
 /**
  * Add a listener for when an XR session starts
- * This event is triggered when the XR session is started, either by the user or by the application
+ * This event is triggered when the XR session is started, either by the user or by the application before all other XR start events
  * @param fn The function to call when the XR session starts
  * @example
  * ```js
@@ -42,8 +42,8 @@
 const onXRSessionEndListeners: ((evt: XRSessionEventArgs) => void)[] = [];
 /**
- * Add a listener for when an XR session ends
- * This event is triggered when the XR session is ended, either by the user or by the application
+ * Add a listener for when an XR session ends
+ * This event is triggered when the XR session is ended, either by the user or by the application before all other XR end events
  * @param fn The function to call when the XR session ends
  * @example
  * ```js

src/engine-components/export/usdz/Extension.ts CHANGED Viewed

@@ -2,12 +2,24 @@
 import { USDObject, USDZExporterContext } from "./ThreeUSDZExporter.js";
+/**
+ * Interface for USDZ Exporter Extensions used by {@link USDZExporter}
+ */
 export interface IUSDExporterExtension {
+    /**
+     * The name of the extension
+     */
     get extensionName(): string;
+    /**
+     * Called before the document is built
+     */
     onBeforeBuildDocument?(context);
+    /**
+     * Called after the document is built
+     */
     onAfterBuildDocument?(context);
-    onExportObject?(object: Object3D, model : USDObject, context: USDZExporterContext);
+    onExportObject?(object: Object3D, model: USDObject, context: USDZExporterContext);
     onAfterSerialize?(context);
-    onAfterHierarchy?(context, writer : any);
+    onAfterHierarchy?(context, writer: any);
 }

src/engine/extensions/NEEDLE_progressive.ts CHANGED Viewed

@@ -92,6 +92,36 @@
     }>
 }
+/**
+ * This is the result of a progressive texture loading event for a material's texture slot in {@link NEEDLE_progressive.assignTextureLOD}
+ * @internal
+ */
+export declare type ProgressiveMaterialTextureLoadingResult = {
+    /** the material the progressive texture was loaded for */
+    material: Material,
+    /** the slot in the material where the texture was loaded */
+    slot: string,
+    /** the texture that was loaded (if any) */
+    texture: Texture | null;
+    /** the level of detail that was loaded */
+    level: number;
+}
+/**
+ * The NEEDLE_progressive extension for the GLTFLoader is responsible for loading progressive LODs for meshes and textures.
+ * This extension can be used to load different resolutions of a mesh or texture at runtime (e.g. for LODs or progressive textures).
+ * @example
+ * ```javascript
+ * const loader = new GLTFLoader();
+ * loader.register(new NEEDLE_progressive());
+ * loader.load("model.glb", (gltf) => {
+ *    const mesh = gltf.scene.children[0] as Mesh;
+ *   NEEDLE_progressive.assignMeshLOD(context, sourceId, mesh, 1).then(mesh => {
+ *     console.log("Mesh with LOD level 1 loaded", mesh);
+ *  });
+ * });
+ * ```
+ */
 export class NEEDLE_progressive implements GLTFLoaderPlugin {
     /** The name of the extension */
@@ -210,6 +240,7 @@
                 }
                 this.onProgressiveLoadEnd(info);
                 return geo;
             }).catch(err => {
                 this.onProgressiveLoadEnd(info);
                 console.error("Error loading mesh LOD", mesh, err);
@@ -231,7 +262,7 @@
      * @returns a promise that resolves to the material or texture with the requested LOD level
      */
     static assignTextureLOD(context: Context, source: SourceIdentifier, materialOrTexture: Material | Texture, level: number = 0)
-        : Promise<Array<{ slot: string, texture: Texture | null }> | Texture | null> {
+        : Promise<Array<ProgressiveMaterialTextureLoadingResult> | Texture | null> {
         if (!materialOrTexture) return Promise.resolve(null);
@@ -262,15 +293,15 @@
                 }
             }
             return PromiseAllWithErrors(promises).then(res => {
-                const textures = new Array<{ slot: string, texture: Texture | null }>();
+                const textures = new Array<ProgressiveMaterialTextureLoadingResult>();
                 for (let i = 0; i < res.results.length; i++) {
                     const tex = res.results[i];
                     const slot = slots[i];
                     if (tex instanceof Texture) {
-                        textures.push({ slot, texture: tex });
+                        textures.push({ material, slot, texture: tex, level });
                     }
                     else {
-                        textures.push({ slot, texture: null });
+                        textures.push({ material, slot, texture: null, level });
                     }
                 }
                 return textures;

src/asap/needle-asap.ts CHANGED Viewed

@@ -73,11 +73,18 @@
 }
-function insertTemporaryContentWhileEngineHasntLoaded(needleEngineElement) {
+function insertTemporaryContentWhileEngineHasntLoaded(needleEngineElement: HTMLElement) {
     if (needleEngineHasLoaded()) return;
     const img = document.createElement("img");
-    img.src = needleLogoOnlySVG;
+    // if a custom logo is assigned we should use this here
+    // technically we should check if the user has a license
+    const customLogoUrl = needleEngineElement?.getAttribute("loading-logo-src");
+    if (customLogoUrl && customLogoUrl?.length > 0)
+        img.src = customLogoUrl;
+    else
+        img.src = needleLogoOnlySVG;
     img.style.position = "absolute";
     img.style.top = "50%";
     img.style.left = "50%";
@@ -94,7 +101,7 @@
     // animation to pulsate
     img.animate([
         { opacity: 0 },
-        { opacity: .3 },
+        { opacity: .5 },
         { opacity: 0 }
     ], {
         duration: 3000,

src/engine/webcomponents/needle menu/needle-menu.ts CHANGED Viewed

@@ -231,6 +231,7 @@
             display: flex;
             justify-content: center;
             align-items: center;
+            max-height: 2.3rem;
             /** basic font settings for all entries **/
             font-size: 1rem;
@@ -265,6 +266,12 @@
             outline: rgba(0,0,0,.05) 1px solid;
         }
+        :host .options > *:disabled {
+            background: rgba(0,0,0,.05);
+            color: rgba(60,60,60,.7);
+            pointer-events: none;
+        }
         button {
             gap: 0.3rem;
         }

src/engine/xr/NeedleXRSession.ts CHANGED Viewed

@@ -9,7 +9,7 @@
 import { getTempQuaternion, getTempVector, getWorldPosition, getWorldQuaternion, getWorldScale, setWorldPosition, setWorldQuaternion, setWorldScale } from "../engine_three_utils.js";
 import type { ICamera, IComponent, INeedleXRSession } from "../engine_types.js";
 import { delay, getParam, isDesktop, isQuest } from "../engine_utils.js";
-import { invokeXRSessionStart } from "./events.js"
+import { invokeXRSessionEnd, invokeXRSessionStart } from "./events.js"
 import { flipForwardMatrix, flipForwardQuaternion, ImplictXRRig } from "./internal.js";
 import { NeedleXRController } from "./NeedleXRController.js";
 import { NeedleXRSync } from "./NeedleXRSync.js";
@@ -952,6 +952,8 @@
             this.context.mainCameraComponent?.applyClearFlags()
         });
+        invokeXRSessionEnd({ session: this });
         for (const listener of NeedleXRSession._xrEndListeners) {
             listener({ xr: this });
         }

src/engine-components/OrbitControls.ts CHANGED Viewed

@@ -559,14 +559,33 @@
     // Adapted from https://discourse.threejs.org/t/camera-zoom-to-fit-object/936/24
     // Slower but better implementation that takes bones and exact vertex positions into account: https://github.com/google/model-viewer/blob/04e900c5027de8c5306fe1fe9627707f42811b05/packages/model-viewer/src/three-components/ModelScene.ts#L321
-    /** Fits the camera to show the objects provided (defaults to the scene if no objects are passed in) */
-    fitCamera(objects?: Array<Object3D>, fitOffset: number = 1.1, immediate: boolean = true) {
+    /** Fits the camera to show the objects provided (defaults to the scene if no objects are passed in)
+     * @param objects The objects to fit the camera to - defaults to the scene if not provided
+     * @param fitOffset A factor to multiply the distance to the objects by. Default is 1.1
+     * @param immediate If true the camera will move immediately to the new position, otherwise it will lerp
+    */
+    fitCamera(objects?: Array<Object3D>, fitOffset: undefined | number = undefined, immediate: boolean = true) {
+        if (this.context.isInXR) {
+            // camera fitting in XR is not supported
+            return;
+        }
+        if (fitOffset == undefined) {
+            fitOffset = 1.1;
+        }
         const camera = this._cameraObject as PerspectiveCamera;
         const controls = this._controls as ThreeOrbitControls | null;
         if (!objects?.length) objects = this.context.scene.children;
-        if (objects.length <= 0) return;
+        if (objects.length <= 0) {
+            console.warn("No objects to fit camera to...");
+            return;
+        }
-        if (!camera || !controls) return;
+        if (!camera || !controls) {
+            console.warn("No camera or controls found to fit camera to objects...");
+            return;
+        }
         const size = new Vector3();
         const center = new Vector3();
@@ -654,16 +673,14 @@
             console.log("Fit camera to objects", fitHeightDistance, fitWidthDistance, "distance", distance);
         }
-        const cameraWp = getWorldPosition(camera);
-        const direction = controls.target.clone()
-            .sub(cameraWp)
-            .normalize()
-            .multiplyScalar(distance);
         controls.maxDistance = distance * 10;
         controls.minDistance = distance * 0.01;
-        this.setLookTargetPosition(center, immediate);
+        const verticalOffset = 0.05;
+        const lookAt = center.clone();
+        lookAt.y -= size.y * verticalOffset;
+        this.setLookTargetPosition(lookAt, immediate);
         this.autoTarget = false;
         // TODO: this doesnt take the Camera component nearClipPlane into account
@@ -673,8 +690,16 @@
         camera.updateMatrixWorld();
         camera.updateProjectionMatrix();
+        const cameraWp = getWorldPosition(camera);
+        const direction = center.clone();
+        direction.sub(cameraWp);
+        direction.y = 0;
+        direction.normalize();
+        direction.multiplyScalar(distance);
+        direction.y += -verticalOffset * 4 * size.y;
         if (camera.parent) {
-            const cameraLocalPosition = camera.parent!.worldToLocal(controls.target.clone().sub(direction));
+            const cameraLocalPosition = camera.parent!.worldToLocal(center.clone().sub(direction));
             this.setCameraTargetPosition(cameraLocalPosition, immediate);
         }
         else console.error(`Can not fit camera ${camera.name} because it has no parent`)
@@ -685,12 +710,15 @@
             const helper = new Box3Helper(box);
             this.context.scene.add(helper);
             setWorldRotation(helper, getWorldRotation(camera));
+            setTimeout(() => {
+                this.context.scene.remove(helper);
+            }, 10000);
             if (!this._haveAttachedKeyboardEvents) {
                 this._haveAttachedKeyboardEvents = true;
                 document.body.addEventListener("keydown", (e) => {
                     if (e.code === "KeyF") {
-                        this.fitCamera(objects);
+                        this.fitCamera(objects, fitOffset, immediate);
                     }
                 });
             }

src/engine-components/Renderer.ts CHANGED Viewed

@@ -11,7 +11,7 @@
 import { getTempVector, getWorldDirection, getWorldPosition, getWorldScale } from "../engine/engine_three_utils.js";
 import type { IGameObject, IRenderer, ISharedMaterials } from "../engine/engine_types.js";
 import { getParam, isMobileDevice } from "../engine/engine_utils.js";
-import { NEEDLE_progressive } from "../engine/extensions/NEEDLE_progressive.js";
+import { NEEDLE_progressive, ProgressiveMaterialTextureLoadingResult } from "../engine/extensions/NEEDLE_progressive.js";
 import { NEEDLE_render_objects } from "../engine/extensions/NEEDLE_render_objects.js";
 import { setCustomVisibility } from "../engine/js-extensions/Layers.js";
 import { Behaviour, GameObject } from "./Component.js";
@@ -681,7 +681,7 @@
             }
         }
-        if (this._wasVisible && this.allowProgressiveLoading) {
+        if (this._wasVisible && this.allowProgressiveLoading && !suppressProgressiveLoading) {
             if (this.automaticallyUpdateLODLevel) {
                 this.updateLODs();
             }
@@ -868,7 +868,7 @@
                     return this._lastLodLevel = mesh["DEBUG:LOD"];
                 }
-                let meshDensity = 0;
+                let meshDensity = 0;
                 // TODO: the mesh info contains also the density for all available LOD level so we can use this for selecting which level to show
                 const lodsInfo = NEEDLE_progressive.getMeshLODInformation(mesh.geometry);
                 // TODO: the substraction here is not clear - it should be some sort of mesh density value
@@ -997,18 +997,13 @@
      * @param level the LOD level to load. Level 0 is the best quality, higher levels are lower quality
      * @returns Promise with true if the LOD was loaded, false if not
      */
-    loadProgressiveTextures(material: Material, level: number) {
-        // progressive load before rendering so we only load textures for visible materials
-        if (!suppressProgressiveLoading && material) {
-            if (this.allowProgressiveLoading) {
-                if (!material.userData) material.userData = {};
-                if (material.userData.LOD !== level) {
-                    material.userData.LOD = level;
-                    return NEEDLE_progressive.assignTextureLOD(this.context, this.sourceId!, material, level);
-                }
-            }
+    loadProgressiveTextures(material: Material, level: number): Promise<ProgressiveMaterialTextureLoadingResult[] | Texture | null> {
+        if (!material) return Promise.resolve(null);
+        if (material.userData && material.userData.LOD !== level) {
+            material.userData.LOD = level;
+            return NEEDLE_progressive.assignTextureLOD(this.context, this.sourceId!, material, level);
         }
-        return Promise.resolve(true);
+        return Promise.resolve(null);
     }
     /** Load progressive meshes for the given mesh
@@ -1017,31 +1012,29 @@
      * @param level the LOD level to load. Level 0 is the best quality, higher levels are lower quality
      * @returns Promise with true if the LOD was loaded, false if not
      */
-    loadProgressiveMeshes(mesh: Mesh, level: number) {
-        if (!suppressProgressiveLoading && mesh) {
-            if (this.allowProgressiveLoading) {
-                if (!mesh.userData) mesh.userData = {};
-                if (mesh.userData.LOD !== level) {
-                    mesh.userData.LOD = level;
-                    const originalGeometry = mesh.geometry;
-                    return NEEDLE_progressive.assignMeshLOD(this.context, this.sourceId!, mesh, level).then(res => {
-                        if (res && mesh.userData.LOD == level && originalGeometry != mesh.geometry) {
-                            // update the lightmap
-                            this.applyLightmapping();
+    loadProgressiveMeshes(mesh: Mesh, level: number) : Promise<BufferGeometry | null> {
+        if (!mesh) return Promise.resolve(null);
+        if (!mesh.userData) mesh.userData = {};
+        if (mesh.userData.LOD !== level) {
+            mesh.userData.LOD = level;
+            const originalGeometry = mesh.geometry;
+            return NEEDLE_progressive.assignMeshLOD(this.context, this.sourceId!, mesh, level).then(res => {
+                if (res && mesh.userData.LOD == level && originalGeometry != mesh.geometry) {
+                    // update the lightmap
+                    this.applyLightmapping();
-                            if (this.handles) {
-                                for (const inst of this.handles) {
-                                    // if (inst["LOD"] < level) continue;
-                                    // inst["LOD"] = level;
-                                    inst.setGeometry(mesh.geometry);
-                                }
-                            }
+                    if (this.handles) {
+                        for (const inst of this.handles) {
+                            // if (inst["LOD"] < level) continue;
+                            // inst["LOD"] = level;
+                            inst.setGeometry(mesh.geometry);
                         }
-                    })
+                    }
                 }
-            }
+                return res;
+            })
         }
-        return true;
+        return Promise.resolve(null);
     }
     /** Apply the settings of this renderer to the given object
@@ -1106,11 +1099,15 @@
     awake() {
         super.awake();
+        if (debugskinnedmesh) console.log("SkinnedMeshRenderer for \"" + this.name + "\"", this);
         // disable skinned mesh occlusion because of https://github.com/mrdoob/js/issues/14499
         this.allowOcclusionWhenDynamic = false;
-        // If we don't do that here the bounding sphere matrix used for raycasts will be wrong. Not sure *why* this is necessary
-        this.gameObject.parent?.updateWorldMatrix(false, true);
-        this.markBoundsDirty();
+        for (const mesh of this.sharedMeshes) {
+            // If we don't do that here the bounding sphere matrix used for raycasts will be wrong. Not sure *why* this is necessary
+            mesh.parent?.updateWorldMatrix(false, true);
+            this.markBoundsDirty();
+        }
     }
     onAfterRender(): void {
         super.onAfterRender();
@@ -1126,20 +1123,28 @@
         //     };
         // }
-        if (this.gameObject instanceof SkinnedMesh && this._needUpdateBoundingSphere) {
-            this._needUpdateBoundingSphere = false;
-            const geometry = this.gameObject.geometry;
-            const raycastmesh = getRaycastMesh(this.gameObject);
-            if (raycastmesh) this.gameObject.geometry = raycastmesh;
-            this.gameObject.computeBoundingSphere();
-            this.gameObject.geometry = geometry;
+        if (this._needUpdateBoundingSphere) {
+            for (const mesh of this.sharedMeshes) {
+                if (mesh instanceof SkinnedMesh) {
+                    this._needUpdateBoundingSphere = false;
+                    const geometry = mesh.geometry;
+                    const raycastmesh = getRaycastMesh(mesh);
+                    if (raycastmesh) mesh.geometry = raycastmesh;
+                    mesh.computeBoundingSphere();
+                    mesh.geometry = geometry;
+                }
+            }
         }
         // if (this.context.time.frame % 30 === 0) this.markBoundsDirty();
-        if (debugskinnedmesh && this.gameObject instanceof SkinnedMesh && this.gameObject.boundingSphere) {
-            const tempCenter = getTempVector(this.gameObject.boundingSphere.center).applyMatrix4(this.gameObject.matrixWorld);
-            Gizmos.DrawWireSphere(tempCenter, this.gameObject.boundingSphere.radius, "red");
+        if (debugskinnedmesh) {
+            for (const mesh of this.sharedMeshes) {
+                if (mesh instanceof SkinnedMesh && mesh.boundingSphere) {
+                    const tempCenter = getTempVector(mesh.boundingSphere.center).applyMatrix4(mesh.matrixWorld);
+                    Gizmos.DrawWireSphere(tempCenter, mesh.boundingSphere.radius, "red");
+                }
+            }
         }
     }

src/engine-components/ShadowCatcher.ts CHANGED Viewed

@@ -24,7 +24,7 @@
     private targetMesh?: Mesh;
-    awake() {
+    start() {
         // if there's no geometry, make a basic quad
         if (!(this.gameObject instanceof Mesh)) {
             const quad = ObjectUtils.createPrimitive(PrimitiveType.Quad, {

src/engine-components/export/usdz/ThreeUSDZExporter.ts CHANGED Viewed

@@ -516,7 +516,7 @@
 	}
-	async parse( scene, options: USDZExporterOptions = new USDZExporterOptions() ) {
+	async parse(scene: Object3D | undefined, options: USDZExporterOptions = new USDZExporterOptions()) {
 		options = Object.assign( new USDZExporterOptions(), options );
@@ -540,9 +540,8 @@
 		Progress.report('export-usdz', "Reparent bones to common ancestor");
 		// HACK let's find all skeletons and reparent them to their skelroot / armature / uppermost bone parent
 		const reparentings: Array<any> = [];
-		scene.traverseVisible(object => {
-			if (object.isSkinnedMesh) {
+		scene?.traverseVisible(object => {
+			if (object instanceof SkinnedMesh) {
 				const bones = object.skeleton.bones as Bone[];
 				const commonAncestor = findCommonAncestor(bones);
@@ -559,7 +558,7 @@
 		}
 		Progress.report('export-usdz', "Traversing hierarchy");
-		traverseVisible( scene, context.document, context, this.keepObject);
+		if(scene) traverseVisible( scene, context.document, context, this.keepObject);
 		Progress.report('export-usdz', "Invoking onAfterBuildDocument");
 		await invokeAll( context, 'onAfterBuildDocument' );

src/engine-components/export/usdz/USDZExporter.ts CHANGED Viewed

@@ -22,11 +22,17 @@
 const debug = getParam("debugusdz");
+/**
+ * Custom branding for the QuickLook overlay, used by {@link USDZExporter}.
+ */
 export class CustomBranding {
+    /** The call to action button text. If not set, the button will close the QuickLook overlay. */
     @serializable()
     callToAction?: string;
+    /** The title of the overlay. */
     @serializable()
     checkoutTitle?: string;
+    /** The subtitle of the overlay. */
     @serializable()
     checkoutSubtitle?: string;
@@ -35,6 +41,21 @@
     callToActionURL?: string;
 }
+/**
+ * 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.
+ * The exporter supports various extensions to add custom behaviors and interactions to the USDZ file.
+ * The exporter can automatically collect Animations and AudioSources and export them as playing at the start.
+ * The exporter can also add a custom QuickLook overlay with a call to action button and custom branding.
+ * @example
+ * ```typescript
+ * const usdz = new USDZExporter();
+ * usdz.objectToExport = myObject;
+ * usdz.autoExportAnimations = true;
+ * usdz.autoExportAudioSources = true;
+ * usdz.exportAsync();
+ * ```
+ */
 export class USDZExporter extends Behaviour {
     @serializable(Object3D)
@@ -87,12 +108,16 @@
     @serializable()
     quickLookCompatible: boolean = true;
-    // Registered extensions. Add your own extensions here
+    /**
+     * Extensions to add custom behaviors and interactions to the USDZ file.
+     * You can add your own extensions here by extending {@link IUSDExporterExtension}.
+     */
     extensions: IUSDExporterExtension[] = [];
     private link!: HTMLAnchorElement;
     private button?: HTMLButtonElement;
+    /** @internal */
     start() {
         if (debug) {
             console.log("USDZExporter", this);
@@ -125,6 +150,7 @@
         }
     }
+    /** @internal */
     onEnable() {
         const ios = isiOS()
         const safari = isSafari();
@@ -142,6 +168,7 @@
         document.getElementById("open-in-ar")?.addEventListener("click", this.onClickedOpenInARElement);
     }
+    /** @internal */
     onDisable() {
         this.button?.remove();
         this.link?.removeEventListener('message', this.lastCallback);
@@ -158,15 +185,24 @@
     private onClickedOpenInARElement = (evt) => {
         evt.preventDefault();
-        this.exportAsync();
+        this.exportAndOpen();
     }
     /**
      * Creates an USDZ file from the current scene or assigned objectToExport and opens it in QuickLook.
      * Use the various public properties of USDZExporter to customize export behaviour.
+     * @deprecated use {@link exportAndOpen} instead
      */
     async exportAsync() {
+        return this.exportAndOpen();
+    }
+    /**
+     * Creates an USDZ file from the current scene or assigned objectToExport and opens it in QuickLook.
+     * @returns a Promise<Blob> containing the USDZ file
+     */
+    async exportAndOpen() : Promise<Blob | null> {
         let name = this.exportFileName ?? this.objectToExport?.name ?? this.name;
         name += "-" + getFormattedDate(); // seems iOS caches the file in some cases, this ensures we always have a fresh file
@@ -181,13 +217,13 @@
         if (this.customUsdzFile) {
             if (debug) console.log("Exporting custom usdz", this.customUsdzFile)
             this.openInQuickLook(this.customUsdzFile, name);
-            return;
+            return null;
         }
         const blob = await this.export(this.objectToExport);
         if (!blob) {
             console.warn("No object to export", this);
-            return;
+            return null;
         }
         if (debug) console.log("USDZ generation done. Downloading as " + name);
@@ -197,20 +233,52 @@
         this.openInQuickLook(blob, name);
+        return blob;
     }
     /**
      * Creates an USDZ file from the current scene or assigned objectToExport and opens it in QuickLook.
      * @returns a Promise<Blob> containing the USDZ file
      */
-    async export(objectToExport: Object3D | undefined) : Promise<Blob | null> {
-        if (!objectToExport)
+    async export(objectToExport: Object3D | undefined): Promise<Blob | null> {
+        // make sure we have an object to export
+        if (!objectToExport) {
+            console.warn("No object to export");
             return null;
+        }
-        Progress.start("export-usdz", { onProgress: (progress) => {
-            this.dispatchEvent(new CustomEvent("export-progress", { detail: { progress } }));
-        }});
+        // if we are already exporting, wait for the current export to finish
+        const taskForThisObject = this._currentExportTasks.get(objectToExport);
+        if (taskForThisObject) {
+            return taskForThisObject;
+        }
+        // start the export
+        const task = this.internalExport(objectToExport);
+        // store the task
+        if (task instanceof Promise) {
+            this._currentExportTasks.set(objectToExport, task);
+            return task.then((blob) => {
+                this._currentExportTasks.delete(objectToExport);
+                return blob;
+            }).catch((_) => {
+                this._currentExportTasks.delete(objectToExport);
+                return null;
+            });
+        }
+        return task;
+    }
+    private readonly _currentExportTasks = new Map<Object3D, Promise<Blob | null>>();
+    private async internalExport(objectToExport: Object3D): Promise<Blob | null> {
+        Progress.start("export-usdz", {
+            onProgress: (progress) => {
+                this.dispatchEvent(new CustomEvent("export-progress", { detail: { progress } }));
+            }
+        });
         Progress.report("export-usdz", { message: "Starting export", totalSteps: 40, currentStep: 0 });
         Progress.report("export-usdz", { message: "Load progressive textures", autoStep: 5 });
         Progress.start("export-usdz-textures", "export-usdz");
@@ -218,6 +286,7 @@
         const renderers = GameObject.getComponentsInChildren(objectToExport, Renderer);
         const progressiveLoading = new Array<Promise<any>>();
         let progressiveTasks = 0;
+        // TODO: it would be better to directly integrate this into the exporter and *on export* request the correct LOD level for textures and meshes instead of relying on the renderer etc
         for (const rend of renderers) {
             rend["didAutomaticallyUpdateLODLevel"] = rend.automaticallyUpdateLODLevel;
             rend.automaticallyUpdateLODLevel = false;
@@ -268,7 +337,7 @@
         extensions.push(animExt);
         const eventArgs = { self: this, exporter: exporter, extensions: extensions, object: objectToExport };
-        Progress.report("export-usdz", "Invoking before-export" );
+        Progress.report("export-usdz", "Invoking before-export");
         this.dispatchEvent(new CustomEvent("before-export", { detail: eventArgs }))
         // Implicit registration and actions for Animators and Animation components
@@ -286,12 +355,12 @@
         //@ts-ignore
         exporter.debug = debug;
         exporter.keepObject = (object) => {
-			// TODO We need to take more care with disabled renderers. This currently breaks when any renderer is disabled
-			// and then enabled at runtime by e.g. SetActiveOnClick, requiring extra work to enable them before export,
-			// cache their state, and then reset their state after export. See
-            const renderer = GameObject.getComponent( object, Renderer )
-			if (renderer && !renderer.enabled) return false;
-			return true;
+            // TODO We need to take more care with disabled renderers. This currently breaks when any renderer is disabled
+            // and then enabled at runtime by e.g. SetActiveOnClick, requiring extra work to enable them before export,
+            // cache their state, and then reset their state after export. See
+            const renderer = GameObject.getComponent(object, Renderer)
+            if (renderer && !renderer.enabled) return false;
+            return true;
         }
         // sanitize anchoring types
@@ -300,7 +369,7 @@
         if (this.planeAnchoringAlignment !== "horizontal" && this.planeAnchoringAlignment !== "vertical" && this.planeAnchoringAlignment !== "any")
             this.planeAnchoringAlignment = "horizontal";
-        Progress.report("export-usdz", "Invoking exporter.parse" );
+        Progress.report("export-usdz", "Invoking exporter.parse");
         //@ts-ignore
         const arraybuffer = await exporter.parse(this.objectToExport, {
             ar: {

src/engine-components/webxr/WebARSessionRoot.ts CHANGED Viewed

@@ -8,7 +8,7 @@
 import { InputEventQueue, NEPointerEvent } from "../../engine/engine_input.js";
 import { serializable } from "../../engine/engine_serialization_decorator.js";
 import type { IComponent, IGameObject } from "../../engine/engine_types.js";
-import { getParam } from "../../engine/engine_utils.js";
+import { getParam, isAndroidDevice, isMobileDevice } from "../../engine/engine_utils.js";
 import { NeedleXRController, type NeedleXREventArgs, type NeedleXRHitTestResult, NeedleXRSession } from "../../engine/engine_xr.js";
 import { Behaviour, GameObject } from "../Component.js";
@@ -552,14 +552,19 @@
     //     // this.offset.premultiply(this._tempMatrix.makeScale(s, s, s));
     // }
-    private prev: Map<number, { x: number, z: number, screenx: number, screeny: number }> = new Map();
+    private prev: Map<number, { ignore: boolean, x: number, z: number, screenx: number, screeny: number }> = new Map();
     private _didMultitouch: boolean = false;
     private touchStart = (evt: TouchEvent) => {
         for (let i = 0; i < evt.changedTouches.length; i++) {
             const touch = evt.changedTouches[i];
+            // if a user starts swiping in the top area of the screen
+            // which might be a gesture to open the menu
+            // we ignore it
+            const ignore = isAndroidDevice() && touch.clientY < window.innerHeight * .1;
             if (!this.prev.has(touch.identifier))
                 this.prev.set(touch.identifier, {
+                    ignore,
                     x: 0,
                     z: 0,
                     screenx: 0,
@@ -579,6 +584,10 @@
         if (evt.touches.length <= 0) {
             this._didMultitouch = false;
         }
+        for (let i = 0; i < evt.changedTouches.length; i++) {
+            const touch = evt.changedTouches[i];
+            this.prev.delete(touch.identifier);
+        }
     }
     private touchMove = (evt: TouchEvent) => {
         if (evt.defaultPrevented) return;
@@ -593,7 +602,7 @@
             }
             const touch = evt.touches[0];
             const prev = this.prev.get(touch.identifier);
-            if (!prev) return;
+            if (!prev || prev.ignore) return;
             const pos = this.getPositionOnPlane(touch.clientX, touch.clientY);
             const dx = pos.x - prev.x;
             const dy = pos.z - prev.z;

src/engine-components/webxr/WebXRButtons.ts CHANGED Viewed

@@ -1,10 +1,9 @@
 import { isDevEnvironment } from "../../engine/debug/index.js";
-import { generateQRCode } from "../../engine/engine_utils.js";
 import { isMozillaXR } from "../../engine/engine_utils.js";
 import { NeedleXRSession } from "../../engine/engine_xr.js";
 import { ButtonsFactory } from "../../engine/webcomponents/buttons.js";
 import { getIconElement } from "../../engine/webcomponents/icons.js";
-import { onXRSessionStart } from "../../engine/xr/events.js";
+import { onXRSessionEnd, onXRSessionStart } from "../../engine/xr/events.js";
 import { GameObject } from "../Component.js";
 import { USDZExporter } from "../export/usdz/USDZExporter.js";
@@ -62,7 +61,7 @@
             const usdzExporter = GameObject.findObjectOfType(USDZExporter);
             if (usdzExporter) {
                 button.classList.add("this-mode-is-requested");
-                usdzExporter.exportAsync().then(() => {
+                usdzExporter.exportAndOpen().then(() => {
                     button.classList.remove("this-mode-is-requested");
                 }).catch(err => {
                     button.classList.remove("this-mode-is-requested");
@@ -198,13 +197,10 @@
     private hideElementDuringXRSession(element: HTMLElement) {
         onXRSessionStart(_ => {
-        })
-        onXRSessionStart
-        NeedleXRSession.onXRSessionStart(_ => {
             element["previous-display"] = element.style.display;
             element.style.display = "none";
         });
-        NeedleXRSession.onXRSessionEnd(_ => {
+        onXRSessionEnd(_ => {
             if (element["previous-display"] != undefined)
                 element.style.display = element["previous-display"];
         });