Motion
A scene’s clock, the anchors that place a change on it, the wrapping cues and the cues on a value, and how each step plays.
On this page
#The timeline
Each scene keeps one clock for its canvas, divided into steps by the step markers in its narrative: step 0 until the first marker, step k from the kth. Every change the canvas makes on its own — a mark arriving, a value moving, a ring drawn round something — is a cue anchored to that clock.
scene{
A ball leaves the ground at 20 m/s, 45° above the horizontal.
===
Its path is a parabola.
===
It lands about 41 m away.
}[
graph{
cue.draw{
curve#path(expression: x - x^2 / 40.8; domain: [0, 40.8])
}(
in: 1
)
cue.trace{
point(x: 0; y: 0; colour: orange)
}(
path: #path
at: 2 + 500ms
)
}(
x-domain: [0, 45]
y-domain: [0, 12]
)
]The path draws itself in as the reader passes the first marker; half a second after the second, the ball rides it.
- A scene's clock starts when the scene comes on stage from above. A step entered forwards plays what is anchored to it from the beginning.
- Passing several markers at once lands on the last of them, with everything anchored to the steps passed already finished.
- A step entered backwards, and a scene the reader scrolls back up into, land finished: nothing plays.
#Anchors
An anchor — a cue's in:, out: or at: — is written one of three ways:
2— the moment step 2 begins.2 + 500ms— half a second after step 2 begins.1.5s— 1.5 seconds on the scene's clock, from when the scene came on stage, whichever step the reader is on.
A step anchor runs from 0 to the number of markers. Inside an environment, one past the last marker is an error; in canvas content outside an environment it is a warning, with the same message. The message counts the markers, so a scene with one marker “has 1 step” and its steps are 0 and 1:
scene{
The stone is dropped.
===
It lands.
}[
graph{
curve(expression: 4.9x^2; domain: [0, 3])
cue{
point(x: 3; y: 44.1)
}(
in: 2
)
}
][semantic]'cue.in' anchors to step 2, but the scene has 1 step (valid: 0–1)
A cue that brings content in, written with no in:, has its content there from the start; in: 0 brings it in as the scene arrives. With no out:, it stays until the end of the scene.
#Wrapping cues
A wrapping cue is a node whose body is the content it acts on. Three decide whether that content is there:
cue— fades it in atin:and out atout:.cue.draw— draws it in: strokes are drawn along their length and fills arrive as the strokes finish. In prose and equations, every glyph's outline is drawn, each a little after the one to its left. What has no stroke fades.cue.write— writes it in, in reading order, atspeed:characters a second or overin-duration:: prose line by line, an equation mark by mark, a code environment'slinescharacter by character.
Three leave presence alone, and act on content that is already there — so they nest inside one of the three above to act on what it brought in:
cue.highlight— two rings push out of the content's edge, in its colour, and fade as they grow. On a code environment's lines it is a wash over them instead.cue.spotlight— dims everything else in the environment, grid and axes included, then lets it back up. On a code environment's lines it is the same wash as a highlight.cue.trace— carries the content along a curve, an expression or a field's first solution on a graph.


