@needle-tools/engine 5.1.0-alpha.1 → 5.1.0-alpha.3

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

@@ -1,8 +1,10 @@
 import { isDevEnvironment } from "../debug/index.js";
+import { HTMLElementBase } from "../engine_ssr.js";
 import { ButtonsFactory } from "./buttons.js";
 import { iconFontUrl, loadFont } from "./fonts.js";
 import { WebXRButtonFactory } from "./WebXRButtons.js";
 
+// NOTE: keep JSX attributes in sync with ./jsx.d.ts
 declare global {
     interface HTMLElementTagNameMap {
         "needle-button": NeedleButtonElement;
@@ -65,7 +67,7 @@ const isDev = isDevEnvironment();
  * @see {@link NeedleEngineWebComponent} for the main <needle-engine> element
  * @see {@link NeedleMenu} for the built-in menu component that can display similar buttons
  */
-export class NeedleButtonElement extends HTMLElement {
+export class NeedleButtonElement extends HTMLElementBase {
 
     static observedAttributes = ["ar", "vr", "quicklook", "qrcode"];
 

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

@@ -5,6 +5,7 @@ import { hasCommercialLicense } from "../engine_license.js";
 import { onStart } from "../engine_lifecycle_api.js";
 import { setDracoDecoderPath, setDracoDecoderType, setKtx2TranscoderPath } from "../engine_loaders.gltf.js";
 import { Context, ContextCreateArgs } from "../engine_setup.js";
+import { HTMLElementBase } from "../engine_ssr.js";
 import { nameToThreeTonemapping } from "../engine_tonemapping.js";
 import { type INeedleEngineComponent, type LoadedModel } from "../engine_types.js";
 import type { addAttributeChangeCallback } from "../engine_utils.js";
@@ -16,6 +17,7 @@ import { arContainerClassName, AROverlayHandler } from "./needle-engine.ar-overl
 import type { registerObservableAttribute } from "./needle-engine.extras.js";
 import { calculateProgress01, EngineLoadingView, type ILoadingViewHandler } from "./needle-engine.loading.js";
 
+// NOTE: keep JSX attributes in sync with ./jsx.d.ts
 declare global {
     interface HTMLElementTagNameMap {
         "needle-engine": NeedleEngineWebComponent;
@@ -40,11 +42,17 @@ export interface NeedleEngineAttributes {
     'hash': string;
     /** Set to automatically add OrbitControls to the loaded scene. */
     'camera-controls': string;
-    /** Override the default draco decoder path location. */
+    /** Override the default Draco decoder/decompressor path. Can be a URL or a local path to a directory containing the Draco decoder files.
+     * @default "https://www.gstatic.com/draco/versioned/decoders/1.5.7/"
+     * @example <needle-engine dracoDecoderPath="./decoders/draco/"></needle-engine>
+     */
     'dracoDecoderPath': string;
-    /** Override the default draco library type. */
+    /** Override the default Draco decoder type. */
     'dracoDecoderType': 'wasm' | 'js';
-    /** Override the default KTX2 transcoder/decoder path. */
+    /** Override the default KTX2 transcoder/decoder path. Can be a URL or a local path to a directory containing the KTX2 transcoder files.
+     * @default "https://cdn.needle.tools/static/three/0.179.1/basis2/"
+     * @example <needle-engine ktx2DecoderPath="./decoders/ktx2/"></needle-engine>
+     */
     'ktx2DecoderPath': string;
     /** Prevent context from being disposed when element is removed from DOM. */
     'keep-alive': 'true' | 'false';
@@ -153,7 +161,7 @@ const observedAttributes = [
  * @see {@link NeedleButtonElement} for adding AR/VR/Quicklook buttons via &lt;needle-button&gt;
  * @see {@link NeedleMenu} for the built-in menu configuration component
  */
-export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngineComponent {
+export class NeedleEngineWebComponent extends HTMLElementBase implements INeedleEngineComponent {
 
     static get observedAttributes() {
         return observedAttributes;

package/src/engine/xr/NeedleXRSession.ts

@@ -207,7 +207,7 @@ function waitForContextLoadingFinished(): Promise<void> {
 }
 
 
-if (DeviceUtilities.isDesktop() && isDevEnvironment()) {
+if (typeof window !== "undefined" && DeviceUtilities.isDesktop() && isDevEnvironment()) {
     window.addEventListener("keydown", (evt) => {
         if (evt.key === "x" || evt.key === "Escape") {
             if (NeedleXRSession.active) {
@@ -840,15 +840,16 @@ export class NeedleXRSession implements INeedleXRSession {
     get viewerPose(): XRViewerPose | undefined { return this._viewerPose; }
 
 
-    /** @returns `true` if any image is currently being tracked */
-    /** returns true if images are currently being tracked */
+    /** @returns `true` if any image is currently being tracked or emulated */
     get isTrackingImages() {
         if (this.frame && "getImageTrackingResults" in this.frame && typeof this.frame.getImageTrackingResults === "function") {
             try {
                 const trackingResult = this.frame.getImageTrackingResults();
                 for (const result of trackingResult) {
                     const state = result.trackingState;
-                    if (state === "tracked") return true;
+                    if (state === "tracked" || state === "emulated") {
+                        return true;
+                    }
                 }
             }
             catch {
@@ -1053,6 +1054,8 @@ export class NeedleXRSession implements INeedleXRSession {
     private readonly _xr_update_scripts: INeedleXRSessionEventReceiver[] = [];
     /** scripts that are in the scene but inactive (e.g. disabled parent gameObject) */
     private readonly _inactive_scripts: INeedleXRSessionEventReceiver[] = [];
+    /** tracks scripts that have received onEnterXR — prevents spurious onLeaveXR calls */
+    private readonly _scripts_in_xr = new Set<INeedleXRSessionEventReceiver>();
     private readonly _controllerAdded: ControllerChangedEvt[];
     private readonly _controllerRemoved: ControllerChangedEvt[];
     private readonly _originalCameraWorldPosition?: Vector3 | null;
@@ -1163,7 +1166,18 @@ export class NeedleXRSession implements INeedleXRSession {
         // we set the session on the webxr manager at the end because we want to receive inputsource events first
         // e.g. in case there's a bug in the threejs codebase
         this.context.xr = this;
-        this.context.renderer.xr.setSession(this.session).then(this.onRendererSessionSet);
+        this.context.renderer.xr.setSession(this.session).then(this.onRendererSessionSet)
+            .catch(err => {
+                // Workaround for WebXR emulators on localhost: the polyfilled XRSession fails the
+                // native XRWebGLBinding constructor's instanceof check. Retry with layers disabled.
+                // See https://github.com/meta-quest/immersive-web-emulator/issues/80
+                if (isDevEnvironment() && err instanceof TypeError && typeof XRWebGLBinding !== "undefined") {
+                    console.error(`XRWebGLBinding failed (${err.message}).\nSee https://github.com/meta-quest/immersive-web-emulator/issues/80`);
+                }
+                else {
+                    console.error("renderer.xr.setSession failed:", err);
+                }
+            });
         // disable three.js renderer controller autoUpdate (added in ac67b31e3548386f8a93e23a4176554c92bbd0d9)
         if ("controllerAutoUpdate" in this.context.renderer.xr) {
             console.debug("Disabling three.js controllerAutoUpdate");
@@ -1331,8 +1345,10 @@ export class NeedleXRSession implements INeedleXRSession {
         // even if they might already be destroyed e.g. by the WebXR component (it destroys the default controller scripts)
         // they should still receive this callback to be properly cleaned up
         for (const listener of this._xr_scripts) {
+            this._scripts_in_xr.delete(listener);
             listener?.onLeaveXR?.({ xr: this });
         }
+        this._scripts_in_xr.clear();
 
         this.sync?.onExitXR(this);
 
@@ -1399,10 +1415,17 @@ export class NeedleXRSession implements INeedleXRSession {
         }
 
         // make sure the camera is parented to the active rig
-        if (this.rig && this._mainCamera?.gameObject) {
-            const currentParent = this._mainCamera?.gameObject?.parent;
-            if (currentParent !== this.rig.gameObject) {
-                this.rig.gameObject.add(this._mainCamera?.gameObject);
+        // Note: applyCustomForward() inserts _cameraRenderParent between rig and camera,
+        // so the hierarchy is: rig → _cameraRenderParent → camera. We check the effective parent.
+        if (this.rig) {
+            const cameraObject = this._mainCamera?.gameObject ?? this.context.mainCamera;
+            if (cameraObject) {
+                const effectiveParent = cameraObject.parent === this._cameraRenderParent
+                    ? this._cameraRenderParent.parent
+                    : cameraObject.parent;
+                if (effectiveParent !== this.rig.gameObject) {
+                    this.rig.gameObject.add(cameraObject);
+                }
             }
         }
 
@@ -1534,8 +1557,12 @@ export class NeedleXRSession implements INeedleXRSession {
         }
 
         //performance.mark('NeedleXRSession update scripts start');
-        // invoke update on all scripts
-        for (const script of this._xr_update_scripts) {
+        // check all XR scripts for destroyed or inactive state
+        // this must cover _xr_scripts (not just _xr_update_scripts) so that scripts
+        // without onUpdateXR are also detected as inactive when removed from the scene
+        // iterate backwards since markInactive/removeScript modifies the array
+        for (let i = this._xr_scripts.length - 1; i >= 0; i--) {
+            const script = this._xr_scripts[i];
             if (script.destroyed === true) {
                 this._script_to_remove.push(script);
                 continue;
@@ -1544,6 +1571,10 @@ export class NeedleXRSession implements INeedleXRSession {
                 this.markInactive(script);
                 continue;
             }
+        }
+        // invoke update on scripts that have onUpdateXR
+        for (const script of this._xr_update_scripts) {
+            if (script.destroyed || script.activeAndEnabled === false) continue;
             if (script.onUpdateXR) script.onUpdateXR(args);
         }
         //performance.mark('NeedleXRSession update scripts end');
@@ -1666,9 +1697,11 @@ export class NeedleXRSession implements INeedleXRSession {
                 const script = this._inactive_scripts[i];
                 if (script.activeAndEnabled) {
                     this._inactive_scripts.splice(i, 1);
-                    this.addScript(script);
-                    this.invokeCallback_EnterXR(script);
-                    for (const ctrl of this.controllers) this.invokeCallback_ControllerAdded(script, ctrl);
+                    // addScript returns false if already re-added (e.g. via new_scripts_xr processing)
+                    if (this.addScript(script)) {
+                        this.invokeCallback_EnterXR(script);
+                        for (const ctrl of this.controllers) this.invokeCallback_ControllerAdded(script, ctrl);
+                    }
                 }
             }
         }
@@ -1689,6 +1722,7 @@ export class NeedleXRSession implements INeedleXRSession {
     }
 
     private invokeCallback_EnterXR(script: INeedleXRSessionEventReceiver) {
+        this._scripts_in_xr.add(script);
         if (script.onEnterXR) {
             script.onEnterXR({ xr: this });
         }
@@ -1704,6 +1738,7 @@ export class NeedleXRSession implements INeedleXRSession {
         }
     }
     private invokeCallback_LeaveXR(script: INeedleXRSessionEventReceiver) {
+        if (!this._scripts_in_xr.delete(script)) return;
         if (script.onLeaveXR && !script.destroyed) {
             script.onLeaveXR({ xr: this });
         }

package/src/engine/xr/events.ts

@@ -1,5 +1,5 @@
-import { NeedleXRSession } from "./NeedleXRSession.js";
 import type { Context } from "../engine_context.js";
+import { NeedleXRSession } from "./NeedleXRSession.js";
 
 export declare type XRSessionEventArgs = { session: NeedleXRSession };
 

package/src/engine-components/Animation.ts

@@ -447,25 +447,13 @@ export class Animation extends Behaviour implements IAnimationComponent {
 
     private internalOnPlay(action: AnimationAction, options: PlayOptions): Promise<AnimationAction> {
         var existing = this.actions.find(a => a === action);
-        if (existing === action && existing.isRunning() && existing.time < existing.getClip().duration) {
-            const handle = this.tryFindHandle(action);
-            if (existing.paused) {
-                existing.paused = false;
-            }
-            if (handle) return handle.waitForFinish();
-        }
 
-        // Assign defaults
-        if (options.loop === undefined) options.loop = this.loop;
-        if (options.clampWhenFinished === undefined) options.clampWhenFinished = this.clampWhenFinished;
-        if (options.minMaxOffsetNormalized === undefined && this.randomStartTime) options.minMaxOffsetNormalized = this.minMaxOffsetNormalized;
-        if (options.minMaxSpeed === undefined) options.minMaxSpeed = this.minMaxSpeed;
-
-        // Reset currently running animations
+        // Stop other animations before the early-return check so exclusive always applies,
+        // even when the target animation is already running.
         const stopOther = options?.exclusive ?? true;
         if (stopOther) {
             for (const act of this.actions) {
-                if (act != existing) {
+                if (act !== action) {
                     if (options.fadeDuration) {
                         act.fadeOut(options.fadeDuration);
                     }
@@ -475,6 +463,20 @@ export class Animation extends Behaviour implements IAnimationComponent {
                 }
             }
         }
+
+        if (existing === action && existing.isRunning() && existing.time < existing.getClip().duration) {
+            const handle = this.tryFindHandle(action);
+            if (existing.paused) {
+                existing.paused = false;
+            }
+            if (handle) return handle.waitForFinish();
+        }
+
+        // Assign defaults
+        if (options.loop === undefined) options.loop = this.loop;
+        if (options.clampWhenFinished === undefined) options.clampWhenFinished = this.clampWhenFinished;
+        if (options.minMaxOffsetNormalized === undefined && this.randomStartTime) options.minMaxOffsetNormalized = this.minMaxOffsetNormalized;
+        if (options.minMaxSpeed === undefined) options.minMaxSpeed = this.minMaxSpeed;
         if (options?.fadeDuration) {
             action.fadeIn(options.fadeDuration);
         }
@@ -515,10 +517,11 @@ export class Animation extends Behaviour implements IAnimationComponent {
 
         action.paused = false;
         action.play();
+        if (debug) console.log("[Animation] Now Playing", action.getClip().name, action)
+
 
         window.requestAnimationFrame(() => AnimationUtils.testIfRootCanAnimate(action));
 
-        if (debug) console.log("PLAY", action.getClip().name, action)
         const handle = new AnimationHandle(action, this.mixer!, options, _ => {
             this._handles.splice(this._handles.indexOf(handle), 1);
         });

package/src/engine-components/AnimatorController.ts

@@ -1586,4 +1586,7 @@ class AnimatorControllerSerializator extends TypeSerializer {
         return undefined;
     }
 }
-new AnimatorControllerSerializator(AnimatorController);
+/** @internal */
+export function initAnimatorControllerSerializer() {
+    new AnimatorControllerSerializator(AnimatorController);
+}