Timelines
Timelines sequence segments, callbacks, and labels over time. The playhead drives every segment: each frame, a segment’s fields are written where its share of the playhead’s time says. So seeking, reversing, alternating, the playback rate, pausing and completing all move the values with the playhead. A field given as a target starts from its value when the playhead first reaches the segment, and every round of a loop plays from there.
Creating a timeline
Section titled “Creating a timeline”import { AnimationTimeSource } from '@shell/animate';
const animate = resources.get('animate');
const tl = animate.timeline({ loop: -1, // -1 = infinite, 0 = no loop alternate: true, // ping-pong direction each loop autoplay: true, // start immediately (default) playbackRate: 1, // speed multiplier timeSource: AnimationTimeSource.Simulation,});TimelineOptions
Section titled “TimelineOptions”| Property | Type | Default | Description |
|---|---|---|---|
loop | number | 0 | Number of loops (-1 = infinite) |
alternate | boolean | false | Alternate direction each loop |
autoplay | boolean | true | Start playback immediately |
playbackRate | number | 1 | Speed multiplier (2 = 2x speed) |
timeSource | AnimationTimeSource | AnimationTimeSource.Simulation | Clock used by the playhead |
A timeline owns one time source for its playhead, callbacks, and loops. A segment has no clock, loop or delay of its own: its position is its place in time, and its onBegin and onComplete are called when the playhead passes its start and end. Wall-time timelines use the ticker’s unscaled frame delta and stop advancing when the ticker is paused or stopped.
Adding segments
Section titled “Adding segments”tl.add(entity, Position, { x: 100, duration: 500 }, 0) // absolute time 0 .add(entity, Position, { y: 200, duration: 500 }, '+=200') // 200ms after previous end .set(entity, Opacity, { value: 0 }, '<') // same start as previous .call(() => console.log('halfway'), 350) // callback at 350ms .label('midpoint', 350) // named position .add(entity, Position, { x: 0, duration: 500 }, 'midpoint'); // at labelPosition types
Section titled “Position types”| Position | Meaning |
|---|---|
number | Absolute time in milliseconds |
'+=N' | N ms after the end of the timeline so far |
'-=N' | N ms before the end of the timeline so far |
'<' | Same start time as the previous segment |
'<+=N' | N ms after the previous segment starts |
'<-=N' | N ms before the previous segment starts |
'labelName' | At a label set with label() before |
undefined | Sequential — at the end of the timeline |
A label that is not set yet, or an N that is not a number, is an error when the segment is added.
Methods
Section titled “Methods”| Method | Description |
|---|---|
add(entity, component, properties, position?) | Add a tween segment |
set(entity, component, properties, position?) | Add a zero-duration tween (immediate property set) |
call(callback, position?) | Schedule a callback at a position |
label(name, position?) | Define a named position for later reference |
play() | Start or resume playback, from where the playhead is |
pause() | Pause playback; the values stay where they are |
reverse() | Flip playback direction |
restart() | Reset to the beginning and start playing |
seek(time) | Put every segment at a time of the current round |
stretch(newDuration) | Scale all segments to a new total duration |
cancel() | Stop where it is; then() settles |
complete() | Put every segment at its end and settle then() |
then(callback?) | A Promise<void> that settles on completion or cancel |
play() on a finished timeline goes on from where its playhead is: forwards, that is the end, and it finishes again in the next frame; after reverse() it plays back to the start. restart() plays it again from the start. Either way, then() waits for the new run.
Properties
Section titled “Properties”| Property | Type | Description |
|---|---|---|
currentTime | number | Current playback time in ms |
totalDuration | number | Total timeline duration in ms |
isPlaying | boolean | Whether the timeline is playing |
Looping and alternate
Section titled “Looping and alternate”When loop is set and the timeline reaches the end, it loops, and every round plays the same. With alternate: true, every second round plays backwards (ping-pong).
Callbacks and labels
Section titled “Callbacks and labels”A callback is called each time the playhead passes its position, both ways, in the order it passes them:
tl.call(() => console.log('started'), 0);tl.label('end', 2000);tl.call(() => console.log('finished'), 'end');Labels can be created at any position, and referenced by name in the add(), set(), or call() calls after them.
Stretching
Section titled “Stretching”Scale the entire timeline proportionally:
tl.stretch(5000); // Expand or shrink to 5 seconds totalAll segment offsets, durations (a segment’s default 300 ms too), callback and label positions are multiplied by the ratio. The options given to add() are left as they were.
Promises
Section titled “Promises”Await the timeline’s end, by completion or cancel:
await tl.then();// orawait tl.then(() => console.log('done'));Integration with systems
Section titled “Integration with systems”Timelines are advanced automatically by the TimelineSystem registered at PostUpdate. You do not need to call __update manually.
A timeline holds while an entity it drives is in a paused Scene. One that drives no entity (only callbacks) holds while the Scene that was active when it was made is paused.