graph{
cue{
fit(of: #points; model: polynomial; degree: 1)
}(
in: 1
in-duration: 800ms
)
scatter#points(x: 1, 2, 3; y: 2.0, 2.4, 3.1)
}Where each is accepted:
- In a scene's detail, beside the environments:
cue,cue.drawandcue.write. Inline,!cue.highlightmarks words in a paragraph, heading or list there. graph: all butcue.write.code: all six.flowchart,logic,network: all butcue.writeandcue.trace.region:cueandcue.draw.
A cue cannot wrap an environment or a table: neither is in any cue's body, so neither can arrive or leave inside a scene.
sequential, on cue, cue.draw, cue.highlight or cue.spotlight or cue.trace, gives each element of its body a turn, top to bottom, each starting when the one before has finished — and leaving the same way at out:.
graph{
cue{
point(x: 1; y: 1)
point(x: 2; y: 3)
point(x: 3; y: 4)
}(
in: 1
sequential
)
}#Cues on a value
A cue on a value is written inside an attribute's value, after it. What is written first is the value the attribute starts at; each cue names a value to move to and when.
#!cue.to
![Three frames of the curve 100 − 4.9x² as its x-domain widens from [0, 5] to [0, 10].](/_next/image?url=%2Fmanual-figures%2Fmotion-cue-to.light.jpg&w=3840&q=90&dpl=dpl_CBrU4MbWhbfSBSWrUGDvQXzUkqv9)
![Three frames of the curve 100 − 4.9x² as its x-domain widens from [0, 5] to [0, 10].](/_next/image?url=%2Fmanual-figures%2Fmotion-cue-to.dark.jpg&w=3840&q=90&dpl=dpl_CBrU4MbWhbfSBSWrUGDvQXzUkqv9)
graph{
curve(expression: 100 - 4.9x^2)
}(
x-domain: [0, 5] !cue.to{[0, 10]}(at: 2)
)!cue.to{…} holds the target, and its at: the anchor. Several may follow one value:
x-domain: [0, 5] !cue.to{[0, 10]}(at: 1) !cue.to{[0, 20]}(at: 2 + 1.5s; duration: 800ms)Two keyframes of 'point.x' share the anchor 'step 1', and the one written later wins.An attribute that takes one carries an Animatable badge in its reference page's attribute table. On any other attribute the cue is refused, with an error that depends on the attribute's type:
graph{
curve(expression: x^2)
}(
title: Speed !cue.to{Distance}(at: 1)
)[attribute]node `graph`: attribute `title`: unknown micronode `cue.to`
hidden is animatable on every graph mark, so hidden: true !cue.to{false}(at: 1) brings a mark in at step 1 that has been part of the environment from the start; the graph fades it over the move's duration:.
The style attributes of a mark drawn from data — the colour:, size:, width:, shape: and opacity: of a scatter, a heatmap or a vertex table — take no cue: colour: red !cue.to{blue}(at: 1) on a scatter is attribute `colour`: unexpected `!`. A single mark's, such as a point's colour:, does.
#!cue.zoom
!cue.zoom moves a graph's window and says where it is going first. A box is drawn round the smaller of the two windows over draw:, held for hold:, and only then does the view move, over duration:. Zooming in, the box grows until it is the plot; zooming out, the plot shrinks into it. The box stays fixed in data coordinates while the view moves round it, and is drawn in colour:.
x-domain: [0, 10] !cue.zoom{[2, 4]}(at: 1; colour: blue) !cue.to{[0, 10]}(at: 2)It is accepted only on an environment's own window:
graph{
point(x: 1 !cue.zoom{2}(at: 1); y: 1)
}[semantic]!cue.zoom moves an environment's own window; 'point.x' is not one — use !cue.to
#Timing and playback
#Durations and easing
A duration is written with its unit, ms or s: 800ms, 1.5s. A bare number is refused: Invalid duration format. Expected "1s" or "500ms".
A cue is a state or a moment. A state brings something in and can take it out again, so it is anchored with in: and out: and its transitions take in-duration and out-duration: cue, cue.draw, cue.write and !cue.highlight. A moment plays once, so it is anchored with at: and lasts its duration: cue.highlight, cue.spotlight, cue.trace, cue.slider, cue.selector, !cue.to and !cue.zoom. The defaults:
cue:in-durationandout-duration, 500ms each.cue.draw:in-durationandout-duration, 2s each.cue.write:in-duration, or as long as its content takes atspeed:, 35 characters a second where neither is written; as long again to leave. A cue with both is refused.cue.highlight:duration, 1.5s, is one ring. The second sets off 30% of the way through the first, so the whole gesture is 1.3 times the duration.cue.spotlight:duration, 3s, the whole time the environment is dimmed — the first and last fifth of it spent dimming and letting go.cue.trace:duration, 1.5s.!cue.to:duration, 1.5s.!cue.zoom:draw700ms,hold250ms, thenduration1.2s.
easing is smooth, the default, or linear, on cue, cue.draw, cue.highlight, cue.trace, !cue.to and !cue.zoom. cue.write and cue.slider take it too, with linear as their default: an even pen, and a sweep whose every second covers the same stretch of the range.
#Playback
A step's playback runs from the step's start until the last thing anchored to it has finished. The canvas toolbar shows a play control for a step whose playback runs 4 seconds or more, holds two or more animations over at least 2 seconds, or sweeps a cue.slider or cue.selector. It pauses and resumes the scene's clock, and Replay returns the step to how it looked before it began and plays it again. Three of the scene's attributes change how a step plays:
!autoplay— every step that animates at all arrives paused at its start, with the control, until the reader presses play. A step that animates nothing goes ahead.loop— when a step's playback ends, it plays again.duration— how long one playback of a step lasts, where the step animates. It is never shorter than the step's cues, so what a longer one adds is a hold on the finished picture before Replay is offered or the loop goes round. It is the scene's implicit attribute:scene:6s{…}.
scene:6s{
The stone is dropped.
===
It falls 44.1 m in three seconds.
}[
graph{
cue.draw{
curve(expression: 4.9x^2; domain: [0, 3])
}(
in: 1
in-duration: 3s
)
}
](
!autoplay
loop
)#Writing guidance
- Framing a readable graph — When to write a domain, the defaults left alone, naming a series, the ticks the prose reads, and one meaning per hue.
- Steps, timers, sweeps & parameters — New content on the step that introduces it, timers for timed motion, sweeps for a change the prose describes, and parameters where one sentence holds across the range.