TimelineTrack

View source
Entity → ceramic.TimelineTrack (Class) → TimelineBoolTrack, TimelineColorTrack, TimelineDegreesTrack, TimelineFloatArrayTrack, TimelineFloatTrack

Base class for animation tracks in a timeline system.

A TimelineTrack manages a sequence of keyframes that define how a value changes over time. The track handles:

  • Keyframe storage and ordering
  • Position tracking and seeking
  • Interpolation between keyframes
  • Automatic size adjustment

This is an abstract base class. Concrete implementations include:

  • TimelineFloatTrack: Animates numeric values
  • TimelineColorTrack: Animates color values
  • TimelineBoolTrack: Animates boolean values
  • TimelineFloatArrayTrack: Animates arrays of numbers

Tracks are typically added to a Timeline which coordinates their playback.

See: Timeline, TimelineKeyframe

Instance Members

size: Int

The total length of this track in frames.

  • Default is 0 (track won't animate)
  • When autoFitSize is true (default), automatically adjusts to the last keyframe's index
  • Set to -1 for an infinite track that never finishes

The actual duration = size / timeline.fps

autoFitSize: Bool

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

loop: Bool

Whether this track should loop back to the beginning when it reaches the end. Ignored if size is -1 (infinite track). Default is false (tracks don't loop independently, controlled by timeline).

locked: Bool

Whether this track is locked from timeline updates. When true, the track won't be updated when its timeline advances. Useful for temporarily disabling specific animations.

timeline: Timeline

The timeline that owns this track. Set automatically when the track is added to a timeline. Null if the track is not attached to any timeline.

position: Float

Current playback position in frames.

  • Can be fractional for smooth interpolation
  • Wraps back to 0 when looping is enabled and size is reached
  • Updated automatically by the timeline or manually with seek()
keyframes: ReadOnlyArray<ceramic.TimelineTrack.K>

Array of keyframes defining the animation. Keyframes are automatically kept sorted by their index (time position). Use add() and remove() to modify the keyframe list.

before: ceramic.TimelineTrack.K

The keyframe at or immediately before the current position. Used as the start point for interpolation. Null if position is before the first keyframe.

after: ceramic.TimelineTrack.K

The keyframe immediately after the current position. Used as the end point for interpolation. Null if position is after the last keyframe.

destroy(): Void
seek(targetPosition: Float): Void

Jump to a specific position in the track. Handles looping and clamping based on track settings. Updates the before/after keyframes and applies the change.

Name Type Description
targetPosition Float The frame index to seek to
add(keyframe: ceramic.TimelineTrack.K): Void

Add a keyframe to this track.

  • Keyframes are automatically sorted by index
  • If a keyframe already exists at the same index, it's replaced
  • Updates track size if autoFitSize is true
  • Immediately applies the change
Name Type Description
keyframe ceramic.TimelineTrack.K The keyframe to add
remove(keyframe: ceramic.TimelineTrack.K): Void

Remove a keyframe from this track.

  • Updates track size if autoFitSize is true
  • Immediately applies the change
Name Type Description
keyframe ceramic.TimelineTrack.K The keyframe to remove
fitSize(): Void

Adjust the track size to match the last keyframe's index. Called automatically when autoFitSize is true and keyframes are added/removed.

apply(?forceChange: Bool = false): Void

Apply the current animation state to the target property. This method should be overridden in subclasses to implement the actual property updates and interpolation.

Called automatically when the track position changes.

Name Type Default Description
forceChange Bool false If true, forces the update even if the value hasn't changed
findKeyframeAtIndex(index: Int): Null<ceramic.TimelineTrack.K>

Find a keyframe at exactly the specified index.

Name Type Description
index Int The frame index to search for
Returns Description
Null<ceramic.TimelineTrack.K> The keyframe at that index, or null if none exists
findKeyframeBefore(position: Float): Null<ceramic.TimelineTrack.K>

Find the keyframe at or before a given position. Used to determine the start point for interpolation.

Name Type Description
position Float The position to search from
Returns Description
Null<ceramic.TimelineTrack.K> The keyframe at or before the position, or null if none exists
findKeyframeAfter(position: Float): Null<ceramic.TimelineTrack.K>

Find the first keyframe after a given position. Used to determine the end point for interpolation.

Name Type Description
position Float The position to search from
Returns Description
Null<ceramic.TimelineTrack.K> The keyframe after the position, or null if none exists
new(): Void

Create a new timeline track. The track starts empty with no keyframes.

Private Members

keyframeBeforeIndex: Int

The index of the last resolved key index before. Used internally.

keyframeAfterIndex: Int

The index of the last resolved key index after. Used internally.

inlineSeek(targetPosition: Float, ?forceSeek: Bool = false, ?forceChange: Bool = false): Void
Name Type Default
targetPosition Float
forceSeek Bool false
forceChange Bool false
computeKeyframeBefore(): Void

Internal. Compute before keyframe, if any matching.

computeKeyframeAfter(): Void

Internal. Compute after keyframe, if any matching.

Metadata

Name Parameters
:build ceramic.macros.EntityMacro.buildForCompletion()
:autoBuild ceramic.macros.EntityMacro.buildForCompletion()
:build tracker.macros.EventsMacro.build()
:autoBuild tracker.macros.EventsMacro.build()