@needle-tools/engine 5.1.0-canary.30cc545 → 5.1.0-canary.40da791

package/src/engine/engine_types.ts

@@ -5,7 +5,6 @@ import { type GLTF as THREE_GLTF } from "three/examples/jsm/loaders/GLTFLoader.j
 
 import type { Camera as CameraComponent } from "../engine-components/api.js";
 import type { Context } from "./engine_context.js";
-import { InstantiateContext } from "./engine_gameobject.js";
 import { CollisionDetectionMode, type PhysicsMaterial, RigidbodyConstraints } from "./engine_physics.types.js";
 import { CircularBuffer } from "./engine_utils.js";
 import type { NeedleXRSession } from "./engine_xr.js";
@@ -196,13 +195,11 @@ export interface IComponent extends IHasGuid {
     /** @internal */
     __internalStart();
     /** @internal */
-    __internalEnable(isAddingOrRemovingFromScene?: boolean);
+    __internalEnable(isHierarchyChange?: boolean);
     /** @internal */
-    __internalDisable(isAddingOrRemovingFromScene?: boolean);
+    __internalDisable(isHierarchyChange?: boolean);
     /** @internal */
     __internalDestroy();
-    /** @internal */
-    resolveGuids?(guidsMap: GuidsMap): void;
 
     /** experimental, called when the script is registered for the first time, this is called even if the component is not enabled. */
     registering?();
@@ -240,14 +237,14 @@ export interface IComponent extends IHasGuid {
 }
 
 export function isComponent(obj: any): obj is IComponent {
-    return obj && obj.isComponent;
+    return obj && typeof obj === "object" && obj.isComponent;
 }
 
 export type ICamera = CameraComponent;
 
 export type IAnimationComponent = Pick<IComponent, "gameObject"> & {
     isAnimationComponent: boolean;
-    addClip?(clip: AnimationClip);
+    addClip?(clip: AnimationClip): void;
 }
 
 /** Interface for a camera controller component that can be attached to a camera to control it */
@@ -258,6 +255,8 @@ export declare interface ICameraController {
 export declare interface ILight extends IComponent {
     intensity: number;
     color: Color;
+    /** The type of light as a lowercase string: `"directional"`, `"point"`, `"spot"` */
+    readonly type: "directional" | "point" | "spot";
 }
 
 export declare interface ISharedMaterials {
@@ -272,7 +271,10 @@ export declare interface IRenderer extends IComponent {
 
 export declare interface IEventList {
     readonly isEventList: true;
-    __internalOnInstantiate(map: InstantiateContext): IEventList;
+}
+
+export declare interface ISignalReceiver {
+    readonly isSignalReceiver: true;
 }
 
 // export declare interface IPhysicsComponent extends IComponent {
@@ -300,12 +302,18 @@ export declare interface ICollider extends IComponent {
      * Default: [0]
     */
     membership?: number[];
-    /** The collider filter indicates what groups the collider can interact with (e.g. group 3 and 4)   
-     * An `undefined` array indicates that the collider can interact with all groups   
-     * Note: Make sure to call updateProperties after having changed this property  
+    /** The collider filter indicates what groups the collider can interact with (e.g. group 3 and 4)
+     * An `undefined` array indicates that the collider can interact with all groups
+     * Note: Make sure to call updateProperties after having changed this property
      * Default: undefined
     */
     filter?: number[];
+    /** The density of the collider used for automatic mass calculation.
+     * When the attached Rigidbody has `autoMass` enabled, the mass is computed as `density × volume`.
+     * Note: Make sure to call updateProperties after having changed this property
+     * Default: undefined (uses physics engine default of 1.0)
+    */
+    density?: number;
 }
 
 export declare interface ISphereCollider extends ICollider {
@@ -473,8 +481,10 @@ export interface IPhysicsEngine {
     postStep();
     /** Indicates whether the physics engine is currently updating */
     get isUpdating(): boolean;
-    /** Clears all cached data (e.g., mesh data when creating scaled mesh colliders) */
-    clearCaches();
+    /** Tears down the physics world and frees all resources. The world will be re-created on next use. */
+    dispose(): void;
+    /** @deprecated Use {@link dispose} instead. */
+    clearCaches(): void;
 
     /** Enables or disables the physics engine */
     enabled: boolean;
@@ -511,20 +521,25 @@ export interface IPhysicsEngine {
         /** True if you want to also hit objects when the raycast starts from inside a collider */
         solid?: boolean,
         queryFilterFlags?: QueryFilterFlags,
-        /** 
-         * Raycast filter groups. Groups are used to apply the collision group rules for the scene query. 
-         * The scene query will only consider hits with colliders with collision groups compatible with 
+        /**
+         * Raycast filter groups. Groups are used to apply the collision group rules for the scene query.
+         * The scene query will only consider hits with colliders with collision groups compatible with
          * this collision group (using the bitwise test described in the collision groups section).
-         * For example membership 0x0001 and filter 0x0002 should be 0x00010002 
+         * For example membership 0x0001 and filter 0x0002 should be 0x00010002
          * @see https://rapier.rs/docs/user_guides/javascript/colliders#collision-groups-and-solver-groups
          */
         filterGroups?: number,
-        /** 
+        /**
          * Predicate to filter colliders in raycast results
          * @param collider The collider being tested
          * @returns False to ignore this collider, true to include it
          */
-        filterPredicate?: (collider: ICollider) => boolean
+        filterPredicate?: (collider: ICollider) => boolean,
+        /** When true, trigger/sensor colliders will be included in the raycast results.
+         * By default trigger colliders are skipped.
+         * @default false
+         */
+        includeTriggers?: boolean,
     }): RaycastResult;
 
     /**
@@ -539,20 +554,25 @@ export interface IPhysicsEngine {
         /** True if you want to also hit objects when the raycast starts from inside a collider */
         solid?: boolean,
         queryFilterFlags?: QueryFilterFlags,
-        /** 
-         * Raycast filter groups. Groups are used to apply the collision group rules for the scene query. 
-         * The scene query will only consider hits with colliders with collision groups compatible with 
+        /**
+         * Raycast filter groups. Groups are used to apply the collision group rules for the scene query.
+         * The scene query will only consider hits with colliders with collision groups compatible with
          * this collision group (using the bitwise test described in the collision groups section).
-         * For example membership 0x0001 and filter 0x0002 should be 0x00010002 
+         * For example membership 0x0001 and filter 0x0002 should be 0x00010002
          * @see https://rapier.rs/docs/user_guides/javascript/colliders#collision-groups-and-solver-groups
          */
         filterGroups?: number,
-        /** 
+        /**
          * Predicate to filter colliders in raycast results
          * @param collider The collider being tested
          * @returns False to ignore this collider, true to include it
          */
-        filterPredicate?: (collider: ICollider) => boolean
+        filterPredicate?: (collider: ICollider) => boolean,
+        /** When true, trigger/sensor colliders will be included in the raycast results.
+         * By default trigger colliders are skipped.
+         * @default false
+         */
+        includeTriggers?: boolean,
     }): RaycastResult;
 
     /**
@@ -736,8 +756,9 @@ export interface IPhysicsEngine {
     getBody(obj: ICollider | IRigidbody): null | any;
 
     // Joints
-    addFixedJoint(body1: IRigidbody, body2: IRigidbody);
-    addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: Vec3, axis: Vec3);
+    addFixedJoint(body1: IRigidbody, body2: IRigidbody): Promise<any> | any;
+    addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: Vec3, axis: Vec3): Promise<any> | any;
+    removeJoint(joint: any): void;
 
     /** Enable to render collider shapes */
     debugRenderColliders: boolean;

package/src/engine/engine_util_decorator.ts

@@ -79,8 +79,12 @@ function createPropertyWrapper(target: IComponent | any, _propertyKey: string |
                 return;
             }
 
-            // only build wrapper once per type
-            if (this[$prop] === undefined) {
+            // Only install the getter/setter once per instance.
+            // processStart may call __internalAwake again for components that were inactive
+            // during processNewScripts — the base Component.__internalAwake has a __didAwake guard
+            // but this decorator wrapper runs before reaching it, so we need our own idempotency check.
+            const desc = Object.getOwnPropertyDescriptor(this, propertyKey);
+            if (!desc || !desc.get) {
 
                 // make sure the field is initialized in a hidden property
                 this[$prop] = this[propertyKey];
@@ -99,6 +103,7 @@ function createPropertyWrapper(target: IComponent | any, _propertyKey: string |
                 }
 
                 Object.defineProperty(this, propertyKey, {
+                    configurable: true,
                     set: function (v) {
                         if (this[$isAssigningProperties] === true) {
                             this[$prop] = v;

package/src/engine/engine_utils.ts

@@ -279,24 +279,35 @@ declare type deepClonePredicate = (owner: any, propertyName: string, current: an
  *   return true;
  * });
  * */
-export function deepClone(obj: any, predicate?: deepClonePredicate): any {
+export function deepClone(obj: any, predicate?: deepClonePredicate, _visited?: WeakSet<object>): any {
     if (obj !== null && obj !== undefined && typeof obj === "object") {
+        if (!_visited) _visited = new WeakSet();
+        if (_visited.has(obj)) return obj;
+        _visited.add(obj);
+
         let clone;
         if (Array.isArray(obj)) clone = [];
         else {
-            clone = Object.create(obj);
-            Object.assign(clone, obj);
+            clone = Object.create(Object.getPrototypeOf(obj));
+            // Copy own properties, skipping getter-only properties that can't be set
+            const descriptors = Object.getOwnPropertyDescriptors(obj);
+            for (const key in descriptors) {
+                const desc = descriptors[key];
+                if (desc.set || desc.writable !== false) {
+                    try { clone[key] = obj[key]; }
+                    catch { /* skip read-only properties */ }
+                }
+            }
         }
         for (const key of Object.keys(obj)) {
             const val = obj[key];
             if (predicate && !predicate(obj, key, val)) {
-                // console.log("SKIP", val);
                 clone[key] = val;
             }
             else if (val?.clone !== undefined && typeof val.clone === "function")
                 clone[key] = val.clone();
             else
-                clone[key] = deepClone(val, predicate);
+                clone[key] = deepClone(val, predicate, _visited);
         }
         return clone;
     }

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/jsx.d.ts

@@ -0,0 +1,51 @@
+/**
+ * JSX IntrinsicElements declarations for Needle Engine web components.
+ *
+ * Covers both the global JSX namespace (Preact, SolidJS, Svelte, vanilla TS)
+ * and React's module-scoped JSX namespace (react-jsx / react-jsxdev transform).
+ *
+ * IMPORTANT: This file must be a module (has a top-level import/export) so that
+ * `declare module "react"` is treated as a *module augmentation* (merging into
+ * the existing React types) rather than an *ambient module declaration* (which
+ * would shadow/replace @types/react).
+ */
+
+import type { NeedleEngineAttributes } from "./needle-engine.js";
+
+interface NeedleButtonJSXAttributes extends Partial<Omit<HTMLElement, "style" | "children">> {
+    style?: Partial<CSSStyleDeclaration>;
+    ar?: boolean | string;
+    vr?: boolean | string;
+    quicklook?: boolean | string;
+    qrcode?: boolean | string;
+    unstyled?: boolean | string;
+}
+
+interface NeedleMenuJSXAttributes extends Partial<Omit<HTMLElement, "style" | "children">> {
+    style?: Partial<CSSStyleDeclaration>;
+}
+
+interface NeedleLogoElementJSXAttributes extends Partial<Omit<HTMLElement, "style" | "children">> {
+    style?: Partial<CSSStyleDeclaration>;
+}
+
+interface NeedleElements {
+    "needle-engine": Partial<NeedleEngineAttributes>;
+    "needle-button": NeedleButtonJSXAttributes;
+    "needle-menu": NeedleMenuJSXAttributes;
+    "needle-logo-element": NeedleLogoElementJSXAttributes;
+}
+
+// Global JSX namespace — Preact, SolidJS, Svelte, vanilla TS
+declare global {
+    namespace JSX {
+        interface IntrinsicElements extends NeedleElements {}
+    }
+}
+
+// React module-scoped JSX namespace (module augmentation, not ambient declaration)
+declare module "react" {
+    namespace JSX {
+        interface IntrinsicElements extends NeedleElements {}
+    }
+}

package/src/engine/webcomponents/logo-element.ts

@@ -3,6 +3,7 @@ import { HTMLElementBase } from "../engine_ssr.js";
 
 const elementName = "needle-logo-element";
 
+// NOTE: keep JSX attributes in sync with ./jsx.d.ts
 declare global {
     interface HTMLElementTagNameMap {
         "needle-logo-element": NeedleLogoElement;

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";
@@ -12,9 +12,10 @@ import { NeedleLogoElement } from "../logo-element.js";
 import { getElementPriority, setElementPriority as _setElementPriority } from "./menu-priority.js";
 import { NeedleSpatialMenu } from "./needle-menu-spatial.js";
 
+// NOTE: keep JSX attributes in sync with ../jsx.d.ts
 declare global {
     interface HTMLElementTagNameMap {
-        "needle-logo-element": NeedleLogoElement;
+        "needle-menu": NeedleMenuElement;
     }
 }
 

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

@@ -4,6 +4,7 @@ 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;

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";
@@ -17,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;
@@ -41,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);
         });