@needle-tools/engine 4.16.4-alpha → 4.16.4-beta

package/src/engine/engine_lods.ts

@@ -14,8 +14,10 @@ const _tempBox: Box3 = new Box3();
 const _tempSphere: Sphere = new Sphere();
 
 /**
- * Needle Engine LODs manager. Wrapper around the internal LODs manager.  
- * It uses the @needle-tools/gltf-progressive package to manage LODs.
+ * Needle Engine LODs manager. Wrapper around the internal LODs manager.
+ * It uses the [@needle-tools/gltf-progressive](https://npmjs.com/package/@needle-tools/gltf-progressive) package to manage LODs.
+ *
+ * For lower-level control (e.g. configuring max concurrent loading tasks, queue settings, or other progressive loading specifics), use {@link NEEDLE_progressive} directly.
  * @link https://npmjs.com/package/@needle-tools/gltf-progressive
  */
 export class LODsManager implements NEEDLE_progressive_plugin {
@@ -37,6 +39,11 @@ export class LODsManager implements NEEDLE_progressive_plugin {
         return this._lodsManager;
     }
 
+    /**
+     * The interval (in seconds) at which the bounding volumes of skinned meshes are automatically updated.  
+     * If set to 0, automatic updates are disabled and bounding volumes will only be updated when the mesh is loaded or when the `updateSkinnedMeshBounds` method is called manually.  
+     * @default 0
+     */
     get skinnedMeshAutoUpdateBoundsInterval() {
         return this._lodsManager?.skinnedMeshAutoUpdateBoundsInterval || this._settings.skinnedMeshAutoUpdateBoundsInterval || 0;
     }
@@ -57,6 +64,7 @@ export class LODsManager implements NEEDLE_progressive_plugin {
         this.applySettings();
     }
 
+    /** @internal */
     constructor(context: Context) {
         this.context = context;
     }

package/src/engine/engine_mainloop_utils.ts

@@ -270,6 +270,10 @@ export function isNeedleXRSessionEventReceiver(script: any, mode: XRSessionMode
 }
 
 
+
+
+// #region activeInHierarchy
+
 let needsUpdate = true;
 export function markHierarchyDirty() {
     needsUpdate = true;
@@ -304,7 +308,7 @@ export function updateIsActive(obj?: Object3D, force: boolean = false) {
     }
 }
 
-function updateIsActiveInHierarchyRecursiveRuntime(go: Object3D, activeInHierarchy: boolean, allowEventCall: boolean, level: number = 0) {
+function updateIsActiveInHierarchyRecursiveRuntime(go: Object3D, activeInHierarchy: boolean, allowEventCall: boolean, level: number = 0): boolean {
     if (level > 1000) {
         console.warn("Hierarchy is too deep (> 1000 level) - will abort updating active state");
         return false;
@@ -336,74 +340,70 @@ function updateIsActiveInHierarchyRecursiveRuntime(go: Object3D, activeInHierarc
         go[constants.activeInHierarchyFieldName] = activeInHierarchy;
 
         if (debugHierarchy)
-            console.warn("ACTIVE CHANGE", go.name, activeSelf, go.visible, activeInHierarchy, "changed?" + changed, go);
+            console.warn("ACTIVE CHANGE", { name: go.name, activeSelf, visible: go.visible, activeInHierarchy, changed, go });
         if (allowEventCall) {
-            perComponent(go, comp => {
-                if (activeInHierarchy) {
-                    if (comp.enabled) {
-                        safeInvoke(comp.__internalAwake.bind(comp));
+            const components = go.userData?.components;
+            if (components) {
+                for (let ci = 0, cl = components.length; ci < cl; ci++) {
+                    const comp = components[ci];
+                    if (activeInHierarchy) {
                         if (comp.enabled) {
-                            comp.__internalEnable();
+                            try { comp.__internalAwake(); }
+                            catch (err) { console.error(err); }
+                            if (comp.enabled) {
+                                comp.__internalEnable();
+                            }
                         }
                     }
-                }
-                else {
-                    if (comp["__didAwake"] && comp.enabled) {
-                        comp["__didEnable"] = false;
-                        comp.onDisable();
+                    else {
+                        if (comp["__didAwake"] && comp.enabled) {
+                            comp["__didEnable"] = false;
+                            comp.onDisable();
+                        }
                     }
                 }
-            });
+            }
         }
     }
-
-    let success = true;
-    if (go.children) {
-        for (const ch of go.children) {
-            const res = updateIsActiveInHierarchyRecursiveRuntime(ch, activeInHierarchy, allowEventCall, level + 1);
-            if (res === false) success = false;
+    const children = go.children;
+    if (children) {
+        // When this node is inactive and hasn't changed, skip children that are already
+        // marked inactive. Only recurse into children that still have a stale active=true
+        // (e.g. after reparenting into this inactive subtree).
+        if (!changed && !activeInHierarchy) {
+            let success = true;
+            for (let i = 0, l = children.length; i < l; i++) {
+                const ch = children[i];
+                if (ch[constants.activeInHierarchyFieldName] !== false) {
+                    if (updateIsActiveInHierarchyRecursiveRuntime(ch, false, allowEventCall, level + 1) === false)
+                        success = false;
+                }
+            }
+            return success;
         }
+        let success = true;
+        for (let i = 0, l = children.length; i < l; i++) {
+            if (updateIsActiveInHierarchyRecursiveRuntime(children[i], activeInHierarchy, allowEventCall, level + 1) === false)
+                success = false;
+        }
+        return success;
     }
-    return success;
+    return true;
 }
 
-// function tryFindActiveStateInParent(obj: Object3D): boolean {
-//     let current: Object3D | undefined | null = obj;
-//     while (current) {
-//         const activeState = current[constants.activeInHierarchyFieldName];
-//         if (activeState !== undefined) return activeState;
-//         if (current instanceof Scene && !current.parent) {
-//             return true;
-//         }
-//         current = current.parent;
-//     }
-//     return false;
-// }
-
-// let isRunning = false;
-// // Prevent: https://github.com/needle-tools/needle-tiny/issues/641
-// const temporyChildArrayBuffer: Array<Array<Object3D>> = [];
-// export function* iterateChildrenSafe(obj: Object3D) {
-//     if (!obj || !obj.children) yield null;
-//     // if(isRunning) return;
-//     // isRunning = true;
-//     const arr = temporyChildArrayBuffer.pop() || [];
-//     arr.push(...obj.children);
-//     for (const ch of arr) {
-//         yield ch;
-//     }
-//     // isRunning = false;
-//     arr.length = 0;
-//     temporyChildArrayBuffer.push(arr);
-// }
+
+
 
 /** @internal */
 export function updateActiveInHierarchyWithoutEventCall(go: Object3D) {
+    if (!go) {
+        console.error("GO is null");
+        return;
+    }
     let activeInHierarchy = true;
+    let foundScene = false;
     let current: Object3D | null = go;
-    let foundScene: boolean = false;
     while (current) {
-        if (!current) break;
         if (current.type === "Scene") foundScene = true;
         if (!isActiveSelf(current)) {
             activeInHierarchy = false;
@@ -411,22 +411,14 @@ export function updateActiveInHierarchyWithoutEventCall(go: Object3D) {
         }
         current = current.parent;
     }
-    if (!go) {
-        console.error("GO is null");
-        return;
-    }
     go[constants.activeInHierarchyFieldName] = activeInHierarchy && foundScene;
 }
 
-function perComponent(go: Object3D, evt: (comp: IComponent) => void) {
-    if (go.userData?.components) {
-        for (const comp of go.userData.components) {
-            evt(comp);
-        }
-    }
-}
 
 
+
+// #region prewarm
+
 const prewarmList: Map<IContext, Object3D[]> = new Map();
 const $prewarmedFlag = Symbol("prewarmFlag");
 const $waitingForPrewarm = Symbol("waitingForPrewarm");

package/src/engine/webcomponents/needle-engine.ts

@@ -168,7 +168,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
      */
     public get context() { return this._context; }
 
-    private _context!: Context;
+    private _context?: Context;
     private _overlay_ar!: AROverlayHandler;
     private _loadingProgress01: number = 0;
     private _loadingView?: ILoadingViewHandler;
@@ -298,12 +298,10 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
 
 
         this._overlay_ar = new AROverlayHandler();
-        this._context ??= new Context({ domElement: this }); // we might have one already if onLoad is running
+        this.getOrCreateContext();
         this.addEventListener("xr-session-started", this.onXRSessionStarted);
         this.onSetupDesktop();
 
-
-
         if (!this.getAttribute("src")) {
             const global = (globalThis as any)["needle:codegen_files"] as unknown as string;
             if (debug) console.log("src is null, trying to load from globalThis[\"needle:codegen_files\"]", global);
@@ -418,18 +416,23 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
             case "focus-rect":
                 {
                     const focus_rect = this.getAttribute("focus-rect") as HTMLElement | string | null;
-                    if (focus_rect && this._context) {
+                    if (focus_rect) {
+                        const context = this.getOrCreateContext();
+
                         if (focus_rect === null) {
-                            this._context.setCameraFocusRect(null);
+                            context.setCameraFocusRect(null);
                         }
                         else if (typeof focus_rect === "string" && focus_rect.length > 0) {
                             const element = document.querySelector(focus_rect);
-                            this._context.setCameraFocusRect(element instanceof HTMLElement ? element : null);
+                            if (!element) console.warn(`No element found for focus-rect selector: ${focus_rect}`);
+                            context.setCameraFocusRect(element instanceof HTMLElement ? element : null);
                         }
                         else if (focus_rect instanceof HTMLElement) {
-                            this._context.setCameraFocusRect(focus_rect);
+                            context.setCameraFocusRect(focus_rect);
+                        }
+                        else {
+                            console.warn("Invalid focus-rect value. Expected a CSS selector string or an HTMLElement.", focus_rect);
                         }
-
                     }
                 }
                 break;
@@ -447,19 +450,22 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
     private _lastSourceFiles: Array<string> | null = null;
     private _createContextPromise: Promise<boolean> | null = null;
 
-    private async onLoad() {
-
-        if (!this.isConnected) return;
-
+    /**
+     * Check if we have a context. If not a new one is created.
+     */
+    private getOrCreateContext() {
         if (!this._context) {
             if (debug) console.warn("Create new context");
             this._context = new Context({ domElement: this });
         }
+        return this._context;
+    }
 
-        if (!this._context) {
-            console.error("Needle Engine: Context not initialized");
-            return;
-        }
+    private async onLoad() {
+
+        if (!this.isConnected) return;
+
+        const context = this.getOrCreateContext();
 
         const filesToLoad = this.getSourceFiles();
         if (!this.checkIfSourceHasChanged(filesToLoad, this._lastSourceFiles)) {
@@ -477,7 +483,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
 
         if (filesToLoad === null || filesToLoad === undefined || filesToLoad.length <= 0) {
             if (debug) console.warn("Clear scene", filesToLoad);
-            this._context.clear();
+            context.clear();
             if (loadId !== this._loadId) return;
         }
 
@@ -491,7 +497,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         this.ensureLoadStartIsRegistered();
         let useDefaultLoading = this.dispatchEvent(new CustomEvent("loadstart", {
             detail: {
-                context: this._context,
+                context: context,
                 alias: alias
             },
             cancelable: true
@@ -581,9 +587,9 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
 
         const currentHash = this.getAttribute("hash");
         if (currentHash !== null && currentHash !== undefined)
-            this._context.hash = currentHash;
-        this._context.alias = alias;
-        this._createContextPromise = this._context.create(args);
+            context.hash = currentHash;
+        context.alias = alias;
+        this._createContextPromise = context.create(args);
         const success = await this._createContextPromise;
         this.applyAttributes();
 
@@ -615,42 +621,45 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
 
     // #region applyAttributes
     private applyAttributes() {
+
+        const context = this.getOrCreateContext();
+
         // set tonemapping if configured
-        if (this._context?.renderer) {
+        if (context.renderer) {
             const threeTonemapping = nameToThreeTonemapping(this.toneMapping);
             if (threeTonemapping !== undefined) {
-                this._context.renderer.toneMapping = threeTonemapping;
+                context.renderer.toneMapping = threeTonemapping;
             }
             const exposure = this.getAttribute("tone-mapping-exposure");
             if (exposure !== null && exposure !== undefined) {
                 const value = parseFloat(exposure);
                 if (!isNaN(value))
-                    this._context.renderer.toneMappingExposure = value;
+                    context.renderer.toneMappingExposure = value;
             }
         }
 
         const backgroundBlurriness = this.getAttribute("background-blurriness");
         if (backgroundBlurriness !== null && backgroundBlurriness !== undefined) {
             const value = parseFloat(backgroundBlurriness);
-            if (!isNaN(value) && this._context) {
-                this._context.scene.backgroundBlurriness = value;
+            if (!isNaN(value)) {
+                context.scene.backgroundBlurriness = value;
             }
         }
 
         const environmentIntensity = this.getAttribute("environment-intensity");
-        if (environmentIntensity != undefined && this._context) {
+        if (environmentIntensity != undefined) {
             const value = parseFloat(environmentIntensity);
-            if (!isNaN(value) && this._context)
-                this._context.scene.environmentIntensity = value;
+            if (!isNaN(value))
+                context.scene.environmentIntensity = value;
         }
 
         const backgroundColor = this.getAttribute("background-color");
-        if (this._context?.renderer) {
+        if (context.renderer) {
             if (typeof backgroundColor === "string" && backgroundColor.length > 0) {
                 const rgbaColor = RGBAColor.fromColorRepresentation(backgroundColor);
                 if (debug) console.debug("<needle-engine> background-color changed, str:", backgroundColor, "→", rgbaColor)
-                this._context.renderer.setClearColor(rgbaColor, rgbaColor.alpha);
-                this.context.scene.background = null;
+                context.renderer.setClearColor(rgbaColor, rgbaColor.alpha);
+                context.scene.background = null;
             }
             // HACK: if we set background-color to a color and then back to null we want the background-image attribute to re-apply
             else if (this.getAttribute("background-image")) {
@@ -660,19 +669,21 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
     }
 
     private onXRSessionStarted = () => {
-        const xrSessionMode = this.context.xrSessionMode;
+        const context = this.getOrCreateContext();
+
+        const xrSessionMode = context.xrSessionMode;
         if (xrSessionMode === "immersive-ar")
-            this.onEnterAR(this.context.xrSession!);
+            this.onEnterAR(context.xrSession!);
         else if (xrSessionMode === "immersive-vr")
-            this.onEnterVR(this.context.xrSession!);
+            this.onEnterVR(context.xrSession!);
 
         // handle session end:
-        this.context.xrSession?.addEventListener("end", () => {
-            this.dispatchEvent(new CustomEvent("xr-session-ended", { detail: { session: this.context.xrSession, context: this._context, sessionMode: xrSessionMode } }));
+        context.xrSession?.addEventListener("end", () => {
+            this.dispatchEvent(new CustomEvent("xr-session-ended", { detail: { session: context.xrSession, context: this._context, sessionMode: xrSessionMode } }));
             if (xrSessionMode === "immersive-ar")
-                this.onExitAR(this.context.xrSession!);
+                this.onExitAR(context.xrSession!);
             else if (xrSessionMode === "immersive-vr")
-                this.onExitVR(this.context.xrSession!);
+                this.onExitVR(context.xrSession!);
         });
     };
 
@@ -741,7 +752,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
                 if (typeof fn === "function") {
                     this._previouslyRegisteredMap.set(eventName, fn);
                     // @ts-ignore // not sure how to type this properly
-                    this.addEventListener(eventName, evt => fn?.call(globalThis, this._context, evt));
+                    this.addEventListener(eventName, evt => fn?.call(globalThis, this.getOrCreateContext(), evt));
                 }
             }
             catch (err) {
@@ -783,35 +794,39 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
      * @internal
      */
     onEnterAR(session: XRSession) {
+        const context = this.getOrCreateContext();
         this.onSetupAR();
         const overlayContainer = this.getAROverlayContainer();
-        this._overlay_ar.onBegin(this._context!, overlayContainer, session);
-        this.dispatchEvent(new CustomEvent("enter-ar", { detail: { session: session, context: this._context, htmlContainer: this._overlay_ar?.ARContainer } }));
+        this._overlay_ar.onBegin(context, overlayContainer, session);
+        this.dispatchEvent(new CustomEvent("enter-ar", { detail: { session: session, context: context, htmlContainer: this._overlay_ar?.ARContainer } }));
     }
 
     /**
      * @internal
      */
     onExitAR(session: XRSession) {
-        this._overlay_ar.onEnd(this._context!);
+        const context = this.getOrCreateContext();
+        this._overlay_ar.onEnd(context);
         this.onSetupDesktop();
-        this.dispatchEvent(new CustomEvent("exit-ar", { detail: { session: session, context: this._context, htmlContainer: this._overlay_ar?.ARContainer } }));
+        this.dispatchEvent(new CustomEvent("exit-ar", { detail: { session: session, context: context, htmlContainer: this._overlay_ar?.ARContainer } }));
     }
 
     /**
      * @internal
      */
     onEnterVR(session: XRSession) {
+        const context = this.getOrCreateContext();
         this.onSetupVR();
-        this.dispatchEvent(new CustomEvent("enter-vr", { detail: { session: session, context: this._context } }));
+        this.dispatchEvent(new CustomEvent("enter-vr", { detail: { session: session, context: context } }));
     }
 
     /**
      * @internal
      */
     onExitVR(session: XRSession) {
+        const context = this.getOrCreateContext();
         this.onSetupDesktop();
-        this.dispatchEvent(new CustomEvent("exit-vr", { detail: { session: session, context: this._context } }));
+        this.dispatchEvent(new CustomEvent("exit-vr", { detail: { session: session, context: context } }));
     }
 
     private onSetupAR() {