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

package/src/engine-components/AnimatorController.builder.ts

@@ -1,17 +1,34 @@
-import { AnimationClip } from "three";
+import { AnimationClip, Object3D } from "three";
+import type { Light, Material, PerspectiveCamera } from "three";
 
 import { AnimatorConditionMode, AnimatorControllerParameterType } from "../engine/extensions/NEEDLE_animator_controller_model.js";
 import type { AnimatorControllerModel, Condition, Parameter, State, Transition } from "../engine/extensions/NEEDLE_animator_controller_model.js";
 import { InstantiateIdProvider } from "../engine/engine_networking_instantiate.js";
 import { AnimatorController } from "./AnimatorController.js";
+import { resolveClipSource, 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>;
+
+/** Extracts parameter names of a given type from the builder's tracked parameter map */
+type ParamNamesOfType<TParams, PType extends string> = {
+    [K in keyof TParams & string]: TParams[K] extends PType ? K : never
+}[keyof TParams & string];
 
 
 /**
  * Configuration for an animation state in the builder
  */
 export declare type StateOptions = {
-    /** The animation clip for this state */
-    clip: AnimationClip;
+    /**
+     * The animation clip for this state. Accepts:
+     * - A pre-built `AnimationClip`
+     * - A single {@link TrackDescriptor} from {@link track}
+     * - An array of {@link TrackDescriptor}s (multiple tracks combined into one clip)
+     *
+     * When omitted, use {@link AnimatorControllerBuilder.track .track()} to define animation tracks inline.
+     */
+    clip?: AnimationClip | TrackDescriptor | TrackDescriptor[];
     /** Whether the animation should loop (default: false) */
     loop?: boolean;
     /** Base speed multiplier (default: 1) */
@@ -30,10 +47,8 @@ export declare type StateOptions = {
 export declare type TransitionOptions = {
     /** Duration of the crossfade in seconds (default: 0) */
     duration?: number;
-    /** Normalized exit time 0-1 (default: 1). Only used when hasExitTime is true */
+    /** Normalized exit time 0-1. When set, the transition waits until the source animation reaches this point before transitioning. */
     exitTime?: number;
-    /** Whether the transition waits for exitTime before transitioning (default: false) */
-    hasExitTime?: boolean;
     /** Normalized offset into the destination state's animation (default: 0) */
     offset?: number;
     /** Whether duration is in seconds (true) or normalized (false) (default: false) */
@@ -63,17 +78,22 @@ type BuilderTransition = {
 type BuilderState = {
     name: string;
     options: StateOptions;
+    inlineTracks: TrackDescriptor[];
     transitions: BuilderTransition[];
 };
 
 /**
  * A fluent builder for creating {@link AnimatorController} instances from code.
  *
- * Use {@link AnimatorController.build} to create a new builder.
+ * Use {@link AnimatorControllerBuilder.create} or {@link AnimatorController.build} to create a new builder.
  *
- * @example
+ * The builder tracks state names and parameter types through the fluent chain,
+ * providing autocomplete for state names in `.transition()` and type-aware
+ * `.condition()` calls (e.g., trigger parameters don't require a mode argument).
+ *
+ * @example With pre-built AnimationClips
  * ```ts
- * const controller = AnimatorController.build("CharacterController")
+ * const controller = AnimatorControllerBuilder.create("CharacterController")
  *     .floatParameter("Speed", 0)
  *     .triggerParameter("Jump")
  *     .state("Idle", { clip: idleClip, loop: true })
@@ -84,58 +104,100 @@ type BuilderState = {
  *     .transition("Walk", "Idle", { duration: 0.25 })
  *         .condition("Speed", "less", 0.1)
  *     .transition("*", "Jump", { duration: 0.1 })
- *         .condition("Jump", "if")
+ *         .condition("Jump")
  *     .transition("Jump", "Idle", { hasExitTime: true, exitTime: 0.9, duration: 0.25 })
  *     .build();
  * ```
  *
+ * @example With inline tracks (no pre-built clips needed)
+ * ```ts
+ * const controller = AnimatorControllerBuilder.create("Door")
+ *     .boolParameter("Open", false)
+ *     .state("Closed", { loop: true })
+ *         .track(door, "position", { from: [0, 0, 0], to: [0, 0, 0], duration: 1 })
+ *     .state("Open", { loop: true })
+ *         .track(door, "position", { from: [0, 0, 0], to: [2, 0, 0], duration: 1 })
+ *         .track(light, "intensity", { from: 0, to: 5, duration: 1 })
+ *     .transition("Closed", "Open", { duration: 0.25 })
+ *         .condition("Open", "if")
+ *     .transition("Open", "Closed", { duration: 0.25 })
+ *         .condition("Open", "ifNot")
+ *     .build(room);
+ * ```
+ *
+ * @typeParam TStates - Union of state names added via `.state()`. Used for autocomplete and validation in `.transition()` and `.defaultState()`.
+ * @typeParam TParams - Record mapping parameter names to their types (`"trigger"`, `"bool"`, `"float"`, `"int"`). Used for type-aware `.condition()` overloads.
+ *
  * @category Animation and Sequencing
  * @group Utilities
  */
-export class AnimatorControllerBuilder {
+export class AnimatorControllerBuilder<
+    TStates extends string = never,
+    TParams extends Record<string, "trigger" | "bool" | "float" | "int"> = {},
+> {
     private _name: string;
     private _parameters: Parameter[] = [];
     private _states: BuilderState[] = [];
     private _anyStateTransitions: BuilderTransition[] = [];
     private _defaultStateName: string | null = null;
     private _lastTransition: BuilderTransition | null = null;
+    private _lastState: BuilderState | null = null;
+
+    /**
+     * Creates a new AnimatorControllerBuilder instance.
+     * @param name - Optional name for the controller
+     */
+    static create(name?: string): AnimatorControllerBuilder {
+        return new AnimatorControllerBuilder(name);
+    }
 
     constructor(name?: string) {
         this._name = name ?? "AnimatorController";
     }
 
     /** Adds a float parameter */
-    floatParameter(name: string, defaultValue: number = 0): this {
+    floatParameter<N extends string>(name: N, defaultValue: number = 0): AnimatorControllerBuilder<TStates, TParams & Record<N, "float">> {
         this._parameters.push({ name, hash: this._parameters.length, type: AnimatorControllerParameterType.Float, value: defaultValue });
-        return this;
+        return this as any;
     }
 
     /** Adds an integer parameter */
-    intParameter(name: string, defaultValue: number = 0): this {
+    intParameter<N extends string>(name: N, defaultValue: number = 0): AnimatorControllerBuilder<TStates, TParams & Record<N, "int">> {
         this._parameters.push({ name, hash: this._parameters.length, type: AnimatorControllerParameterType.Int, value: defaultValue });
-        return this;
+        return this as any;
     }
 
     /** Adds a boolean parameter */
-    boolParameter(name: string, defaultValue: boolean = false): this {
+    boolParameter<N extends string>(name: N, defaultValue: boolean = false): AnimatorControllerBuilder<TStates, TParams & Record<N, "bool">> {
         this._parameters.push({ name, hash: this._parameters.length, type: AnimatorControllerParameterType.Bool, value: defaultValue });
-        return this;
+        return this as any;
     }
 
     /** Adds a trigger parameter */
-    triggerParameter(name: string): this {
+    triggerParameter<N extends string>(name: N): AnimatorControllerBuilder<TStates, TParams & Record<N, "trigger">> {
         this._parameters.push({ name, hash: this._parameters.length, type: AnimatorControllerParameterType.Trigger, value: false });
-        return this;
+        return this as any;
     }
 
     /**
      * Adds a state to the controller. The first state added becomes the default state.
+     *
+     * When `options.clip` is provided, the state uses that clip directly.
+     * When omitted, chain `.track()` calls to define animation tracks inline:
+     * ```ts
+     * .state("Open", { loop: true })
+     *     .track(door, "position", { from: [0,0,0], to: [2,0,0], duration: 1 })
+     *     .track(light, "intensity", { from: 0, to: 5, duration: 1 })
+     * ```
+     *
      * @param name - Unique name for the state
-     * @param options - State configuration including clip, loop, speed
+     * @param options - State configuration including clip, loop, speed. When omitted, use `.track()` to add animation data.
      */
-    state(name: string, options: StateOptions): this {
-        this._states.push({ name, options, transitions: [] });
-        return this;
+    state<N extends string>(name: N, options?: StateOptions): AnimatorControllerBuilder<TStates | N, TParams> {
+        const state: BuilderState = { name, options: options ?? {}, inlineTracks: [], transitions: [] };
+        this._states.push(state);
+        this._lastState = state;
+        return this as any;
     }
 
     /**
@@ -146,8 +208,9 @@ export class AnimatorControllerBuilder {
      * @param to - Destination state name
      * @param options - Transition configuration
      */
-    transition(from: string, to: string, options?: TransitionOptions): this {
-        const t: BuilderTransition = { to, options: options ?? {}, conditions: [] };
+    transition(from: TStates | "*", to: TStates, options?: TransitionOptions): AnimatorControllerBuilder<TStates, TParams> {
+        this._lastState = null;
+        const t: BuilderTransition = { to: to as string, options: options ?? {}, conditions: [] };
         if (from === "*") {
             this._anyStateTransitions.push(t);
         }
@@ -157,19 +220,68 @@ export class AnimatorControllerBuilder {
             state.transitions.push(t);
         }
         this._lastTransition = t;
-        return this;
+        return this as any;
     }
 
     /**
      * Adds a condition to the most recently added transition.
      * Multiple conditions on the same transition are AND-ed together.
+     *
+     * The required arguments depend on the parameter type:
+     * - **Trigger**: `.condition("Jump")` — mode defaults to `"if"`, no threshold needed
+     * - **Bool**: `.condition("Open", "if")` or `.condition("Open", "ifNot")`
+     * - **Float/Int**: `.condition("Speed", "greater", 0.1)`
+     *
      * @param parameter - Name of the parameter to evaluate
-     * @param mode - Condition mode: `"if"`, `"ifNot"`, `"greater"`, `"less"`, `"equals"`, `"notEqual"`
-     * @param threshold - Comparison threshold for numeric conditions (default: 0)
      */
-    condition(parameter: string, mode: ConditionMode, threshold: number = 0): this {
+    // Trigger parameters: mode is optional (defaults to "if")
+    condition(parameter: ParamNamesOfType<TParams, "trigger">, mode?: "if" | "ifNot"): AnimatorControllerBuilder<TStates, TParams>;
+    // Bool parameters: mode is required
+    condition(parameter: ParamNamesOfType<TParams, "bool">, mode: "if" | "ifNot"): AnimatorControllerBuilder<TStates, TParams>;
+    // Float/Int parameters: mode and optional threshold
+    condition(parameter: ParamNamesOfType<TParams, "float" | "int">, mode: "greater" | "less" | "equals" | "notEqual", threshold?: number): AnimatorControllerBuilder<TStates, TParams>;
+    condition(parameter: string, mode?: ConditionMode, threshold?: number): AnimatorControllerBuilder<TStates, TParams> {
         if (!this._lastTransition) throw new Error("AnimatorControllerBuilder: .condition() must be called after .transition()");
-        this._lastTransition.conditions.push({ parameter, mode, threshold });
+        this._lastTransition.conditions.push({ parameter, mode: mode ?? "if", threshold: threshold ?? 0 });
+        return this as any;
+    }
+
+    // --- Object3D ---
+    /** Adds an animation track for an Object3D's position or scale to the current state */
+    track(target: Object3D, property: "position" | "scale", keyframes: KF<Vec3Value>, options?: TrackOptions): this;
+    /** Adds an animation track for an Object3D's quaternion to the current state */
+    track(target: Object3D, property: "quaternion", keyframes: KF<QuatValue>, options?: TrackOptions): this;
+    /** Adds an animation track for an Object3D's rotation (Euler, converted to quaternion) to the current state */
+    track(target: Object3D, property: "rotation", keyframes: KF<EulerValue>, options?: TrackOptions): this;
+    /** Adds an animation track for an Object3D's visibility to the current state */
+    track(target: Object3D, property: "visible", keyframes: KF<boolean>, options?: TrackOptions): this;
+    // --- Material ---
+    /** Adds an animation track for a material's numeric property to the current state */
+    track(target: Material, property: "opacity" | "roughness" | "metalness" | "alphaTest" | "emissiveIntensity" | "envMapIntensity" | "bumpScale" | "displacementScale" | "displacementBias", keyframes: KF<number>, options?: TrackOptions): this;
+    /** Adds an animation track for a material's color property to the current state */
+    track(target: Material, property: "color" | "emissive", keyframes: KF<ColorValue>, options?: TrackOptions): this;
+    // --- Light ---
+    /** Adds an animation track for a light's numeric property to the current state */
+    track(target: Light, property: "intensity" | "distance" | "angle" | "penumbra" | "decay", keyframes: KF<number>, options?: TrackOptions): this;
+    /** Adds an animation track for a light's color to the current state */
+    track(target: Light, property: "color", keyframes: KF<ColorValue>, options?: TrackOptions): this;
+    // --- Camera ---
+    /** Adds an animation track for a camera's numeric property to the current state */
+    track(target: PerspectiveCamera, property: "fov" | "near" | "far" | "zoom", keyframes: KF<number>, options?: TrackOptions): this;
+    /**
+     * Adds an animation track to the most recently added state.
+     * Must be called after `.state()`. The track has the same type-safe overloads
+     * as the standalone {@link track} function.
+     *
+     * @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._lastState) throw new Error("AnimatorControllerBuilder: .track() must be called after .state()");
+        if (this._lastState.options.clip) throw new Error(`AnimatorControllerBuilder: state "${this._lastState.name}" already has a clip. Use either .track() or { clip: ... }, not both.`);
+        this._lastState.inlineTracks.push(trackFn(target as Object3D, property as "position", keyframes, options));
         return this;
     }
 
@@ -178,16 +290,18 @@ export class AnimatorControllerBuilder {
      * If not called, the first added state is used.
      * @param name - Name of the state
      */
-    defaultState(name: string): this {
-        this._defaultStateName = name;
-        return this;
+    defaultState(name: TStates): AnimatorControllerBuilder<TStates, TParams> {
+        this._defaultStateName = name as string;
+        return this as any;
     }
 
     /**
      * Builds and returns the {@link AnimatorController}.
      * Resolves all state name references to indices.
+     * @param root - Optional root Object3D for resolving {@link TrackDescriptor} track paths.
+     *   When provided, tracks targeting a different object use `target.name` for named resolution.
      */
-    build(): AnimatorController {
+    build(root?: Object3D): AnimatorController {
         const stateIndexMap = new Map<string, number>();
         this._states.forEach((s, i) => stateIndexMap.set(s.name, i));
 
@@ -203,7 +317,7 @@ export class AnimatorControllerBuilder {
             if (destIndex === undefined) throw new Error(`AnimatorControllerBuilder: transition target "${t.to}" not found`);
             return {
                 exitTime: t.options.exitTime ?? 1,
-                hasExitTime: t.options.hasExitTime ?? false,
+                hasExitTime: t.options.exitTime !== undefined,
                 duration: t.options.duration ?? 0,
                 offset: t.options.offset ?? 0,
                 hasFixedDuration: t.options.hasFixedDuration ?? false,
@@ -226,12 +340,24 @@ export class AnimatorControllerBuilder {
                 transitions.push(resolveTransition(anyT));
             }
 
+            // Resolve clip: from options.clip, inline .track() calls, or error
+            let clip: AnimationClip;
+            if (s.options.clip) {
+                clip = resolveClipSource(s.options.clip, root);
+            }
+            else if (s.inlineTracks.length > 0) {
+                clip = resolveClipSource(s.inlineTracks, root);
+            }
+            else {
+                throw new Error(`AnimatorControllerBuilder: state "${s.name}" has no clip and no inline tracks. Provide { clip } or chain .track() calls.`);
+            }
+
             return {
                 name: s.name,
                 hash: index,
                 motion: {
-                    name: s.options.clip.name,
-                    clip: s.options.clip,
+                    name: clip.name,
+                    clip: clip,
                     isLooping: s.options.loop ?? false,
                 },
                 transitions,

package/src/engine-components/AnimatorController.ts

@@ -397,6 +397,7 @@ export class AnimatorController {
      * Stops all animations and unregisters the mixer from the animation system.
      */
     dispose() {
+        if (!this._mixer) return;
         this._mixer.stopAllAction();
         if (this.animator) {
             this._mixer.uncacheRoot(this.animator.gameObject);

package/src/engine-components/ContactShadows.ts

@@ -100,7 +100,7 @@ export class ContactShadows extends Behaviour {
             const obj = new Object3D();
             obj.name = "ContactShadows";
             instance = addComponent(obj, ContactShadows, {
-                autoFit: false,
+                autoFit: true,
                 occludeBelowGround: false
             });
             this._instances.set(context, instance);
@@ -169,6 +169,10 @@ export class ContactShadows extends Behaviour {
         return this._needsUpdate;
     }
     private _needsUpdate: boolean = false;
+    private _needsFit: boolean = false;
+
+    // TODO: support auto-refit for moveable/animated objects (e.g. via mesh-bvh / scene BVH).
+    // Currently there's no reliable way to detect object position/scale changes.
 
     /** All shadow objects are parented to this object. 
      * The gameObject itself should not be transformed because we want the ContactShadows object e.g. also have a GroundProjectedEnv component
@@ -366,6 +370,11 @@ export class ContactShadows extends Behaviour {
 
     onEnable(): void {
         this._needsUpdate = true;
+        this.autoCleanup(this.context.events.on("scene-content-changed", () => {
+            if (!this.autoFit) return;
+            this._needsFit = true;
+            this._needsUpdate = true;
+        }));
     }
 
     /** @internal */
@@ -393,6 +402,11 @@ export class ContactShadows extends Behaviour {
     /** @internal */
     onBeforeRender(_frame: XRFrame | null): void {
 
+        if (this._needsFit && this.autoFit) {
+            this._needsFit = false;
+            this.fitShadows();
+        }
+
         if (this.manualUpdate) {
             if (!this._needsUpdate) return;
         }

package/src/engine-components/DropListener.ts

@@ -597,6 +597,9 @@ export class DropListener extends Behaviour {
         });
         this.dispatchEvent(evt);
         this.onDropped?.invoke(evt.detail);
+        if (obj) {
+            this.context.events.emit("scene-content-changed", { source: this, object: obj });
+        }
 
         // send network event
         if (!isRemote && ctx.url?.startsWith("http") && this.context.connection.isConnected && obj) {

package/src/engine-components/OrbitControls.ts

@@ -663,7 +663,15 @@ export class OrbitControls extends Behaviour implements ICameraController {
         }
         this._controls.enabled = true;
 
-        if (this.context.input.getPointerDown(1) || this.context.input.getPointerDown(2) || this.context.input.mouseWheelChanged || (this.context.input.getPointerPressed(0) && this.context.input.getPointerPositionDelta(0)?.length() || 0 > .1)) {
+        // Interrupt programmatic transitions on meaningful new user interaction:
+        // - Middle/right button down (always intentional camera control)
+        // - Mouse wheel (zoom intent)
+        // - Left button drag start: getPointerDown(0) with a position delta — a bare click
+        //   without movement shouldn't cancel an animation, but starting to drag should.
+        //   Using getPointerDown (not getPointerPressed) ensures we only interrupt once at
+        //   drag onset, not continuously every frame during a drag.
+        const leftDragStart = this.context.input.getPointerDown(0) && (this.context.input.getPointerPositionDelta(0)?.length() || 0) > .1;
+        if (this.context.input.getPointerDown(1) || this.context.input.getPointerDown(2) || this.context.input.mouseWheelChanged || leftDragStart) {
             this._inputs += 1;
         }
         if (this._inputs > 0 && this.allowInterrupt) {
@@ -1095,13 +1103,16 @@ export class OrbitControls extends Behaviour implements ICameraController {
     // Adapted from https://discourse.threejs.org/t/camera-zoom-to-fit-object/936/24
     // Slower but better implementation that takes bones and exact vertex positions into account: https://github.com/google/model-viewer/blob/04e900c5027de8c5306fe1fe9627707f42811b05/packages/model-viewer/src/three-components/ModelScene.ts#L321
 
-    /** 
-     * Fits the camera to show the objects provided (defaults to the scene if no objects are passed in) 
+    /**
+     * Fits the camera to show the objects provided (defaults to the scene if no objects are passed in)
      * @param options The options for fitting the camera. Use to provide objects to fit to, fit direction and size and other settings.
     */
     fitCamera(options?: OrbitFitCameraOptions);
-    /** @deprecated Use fitCamera(options) */
-    fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<OrbitFitCameraOptions, "objects">);
+    // Deprecated overload commented out: it accepted Object3D as first arg, which caused
+    // TypeScript autocomplete to show Object3D properties (position, worldPosition, etc.)
+    // instead of OrbitFitCameraOptions. The implementation still handles Object3D at runtime
+    // for backwards-compat — use fitCamera({ objects: [...] }) instead.
+    // fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<OrbitFitCameraOptions, "objects">);
     fitCamera(objectsOrOptions?: Object3D | Array<Object3D> | OrbitFitCameraOptions, options?: OrbitFitCameraOptions): void {
 
 

package/src/engine-components/SceneSwitcher.ts

@@ -747,6 +747,9 @@ export class SceneSwitcher extends Behaviour {
                 const openedEvt = new CustomEvent<LoadSceneEvent>("scene-opened", { detail: { scene: scene, switcher: this, index: index } });
                 this.dispatchEvent(openedEvt);
                 this.sceneLoaded?.invoke(this);
+                if (this._currentSceneAsset) {
+                    this.context.events.emit("scene-content-changed", { source: this, object: this._currentSceneAsset });
+                }
                 return true;
             }
         }

package/src/engine-components/api.ts

@@ -34,6 +34,7 @@
  * @module Built-in Components
  */
 
+export { AnimationBuilder, type AnimationKeyframe, type Tween, type AnimationInterpolation } from "./AnimationBuilder.js";
 export { AnimatorControllerBuilder, type ConditionMode, type StateOptions, type TransitionOptions } from "./AnimatorController.builder.js";
 export * from "./codegen/components.js";
 export { Collider } from "./Collider.js"; // export abstract type

package/src/engine-components/codegen/components.ts

@@ -3,10 +3,10 @@
 export class __Ignore {}
 export { AlignmentConstraint } from "../AlignmentConstraint.js";
 export { Animation } from "../Animation.js";
+export { AnimationBuilder } from "../AnimationBuilder.js";
 export { Keyframe } from "../AnimationCurve.js";
 export { AnimationCurve } from "../AnimationCurve.js";
 export { Animator } from "../Animator.js";
-export { AnimatorControllerBuilder } from "../AnimatorController.builder.js";
 export { AnimatorController } from "../AnimatorController.js";
 export { AudioListener } from "../AudioListener.js";
 export { AudioSource } from "../AudioSource.js";
@@ -161,12 +161,12 @@ export { SignalAsset } from "../timeline/SignalAsset.js";
 export { SignalReceiverEvent } from "../timeline/SignalAsset.js";
 export { SignalReceiver } from "../timeline/SignalAsset.js";
 export { TimelineBuilder } from "../timeline/TimelineBuilder.js";
-export { AnimationTrackHandler } from "../timeline/TimelineTracks.js";
-export { AudioTrackHandler } from "../timeline/TimelineTracks.js";
-export { MarkerTrackHandler } from "../timeline/TimelineTracks.js";
+export { TimelineAnimationTrack } from "../timeline/TimelineTracks.js";
+export { TimelineAudioTrack } from "../timeline/TimelineTracks.js";
+export { TimelineMarkerTrack } from "../timeline/TimelineTracks.js";
 export { SignalTrackHandler } from "../timeline/TimelineTracks.js";
-export { ActivationTrackHandler } from "../timeline/TimelineTracks.js";
-export { ControlTrackHandler } from "../timeline/TimelineTracks.js";
+export { TimelineActivationTrack } from "../timeline/TimelineTracks.js";
+export { TimelineControlTrack } from "../timeline/TimelineTracks.js";
 export { TransformGizmo } from "../TransformGizmo.js";
 export { BaseUIComponent } from "../ui/BaseUIComponent.js";
 export { UIRootComponent } from "../ui/BaseUIComponent.js";

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

@@ -44,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.  
@@ -385,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;
     }
 
@@ -399,21 +399,21 @@ 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.ActivationTrackHandler[] {
+    get activationTracks(): Tracks.TimelineActivationTrack[] {
         return this._activationTracks;
     }
 
     /**
      * @returns all tracks of the timeline
      */
-    get tracks(): ReadonlyArray<Tracks.TrackHandler> {
+    get tracks(): ReadonlyArray<Tracks.TimelineTrackHandler> {
         return this._allTracks.flat();
     }
 
@@ -452,16 +452,16 @@ export class PlayableDirector extends Behaviour {
     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 _activationTracks: Array<Tracks.ActivationTrackHandler> = [];
-    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);
@@ -535,7 +535,7 @@ export class PlayableDirector extends Behaviour {
                 // 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);
@@ -652,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;
@@ -675,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;
@@ -725,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;
@@ -749,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;
 
@@ -795,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) {
@@ -807,7 +807,7 @@ export class PlayableDirector extends Behaviour {
                 this._controlTracks.push(handler);
             }
             else if (track.type === Models.TrackType.Activation) {
-                const handler = new Tracks.ActivationTrackHandler();
+                const handler = new Tracks.TimelineActivationTrack();
                 handler.director = this;
                 handler.track = track;
                 this._activationTracks.push(handler);