Class TimelineBuilder

A fluent builder for creating timeline assets (TimelineAssetModel) from code.

Use TimelineBuilder.create to start building a timeline.

Example: Using build() for timelines without signal callbacks

const timeline = TimelineBuilder.create("MySequence")
    .animationTrack("Character", animator)
        .clip(walkClip, { duration: 2, easeIn: 0.3 })
        .clip(runClip, { duration: 3, easeIn: 0.5, easeOut: 0.5 })
    .activationTrack("FX", particleObject)
        .clip({ start: 1, duration: 2 })
    .audioTrack("Music", audioSource)
        .clip("music.mp3", { start: 0, duration: 5, volume: 0.8 })
    .build();

director.playableAsset = timeline;
director.play();

Example: With inline tracks (no pre-built clips needed)

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

TimelineBuilder.create("WithSignals")
    .animationTrack("Character", animator)
        .clip(walkClip, { duration: 2 })
    .signalTrack("Events")
        .signal(1.0, () => console.log("1 second!"))
        .signal(2.0, () => spawnParticles())
    .install(director);

director.play();

Methods

activationTrack animationTrack audioTrack build clip controlTrack install marker markerTrack muted signal signalTrack track create

Methods

activationTrack

  • activationTrack(
        name: string,
        binding?: null | Object3D<Object3DEventMap>,
    ): ActivationTrackBuilder

    Adds an activation track. Subsequent .clip() calls define when the bound object is active.

    Parameters

    • name: string

      Display name for the track

    • Optionalbinding: null | Object3D<Object3DEventMap>

      The Object3D to show/hide

    Returns ActivationTrackBuilder

animationTrack

  • animationTrack(
        name: string,
        binding?: null | Object3D<Object3DEventMap> | Animator,
    ): AnimationTrackBuilder

    Adds an animation track. Chain .clip() calls to add pre-built clips, or chain .track() calls to define animation data inline:

    Parameters

    • name: string

      Display name for the track

    • Optionalbinding: null | Object3D<Object3DEventMap> | Animator

      The Animator or Object3D to animate

    Returns AnimationTrackBuilder

    Example: With pre-built AnimationClip

    .animationTrack("Character", animator)
        .clip(walkClip, { duration: 2, easeIn: 0.3 })
        .clip(runClip, { duration: 3 })

    Example: With inline tracks

    .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 })

audioTrack

  • audioTrack(
        name: string,
        binding?: null | Object3D<Object3DEventMap> | AudioSource,
        volume?: number,
    ): AudioTrackBuilder

    Adds an audio track. Subsequent .clip() calls add audio clips to this track.

    Parameters

    • name: string

      Display name for the track

    • Optionalbinding: null | Object3D<Object3DEventMap> | AudioSource

      The AudioSource to play audio on (optional)

    • Optionalvolume: number

      Track volume multiplier (default: 1)

    Returns AudioTrackBuilder

build

  • build(): TimelineAssetModel

    Builds and returns the TimelineAssetModel. Assign the result to PlayableDirector.playableAsset to play it.

    If you used .signal() with callbacks, use install instead — it calls build() internally and also wires up the SignalReceiver on the director's GameObject.

    Returns TimelineAssetModel

clip

controlTrack

  • controlTrack(name: string): ControlTrackBuilder

    Adds a control track. Subsequent .clip() calls control nested timelines or objects.

    Parameters

    • name: string

      Display name for the track

    Returns ControlTrackBuilder

install

  • install(director: PlayableDirector): TimelineAssetModel

    Builds the timeline asset, assigns it to the director, and wires up any .signal() callbacks by creating/configuring a SignalReceiver on the director's GameObject.

    Parameters

    Returns TimelineAssetModel

    The built TimelineAssetModel (also assigned to director.playableAsset)

    Example

    TimelineBuilder.create("MyTimeline")
        .animationTrack("Anim", animator)
            .clip(walkClip, { duration: 2 })
        .signalTrack("Events")
            .signal(1.0, () => console.log("signal fired!"))
        .install(director);

    director.play();

marker

  • marker(time: number, asset: string, options?: SignalMarkerOptions): this

    Adds a signal marker to the current signal or marker track.

    Parameters

    • time: number

      Time in seconds when the signal fires

    • asset: string

      The signal asset identifier (guid string)

    • Optionaloptions: SignalMarkerOptions

      Optional marker configuration

    Returns this

markerTrack

muted

  • muted(muted?: boolean): this

    Mutes the current track so it is skipped during playback.

    Parameters

    • muted: boolean = true

    Returns this

