The Timeline

Initiative is the map's

Initiative belongs to the map now, not to whoever happens to be connected: round 3 on one map stays round 3 when another map advances, a reload shows the order as it was, and someone who joins mid-fight sees it at once. Roll Initiative in the chat starts it as before; End Turn ends yours (the GM ends anyone's, and Next turn walks the order) — on a computer it sits just below Mini-Me while it is your turn; every advance is a map commit, so History can put a round back.

The strip

Time runs left to right: the past to the left, the future to the right, as far either way as you care to go.

• Ticks. A round is 30 ticks, one per initiative count, counting down: the round begins at 30, and the tall ticks partway along are initiative 20 and 10, labelled. Each round begins with a heavier, full-height tick labelled Round N. An initiative above 30 sits at the start of its round.
• Now is an accent line at the current turn, whose token is framed in gold. The strip keeps it in the middle; when a turn ends, the strip slides along so the new turn lands where the last one was.
• Tokens sit along the top of the strip at their initiative, in every round you can see, with the current turn framed. Click one to select it and jump the map to it; double-click (or shift-click) to impersonate it. The GM drags one along the current round and drops it at another count to reorder.
• Effects are coloured bars below the tokens, from where they begin to where they end — on past the right edge when they run until ended — each taking the next row down when it overlaps another. Hover one for its card: what it is, what it is on, what is left. Click it to open it: the one who started it, and the GM, get the full editor (with End now and Remove); anyone else sees its details and source link.
• The + — the strip's full height, at its right end (left of the chat when that is open) — starts a timed effect or adds a token to initiative (the token rolls 1d20 plus its Dexterity modifier and joins the order; the list stays open so several can go in).
• The chevron at the strip's left end, its full height, collapses it to a thin line along the bottom; clicking the line, or the Timeline tab at the right of the play bar, brings it back. Until you choose, the strip shows itself while initiative runs or an effect is on the map and stays out of the way otherwise. The left rail and both sidebars run down over it.

Moving around

Zooming spreads the ticks apart or draws them together; tokens and effect bars keep their size. Scrolling down, when there are more effects than fit, brings the lower bars up and moves the tokens out of view. None of this reaches the map behind the strip, and the strip has no right-click menu — the right button is how a mouse scrolls it.

Once you scroll away, the strip stays where you left it. When the current turn is out of view, Now appears just above the strip, midway between its two end buttons: click it to bring the current turn back to the middle and follow it again.

Timed effects

An effect has a name, a colour (a distinct one is picked for you), the token it is on, what it does to that token's numbers (see Buffs), a start (now, or a round and an initiative — or Click the timeline… and click the strip where it should start), a description and a source link, and a duration:

• Rounds — it ends at the same place in initiative that many rounds later. 0 ends when this round comes back to the same count; 10 is ten rounds.
• Until ended — it runs until someone ends it. Ending combat does not end it; a counted effect with a round left keeps that round for the next fight.
• Until… — a function decides, every tick.

Anyone who may play on the map can start an effect (a spell is the caster's); the one who started it, or the GM, changes or ends it. Actions can do all of this too — see api.timeline.

From a power

A System 8 power action with a duration places its effects itself: one on each token the action was aimed at (or on you, when its range is personal and it was aimed at nobody), named after the action, coloured alike, with the power's page as the source. The duration follows the document's:

• N rounds counts rounds.
• concentration, encounter, sustained and permanent run until ended.
• A save that ends it — Str ends, Con ends — is the Timeline's to ask: on that token's own turn, its player is asked for the save (1d20 + the ability), and the effect ends when the total meets the power roll, which in System 8 is the save DC. Miss, or decline, and it runs on to the next turn.

Ritual and instantaneous durations place nothing. Other systems' actions place effects when their own code does, through api.timeline.

Writing a duration function

The function runs at every tick, in the platform's small sandboxed script language (not full JavaScript — no loops over the network, no await), as

(round, whoseTurn) => …

and the effect ends the first time it returns true. round is the current round; whoseTurn is the token acting at this tick — id, name, initiative — or nothing when initiative is not running.

// Ends at the start of round 5.
(round, whoseTurn) => round >= 5

whoseTurn.requestRoll(expression) asks whoever plays that token to roll: the prompt reaches the token's owner, the GM, and the character's editors, like any roll request. The platform pauses the function until the roll is answered and then runs it again with the result in hand — { total }, or null if they declined — so write the call plainly:

// A save at the end of the affected token's turn: 15 or better ends it.
(round, whoseTurn) => {
  if (!whoseTurn || whoseTurn.id !== 'TOKEN_ID') return false;
  const roll = whoseTurn.requestRoll('1d20+3', { label: 'Wisdom save' });
  return roll !== null && roll.total >= 15;
}

While the ask stands the slice shows a dashed edge and the card says awaiting a roll; the same tick asks once, and an ask nobody answers within five minutes is dropped and asked again next tick. A function that throws leaves the effect running, dims its slice, and sends whoever started it a message with the sentence — once, until the function is changed.