Scene format
The authoritative reference for Starlight's YAML: the on-disk project layout, project.yaml, and the scene files that describe what every surface in a venue shows. It is written from the parser and serializer that actually read and write these files — src/engine/yaml/{parse,serialize,clock,effects}.ts — and the model schemas in src/engine/model/ and src/engine/clocks/. When this document and a scene disagree, the parser wins; report the drift.
Audience: an artist or engineer authoring scenes by hand, or an agent generating
them. Everything here round-trips: parse → serialize → parse is a fixed point
(byte-stable up to canonical scalar spellings and dropped auto-ids — see
§9).
Sibling docs. Animation detail (clocks, keyframes, easing, cues, triggers)
lives in docs/clocks-and-animation.md; the visual editor and DAG in
docs/node-graph.md; the layer timeline and span in docs/timeline.md; the two-process engine in docs/architecture.md; the MCP
tools and custom effects in docs/mcp-and-extensions.md; export and packaging in
docs/export-rendering-and-building.md; the stages: block in docs/stages.md. This file cross-links to them rather than
repeating them.
1. A project on disk
A Starlight project is a plain folder the user owns — no database, no bundle. It
is discovered by the presence of a project.yaml at its root.
bolts-demo/
project.yaml # surfaces + brand kit (§2)
scenes/ # one .yaml (or .yml) per scene (§3)
01-game-open.yaml
03-touchdown.yaml
assets/ # images (png/jpg/svg/webp/gif) + video (mp4/webm/mov/m4v/ogv)
logo.svg
scoreboard-loop.mp4
fonts/ # brand font files (otf/ttf/woff/woff2), mapped in project.yaml
Knockout-HTF.otf
extensions/ # custom effects/layers (see docs/mcp-and-extensions.md)
manifest.json
effects/ # effect modules: shader effects as data (see docs/effects.md)
ripple/effect.json # + main.wgsl, main.glsl
.starlight/ # editor VIEW state — committed, not scene content (see below)
layout.json
workspace.json
context/ # Claude session logs + the artist brief (docs/project-memory.md) — versioned
.gitignore # ignores renders/ and generations/ (regenerated or per-machine, never versioned)
renders/ # export output — gitignored, regenerated on demand; in a shared project it syncs to everyone (docs/shared-projects.md §2a)
generations/ # AI generation outputs + generation.json — gitignored (docs/project-memory.md)Where to keep projects
Keep projects on local disk (e.g. ~/Documents/Starlight/), not inside a
cloud-synced mount — ~/Library/CloudStorage/… (Dropbox, OneDrive, Google
Drive, Box), iCloud Drive (~/Library/Mobile Documents/), ~/Dropbox, or a
Windows OneDrive folder. Those providers offload files to dataless
placeholders; touching one stalls until it downloads, which can freeze saving,
versioning (git), and opening. Starlight times out its own housekeeping and
shows a one-time warning when it opens such a project. To share a project, push
its git repo to a remote, export renders, or copy the folder.
How a project is discovered and opened
Source: src/main/project.ts.
- Bundled demo → working copy. On first launch the app copies the bundled
demo-project/to~/Documents/Starlight/bolts-demo, runsgit init, and opens that copy henceforth (ensureDefaultProject). Keeping the working copy outside the app's own repo makes every project a real folder with its own version history. - A folder is a project when it contains
project.yaml.readProjectreads the project YAML, everyscenes/*.{yaml,yml}(in the scene order: project.yaml'ssceneOrder:, else by name —readdirorder is OS-dependent), listsassets/asstarlight-asset://URLs (stat only — the bytes stream over a Range-capable protocol; seedocs/assets.md) and inlinesfonts/as data URLs (the renderer never touches the filesystem; seedocs/architecture.md). - Which scene opens first — the scene that was last open in this project
(
lastScenein.starlight/workspace.json, written on every scene open), while it still exists; otherwiseproject.yaml'sdefaultScene, when it names an existing scene; otherwise the first scene in the scene order (pickOpenScene/pickDefaultSceneinmodel/project.ts— a deleted or renamed remembered scene falls back quietly). The MCPget_projectreports the same choice asopenScene. This is why the demo scenes are numbered01-…,03-…. - Every save is a git checkpoint.
⌘S(and each MCPwrite_scene) writes the file(s) andgit commits them;restore_checkpoint <hash>/ in-app undo rolls back. Seedocs/mcp-and-extensions.mdanddocs/export-rendering-and-building.md.
.starlight/ — editor view state, not content
.starlight/layout.json (canvas placement) and .starlight/workspace.json
(panel layout, per-scene graph pan/zoom, the last-open scene) are view
state: they ride the next checkpoint (they are not gitignored) but are never
part of the rendered scene. (A surface move and a guide edit are undoable in the
editor; see docs/architecture.md.) layout.json maps each surface to its place,
{ "N": { "x": 0, "y": 0, "guides": { "x": [960], "y": [540] } } }: guides is
optional, the surface's guides in its own pixels (x the vertical ones, y the
horizontal ones; help #canvas-rulers), and absent when the surface has none. What you arrange
in the graph is not view state: node moves, node colours and sticky notes are
scene content (§3).
A corrupt workspace file is ignored with one console warning and falls back to
defaults.
Schema versioning
Both project.yaml and every scene carry schemaVersion (a positive integer).
A scene that omits it reads as v3 (BASE_SCHEMA_VERSION); the serializer always
writes it back, raising it only when the scene uses something newer. It exists so a reader can migrate older documents — and refuse newer ones:
a scene above CURRENT_SCHEMA_VERSION fails with this scene is schemaVersion N, written by a newer Starlight — this build reads up to 18; update Starlight to open it
rather than being half-read.
| Document | Current | History |
|---|---|---|
| scene | 18 (CURRENT_SCHEMA_VERSION, model/scene.ts) | 1 the original format. 2 the matte composite node (§4), which replaces v1's mask: { source } field: a v1 mask: is still read and migrated into a matte node at parse (masks.md §7), so the next save writes v2. A scene that holds a matte node is v2 whatever it claims; a v1 scene with no masks keeps its 1 (an older Starlight can still open it). 3 an effect with no clock: of its own keys its animated params on its host node's clock (v1/v2: the scene loop) — §8. A v1/v2 effect whose reading would change (animated params, no clock:, on a node whose clock sets a period, mode or use:) is pinned at parse with clock: { mode: loop }, which is lossless (period absent = the scene loop, still following a loop change); a scene holding a clockless animated effect on such a node is written as v3, else it keeps its version. 4 a gradient's attributes can be keyframe lists, and a radial gradient carries center / radius (§4). A v3 reader would misread them (an angle list as NaN; centre and radius ignored), so a scene that uses any of it is v4 whatever it claims (raised at parse, like a matte) and is written as v4 (gradientSchemaVersion); every other scene keeps its version. Nothing older migrates: no v1–v3 scene can hold these shapes. 5 a video can carry an offset: (§4), the layer timeline's slip. A v4 reader would play the clip unshifted, so a scene with one is v5 whatever it claims and is written as v5 (videoOffsetSchemaVersion); every other scene keeps its version. Nothing older migrates. 6 an extension's node type, written node: <kind> (§4). A v5 reader knows no node: keyword, so a scene with one is v6 whatever it claims and is written as v6 (extensionNodeSchemaVersion); every other scene keeps its version. Nothing older migrates: before v6 such a node saved as null and could not be read back. 7 a node, or a surface binding's use: comp, can carry a delay: (§4): it and everything in it run later. A v6 reader would play it on time, so a scene with one is v7 whatever it claims and is written as v7 (delaySchemaVersion, model/delay.ts); every other scene keeps its version. Nothing older migrates: no v1–v6 scene holds one. 8 a comp can have a frame, written name: { size, children } instead of a node list (§3). A v7 reader expects a list there, so a scene with a framed comp is v8 whatever it claims and is written as v8 (compFrameSchemaVersion, model/comp-frame.ts); every other scene keeps its version. Nothing older migrates: no v1–v7 scene holds one. 9 a video can carry a trim: [in, out] (§4): a piece of the source, locked to the scene loop, on its own decoder. A v8 reader would play the whole clip on the transport, so a scene with one is v9 whatever it claims and is written as v9 (videoTrimSchemaVersion, model/video.ts); every other scene keeps its version. Nothing older migrates: no v1–v8 scene holds one. 10 a surface's tile plan can give each seam its own crossfade width (feather: [1024, 600]), carry the tiles' loop: and the seam check's match: (§3). A v9 reader refuses these keys in a plan, so a scene that uses any is v10 whatever it claims and is written as v10 (tilePlanSchemaVersion, model/tile-plan.ts); every other scene keeps its version. Nothing older migrates: no v1–v9 plan holds them. A bypassed comp (name: { children, bypass: true }, §3) is v10 too, for the same reason: a v9 reader refuses the key on a comp map (compBypassSchemaVersion, model/bypass.ts). 11 a video can name a version of its clip, version: denoise-41c0e9aa (§4, assets.md §10). A v10 reader would draw the original clip. For a clean-up or a new look, that is a different picture, so it would be a misread. So a scene with one is v11 whatever it claims and is written as v11 (versionSchemaVersion, model/video.ts); every other scene keeps its version. An older Starlight refuses a v11 scene and asks you to update; it never shows the original by mistake. Nothing older migrates: no v1–v10 scene holds one. 12 a clock track can be per-frame samples, x: { fps: 29.97, start: 187, values: [..] } (§8, clocks-and-animation.md §5). A v11 reader expects a key list there and refuses the scene with an error about the list, so a scene that writes a track as samples is v12 whatever it claims and is written as v12 (sampledTrackSchemaVersion, model/sampled-tracks.ts); a track that was samples but is now ordinary keys raises nothing. Every other scene keeps its version. Nothing older migrates. 18 matte sources (masks.md §8): a matte node can carry range: [low, high] (near / far on a depth matte, §4), and a video can name a matte version, version: depth-1a2b3c4d (a person, depth or roto mask of its clip that a matte node cuts with, §4). A v15 reader keeps range as an unknown key and cuts by the whole matte, and where the mask file is missing it would cut by the clip's own picture (a version falls back to its original there), both a different picture, so a scene with either is v18 whatever it claims and is written as v18 (matteSourcesSchemaVersion, model/matte.ts); every other scene keeps its version. Nothing older migrates: no v1–v17 scene holds one. The prerender: key (§4) needs no new version: it is a cache, not content. When the app saves it keeps the file's version and raises it only when the scene needs a newer one (it never lowers it); YAML written through MCP is stored as given, so write schemaVersion: 4 (an animated gradient), 5 (a video offset), 6 (a node:), 7 (a delay), 8 (a framed comp), 9 (a video trim), 10 (a tile plan's feather list, loop or match, or a bypassed comp), 11 (a video version:) or 12 (a per-frame track) yourself (write_comp and write_node save the scene in the app's own form, which sets it). 13 a text can lay out its lines: wrap, lineHeight, maxLines with overflow, anchorY: baseline and markup (§4). A v12 reader keeps them as unknown keys and draws one long line at the top of its box, a different picture, so a scene with any of them is v13 whatever it claims and is written as v13 (textLayoutSchemaVersion, model/text-layout.ts); every other scene keeps its version, and a text without them draws exactly as before. Nothing older migrates: no v1–v12 scene holds one. 14 a text can have an outline: stroke (a colour or a keyframe list), strokeWidth and fill: none for a hollow word (§4). A v13 reader keeps stroke and strokeWidth as unknown keys and draws no outline, a different picture, and refuses fill: none with a colour error, so a scene with any of them is v14 whatever it claims and is written as v14 (textStrokeSchemaVersion, model/text-stroke.ts); every other scene keeps its version (a v13 scene stays v13), and a text without them draws exactly as before. Nothing older migrates: no v1–v13 scene holds one. 15 a text can animate its letters one after another: letters: { by, stagger, order, clock } (§4). A v14 reader keeps letters as an unknown key and draws the word still, a different picture, so a scene with one is v15 whatever it claims and is written as v15 (textLettersSchemaVersion, model/text-letters.ts); every other scene keeps its version (a v14 scene stays v14), and a text without it draws exactly as before. Nothing older migrates: no v1–v14 scene holds one. 16 a shape or a path can trim its stroke, After Effects' Trim Paths: trimStart, trimEnd and trimOffset, each a value or a keyframe list (§4). A v15 reader keeps them as unknown keys and draws the whole stroke, a different picture, so a scene whose trim changes the picture is v16 whatever it claims and is written as v16 (trimSchemaVersion, usesTrim in model/trim-path.ts): the node draws a stroke, and its trimStart or trimEnd is a keyframe list whose keys differ, or its still values do not span the whole outline. Every other scene keeps its version (a v15 scene stays v15): an offset alone, a whole lap (0 → 1, or 1 → 0), trimEnd: 1 written out at its default, or a trim on a node that draws no stroke draws exactly what an older Starlight draws, and a shape without a trim draws exactly as before. Nothing older migrates: no v1–v15 scene holds one. 17 a particles node, a particle system (§4). A v15 reader knows no particles: keyword and would refuse the scene with expected a node keyword, so a scene with one is v17 whatever it claims and is written as v17 (particlesSchemaVersion, model/particles.ts); every other scene keeps its version. Nothing older migrates: no v1–v16 scene holds one. The prerender: key (§4) needs no new version: it is a cache, not content. When the app saves it keeps the file's version and raises it only when the scene needs a newer one (it never lowers it); YAML written through MCP is stored as given, so write schemaVersion: 4 (an animated gradient), 5 (a video offset), 6 (a node:), 7 (a delay), 8 (a framed comp), 9 (a video trim), 10 (a tile plan's feather list, loop or match, or a bypassed comp), 11 (a video version:), 13 (a text's wrap, lineHeight, maxLines, overflow, anchorY or markup), 14 (a text's stroke, strokeWidth or fill: none), 15 (a text's letters), 16 (a shape's or a path's trimStart, trimEnd or trimOffset), 17 (a particles node) or 18 (a matte range, or a video naming a matte version) yourself. |
project.yaml | 1 (PROJECT_SCHEMA_VERSION, model/project.ts) | Unchanged since 1. |
2. project.yaml
Declares the venue's canonical surfaces (every physical board, named once) and
the brand kit (design tokens + fonts). Parsed by parseProject
(yaml/parse.ts), validated by ProjectSchema (model/project.ts).
| Field | Type | Default | Meaning |
|---|---|---|---|
schemaVersion | integer > 0 | 1 | Document schema version (§1); the project format is still 1. |
project | string (non-empty) | — required | Project name (the project: key). |
surfaces | map: name → { size, fit? } | {} | Every surface in the building. |
brand.theme | map: token → value | {} | Design tokens ($team.gold → #FFB81C). |
brand.fonts | map: family → file path | {} | Font family name → project-relative file. |
assets | string | assets | Parsed into assetsDir and written back, but not used: the app always reads and writes assets/ (main/asset-list.ts, main/project.ts), so another value has no effect. |
defaultScene | string | — | Scene basename to open on launch when no last-open scene is remembered (falls back to the first scene in the scene order). |
sceneOrder | list of scene basenames | — (name order) | The scene order (help #scenes-order): the scene list, ⌘PageDown / ⌘PageUp, the palette, the reel and the MCP scene lists. Listed scenes first, in this order; every other scene after them, by name; a name that is not a scene is skipped. The scene list's drag, ⌥↑ / ⌥↓ and move up / down write it, one atomic edit of this key alone (src/shared/scene-order.ts) and one version per burst of moves; a rename, a duplicate (right after its scene) and a delete keep it right. An older Starlight keeps it untouched and lists by name. |
id | string (non-empty) | — | Optional stable project id; never written automatically, and it outlives a rename of project:. |
export | map | — | Delivery settings: naming (template; default {scene}_{surface}_{w}x{h}_{fps}fps_{codec}, tokens {project} {scene} {surface} {w} {h} {fps} {format} {codec}), formats, fps, aliases (surface → pixel-map name) — export-rendering-and-building.md. |
room | map | — | The Glimpse panel's venueUrl, feedWidth (512, 1024 or 2048) and feedFps (15, 30 or scene; default 30: how often the room takes a new frame and draws, at most) — previz-panel.md. |
media | map: root name → folder | — | Linked media folders; scenes reference media:<root>/<path> — assets.md. |
shared | boolean | — | Shared-project mode: omitted, a project in a cloud-synced folder is shared; false opts out, true forces it — shared-projects.md. |
Unknown top-level keys are preserved on the project's unknown bag
(§10).
surfaces
Each surface is { size, fit? }. size is the surface's output resolution — the
pixels Starlight renders for it (on an LED wall, its pixel map). It is required (WxH, e.g.
1920x1080, both sides > 0); a surface without a size is a ParseError
(surfaces.<name>.size — expected WxH), and so is a zero or negative one. fit is optional and is the default fit a scene uses for that
surface unless the scene's binding overrides it (§7).
surfaces:
jumbotron: { size: 1920x1080 } # fit defaults to none
ribbon-main: { size: 10080x84, fit: tile-x } # a long, short ribbon
vomitory: { size: 384x640, fit: cover } # a portrait tunnel boardbrand — the brand kit
brand.theme holds design tokens. Keys may be dotted (team.gold) or
nested maps (team: { gold: … }) — both resolve identically
(§6). Values are usually #hex colours but can be any scalar or a
$token that chains to another token.
brand.fonts maps a family name (used in scene text via font:) to a
file under fonts/ (fonts/<file>, subfolders allowed; .otf/.ttf/.woff/.woff2).
Only fonts/ is read into the payload, so a path anywhere else never loads. The renderer
loads each via the FontFace API before the first build, and again on every project load (an
open, a switch, Reload Project from Disk): new or changed files load, and families no longer
declared are removed (planFontLoad in brand-fonts.ts, loadFontFamilies in CanvasStage); a
replaced face clears Pixi's text-metrics cache. A missing file is skipped gracefully —
text falls back to a heavy-condensed system stack — so a scene never breaks for a
font the repo can't ship. The in-app font-row refresh also auto-discovers font
files directly in fonts/ (not subfolders) and names each by its filename
(lower-cased, spaces/underscores → -, -2 on a clash), writing project.yaml and a
rescan fonts (+N) checkpoint.
schemaVersion: 1
project: bolts-demo
defaultScene: 01-game-open
surfaces:
jumbotron: { size: 1920x1080 }
ribbon-main: { size: 10080x84, fit: tile-x }
vomitory: { size: 384x640, fit: cover }
brand:
theme:
team.gold: "#FFB81C" # dotted keys …
team.navy: "#0B162A"
team.electric: "#2BD9FF"
ink.white: "#F4F7FB"
wash.gold-0: "#FFB81C00" # 8-digit hex → RGBA (fully transparent gold)
fonts:
knockout-heavy: fonts/Knockout-HTF.otf
assets: assets
brand.themeandbrand.fontsalways serialize (as{}when empty); this is intrinsic to the model, not something you must author.
Weights and styles of a brand font: one key per file
A family such as Inter comes as one file per weight and style. In brand.fonts each file is
its own key, and the key is what a text names. The MCP tool list_fonts
(mcp-and-extensions.md §3) shows every key with the weight (100–900)
and style read from the file itself, so nobody has to guess which file is which.
brand:
fonts:
inter-regular: fonts/Inter-Regular.otf # Regular, 400
inter-italic: fonts/Inter-Italic.otf # Italic, 400
inter-bold: fonts/Inter-Bold.otf # Bold, 700
inter-bolditalic: fonts/Inter-BoldItalic.otf # Bold Italic, 700 (the key ↻ gives this file)How a text picks a weight or italic:
- Write the key of the file in
font:.font: inter-bolddraws Inter Bold. The menu name works too:font: Inter Boldfindsinter-bold(resolveFontChoice). - Leave
weight:out of a text in a brand font. Each file is loaded as a family of its own at one weight (aFontFacewith no weight,engine/compositor/assets.ts). Soweight: 600or more makes the browser thicken the file (a fake bold), even when the file is the Bold, and a weight under 600 changes nothing. - For a weight that has no file (SemiBold, say), add the file (below). Do not fake it.
Add a weight or a style:
- Put the file in the project's
fonts/folder: drop it on the Starlight window, or copy it in. - A dropped file is added to
brand.fontsat once. For a file you copied in, click ↻ beside the font field. The key is the file name in lower case, with a dash for each run of spaces or underscores (Inter-SemiBold.otf→inter-semibold,-2when the key is taken;rescanFonts).list_fontsshows this key asaddsAsbefore you click. - Write
font: inter-semiboldin the text.
Italic and bold inside one text (markup: true, §4 text) draw each style from its
own file. Starlight finds the file by what the font files say (their family, weight and italic
flag), not by the key names. For a text in a family at a weight:
*italic*: the same family's italic file, at the nearest weight;**bold**: the same family's Bold (700), else the nearest heavier file (600 or more, never lighter than the text);***bold italic***: the same family's italic file at that bold weight.
So any key name works: graphik-regularitalic (Graphik-RegularItalic.otf), gotham-bookitalic,
minionpro-it, helveticaneueltstd-bdit. A Medium text's **bold** is the Bold, and
font: Inter-Regular (other capitals) finds the same files as inter-regular. Starlight reads
the files once, when the project's fonts load or change (engine/model/font-styles.ts). A file
it cannot read is found by its key name instead: <stem>-italic, <stem>-bold,
<stem>-bold-italic, where <stem> is the text's key without -regular.
When a file is not there:
- A key whose file is missing draws with the fallback fonts (below), and so does a key whose
path is outside
fonts/or spelled with other capital letters than the file. - A style a markup text uses with no file draws upright or at the regular weight, and the text's properties say which file to add. Starlight never slants or thickens a brand file for markup.
- A variable font (one file with every weight,
wght 100–900) draws one weight. For several weights, use one static file per weight. - An online-only file (Dropbox) loads in the app once Dropbox has downloaded it.
list_fontsreports it and never downloads it, so it cannot say that file's weight and style.
3. The scene file
A scene names a loop, a design resolution, optional token overrides and named
clocks, shared comps, and per-surface surfaces bindings. Parsed by
parseScene, validated by SceneSchema (model/scene.ts).
| Field | Type | Default | Meaning |
|---|---|---|---|
schemaVersion | integer > 0 | 3 (BASE_SCHEMA_VERSION; the current version is 10) | Document schema version (§1). |
scene | string (non-empty) | — required | Scene name. |
loop | duration | — | Loop period, e.g. 4s. Absent → clocks fall back per-node. Keys are phases, so editing loop: by hand stretches every key on a clock that follows the loop. The app's duration field keeps the key times instead, or stretches everything in ms with them when asked (clocks-and-animation.md §3). |
fps | number, 0 < fps ≤ 240 | 30 at runtime | Frame rate for stepping + export encoding. |
design | size | 1920x1080 | The artboard: the canvas the shared comps are authored on. Each surface's fit scales it into that surface's output resolution. |
theme | map: alias → value | — | Scene-local token overrides; chain to the brand kit. |
clocks | map: name → named clock | — | Shared timing sources (docs/clocks-and-animation.md). |
cues | map: cue name → phase 0..1 | — | Cue points on the scene clock (the loop). |
markers | list of markers | — | Timeline markers at scene time (below). Never rendered. |
comps | map: name → node list | {} | Shared branches, instanced by surfaces. |
surfaces | map: name → binding | {} | What each surface shows. |
graphLayout | map: graph key → offset | — | Node-graph moves (below). Never rendered. |
graphColors | map: graph key → colour name | — | Node-graph organising colours. Never rendered. |
graphNotes | list of notes | — | Node-graph sticky notes. Never rendered. |
stages | map: stage id → stage | — | 3D shot blocking for AI generation (below). Never rendered. |
loop, fps, design, theme, clocks, and cues are omitted from the
serialized output when unset, and markers, graphLayout, graphColors and graphNotes
when empty, so a minimal scene round-trips clean. Unknown top-level keys land on
the scene unknown bag (stages rides it today, so it is written at the end of the file).
scene: 01-game-open
loop: 4s
design: 1920x1080 # the artboard: comps authored at 1920×1080, fit into each surface
theme: # scene aliases → brand tokens (resolved at render)
primary: $team.gold
base: $team.navy
electric: $team.electric
comps:
main: # a shared branch — file order = draw order (top drawn first / lowest)
- transform:
- gradient: radial
stops: [ { offset: 0, color: $base }, { offset: 1, color: $base } ]
size: 2600x1700
position: { x: 960, y: 540 }
surfaces:
jumbotron: { size: 1920x1080, use: main }
ribbon-main: { size: 10080x84, use: band, fit: tile-x, design: 1920x84 }
vomitory: { size: 384x640, use: portrait, fit: cover, design: 384x640 }comps — shared branches
comps is a map of comp name → node list. A comp is a reusable branch: a
surface instances one with use:, and a clone or use node can instance one
by name (§4). File order within a comp is draw order — the first item
draws first (lowest / furthest back), the last draws on top.
Framed comps — a comp with a size
A comp can have a frame (scene format v8, model/comp-frame.ts), like an After Effects
comp. It is then written as a map instead of a list:
comps:
hero: # framed: a 2520×1080 box (21:9)
size: 2520x1080
children:
- transform:
- image: assets/plates/skyline.png
position: { x: -400, y: 0 }
main: # unframed: a plain list, as always
- transform:
- use: hero # the holder transform places (and scales) the box
position: { x: 3200, y: 800 } # the frame's centre lands here: its top-left is at (1940, 260)
anchor: { x: 1260, y: 540 } # the frame's centre: the holder turns around its middle| Field | Type | Notes |
|---|---|---|
size | WxH, whole px, 1–16384 a side | required in the map form unless bypass is given. A missing size, a size that is not whole pixels, or any key other than size / children / bypass is a parse error at comps.<name>.…. |
children | node list | The comp's nodes, exactly what an unframed comp's list holds. Omitted = empty. |
bypass | true / false | A bypassed comp (scene format v10, model/bypass.ts): it draws nothing wherever it is used — every use: of it, every clone of it, every surface bound to it (that surface's inline children still draw). Written only when true: name: { children: [...], bypass: true }, a framed one { size, children, bypass: true }; switched off, the comp goes back to its list (or { size, children }) form. A scene with a bypassed comp is v10 (compBypassSchemaVersion); a v9 reader refuses the key. In-app: b, or the bypass switch, on the comp's root node. |
- The crop. A framed comp draws only
(0, 0, w, h)of its own px, wherever it is drawn: at ause:(the holder transform places and scales the box), in each copy of acloneof it (the copy's cell is the frame), and on a surface bound to it withuse:(the box sits at the surface's design origin;designandfitwork as before). The viewer crops the same way. An unframed comp is unbounded, as before. - Node ids do not change. The nodes keep the plain comp path (
comp/<name>/<i>), so framing or unframing a comp keeps every auto id, and an unframed comp is written as before. - Presets (
compFramePresets): Seedance's own output sizes — 16:91920x1080, 21:92206x946, 4:31664x1248, 1:11440x1440, 3:41248x1664, 9:161080x1920(the 1080p tier of Seedance 1.5 / 2.0 / 2.5), and 16:9-4k3840x2160, 21:9-4k4398x1886(Seedance 2.0 Pro 4K). These are ByteDance's own output sizes (BytePlus ModelArk API reference); ByteDance offers no 9:21 — and each project surface's size. A frame of exactly the size the model makes is an input it does not resample or re-crop. - Pre-comp (
precompNodes, the app's Pre-comp…, MCPprecomp) moves sibling layers into a new framed comp and leaves ONEtransform: [ - use: <comp> ]holder in their place that puts the frame's top-left on its origin; the layers shift by −origin inside the comp, so nothing moves on screen. Like every new layer, the holder turns around its centre: itsanchoris the frame's centre(w/2, h/2)and itspositionis origin + that anchor. A moved layer with no transform of its own gets a wrapper that only does the shift, and no anchor (it had none). New Comp… (createFramedCompUse) writes its holder the same way. Set Comp Frame (setCompFrame, MCPset_comp_frame) adds, changes or removes a frame without moving the content. Renaming a comp keeps its frame. - Generate from this comp (MCP
render_comp_still) renders the frame at its pixel size (a one-surface scene bound to the comp atsize = design = frame) and stores the PNG asassets/comps/<scene>/<comp>-<hash8>.png, with a sidecar inassets/.comps/. For Seedance 2.0, which makes six shapes only, the app grows the frame to the nearest shape first and renders that bigger box, the comp's layers past the frame included (generation.md §12). When the clip lands, the app adds it to the comp as an ordinarytransform: [ - video: … ]on top, scaled to that box, so the frame crops the added band: no new format. - Scale to Fit inside a framed comp fits the frame:
fitTargets(model/fit-layer.ts) returns the frame as the one target (kind: 'comp') for a layer in a framed comp, throughcompFrameOf(scene, comp), so the app and MCPfit_layernever ask which surface.
surfaces — per-surface bindings
A scene's surfaces map binds content onto the project's surfaces by name. Each
binding is { size?, fit?, design?, use?, delay?, children?, tiles?, prerender? } (SurfaceBinding).
| Field | Type | Default | Meaning |
|---|---|---|---|
size | size | project surface's size | The output resolution for this scene: the pixels rendered. Overrides the project's. |
fit | fit mode | project surface's fit / none | How the artboard maps into the output resolution (§7). |
design | size | scene design (1920×1080) | This surface's own artboard: the canvas its content is laid out on. |
use | comp name (non-empty) | — (unbound) | Comp to instance at the surface root — the comp that feeds this surface, re-routable in the node graph. Must name a comp in comps (unknown comp "<x>" — valid comps: …). |
delay | duration (may be negative) | — (on time) | Runs the use: comp this much later on this surface — the surface-to-surface chase: one comp on five surfaces, each a little later. The comp's whole timeline turns: its keys, its effects and its layers' spans. The surface's own children keep scene time. Scene format v7; serialized only when set (§4). |
children | node list | — | Extra nodes drawn at the surface root, on top of use. |
tiles | map | — | The surface's tile plan for AI video (below). Editor metadata: never rendered. |
prerender | true, or { alpha: auto | on | off } | — (drawn live) | Play the whole surface's content from a file rendered on this computer (§4). A cache: no new scene version. |
Both use and children may be present — the comp draws, then the inline
children draw over it. Neither is required: a binding without use is an unbound
surface — N: {} is valid, round-trips, validates and exports; the surface renders its inline
children, or black when it has none. One comp may feed any number of surfaces. Re-routing a
surface (the node graph's feed wires, or a
write_scene) changes only use: the surface's size, fit, design and children stay. Surface children are ordinary design-space nodes and are
fit into the surface just like a comp, so a child that needs positioning must be
wrapped in a transform (§4).
One rule: a scene can only use the surfaces project.yaml declares. A binding for another
name (an unknown surface, e.g. main-4k beside a project that has only main) parses,
round-trips and shows in the node graph, so the artist can rewire or remove it (its
Properties sheet notes not in project.yaml — not shown, rendered or exported). Nothing else
treats it as a surface: the canvas and exports build only project.yaml's surfaces, its clips
never decode, render_still / render_surfaces refuse or leave it out, Glimpse publishes only
project surfaces, and the thumbnails, Tile Plan, pre-render, Scale to Fit and the effect preview
never pick it. The canvas warns once per scene (This scene uses a surface named main-4k, but the
project has no surface with that name. It is not shown or exported. …), and an MCP
write_scene / create_scene saves it with a warnings line that lists the project's surfaces.
The rule is wallsNotInProject (model/focus.ts); the words are src/shared/unknown-walls.ts.
To add a surface, add it under surfaces: in project.yaml (a name and its size, §2) and
choose File › Reload Project from Disk (a shared project reloads by itself). No button and
no MCP tool adds one.
Output resolution vs artboard. The two sizes do different jobs, and the Properties
sheet names them by that job (the YAML keys stay size and design): the output
resolution (size) is what renders, the artboard (design) is what you lay content
out on, and fit scales the artboard into the output. Selecting a surface shows one row each:
the output resolution as W × H (marked overridden, with the project's value and a reset,
only when this scene's size differs from project.yaml's), the fit (its inherited value
reads none (project)), and the artboard, folded to same as output when the two match.
Every edit is the scene binding; project.yaml is never written from the sheet.
The per-surface design is the ribbon pattern. The scene design is
jumbotron-native (1920×1080). A ribbon is 10080×84 — fitting a 1080-tall comp
down to 84px is a ~13× crush that makes marks illegible. Instead, author a
band-native comp and give the ribbon its own design: 1920x84, so tile-x
scales it 1:1 and repeats honest tiles:
comps:
band: # authored at true 84px ribbon height
- clone: { of: assets/bolt-rib.svg, count: 6, gap: 480, direction: x, drift: -240px/s }
surfaces:
ribbon-main: { size: 10080x84, use: band, fit: tile-x, design: 1920x84 }Fit computation and how surfaces render across the multi-surface canvas are
detailed in docs/export-rendering-and-building.md.
tiles — a surface's tile plan
Tile Plan (help "Tile a surface for AI video") cuts a surface into zones, one AI video
generation each, at a Seedance output shape. The plan rides the surface's binding. It is editor
metadata like markers: nothing renders it, an older Starlight keeps it as an unknown key, and
a surface without one writes no tiles: line, so older scenes read and write byte for byte as
before. A plan needs no new schemaVersion, except that a feather list (one width per seam),
a loop or a seam check's match makes the scene v10: Starlight 0.2.12 and 0.2.13 read plans
but refuse those keys, so v10 makes them say "update Starlight" instead (tilePlanSchemaVersion,
model/tile-plan.ts).
surfaces:
N:
design: 6400x1600
fit: none
children: [ … ] # the artist's layers; never removed
tiles:
model: seedance-2.5-pro # seedance-2.5-pro | seedance-2.0-pro | videorouter-seedance-2.5
tier: 1080p # 1080p, or 4k (seedance-2.0-pro only)
shape: 21:9 # 21:9 (2206x946, 4K 4398x1886) or 16:9 (1920x1080, 4K 3840x2160)
overlap: 20% # the least overlap asked for (0.2 also reads)
zones: [0, 2669] # each zone's left edge, in the surface's native px
seams: [3200] # optional: each crossfade's centre (default: mid-overlap)
feather: 1024 # optional: the crossfade width (default: the overlap, at most 1024),
# or one per seam: [1024, 600] (v10)
batch: b5k2m9 # set by Generate tiles
videos: [assets/tiles/01-panorama/N/b5k2m9-tile-01.mp4, null] # set by Assemble
video: 2206x946 # optional: the clips' real px when not the shape's
loop: # optional (v10): every tile made into the same loop
clip: 4041.667ms # the length every tile is cut as (the shortest clip)
overlap: 1s # optional: Make Loop's settings, its defaults when absent
dissolve: noise # (noise | crossfade), noiseScale, softness, seed, evolve
match: # optional, set by Check seams (schemaVersion 10)
colour: true # colour match on (default); false keeps the fits unused
fits: # one per seam (~ = none): the LATER clip's correction
- clips: [assets/…-tile-01.mp4, assets/…-tile-02.mp4]
gain: [1.021, 0.968, 1.044] # R, G, B: later' = gain · later + offset, 8-bit levels
offset: [-2.4, 3.1, 0.6]
mask: assets/tiles/01-panorama/N/detail-5d1c2e9a.png # white = every clip stays still
maskClips: [assets/…-tile-01.mp4, assets/…-tile-02.mp4]- A zone is always the full surface height at the tile's aspect (21:9 on a 1600 px surface is 3731×1600), so only its x is stored. There is one row: a horizontal seam would cut through people.
- Assemble writes the comp
tiles-<surface>(each clip in its zone, scaled to surface px; later zones on top; the top clip's left edge feathered across the seam's band) and, when a band starts inside the overlap, a small framed comptiles-<surface>-t<N>that cuts the top clip first. Oneuse: tiles-<surface>goes on top of the surface's children. These are ordinary comps; a re-assembly (a seam or the feather changed) rewrites them. loop(Make Loop on a tiled surface: the panel's make tiles loop, MCPmake_loop { scene, surface }): every assembly makes each placed clip into the same Make Loop cut (videotrim), named after its zone (tiles-N-z1,tiles-N-z1-a,-b,-matte,-dissolve,-black,-noise), and sets the sceneloopto it. So a seam move or a re-rolled tile keeps the loop. A new batch drops the key.matchis what the seam check found (help "Check the seams";tiles_check { scene, surface };engine/model/tile-match.ts). A fit (or the mask) applies only whilevideosstill names the clips it was measured on, so a re-rolled tile never gets a stale correction. With colour match on, Assemble puts a masked adjustment layer above the later clip in its cut comp:adjust: {}with alevelseffect for the gain and offset, cut by agradientramp from the band to the zone's end (no second video node). It makes the scene v10 (above). Gains 0.5–2, offsets ±128; gain and offset ranges, list lengths and keys are checked at parse.- Keep design detail sharp is not in the plan: it is a
mattenode (mode: luma,invert: true) around the surface'suse: tiles-<surface>holder, cut by the detail mask image (scaled from grid px onto the surface). It is an ordinary matte in the surface's list. - Prefer the tools to a hand edit:
plan_tiles,generate_tiles,assemble_tiles,set_tile_seams,make_loop { scene, surface },tiles_check,set_tile_match(mcp-and-extensions.md).
graphLayout, graphColors, graphNotes — node-graph metadata
Three top-level keys hold what you arrange in the node graph (node-graph.md): where you moved nodes, the colours you gave them, and the sticky notes on the graph. They are editor metadata: scene content, versioned with the scene and undoable edit by edit, that is never rendered. The surfaces, the viewer, export and MCP renders never read them, and changing them rebuilds no surface (the rebuild plan files them as inert). Each is omitted when empty.
graphLayout:
"@surface:N": { x: 40, y: 0 }
pin-k3x9a2: { x: 0, y: -24 }
graphColors:
"@surface:N": blue
"@comp:wall-N": purple
pin-k3x9a2: green
graphNotes:
- id: note-0f3k2a
x: 120
y: -80
w: 220
h: 110
color: yellow
text: intro hits on the downbeat
- id: note-9a1b2c
in: wall-N # inside comp wall-N's graph; absent = top level
x: 0
y: 140
w: 220
h: 110
text: |-
two lines
of textGraph keys. graphLayout and graphColors key a glyph the same way:
@surface:<name> a surface root, @comp:<name> a comp, @main the scene dial,
@clock:<name> a named clock's dial, and a content node by its id. A content
node with an auto id is given an explicit pin-… id the first time it is moved or
coloured, so its key survives a reorder (an auto id is positional,
§9). A node whose id the YAML already spells out
(id: logo, or an earlier pin) keeps it and is keyed by it, so MCP edits and references
that name it never break.
Effect chips and synthetic glyphs (a clone's source, a use instance) have no
key of their own: they follow the auto layout, and an effect chip wears its host
node's colour. Renaming a comp, surface or clock in the YAML does not carry its
key along; rename the key too, or the offset / colour / note is left behind.
graphLayout— graph key → a manual offset{ x, y }(graph px, a Vec2) added on top of the auto layout. Written by node moves; reset layout clears the map.graphColors— graph key →red,orange,yellow,green,blueorpurple. A neutral organising palette with no meaning of its own (not the Generations grades). Anything else is a parse error that names the six.graphNotes— the sticky notes, in draw order (a later note draws over an earlier one). A hand-written note needs onlytext:
| Field | Type | Default | Meaning |
|---|---|---|---|
text | string | "" | The note's plain text. Use a |- block for several lines. |
id | string | note-<n> (n = its place in the list, from 1) | Stable note id. A repeated id is made unique at parse. |
in | comp name | — (the top level) | The comp whose drilled-in graph the note belongs to; it shows only there. |
near | graph key or name | — (the first column) | What the note is about, so a note with no position is placed beside it: a graph key ("@comp:wall-E1", "@surface:N", "@main", "@clock:<name>"), a node's id, or a bare comp / surface name. Read only while the note has no position. |
x, y | number | — (none saved) | Top-left corner, in that graph view's graph px. Leave both out and the graph places the note in free space beside near, never on a node or another note (node-graph.md). Moving or resizing the note in the graph saves them. One alone is a position (the other is 0). |
w, h | number > 0 | — (sized to the text) | Size in graph px. Left out, the note is as wide as its longest line (90 to 320) and as tall as its wrapped lines. |
color | graph colour | — (uncoloured) | One of the six graphColors names. |
A note written with only its text is saved the same way: no x, y, w or h, so it stays
placed by the graph until someone moves it. Starlight 0.2.27 and older filled in x: 0, y: 0, w: 220, h: 110 for such a note and saved that; this exact rect reads as no position. near
and a note with no rect raise no schemaVersion: notes are never rendered, and an older
Starlight reads a note without a rect at 0, 0 (and ignores near), as before.
They sit beside graphLayout rather than inside it on purpose: a Starlight
build that predates them keeps them as unknown top-level keys
(§10) instead of refusing the file. read_scene
returns them with the rest of the scene, so an agent can read the user's notes.
markers — timeline markers
Labelled, coloured moments on the timeline (timeline.md §markers),
at scene time. Editor metadata like graphNotes: versioned and undoable, never
rendered, and changing them rebuilds no surface. A marker drives nothing — unlike a cue
(§8), which a trigger can fire from, so moving or
renaming a marker can never retime a clock.
markers:
- 1.5s # a marker with no label
- { at: 3s, label: drop, color: red }| Field | Type | Default | Meaning |
|---|---|---|---|
at | duration ≥ 0 | — required | The instant, in scene time. |
label | string | — | What the flag reads (else its time). |
color | graph colour | — | One of the six graphColors names. |
An item is a bare duration (a marker with neither label nor colour) or the map. Parse sorts
the list by at; serialize writes the bare form when it can. A video node carries its
own list in the same grammar at clip time (video). No schema bump: a Starlight
that predates markers keeps them as unknown keys (§10) and renders
the scene identically.
stages — 3D shot blocking
A stage blocks out one AI generation before anything is spent: clay boxes, cylinders,
cones, spheres and posable figures on a ground, in metres, seen through a render camera
with a real lens, framed to the aspect the model will make. Its grey layout capture goes
to an image or video model as an input. A stage belongs to the scene but is not a
node: it adds nothing to the graph, renders on no surface and reaches no deliverable. The
full reference (every key, frames and checks, figures and poses, captures, recipes, the
stage_* MCP tools): stages.md.
stages:
hero-wide: # stage id: ^[a-z0-9][a-z0-9-]{0,47}$, at most 64 per scene
name: Hero on the riser
target: jumbotron # a project surface (optional): default frame, crop guide
frame: surface # the OUTPUT aspect: `surface` (the target's; the default with a target) or W:H like '21:9'
camera:
pos: { x: 0, y: 1.6, z: 9 } # metres, Y up, the ground is y 0
target: { x: 0, y: 1.3, z: 0 }
focal: 35 # mm on a 36 mm-wide frame, 8..1200
items:
- id: k1
kind: figure # box | cylinder | cone | sphere | figure
name: hero
pos: { x: 0, y: 0.6, z: 0 } # the centre of the footprint: standing on the riser
size: { x: 0.56, y: 1.75, z: 0.42 }
pose: { name: arms-up }
- id: k2
kind: box
name: riser
pos: { x: 0, y: 0, z: -1 }
size: { x: 8, y: 0.6, z: 4 }- Validated on write, lenient on load. Plain parsing never checks a stage, so a broken
one never stops its scene from opening (the stage list marks it invalid). The MCP write
paths —
stage_write, and awrite_scene/create_scene/ compose plan that carriesstages:— check each stage against the project and reject a broken one with an issue at the exact path (§11). - Write paths.
stage_write/stage_deletechange only thestages:block (comments elsewhere survive). Awrite_sceneis the whole file, so leavingstages:out of one deletes the scene's stages. - Captures live beside the scene, not in it:
assets/stages/<scene>/<id>-<hash8>.pngwith a provenance sidecar underassets/.stages/. - An older Starlight keeps the block as an unknown key (§10).
4. Nodes
A node is a map whose single type keyword selects its kind; sibling keys are
its props. The keyword → kind mapping (NODE_KEYWORDS, model/nodes.ts):
| Keyword | Kind | Keyword value is… |
|---|---|---|
text | text | the string content |
image | image | the asset path |
cutout | image (+ a cutout effect) | the asset path — a legacy spelling (below) |
video | video | the asset path |
audio | audio | the asset path (a track: draws nothing) |
shape | shape | rect | ellipse | line |
path | path | the list of subpaths |
gradient | gradient | linear | radial |
transform | transform | the child list |
group | group | the child list |
clone | clone | the { of, count, … } map |
particles | particles | the { rate, life, emitter, … } map (every key optional) |
use | ref | the comp name |
adjust | adjust | {} — an adjustment layer has no content of its own |
matte | matte | the { content, matte, … } map — two input nodes and the matte's settings |
node | an extension's kind | the node type an extension registered (below) |
Exactly one keyword must be present. Zero keywords → expected a node keyword (text, image, …). Two or more → ambiguous node — multiple keywords present: …. Both are friendly ParseErrors anchored to the node's path
(§11).
Fields on every node
Regardless of kind, any node may carry these common fields (NodeCommon):
| Field | Type | Default | Meaning |
|---|---|---|---|
id | string | auto-derived | Stable identity. Usually omitted — see §9. |
clock | clock block | — | Phase-space animation driving this node (docs/clocks-and-animation.md). |
bypass | true | — | Switches off what the node adds (model/bypass.ts). A transform or group passes its children through: they draw and animate as if it were not there (none of its position, scale, rotation, skew, anchor, opacity, blend, clock, gate, span, delay or effects). A source (image, cutout, video, shape, path, gradient, text, use, clone, particles, audio, an extension's node) hides, with its subtree, and samples nothing. A matte shows its content uncut. An adjust layer is inert. |
blend | a blend mode (below) | — | How the node's finished pixels (after effects + opacity) combine with what is beneath. Omit/normal → default; serialized only when set. Full reference: blend-modes.md. |
effects | list | — | Stacked GPU effects (§8). |
span | [in, out] — two durations | — (the whole loop) | The layer's in/out point in scene time (After Effects' layer bar): the subtree renders only while in ≤ t < out, t being the wrapped loop time live preview and export both sample. 0 ≤ in < out; bare numbers are ms. Independent of the clock — keyframes stay in phase space. Serialized only when set, as a flow pair (span: [1s, 2500ms]) (below; docs/timeline.md). |
delay | duration (may be negative) | — (on time) | The node and everything inside it run this much later: its clock, its effects' and gradient's keys, its children, and — on a use: / clone of a comp — the comp's whole timeline. Read on the looping scene time, wrapped. Moving a layer bar in the timeline sets it. Scene format v7; serialized only when set (below). |
prerender | true, or { alpha: auto | on | off } | — (drawn live) | Play the node's content from a video file that Starlight renders on this computer (below). A cache, not content: it needs no new scene version. Serialized only when set. |
bypass is a special case: only the literal true is retained — any other
value (false, absent) leaves the field unset, so an un-bypassed node serializes
without it. In-app, b (or the bypass switch on the node in the graph) toggles bypass on the
selected node. Before 0.2.14 a bypassed transform or group hid its subtree; the file is
the same, only the reading changed.
blend modes, grouped as in Photoshop (the props panel's dropdown uses the same
groups):
| Group | Modes |
|---|---|
| normal | normal |
| darken | darken multiply color-burn linear-burn |
| lighten | lighten screen color-dodge add |
| contrast | overlay soft-light hard-light vivid-light linear-light pin-light hard-mix |
| inversion | difference exclusion negation |
| cancellation | subtract divide |
| component | hue saturation color luminosity |
Spellings are forgiving: case, spaces, underscores and camelCase normalize
(Soft Light, softLight, soft_light → soft-light), and linear-dodge
(also plus, plus-lighter, Linear Dodge (Add)) is add — it parses to add
and serializes as add. Anything else is a parse error that lists the valid set
(comps.main.0.blend: expected a blend mode (…)), so a typo never silently renders
normal. normal, add, screen and multiply are free GPU blend states; every
other mode costs one backdrop copy + one pass over the node's bounds
(blend-modes.md §4). A group with effects or a non-hardware
blend is isolated: its children blend against each other inside it, then the group
blends onto the scene.
span — a layer's in/out in scene time
- text: "TOUCHDOWN"
span: [1s, 3s] # on from 1s, off at 3s (half-open: 3s itself is off)span is the After Effects layer bar on a model whose motion lives in phase space. It
gates whether the subtree is drawn at scene time t — nothing else. The node's clock
keeps sampling, its keyframes stay where they are, and a gate on the same node still
applies: the node shows only where both the span and the gate are on (bypass still
wins over both). The rules:
- Half-open, scene time, wrapped. Visible while
in ≤ t < out,tthe transport's wrapped loop time — never the unwrapped audio time — so a span is loop-perfect by construction and two abutting spans never overlap or gap by a frame. - No wrap-around.
in < outalways; a stretch that would cross the loop seam is two layers, or agate(the phase-space in/out, which repeats every clock cycle). - Full = absent. A span covering the whole loop is not stored, so trimming a bar back out in the timeline leaves no YAML behind.
Edited in the layer timeline (an edge's top half trims, the body's bottom half moves and its
top half copies, ⌥[/⌥] set at the playhead); edits write whole milliseconds that land on frame boundaries. A move
(or copy, paste, nudge) writes the span and the layer's delay together, so the keys go with the bar. Errors:
§11. Full detail: docs/timeline.md.
delay — a layer runs later
- transform:
- text: "LINE 2"
clock: { tracks: { x: [-400, 0, 0] } }
delay: 200ms # the whole layer runs 0.2 s later: its fly-in starts 0.2 s after LINE 1'sdelay is After Effects' layer start time, on a model whose keys live in phase space
(docs/clocks-and-animation.md §3).
The node and everything inside it read the looping scene time t − delay, wrapped into
the loop: a delayed loop is the same loop, turned, so it never seams. Negative runs it
earlier. The rules:
- What it reaches. The node's own clock (tracks and gate), its effects' animated params
(their own clock or the node's), a gradient's keys, every child (delays add up down the
tree), and through a
use:/ clone of a comp the comp's whole timeline, its spans included. A clone draws one raster per frame, so all its copies share the one delay. - What it leaves alone. The node's own
span, and the spans of the layers beside it in the same comp: a span is where a layer shows, in its comp's time. Audio drives follow the song. A video's frames follow its clip (offset:, one decoder per clip). - A surface's delay. A surface binding's
delayturns itsuse:comp on that surface only (§3): the surface-to-surface chase. - The timeline writes it. Moving a layer bar moves its
spans and itsdelaytogether (⌘ / Ctrl moves the span only). A comp's own timeline shows the comp's own time; each use of it runs its delay later. - Absent = 0. A zero delay is not stored. A duration (
2s,-250ms; bare numbers are ms), stored in whole ms. A scene that holds one is written as v7.
prerender — play a layer from a file
- transform:
- use: crowd-heavy
prerender: true # or { alpha: auto }, { alpha: on }, { alpha: off }A heavy layer (many clips, effects or nested comps) can be slow to draw live. With
prerender:, Starlight renders the node's content once to a video file and plays that file
instead (shared/prerender.ts, model/prerender-key.ts). Any node can carry the key, and so
can a surface binding (§3). To pre-render a comp, put the
key on its use: node. A framed comp's map cannot hold it: an older reader refuses unknown
keys there.
- The values.
trueis the same as{ alpha: auto }.autokeeps transparency only when the content has it (Starlight checks the first, the middle and the last frame).onalways keeps it.offrenders the content over black. - What is in the file. The node's content: its children, with their clocks, effects,
spans and comps. For a
use:, the comp. For amattenode, the cut result. - What stays live. The node's own transform, clock, opacity, effects, blend and span. So the file sits exactly where the content sat. To bake the node's own effects too, pre-render its parent instead.
- Delays. On a
use:(or a clone), the delay stays live: its own, and every delay above it. On any other node, its own delay and its parents' delays in the same comp are in the file (its children's spans keep the comp's time, so they cannot move with the file); changing them makes the file stale. A delay that comes from outside the comp (ause:above it, a surface'sdelay:) stays live: one file plays on every surface of a chase. - While you edit inside. When the selection is inside the node, the node draws live, so you can still click, select and move its layers.
- A cache on each computer. The files live in this computer's renders folder
(
renders/.prerender/<key>/; in a shared project<root>/renders/.prerender/<key>/, which never syncs). They are not in the scene and not in git. Each computer renders its own. The key is a hash of everything the content depends on: its nodes, media files, versions, clocks, the sceneloopandfps, fonts and colour files. Graph layout, notes and markers do not change it. Changing the code of an extension that the content uses (extensions/<name>/index.js) makes its files stale. - Fresh, stale, none. Fresh: a file matches the content now, so the file plays. Stale: the content changed after the last render, so the node draws live and shows a stale badge until it is rendered again. None: no file yet, so the node draws live. An undo back to an earlier state finds that state's file again.
- One loop. The file holds exactly one scene loop. Content that does not repeat every loop cannot be pre-rendered, and Starlight says why. Examples: an untrimmed clip whose length does not divide the loop, a clock on audio time, a music drive.
- No new scene version. An older Starlight keeps the key and ignores it (§10). It draws the node live, which is the same picture.
- Export. An export always renders live, so its pixels are exact (the files are 8-bit
4:2:0). There is no switch yet to export from the pre-rendered files. The
request field for it,
ExportRequest.usePrerenders, exists, but the export sheet and the MCP tools do not set it. - A/B. ⌥B / Alt+B on the selection shows the node live or from its file. Only the view changes; the scene does not.
Positioning: only transform moves things
A text / shape / path / image / gradient / clone / particles node has no position of
its own — it draws at its parent's origin. To place one, wrap it in a
transform and set position there. A stray position: on a bare shape is not
an error — it lands silently on the node's unknown bag and is ignored by the
compositor.
text
- text: "TOUCHDOWN" # keyword value = content (coerced to a string)
font: knockout-heavy # a brand.fonts family name
size: 204
fill: $primary # #hex or $token
weight: 800 # number or string ("bold")
letterSpacing: 2
align: left # left | center | right| Field | Type | Default | Notes |
|---|---|---|---|
content | string | — required | The text: value; a non-string is coerced with String(). A line break starts a new line. |
font | string | — | A brand font family, or a font installed on this computer (Arial, Segoe UI). The name a font menu shows also works: Knockout Heavy finds the brand family knockout-heavy, and a weight or style word on the end (Segoe UI Semibold, Helvetica Neue Bold Italic) sets that weight (unless weight is set) and style. Resolved by resolveFontChoice (engine/model/font-choice.ts). A name with no form that is there falls back to the condensed system stack. |
size | number > 0 | — | Type size in design px. |
fill | colour, a list, or none | — (white) | #hex or $token — anything else is a ParseError (§5) — or a keyframe list of them (animated, below). v14: none draws no fill: with a stroke, a hollow word (outline, below). |
stroke | colour or a list | — (no outline) | v14. The outline's colour, #hex / $token or a keyframe list of them (animated, below). Drawn centred on the letters' edges, under the fill (outline, below). |
strokeWidth | number > 0 | 1 (with a stroke) | v14. The outline's width in px of the text's own space: 6 puts 3 px outside each letter and 3 px inside it. Without a stroke it draws nothing. |
weight | number | string | — | e.g. 800 or "bold", for a font installed on this computer. A brand font file has one weight: name the weight's key instead (font: inter-bold), because 600 or more on a brand file is a fake bold (§2 weights and styles). |
letterSpacing | number | — | Tracking in px. |
align | left|center|right | — | Horizontal alignment — it also sets the block's anchor: left puts the left edge on the transform's point, center the middle, right the right edge. Lines of several line up the same way inside the block. |
wrap | number > 0 | — (no wrapping) | v13. The width, in px of the text's own space, that lines wrap at: as many words as fit go on a line, breaking at spaces (the spaces at a break are dropped); a word wider than wrap breaks between its letters. A line break still starts a new line. |
lineHeight | number > 0 | — (the font's own line box) | v13. Baseline to baseline, as a multiple of size: 1.25 with size: 40 puts the baselines 50 px apart. The extra space goes half above and half below each line, as in CSS and Figma. |
maxLines | whole number ≥ 1 | — (all lines) | v13. At most this many lines; the rest is cut. |
overflow | ellipsis | clip | ellipsis | v13. What a text cut by maxLines shows: ellipsis ends the last kept line in … (letters come off its end until the line with … fits wrap), clip just stops. |
anchorY | top | baseline | top | v13. Which part of the text sits on the transform's point vertically: the top of its box, or the FIRST line's baseline. The baseline comes from the metrics of the face that draws, so it is exact for any font. |
markup | true | — (off) | v13. *italic*, **bold** and ***bold italic*** in the content draw in those styles (below). |
letters | map | — (the text draws as one) | v15. { by, stagger, order, clock }: the text animates unit by unit, each unit on its own run of clock, one stagger after the one before (letters, below). |
Optional fields are omitted from the model until set; at render a
textwith nosize/fill/align/letterSpacingfalls back to48px /#ffffff/left/0(registry/builtins.ts), and astrokewith nostrokeWidthis 1 px wide.
Layout (v13). A text with any of wrap, lineHeight, maxLines, overflow, anchorY
or markup is laid out by engine/registry/text-layout.ts layoutText: the canvas, every
export and still, and the MCP measure_text tool all run it, so its lines and baselines are
the same everywhere (measure_text: mcp-and-extensions.md §3).
It measures with the renderer's own canvas text measure and the font string the text draws with.
A text with none of these fields is built exactly as before (its pixels do not change).
# A review card: the body wraps at 920 px, baselines 54.75 px apart, the first
# baseline on the transform's point, at most 4 lines with an ellipsis.
- transform:
- text: "easily one of the most beautiful animated films i've seen in years. *every frame* looks like a page from an illuminated storybook"
font: Inter
size: 38
fill: $bodyInk
wrap: 920
lineHeight: 1.4408 # 54.75 / 38
maxLines: 4
anchorY: baseline
markup: true
position: { x: 40, y: 213.5 } # where the first baseline goesMarkup. With markup: true: *italic*, **bold**, ***bold italic***. A run of
asterisks opens a style when a letter follows it and closes one when a letter comes before it;
it closes the nearest open run with the same number of asterisks. Anything else is a plain
asterisk (5 * 3, an opener never closed, four or more in a row), and \* is always an
asterisk (in a double-quoted YAML string, write \\*). Styles nest and run across line
breaks. Each style draws with its own face:
- A brand font (a
brand.fontsfile) draws each style from its own file: the file of the same family that is that style, found by what the files say, whatever its key (§2 weights and styles). A style with no file draws with the regular file, and the text's properties panel andmeasure_textsay which file is missing. Starlight never slants or thickens a face itself. - An installed font asks the system for its italic, and for a bolder weight (CSS
bolder: 400 → 700, 600 → 900), as any app does.
The runs of a line sit on one baseline, and baselines are lineHeight apart whatever the faces.
Outline (v14). stroke draws an outline round every letter, strokeWidth px wide (1 when
not set), and fill: none leaves the letters empty, so outlined type needs no SVG.
- text: GOAL # a hollow word: only the outline
size: 220
fill: none
stroke: $team.gold
strokeWidth: 6
- text: TOUCHDOWN # a filled word with a contrasting edge
size: 160
fill: "#FFFFFF"
stroke: $ink
strokeWidth: 10- Centred on the edge, under the fill. The stroke straddles each letter's edge, half outside
and half inside, and the fill is drawn over it, so with a fill only the outer half shows (a
strokeWidth: 10edge looks 5 px wide). Every stroke is drawn before every fill, so a thick outline never covers a neighbouring letter or the line above. - Round joins. Corners of the outline are rounded, so the sharp corners of an italic or a condensed face do not grow spikes.
- The letters do not move. Adding an outline leaves every letter, line and baseline where it
was, for every
align,wrap,lineHeight,maxLines,anchorY,markuprun andletterSpacing; the outline reaches out half its width. Wrapping still measures the letters, not the outline. - The box grows. The text's box (selection, snapping, a clock's pivot, effects) is the
letters' box grown by half the stroke width on every side, as a shape's stroke is.
measure_textreports that box, withoutset(the half width); its lines and baselines are the letters', unchanged.
Animated colour. fill may be a keyframe list instead of a colour, the shape fill's form
(shape): shorthand [a, b, a] or long form [{ phase, value, ease }], each value a
#hex or a $token. It rides the node's own clock: (else the scene loop), blends in OKLab
with the usual eases, and carries alpha in the colour (#rrggbbaa). Every *italic* and
**bold** run follows the one colour. The outline's stroke animates the same way, on the same
clock, apart from the fill. A still colour stays a value on save; an animated one stays its
shortest list
(clocks-and-animation.md §4).
- text: GOAL
size: 160
fill: ["#FFFFFF", $team.gold, "#FFFFFF"] # white, gold, white
clock: { period: 2s }No new schemaVersion for an animated fill: an older Starlight refuses a list in fill
(expected a colour …, naming the field) rather than drawing it some other way, so the scene
keeps the version its other content asks for (a layout field still makes it v13, an outline
v14, letters v15).
Letters (v15). Type that arrives letter by letter is ONE text with letters:, never one
node per letter. The text splits into units and each unit runs its own copy of a clock, each a
stagger after the one before: the clone cascade on a
text (engine/model/text-letters.ts).
- text: TAYLOR # a hero name, 2 frames per letter at 60 fps, a small landing
font: anton
size: 520
fill: $ink
letters:
by: letter # letter (default) | word | line
stagger: 33ms # unit k starts k × 33 ms after the first
order: forward # forward (default) | reverse | center | edges | random
clock: # each unit's own clock: a node clock's shape
period: 200ms
mode: once
tracks:
opacity: [0, 1, 1]
scale: [{ phase: 0, value: 0.4, ease: overshoot }, { phase: 1, value: 1 }] # peaks ≈ 1.06
fill: [{ phase: 0, value: "#FF5A1F", ease: hold }, { phase: 0.2, value: "#FF5A1F" }, { phase: 1, value: $ink }]| Field | Type | Default | Notes |
|---|---|---|---|
by | letter | word | line | letter | What one unit is. A letter is a grapheme (a letter with its accents, an emoji with its skin tone, a flag: Intl.Segmenter, the splitter Pixi draws spaced text with); a ligature the font draws splits into its letters. A word is a run of letters between spaces (a markup word that changes style is one unit). A line is a laid-out line (after wrap and maxLines). Spaces are never units and take no stagger slot. |
stagger | duration ≥ 0 | 0 | The time between one unit's start and the next's, as a clone's stagger: unit k in order runs k × stagger behind the first. At 60 fps a frame is 16.67 ms: 33ms is 2 frames per letter. |
order | forward | reverse | center | edges | random | forward | The order units start in, over the whole text (line by line, left to right). center: the middle unit first, then outward, the left one of an equal pair first (TAYLOR runs Y L A O T R). edges: both ends first, then inward (T R A O Y L). random: a fixed shuffle seeded by the node's id (integer hashing): the same every frame and on every machine; another node, or another unit count, shuffles otherwise. Every order gives each unit a slot of its own. |
clock | clock | — (the units hold still) | Each unit's clock, the shape of a node's clock: (§8): period (else the scene loop), mode (once | loop | pingpong), or use: a named clock (its trigger and anchor apply), and tracks. gate and drive are refused here (they belong on the text's own clock). |
clock.tracks | tracks | — | x, y, scale, scaleX, scaleY, rotate, skewX, skewY, opacity, keyed in phase like any track (shorthand, long form or per-frame samples), plus fill: a colour keyframe list (#hex / $token, OKLab) that colours each unit's fill in place of the text's fill. A stroke track is refused: the outline keeps the text's stroke (still or keyed on the text's own clock). |
- Each unit moves from its own place.
x/yoffset it,opacityfades it, andscale,scaleX,scaleY,rotateand the skews turn round the middle of the unit's advance horizontally and its line's baseline vertically, so a letter grows up from the line it sits on. - Timing is the clone's (
compositor/instancing.tsinstancePhase, unit slot as the index):loopandpingpongrepeat each unit on its own phase; aonceclock holds its first key until the unit starts and its last after it ends, so the word is still at the end. The node'sdelaydelays the letters too. The last unit ends at period + (units − 1) × stagger (with 6 letters, 200 ms and 33 ms: 365 ms).measure_textgives the unit counts (units) and, for a text withletters:,lastStartMsandtotalMs. - At rest the picture is the text's. With every unit at rest (opacity 1, no offset, scale
1, no turn) every glyph is exactly where the text without
letters:draws it: kerning with the letter before it,align,letterSpacing,wrap,lineHeight,maxLinesand its…,anchorY,markupruns and the outline (every stroke under every fill). Each unit is drawn at the pen Pixi's own draw of the line reaches it at,W(line) − W(line[i:]) + i × letterSpacing, and on the same pixel grid, at the same fraction of a pixel, so on whole-px placements the pixels are the same. Off the grid (a fractional position, a scale, a turn) only the filtering of edge pixels can differ, each letter's texture keeping a 1 px empty margin. - The text's own clock still drives the whole text (a slide under the type-on), and its
own
fill/strokekeys tint every unit's fill / outline on that clock. - Cost: one texture per unit per paint pass (an outline doubles it), built once; each frame moves and tints units, never redraws them. Fine for names and titles; a paragraph by letter is hundreds of textures.
- In the app. The text sheet has letters by, order and stagger ms (under
more until set) and a note of the unit count and timing; the per-unit
clockis set in YAML in this version. The timeline shows the text's own clock lanes and colour lanes, not the per-unit tracks. - Errors at the key:
letters.by — expected letter, word or line,letters.order — …,letters.stagger — expected the time between one unit's start and the next's: 0 or more,letters.clock.gate — a letter does not take a gate,letterson any other node (only a text animates its letters). Keys inside the map that Starlight does not know stay inside it, as a clone's do. - v15. A v14 reader would keep
lettersas an unknown key and draw the word still, so a scene with one is written as v15 (textLettersSchemaVersion) and an older Starlight asks to update; every other scene keeps its version.
image
- image: assets/logo.svg # asset path under the project assets dir| Field | Type | Default | Notes |
|---|---|---|---|
src | string (non-empty) | — required | The image: value. A non-string is a ParseError (expected an asset path). png/jpg/svg/webp/gif. Draws at its own pixel size, top-left at the origin; an SVG scaled up is drawn again at the size it is shown, so it stays sharp at the same layout size (assets.md §9). A missing or undecodable file draws Texture.WHITE — a single 1×1 white pixel — and the canvas's bottom-left line names it: missing media: … when the file is gone, could not load: … when it will not decode (renderer/missing-media.ts). |
cutout
- cutout: assets/players/jane.jpg # legacy spelling of the form below
# parses to, and saves back as:
- image: assets/players/jane.jpg
effects:
- cutout: {} # the subject, background removedcutout: is legacy sugar. It parses to an image node with a cutout effect at the
head of its effects stack, and the next save writes that form, so the graph always shows
image → cutout → filters and b A/Bs the extraction. A non-string value is a ParseError
(expected an asset path). Write the image + cutout effect form. The subject is
extracted (background removed) by macOS subject extraction (Vision) on a Mac and saved in the
project as assets/.cutouts/<name>-<hash>.png, so every machine (Windows too) draws the same
cutout (assets.md §8). Where none is saved
and this machine cannot make one, the original image draws and the canvas says cutout not made
yet – open on a Mac to make it. Nothing in the scene names the cutout file; the format is
unchanged.
video
- video: assets/scoreboard-loop.mp4
loop: true # default true — venue content loops
muted: true # default true — venue playback is silent; false plays the clip's sound| Field | Type | Default | Notes |
|---|---|---|---|
src | string (non-empty) | — required | The video: value (mp4/webm/mov/m4v/ogv). |
loop | boolean | true | Loop the clip. |
muted | boolean | true | Mute the clip's own sound. false plays it on the transport, through the monitor, and mixes it into exports at full volume (when the file has an audio stream). Once per clip however many layers show it, timed like the picture (the first node's loop and offset); any un-muted, un-bypassed layer on the clip sounds it. |
offset | duration (may be negative) | 0 | Scene v5. The clip's place on the transport: transport 0 shows this clip time (2s starts the clip 2 s in; -1s starts it a second late, holding its first frame). What the layer timeline's slip writes (timeline.md §gestures). One decoder per clip: every node on a src plays at the first one's offset, and a slip writes them all. Not written when 0. |
trim | [in, out] (two durations, 0 ≤ in < out) | — | Scene v9. Play only this piece of the source (trim: [5s, 10s]), locked to the scene loop: at its span's start (loop time 0 with no span) it shows source in, then plays on with the loop, and holds its frame just before out if the piece is shorter than its time on screen. Outside its span it waits on its in frame, ready for its next entrance. It restarts on every loop pass, so it never drifts against the loop. A trimmed node has its own decoder: two trimmed layers on one file show different times (Make Loop uses this). It ignores loop and offset, a slip never moves it, and it never sounds (the file's sound comes from its untrimmed layers). The loop time it reads is the scene's, not a comp's delay. Not written when absent. |
version | a version id, <op>-<hash8> (denoise-41c0e9aa) | — (the original) | Scene v11 (a matte version, person-…, depth-… or roto-…: v18, and only as a matte node's input, below). The layer plays this version of its clip: a file made from it, such as an upscale or a clean-up (below; assets.md §10). video: still names the original. Not written when absent. |
markers | list of markers | — | Layer markers at clip time (ms into the source), the scene markers grammar. They mark the content: they show wherever the clip plays that frame, so a slip slides them with the clip (timeline.md §layer markers). Never rendered. |
(loop/muted are only written when explicitly set; their runtime default is
true.) A span never shifts the clip — it is a window onto it (timeline.md §span); the offset does.
Transparent video needs nothing in the scene. A clip imported with alpha (ProRes 4444,
VP9 alpha, HEVC with alpha, a dropped PNG/EXR/TIFF sequence folder) is ingested to a packed
matte — colour and alpha in one hardware-decoded stream — and the video node draws it
with its alpha at the clip's own size (docs/assets.md §6). The packing is recorded next to
the asset (assets/.mattes/), not in the scene.
A version of the clip
- video: assets/walls/north.mp4 # the scene still names the original
version: denoise-41c0e9aa # scene v11: this layer plays the versionA version is a new file made from a clip: sharper, cleaner, at another frame rate, or with a
new look. It lives beside the clip, in assets/.versions/ (assets.md
§10), never in the scene. version: only says which
version this layer plays (VideoNode.versionId, model/versions.ts).
- The scene names the original. Remove
version:and the layer plays the original again. New layers start on the original. - The layout does not change. A version draws at the original's size. A 2× upscale draws in the same place, at the same size; only the pixels are sharper.
- When the version cannot play, the original plays. This happens when the version file is
not on this computer, or when the version does not match the clip or this layer now (for
example, it was made for 60 fps and the scene is 30 fps). The canvas line and Properties
say why, for example
version not used: north.mp4 · fps-a1b2c3d4 made for 60 fps; the scene is 30 fps. The version file stays. - Export uses the version's full file. When the version is not on this computer, the export refuses, like a missing file: shipping the original without a word would be wrong. When it is there but does not match, the export goes ahead with the original, and the result lists the reason as a warning.
- Scene v11. A scene with a
version:is v11. An older Starlight refuses to open it and asks you to update. - A/B. ⌥B / Alt+B on the selection shows the original or the version. Only the view changes; the scene does not.
audio
- audio: assets/audio/anthem.mp3
volume: 0.8 # 0..1, default 1
offset: 1.5s # start this far INTO the track (transport 0 plays from here)| Field | Type | Default | Notes |
|---|---|---|---|
src | string (non-empty) | — required | The audio: value (mp3/wav/m4a/aac/flac/ogg). A non-string → expected an asset path. |
volume | number 0..1 | 1 | Playback gain. |
muted | boolean | false | Silence playback; the track and its analysis stay. |
offset | duration ≥ 0 | 0 | Where in the track transport 0 starts (1.5s, 1500ms, bare ms). Negative → validation error. |
loop | boolean | false | Restart the track when it ends (a song plays once by default). |
export | boolean | true | Mux this track into exports. |
A track, not a picture: it draws nothing and plays against the transport's unwrapped
time, so a song longer than the loop plays on across loop wraps. Clocks can follow it with
drive (clocks-and-animation.md); it is never a matte input.
shape
- shape: rect # rect | ellipse | line
size: 850x18
fill: $electric
stroke: $ink
strokeWidth: 2
radius: 9 # rect corner radius| Field | Type | Default | Notes |
|---|---|---|---|
shape | rect|ellipse|line | — required | Anything else → expected rect, ellipse, or line. |
size | size (WxH) | — | Bounding size; width and height > 0. |
fill | colour or a list | — | #hex / $token, or a keyframe list of them (animated, below). |
stroke | colour or a list | — | Stroke colour (#hex / $token), or a keyframe list of them. |
strokeWidth | number ≥ 0 | — | Stroke width in px. |
trimStart | number 0..1 or a list | 0 | Trim paths (scene v16, below): where the stroke starts, a fraction of the outline. |
trimEnd | number 0..1 or a list | 1 | Where the stroke ends, a fraction of the outline. |
trimOffset | number (degrees) or a list | 0 | Turns the drawn stretch round the outline; 360 = one lap. |
radius | number ≥ 0 | — | Corner radius (rect). |
At render, an omitted
sizedraws at100×100and an omittedstrokeWidthstrokes at1. Alineignoresfilland strokes in itsstrokecolour (falling back tofill, else#ffffff). Arect/ellipsewith neitherfillnorstrokedraws nothing. The box is drawn from its top-left corner; an ellipse fills it.
Animated colours. fill and stroke may each be a keyframe list instead of a colour,
the gradient stop colour's form: shorthand [a, b, a] or long form [{ phase, value, ease }],
each value a #hex or a $token. The list rides the node's own clock: (else the scene
loop); keys blend in OKLab with the usual eases; alpha rides in the colour (#rrggbbaa), so a
fill fades by keying its alpha. A $token key plays the colour the token resolves to, and
follows the brand kit. A still colour stays a value on save; an animated one stays its
shortest list (clocks-and-animation.md §4).
- shape: rect
size: 400x120
radius: 12
fill: ["#1E3A8A", $team.gold, "#1E3A8A"]
clock: { period: 2s }No new schemaVersion: an older Starlight refuses a list in fill (expected a colour …,
naming the field) rather than drawing it some other way, so the scene keeps the version its
other content asks for.
Trim paths — draw part of the stroke
trimStart, trimEnd and trimOffset draw only part of a shape's or a path's stroke: After
Effects' Trim Paths, for line reveals, logo stroke builds, progress rings and underline wipes.
The fill is never trimmed: it draws whole whatever the trim. A node that draws no stroke has
nothing to trim (a rect or ellipse without stroke, a path with a fill, a closed subpath
and no stroke set).
trimStart,trimEndare fractions0..1of the outline's length (After Effects' Start and End, 0–100 %). Absent:0and1, the whole outline. A value outside0..1is an error (trimEnd 1.5 is out of range 0..1, at its key).- They are interchangeable, as in After Effects:
trimStart: 0.8, trimEnd: 0.2draws the stretch from 0.2 to 0.8. Equal values draw no stroke.0→1is the whole outline, drawn as an untrimmed stroke (a closed outline stays closed, with no seam). trimOffsetturns the drawn stretch round the outline, in degrees (After Effects' Offset):360is one lap, a negative value turns it back, and any number works (720= two laps). On a closed outline a stretch the offset carries past the start point runs on through it as one unbroken stroke; on an open one it comes out as two pieces, one at each end.- Where an outline starts (After Effects' order): an
ellipseat 12 o'clock, arectat its top-right corner (just below its rounding), both running clockwise; alineat(0, 0)towards itssizecorner; apathat the first vertex of each subpath, in vertex order. - Several subpaths trim together, each by the same fractions of its own length (After
Effects' "Simultaneously"):
trimEnd: 0.5draws the first half of every subpath. - The ends of a trimmed piece are square (butt), as an open path's are.
- Animated: each value may be a keyframe list in place of the number — shorthand
[0, 1]or long form[{ phase, value, ease }]— riding the node's ownclock:(else the scene loop), the gradient angle's form (clocks-and-animation.md §4). A still value stays a value on save, a list its shortest form. - The box does not change: selection, a clock's pivot and fit use the untrimmed shape's bounds at every trim.
- shape: ellipse # a progress ring that draws itself round once
size: 300x300
stroke: $team.gold
strokeWidth: 12
trimEnd: [0, 1]
clock: { period: 2s, mode: once }
- shape: line # an underline that wipes in from the left
size: 800x1
stroke: "#ffffff"
strokeWidth: 6
trimEnd: [{ phase: 0, value: 0, ease: snap }, { phase: 0.4, value: 1 }]
- shape: ellipse # a quarter arc that spins (a loader)
size: 120x120
stroke: "#ffffff"
strokeWidth: 8
trimEnd: 0.25
trimOffset: [0, 360]
clock: { period: 1s }Scene v16. A scene whose trim changes the picture — on a node that draws a stroke, a
trimStart or trimEnd that moves (a keyframe list whose keys differ) or still values that do
not span the whole outline — is written as schemaVersion: 16 (§1): an older
Starlight would keep the fields as unknown keys and draw the whole stroke, so it refuses the scene
and asks to update instead. A trim that draws the same picture an older Starlight draws (an
offset alone, a whole lap, a node with no stroke) raises nothing.
path
- path: # keyword value = a LIST of subpaths
- vertices:
- { p: [0, 0], in: [0, 0], out: [40, 0] } # corner: in = out = [0,0]
- { p: [160, 90], in: [-40, 0], out: [0, 0] } # in/out are deltas RELATIVE to p
closed: true
fill: $primary # fills CLOSED subpaths only
stroke: $ink
strokeWidth: 2| Field | Type | Default | Notes |
|---|---|---|---|
path | list of subpaths | — required | The keyword value; a non-list → expected a list of subpaths. |
fill | colour | — | #hex / $token. Paints closed subpaths only. |
stroke | colour | — | Stroke colour (#hex / $token). |
strokeWidth | number ≥ 0 | — | Stroke width in px (render fallback 2). |
trimStart / trimEnd / trimOffset | numbers or lists | 0 / 1 / 0 | Trim paths (scene v16), as on a shape: every subpath trimmed by the same fraction, from its first vertex. |
An editable cubic-bezier vector shape — created by the pen tool (command palette
pen → create · path); it is not emitted by SVG or After-Effects import in
the shipping UI. Like shape, a path has no position of its own — wrap it in a
transform.
Each subpath is { vertices, closed } with at least 2 vertices (fewer → validation
error); closed (default false, only literal
true closes) joins the last vertex back to the first — a fill needs at least one
closed subpath. Each vertex is { p, in, out }, three [x, y] points (each
defaulting to [0, 0] when omitted):
p— the on-path point, in design px.in/out— the cubic-bezier handles, as deltas relative top(the Lottie / After Effects convention): absolute controls arep + inandp + out. A corner vertex hasin = out = [0, 0]; a smooth vertex mirrors them.
An open or unfilled path always strokes — the builder defaults it to white at width
2, so a freshly-drawn line is always visible (precisely: with no stroke, it strokes
white unless it has a fill and at least one closed subpath). path.fill / path.stroke resolve
$tokens exactly like shape, and animate like it: a keyframe list of colours in place of the
colour, on the node's clock. Its stroke trims like a shape's (Trim paths):
a logo's outline that draws itself on is its path with trimEnd: [0, 1].
gradient
- gradient: linear # linear | radial
angle: 90 # linear angle: 0 = left→right, 90 = top→bottom
stops:
- { offset: 0.0, color: $base }
- { offset: 0.5, color: $sweepMid } # offset optional — see below
- { offset: 1.0, color: $base }
size: 760x1700| Field | Type | Default | Notes |
|---|---|---|---|
gradient | linear|radial | — required | Anything else → expected linear or radial. |
stops | list of { offset?, color } | — required | A missing list → expected a list of gradient stops. |
angle | number (degrees) or a list | 0 | Linear only; 0 = left→right, 90 = top→bottom (clockwise, y down). Any angle. |
center | [x, y] / { x, y } / a number, fractions of the box | [0.5, 0.5] | Radial only. Animated: { x: <n | list>, y: <n | list> }. |
radius | number ≥ 0 or a list, fraction of the box | 0.5 | Radial only; 0.5 = the ramp ends at the box edges. |
size | size (WxH) | the design size | The box the gradient fills, from its top-left corner; width and height > 0. The default is the design size of the surface it is built on (surfaceDesign: the binding's design, else the scene's). Animated: { width: <n | list>, height: <n | list> } (px). |
A linear gradient runs through the box's centre along the true angle, in the box's
own pixels, and spans it corner to corner the way CSS linear-gradient does: the first and
last stops land exactly on the far corners, so a 30° ramp is 30° on a 6400×1600 box too
(linearGradientLine, registry/builtins.ts). Only the zero direction differs from CSS
(here 0 points right, not up). A radial gradient is centred at center (default the middle), its last stop at
radius (default the box's edge).
Each stop needs a color — a #hex or $token (a ParseError otherwise). offset is
optional, and when given must be a number in 0..1 (stop offset 1.5 is out of range 0..1, checked like a cue phase); when omitted it is auto-distributed evenly — stop i of n gets i/(n-1) (a lone
stop gets 0). So stops: [ {color: $a}, {color: $b}, {color: $c} ] implies
offsets 0, 0.5, 1.
Animated attributes (scene v4). Each of angle, radius, a stop's offset and
color, center.x / center.y and size.width / size.height may be a keyframe list
instead of a value — shorthand [a, b, a] or long form [{ phase, value, ease }] (a colour's
value is a hex string or a $token). The lists ride the gradient node's own clock: (else
the scene loop); colour keys blend in OKLab, and a $token key plays the colour it resolves to.
A static attribute stays a value on save; an animated one stays its shortest list
(clocks-and-animation.md §4).
- gradient: linear
angle: [0, 90, 0]
stops:
- { offset: 0, color: ["#1E3A8A", "#86198F", "#1E3A8A"] }
- { offset: [1, 0.6, 1], color: "#4C1D95" }
clock: { period: 10s }
- gradient: radial
center: { x: [0.3, 0.7, 0.3], y: 0.5 } # static: center: [0.5, 0.5]
radius: [0.3, 0.6, 0.3]
size: { width: [800, 1200, 800], height: 600 } # static: size: 1920x1080
stops: [ { offset: 0, color: "#ffffff" }, { offset: 1, color: "#ffffff00" } ]transform
The only node that moves, scales, rotates, skews, fades, or re-anchors its subtree. The keyword value is the child list.
- transform:
- text: "BOLTS"
fill: $primary
position: { x: 170, y: 455 }
scale: 1.05 # scalar → { x: 1.05, y: 1.05 }
rotation: -16 # degrees
skewX: -10
skewY: 0
opacity: 0.85 # 0..1
anchor: { x: 0, y: 150 } # pivot in local px| Field | Type | Default | Notes |
|---|---|---|---|
position | vec2 | — | Translation in parent px. |
scale | vec2 | — | Non-uniform; a scalar normalises to {x,y}. |
rotation | number | — | Degrees. |
skewX / skewY | number | — | Skew in degrees. |
opacity | number 0..1 | — | Out-of-range → validation error. |
anchor | vec2 | — | Pivot / anchor in local px: the point that lands on position. Static and animated (clock-track) scale, rotation and skew turn around it. Without it, static ones turn around (0,0) and a clock's around the subtree's box centre (the rule scenes made before keep). New layers made in the app write it at their content's centre, with position where that centre lands (or anchor: 0 when the content's size is not known at create time). |
children | node list | — required | The transform: value. |
group
A pure container — children share the group's clock and effects but the group applies no transform of its own (bypassed, it passes its children through). The keyword value is the child list.
- group: # e.g. an L-bracket built from two rects
- shape: rect
size: 88x10
fill: $primary
- shape: rect
size: 10x88
fill: $primary| Field | Type | Default | Notes |
|---|---|---|---|
children | node list | — required | The group: value. |
clone — repetition in one draw call
Instances a source many times along a line or grid. The keyword value is a map; its params live inside that map (not as node siblings).
- clone:
of: assets/bolt-sm.svg # an asset path OR a comp name
count: 16
gap: 160 # primary-axis pitch in px
direction: x # x | y | grid | radial
drift: -160px/s # seamless belt velocity
stagger: 80ms # per-instance clock phase offset (a cascade wave)
clock: { period: 2s, tracks: { scale: [0.9, 1.2, 0.9] } }Grid form:
- clone:
of: assets/bolt-sm.svg
count: 48
gap: 236 # column pitch (x)
gapY: 210 # row pitch (y)
direction: grid
rows: 6
cols: 8
clock: { period: 2s }
stagger: 55ms # offsets the clone's own clock per copy; no clock, no cascade| Field | Type | Default | Notes |
|---|---|---|---|
of | string (non-empty) | — required | A comp name, else an asset path (which has a file extension). Missing/non-string → expected a source path or comp name; neither a comp nor an asset path → "<x>" names no comp and is not an asset path … — valid comps: …. |
count | integer ≥ 0 | 0 | Instance count (ignored by direction: grid, which draws rows × cols). Always serialized. A non-number ("16") is a ParseError, never 0 instances. |
gap | number | 0 | Primary-axis pitch in px. Always serialized. A non-number is a ParseError. |
direction | x|y|grid|radial | x | Layout axis (or a circular ring). |
rows | integer ≥ 0 | — | Grid rows (direction: grid). |
radius | number ≥ 0 | — | Ring radius px (direction: radial) — instances spread evenly, first at 12 o'clock. drift then spins the ring in degrees/s (seamless when drift × loop is a multiple of 360/count). |
cols | integer ≥ 0 | — | Grid columns (direction: grid). |
gapY | number | gap | Grid row pitch in px. |
drift | velocity (px/s) | — | Seamless belt velocity along the row / column; the belt wraps within count × gap px. A grid does not drift. |
stagger | duration | — | Per-instance clock-phase offset (the cascade). It offsets the clone's own clock:; with none it does nothing. |
The clone's own clock animates each copy (x, y, scale, scaleX, scaleY, rotate,
opacity; skew is not applied per copy), copy i running i × stagger behind the first. A
comp source is rasterized once per frame and that one texture is instanced, so every copy shows
the same frame of the comp's own animation. A text's letters cascade the same way, one letter (word, line) per
copy, with letters: { stagger, order, clock } on the text (§4 text, letters).
rows, cols, gapY and radius must be numbers too (rows/cols whole). Unknown
keys inside the clone: map stay inside the map, and unknown sibling keys stay siblings
— each re-serializes where it was written.
Seamless belts: a drifting belt loops cleanly only when drift × loop is a
whole number of gaps — e.g. -160px/s × 4s = 640 = 4 × 160. See
docs/clocks-and-animation.md. With a stagger AND a clock, each copy carries its own
phase, so a whole number of gaps is not enough: copy i lands in copy i + k's slot with a
different phase and the animation jumps at the wrap. Make drift × loop a whole number of
belt widths (count × gap) instead. A radial drift is read as degrees/s whatever its unit
(drift: 45 or 45px/s; it re-serializes as 45px/s). The properties panel's clone
section offers radial too, with a radius (px) field, and its drift reads °/s. Picking
radial sets no radius, so the copies stack until one is typed.
particles — a particle system
Sparks, dust, snow, embers, confetti, stars: sprites born at rate per second from an
emitter, each flying its own path for its life, sized, faded and tinted over that life
(model/particles.ts, registry/particles-sim.ts). One node, one draw call. Scene format v17.
- transform:
- particles:
of: assets/spark.png # optional: an asset or a comp, as for clone; absent = a soft dot
seed: 7
rate: 120 # births per second
life: 2.5s
lifeRandom: 0.3 # ±30 %
emitter: { shape: ellipse, size: 600x200, from: edge }
angle: -90 # 0 = right, 90 = down (the gradient rule); or outward
spread: 30 # the launch cone's width in degrees; 360 = every way
speed: 240 # px/s
speedRandom: 0.4
gravity: { x: 0, y: 180 } # px/s²
drag: 0.6 # 1/s, linear
turbulence: { amount: 80, scale: 400, evolve: 1, octaves: 2 }
size: 18 # px at birth
sizeRandom: 0.5
color: $team.gold # the tint, when there is no overLife.color
rotation: 360 # random start angle range, degrees
spin: 120 # each particle turns a random -120..+120 °/s
overLife: # keyframe lists on phase = age / life
size: [0.3, 1, 0]
opacity: [0, 1, 1, 0]
color: ["#FFFFFF", $team.gold, "#FF4800"]
trail: { length: 150ms, samples: 5, fade: 1 }
max: 4000
blend: add
position: { x: 960, y: 980 }
anchor: 0Every param is optional and lives inside the particles: map (- particles: {} is a working
system); only authored values are stored. Keys the map does not know stay in it, as a clone's do;
a key the nested maps (emitter, turbulence, trail, overLife) do not know is an error.
| Field | Type | Default | Notes |
|---|---|---|---|
of | string | a soft dot | An asset path or a comp name, by clone.of's rules (a comp is rasterized every frame; cycles, typos, renames and asset references follow it). size sets the sprite's longer side. |
seed | whole number | 0 | Another seed is another pattern of the same system. The app writes a random one on create and on duplicate. |
rate | number > 0 | 40 | Births per second, snapped so rate × loop is a whole number (at least 1). |
life | duration > 0 | 2s | How long each particle lives. |
lifeRandom, speedRandom, sizeRandom | 0..1 | 0 | ± fraction (0.3 = ±30 %). |
emitter.shape | point | line | rect | ellipse | point | Centred on the node's origin. |
emitter.size / emitter.length | size / px | 100x100 / 100 | A rect's or an ellipse's box; a line's length, along x. |
emitter.from | area | edge | area | Born anywhere inside a rect / ellipse, or on its outline. |
angle | degrees, or outward | -90 | The launch direction: 0 right, 90 down, -90 up. outward: away from the emitter's centre (a ring burst); from a point, every way. |
spread | 0..360 | 30 | The launch cone's full width. |
speed | px/s ≥ 0 | 120 | |
gravity | { x, y } px/s² | none | A sideways one is a wind. |
drag | 1/s ≥ 0 | 0 | Linear: 1 slows a particle to about a third of its speed in a second. |
turbulence | { amount, scale, evolve, octaves } | none | A curl-noise push off the path: amount px (60), features scale px wide (300), evolve whole field cycles per scene loop (1; 0 = a still field), octaves 1..4 (2). turbulence: {} is on with the defaults. |
size | px > 0 | 12 | At birth. |
color | colour | #ffffff | The sprite's tint (#hex / $token), multiplied into it. |
rotation / spin | degrees / °/s | 0 / 0 | A random start angle in a range that wide; each particle turns a random speed between -spin and +spin. |
overLife.size / .opacity / .color | keyframe lists | — | On phase = age / life (0 born, 1 dies), shorthand or long form with eases. size multiplies size, opacity is 0..1, color keys (hex or $token, OKLab-blended) replace color. |
trail | { length, samples, fade } | none | samples (1..16, 4) copies of each particle's own past, the last length ago (150ms), fading by fade (0..1, 1). trail: {} is on with the defaults. |
max | whole 1..20000 | 2000 | Sprites per instance: particles × (1 + trail samples). |
A pure function of time. A particle's state is a closed-form function of the scene time and
the seed, never stepped frame to frame (docs/clocks-and-animation.md §3 "Particles"). So
scrubbing, delay, span, the loop wrap, nested comps and parallel export segments all draw the
same frame, and preview and export are the same pixels.
- The loop is seamless by construction. Births repeat every scene loop: N =
rate × loopbirths per loop, one per slot, and every random a particle draws is keyed by its slot. At the start of the loop the particles born near its end are still in flight, so the system never starts empty and never jumps at the wrap. Alifelonger than the loop shows two generations of each particle at once. - Its clock is its layer's. The node's own
clock:moves, scales, turns, skews and fades the WHOLE cloud like any layer's (the cloud lives in the node's space: a moving parent carries it). Aspanreveals a system that is already running. - The budget.
maxcaps the sprites one instance draws; every surface, every tile of atile-xsurface and everyuse:of a comp holding it is its own instance. Overmaxthe rate is lowered to fit (the Properties panel says so, and MCP writes return a warning); when even one birth per loop needs more (a life of several loops, a long trail), the warning says it is still over. A scene should stay under 20 000 sprites in all, over every surface, tile and comp use (PARTICLES_SCENE_BUDGET,particlesSceneSprites); past it, MCP writes and the panel say so. - What it does not do. Turbulence displaces each particle off its path; it does not advect particles along streams. There is no flocking, no collision and no fluid solver: each of those needs the other particles' history, which a pure function of time does not have.
- In the app. The palette's
particlesrow makes soft dots drifting up, faded in and out,blend: add, with a random seed. Properties › particles edits every param but the over-life curves (write those in the scene).
use (ref) — instance a comp
- use: td-stack # instance the comp named "td-stack"| Field | Type | Default | Notes |
|---|---|---|---|
use | comp name (non-empty) | — required | Non-string → expected a comp name. |
Like any node, a use: takes a delay: — the per-copy time offset: several use: layers
of one comp, each a little later, chase each other (delay).
(The keyword is use; the model kind is ref. A surface binding's use: is the
same idea at the surface root — §3.)
A use: of a framed comp is a w×h box: the comp's content is cropped to its frame, and
the transform holding the use: places and scales the box (§3).
An unknown comp name is a parse error, naming the valid comps: comps.main.0.use — unknown comp "td-stak" — valid comps: main, td-stack. So is a comp that instances
itself — directly, or through other comps' use: / comp-naming clone.of — reported once
at the reference that closes the loop: comp cycle a → b → a — a comp cannot instance itself, directly or through other comps (collectCompRefIssues, model/comps.ts). A
clone's of: naming no comp is an asset path; one that has no file extension either is
rejected as a typo'd comp name.
matte — the matte composite
Masking is a node: a matte cuts its content (what you see) by the coverage of its
matte input (the shape that cuts it — never drawn itself). Full detail — the lowering onto
the fused composite pass, the matte cache, the editor tools: docs/masks.md.
- matte:
content: # required: ONE node — what you see
transform:
- video: assets/plates/N-tile-a.mp4
position: { x: 0, y: 0 }
matte: # required: ONE node — the shape that cuts it
transform:
- path: [ … ] # drawn with the pen, or any visual node
fill: "#ffffff"
position: { x: 800, y: 200 }
mode: alpha # alpha (default) | luma
invert: false # default false
feather: 40 # px in the CONTENT's space, default 0
opacity: 1 # 0..1 matte strength, default 1
range: [0, 1] # scene v18: remap of the matte value, default [0, 1]| Field | Type | Default | Notes |
|---|---|---|---|
content | one node | — required | Any visual node (a transform, group, plate, text, clone, use, an adjustment layer…). A list → expected ONE node — wrap several in a group. |
matte | one node | — required | Any visual node; its coverage cuts the content and it is never drawn. Not audio, not an adjustment layer. |
mode | alpha|luma | alpha | alpha = coverage (a shape's alpha); luma = Rec. 709 luminance over black. Anything else → matte mode must be alpha or luma. |
invert | boolean | false | Keep everything OUTSIDE the matte. |
feather | number ≥ 0 | 0 | Edge softening across ≈ feather px (Gaussian, σ = feather/4), in the content node's px. |
opacity | number 0..1 | 1 | The matte's strength: mix(1, matte, opacity); 0 leaves the content uncut. |
range | [low, high], 0 ≤ low < high ≤ 1 | [0, 1] | Scene v18. A remap of the matte's value FIRST, before the feather, invert and opacity: below low cuts, above high keeps, linear between. Near / far on a depth matte (white = near: [0.5, 1] keeps the nearer half), a choke on a soft matte. Anything else → a matte range is [low, high] with 0 ≤ low < high ≤ 1 …. |
Both inputs and every setting live inside the matte: map (only authored settings
serialize; unknown keys inside the map are kept there). The matte node adds no transform —
each input keeps its own, so the shape sits where you place it — and nothing is referenced
by id. Common fields sit beside the keyword: bypass: true shows the content uncut (the
matte stays hidden, the matte node's own effects and blend off), effects apply to the cut
result, blend composites it. The cut
applies before the content node's own spatial effects (a blur on it softens the edge). A
group as the matte input unions shapes; a matte node (invert: true) as the matte input
subtracts; an adjustment layer as the content is a masked adjustment layer (adjust).
A cut image / video plate costs no extra pass — through its positioning transform too.
A matte version as the matte input (masks.md §8): a clip's person, depth or roto mask is a version of the clip. Cut layer writes the cut on the clip itself, inside its transform, with a second video of the same clip that names the matte version (the "twin"):
- transform:
- matte:
content: { video: assets/singer.mp4 }
matte: { video: assets/singer.mp4, version: depth-1a2b3c4d } # the twin
mode: luma
range: [0.5, 1]
position: { x: 1333, y: 24 }The twin plays its clip's timing (the same src: one offset and loop; the clip's trim when it has none of its own) and lays out at the clip's size, so the mask stays on the picture. Where the matte file is missing or no longer matches the clip, the content draws uncut: a matte version never falls back to the clip. A twin may also be one shape of a group used as the matte (a union). A video naming a matte version outside every matte input is not used: it plays its original. Scene v18.
An image's depth matte is the same shape with an image: matte: { content: { image: <p> }, matte: { image: <p>, effects: [{ depth: {} }] } }, luma. The depth effect (texture stage, no params) swaps the image for its grey depth map (white = near), made once on a Mac and saved at assets/.depth/<name>-<hash>.png (masks.md §8). Where the map is not made, the cut is dropped and the image draws uncut: never cut by the photo. Scene v18 while a depth effect is used.
v1 mask: — scene-format 1 wrote masks as mask: { source: <id>, … } on the cut node,
naming a matte-only node elsewhere. It is still read, and migrated into a matte node at
parse (the next save writes the matte node); a v1 mask that no matte node can express
without changing the picture is a parse error naming the fix (masks.md §7).
adjust — an adjustment layer
No content of its own: its effects, opacity and blend apply to every sibling below
it in the same list (the earlier entries of the comp / group / transform / surface
binding), like an After Effects adjustment layer. Siblings after it draw on top, untouched.
To limit WHERE it applies, make it the content of a matte
node standing in its place.
- video: assets/plates/N-tile-a.mp4 # adjusted
- text: "TOUCHDOWN" # adjusted
- matte: # a masked adjustment layer
content:
adjust: {}
opacity: 0.8 # 0..1 strength, default 1
blend: screen # the result over the unadjusted layers (normal = replace)
effects:
- hue-saturation: { saturation: 25 } # colour ops → one LUT, one pass
- blur: { amount: 6 } # + one pass per spatial effect
matte: { shape: ellipse, size: 2400x1200, fill: "#ffffff" } # where it applies
feather: 60
- image: assets/logo.png # above it: not adjusted| Field | Type | Default | Notes |
|---|---|---|---|
adjust | {} | — required | The keyword. A bare adjust: or adjust: true parse too and re-emit as adjust: {}; keys inside the map are preserved there. Anything else → expected adjust: {} — an adjustment layer has no content of its own …. |
opacity | number 0..1 | 1 | The adjusted result mixed over the unadjusted layers. Non-number → expected an adjustment opacity 0..1; out of range → validation error. Serialized only when set. |
clock | clock block | — | Drives opacity (tracks, drives) and the gate only — any other track → parse error. |
Several adjustment layers stack in list order (the upper one adjusts the lower one's
result). The layers an adjustment covers render isolated, like a precomp: blend modes
among them composite against each other, and an ancestor's hardware mode lands on the
adjusted result instead of reaching in. An adjustment that changes nothing (bypassed,
opacity 0, nothing below it, or no active effect and a normal blend) costs nothing. It is
never a matte input and carries no texture-stage effect (cutout). Full reference — the
math, the GPU path, export strips and the cost per adjustment:
docs/adjustment-layers.md.
node — an extension's node type
A node type an extension registers (api.registerNodeType('badge', …),
docs/mcp-and-extensions.md) is written with the node: keyword,
its own props as siblings, because the parser does not know the registry. The palette's
create row for an extension kind writes the bare - node: badge.
- transform:
- node: badge # the kind the extension registered
size: 120 # its own props, kept on the node as they are (node.size)
fill: "#ff0000"
position: { x: 400, y: 200 }The fields on every node (id, clock, effects, blend, bypass, span, delay) work as
usual; every other key is the extension's (a built-in keyword such as text: beside
node: is one of its props), round-trips verbatim, and is checked by the extension's own
schema when it builds. A scene holding one is v6 (§1).
node: text (a built-in kind) → text is a built-in node — write it with its own keyword (text: …); a missing or non-string kind → expected the node type an extension registered, e.g. node: badge. The scene parses and saves without the extension, but drawing the node
needs it loaded (its builder).
5. Value scalars
The scalar vocabulary (model/values.ts). All are normalised to a canonical
in-memory form and re-serialized to a canonical string, which is what makes the
round-trip a fixed point.
| Scalar | Authored forms | Normalised to | Serializes as | Parser |
|---|---|---|---|---|
| Size | 1920x1080, 1920×1080, { width, height } (both > 0) | { width, height } | WxH | parseSize |
| Duration | 4s, 250ms, bare number (= ms) | milliseconds (number) | Ns for whole seconds, else Nms | parseDuration |
| Velocity | -120px/s, bare number (= px/s) | px/second (number) | Npx/s | parseVelocity |
| Vec2 | 5, [x, y], { x, y } | { x, y } | number if x == y, else { x, y } | coerceVec2 |
| Colour | #rgb/#rgba/#rrggbb/#rrggbbaa, $token | string (verbatim) | as authored | isHexColor / isTokenRef |
| Token | $name, $dotted.name | string ref | as authored | isTokenRef |
Notes:
- Size accepts the ASCII
xor the Unicode×; whitespace around it is tolerated. A bad size →expected WxH; a zero or negative side →expected WxH with a width and height > 0 (got 1920x0). (YAML reads0x10as the hex integer 16, so it isexpected WxH.) - Duration normalises to ms, so
4s,4000ms, and4000are the same value and always re-serialize as4s. A bad duration →expected a duration like 4s or 250ms. - Velocity normalises to px/s and always re-serializes with the
px/sunit. A bad velocity →expected a velocity like -120px/s. - Vec2 collapses a scalar to
{x, y}equal on both axes;scale: 1.05andscale: { x: 1.05, y: 1.05 }are identical, and serialize back to1.05. - Colour is any
#hex(3/4/6/8 digits — 4/8 carry alpha) or a$token; it is stored as-authored and resolved separately (§6). It is checked at parse on every colour field (fill,stroke, stopcolor):#ZZZ, a bare number, or a CSS name likewhite→expected a colour — #rgb, #rgba, #rrggbb, #rrggbbaa, or a $token (got "#ZZZ"). Atext's stillfillmay also benone(no fill, scene v14). Quote hex colours — an unquoted#fffstarts a YAML comment, and the error says so (got nothing — quote a hex colour …).
6. Tokens
A $token is a late-bound reference resolved through a two-level chain
(model/tokens.ts): the scene theme first, then the project
brand.theme, following $-references until a literal (non-$) value is
reached.
fill: $primary
→ scene.theme.primary = $team.gold (scene alias → brand token)
→ brand.theme["team.gold"] = "#FFB81C" (literal — done)- Two brand spellings, one meaning.
brand.thememay use dotted keys (team.gold: …) or nested maps (team: { gold: … }); a lookup tries the exact dotted key first, then walks the nested path. Both resolve. - Where tokens are resolved. Colour-bearing fields —
text.fill,text.stroke,shape.fill,shape.stroke,path.fill,path.stroke,particles.color,gradientstop colours, and#hex/$tokeneffect params — and the keys of an animated colour (a stop's, a shape's, a path's or a text'sfill/strokelist, a text'sletters.clock.tracks.fill, a particle system'soverLife.color). Resolution produces a token-resolved twin of the scene; the authored scene (with$tokensintact) is what's saved. A token key keeps its name and plays the colour it resolves to, so a brand-kit change re-colours the animation too. - Errors. An unresolved token (
unresolved token $x) or a reference cycle (token cycle at $x) raises aTokenErroranchored to the field path. The MCPwrite_sceneguard rejects unresolved tokens too. Fix by defining the token in the scenethemeor the brand kit, or by using a literal#hex.
7. Fit modes
How a surface's artboard (the scene design, or the surface's own design)
maps into its output resolution (size) (Fit, model/scene.ts). Set per surface
(scene binding), falling back to the project surface's fit, then none.
| Fit | Behaviour |
|---|---|
none | No scaling — artboard pixels map 1:1 at the surface origin (default). |
fill | Stretch to the surface on both axes (aspect not preserved). |
cover | Scale to cover the surface, preserving aspect, centred; overflow is cropped. |
contain | Scale to fit inside the surface, preserving aspect, centred; letterboxed. |
tile-x | Scale to the surface height, then repeat horizontally (ribbons/belts). |
tile-y | Scale to the surface width, then repeat vertically. |
Tiles start at the left (tile-x) or top (tile-y) edge, at most 64 of them; the last is
cut at the edge. Everything is clipped to the surface rect (applyFit,
compositor/surface-renderer.ts).
The exact math and the multi-surface compositor are covered in
docs/export-rendering-and-building.md. The authoring rule that matters: pair
tile-x with a band-native per-surface design (§3) so
ribbon marks read at true height.
A master at the artboard's size is an export option, not a surface. A scene authored at the
plate's pixels (design: 3840x2160) on a 1920×1080 surface at fit: fill plays at 1920×1080. For a
3840×2160 file, export with size: design (MCP export_scene / export_scenes / export_reel,
or the ⌘E sheet's size › design): the surface renders at its artboard's size, sharp. It needs
fill, cover or contain at the surface's shape. Never add a surface to project.yaml, or a binding
for a made-up surface, for a master
(export-rendering-and-building.md §6).
8. Clocks, cues, and effects (summary)
Animation is authored in phase space (0..1 around the loop), so loops are
seamless by construction. Full detail — the sampler, easing curves, named-clock
graphs, cues, and triggers — is in docs/clocks-and-animation.md. The essentials
as they appear in scene YAML:
A node's clock. Any node carries a clock block: a period (which should
divide the scene loop), a mode (loop default, or once / pingpong), and
tracks (property → keyframes).
clock:
period: 2s
tracks:
scale: [1, 1.16, 1] # SHORTHAND — values spread evenly over phase 0..1
skewX: # LONG FORM — explicit phase + ease
- { phase: 0.0, value: 0, ease: snap }
- { phase: 0.08, value: -12 }
- { phase: 1.0, value: 0 }-
Animatable props:
x,y,scale,scaleX,scaleY,rotate,skewX,skewY,opacity(scaleis uniform and multipliesscaleX/scaleY). An unknown property is aParseError. -
xandytracks add to the staticposition. A key of0means "atposition", so key how far the layer moves, not where it lands:- transform: [ { text: "ROW" } ] position: { x: 800, y: 540 } # where it rests clock: { tracks: { x: [0, 400, 0] } } # x 800 → 1200 → 800The place written into the track (
x: [800, 1200, 800]) draws the layer at 1600 → 2000, twice as far.rotate,skewXandskewYtracks add to the static values too;scale,scaleX,scaleYandopacitytracks multiply them (clocks-and-animation.md §4). -
Shorthand
[a, b, a]distributes keyframes at even phases with the smooth default ease (cubic-bezier(.4,0,.2,1)) on every non-terminal keyframe. -
ease(the segment leaving a key, to the next one) is one of:- a cubic preset:
linear,ease,ease-in,ease-out,ease-in-out,smooth,snap,overshoot,expo-in,expo-out,expo-in-out,back-in,back-in-out; - a custom cubic:
cubic-bezier(x1,y1,x2,y2),[x1,y1,x2,y2]or{x1,y1,x2,y2}—x1/x2in0..1(they are time),y1/y2free (overshoot); - a step:
hold(keep the value until the next key) orsteps(n)—n(a whole number ≥ 1) equal jumps across the segment, each at the end of its step;steps(n, start)jumps at the start (steps(n, end)is the default spelled out;steps(1)writes back ashold); - a function:
elastic,bounceorspring, each settling onto the next key. Two take settings:spring(bounce), bounce from 0 (never passes the target) to 0.95 (plainspringis 0.5), andelastic(amplitude, period), amplitude 1 or more and period above 0 up to 1 of the segment (plainelasticis 1, 0.3).
The same values work on animated effect params and gradient attributes (a colour key included). The gate takes no ease. None of these needs a newer
schemaVersion: an older Starlight refuses a scene that uses one (unknown ease "hold") rather than misreading it. (clocks-and-animation.md §6.) Omitperiodto inherit the scene loop. - a cubic preset:
-
A long-form
phaseis a number in0..1, like a cue phase. -
Per-frame samples (scene v12), for tracking data and baked motion: a track can be
{ fps, start, values }instead of a key list, one value per frame atfps, the first on framestartof the clock (default 0), straight lines between;nullis a frame with no sample. The parser places them on the clock's period as linear keys (the first value holds beforestart, the last after the end), and the serializer writes them back in this form while the keys still sit one per frame with straight segments (clocks-and-animation.md §5). Clock tracks only: on an effect param or a gradient attribute it is an error. MCPimport_trackandtrack_regionwrite them from tracking data (clocks-and-animation.md §5).clock: tracks: x: { fps: 29.97, start: 187, values: [1640, 1620, 1580, 1520, 1440, null, 1220] }
Named clocks (scene.clocks). Shared timing sources — { period?, mode? }
(plus optional cues, trigger, and the beat-clock fields offset: — a duration, where
phase 0 lands — and unwrapped: true — sample the song's unwrapped time, not the loop)
with no tracks. A node references one with clock: { use: <name>, tracks: {…} },
drawing period + mode from it. A period can be a concrete duration or a derived
ratio scene/N (the scene loop ÷ N; scene alone = ÷1). Carrying a local
period/mode beside use: is a validation error, and an unknown use: is
rejected naming the valid clocks.
clocks:
heartbeat: { period: 2s, mode: loop }
quarter: { period: scene/4 } # derived: scene loop ÷ 4
comps:
main:
- text: "A"
clock: { use: heartbeat, tracks: { scale: [1, 1.1, 1] } }Cues + triggers. A cue is a named phase point on a clock's loop. Named clocks
carry their own cues: (name → phase 0..1); the scene clock's cues live at
scene.cues (the scene loop isn't in the clocks: map). A named clock may carry
a trigger: { from, cue } — it starts when clock from reaches cue cue
(from is a named clock or the literal scene). Trigger chains compose and wrap mod
the scene loop; a chain that loops back (a → b → a) is a parse error. A triggered clock
is loop-perfect only when it starts on a whole cycle of its period
(docs/clocks-and-animation.md §11).
cues: # cues on the scene clock (the loop)
impact: 0.25
clocks:
flash:
period: 1s
trigger: { from: scene, cue: impact } # starts at the scene's "impact" cueEffects (effects). A stack of GPU effects on a node, authored as a list of
single-key maps — { <effectName>: { …params } }. A param is a const (a
number, a #hex/$token colour, or a choice string such as feather's
curve: linear) or an animated keyframe list (animatable params only). Animated
params ride the host node's clock (its period/mode, or the named clock it uses,
trigger offset included; the scene loop when the node has none), so they move with the
node's transform keys; a reserved clock: key on the effect, { period?, mode? }, gives
the effect its own clock instead (clocks-and-animation.md §4).
The properties panel's ◇ chip on each animatable param writes exactly this form.
- text: "GOAL"
clock: { period: 2s, tracks: { scale: [1, 1.16, 1] } }
effects:
- glow:
color: $primary
radius: 7
intensity: [0.12, 0.6, 0.15] # animated — rides the node's 2s clock
- chroma-shift: { angle: 0, offset: [0, 3, 0], clock: { period: 1s } } # its own clock
- scanlines: { gap: 3 } # an extension effect (see below)Each entry must have exactly one key (the effect name); zero or multiple keys is
a ParseError. Its value must be a map — - cutout: {} for an effect with no params (a
bare - cutout: is effect "cutout" params must be a map). An effect name the live
registry does not know is kept on save and builds nothing when rendered (it may be an
extension that is not loaded or not trusted yet); only the MCP writers reject it. Effect names (including extension effects) and which params are
animatable come from the MCP get_project catalog — see
docs/mcp-and-extensions.md. The parser does not know the registry, but MCP
write_scene / create_scene / compose do: an unknown effect, an unknown or
non-animatable param, a choice outside its options, or a wrong-typed value is rejected
against the live catalog (§11).
The built-in effects and their params are tabled in
docs/mcp-and-extensions.md → Built-in effects
(e.g. - feather: { left: 800 } — edge alpha ramps for overlapping AI tiles).
Effect modules (effects/<name>/ in the project, effects.md) are used by their
name, exactly like a built-in: - ripple: { amount: 8, scale: [4, 12, 4] }. No new
schemaVersion: the stack already takes any registered name. Their params map to the scene
like this: a number, a whole number or a choice as usual; an on/off as 0 or 1; a colour as a
#hex or a $token; a point or vector as one number per part (center → centerX,
centerY, and Z, W for 3 and 4 parts), each one able to animate; a curve as text,
"0,0 0.5,0.8 1,1"; an image or clip input as an asset path (dust: assets/dust.png). A
module that is not loaded (a broken rule, a compile error) is kept on save and draws nothing,
like any unknown effect.
Colour effects (exposure, brightness-contrast, hue-saturation, levels,
curves, color-balance, temperature-tint, invert, lut) are point ops. All of a
node's colour effects fuse, in stack order, into ONE baked LUT that is applied before
the node's spatial effects, wherever the colour entries sit in the list. Full reference:
color.md. Two param shapes are specific to them:
effects:
- curves: { master: "0,0 64,52 192,206 255,255", red: "0,0 128,140 255,255" } # "x,y …" in 0..255
- levels: { inBlack: 16, inWhite: 235, gamma: 1.1, redGamma: 0.95 } # 0..255 units
- lut: { file: assets/luts/film.cube, strength: 0.8 } # a .cube asset pathA curve is a string of x,y control points (0..255, at least two, separated by spaces;
; and newlines also work), so it is not animatable. Every numeric colour param is
animatable. write_scene rejects a malformed curve, an unknown colour param and an
invalid choice (invert.channel), naming the param. A lut file counts as an asset
reference: it blocks rename/delete of the .cube, and Replace rewrites it.
9. IDs and the round-trip contract
Every node has a stable string id, but scenes almost never write one. An id
is auto-derived on parse as a pure function of the node's kind and its
positional path in the document (comp/surface name + child indices), via a
tiny FNV-1a hash (autoNodeId, model/ids.ts). Because the path survives
serialize unchanged, re-parsing regenerates identical ids — so the round-trip is
a fixed point without writing ids to disk.
The serializer recomputes each node's auto id and omits id when it matches.
Therefore:
- Omit
idalmost always — clean YAML, ids regenerated deterministically. - Write an explicit
idonly when you need identity to survive structural edits (reordering, re-nesting), because a positional auto id changes when a node's path changes. An explicitidoverrides the auto id and is written back on serialize.
This is why the demo scenes contain no id: keys: they are all auto-derived.
10. Forward tolerance
Unknown keys are preserved, not rejected. At every level — project, scene,
surface binding, node, and the inside of a clone or particles map — any key the parser
doesn't recognise is collected onto an unknown bag and re-emitted verbatim on
serialize. This lets a newer document survive an older reader (and a stray key
like a position: on a non-transform node is silently kept rather than crashing
the parse — though it has no effect). The clock block is a known key lowered
to the typed model, not an unknown-bag passenger. The scene's stages: map rides the
bag on purpose: its accessor (src/engine/stage3d/scene-stages.ts) is the only code that
knows where stages live, and only the write paths validate it (§3).
11. Errors
Parse and token errors are friendly and path-anchored (model/errors.ts).
The format is:
scenes/03-touchdown.yaml: surfaces.ribbon-main.size — expected WxHi.e. <source>: <dotted.path> — <message>. Multiple issues are listed together.
ParseError covers structural/schema problems; TokenError covers unresolved
tokens; the low-level scalar parsers throw a path-free ValueError that the
caller re-anchors.
What triggers a validation error:
| Trigger | Message (shape) |
|---|---|
| No node keyword | expected a node keyword (text, image, …) |
| Multiple node keywords | ambiguous node — multiple keywords present: … |
Bad shape: value | expected rect, ellipse, or line |
Bad gradient: value | expected linear or radial |
Bad path: value (not a list) | expected a list of subpaths |
| Malformed subpath / vertex / point | expected a subpath { vertices, closed } / expected a list of vertices / expected a vertex { p, in, out } / expected a point [x, y] |
Non-string image:/video: src | expected an asset path |
| Bad scalar (size/duration/velocity/vec2) | expected WxH / expected a duration like 4s or 250ms / … |
| A size with a zero or negative side (surface, design, shape, gradient, project surface) | expected WxH with a width and height > 0 (got <w>x<h>) |
A colour that is not #hex / $token (fill, stroke, stop color) | expected a colour — #rgb, #rgba, #rrggbb, #rrggbbaa, or a $token (got "<x>"); on a shape's, a path's or a text's fill (and a shape's or a path's stroke), which may be a list, … a $token, or a list of colours to animate it (got "<x>"); a key in a colour list → "fill" keyframe <k> needs a colour — #rgb, #rgba, #rrggbb, #rrggbbaa or a $token (got "<x>") (an unquoted #… → got nothing — quote a hex colour …) |
A gradient stop offset out of range / not a number | stop offset <n> is out of range 0..1 / expected a stop offset 0..1 (got "<x>") |
A bad gradient keyframe list (scene v4) — a colour key that is neither a hex nor a $token, a key out of range, a malformed center / size | stops.<i>.color — … keyframe <k> needs a colour — #rgb, #rgba, #rrggbb, #rrggbbaa or a $token (got "<x>") / stops.<i>.offset — keyframe <k>: stop offset <n> is out of range 0..1 / radius <n> must be 0 or more / size.width — keyframe <k>: width <n> must be more than 0 / center — expected [x, y], { x, y } or a number …, or { x: [..], y: [..] } to animate an axis |
A clone number that is not a number (count, gap, rows, cols, gapY, radius) | expected a whole number ≥ 0 (got "16") / expected a number (got "<x>") / expected a number ≥ 0 (got <n>) |
A surface / node use: naming no comp | unknown comp "<x>" — valid comps: … |
A clone.of that is neither a comp nor an asset path | "<x>" names no comp and is not an asset path (an asset path has a file extension, e.g. assets/logo.svg) — valid comps: … |
| A comp that instances itself (directly or through other comps) | comp "<x>" instances itself — a comp cannot contain itself / comp cycle a → b → a — a comp cannot instance itself, directly or through other comps |
A long-form keyframe phase out of range / not a number (tracks, gate, animated effect params) | "track <prop>" keyframe <i> phase <n> is out of range 0..1 / … keyframe <i> needs a numeric phase (0..1) |
An ease x1/x2 outside 0..1, or a non-number control point | ease x1 <n> is out of range 0..1 — x control points are time (y1/y2 may overshoot) / ease x1 must be a number (got NaN) |
An unknown ease, or a bad steps() | unknown ease "<x>" (a name like smooth or hold, steps(n), or cubic-bezier(...)) / steps(<n>) needs a whole number of steps ≥ 1 / steps(<n>, <x>) jumps at start or end |
| Unknown animatable property in a track | unknown animatable property "<x>" |
| A bad per-frame track (scene v12) | ….clock — "track x" needs fps: the frames per second of its values, a number above 0 up to 1000 (got null) / "track x" start is the frame of the first value: a whole number, 0 or more (got -1) / "track x" needs values: a list with one number per frame, e.g. values: [0, 2.5, 5] / "track x" value 3 must be a number, or null for a frame with no sample (got "a") / "track x" needs at least one number in values / "track x" — a per-frame track is { fps, start, values }; "ease" is not one of its keys |
| Per-frame values past the end of their clock | ….clock.tracks.x — 600 values from frame 0 at 29.97 fps run to frame 599 (19.99 s), past the end of its clock: 18.42 s, whose last frame is 552. Drop the last 47 values, or make the clock longer. |
| Per-frame samples on an effect param or a gradient attribute | "<label>" — per-frame samples ({ fps, values }) work on clock tracks only (x, y, scale, scaleX, scaleY, rotate, skewX, skewY, opacity); write keys here |
clock.use naming no scene clock | unknown named clock "<x>" — valid clocks: … |
use: beside a local period/mode | a clock with use: … takes its period and mode from that named clock — remove the local period/mode |
Bad mode | mode must be once, loop, or pingpong |
A trigger's unknown from clock | unknown trigger source "<x>" — a named clock or "scene" |
A trigger's missing cue on from | clock "<from>" has no cue "<cue>" |
| A clock triggering its own cue | clock "<x>" cannot trigger off its own cue |
| A multi-clock trigger cycle (once per cycle) | trigger cycle a → b → a — a clock cannot start off a chain that leads back to itself |
A matte: that is not a map / misses an input / takes a list | expected { content: <node>, matte: <node>, … } / ….matte.content — expected the node to cut — content: { video: … } / ….matte.matte — expected the node whose shape cuts the content — matte: { path: … } / expected ONE node — wrap several in a group: { group: [ … ] } |
| Audio as a matte's content; audio or an adjustment layer as its matte input | the content is an audio node — a matte cuts pixels, and audio has none / the matte input "<x>" is an audio node — it has no pixels to cut with / the matte input "<x>" is an adjustment layer — it has no pixels of its own … |
| A bad matte setting | matte mode must be alpha or luma / expected true or false / expected a feather in px (a number ≥ 0) / expected a matte opacity 0..1 / a matte range is [low, high] with 0 ≤ low < high ≤ 1 … |
A v1 mask: no matte node can express | mask source "<x>" contains "<n>" or sits inside it — … / … lives in another comp or surface than "<n>" — … / … sits inside "<t>", whose clock the cut node does not share — … / "<n>" has spatial effects inside the wrapper "<w>" — … / mask chain from "<n>" loops back to itself … / mask source "<x>" names no node in the scene (masks.md §7) |
effects / blend / clock / span on a matte node cutting an adjustment layer | a matte node cutting an adjustment layer carries no <field> of its own — put it on the adjustment layer (its content) |
| A scene newer than this build | schemaVersion — this scene is schemaVersion <n>, written by a newer Starlight — this build reads up to 18; update Starlight to open it |
| A bad particles value (scene v17) | ….particles — expected { rate, life, emitter, … } — a particle system's settings (got 7) / ….particles.rate — expected births per second, a number above 0 (got "fast") / ….particles.life — expected a lifetime above 0, like 2s or 250ms / ….particles.speedRandom — expected a fraction 0..1, 0.3 = ±30 % (got 30) / ….particles.emitter.shape — expected point, line, rect or ellipse (got "star") / ….particles.emitter.radius — not an emitter key (shape, size, length, from) / ….particles.angle — expected degrees (0 = right, 90 = down, -90 = up) or outward / ….particles.spread — expected the launch cone's width in degrees, 0..360 / ….particles.gravity — expected { x, y } in px/s², e.g. { x: 0, y: 300 } pulls down / ….particles.turbulence.evolve — expected a whole number of field cycles per loop, 0 or more (got 0.5) / ….particles.overLife.opacity — keyframe 1: opacity 1.4 is out of range 0..1 / ….particles.trail.samples — expected a whole number 1..16 / ….particles.max — expected a sprite budget, a whole number 1..20000; a particles.of that names no comp and has no file extension gets the clone's message |
| A bad text layout value (scene v13) | ….wrap — expected the width lines wrap at, in px: a number above 0, like 820 (got 0) / ….lineHeight — expected the distance between baselines as a multiple of size: a number above 0, like 1.25 (got -1) / ….maxLines — expected a whole number of lines, 1 or more (got 1.5) / ….overflow — expected ellipsis or clip (got "fade") / ….anchorY — expected top or baseline (got "middle") / ….markup — expected true or false (got "yes") |
Content on an adjust: keyword | expected adjust: {} — an adjustment layer has no content of its own; its effects, opacity and blend apply to the layers below it (got …) |
A non-number adjustment opacity | expected an adjustment opacity 0..1 (got "<x>") |
An adjustment layer's clock driving anything but opacity | an adjustment layer's clock drives opacity only (and its gate) — "<prop>" has nothing to move; animate its matte to move the adjusted area |
Malformed v1 mask: | expected the id of the matte node / matte mode must be alpha or luma / expected true or false / expected a feather in px (a number ≥ 0) |
Malformed delay: (on a node or a surface binding) | comps.main.0.delay — expected a duration like 4s or 250ms |
Malformed span: (not a pair of durations) | expected [in, out] — two durations like [1s, 3s] (a bad member → span.<i> — expected a duration like 4s or 250ms) |
A span that starts before 0 / ends at or before its in | span in -500ms is before 0 — scene time starts at 0 (a bare -500) / span out 1s must be after its in 2s |
A video trim that is not two times / starts before 0 / ends at or before its in (scene v9) | expected [in, out] — two times in the source like [5s, 10s] / trim in -1s is before 0 — the source starts at 0 / trim out 2s must be after its in 5s |
| Cue phase out of range | cue "<x>" phase <n> is out of range 0..1 |
A malformed markers list (the scene's or a video's) | markers — expected a list of markers — a duration, or { at, label, color } / marker <i>: expected a time like 1.5s or 250ms / marker <i>: -1s is before 0 / marker <i>: needs an at — { at: 1.5s } / marker <i>: expected a colour — one of red, orange, yellow, green, blue, purple |
A graphColors value, or a note's color, that is not one of the six | graphColors.<key> — expected a graph colour — one of red, orange, yellow, green, blue, purple (got "<x>") / graphNotes.<i>.color — expected a graph colour — one of … |
A malformed graphNotes entry | expected a list of notes { text, x, y, w, h } / graphNotes.<i>.<x|y|w|h> — expected a number (graph px) / … — expected a size > 0 (graph px) / graphNotes.<i>.text — expected the note text |
Effect entry not a single { name: {…} } | effects[i] must have exactly one effect name … |
Schema violation (e.g. opacity > 1, fps > 240, a non-integer count) | zod message at the field path |
MCP writes only (write_scene, create_scene, compose plans — checked against the
live registry catalog after parse; mcp-and-extensions.md):
| Trigger | Message (shape) |
|---|---|
| An effect nobody registered (a typo, an extension that is not loaded) | comps.main.0.effects.<i> — unknown effect "<x>" — valid effects: … (before the app has synced its registry: … (the app has not synced its live registry yet, so extension effects are not known — retry shortly)) |
| A param the effect does not declare | ….effects.<i>.<effect>.<param> — effect "<e>": unknown param "<p>" — valid params: … |
| Animating a non-animatable param | effect "<e>": param "<p>" is not animatable — animatable: … |
| A choice param outside its options | effect "<e>": param "<p>" must be one of a, b (got "<x>") |
| A wrong-typed constant | effect "<e>": param "<p>" expects a number (got "8") / expects a string (got 7) / expects a colour — #rgb, … or a $token (got "white") |
| A node kind the registry lacks | the "<keyword>" node type is not registered in this app — registered: … |
A texture-stage effect (cutout) on an adjustment layer | ….effects.<i> — effect "cutout" replaces an image's source pixels — an adjustment layer has none (put it on the image node) |
A broken stage (stages:; stage_write gives the same messages) | stages.<id>.target — unknown surface "<x>" — valid surfaces: … / stages.<id>.frame — expected "surface" or W:H like 21:9 / stages.<id>.items.<i>.size.y — expected a number > 0 / stages.<id>.items.<i>.id — duplicate item id "<x>" / stages.<id>.camera.focal — expected a focal length in mm from 8 to 1200 / stages.<id> — expected a stage id like hero-walk (lowercase letters, digits and -, up to 48) (stages.md) |
The clock.use reference check, the trigger from/cue/cycle check, the matte-input
check and the comp-reference check (use: / clone.of existence + cycles) run after
schema validation, so a typo in a clock name never silently retimes a node to the scene
loop, a matte never silently fails to cut, and a typo in a comp name never silently blanks
a surface — each is a hard, named error at parse. (The v1 mask migration runs before schema
validation, so its errors come first.)