@needle-tools/engine 5.0.4 → 5.0.6

package/src/engine/xr/NeedleXRSession.ts

@@ -805,15 +805,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 {
@@ -1018,6 +1019,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;
@@ -1128,7 +1131,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");
@@ -1296,8 +1310,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);
 
@@ -1364,10 +1380,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);
+                }
             }
         }
 
@@ -1499,8 +1522,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;
@@ -1509,6 +1536,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');
@@ -1631,9 +1662,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);
+                    }
                 }
             }
         }
@@ -1654,6 +1687,7 @@ export class NeedleXRSession implements INeedleXRSession {
     }
 
     private invokeCallback_EnterXR(script: INeedleXRSessionEventReceiver) {
+        this._scripts_in_xr.add(script);
         if (script.onEnterXR) {
             script.onEnterXR({ xr: this });
         }
@@ -1669,6 +1703,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-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

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

package/src/engine-components/AudioSource.ts

@@ -4,7 +4,6 @@ import { PositionalAudioHelper } from 'three/examples/jsm/helpers/PositionalAudi
 import { isDevEnvironment } from "../engine/debug/index.js";
 import { Application, ApplicationEvents } from "../engine/engine_application.js";
 import { findObjectOfType } from "../engine/engine_components.js";
-import { Mathf } from "../engine/engine_math.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { DeviceUtilities, getParam } from "../engine/engine_utils.js";
 import { AudioListener } from "./AudioListener.js";
@@ -140,12 +139,23 @@ export class AudioSource extends Behaviour {
     get isPlaying(): boolean { return this.sound?.isPlaying ?? false; }
 
     /**
-     * The total duration of the current audio clip in seconds.
+     * The total duration of the currently loaded audio clip in seconds.
      * 
      * @returns Duration in seconds or undefined if no clip is loaded
+     * @remarks For MediaStream clips, duration is not directly available and will return undefined. If the audio clip has not started loading or is still loading, duration may also be undefined until the audio buffer is ready.
      */
     get duration() {
-        return this.sound?.buffer?.duration;
+        if (this.sound?.buffer?.duration) {
+            return this.sound.buffer.duration;
+        }
+        else if (this._audioElement?.duration) {
+            return this._audioElement.duration;
+        }
+        else if (this._loadedClip instanceof MediaStream) {
+            // MediaStream duration is not directly available; return undefined or estimate if possible
+            return undefined;
+        }
+        return undefined;
     }
 
     /**
@@ -200,7 +210,8 @@ export class AudioSource extends Behaviour {
     /**
      * Controls how the audio is positioned in space.
      * Values range from 0 (2D, non-positional) to 1 (fully 3D positioned).
-     * Note: 2D playback is not fully supported in the current implementation.
+     * Internally uses a dual-path audio graph to crossfade between a spatialized (PannerNode)
+     * and a non-spatialized (direct) signal path.
      */
     @serializable()
     get spatialBlend(): number {
@@ -292,12 +303,18 @@ export class AudioSource extends Behaviour {
     // set this from audio context time, used to set clip offset when setting "time" property
     // there is maybe a better way to set a audio clip current time?!
     private _lastClipStartedLoading: string | MediaStream | null = null;
+    private _loadedClip: string | MediaStream | null = null;
     private _audioElement: HTMLAudioElement | null = null;
 
+    // Spatial blend dual-path audio nodes
+    private _entryNode: GainNode | null = null;
+    private _spatialGain: GainNode | null = null;
+    private _bypassGain: GainNode | null = null;
+
     /**
      * Returns the underlying {@link PositionalAudio} object, creating it if necessary.
      * The audio source needs a user interaction to be initialized due to browser autoplay policies.
-     * 
+     *
      * @returns The three.js PositionalAudio object or null if unavailable
      */
     public get Sound(): PositionalAudio | null {
@@ -312,45 +329,12 @@ export class AudioSource extends Behaviour {
             if (listener?.listener) {
                 this.sound = new PositionalAudio(listener.listener);
                 this.gameObject?.add(this.sound);
-
-                // this._listener = listener;
-                // this._originalSoundMatrixWorldFunction = this.sound.updateMatrixWorld;
-                // this.sound.updateMatrixWorld = this._onSoundMatrixWorld;
             }
             else if (debug) console.warn("No audio listener found in scene - can not play audio");
         }
         return this.sound;
     }
 
-    // This is a hacky workaround to get the PositionalAudio behave like a 2D audio source
-    // private _listener: AudioListener | null = null;
-    // private _originalSoundMatrixWorldFunction: Function | null = null;
-    // private _onSoundMatrixWorld = (force: boolean) => {
-    //     if (this._spatialBlend > .05) {
-    //         if (this._originalSoundMatrixWorldFunction) {
-    //             this._originalSoundMatrixWorldFunction.call(this.sound, force);
-    //         }
-    //     }
-    //     else {
-    //         // we use another object's matrix world function (but bound to the positional audio)
-    //         // this is just a little trick to prevent calling the PositionalAudio's updateMatrixWorld function
-    //         this.gameObject.updateMatrixWorld?.call(this.sound, force);
-    //         if (this.sound && this._listener) {
-    //             this.sound.gain.connect(this._listener.listener.getInput());
-    //             // const pos = getTempVector().setFromMatrixPosition(this._listener.gameObject.matrixWorld);
-    //             // const ctx = this.sound.context;
-    //             // const delay = this._listener.listener.timeDelta;
-    //             // const time = ctx.currentTime ;
-    //             // this.sound.panner.positionX.setValueAtTime(pos.x, time);
-    //             // this.sound.panner.positionY.setValueAtTime(pos.y, time);
-    //             // this.sound.panner.positionZ.setValueAtTime(pos.z, time);
-    //             // this.sound.panner.orientationX.setValueAtTime(0, time);
-    //             // this.sound.panner.orientationY.setValueAtTime(0, time);
-    //             // this.sound.panner.orientationZ.setValueAtTime(-1, time);
-    //         }
-    //     }
-    // }
-
     /**
      * Indicates whether the audio source is queued to play when possible.
      * This may be true before user interaction has been registered.
@@ -376,8 +360,10 @@ export class AudioSource extends Behaviour {
         if (this.playOnAwake) this.shouldPlay = true;
 
         if (this.preload) {
-            if (typeof this.clip === "string") {
-                this.audioLoader.load(this.clip, this.createAudio, () => { }, console.error);
+            if (typeof this.clip === "string" && this.clip.length > 0) {
+                this.audioLoader.load(this.clip, this.createAudio, () => { }, e => {
+                    console.error(`[AudioSource] Error preloading audio clip "${this.clip}":`, e);
+                });
             }
         }
     }
@@ -433,9 +419,9 @@ export class AudioSource extends Behaviour {
             this.sound?.setVolume(this.volume);
     }
 
-    private createAudio = (buffer?: AudioBuffer) => {                
-        if(this.destroyed) {
-            if(debug) console.warn("AudioSource destroyed, not creating audio", this.name);
+    private createAudio = (buffer?: AudioBuffer) => {
+        if (this.destroyed) {
+            if (debug) console.warn("AudioSource destroyed, not creating audio", this.name);
             return;
         }
 
@@ -451,26 +437,17 @@ export class AudioSource extends Behaviour {
             sound.stop();
 
         if (buffer) sound.setBuffer(buffer);
+        this._loadedClip = this.clip;
         sound.loop = this._loop;
         if (this.context.application.muted) sound.setVolume(0);
         else sound.setVolume(this.volume);
         sound.autoplay = this.shouldPlay && AudioSource.userInteractionRegistered;
+        this.setupSpatialBlendNodes();
         this.applySpatialDistanceSettings();
 
         if (sound.isPlaying)
             sound.stop();
 
-        // const panner = sound.panner;
-        // panner.coneOuterGain = 1;
-        // sound.setDirectionalCone(360, 360, 1);
-        // const src = sound.context.createBufferSource();
-        // src.buffer = sound.buffer;
-        // src.connect(sound.panner);
-        // src.start(this.audioContext?.currentTime);
-        // const gain = sound.context.createGain();
-        // gain.gain.value = 1 - this.spatialBlend;
-        // src.connect(gain);
-
         // make sure we only play the sound if the user has interacted with the page
         AudioSource.registerWaitForAllowAudio(this.__onAllowAudioCallback);
     }
@@ -479,30 +456,97 @@ export class AudioSource extends Behaviour {
             this.play();
     }
 
+    /**
+     * Sets up the dual-path audio graph for spatial blend crossfading.
+     * Creates two parallel signal paths from source to output:
+     * - 3D path: entry → panner → spatialGain → gain (spatialized)
+     * - 2D path: entry → bypassGain → gain (non-spatialized)
+     */
+    private setupSpatialBlendNodes() {
+        const sound = this.sound;
+        if (!sound || this._entryNode) return;
+
+        const ctx = sound.context;
+        this._entryNode = ctx.createGain();
+        this._spatialGain = ctx.createGain();
+        this._bypassGain = ctx.createGain();
+
+        // Disconnect the default panner → gain connection set up by three.js
+        try { sound.panner.disconnect(sound.gain); } catch { /* not connected */ }
+
+        // 3D path: entry → panner → spatialGain → gain
+        this._entryNode.connect(sound.panner);
+        sound.panner.connect(this._spatialGain);
+        this._spatialGain.connect(sound.gain);
+
+        // 2D path: entry → bypassGain → gain
+        this._entryNode.connect(this._bypassGain);
+        this._bypassGain.connect(sound.gain);
+
+        // Override getOutput so three.js connects source → entryNode instead of panner
+        sound.getOutput = () => this._entryNode! as unknown as PannerNode;
+
+        // Wrap connect() to undo PositionalAudio's redundant panner → gain reconnection
+        const origConnect = sound.connect;
+        sound.connect = function () {
+            origConnect.call(sound);
+            try { sound.panner.disconnect(sound.gain); } catch { /* expected */ }
+            return sound;
+        };
+
+        // Wrap disconnect() to prevent error when panner → gain doesn't exist
+        const origDisconnect = sound.disconnect;
+        sound.disconnect = function () {
+            try { origDisconnect.call(sound); } catch { /* panner → gain already removed */ }
+            return sound;
+        };
+
+        this.updateSpatialBlendGains();
+    }
+
+    /** Updates the spatial/bypass gain values based on the current spatialBlend. */
+    private updateSpatialBlendGains() {
+        if (!this._spatialGain || !this._bypassGain || !this.sound) return;
+        const t = this.sound.context.currentTime;
+        // Use setTargetAtTime for smooth transitions (avoids clicks/pops)
+        this._spatialGain.gain.setTargetAtTime(this._spatialBlend, t, 0.01);
+        this._bypassGain.gain.setTargetAtTime(1 - this._spatialBlend, t, 0.01);
+    }
+
     private applySpatialDistanceSettings() {
         const sound = this.sound;
         if (!sound) return;
         this._needUpdateSpatialDistanceSettings = false;
-        const dist = Mathf.lerp(10 * this._maxDistance / Math.max(0.0001, this.spatialBlend), this._minDistance, this.spatialBlend);
-        if (debug) console.log(this.name, this._minDistance, this._maxDistance, this.spatialBlend, "Ref distance=" + dist);
-        sound.setRefDistance(dist);
-        sound.setMaxDistance(Math.max(0.01, this._maxDistance));
-        // sound.setRolloffFactor(this.spatialBlend);
-        // sound.panner.positionZ.automationRate
+
+        const ref = Math.max(0.0001, this._minDistance);
+        const max = Math.max(0.01, this._maxDistance);
+        if (debug) console.log(this.name, ref, max, this.spatialBlend);
+        sound.setRefDistance(ref);
+        sound.setMaxDistance(max);
 
         // https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/distanceModel
         switch (this.rollOffMode) {
             case AudioRolloffMode.Logarithmic:
-                sound.setDistanceModel('exponential');
+                // Unity's logarithmic rolloff matches Web Audio's 'inverse' model:
+                // gain = refDistance / (refDistance + rolloffFactor * (distance - refDistance))
+                // We compute rolloffFactor so gain reaches ~0.01 (-40dB) at maxDistance,
+                // matching Unity's behavior of effective silence at maxDistance.
+                sound.setDistanceModel('inverse');
+                sound.setRolloffFactor(99 * ref / Math.max(0.001, max - ref));
                 break;
             case AudioRolloffMode.Linear:
+                // gain = 1 - rolloffFactor * (distance - refDistance) / (maxDistance - refDistance)
+                // With rolloffFactor=1 this reaches exactly 0 at maxDistance.
                 sound.setDistanceModel('linear');
+                sound.setRolloffFactor(1);
                 break;
             case AudioRolloffMode.Custom:
                 console.warn("Custom rolloff for AudioSource is not supported: " + this.name);
                 break;
         }
 
+        this.updateSpatialBlendGains();
+
         if (this.spatialBlend > 0) {
             if (debug && !this.helper) {
                 this.helper = new PositionalAudioHelper(sound, sound.getRefDistance());
@@ -519,7 +563,7 @@ export class AudioSource extends Behaviour {
         if (typeof clip === "string") {
             if (debug)
                 console.log(clip);
-            if (clip.endsWith(".mp3") || clip.endsWith(".wav")) {
+            if (clip.endsWith(".mp3") || clip.endsWith(".wav") || clip.endsWith(".ogg") || clip.endsWith(".flac") || clip.endsWith(".aac") || clip.endsWith(".webm")) {
                 if (!this.audioLoader)
                     this.audioLoader = new AudioLoader();
                 this.shouldPlay = true;
@@ -530,9 +574,12 @@ export class AudioSource extends Behaviour {
                 this._lastClipStartedLoading = clip;
                 if (debug)
                     console.log("load audio", clip);
-                const buffer = await this.audioLoader.loadAsync(clip).catch(console.error);
-                if(this.destroyed) return;
-                if(this._lastClipStartedLoading === clip) this._lastClipStartedLoading = null;
+                const buffer = await this.audioLoader.loadAsync(clip).catch(e => {
+                    console.error(`[AudioSource] Error loading audio clip "${clip}":`, e);
+                    return null;
+                });
+                if (this.destroyed) return;
+                if (this._lastClipStartedLoading === clip) this._lastClipStartedLoading = null;
                 if (buffer) this.createAudio(buffer);
             }
             else console.warn("Unsupported audio clip type", clip)
@@ -548,8 +595,9 @@ export class AudioSource extends Behaviour {
      * If no argument is provided, plays the currently assigned clip.
      * 
      * @param clip - Optional audio clip or {@link MediaStream} to play
+     * @returns A promise that resolves when playback starts successfully, or rejects on error
      */
-    play(clip: string | MediaStream | undefined = undefined) {
+    async play(clip: string | MediaStream | undefined = undefined): Promise<boolean> {
         // use audio source's clip when no clip is passed in
         if (!clip && this.clip)
             clip = this.clip;
@@ -557,27 +605,27 @@ export class AudioSource extends Behaviour {
         // We only support strings and media stream
         // TODO: maybe we should return here if an invalid value is passed in
         if (clip !== undefined && typeof clip !== "string" && !(clip instanceof MediaStream)) {
-            if (isDevEnvironment())
-                console.warn("Called play on AudioSource with unknown argument type:", clip + "\nUsing the assigned clip instead:", this.clip)
             // e.g. when a AudioSource.Play is called from SpatialTrigger onEnter this event is called with the TriggerReceiver... to still make this work we *re-use* our already assigned clip. Because otherwise calling `play` would not play the clip...
             clip = this.clip;
+            if (isDevEnvironment()) console.warn("[AudioSource] Called play on AudioSource with unknown argument type:", clip + "\nUsing the assigned clip instead:", this.clip)
         }
 
-        // Check if we need to call load first
-        let needsLoading = !this.sound || (clip && clip !== this.clip);
+        // Load if the sound hasn't been created yet or if the clip changed since last load
+        let needsLoading = !this.sound || (clip && clip !== this._loadedClip);
         if (typeof clip === "string" && !this.audioLoader) needsLoading = true;
         if (clip instanceof MediaStream || typeof clip === "string")
             this.clip = clip;
         if (needsLoading) {
             this.shouldPlay = true;
-            this.onNewClip(clip);
-            return;
+            return this.onNewClip(clip).then(() => true).catch(() => false);
         }
 
         this.shouldPlay = true;
         this._hasEnded = false;
-        if (debug)
-            console.log("play", this.sound?.getVolume(), this.sound);
+
+        if (debug) console.log("[AudioSource] play", this.sound?.getVolume(), this.sound);
+        // If a different clip was passed in, needsLoading above would be true and onNewClip handles it.
+        // This guard prevents double-playing the same already-playing sound (which would throw in three.js).
         if (this.sound && !this.sound.isPlaying) {
             const muted = this.context.application.muted;
             if (muted) this.sound.setVolume(0);
@@ -597,13 +645,17 @@ export class AudioSource extends Behaviour {
                     this.context.domElement.shadowRoot?.append(this._audioElement);
                 this._audioElement.srcObject = this.clip;
                 this._audioElement.autoplay = false;
+                return true;
 
             }
             else {
                 if (this._audioElement) this._audioElement.remove();
                 this.sound.play(muted ? .1 : 0);
+                return true;
             }
         }
+
+        return false;
     }
 
     /**
@@ -611,7 +663,7 @@ export class AudioSource extends Behaviour {
      * Use play() to resume from the paused position.
      */
     pause() {
-        if (debug) console.log("Pause", this);
+        if (debug) console.log("[AudioSource] pause", this);
         this._hasEnded = true;
         this.shouldPlay = false;
         if (this.sound && this.sound.isPlaying && this.sound.source) {
@@ -626,13 +678,13 @@ export class AudioSource extends Behaviour {
      * Unlike pause(), calling play() after stop() will start from the beginning.
      */
     stop() {
-        if (debug) console.log("Pause", this);
+        if (debug) console.log("[AudioSource] stop", this);
         this._hasEnded = true;
         this.shouldPlay = false;
         if (this.sound && this.sound.source) {
             this._lastContextTime = this.sound?.context.currentTime;
             if (debug)
-                console.log(this._lastContextTime)
+                console.log("[AudioSource] lastContextTime", this._lastContextTime);
             this.sound.stop();
         }
         this._audioElement?.remove();
@@ -657,8 +709,7 @@ export class AudioSource extends Behaviour {
 
         if (this.sound && !this.sound.isPlaying && this.shouldPlay && !this._hasEnded) {
             this._hasEnded = true;
-            if (debug)
-                console.log("Audio clip ended", this.clip);
+            if (debug) console.log("[AudioSource] Audio clip ended", this.clip);
             this.dispatchEvent(new CustomEvent("ended", { detail: this }));
         }
 

package/src/engine-components/DragControls.ts

@@ -12,6 +12,7 @@ import { getParam } from "../engine/engine_utils.js";
 import { NeedleXRSession } from "../engine/engine_xr.js";
 import { Avatar_POI } from "./avatar/Avatar_Brain_LookAt.js";
 import { Behaviour, GameObject } from "./Component.js";
+import { EventList } from "./EventList.js";
 import { UsageMarker } from "./Interactable.js";
 import { Rigidbody } from "./RigidBody.js";
 import { SyncedTransform } from "./SyncedTransform.js";
@@ -155,7 +156,19 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
     @serializable()
     public showGizmo: boolean = false;
 
-    /** 
+    /** Invoked once when a drag begins (after the minimum drag distance threshold is met). */
+    @serializable(EventList)
+    dragStarted: EventList = new EventList();
+
+    /** Invoked every frame while the object is being dragged. */
+    @serializable(EventList)
+    dragUpdated: EventList = new EventList();
+
+    /** Invoked once when the last pointer is released and the drag ends. */
+    @serializable(EventList)
+    dragEnded: EventList = new EventList();
+
+    /**
      * Returns the object currently being dragged by this DragControls component, if any.
      * @returns The object being dragged or null if no object is currently dragged
      */
@@ -457,6 +470,7 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
         if (!object) return;
 
         this._isDragging = true;
+        this.dragStarted?.invoke();
 
         const sync = GameObject.getComponentInChildren(object, SyncedTransform);
         if (debug) console.log("DRAG START", sync, object);
@@ -497,9 +511,10 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
         const object = this._targetObject || this.gameObject;
 
         InstancingUtil.markDirty(object);
+        this.dragUpdated?.invoke();
     }
 
-    /** 
+    /**
      * Called when the last pointer has been removed from this object.
      * Cleans up drag state and applies final velocities to rigidbodies.
      * @param evt Pointer event data for the last pointer that was lifted
@@ -507,6 +522,7 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
     private onLastDragEnd(evt: PointerEventData | null) {
         if (!this || !this._isDragging) return;
         this._isDragging = false;
+        this.dragEnded?.invoke();
         for (const rb of this._draggingRigidbodies) {
             rb.setVelocity(rb.smoothedVelocity.multiplyScalar(this.context.time.deltaTime));
         }