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

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';
@@ -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;
@@ -343,6 +349,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);
     }
 
@@ -391,6 +398,20 @@ export class PlayableDirector extends Behaviour {
         return this._markerTracks;
     }
 
+    /**
+     * @returns all activation tracks of the timeline
+     */
+    get activationTracks(): Tracks.ActivationTrackHandler[] {
+        return this._activationTracks;
+    }
+
+    /**
+     * @returns all tracks of the timeline
+     */
+    get tracks(): ReadonlyArray<Tracks.TrackHandler> {
+        return this._allTracks.flat();
+    }
+
     /**
      * Iterates over all markers of the timeline, optionally filtering by type
      * 
@@ -412,19 +433,17 @@ 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;
@@ -433,6 +452,7 @@ export class PlayableDirector extends Behaviour {
     private readonly _signalTracks: Array<Tracks.SignalTrackHandler> = [];
     private readonly _markerTracks: Array<Tracks.MarkerTrackHandler> = [];
     private readonly _controlTracks: Array<Tracks.ControlTrackHandler> = [];
+    private readonly _activationTracks: Array<Tracks.ActivationTrackHandler> = [];
     private readonly _customTracks: Array<Tracks.TrackHandler> = [];
 
     private readonly _tracksArray: Array<Array<Tracks.TrackHandler>> = [];
@@ -443,6 +463,7 @@ export class PlayableDirector extends Behaviour {
         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 +524,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) {
                     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 +562,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 +583,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 +639,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);
@@ -810,6 +801,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.ActivationTrackHandler();
+                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[] } = {};