Skip to content

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.

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,
});
PropertyTypeDefaultDescription
loopnumber0Number of loops (-1 = infinite)
alternatebooleanfalseAlternate direction each loop
autoplaybooleantrueStart playback immediately
playbackRatenumber1Speed multiplier (2 = 2x speed)
timeSourceAnimationTimeSourceAnimationTimeSource.SimulationClock 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.

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 label
PositionMeaning
numberAbsolute 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
undefinedSequential — 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.

MethodDescription
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.

PropertyTypeDescription
currentTimenumberCurrent playback time in ms
totalDurationnumberTotal timeline duration in ms
isPlayingbooleanWhether the timeline is playing

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

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.

Scale the entire timeline proportionally:

tl.stretch(5000); // Expand or shrink to 5 seconds total

All 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.

Await the timeline’s end, by completion or cancel:

await tl.then();
// or
await tl.then(() => console.log('done'));

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.