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

package/src/engine/engine_serialization_builtin_serializer.ts

@@ -4,6 +4,7 @@ import { isDevEnvironment, showBalloonMessage, showBalloonWarning } from "../eng
 import { Behaviour, Component, GameObject } from "../engine-components/Component.js";
 import { CallInfo, EventList } from "../engine-components/EventList.js";
 import { AssetReference } from "./engine_addressables.js";
+import { AudioClip } from "./engine_audio.js";
 import { debugExtension } from "./engine_default_parameters.js";
 import { SerializationContext, TypeSerializer } from "./engine_serialization_core.js";
 import { RenderTexture } from "./engine_texture.js";
@@ -11,25 +12,7 @@ import { IComponent } from "./engine_types.js";
 import { resolveUrl } from "./engine_utils.js";
 import { RGBAColor } from "./js-extensions/index.js";
 
-// export class SourcePath {
-//     src?:string
-// };
-
-// class SourcePathSerializer extends TypeSerializer{
-//     constructor(){
-//         super(SourcePath);
-//     }
-//     onDeserialize(data: any, _context: SerializationContext) {
-//         if(data.src && typeof data.src === "string"){
-//             return data.src;
-//         }
-//     }
-//     onSerialize(_data: any, _context: SerializationContext) {
-
-//     }
-// }
-// new SourcePathSerializer();
-
+// #region Color
 class ColorSerializer extends TypeSerializer {
     constructor() {
         super([Color, RGBAColor], "ColorSerializer")
@@ -52,7 +35,8 @@ class ColorSerializer extends TypeSerializer {
             return { r: data.r, g: data.g, b: data.b }
     }
 }
-export const colorSerializer = new ColorSerializer();
+
+// #region Euler
 
 class EulerSerializer extends TypeSerializer {
     constructor() {
@@ -72,12 +56,13 @@ class EulerSerializer extends TypeSerializer {
         return { x: data.x, y: data.y, z: data.z, order: data.order };
     }
 }
-export const euler = new EulerSerializer();
 
 declare type ObjectData = {
     node?: number;
     guid?: string;
 }
+
+// #region ObjectSerializer
 class ObjectSerializer extends TypeSerializer {
     constructor() {
         super(Object3D, "ObjectSerializer");
@@ -107,16 +92,6 @@ class ObjectSerializer extends TypeSerializer {
                 console.warn(`Wrong usage of @serializable detected in your script \"${scriptname}\"\n\nIt looks like you used @serializable(Object3D) or @serializable(GameObject) for a prefab or scene reference which is exported to a separate glTF file.\n\nTo fix this please change your code to:\n\n@serializable(AssetReference)\n${context.path}! : AssetReference;\n\0`);
             }
             // ACTUALLY: this is already handled by the extension_utils where we resolve json pointers recursively
-            // if(data.startsWith("/nodes/")){
-            //     const node = parseInt(data.substring("/nodes/".length));
-            //     if (context.nodeToObject) {
-            //         const res = context.nodeToObject[node];
-            //         if (debugExtension)
-            //             console.log("Deserialized object reference?", data, res, context?.nodeToObject);
-            //         if (!res) console.warn("Did not find node: " + data, context.nodeToObject, context.object);
-            //         return res;
-            //     }
-            // }
             return undefined;
         }
 
@@ -166,9 +141,8 @@ class ObjectSerializer extends TypeSerializer {
         return undefined;
     }
 }
-export const objectSerializer = new ObjectSerializer();
-
 
+// #region ComponentSerializer
 class ComponentSerializer extends TypeSerializer {
 
     constructor() {
@@ -241,7 +215,6 @@ class ComponentSerializer extends TypeSerializer {
         }
     }
 }
-export const componentSerializer = new ComponentSerializer();
 
 
 declare class EventListData {
@@ -258,6 +231,7 @@ declare type EventListCall = {
 
 const $eventListDebugInfo = Symbol("eventListDebugInfo");
 
+// #region EventListSerializer
 class EventListSerializer extends TypeSerializer {
     constructor() {
         super([EventList]);
@@ -396,22 +370,14 @@ class EventListSerializer extends TypeSerializer {
     //     };
     // }
 }
-export const eventListSerializer = new EventListSerializer();
 
 
 /** Map<Clone, Original> texture. This is used for compressed textures (or when the GLTFLoader is cloning RenderTextures)
  * It's a weak map so we don't have to worry about memory leaks
  */
 const cloneOriginalMap = new WeakMap<Texture, Texture>();
-const textureClone = Texture.prototype.clone;
-Texture.prototype.clone = function () {
-    const clone = textureClone.call(this);
-    if (!cloneOriginalMap.has(clone)) {
-        cloneOriginalMap.set(clone, this);
-    }
-    return clone;
-}
 
+// #region RenderTextureSerializer
 export class RenderTextureSerializer extends TypeSerializer {
     constructor() {
         super([RenderTexture, WebGLRenderTarget]);
@@ -452,9 +418,8 @@ export class RenderTextureSerializer extends TypeSerializer {
         return undefined;
     }
 }
-new RenderTextureSerializer();
-
 
+// #region UriSerializer
 export class UriSerializer extends TypeSerializer {
     constructor() {
         super([URL]);
@@ -471,4 +436,56 @@ export class UriSerializer extends TypeSerializer {
         return undefined;
     }
 }
-new UriSerializer();
+
+// #region AudioClipSerializer
+class AudioClipSerializer extends TypeSerializer {
+    constructor() {
+        super([AudioClip]);
+    }
+
+    onSerialize(_data: AudioClip, _context: SerializationContext) {
+        return null;
+    }
+
+    onDeserialize(data: string, context: SerializationContext) {
+        if (typeof data === "string" && data.length > 0) {
+            const url = resolveUrl(context.gltfId, data);
+            if (url) return new AudioClip(url);
+        }
+        return undefined;
+    }
+}
+
+
+// #region Init serializer
+// Module-level references used by EventListSerializer internally
+export let colorSerializer: ColorSerializer;
+export let objectSerializer: ObjectSerializer;
+export let componentSerializer: ComponentSerializer;
+export let eventListSerializer: EventListSerializer;
+
+/** Register all builtin serializers and prototype patches.
+ * Must be called from {@link initEngine} so the registrations survive tree-shaking
+ * when the package declares `sideEffects: false`.
+ */
+export function initBuiltinSerializers() {
+    // Prototype patches
+    const textureClone = Texture.prototype.clone;
+    Texture.prototype.clone = function () {
+        const clone = textureClone.call(this);
+        if (!cloneOriginalMap.has(clone)) {
+            cloneOriginalMap.set(clone, this);
+        }
+        return clone;
+    }
+
+    // Register all serializers
+    colorSerializer = new ColorSerializer();
+    new EulerSerializer();
+    objectSerializer = new ObjectSerializer();
+    componentSerializer = new ComponentSerializer();
+    eventListSerializer = new EventListSerializer();
+    new RenderTextureSerializer();
+    new UriSerializer();
+    new AudioClipSerializer();
+}

package/src/engine/physics/workers/mesh-bvh/GenerateMeshBVHWorker.js

@@ -35,7 +35,7 @@ export class GenerateMeshBVHWorker extends WorkerBase {
 
             worker.onerror = e => {
 
-                reject(new Error(`[GenerateMeshBVHWorker] ${e.message || "Unknown error. Please check the server console. If you're using vite try adding 'three-mesh-bvh' to 'optimizeDeps.exclude' in your vite.config.js"}`));
+                reject(new Error(`[GenerateMeshBVHWorker] ${e.message || "Could not load worker."}`));
             
 			};
 

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

@@ -1,8 +1,8 @@
 import { showBalloonMessage } from "../../debug/debug.js";
-import { HTMLElementBase } from "../../engine_ssr.js";
 import type { Context } from "../../engine_context.js";
 import { hasCommercialLicense, onLicenseCheckResultChanged, Telemetry } from "../../engine_license.js";
 import { isLocalNetwork } from "../../engine_networking_utils.js";
+import { HTMLElementBase } from "../../engine_ssr.js";
 import { DeviceUtilities, getParam } from "../../engine_utils.js";
 import { onXRSessionStart, XRSessionEventArgs } from "../../xr/events.js";
 import { ButtonsFactory } from "../buttons.js";

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

@@ -1,11 +1,11 @@
 import { isDevEnvironment, showBalloonWarning } from "../debug/index.js";
-import { HTMLElementBase } from "../engine_ssr.js";
 import { PUBLIC_KEY, VERSION } from "../engine_constants.js";
 import { ContextEvent, ContextRegistry } from "../engine_context_registry.js";
 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";
@@ -42,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';

package/src/engine/xr/NeedleXRSession.ts

@@ -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);
+}