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

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

@@ -42,7 +42,7 @@ export enum ClipExtrapolation {
  * @category Animation and Sequencing
  * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
  */
-export declare type TrackModel = {
+export type TrackModel = {
     name: string;
     type: TrackType;
     muted: boolean;
@@ -53,6 +53,10 @@ export declare type TrackModel = {
     volume?: number;
 }
 
+export function isTrackModel(obj:unknown): obj is TrackModel {
+    return typeof obj === "object" && obj !== null && "name" in obj && "type" in obj && "outputs" in obj && "muted" in obj;
+}
+
 declare type Vec3 = { x: number, y: number, z: number };
 declare type Quat = { x: number, y: number, z: number, w: number };
 

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

@@ -4,13 +4,14 @@ import { isDevEnvironment } from "../../engine/debug/index.js";
 import { Context } from "../../engine/engine_setup.js";
 import type { Constructor } from "../../engine/engine_types.js";
 import { getParam, resolveUrl } from "../../engine/engine_utils.js";
-import { setObjectAnimated } from "../AnimationUtils.js";
 import { Animator } from "../Animator.js"
 import { AudioSource } from "../AudioSource.js";
 import { GameObject } from "../Component.js";
 import type { PlayableDirector } from "./PlayableDirector.js";
 import { SignalReceiver } from "./SignalAsset.js";
 import * as Models from "./TimelineModels.js";
+import type { TimelineBuilder } from "./TimelineBuilder.js";
+import { AnimationUtils } from "../../engine/engine_animation.js";
 
 const debug = getParam("debugtimeline");
 
@@ -18,7 +19,7 @@ const debug = getParam("debugtimeline");
  * A TrackHandler is responsible for evaluating a specific type of timeline track.  
  * A timeline track can be an animation track, audio track, signal track, control track etc and is controlled by a {@link PlayableDirector}.
  */
-export abstract class TrackHandler {
+export abstract class TimelineTrackHandler {
     director!: PlayableDirector;
     track!: Models.TrackModel;
 
@@ -136,7 +137,7 @@ class AnimationClipOffsetData {
 }
 
 // TODO: add support for clip clamp modes (loop, pingpong, clamp)
-export class AnimationTrackHandler extends TrackHandler {
+export class TimelineAnimationTrack extends TimelineTrackHandler {
     /** @internal */
     models: Array<Models.ClipModel> = [];
     /** @internal */
@@ -178,7 +179,7 @@ export class AnimationTrackHandler extends TrackHandler {
     onStateChanged() {
         if (this._animator) {
             // We can not check the *isPlaying* state here because the timeline might be paused and evaluated by e.g. ScrollFollow
-            setObjectAnimated(this._animator.gameObject, this, this.director.enabled && this.director.weight > 0);
+            AnimationUtils.setObjectAnimated(this._animator.gameObject, this, this.director.enabled && this.director.weight > 0);
         }
     }
 
@@ -262,7 +263,7 @@ export class AnimationTrackHandler extends TrackHandler {
             // which overrides the timeline
             this._animator = GameObject.getComponent(this.target, Animator) ?? null;
             if (this._animator) {
-                setObjectAnimated(this._animator.gameObject, this, true);
+                AnimationUtils.setObjectAnimated(this._animator.gameObject, this, true);
             }
         }
 
@@ -591,7 +592,21 @@ const muteAudioTracks = getParam("mutetimeline");
 
 declare type AudioClipModel = Models.ClipModel & { _didTriggerPlay: boolean };
 
-export class AudioTrackHandler extends TrackHandler {
+/**
+ * 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 TimelineAudioTrack extends TimelineTrackHandler {
 
     models: Array<AudioClipModel> = [];
     listener!: AudioListener;
@@ -600,6 +615,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) {
@@ -796,7 +815,7 @@ export class AudioTrackHandler extends TrackHandler {
     private static _audioBuffers: Map<string, Promise<AudioBuffer | null>> = new Map();
 
     public static dispose() {
-        AudioTrackHandler._audioBuffers.clear();
+        TimelineAudioTrack._audioBuffers.clear();
     }
 
     private handleAudioLoading(model: Models.ClipModel, audio: Audio): Promise<AudioBuffer | null> | null {
@@ -806,8 +825,8 @@ export class AudioTrackHandler extends TrackHandler {
         // TODO: maybe we should cache the loaders / buffers here by path
         const path = this.getAudioFilePath(model.asset.clip);
 
-        if (AudioTrackHandler._audioBuffers.get(path)) {
-            const promise = AudioTrackHandler._audioBuffers.get(path)!
+        if (TimelineAudioTrack._audioBuffers.get(path)) {
+            const promise = TimelineAudioTrack._audioBuffers.get(path)!
             promise.then((buffer) => {
                 if (buffer) audio.setBuffer(buffer);
             });
@@ -827,17 +846,17 @@ export class AudioTrackHandler extends TrackHandler {
                     resolve(null);
                 });
         });
-        AudioTrackHandler._audioBuffers.set(path, loadingPromise);
+        TimelineAudioTrack._audioBuffers.set(path, loadingPromise);
         return loadingPromise;
     }
 }
 
-export class MarkerTrackHandler extends TrackHandler {
+export class TimelineMarkerTrack extends TimelineTrackHandler {
     models: Array<Models.MarkerModel & Record<string, any>> = [];
     needsSorting = true;
 
     *foreachMarker<T>(type: string | null = null) {
-        if(this.needsSorting) this.sort();
+        if (this.needsSorting) this.sort();
         for (const model of this.models) {
             if (model && model.type === type) yield model as T;
         }
@@ -858,26 +877,34 @@ export class MarkerTrackHandler extends TrackHandler {
     }
 }
 
-export class SignalTrackHandler extends TrackHandler {
+export class SignalTrackHandler extends TimelineTrackHandler {
     models: Models.SignalMarkerModel[] = [];
     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;
 
-    // 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;
+        }
+    }
+
+    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 +926,6 @@ export class SignalTrackHandler extends TrackHandler {
                     isActive = true;
                 }
             }
-            // console.log(time, td, isActive);
             if (isActive) {
                 if (!wasTriggered) {
                     if (debug)
@@ -917,16 +943,59 @@ 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;
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Handles activation (visibility) of bound objects for a timeline activation track.
+ *
+ * Each clip on the track defines a time range during which the bound objects should be active (visible).
+ * @see TimelineTrackHandler for details on how tracks and clips work in general, and how to mutate them at runtime.
+ * @see PlayableDirector for how to control timeline playback and time.
+ * @see TimelineBuilder for how to create and configure timelines and tracks in the editor.
+ */
+export class TimelineActivationTrack extends TimelineTrackHandler {
+
+    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);
             }
         }
     }
 }
 
 
-export class ControlTrackHandler extends TrackHandler {
+export class TimelineControlTrack extends TimelineTrackHandler {
     models: Array<Models.ClipModel> = [];
     timelines: Array<PlayableDirector | null> = [];
 

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"

package/src/engine-components/web/CursorFollow.ts

@@ -178,7 +178,6 @@ export class CursorFollow extends Behaviour {
      * - Cursor that follows terrain or mesh surfaces
      *
      * **Important notes:**
-     * - Requires objects in the scene to have colliders for raycasting to work
      * - Works best with {@link keepDistance} set to `false` to allow depth changes
      * - Can be combined with {@link damping} for smooth surface following
      * - The raycast uses the physics system's raycast functionality