Timeline

An animation timeline system that manages keyframe-based animations.

Timeline provides:

• Frame-based positioning and playback
• Multiple animation tracks for different properties
• Label system for marking important positions
• Looping and one-shot playback modes
• Auto-update integration with the game loop
• Complete callbacks for animation sequences

Timelines are commonly used in:

• Fragment animations
• Complex UI transitions
• Cutscenes and scripted sequences
• Any multi-property animations that need synchronization

Example usage:

var timeline = new Timeline();
timeline.fps = 30;
timeline.size = 120; // 4 seconds at 30 fps

// Add animation tracks
var track = new TimelineFloatTrack();
track.add(new TimelineFloatKeyframe(0, 100));
track.add(new TimelineFloatKeyframe(60, 200));
timeline.add(track);

// Add labels for important positions
timeline.setLabel(0, "start");
timeline.setLabel(60, "middle");
timeline.setLabel(120, "end");

// Play animation from a label
timeline.animate("start", () -> trace("Animation complete!"));

Instance Members #

The total length of the timeline in frames.

• Default is 0 (timeline won't play)
• When autoFitSize is true (default), automatically adjusts to match the longest track
• Set to -1 for an infinite timeline that never finishes

The actual duration in seconds = size / fps

Whether the timeline should automatically adjust its size to match the longest track. When true (default), you don't need to manually set the timeline size.

Whether the timeline should loop back to the beginning when it reaches the end. Ignored if size is -1 (infinite timeline). Default is true.

Whether the timeline automatically updates each frame. When true (default), the timeline advances based on frame delta time. Set to false to manually control timeline playback with seek() or update().

Timeline playback speed in frames per second. This defines how many timeline frames pass per second of real time.

Note: Timeline values are interpolated between frames, so using 30 fps still provides smooth animation even on 60+ fps displays.

Default is 30 fps.

Current playback position in frames.

• Starts at 0
• Can be fractional for smooth interpolation between frames
• Wraps back to 0 when looping is enabled and size is reached
• Use seek() to jump to specific positions

Array of animation tracks managed by this timeline. Each track animates a specific property of an entity. Tracks are updated automatically as the timeline plays.

Whether the timeline playback is paused. Setting to true stops all animation while preserving the current position.

Array of label names in the timeline. Labels mark important positions for seeking and animation control. Sorted by position (frame index).

Optional starting position for timeline playback.

• If >= 0, timeline starts from this frame index
• When looping, timeline resets to this position instead of 0
• Default is -1 (use position 0)

Optional ending position for timeline playback.

• If >= 0, timeline stops at this frame index
• When looping, timeline resets to startPosition (or 0)
• Default is -1 (use timeline size)

Update the timeline position based on elapsed time. Called automatically each frame when autoUpdate is true.

Jump to a specific position in the timeline. Handles looping and clamping based on timeline settings. Updates all tracks to reflect the new position.

Play an animation sequence from a labeled position. The animation plays until reaching the next label or timeline end.

If the animation is interrupted (by seeking or playing another animation), the complete callback won't be called.

Jump to the position of a named label.

Reset the timeline's start and end positions to their defaults. After calling this, the timeline will play from 0 to its full size.

Set up the timeline to loop within a labeled section.

The timeline will:

• Jump to the label position
• Set startPosition to the label's frame
• Set endPosition to the next label (or timeline end)
• Loop within this range

Apply all timeline tracks at the current position. Useful for ensuring all animated properties are up to date.

Add an animation track to this timeline. If the track was previously added to another timeline, it's removed first. If autoFitSize is true, the timeline size adjusts to accommodate the track.

Get a track by its ID.

Remove an animation track from this timeline. If autoFitSize is true, the timeline size adjusts after removal.

Adjust the timeline size to match the longest track. Called automatically when autoFitSize is true and tracks are added/removed.

Find the last label before a given position.

Get the label name at a specific frame index.

Get the frame index of a named label.

Create or update a label at a specific position. If a label with the same name exists, it's moved to the new position. Labels are automatically sorted by position.

Remove any label at the specified frame index.

Remove a label by name.

Create a new timeline instance. The timeline starts paused at position 0 with no tracks.

Private Members #

Used in pair with labels to manage timeline labels

Internal array of complete handlers

Internal array of complete handler label indexes

Event triggered when the timeline position reaches a label. Useful for triggering actions at specific points in the animation.

Event triggered when the timeline leaves a labeled section. This happens when reaching the next label or the end of the timeline. Useful for cleaning up effects or transitioning to new states.

Internal function to bind or update to app update event depending on current settings

Metadata #