signal

  • signal(time: number, callback: Function, options?: SignalMarkerOptions): this

    Adds a signal with a callback to the current signal track. This is a convenience method that automatically generates a signal asset guid, adds the marker, and registers the callback so that install can wire up the SignalReceiver on the director's GameObject.

    Parameters

    • time: number

      Time in seconds when the signal fires

    • callback: Function

      The function to invoke when the signal fires

    • Optionaloptions: SignalMarkerOptions

      Optional marker configuration

    Returns this

    Example

    const timeline = TimelineBuilder.create("Sequence")
        .signalTrack("Events")
            .signal(1.0, () => console.log("1 second reached!"))
            .signal(3.5, () => console.log("halfway!"), { emitOnce: true })
        .install(director);

signalTrack

  • signalTrack(
        name: string,
        binding?: null | Object3D<Object3DEventMap> | SignalReceiver,
    ): SignalTrackBuilder

    Adds a signal track. Use .signal() or .marker() to add signal markers.

    Parameters

    • name: string

      Display name for the track

    • Optionalbinding: null | Object3D<Object3DEventMap> | SignalReceiver

      The SignalReceiver component (optional — if using .signal() with callbacks, one is created automatically by install)

    Returns SignalTrackBuilder

track

  • track(
        target: Object3D,
        property: "position" | "scale",
        keyframes: KF<Vec3Value>,
        options?: TrackOptions,
    ): this

    Adds an animation track descriptor for an Object3D's position or scale to the current animation track

    Parameters

    • target: Object3D
    • property: "position" | "scale"
    • keyframes: KF<Vec3Value>
    • Optionaloptions: TrackOptions

    Returns this

  • track(
        target: Object3D,
        property: "quaternion",
        keyframes: KF<QuatValue>,
        options?: TrackOptions,
    ): this

    Adds an animation track descriptor for an Object3D's quaternion to the current animation track

    Parameters

    • target: Object3D
    • property: "quaternion"
    • keyframes: KF<QuatValue>
    • Optionaloptions: TrackOptions

    Returns this

  • track(
        target: Object3D,
        property: "rotation",
        keyframes: KF<EulerValue>,
        options?: TrackOptions,
    ): this

    Adds an animation track descriptor for an Object3D's rotation (Euler, converted to quaternion) to the current animation track

    Parameters

    • target: Object3D
    • property: "rotation"
    • keyframes: KF<EulerValue>
    • Optionaloptions: TrackOptions

    Returns this

  • track(
        target: Object3D,
        property: "visible",
        keyframes: KF<boolean>,
        options?: TrackOptions,
    ): this

    Adds an animation track descriptor for an Object3D's visibility to the current animation track

    Parameters

    • target: Object3D
    • property: "visible"
    • keyframes: KF<boolean>
    • Optionaloptions: TrackOptions

    Returns this

  • 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 numeric property to the current animation track

    Parameters

    • target: Material
    • property:
          | "opacity"
          | "roughness"
          | "metalness"
          | "alphaTest"
          | "emissiveIntensity"
          | "envMapIntensity"
          | "bumpScale"
          | "displacementScale"
          | "displacementBias"
    • keyframes: KF<number>
    • Optionaloptions: TrackOptions

    Returns this

  • track(
        target: Material,
        property: "color" | "emissive",
        keyframes: KF<ColorValue>,
        options?: TrackOptions,
    ): this

    Adds an animation track descriptor for a material's color property to the current animation track

    Parameters

    • target: Material
    • property: "color" | "emissive"
    • keyframes: KF<ColorValue>
    • Optionaloptions: TrackOptions

    Returns this

  • track(
        target: Light,
        property: "intensity" | "distance" | "angle" | "penumbra" | "decay",
        keyframes: KF<number>,
        options?: TrackOptions,
    ): this

    Adds an animation track descriptor for a light's numeric property to the current animation track

    Parameters

    • target: Light
    • property: "intensity" | "distance" | "angle" | "penumbra" | "decay"
    • keyframes: KF<number>
    • Optionaloptions: TrackOptions

    Returns this

  • track(
        target: Light,
        property: "color",
        keyframes: KF<ColorValue>,
        options?: TrackOptions,
    ): this

    Adds an animation track descriptor for a light's color to the current animation track

    Parameters

    • target: Light
    • property: "color"
    • keyframes: KF<ColorValue>
    • Optionaloptions: TrackOptions

    Returns this

  • track(
        target: PerspectiveCamera,
        property: "zoom" | "fov" | "near" | "far",
        keyframes: KF<number>,
        options?: TrackOptions,
    ): this

    Adds an animation track descriptor for a camera's numeric property to the current animation track

    Parameters

    • target: PerspectiveCamera
    • property: "zoom" | "fov" | "near" | "far"
    • keyframes: KF<number>
    • Optionaloptions: TrackOptions

    Returns this

Staticcreate

  • create(name?: string, seed?: number): TimelineBuilderBase

    Creates a new TimelineBuilder instance.

    Parameters

    • Optionalname: string

      Name for the timeline asset

    • Optionalseed: number

      Optional numeric seed for deterministic guid generation. Defaults to Date.now().

    Returns TimelineBuilderBase

Settings

Member Visibility

On This Page

Methods