@needle-tools/engine/lib/engine-components/timeline/TimelineTracks.d.ts

Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.

import { AnimationAction, AnimationClip, AnimationMixer, Audio, AudioListener, Object3D } from "three";
import { Context } from "../../engine/engine_setup.js";
import { AudioSource } from "../AudioSource.js";
import type { PlayableDirector } from "./PlayableDirector.js";
import { SignalReceiver } from "./SignalAsset.js";
import * as Models from "./TimelineModels.js";
/**
 * 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 declare abstract class TimelineTrackHandler {
    director: PlayableDirector;
    track: Models.TrackModel;
    get muted(): boolean;
    set muted(val: boolean);
    forEachClip(backwards?: boolean): IterableIterator<Models.ClipModel>;
    onEnable?(): any;
    onDisable?(): any;
    onDestroy?(): any;
    abstract evaluate(time: number): any;
    onMuteChanged?(): any;
    onPauseChanged?(): any;
    /** invoked when PlayableDirectory playmode state changes (paused, playing, stopped) */
    onStateChanged?(isPlaying: boolean): any;
    getClipTime(time: number, model: Models.ClipModel): number;
    getClipTimeNormalized(time: number, model: Models.ClipModel): number;
    evaluateWeight(time: number, index: number, models: Array<Models.ClipModel>, isActive?: boolean): number;
}
export declare class TimelineAnimationTrack extends TimelineTrackHandler {
    /** @internal */
    models: Array<Models.ClipModel>;
    /** @internal */
    trackOffset?: Models.TrackOffset;
    /** The object that is being animated. */
    target?: Object3D;
    /** The AnimationMixer, should be shared with the animator if an animator is bound */
    mixer?: AnimationMixer;
    clips: Array<AnimationClip>;
    actions: Array<AnimationAction>;
    /**
     * You can use the weight to blend the timeline animation tracks with multiple animation tracks on the same object.
     * @default 1
     */
    weight: number;
    /** holds data/info about clips differences */
    private _actionOffsets;
    private _didBind;
    private _animator;
    onDisable(): void;
    onDestroy(): void;
    onStateChanged(): void;
    createHooks(clipModel: Models.AnimationClipModel, clip: any): void;
    bind(): void;
    private ensureTrackOffsets;
    private _useclipOffsets;
    private _totalOffsetPosition;
    private _totalOffsetRotation;
    private _totalOffsetPosition2;
    private _totalOffsetRotation2;
    private _summedPos;
    private _tempPos;
    private _summedRot;
    private _tempRot;
    private _clipRotQuat;
    evaluate(time: number): void;
    private createRotationInterpolant;
    private createPositionInterpolant;
}
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 declare class TimelineAudioTrack extends TimelineTrackHandler {
    models: Array<AudioClipModel>;
    listener: AudioListener;
    audio: Array<Audio>;
    audioContextTimeOffset: Array<number>;
    lastTime: number;
    audioSource?: AudioSource;
    /** Track-level volume multiplier (0–1). Applied on top of per-clip volume each frame. */
    get volume(): number;
    set volume(val: number);
    private _audioLoader;
    private getAudioFilePath;
    onAllowAudioChanged(allow: boolean): void;
    addModel(model: Models.ClipModel): void;
    onDisable(): void;
    onDestroy(): void;
    onMuteChanged(): void;
    stop(): void;
    private _playableDirectorResumed;
    onPauseChanged(): void;
    evaluate(time: number): void;
    /** Call to load audio buffer for a specific time in the track. Can be used to preload the timeline audio */
    loadAudio(time: number, lookAhead?: number, lookBehind?: number): Promise<(AudioBuffer | null)[]> | null;
    private isInTimeRange;
    private static _audioBuffers;
    static dispose(): void;
    private handleAudioLoading;
}
export declare class TimelineMarkerTrack extends TimelineTrackHandler {
    models: Array<Models.MarkerModel & Record<string, any>>;
    needsSorting: boolean;
    foreachMarker<T>(type?: string | null): Generator<T, void, unknown>;
    onEnable(): void;
    evaluate(_time: number): void;
    private sort;
}
export declare class SignalTrackHandler extends TimelineTrackHandler {
    models: Models.SignalMarkerModel[];
    didTrigger: boolean[];
    receivers: Array<SignalReceiver | null>;
    private _lastTime;
    onEnable(): void;
    onMuteChanged(): void;
    evaluate(time: number): void;
}
/**
 * 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 declare class TimelineActivationTrack extends TimelineTrackHandler {
    evaluate(time: number): void;
}
export declare class TimelineControlTrack extends TimelineTrackHandler {
    models: Array<Models.ClipModel>;
    timelines: Array<PlayableDirector | null>;
    resolveSourceObjects(_context: Context): void;
    private _previousActiveModel;
    evaluate(time: number): void;
}
export {};