Clocks and the stage

Where time comes from

A player has no clock of its own. It asks its clock for the time now, and to be called on every frame while it plays. Hand it one as createPlayer(program, drawer, { clock }). Without one, it plays on the page's frame clock.

frameClock() is that clock: one requestAnimationFrame loop, shared by every player playing on it. The first call makes it, and every later call returns the same one. It sleeps while nothing ticks on it.

Its now() is performance.now() in seconds, read when asked rather than at the last frame. So a player started between two frames starts at that very moment.

A clock you step yourself

manualClock(start?) makes a clock at start seconds that moves only when told. advance(seconds) moves it on and ticks every player on it once, at the new time. Use it in tests, or to render video one frame at a time.

Each button below makes one call. Pause the player and clock.ticking drops to 0. Advance then: the clock moves on, and the player stays where it is. The clock keeps counting, while player.time starts over every lap. Each frame drawn leaves a dot, so the eases show in the spacing.

import { compile, createPlayer, manualClock, svgDrawer } from "@stew/engine";
import clip from "./clip.json";

const program = compile(clip);
const drawer = svgDrawer(program, uid =>
  [...svg.querySelectorAll(`[data-stew-uid="${uid}"]`)]);

// a clock that moves only when told, from 0 seconds
const clock = manualClock();
const player = createPlayer(program, drawer, { clock, repeat: -1 });
player.play(); // ticking on the clock, still at 0

// the buttons
clock.advance(1 / 30);
clock.advance(0.25);
player.pause();
player.play();

// the readouts
console.log(clock.now(), player.time, clock.ticking);

One shape, several players

Hand the same stage to each player's svgDrawer, and the players that draw one element keep one transform on it. Their moves add up, their turns and skews add up, and their stretches multiply. An element is written only when its matrix changed.

Each turn, skew and stretch happens about the pivot of the last player turning, skewing or stretching it. Below, the hop lifts the friend and squashes it on its bottom edge, while the flip turns it about its middle. A move is never turned by the turn: it runs along the axes the element sits in.

Turn a player off and it is destroyed: it lets go, and the friend shows what the other still writes. With both off, the friend has no transform at all, just as it was drawn.

import { compile, createPlayer, createStage, svgDrawer, type StewDoc } from "@stew/engine";
import hop from "./hop.json";
import flip from "./flip.json";

// one stage: what its players move on one shape adds up
const stage = createStage();
const nodes = (uid: string) =>
  [...svg.querySelectorAll(`[data-stew-uid="${uid}"]`)];

function play(clip: StewDoc) {
  const program = compile(clip);
  const drawer = svgDrawer(program, nodes, stage);
  const player = createPlayer(program, drawer, { repeat: -1 });
  player.play();
  return player;
}

// both draw the element with data-stew-uid="friend"
const hopper = play(hop);
const flipper = play(flip);

Clips and ranks

By default, everything on a stage adds up. A drawer made with { exclusive: true } draws a clip: of the clips on one element, each part (move x, move y, turn, skew, stretch) comes from the clip that drew it last. Anything that isn't a clip still adds to it.

For a pivot, the last player is the one that joined the stage last, and one still at rest has no say. Of the clips, only the one that drew a part last counts for that part's pivot. ranked(stage, rank) changes the order: players drawn through it come after every player ranked lower, however late those joined, so their pivot wins.

cursorAction and dragAction write through a stage too. They aren't clips, so a pointer action and a clip that move one layer add up.

Letting go

The stage remembers how every attribute looked before its players first wrote it. When a player is destroyed, its drawer's restore() runs: what it wrote gives way to what the others still write, and once the last one lets go, the element looks exactly as it did before the first frame.

Only what the engine wrote goes back. A value someone else wrote since, like an edit made while it played, is theirs and stays.

A transform is written as the element's transform attribute. The artwork's own <svg> is moved through its inline style instead, since WebKit ignores the attribute there. Its pivot is a share of its box (0 to 1), written as its transform-origin, and one pivot serves its turn, skew and stretch: the turn's pivot while it turns, else the stretch's, else the skew's.