@needle-tools/engine 5.1.0-canary.deec6e4 → 5.1.0-canary.e7c2511

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,7 +12,7 @@ import { IComponent } from "./engine_types.js";
 import { resolveUrl } from "./engine_utils.js";
 import { RGBAColor } from "./js-extensions/index.js";
 
-
+// #region Color
 class ColorSerializer extends TypeSerializer {
     constructor() {
         super([Color, RGBAColor], "ColorSerializer")
@@ -35,6 +36,8 @@ class ColorSerializer extends TypeSerializer {
     }
 }
 
+// #region Euler
+
 class EulerSerializer extends TypeSerializer {
     constructor() {
         super([Euler], "EulerSerializer");
@@ -58,6 +61,8 @@ declare type ObjectData = {
     node?: number;
     guid?: string;
 }
+
+// #region ObjectSerializer
 class ObjectSerializer extends TypeSerializer {
     constructor() {
         super(Object3D, "ObjectSerializer");
@@ -119,7 +124,7 @@ class ObjectSerializer extends TypeSerializer {
                 }
                 if (!res) {
                     if (isDevEnvironment() || debugExtension)
-                        console.warn("Could not resolve object reference", context.path, data, context.target, context.context.scene);
+                        console.warn(`Could not resolve object reference \"${context.path}\" (guid: ${data.guid}). The referenced object may have been deleted — check if the reference is still valid in your scene.`);
                     data["could_not_resolve"] = true;
                 }
                 else {
@@ -137,7 +142,7 @@ class ObjectSerializer extends TypeSerializer {
     }
 }
 
-
+// #region ComponentSerializer
 class ComponentSerializer extends TypeSerializer {
 
     constructor() {
@@ -226,6 +231,7 @@ declare type EventListCall = {
 
 const $eventListDebugInfo = Symbol("eventListDebugInfo");
 
+// #region EventListSerializer
 class EventListSerializer extends TypeSerializer {
     constructor() {
         super([EventList]);
@@ -328,11 +334,6 @@ class EventListSerializer extends TypeSerializer {
             if (debugExtension)
                 console.log(evt);
 
-            const eventListOwner = context.target;
-            if (eventListOwner !== undefined && context.path !== undefined) {
-                evt.setEventTarget(context.path, eventListOwner);
-            }
-
             return evt;
         }
         return undefined;
@@ -371,6 +372,7 @@ class EventListSerializer extends TypeSerializer {
  */
 const cloneOriginalMap = new WeakMap<Texture, Texture>();
 
+// #region RenderTextureSerializer
 export class RenderTextureSerializer extends TypeSerializer {
     constructor() {
         super([RenderTexture, WebGLRenderTarget]);
@@ -412,7 +414,7 @@ export class RenderTextureSerializer extends TypeSerializer {
     }
 }
 
-
+// #region UriSerializer
 export class UriSerializer extends TypeSerializer {
     constructor() {
         super([URL]);
@@ -430,7 +432,27 @@ export class UriSerializer extends TypeSerializer {
     }
 }
 
+// #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;
@@ -460,4 +482,5 @@ export function initBuiltinSerializers() {
     eventListSerializer = new EventListSerializer();
     new RenderTextureSerializer();
     new UriSerializer();
+    new AudioClipSerializer();
 }

package/src/engine/engine_serialization_core.ts

@@ -207,6 +207,15 @@ export interface ISerializable {
     onAfterDeserialize?(data: any, context: SerializationContext): void;
 };
 
+export function isSerializable(obj: any): obj is ISerializable {
+    return obj && typeof obj === "object" && (
+        typeof obj.$serializedTypes === "object" ||
+        typeof obj.onBeforeDeserialize === "function" ||
+        typeof obj.onBeforeDeserializeMember === "function" ||
+        typeof obj.onAfterDeserializeMember === "function" ||
+        typeof obj.onAfterDeserialize === "function"
+    )
+}
 
 export function serializeObject(obj: ISerializable, context: SerializationContext): object | null {
     const types = obj.$serializedTypes;

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";
@@ -201,8 +200,6 @@ export interface IComponent extends IHasGuid {
     __internalDisable(isAddingOrRemovingFromScene?: 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 */
@@ -274,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 {
@@ -302,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 {
@@ -475,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;
@@ -738,8 +746,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/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/Animator.ts

@@ -89,6 +89,15 @@ export class Animator extends Behaviour implements IAnimationComponent {
         return true;
     }
 
+    /**
+     * The current animator mixer, used for low-level control of animations. Owned by the AnimatorController
+     * @returns The current AnimationMixer, or null if no controller is assigned
+     * @see AnimatorController.mixer
+     */
+    get mixer() {
+        return this._animatorController?.mixer || null;
+    }
+
     /**
      * When enabled, animation will affect the root transform position and rotation
      */
@@ -401,17 +410,15 @@ export class Animator extends Behaviour implements IAnimationComponent {
     initializeRuntimeAnimatorController(force: boolean = false) {
         const shouldRun = (force || this.runtimeAnimatorController !== this._initializeWithRuntimeAnimatorController);
         if (this.runtimeAnimatorController && shouldRun) {
-            const clone = this.runtimeAnimatorController.clone();
-            this._initializeWithRuntimeAnimatorController = clone;
-            if (clone) {
-                console.assert(this.runtimeAnimatorController !== clone);
-                this.runtimeAnimatorController = clone;
-                console.assert(this.runtimeAnimatorController === clone);
-                this.runtimeAnimatorController.bind(this);
-                this.runtimeAnimatorController.setSpeed(this._speed);
-                this.runtimeAnimatorController.normalizedStartOffset = this._normalizedStartOffset;
-            }
-            else console.warn("Could not clone animator controller", this.runtimeAnimatorController);
+            // Create a fresh controller from the (possibly remapped) model.
+            // The constructor deep-clones the model, preserving Object3D refs that
+            // the resolve system has already remapped to cloned objects.
+            const controller = new AnimatorController(this.runtimeAnimatorController.model);
+            this.runtimeAnimatorController = controller;
+            this._initializeWithRuntimeAnimatorController = controller;
+            controller.bind(this);
+            controller.setSpeed(this._speed);
+            controller.normalizedStartOffset = this._normalizedStartOffset;
         }
     }