`station()` and `leg()` — a route through the score

Map mode's two cues. A station is a place the camera stays; a leg is the move from one station to the next. Together they make a route that runs on its own clock — in a map-mode project ("defaultViewMode": "map") it is the piece's time, and the transport drives it. For the idea and how to work with it, see Map Mode — Stations & Legs.

demo-map — nine stations on a 3×3 grid, one route through them

station(name:reef, stay:75, at:[0.667, 0.5], edge:reef-buoy, align:center)
  draw(start:penA, trig:manual)
  text(uid:reef-story, cycle:reef.txt, dur:4, trig:manual, tdelay:8)

leg(dur:8, lead:2) ui(uid:lighthouse-beam, visible:true, dur:4, trig:manual)

Neither is ever fired by the playhead, and neither are the other cues on their elements: the route runs them.

Changing a route

Times — the route table. Open the route table and click ✎ edit: every station's stay: and until:, and every leg's dur:, become fields. Type a value, press Enter, and it is written to the score. The quickest way to retime a piece; see Changing the times.
Other parameters — the DSL editor. Tick show on map in the route table so the station rectangles and leg arrows can be clicked, turn on the ✏ pencil and click one: the parameters it already has (at:, scale:, run:, lead:…) appear as fields. It offers no list of new ones to add — type those into the cue.
Drawing the route — Inkscape. Stations are rectangles and legs are connector arrows, so moving, resizing or reconnecting them is done there (see Drawing a route).

`station()`

Put it on a rectangle drawn around what the camera should see there. The camera fits the rectangle on arrival.

Parameter	Meaning
`name`	The station's name, used by legs and the route table. Default: the element's `id`.
`stay`	Beats the camera stays, or quoted minutes and seconds of beats: `stay:85`, `stay:"1:25"`. With `until:`, the longest it waits. A last station without one holds the view until the route is stopped.
`until`	A gate: the stay ends when it opens. `until:click` waits for a performer (a continue ▸ button appears); `until:"click:<id>"` for a click on that element of the score. Anything else is a condition on a signal, quoted: `until:"buoy.end"`, `until:"adc.onset>0.5"`.
`start`	`start:1` — the route begins here. Default: the first station no leg arrives at.
`pause`	Scroll scores: `pause:1` — the score's playback holds for the stay (released when the station is left). Map mode has no playback to hold.
`run`	`run:<id>` or `run:[<id>, <id>]` — on arrival, run the cue that element carries, as `next:<id>` would. For cues that must stay on their own element (`o2p()`, `text(target:self)`).
`state`	`state:[<uid>, …]` — what this station expects to be visible. Applied when the route jumps here (see below).
`scale`	A zoom level, instead of fitting the rectangle.
`to`	Follow this element instead of the rectangle's centre.
`at`	`[x, y]` — where on screen the target lands, as fractions of the view. Default `[0.5, 0.5]`.
`edge`	`<id>` — the playhead line arrives just before this element (or through its centre with `align:center`).
`align`	With `edge`: `center`.
`playhead`	`<id>` — the playhead line ends on this element. On pinned material the pin slides to bring it there. `stay` — the view moves without the playhead.
`hold`	Beats, or `next`: the camera stays locked on its target after arriving, as it is carried about.
`sweep`	`sweep:0` — a pinned target stays pinned on arrival.
`margin`	With `edge`: the gap before the element, in score units.

at, edge, align, playhead, hold, sweep and margin are passed to the zoom() that makes the move.

The stay's cues

Every other cue on the station's element runs when the route arrives:

at once, or after tdelay: beats into the stay;
or when a quoted trig: condition comes true during the stay — trig:"story.line==5" (a text reaching line 5), trig:"buoy.end", any signal condition. A tdelay: then counts from that moment.

Leaving the station ends what the stay set going: its texts, its cues still waiting, its pause:1 hold.

Triggered by another cue

A station can be entered from outside the route: next:<station id> from a chain, a button, or any cue that runs the element. The route starts there and carries on. Only station() runs; the stay's cues are run by the route on arrival, not twice.

`leg()`

Put it on an arrow drawn with Inkscape's connector tool from one station rectangle to the next; the connector's ends say which stations it joins.

Parameter	Meaning
`dur`	Beats the camera move takes. Default 2; `dur:0` is a cut.
`ease`	As for `zoom()`: `easeInOutSine` (default), `linear`, `easeInOutCubic`, `easeOutCubic`.
`lead`	Beats before the camera leaves that the leg's own cues start. After a gate, they start as it opens and the camera leaves `lead` beats later.
`from`, `to`	Station names or ids, instead of a connector's ends.

Other cues on the leg's element start at lead before departure (plus any tdelay: of their own) — typically revealing what the camera is about to arrive at:

leg(dur:10, lead:2) ui(uid:reef-outline, visible:true, dur:4, trig:manual)

Jumps

Starting the route at a station — ▶ on a row of the route table, or a station triggered by a cue — is a jump. It puts back everything the route's stations and legs change:

what they reveal or expect is shown only if the target's state: lists it, or it was visible when the score loaded;
the pens their draw() controls start are lifted and the ink wiped;
the elements they run: go back to their start.

Then the camera cuts to the station and its stay begins.

Signals for waiting on

Signal	Published by	Value
`<uid>.line`	`text()`	the line showing: 1, 2, 3 …; 0 before the first and after the last
`<uid>.end`	`text()`, `o2p()` (finite `loop:`), `audio()`, `stopwatch()` (with `hold:`)	0 as it starts, 1 when it reaches its end (not when stopped)

Examples

A fixed stay, a text, a reveal on the way out

station(name:reef, stay:75, run:reef-story, edge:reef-buoy, align:center)
leg(dur:8, lead:2) ui(uid:lighthouse-beam, visible:true, dur:4, trig:manual)

Wait for a moving object to arrive, at most four minutes

station(name:drift, until:"buoy.end", stay:240, run:buoy, to:buoy, hold:next)

A performer decides when to move on

station(name:harbour, until:click)                   // continue ▸, bottom left
station(name:harbour, until:"click:harbour-bell")    // a click on the bell drawn there

A camera move inside a stay, on a line of its text

station(name:lighthouse, stay:128, run:keeper-story)
  zoom(to:lamp, scale:40, dur:4, trig:"keeper-story.line==5", tdelay:1)

Demo project

demo-map shows every kind of gate on a 3×3 grid; see Map Mode.

The end of the route

station(name:coda, at:[0.5, 0.5], hold:next)

No stay: and no leg out: the view holds until the route is stopped.

Tip: use ← → or ↑ ↓ to navigate the docs

station() and leg() — a route through the score