@needle-tools/engine 5.1.0-canary.fbdfce3 → 5.1.0-experimental.03e8105

package/src/engine-components/OrbitControls.ts

@@ -663,7 +663,15 @@ export class OrbitControls extends Behaviour implements ICameraController {
         }
         this._controls.enabled = true;
 
-        if (this.context.input.getPointerDown(1) || this.context.input.getPointerDown(2) || this.context.input.mouseWheelChanged || (this.context.input.getPointerPressed(0) && this.context.input.getPointerPositionDelta(0)?.length() || 0 > .1)) {
+        // Interrupt programmatic transitions on meaningful new user interaction:
+        // - Middle/right button down (always intentional camera control)
+        // - Mouse wheel (zoom intent)
+        // - Left button drag start: getPointerDown(0) with a position delta — a bare click
+        //   without movement shouldn't cancel an animation, but starting to drag should.
+        //   Using getPointerDown (not getPointerPressed) ensures we only interrupt once at
+        //   drag onset, not continuously every frame during a drag.
+        const leftDragStart = this.context.input.getPointerDown(0) && (this.context.input.getPointerPositionDelta(0)?.length() || 0) > .1;
+        if (this.context.input.getPointerDown(1) || this.context.input.getPointerDown(2) || this.context.input.mouseWheelChanged || leftDragStart) {
             this._inputs += 1;
         }
         if (this._inputs > 0 && this.allowInterrupt) {
@@ -758,19 +766,26 @@ export class OrbitControls extends Behaviour implements ICameraController {
 
         if (this.targetBounds) {
             // #region target bounds
-            const targetVector = this._controls.target;
             const boundsCenter = this.targetBounds.worldPosition;
             const boundsHalfSize = getTempVector(this.targetBounds.worldScale).multiplyScalar(0.5);
             const min = getTempVector(boundsCenter).sub(boundsHalfSize);
             const max = getTempVector(boundsCenter).add(boundsHalfSize);
-            const newTarget = getTempVector(this._controls.target).clamp(min, max);
-            const duration = .1;
-            if (duration <= 0) targetVector.copy(newTarget);
-            else targetVector.lerp(newTarget, this.context.time.deltaTime / duration);
+
             if (this._lookTargetLerpActive) {
-                if (duration <= 0) this._lookTargetEndPosition.copy(newTarget);
-                else this._lookTargetEndPosition.lerp(newTarget, this.context.time.deltaTime / (duration * 5));
+                // During a programmatic transition (fitCamera / setLookTargetPosition with immediate: false),
+                // only clamp the destination. The look-target lerp (above) handles moving _controls.target
+                // towards the endpoint — we must not fight it by also lerping _controls.target here.
+                this._lookTargetEndPosition.clamp(min, max);
+            }
+            else {
+                // Interactive use (pan/orbit): smoothly push the target back into bounds
+                const targetVector = this._controls.target;
+                const newTarget = getTempVector(targetVector).clamp(min, max);
+                const duration = .1;
+                if (duration <= 0) targetVector.copy(newTarget);
+                else targetVector.lerp(newTarget, Math.min(1, this.context.time.deltaTime / duration));
             }
+
             if (debug) {
                 Gizmos.DrawWireBox(boundsCenter, boundsHalfSize.multiplyScalar(2), 0xffaa00);
             }
@@ -847,7 +862,8 @@ export class OrbitControls extends Behaviour implements ICameraController {
                 this._controls.update(this.context.time.deltaTime);
 
                 if (debug) {
-                    Gizmos.DrawWireSphere(this._controls.target, 0.1, 0x00ff00);
+                    const distance = this._controls.getDistance();
+                    Gizmos.DrawWireSphere(this._controls.target, 0.01 * distance, 0x00ff00);
                 }
             }
         }
@@ -1022,7 +1038,8 @@ export class OrbitControls extends Behaviour implements ICameraController {
 
         if (debug) {
             console.warn("OrbitControls: setLookTargetPosition", position, immediateOrDuration);
-            Gizmos.DrawWireSphere(this._lookTargetEndPosition, .2, 0xff0000, 2);
+            const distance = this._controls.getDistance();
+            Gizmos.DrawWireSphere(this._lookTargetEndPosition, 0.01 * distance, 0xff5500, 2);
         }
 
         if (immediateOrDuration === true) {
@@ -1086,13 +1103,16 @@ export class OrbitControls extends Behaviour implements ICameraController {
     // Adapted from https://discourse.threejs.org/t/camera-zoom-to-fit-object/936/24
     // Slower but better implementation that takes bones and exact vertex positions into account: https://github.com/google/model-viewer/blob/04e900c5027de8c5306fe1fe9627707f42811b05/packages/model-viewer/src/three-components/ModelScene.ts#L321
 
-    /** 
-     * Fits the camera to show the objects provided (defaults to the scene if no objects are passed in) 
+    /**
+     * Fits the camera to show the objects provided (defaults to the scene if no objects are passed in)
      * @param options The options for fitting the camera. Use to provide objects to fit to, fit direction and size and other settings.
     */
     fitCamera(options?: OrbitFitCameraOptions);
-    /** @deprecated Use fitCamera(options) */
-    fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<OrbitFitCameraOptions, "objects">);
+    // Deprecated overload commented out: it accepted Object3D as first arg, which caused
+    // TypeScript autocomplete to show Object3D properties (position, worldPosition, etc.)
+    // instead of OrbitFitCameraOptions. The implementation still handles Object3D at runtime
+    // for backwards-compat — use fitCamera({ objects: [...] }) instead.
+    // fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<OrbitFitCameraOptions, "objects">);
     fitCamera(objectsOrOptions?: Object3D | Array<Object3D> | OrbitFitCameraOptions, options?: OrbitFitCameraOptions): void {
 
 

package/src/engine-components/RigidBody.ts

@@ -204,12 +204,19 @@ export class Rigidbody extends Behaviour implements IRigidbody {
 
     get isRigidbody() { return true; }
 
-    /** When true the mass will be automatically calculated by the attached colliders */
+    /** When true the mass is automatically computed from the attached colliders using `mass = density × volume`.
+     * Each collider's {@link Collider.density} determines how heavy it contributes to the total mass.
+     * Disable to set mass explicitly via the `mass` property.
+     */
     @validate()
     autoMass: boolean = true;
 
-    /** By default the mass will be automatically calculated (see `autoMass`) by the physics engine using the collider sizes  
-     * To set the mass manually you can either set the `mass` value or set `autoMass` to `false`
+    /** The mass of the rigidbody in kg (when `autoMass` is disabled).
+     * When `autoMass` is enabled, reading this returns the computed mass from `density × volume` of all attached colliders.
+     * Setting this property automatically disables `autoMass`.
+     *
+     * **Prefer using {@link Collider.density}** with `autoMass` enabled instead — density scales
+     * naturally with collider size, while explicit mass stays fixed regardless of shape changes.
      */
     @serializable()
     set mass(value: number) {
@@ -403,9 +410,16 @@ export class Rigidbody extends Behaviour implements IRigidbody {
         this.context.physics.engine?.removeBody(this);
     }
 
-    onValidate() {
+    onValidate(property?: string) {
         this._propertiesChanged = true;
+        if (property === "autoMass" && !this.autoMass) {
+            if (isDevEnvironment() && !Rigidbody._didWarnAutoMass) {
+                Rigidbody._didWarnAutoMass = true;
+                console.warn("[Rigidbody] autoMass disabled — consider using Collider.density instead of setting mass explicitly. Density scales naturally with collider size.");
+            }
+        }
     }
+    private static _didWarnAutoMass = false;
 
     // need to do this right before updating physics to prevent rendered object glitching through physical bodies
     * beforePhysics() {

package/src/engine-components/SceneSwitcher.ts

@@ -747,6 +747,9 @@ export class SceneSwitcher extends Behaviour {
                 const openedEvt = new CustomEvent<LoadSceneEvent>("scene-opened", { detail: { scene: scene, switcher: this, index: index } });
                 this.dispatchEvent(openedEvt);
                 this.sceneLoaded?.invoke(this);
+                if (this._currentSceneAsset) {
+                    this.context.events.emit("scene-content-changed", { source: this, object: this._currentSceneAsset });
+                }
                 return true;
             }
         }

package/src/engine-components/SeeThrough.ts

@@ -249,10 +249,10 @@ export class SeeThrough extends Behaviour {
             }
 
             const materials = renderer.sharedMaterials;// : this.rendererMaterials.get(renderer);
-            if (!materials) return;
+            if (!materials?.length) return;
 
             const block = MaterialPropertyBlock.get(renderer.gameObject);
-            const currentOpacity = (block.getOverride("opacity")?.value ?? materials[0].opacity ?? 1);
+            const currentOpacity = (block.getOverride("opacity")?.value ?? materials[0]?.opacity ?? 1);
 
             let newAlpha = Mathf.lerp(currentOpacity, targetAlpha, duration <= 0 ? 1 : this.context.time.deltaTime / duration);;
             if (newAlpha >= 0.99) newAlpha = 1;

package/src/engine-components/api.ts

@@ -34,8 +34,9 @@
  * @module Built-in Components
  */
 
+export { AnimationBuilder, type AnimationKeyframe, type Tween, type AnimationInterpolation } from "./AnimationBuilder.js";
+export { AnimatorControllerBuilder, type ConditionMode, type StateOptions, type TransitionOptions } from "./AnimatorController.builder.js";
 export * from "./codegen/components.js";
-export { AnimatorControllerBuilder, type ConditionMode, type StateOptions, type TransitionOptions } from "./AnimatorController.js";
 export { Collider } from "./Collider.js"; // export abstract type
 export { Behaviour, Component, GameObject } from "./Component.js";
 

package/src/engine-components/codegen/components.ts

@@ -3,21 +3,13 @@
 export class __Ignore {}
 export { AlignmentConstraint } from "../AlignmentConstraint.js";
 export { Animation } from "../Animation.js";
+export { AnimationBuilder } from "../AnimationBuilder.js";
 export { Keyframe } from "../AnimationCurve.js";
 export { AnimationCurve } from "../AnimationCurve.js";
 export { Animator } from "../Animator.js";
-export { AnimatorControllerBuilder } from "../AnimatorController.js";
 export { AnimatorController } from "../AnimatorController.js";
 export { AudioListener } from "../AudioListener.js";
 export { AudioSource } from "../AudioSource.js";
-export { Avatar_POI } from "../avatar/Avatar_Brain_LookAt.js";
-export { Avatar_Brain_LookAt } from "../avatar/Avatar_Brain_LookAt.js";
-export { Avatar_MouthShapes } from "../avatar/Avatar_MouthShapes.js";
-export { Avatar_MustacheShake } from "../avatar/Avatar_MustacheShake.js";
-export { AvatarBlink_Simple } from "../avatar/AvatarBlink_Simple.js";
-export { AvatarEyeLook_Rotation } from "../avatar/AvatarEyeLook_Rotation.js";
-export { AvatarModel } from "../AvatarLoader.js";
-export { AvatarLoader } from "../AvatarLoader.js";
 export { AxesHelper } from "../AxesHelper.js";
 export { BasicIKConstraint } from "../BasicIKConstraint.js";
 export { BoxHelperComponent } from "../BoxHelperComponent.js";
@@ -168,11 +160,13 @@ export { PlayableDirector } from "../timeline/PlayableDirector.js";
 export { SignalAsset } from "../timeline/SignalAsset.js";
 export { SignalReceiverEvent } from "../timeline/SignalAsset.js";
 export { SignalReceiver } from "../timeline/SignalAsset.js";
-export { AnimationTrackHandler } from "../timeline/TimelineTracks.js";
-export { AudioTrackHandler } from "../timeline/TimelineTracks.js";
-export { MarkerTrackHandler } from "../timeline/TimelineTracks.js";
+export { TimelineBuilder } from "../timeline/TimelineBuilder.js";
+export { TimelineAnimationTrack } from "../timeline/TimelineTracks.js";
+export { TimelineAudioTrack } from "../timeline/TimelineTracks.js";
+export { TimelineMarkerTrack } from "../timeline/TimelineTracks.js";
 export { SignalTrackHandler } from "../timeline/TimelineTracks.js";
-export { ControlTrackHandler } from "../timeline/TimelineTracks.js";
+export { TimelineActivationTrack } from "../timeline/TimelineTracks.js";
+export { TimelineControlTrack } from "../timeline/TimelineTracks.js";
 export { TransformGizmo } from "../TransformGizmo.js";
 export { BaseUIComponent } from "../ui/BaseUIComponent.js";
 export { UIRootComponent } from "../ui/BaseUIComponent.js";

package/src/engine-components/export/usdz/USDZExporter.ts

@@ -3,7 +3,7 @@ import { Euler, Material, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "t
 
 import { isDevEnvironment, showBalloonMessage, showBalloonWarning } from "../../../engine/debug/index.js";
 import { findObjectOfType } from "../../../engine/engine_components.js";
-import { hasProLicense } from "../../../engine/engine_license.js";
+import { UFadk } from "../../../engine/engine_license.js";
 import { serializable } from "../../../engine/engine_serialization.js";
 import { getFormattedDate, Progress } from "../../../engine/engine_time_utils.js";
 import { DeviceUtilities, getParam } from "../../../engine/engine_utils.js";
@@ -277,7 +277,7 @@ export class USDZExporter extends Behaviour {
         let name = this.exportFileName ?? this.objectToExport?.name ?? this.name;
         name += "-" + getFormattedDate(); // seems iOS caches the file in some cases, this ensures we always have a fresh file
 
-        if (!hasProLicense()) {
+        if (!UFadk()) {
             if (name !== "") name += "-";
             name += "MadeWithNeedle";
         }
@@ -682,7 +682,7 @@ export class USDZExporter extends Behaviour {
                     if (debug)
                         showBalloonMessage("Quicklook url: " + callToActionURL);
                     if (callToActionURL) {
-                        if (!hasProLicense()) {
+                        if (!UFadk()) {
                             console.warn("Quicklook closed: custom redirects require a Needle Engine Pro license: https://needle.tools/pricing", callToActionURL)
                         }
                         else {
@@ -697,7 +697,7 @@ export class USDZExporter extends Behaviour {
     private buildQuicklookOverlay(): CustomBranding {
         const obj: CustomBranding = {};
         if (this.customBranding) Object.assign(obj, this.customBranding);
-        if (!hasProLicense()) {
+        if (!UFadk()) {
             console.log("Custom Quicklook banner text requires pro license: https://needle.tools/pricing");
             obj.callToAction = "Close";
             obj.checkoutTitle = "🌵 Made with Needle";

package/src/engine-components/timeline/PlayableDirector.ts

@@ -4,7 +4,6 @@ import { isDevEnvironment } from '../../engine/debug/index.js';
 import { FrameEvent } from '../../engine/engine_context.js';
 import { isLocalNetwork } from '../../engine/engine_networking_utils.js';
 import { serializable } from '../../engine/engine_serialization.js';
-import type { GuidsMap } from '../../engine/engine_types.js';
 import { deepClone, delay, getParam } from '../../engine/engine_utils.js';
 import { Animator } from '../Animator.js';
 import { AudioListener } from '../AudioListener.js';
@@ -45,7 +44,7 @@ export enum ClipExtrapolation {
 };
 
 /** @internal */
-export type CreateTrackFunction = (director: PlayableDirector, track: Models.TrackModel) => Tracks.TrackHandler | undefined | null;
+export type CreateTrackFunction = (director: PlayableDirector, track: Models.TrackModel) => Tracks.TimelineTrackHandler | undefined | null;
 
 /**
  * PlayableDirector is the main component for controlling timelines in Needle Engine.  
@@ -115,7 +114,15 @@ export class PlayableDirector extends Behaviour {
      * The timeline asset containing tracks, clips, and markers that this director will play.
      * Assign a timeline asset exported from Unity or Blender to enable playback.
      */
-    playableAsset?: Models.TimelineAssetModel;
+    @serializable()
+    get playableAsset(): Models.TimelineAssetModel | undefined { return this._playableAsset; }
+    set playableAsset(value: Models.TimelineAssetModel | undefined) {
+        if (this._playableAsset !== value) {
+            this._playableAsset = value;
+            this._needsGraphRebuild = true;
+        }
+    }
+    private _playableAsset?: Models.TimelineAssetModel;
 
     /**
      * When true, the timeline starts playing automatically when the component awakens.
@@ -123,7 +130,7 @@ export class PlayableDirector extends Behaviour {
      * @default false
      */
     @serializable()
-    playOnAwake?: boolean;
+    playOnAwake: boolean = false;
 
     /**
      * Determines how the timeline behaves when it reaches the end of its duration.
@@ -207,14 +214,10 @@ export class PlayableDirector extends Behaviour {
     onEnable() {
         if (debug) console.log("[Timeline] OnEnable", this.name, this.playOnAwake);
 
-        for (const track of this._audioTracks) {
-            track.onEnable?.();
-        }
-        for (const track of this._customTracks) {
-            track.onEnable?.();
-        }
-        for (const track of this._animationTracks) {
-            track.onEnable?.();
+        for (const tracks of this._allTracks) {
+            for (const track of tracks) {
+                track.onEnable?.();
+            }
         }
         if (this.playOnAwake) {
             this.play();
@@ -265,6 +268,7 @@ export class PlayableDirector extends Behaviour {
         this.resolveBindings();
         this.updateTimelineDuration();
         this.setupAndCreateTrackHandlers();
+        this._needsGraphRebuild = false;
     }
 
     /**
@@ -273,6 +277,8 @@ export class PlayableDirector extends Behaviour {
      */
     async play() {
         if (!this.isValid()) return;
+        // Ensure graph is built (handles the case where playableAsset is assigned after awake)
+        if (this._needsGraphRebuild) this.rebuildGraph();
         const pauseChanged = this._isPaused == true;
         this._isPaused = false;
         if (this._isPlaying) return;
@@ -290,8 +296,13 @@ export class PlayableDirector extends Behaviour {
                 await Promise.all(promises);
                 if (!this._isPlaying) return;
             }
-            while (this._audioTracks.length > 0 && this._isPlaying && !AudioSource.userInteractionRegistered && this.waitForAudio)
+            let ticks = 0;
+            while (this._audioTracks.length > 0 && this._isPlaying && !AudioSource.userInteractionRegistered && this.waitForAudio) {
+                if (ticks++ <= 0) {
+                    if (isDevEnvironment() || debug) console.warn(`[Timeline] Waiting for user interaction to play audio... (timeline '${this.name}' will start as soon as user interacts with the page). To start the timeline immediately without waiting for user interaction, set 'waitForAudio' to false on the PlayableDirector component.`);
+                }
                 await delay(200);
+            }
         }
         this.invokeStateChangedMethodsOnTracks();
         // Update timeline in LateUpdate to give other scripts time to react to the updated state  
@@ -343,6 +354,7 @@ export class PlayableDirector extends Behaviour {
      * Evaluate the timeline at the current time. This is useful when you want to manually update the timeline e.g. when the timeline is paused and you set `time` to a new value.
      */
     evaluate() {
+        if (this._needsGraphRebuild) this.rebuildGraph();
         this.internalEvaluate(true);
     }
 
@@ -373,7 +385,7 @@ export class PlayableDirector extends Behaviour {
     /**
      * @returns all audio tracks of the timeline
      */
-    get audioTracks(): Tracks.AudioTrackHandler[] {
+    get audioTracks(): Tracks.TimelineAudioTrack[] {
         return this._audioTracks;
     }
 
@@ -387,10 +399,24 @@ export class PlayableDirector extends Behaviour {
     /**
      * @returns all marker tracks of the timeline
      */
-    get markerTracks(): Tracks.MarkerTrackHandler[] {
+    get markerTracks(): Tracks.TimelineMarkerTrack[] {
         return this._markerTracks;
     }
 
+    /**
+     * @returns all activation tracks of the timeline
+     */
+    get activationTracks(): Tracks.TimelineActivationTrack[] {
+        return this._activationTracks;
+    }
+
+    /**
+     * @returns all tracks of the timeline
+     */
+    get tracks(): ReadonlyArray<Tracks.TimelineTrackHandler> {
+        return this._allTracks.flat();
+    }
+
     /**
      * Iterates over all markers of the timeline, optionally filtering by type
      * 
@@ -412,37 +438,37 @@ export class PlayableDirector extends Behaviour {
     }
 
 
-    private _guidsMap?: GuidsMap;
-    /** @internal */
-    resolveGuids(map: GuidsMap) {
-        this._guidsMap = map;
-    }
 
     // INTERNALS
 
+    private _needsGraphRebuild: boolean = false;
     private _isPlaying: boolean = false;
     private _internalUpdateRoutine: any;
     private _isPaused: boolean = false;
     /** internal, true during the time stop() is being processed */
     private _isStopping: boolean = false;
+    /** @internal Whether the current evaluate() was triggered by user code (not the internal update loop or stop/pause). */
+    _isUserEvaluation: boolean = false;
     private _time: number = 0;
     private _duration: number = 0;
     private _weight: number = 1;
-    private readonly _animationTracks: Array<Tracks.AnimationTrackHandler> = [];
-    private readonly _audioTracks: Array<Tracks.AudioTrackHandler> = [];
+    private readonly _animationTracks: Array<Tracks.TimelineAnimationTrack> = [];
+    private readonly _audioTracks: Array<Tracks.TimelineAudioTrack> = [];
     private readonly _signalTracks: Array<Tracks.SignalTrackHandler> = [];
-    private readonly _markerTracks: Array<Tracks.MarkerTrackHandler> = [];
-    private readonly _controlTracks: Array<Tracks.ControlTrackHandler> = [];
-    private readonly _customTracks: Array<Tracks.TrackHandler> = [];
+    private readonly _markerTracks: Array<Tracks.TimelineMarkerTrack> = [];
+    private readonly _controlTracks: Array<Tracks.TimelineControlTrack> = [];
+    private readonly _activationTracks: Array<Tracks.TimelineActivationTrack> = [];
+    private readonly _customTracks: Array<Tracks.TimelineTrackHandler> = [];
 
-    private readonly _tracksArray: Array<Array<Tracks.TrackHandler>> = [];
-    private get _allTracks(): Array<Array<Tracks.TrackHandler>> {
+    private readonly _tracksArray: Array<Array<Tracks.TimelineTrackHandler>> = [];
+    private get _allTracks(): Array<Array<Tracks.TimelineTrackHandler>> {
         this._tracksArray.length = 0;
         this._tracksArray.push(this._animationTracks);
         this._tracksArray.push(this._audioTracks);
         this._tracksArray.push(this._signalTracks);
         this._tracksArray.push(this._markerTracks);
         this._tracksArray.push(this._controlTracks);
+        this._tracksArray.push(this._activationTracks);
         this._tracksArray.push(this._customTracks);
         return this._tracksArray;
     }
@@ -503,60 +529,32 @@ export class PlayableDirector extends Behaviour {
 
         const time = this._time;
 
-        for (const track of this.playableAsset!.tracks) {
-            if (track.muted) continue;
-            switch (track.type) {
-                case Models.TrackType.Activation:
-                    // when the timeline is being disabled or stopped 
-                    // then we want to leave objects active state as they were
-                    // see NE-3241
-                    // TODO: support all "post-playback-state" settings an activation track has, this is just "Leave as is"
-                    if (!called_by_user && !this._isPlaying) continue;
-
-                    for (let i = 0; i < track.outputs.length; i++) {
-                        const binding = track.outputs[i];
-                        if (typeof binding === "object") {
-                            let isActive: boolean = false;
-                            if (track.clips) {
-                                for (const clip of track.clips) {
-                                    if (clip.start <= time && time <= clip.end) {
-                                        isActive = true;
-                                    }
-                                }
-                            }
-                            const obj = binding as Object3D;
-                            if (obj.visible !== undefined) {
-                                if (obj.visible !== isActive) {
-                                    obj.visible = isActive;
-                                    if (debug)
-                                        console.warn(this.name, "set ActivationTrack-" + i, obj.name, isActive, time);
-                                }
-                            }
-                        }
-                    }
-                    break;
-
-            }
-        }
-
+        this._isUserEvaluation = called_by_user;
         for (const track of this._allTracks) {
             for (const handler of track) {
                 // When timeline reaches the end "stop()" is called which is evaluating with time 0
                 // We don't want to re-evaluate the animation then in case the timeline is blended with the Animator
                 // e.g then the timeline animation at time 0 is 100% applied on top of the animator animation
-
-                if (this._isStopping && handler instanceof Tracks.AnimationTrackHandler) {
+                if (this._isStopping && handler instanceof Tracks.TimelineAnimationTrack) {
                     continue;
                 }
                 handler.evaluate(time);
             }
         }
+        this._isUserEvaluation = false;
     }
 
     private resolveBindings() {
         if (!this._clonedPlayableAsset) {
             this._clonedPlayableAsset = true;
-            this.playableAsset = deepClone(this.playableAsset);
+            // Deep clone so each director owns its own copy of the asset data.
+            // Needed because NEEDLE_persistent_assets returns the same shared object for all references —
+            // without this, resolving guid strings below would mutate shared data.
+            // On instantiated clones this is skipped (_clonedPlayableAsset is copied as true)
+            // because the instantiate resolve system already created an independent copy.
+            this.playableAsset = deepClone(this.playableAsset, (_obj, _key, val) => {
+                return !(val?.isObject3D === true);
+            });
         }
 
         if (!this.playableAsset || !this.playableAsset.tracks) return;
@@ -569,15 +567,13 @@ export class PlayableDirector extends Behaviour {
 
         for (const track of this.playableAsset.tracks) {
             for (let i = track.outputs.length - 1; i >= 0; i--) {
-                let binding = track.outputs[i];
+                const binding = track.outputs[i];
                 if (typeof binding === "string") {
-                    if (this._guidsMap && this._guidsMap[binding])
-                        binding = this._guidsMap[binding];
                     const obj = GameObject.findByGuid(binding, root);
                     if (obj === null || typeof obj !== "object") {
                         // if the binding is missing remove it to avoid unnecessary loops
                         track.outputs.splice(i, 1);
-                        console.warn("Failed to resolve binding", binding, track.name, track.type);
+                        console.warn(`[Timeline] Failed to resolve binding on track '${track.name}' of type '${track.type}' in director '${this.name}' with timeline asset '${this.playableAsset.name}' ('${binding}' not found in scene)`);
                     }
                     else {
                         if (debug)
@@ -592,21 +588,20 @@ export class PlayableDirector extends Behaviour {
                         continue;
                     }
                     // if the binding is missing remove it to avoid unnecessary loops
-                    if (track.type !== Models.TrackType.Audio && track.type !== Models.TrackType.Control && track.type !== Models.TrackType.Marker && track.type !== Models.TrackType.Signal)
-                        console.warn("Missing binding", binding, track.name, track.type, this.name, this.playableAsset.name);
+                    if (track.type !== Models.TrackType.Audio && track.type !== Models.TrackType.Control && track.type !== Models.TrackType.Marker && track.type !== Models.TrackType.Signal) {
+                        console.warn(`[Timeline] Missing binding on track '${track.name}' of type '${track.type}' in director '${this.name}' with timeline asset '${this.playableAsset.name}' (null binding)`);
+                    }
                 }
             }
             if (track.type === Models.TrackType.Control) {
                 if (track.clips) {
                     for (let i = 0; i < track.clips.length; i++) {
                         const clip = track.clips[i];
-                        let binding = clip.asset.sourceObject;
+                        const binding = clip.asset.sourceObject;
                         if (typeof binding === "string") {
-                            if (this._guidsMap && this._guidsMap[binding])
-                                binding = this._guidsMap[binding];
                             const obj = GameObject.findByGuid(binding, root);
                             if (obj === null || typeof obj !== "object") {
-                                console.warn("Failed to resolve sourceObject binding", binding, track.name, clip);
+                                console.warn(`[Timeline] Failed to resolve sourceObject binding on track '${track.name}' of type '${track.type}' in director '${this.name}' with timeline asset '${this.playableAsset.name}' ('${binding}' not found in scene)`);
                             }
                             else {
                                 if (debug)
@@ -649,6 +644,7 @@ export class PlayableDirector extends Behaviour {
         this._animationTracks.length = 0;
         this._audioTracks.length = 0;
         this._signalTracks.length = 0;
+        this._activationTracks.length = 0;
 
         if (!this.playableAsset) return;
         let audioListener: AudioListener | null = GameObject.findObjectOfType(AudioListener, this.context);
@@ -656,7 +652,7 @@ export class PlayableDirector extends Behaviour {
             const type = track.type;
             const registered = PlayableDirector.createTrackFunctions[type];
             if (registered !== null && registered !== undefined) {
-                const res = registered(this, track) as Tracks.TrackHandler;
+                const res = registered(this, track) as Tracks.TimelineTrackHandler;
                 if (typeof res.evaluate === "function") {
                     res.director = this;
                     res.track = track;
@@ -679,7 +675,7 @@ export class PlayableDirector extends Behaviour {
                     }
                     const animationClips = binding?.gameObject?.animations;
                     if (animationClips) {
-                        const handler = new Tracks.AnimationTrackHandler();
+                        const handler = new Tracks.TimelineAnimationTrack();
                         handler.trackOffset = track.trackOffset;
                         handler.director = this;
                         handler.track = track;
@@ -729,7 +725,7 @@ export class PlayableDirector extends Behaviour {
             }
             else if (track.type === Models.TrackType.Audio) {
                 if (!track.clips || track.clips.length <= 0) continue;
-                const audio = new Tracks.AudioTrackHandler();
+                const audio = new Tracks.TimelineAudioTrack();
                 audio.director = this;
                 audio.track = track;
                 audio.audioSource = track.outputs.find(o => o instanceof AudioSource) as AudioSource;
@@ -753,7 +749,7 @@ export class PlayableDirector extends Behaviour {
                     signalHandler.director = this;
                     signalHandler.track = track;
 
-                    const markerHandler: Tracks.MarkerTrackHandler = new Tracks.MarkerTrackHandler();
+                    const markerHandler: Tracks.TimelineMarkerTrack = new Tracks.TimelineMarkerTrack();
                     markerHandler.director = this;
                     markerHandler.track = track;
 
@@ -799,7 +795,7 @@ export class PlayableDirector extends Behaviour {
                 this._signalTracks.push(handler);
             }
             else if (track.type === Models.TrackType.Control) {
-                const handler = new Tracks.ControlTrackHandler();
+                const handler = new Tracks.TimelineControlTrack();
                 handler.director = this;
                 handler.track = track;
                 if (track.clips) {
@@ -810,6 +806,12 @@ export class PlayableDirector extends Behaviour {
                 handler.resolveSourceObjects(this.context);
                 this._controlTracks.push(handler);
             }
+            else if (track.type === Models.TrackType.Activation) {
+                const handler = new Tracks.TimelineActivationTrack();
+                handler.director = this;
+                handler.track = track;
+                this._activationTracks.push(handler);
+            }
         }
     }
 

package/src/engine-components/timeline/SignalAsset.ts

@@ -1,4 +1,5 @@
 import { serializable } from "../../engine/engine_serialization_decorator.js";
+import { ISignalReceiver } from "../../engine/engine_types.js";
 import { getParam } from "../../engine/engine_utils.js";
 import { Behaviour } from "../Component.js";
 import { EventList } from "../EventList.js";
@@ -33,7 +34,9 @@ export class SignalReceiverEvent {
  * @category Animation and Sequencing
  * @group Components
  */
-export class SignalReceiver extends Behaviour {
+export class SignalReceiver extends Behaviour implements ISignalReceiver {
+
+    readonly isSignalReceiver = true;
 
     private static receivers: { [key: string]: SignalReceiver[] } = {};