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

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 { $TXm } 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 (!$TXm()) {
             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 (!$TXm()) {
                             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 (!$TXm()) {
             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[] } = {};