Scene API

scene(), the s.* builders for text, code, shapes, images, focus helpers, links, and transitions.

This page lists the builders available on a scene. Animation, style, and focus methods that you chain onto the returned nodes are documented in Code & node animations.

`scene(name, frames)`

Declare a scene and its duration. Use raw frames for precision, or time helpers for readability.

let s = scene("Introduction", sec(6));
let quick = scene("Title card", ms(2500));

ms(n) converts milliseconds to frames. sec(n), secs(n), seconds(n), and s(n) convert seconds to frames using [output].fps from codescene.toml.

Timeline markers

Use markers when a scene has more than a couple of timed actions. Markers keep the script readable because animation calls can refer to named moments instead of repeating raw offsets.

mark("code_in", sec(1));
mark("focus_line", after("code_in", sec(1.4)));

code.fade_in(at("code_in"), ms(500));
code.typewriter(after("code_in", ms(200)), sec(2.2));
code.spotlight(2, 0.6, at("focus_line"), ms(650));

Function	Description
`mark(name, time)`	Store a named timeline position and return its frame.
`at(name)`	Read a named timeline position.
`after(name, offset)`	Return a marker plus an offset.
`after(time, offset)`	Return one time value plus another.

Text

// text(content, x, y)
let title = s.text("Hello, CineCode", 96, 64);

Code

// code(source, lang, [theme], x, y)
let a = s.code(read("src/main.rs"), "rust", 96, 160);
let b = s.code(read("src/main.rs"), "rust", "Solarized (dark)", 96, 160);

source — the code text (use read("path") to load a file)
lang — a language id (see Languages)
theme — optional code highlight theme (see Themes)
x, y — top-left position

read("src/main.rs") returns the literal contents of that file as a string — the script never rewrites your code, it only loads and films it. You can also pass an inline string, e.g. s.code("let x = 1;", "rust", 96, 160). See How it works — three ingredients for the full picture.

Shapes

s.panel(x, y, w, h, r, g, b);
s.rect(x, y, w, h);
s.square(x, y, size);
s.circle(x, y, radius);
s.ellipse(x, y, rx, ry);
s.line(x1, y1, x2, y2);
s.polygon([[x, y], ...]);
s.path([[x, y], ...]);

Images

// image(path, x, y, [w, h])
s.image("assets/diagram.png", 700, 160, 420, 300);

Focus helpers

These act on a code/text node:

// underline(node, line, start, dur)
s.underline(code, 3, sec(3), ms(667));

// surround(node, from_line, to_line, start, dur)
s.surround(code, 1, 4, sec(3), ms(800));

// point_at(node, line, from_x, from_y, start, dur)
s.point_at(code, 5, 760, 320, sec(4), ms(600));

// variable_update(node, line, label, start, dur) — a value badge beside a line
s.variable_update(code, 4, "acc = 6", sec(4), ms(250));

Diff (added / removed lines)

Mark a code change like a review — a tinted band, a colored gutter stripe, and a +/- sign per line (green = added, red = removed):

// diff_add / diff_remove(node, line, start, dur) — one changed line
s.diff_add(code, 3, sec(4), ms(450));
s.diff_remove(code, 2, sec(4), ms(450));

// diff(node, added_lines, removed_lines, start, dur) — a whole patch at once
s.diff(code, [3], [2], sec(4), ms(450));

// Compute and present a line diff from two code nodes.
s.diff_auto(before, after, sec(4), ms(450));
s.before_after(before, after, sec(5), ms(500));
s.split_diff(before, after, sec(6), ms(600));

See Diff & data flow for the complete API and the distinction between visual annotations and source edits.

Data flow & token transforms

Operate on individual tokens (matched by substring) to show how a value flows or how a refactor reshapes the code:

// token_trace(node, from_line, from_token, to_line, to_token, start, dur)
// — an arrow from one token to another, tracing a value's data flow
s.token_trace(code, 1, "total", 3, "total", sec(4), ms(450));

// move_token(node, line, token, to_x, to_y, start, dur)
// — a ghost copy glides out, leaving the slot empty (extract / hoist)
s.move_token(code, 1, "total", 900, 300, sec(4), ms(650));

// morph_token(node, line, token, new_text, start, dur)
// — an in-place odometer swap (rename). A visual annotation; use `retype`
//   for a real code edit.
s.morph_token(code, 2, "vat", "tax", sec(4), ms(500));

diff, token_trace, move_token, and morph_token are visual annotations drawn over the code — the code node's text is unchanged. For edits that change the source itself, use retype / backspace (see Code & node animations).

Morph

// morph(old_node, new_node, style, start, dur)
s.morph(a, b, "fade", 60, 40);

Link code to a simulation

// link(node, line, sim, start, dur)
s.link(code, 9, grid, 100, 90);

See Bind code to simulations.

Simulations

s.terrain(x, y, w, h);    s.noise(x, y, w, h);
s.pathfind(x, y, w, h);
s.particles(from_x, from_y, to_x, to_y);
s.graph(x, y, w, h);
s.life(x, y, w, h);       s.automata(x, y, w, h);
s.boids(x, y, w, h);

Each returns a simulation node configured with a fluent chain — see Simulations.

Camera

let cam = s.camera();

See Camera.

Layout and groups

Use group, row, column, grid, and stack to position and animate multiple nodes as one unit. See Layout & groups.

Transition

// transition(kind, frames, [r, g, b])
s.transition("crossfade", ms(600));
s.transition("fade_color", ms(800), 0.03, 0.04, 0.08);

See Transitions.

On this page