Timelines

View source
Entity → ceramic.Timelines (Class)

Central system for creating and binding timeline tracks and keyframes.

The Timelines class serves as a factory and binding system for the timeline animation framework. It handles:

  • Creating appropriate track types based on field types
  • Creating keyframes with proper typing
  • Binding tracks to entity properties for automatic updates
  • Extensibility through events for custom track/keyframe types

This system is primarily used by the Fragment system when loading timeline data from .fragment files, but can also be extended to support custom animation types.

Built-in support includes:

  • Float tracks (numeric properties)
  • Color tracks (Color properties)
  • Boolean tracks (Bool properties)
  • Float array tracks (Array properties)
  • Degrees tracks (rotation with shortest-path interpolation)

To add custom track types:

  1. Listen to the createTrack event
  2. Check the type parameter
  3. Create and assign your custom track to result.value

Example extension:

app.timelines.onCreateTrack(this, (type, options, result) -> {
    if (type == "MyCustomType") {
        result.value = new MyCustomTrack();
    }
});
See: Timeline, TimelineTrack, Fragment

Instance Members

emitCreateTrack(type: String, options: Dynamic, result: Value<TimelineTrack<TimelineKeyframe>>): Void

Event for creating timeline tracks from field type information.

Listen to this event to add support for custom track types. The system will check all listeners until one sets result.value.

Name Type Description
type String The field type as a string (e.g., "Float", "Bool", "MyCustomType")
options Dynamic Optional configuration from track data (e.g., {degrees: true})
result Value<TimelineTrack<TimelineKeyframe>> Assign the created track to result.value
emitBindTrack(type: String, options: Dynamic, track: TimelineTrack<TimelineKeyframe>, entity: Entity, field: String): Void

Event for binding timeline tracks to entity properties.

Listen to this event to customize how track values are applied to entity properties. Default implementation uses reflection via entity.setProperty().

Name Type Description
type String The field type as a string
options Dynamic Optional configuration (e.g., {copyArray: true})
track TimelineTrack<TimelineKeyframe> The track to bind
entity Entity The entity whose property will be animated
field String The property name to animate
emitCreateKeyframe(type: String, options: Dynamic, value: Dynamic, index: Int, easing: Anonymous, existing: Null<TimelineKeyframe>, result: Value<TimelineKeyframe>): Void

Event for creating timeline keyframes from data.

Listen to this event to add support for custom keyframe types. The system will check all listeners until one sets result.value.

Tip: Reuse the existing keyframe when possible to reduce allocations.

Name Type Description
type String The field type as a string
options Dynamic Optional configuration
value Dynamic The keyframe value (type depends on field type)
index Int The frame index (time position)
easing Anonymous The easing function for interpolation
existing Null<TimelineKeyframe> Existing keyframe at this index (can be reused)
result Value<TimelineKeyframe> Assign the created/updated keyframe to result.value
new(): Void

Create a new Timelines system instance. Automatically registers default handlers for built-in track types.

Private Members

handleCreateTrack(type: String, options: Dynamic, result: Value<TimelineTrack<TimelineKeyframe>>): Void
Name Type
type String
options Dynamic
result Value<TimelineTrack<TimelineKeyframe>>
handleBindTrack(type: String, options: Dynamic, track: TimelineTrack<TimelineKeyframe>, entity: Entity, field: String): Void
Name Type
type String
options Dynamic
track TimelineTrack<TimelineKeyframe>
entity Entity
field String
handleCreateKeyframe(type: String, options: Dynamic, value: Dynamic, index: Int, easing: Anonymous, existing: Null<TimelineKeyframe>, result: Value<TimelineKeyframe>): Void
Name Type
type String
options Dynamic
value Dynamic
index Int
easing Anonymous
existing Null<TimelineKeyframe>
result Value<TimelineKeyframe>

Metadata

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