@needle-tools/engine 5.1.0-alpha.3 → 5.1.0-alpha.4

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

@@ -591,6 +591,20 @@ const muteAudioTracks = getParam("mutetimeline");
 
 declare type AudioClipModel = Models.ClipModel & { _didTriggerPlay: boolean };
 
+/**
+ * Handles audio playback for a timeline audio track.
+ *
+ * **Runtime mutation:** The track model is read fresh every frame during `evaluate()`.
+ * You can mutate `track.volume`, `clip.start`, `clip.end`, `clip.asset.volume` etc.
+ * at any time — changes take effect on the next frame without rebuilding the timeline.
+ *
+ * **Audio stopping:** Audio clips are automatically stopped when:
+ * - Timeline time moves outside a clip's `[start, end]` range (e.g. jumping or normal playback advancing past a clip)
+ * - The track is muted (via `muted = true`)
+ * - The director is stopped (`director.stop()`)
+ * - The director is paused (`director.pause()`)
+ * - The director is disabled or destroyed
+ */
 export class AudioTrackHandler extends TrackHandler {
 
     models: Array<AudioClipModel> = [];
@@ -600,6 +614,10 @@ export class AudioTrackHandler extends TrackHandler {
     lastTime: number = 0;
     audioSource?: AudioSource;
 
+    /** Track-level volume multiplier (0–1). Applied on top of per-clip volume each frame. */
+    get volume(): number { return this.track.volume ?? 1; }
+    set volume(val: number) { this.track.volume = val; }
+
     private _audioLoader: AudioLoader | null = null;
 
     private getAudioFilePath(path: string) {
@@ -863,21 +881,29 @@ export class SignalTrackHandler extends TrackHandler {
     didTrigger: boolean[] = [];
     receivers: Array<SignalReceiver | null> = [];
 
-    // TODO: test when timeline signals are being reset in Unity
-    // onEnable() {
-    //     for (let i = 0; i < this.didTrigger?.length; i++) {
-    //         this.didTrigger[i] = false;
-    //     }
-    // }
+    private _lastTime: number = -1;
+
+    onEnable() {
+        // Reset state so signals fire fresh on replay
+        this._lastTime = -1;
+        for (let i = 0; i < this.didTrigger.length; i++) {
+            this.didTrigger[i] = false;
+        }
+    }
 
-    // private _lastTime: number = -1;
+    onMuteChanged() {
+        // When unmuted, sync _lastTime to avoid stale comparisons
+        if (!this.track.muted) {
+            this._lastTime = -1;
+        }
+    }
 
     evaluate(time: number) {
         if (this.track.muted) return;
 
-        // let lastTime = this._lastTime;
-        // if (lastTime === -1) lastTime = time;
-        // this._lastTime = time;
+        let lastTime = this._lastTime;
+        if (lastTime === -1) lastTime = time;
+        this._lastTime = time;
 
         const estimatedFrameLengthWithPadding = this.director.context.time.deltaTime * 1.5;
 
@@ -899,7 +925,6 @@ export class SignalTrackHandler extends TrackHandler {
                     isActive = true;
                 }
             }
-            // console.log(time, td, isActive);
             if (isActive) {
                 if (!wasTriggered) {
                     if (debug)
@@ -917,9 +942,45 @@ export class SignalTrackHandler extends TrackHandler {
                     }
                 }
             }
-            else {
-                if (!model.emitOnce)
+            else if (!model.emitOnce) {
+                // Only reset didTrigger when time has moved backward past the signal
+                // (e.g. timeline looped or was scrubbed back). Don't reset just because
+                // the deltaTime-based activation window shrank on a fast frame.
+                if (time < model.time && lastTime >= model.time) {
                     this.didTrigger[i] = false;
+                }
+            }
+        }
+    }
+}
+
+
+export class ActivationTrackHandler extends TrackHandler {
+
+    evaluate(time: number) {
+        if (this.track.muted) return;
+        // NE-3241 / NE-3737: Don't evaluate when stopped (preserves "Leave as is" post-playback).
+        // But DO evaluate if the user explicitly called director.evaluate().
+        if (!this.director.isPlaying && !this.director._isUserEvaluation) return;
+
+        for (let i = 0; i < this.track.outputs.length; i++) {
+            const binding = this.track.outputs[i];
+            if (typeof binding !== "object" || binding === null) continue;
+
+            let isActive = false;
+            if (this.track.clips) {
+                for (const clip of this.track.clips) {
+                    if (clip.start <= time && time <= clip.end) {
+                        isActive = true;
+                        break;
+                    }
+                }
+            }
+
+            const obj = binding as Object3D;
+            if (obj.visible !== undefined && obj.visible !== isActive) {
+                obj.visible = isActive;
+                if (debug) console.warn(this.director.name, "ActivationTrack-" + i, obj.name, isActive, time);
             }
         }
     }

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

@@ -1,4 +1,5 @@
-export { type ITimelineAnimationCallbacks as ITimelineAnimationOverride } from "./PlayableDirector.js"
+export { DirectorWrapMode, type ITimelineAnimationCallbacks as ITimelineAnimationOverride } from "./PlayableDirector.js"
 export * from "./SignalAsset.js"
+export * from "./TimelineBuilder.js"
 export * from "./TimelineModels.js"
 export * from "./TimelineTracks.js"