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

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

@@ -1,10 +1,15 @@
 import { AnimationClip, Object3D } from "three";
+import type { Light, Material, PerspectiveCamera } from "three";
 
 import type { Animator } from "../Animator.js";
 import type { AudioSource } from "../AudioSource.js";
 import { GameObject } from "../Component.js";
 import { InstantiateIdProvider } from "../../engine/engine_networking_instantiate.js";
 import { EventList } from "../EventList.js";
+import { isTrackDescriptor, resolveToClip, track as trackFn, type TrackDescriptor, type TrackOptions, type AnimationKeyframe, type Tween, type Vec3Value, type QuatValue, type EulerValue, type ColorValue } from "../AnimationBuilder.js";
+
+/** Keyframe array or tween shorthand */
+type KF<V> = AnimationKeyframe<V>[] | Tween<V>;
 import { SignalAsset, SignalReceiver, SignalReceiverEvent } from "./SignalAsset.js";
 import type { PlayableDirector } from "./PlayableDirector.js";
 import { ClipExtrapolation, TrackType } from "./TimelineModels.js";
@@ -108,6 +113,7 @@ type BuilderTrack = {
     volume?: number;
     trackOffset?: TrackOffset;
     cursor: number; // current time position for auto-advancing
+    inlineTracks: TrackDescriptor[]; // accumulated by .track() calls, committed at boundaries
 };
 
 type PendingSignal = {
@@ -116,6 +122,129 @@ type PendingSignal = {
     callback: Function;
 };
 
+
+// ============================================================
+// Track builder interfaces — typed views per track type
+// ============================================================
+
+/**
+ * Shared methods available on all track builders and the TimelineBuilder entry point.
+ * Provides track creation, build, and install methods.
+ *
+ * @category Animation and Sequencing
+ */
+export interface TimelineBuilderBase {
+    /** Adds an animation track. Chain `.clip()` or `.track()` to add content. */
+    animationTrack(name: string, binding?: Animator | Object3D | null): AnimationTrackBuilder;
+    /** Adds an audio track. Chain `.clip()` to add audio clips. */
+    audioTrack(name: string, binding?: AudioSource | Object3D | null, volume?: number): AudioTrackBuilder;
+    /** Adds an activation track. Chain `.clip()` to define activation windows. */
+    activationTrack(name: string, binding?: Object3D | null): ActivationTrackBuilder;
+    /** Adds a control track. Chain `.clip()` to control nested objects/timelines. */
+    controlTrack(name: string): ControlTrackBuilder;
+    /** Adds a signal track. Chain `.signal()` or `.marker()` to add events. */
+    signalTrack(name: string, binding?: SignalReceiver | Object3D | null): SignalTrackBuilder;
+    /** Adds a marker track. Chain `.marker()` to add markers. */
+    markerTrack(name: string): MarkerTrackBuilder;
+    /** Builds and returns the {@link TimelineAssetModel}. */
+    build(): TimelineAssetModel;
+    /** Builds the timeline, assigns it to the director, and wires up signal callbacks. */
+    install(director: PlayableDirector): TimelineAssetModel;
+}
+
+/**
+ * Builder for animation tracks.
+ * Provides `.clip()` for pre-built AnimationClips and `.track()` for inline animation definition.
+ *
+ * @category Animation and Sequencing
+ */
+export interface AnimationTrackBuilder extends TimelineBuilderBase {
+    /** Adds a pre-built AnimationClip */
+    clip(asset: AnimationClip, options?: AnimationClipOptions): AnimationTrackBuilder;
+    /** Adds a clip from a single {@link TrackDescriptor} */
+    clip(descriptor: TrackDescriptor, options?: AnimationClipOptions): AnimationTrackBuilder;
+    /** Adds a clip from multiple {@link TrackDescriptor}s */
+    clip(descriptors: TrackDescriptor[], options?: AnimationClipOptions): AnimationTrackBuilder;
+    /** Adds an animation track for an Object3D's position or scale */
+    track(target: Object3D, property: "position" | "scale", keyframes: KF<Vec3Value>, options?: TrackOptions): AnimationTrackBuilder;
+    /** Adds an animation track for an Object3D's quaternion */
+    track(target: Object3D, property: "quaternion", keyframes: KF<QuatValue>, options?: TrackOptions): AnimationTrackBuilder;
+    /** Adds an animation track for an Object3D's rotation (Euler, converted to quaternion) */
+    track(target: Object3D, property: "rotation", keyframes: KF<EulerValue>, options?: TrackOptions): AnimationTrackBuilder;
+    /** Adds an animation track for an Object3D's visibility */
+    track(target: Object3D, property: "visible", keyframes: KF<boolean>, options?: TrackOptions): AnimationTrackBuilder;
+    /** Adds an animation track for a material's numeric property */
+    track(target: Material, property: "opacity" | "roughness" | "metalness" | "alphaTest" | "emissiveIntensity" | "envMapIntensity" | "bumpScale" | "displacementScale" | "displacementBias", keyframes: KF<number>, options?: TrackOptions): AnimationTrackBuilder;
+    /** Adds an animation track for a material's color property */
+    track(target: Material, property: "color" | "emissive", keyframes: KF<ColorValue>, options?: TrackOptions): AnimationTrackBuilder;
+    /** Adds an animation track for a light's numeric property */
+    track(target: Light, property: "intensity" | "distance" | "angle" | "penumbra" | "decay", keyframes: KF<number>, options?: TrackOptions): AnimationTrackBuilder;
+    /** Adds an animation track for a light's color */
+    track(target: Light, property: "color", keyframes: KF<ColorValue>, options?: TrackOptions): AnimationTrackBuilder;
+    /** Adds an animation track for a camera's numeric property */
+    track(target: PerspectiveCamera, property: "fov" | "near" | "far" | "zoom", keyframes: KF<number>, options?: TrackOptions): AnimationTrackBuilder;
+    /** Mutes this track so it is skipped during playback */
+    muted(muted?: boolean): AnimationTrackBuilder;
+}
+
+/**
+ * Builder for audio tracks. Provides `.clip()` for adding audio clips by URL.
+ * @category Animation and Sequencing
+ */
+export interface AudioTrackBuilder extends TimelineBuilderBase {
+    /** Adds an audio clip by URL */
+    clip(url: string, options: AudioClipOptions): AudioTrackBuilder;
+    /** Mutes this track so it is skipped during playback */
+    muted(muted?: boolean): AudioTrackBuilder;
+}
+
+/**
+ * Builder for activation tracks. Provides `.clip()` for defining activation windows.
+ * @category Animation and Sequencing
+ */
+export interface ActivationTrackBuilder extends TimelineBuilderBase {
+    /** Adds an activation clip that shows/hides the bound object */
+    clip(options: ActivationClipOptions): ActivationTrackBuilder;
+    /** Mutes this track so it is skipped during playback */
+    muted(muted?: boolean): ActivationTrackBuilder;
+}
+
+/**
+ * Builder for control tracks. Provides `.clip()` for controlling nested objects/timelines.
+ * @category Animation and Sequencing
+ */
+export interface ControlTrackBuilder extends TimelineBuilderBase {
+    /** Adds a control clip for a source object */
+    clip(sourceObject: Object3D, options: ControlClipOptions): ControlTrackBuilder;
+    /** Mutes this track so it is skipped during playback */
+    muted(muted?: boolean): ControlTrackBuilder;
+}
+
+/**
+ * Builder for signal tracks. Provides `.signal()` for callback-based signals and `.marker()` for asset-based markers.
+ * @category Animation and Sequencing
+ */
+export interface SignalTrackBuilder extends TimelineBuilderBase {
+    /** Adds a signal with a callback that fires at the given time */
+    signal(time: number, callback: Function, options?: SignalMarkerOptions): SignalTrackBuilder;
+    /** Adds a signal marker referencing a signal asset by guid */
+    marker(time: number, asset: string, options?: SignalMarkerOptions): SignalTrackBuilder;
+    /** Mutes this track so it is skipped during playback */
+    muted(muted?: boolean): SignalTrackBuilder;
+}
+
+/**
+ * Builder for marker tracks. Provides `.marker()` for adding markers.
+ * @category Animation and Sequencing
+ */
+export interface MarkerTrackBuilder extends TimelineBuilderBase {
+    /** Adds a marker referencing a signal asset by guid */
+    marker(time: number, asset: string, options?: SignalMarkerOptions): MarkerTrackBuilder;
+    /** Mutes this track so it is skipped during playback */
+    muted(muted?: boolean): MarkerTrackBuilder;
+}
+
+
 /**
  * A fluent builder for creating timeline assets ({@link TimelineAssetModel}) from code.
  *
@@ -137,6 +266,19 @@ type PendingSignal = {
  * director.play();
  * ```
  *
+ * @example With inline tracks (no pre-built clips needed)
+ * ```ts
+ * TimelineBuilder.create("DoorSequence")
+ *     .animationTrack("Door", door)
+ *         .track(door, "position", { from: [0, 0, 0], to: [2, 0, 0], duration: 1 })
+ *         .track(light, "intensity", { from: 0, to: 5, duration: 1 })
+ *     .signalTrack("Events")
+ *         .signal(0.5, () => playSound("creak"))
+ *     .install(director);
+ *
+ * director.play();
+ * ```
+ *
  * @example Using install() with signal callbacks
  * ```ts
  * TimelineBuilder.create("WithSignals")
@@ -170,20 +312,37 @@ export class TimelineBuilder {
      * @param name - Name for the timeline asset
      * @param seed - Optional numeric seed for deterministic guid generation. Defaults to `Date.now()`.
      */
-    static create(name?: string, seed?: number): TimelineBuilder {
+    static create(name?: string, seed?: number): TimelineBuilderBase {
         return new TimelineBuilder(name ?? "Timeline", seed);
     }
 
     // #region Track creation
 
     /**
-     * Adds an animation track. Subsequent `.clip()` calls add animation clips to this track.
+     * Adds an animation track. Chain `.clip()` calls to add pre-built clips,
+     * or chain `.track()` calls to define animation data inline:
+     *
+     * @example With pre-built AnimationClip
+     * ```ts
+     * .animationTrack("Character", animator)
+     *     .clip(walkClip, { duration: 2, easeIn: 0.3 })
+     *     .clip(runClip, { duration: 3 })
+     * ```
+     *
+     * @example With inline tracks
+     * ```ts
+     * .animationTrack("Door", door)
+     *     .track(door, "position", { from: [0, 0, 0], to: [2, 0, 0], duration: 1 })
+     *     .track(light, "intensity", { from: 0, to: 5, duration: 1 })
+     * ```
+     *
      * @param name - Display name for the track
      * @param binding - The Animator or Object3D to animate
      */
-    animationTrack(name: string, binding?: Animator | Object3D | null): this {
+    animationTrack(name: string, binding?: Animator | Object3D | null): AnimationTrackBuilder {
+        this.commitInlineTracks();
         this._currentTrack = this.pushTrack(name, TrackType.Animation, binding ?? null);
-        return this;
+        return this as unknown as AnimationTrackBuilder;
     }
 
     /**
@@ -192,10 +351,11 @@ export class TimelineBuilder {
      * @param binding - The AudioSource to play audio on (optional)
      * @param volume - Track volume multiplier (default: 1)
      */
-    audioTrack(name: string, binding?: AudioSource | Object3D | null, volume?: number): this {
+    audioTrack(name: string, binding?: AudioSource | Object3D | null, volume?: number): AudioTrackBuilder {
+        this.commitInlineTracks();
         this._currentTrack = this.pushTrack(name, TrackType.Audio, binding ?? null);
         this._currentTrack.volume = volume;
-        return this;
+        return this as unknown as AudioTrackBuilder;
     }
 
     /**
@@ -203,18 +363,20 @@ export class TimelineBuilder {
      * @param name - Display name for the track
      * @param binding - The Object3D to show/hide
      */
-    activationTrack(name: string, binding?: Object3D | null): this {
+    activationTrack(name: string, binding?: Object3D | null): ActivationTrackBuilder {
+        this.commitInlineTracks();
         this._currentTrack = this.pushTrack(name, TrackType.Activation, binding ?? null);
-        return this;
+        return this as unknown as ActivationTrackBuilder;
     }
 
     /**
      * Adds a control track. Subsequent `.clip()` calls control nested timelines or objects.
      * @param name - Display name for the track
      */
-    controlTrack(name: string): this {
+    controlTrack(name: string): ControlTrackBuilder {
+        this.commitInlineTracks();
         this._currentTrack = this.pushTrack(name, TrackType.Control, null);
-        return this;
+        return this as unknown as ControlTrackBuilder;
     }
 
     /**
@@ -222,18 +384,20 @@ export class TimelineBuilder {
      * @param name - Display name for the track
      * @param binding - The SignalReceiver component (optional — if using `.signal()` with callbacks, one is created automatically by {@link install})
      */
-    signalTrack(name: string, binding?: SignalReceiver | Object3D | null): this {
+    signalTrack(name: string, binding?: SignalReceiver | Object3D | null): SignalTrackBuilder {
+        this.commitInlineTracks();
         this._currentTrack = this.pushTrack(name, TrackType.Signal, binding ?? null);
-        return this;
+        return this as unknown as SignalTrackBuilder;
     }
 
     /**
      * Adds a marker track. Use `.marker()` to add markers.
      * @param name - Display name for the track
      */
-    markerTrack(name: string): this {
+    markerTrack(name: string): MarkerTrackBuilder {
+        this.commitInlineTracks();
         this._currentTrack = this.pushTrack(name, TrackType.Marker, null);
-        return this;
+        return this as unknown as MarkerTrackBuilder;
     }
 
     // #endregion
@@ -243,23 +407,40 @@ export class TimelineBuilder {
     /**
      * Adds a clip to the current track. The clip type must match the track type.
      *
-     * - On an **animation track**: pass an `AnimationClip` and optional {@link AnimationClipOptions}
+     * - On an **animation track**: pass an `AnimationClip`, a {@link TrackDescriptor}, or a `TrackDescriptor[]` — and optional {@link AnimationClipOptions}
      * - On an **audio track**: pass a clip URL (string) and {@link AudioClipOptions}
      * - On an **activation track**: pass {@link ActivationClipOptions}
      * - On a **control track**: pass an Object3D and {@link ControlClipOptions}
      */
     clip(asset: AnimationClip, options?: AnimationClipOptions): this;
+    clip(descriptor: TrackDescriptor, options?: AnimationClipOptions): this;
+    clip(descriptors: TrackDescriptor[], options?: AnimationClipOptions): this;
     clip(url: string, options: AudioClipOptions): this;
     clip(options: ActivationClipOptions): this;
     clip(sourceObject: Object3D, options: ControlClipOptions): this;
-    clip(assetOrOptions: AnimationClip | string | Object3D | ActivationClipOptions, options?: AnimationClipOptions | AudioClipOptions | ControlClipOptions): this {
+    clip(assetOrOptions: AnimationClip | TrackDescriptor | TrackDescriptor[] | string | Object3D | ActivationClipOptions, options?: AnimationClipOptions | AudioClipOptions | ControlClipOptions): this {
         if (!this._currentTrack) throw new Error("TimelineBuilder: .clip() must be called after a track method (e.g. .animationTrack())");
+        this.commitInlineTracks();
 
         const track = this._currentTrack;
 
         switch (track.type) {
             case TrackType.Animation: {
-                const animClip = assetOrOptions as AnimationClip;
+                // Resolve TrackDescriptor(s) to AnimationClip if needed
+                let animClip: AnimationClip;
+                if (assetOrOptions instanceof AnimationClip) {
+                    animClip = assetOrOptions;
+                }
+                else {
+                    const descriptors = Array.isArray(assetOrOptions) ? assetOrOptions : [assetOrOptions as TrackDescriptor];
+                    // Use the track's binding as root for resolution
+                    const binding = track.outputs[0];
+                    const root = binding instanceof Object3D ? binding
+                        : (binding != null && "gameObject" in binding) ? (binding as any).gameObject as Object3D
+                        : undefined;
+                    animClip = resolveToClip(descriptors, root);
+                }
+
                 const opts = (options ?? {}) as AnimationClipOptions;
                 const duration = opts.duration ?? animClip.duration;
                 const start = opts.start ?? track.cursor;
@@ -459,6 +640,47 @@ export class TimelineBuilder {
         return this;
     }
 
+    // --- Object3D ---
+    /** Adds an animation track descriptor for an Object3D's position or scale to the current animation track */
+    track(target: Object3D, property: "position" | "scale", keyframes: KF<Vec3Value>, options?: TrackOptions): this;
+    /** Adds an animation track descriptor for an Object3D's quaternion to the current animation track */
+    track(target: Object3D, property: "quaternion", keyframes: KF<QuatValue>, options?: TrackOptions): this;
+    /** Adds an animation track descriptor for an Object3D's rotation (Euler, converted to quaternion) to the current animation track */
+    track(target: Object3D, property: "rotation", keyframes: KF<EulerValue>, options?: TrackOptions): this;
+    /** Adds an animation track descriptor for an Object3D's visibility to the current animation track */
+    track(target: Object3D, property: "visible", keyframes: KF<boolean>, options?: TrackOptions): this;
+    // --- Material ---
+    /** Adds an animation track descriptor for a material's numeric property to the current animation track */
+    track(target: Material, property: "opacity" | "roughness" | "metalness" | "alphaTest" | "emissiveIntensity" | "envMapIntensity" | "bumpScale" | "displacementScale" | "displacementBias", keyframes: KF<number>, options?: TrackOptions): this;
+    /** Adds an animation track descriptor for a material's color property to the current animation track */
+    track(target: Material, property: "color" | "emissive", keyframes: KF<ColorValue>, options?: TrackOptions): this;
+    // --- Light ---
+    /** Adds an animation track descriptor for a light's numeric property to the current animation track */
+    track(target: Light, property: "intensity" | "distance" | "angle" | "penumbra" | "decay", keyframes: KF<number>, options?: TrackOptions): this;
+    /** Adds an animation track descriptor for a light's color to the current animation track */
+    track(target: Light, property: "color", keyframes: KF<ColorValue>, options?: TrackOptions): this;
+    // --- Camera ---
+    /** Adds an animation track descriptor for a camera's numeric property to the current animation track */
+    track(target: PerspectiveCamera, property: "fov" | "near" | "far" | "zoom", keyframes: KF<number>, options?: TrackOptions): this;
+    /**
+     * Adds an animation track descriptor to the current animation track.
+     * Multiple `.track()` calls accumulate into a single animation clip that is
+     * committed when the next `.clip()`, track method, or `.build()`/`.install()` is called.
+     *
+     * Must be called after `.animationTrack()`.
+     *
+     * @param target - The object whose type determines valid properties and value types
+     * @param property - The property to animate
+     * @param keyframes - Keyframe array or {@link Tween} shorthand
+     * @param options - Optional {@link TrackOptions} with a `root` for named targeting
+     */
+    track(target: object, property: string, keyframes: KF<any>, options?: TrackOptions): this {
+        if (!this._currentTrack) throw new Error("TimelineBuilder: .track() must be called after .animationTrack()");
+        if (this._currentTrack.type !== TrackType.Animation) throw new Error("TimelineBuilder: .track() is only supported on animation tracks");
+        this._currentTrack.inlineTracks.push(trackFn(target as Object3D, property as "position", keyframes, options));
+        return this;
+    }
+
     // #endregion
 
     /**
@@ -469,6 +691,7 @@ export class TimelineBuilder {
      * internally and also wires up the SignalReceiver on the director's GameObject.
      */
     build(): TimelineAssetModel {
+        this.commitInlineTracks();
         const tracks: TrackModel[] = this._tracks.map(t => {
             const track: TrackModel = {
                 name: t.name,
@@ -555,10 +778,47 @@ export class TimelineBuilder {
             clips: [],
             markers: [],
             cursor: 0,
+            inlineTracks: [],
         };
         this._tracks.push(track);
         return track;
     }
 
+    /** Commits any pending `.track()` descriptors on the current animation track into a clip */
+    private commitInlineTracks(): void {
+        if (!this._currentTrack || this._currentTrack.inlineTracks.length === 0) return;
+
+        const t = this._currentTrack;
+        const binding = t.outputs[0];
+        const root = binding instanceof Object3D ? binding
+            : (binding != null && "gameObject" in binding) ? (binding as any).gameObject as Object3D
+            : undefined;
+        const animClip = resolveToClip(t.inlineTracks, root);
+
+        const start = t.cursor;
+        const duration = animClip.duration;
+
+        const clipModel: ClipModel = {
+            start,
+            end: start + duration,
+            duration,
+            timeScale: 1,
+            clipIn: 0,
+            easeInDuration: 0,
+            easeOutDuration: 0,
+            preExtrapolationMode: ClipExtrapolation.None,
+            postExtrapolationMode: ClipExtrapolation.None,
+            asset: {
+                clip: animClip,
+                loop: false,
+                duration: animClip.duration,
+                removeStartOffset: false,
+            } satisfies AnimationClipModel,
+        };
+        t.clips.push(clipModel);
+        t.cursor = start + duration;
+        t.inlineTracks = [];
+    }
+
     // #endregion
 }

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);
             }
         }
 
@@ -605,7 +606,7 @@ declare type AudioClipModel = Models.ClipModel & { _didTriggerPlay: boolean };
  * - The director is paused (`director.pause()`)
  * - The director is disabled or destroyed
  */
-export class AudioTrackHandler extends TrackHandler {
+export class TimelineAudioTrack extends TimelineTrackHandler {
 
     models: Array<AudioClipModel> = [];
     listener!: AudioListener;
@@ -814,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 {
@@ -824,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);
             });
@@ -845,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;
         }
@@ -876,7 +877,7 @@ export class MarkerTrackHandler extends TrackHandler {
     }
 }
 
-export class SignalTrackHandler extends TrackHandler {
+export class SignalTrackHandler extends TimelineTrackHandler {
     models: Models.SignalMarkerModel[] = [];
     didTrigger: boolean[] = [];
     receivers: Array<SignalReceiver | null> = [];
@@ -954,8 +955,15 @@ export class SignalTrackHandler extends TrackHandler {
     }
 }
 
-
-export class ActivationTrackHandler extends TrackHandler {
+/**
+ * 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;
@@ -987,7 +995,7 @@ export class ActivationTrackHandler extends TrackHandler {
 }
 
 
-export class ControlTrackHandler extends TrackHandler {
+export class TimelineControlTrack extends TimelineTrackHandler {
     models: Array<Models.ClipModel> = [];
     timelines: Array<PlayableDirector | null> = [];
 

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