Skip to content

An AI skill that turns books into animated, narrated, interactive web experiences

feat(engine): add clock-driven camera

yzr8331398c0051
diff --git a/.claude/skills/papermorph/assets/engine/engine.js b/.claude/skills/papermorph/assets/engine/engine.js
index 568d6bd..3e33e7b 100644
--- a/.claude/skills/papermorph/assets/engine/engine.js
+++ b/.claude/skills/papermorph/assets/engine/engine.js
@@ -827,6 +827,74 @@ function evalTo(t, list = TW) {
}
}
+/* ---------- world clock and camera ---------- */
+const soft = p => (1 - Math.cos(Math.PI * p)) / 2; // gentle in-out, for camera moves
+// Continuous motion: f(t) runs on every frame of the beat with t in seconds from its start (0..D).
+// Keep f a pure function of t, so pause, seek and ?beat=N&t=S show the same frame.
+const clockRun = (f, D) => { f(0); prog(q => f(q * D), 0, D, lin); };
+// A camera looks at a world group through the stage (or a box, for split screen and picture-in-picture).
+// The view {x, y, z, r} is the world point at the centre, the zoom (screen px per world px) and the roll in degrees.
+// Moves are keyed on the beat clock: to(view, t0, dur, ease) blends each given key from its value at t0; a key may be a
+// function of t (follow). Unspecified keys keep following the earlier moves. dur 0 is a hard cut.
+let camN = 0;
+function camera(p, D, { box, x = 800, y = 450, z, r = 0, bg = COL.board } = {}) {
+ const [bx, by, bw, bh] = box || [0, 0, 1600, 900];
+ const el = G(p, { x: bx + bw / 2, y: by + bh / 2 });
+ let hold = el;
+ if (box) {
+ const id = 'cam' + (++camN);
+ mk('rect', { x: -bw / 2, y: -bh / 2, width: bw, height: bh, rx: 18 }, mk('clipPath', { id }, mk('defs', {}, el)));
+ hold = G(el); hold.setAttribute('clip-path', `url(#${id})`);
+ mk('rect', { x: -bw / 2, y: -bh / 2, width: bw, height: bh, fill: bg }, hold);
+ }
+ const view = mk('g', {}, hold), world = G(view);
+ if (box) mk('rect', { x: -bw / 2, y: -bh / 2, width: bw, height: bh, rx: 18, fill: 'none', stroke: COL.faint, 'stroke-width': 2 }, el);
+ const v0 = { x, y, z: z ?? (box ? Math.min(bw / 1600, bh / 900) : 1), r };
+ const ops = [], shakes = [], layers = [];
+ const val = (v, t) => typeof v === 'function' ? v(t) : v;
+ // The view at time t after the first n moves; each move remembers the view it starts from.
+ function at(t, n = ops.length) {
+ const s = { ...v0 };
+ for (let i = 0; i < n && ops[i].t0 <= t; i++) {
+ const o = ops[i], a = o.from || (o.from = at(o.t0, i));
+ const q = o.dur ? o.ease(Math.min(1, (t - o.t0) / o.dur)) : 1, b = {};
+ for (const k in o.v) b[k] = val(o.v[k], t);
+ if ('z' in b) s.z = a.z * (b.z / a.z) ** q; // even zoom speed
+ // While zooming, x/y move so that one world point stays put on screen (when start and end allow it).
+ const u = 'z' in b && Math.abs(b.z - a.z) > 1e-6 * a.z ? (1 / s.z - 1 / a.z) / (1 / b.z - 1 / a.z) : q;
+ for (const k of ['x', 'y']) if (k in b) s[k] = a[k] + (b[k] - a[k]) * u;
+ if ('r' in b) s.r = a.r + (b.r - a.r) * q;
+ }
+ return s;
+ }
+ function apply(t) {
+ const s = at(t);
+ let sx = 0, sy = 0;
+ for (const k of shakes) if (t > k.t0 && t < k.t0 + k.dur) {
+ const e = k.amp * Math.min(1, (t - k.t0) / .3, (k.t0 + k.dur - t) / .3), w = 2 * Math.PI * k.hz * t;
+ sx += e * (Math.sin(w) + .5 * Math.sin(2.3 * w + 1)) / 1.5; sy += e * (Math.sin(1.7 * w + 2) + .5 * Math.sin(3.1 * w)) / 1.5;
+ }
+ view.setAttribute('transform', `translate(${sx} ${sy}) rotate(${-s.r}) scale(${s.z}) translate(${-s.x} ${-s.y})`);
+ const dx = s.x - v0.x, dy = s.y - v0.y;
+ for (const L of layers) put(L.g, { x: L.wrap ? dx - ((L.k * dx) % L.wrap + L.wrap) % L.wrap : (1 - L.k) * dx, y: (1 - L.k) * dy });
+ }
+ const cam = { el, world, at,
+ to(v, t0, dur = 1, ease = soft) { ops.push({ v, t0, dur, ease }); ops.sort((a, b) => a.t0 - b.t0); ops.forEach(o => delete o.from); return cam; },
+ cut: (v, t0) => cam.to(v, t0, 0),
+ shake(amp, t0, dur, hz = 7) { shakes.push({ amp, t0, dur, hz }); return cam; },
+ // Parallax layer: k < 1 is far (moves slower than the camera), k > 1 near. With wrap = W the layer's content
+ // repeats every W world px: draw one period plus the widest view, and the layer never runs out.
+ layer(k = 1, wrap) { const g = G(world); layers.push({ g, k, wrap }); return g; },
+ // Screen position of a world point at time t (k = 1 layers, no shake): for labels that track an object.
+ screen(wx, wy, t) {
+ const s = at(t), a = -s.r * Math.PI / 180, ux = (wx - s.x) * s.z, uy = (wy - s.y) * s.z;
+ return [bx + bw / 2 + ux * Math.cos(a) - uy * Math.sin(a), by + bh / 2 + ux * Math.sin(a) + uy * Math.cos(a)];
+ },
+ };
+ clockRun(apply, D);
+ return cam;
+}
+
/* ---------- scene ---------- */
const scene = document.getElementById('scene');
const S = {};
diff --git a/.claude/skills/papermorph/references/engine.md b/.claude/skills/papermorph/references/engine.md
index 71a4950..07b798e 100644
--- a/.claude/skills/papermorph/references/engine.md
+++ b/.claude/skills/papermorph/references/engine.md
@@ -42,12 +42,25 @@ Topic helpers already in the engine: number lines (`numberLine`, `X(v)`, `Y0`, `
```
- `m('name', offset)` is the start time of the word after `[[name]]`; `D` is the clip's length. Use marks for actions tied to speech; scene entrances and transitions can use fixed offsets.
-- Tweens: `tw(e, to, t0, dur, ease)`, `prog(q => …, t0, dur, ease)` for custom motion (arcs, counters, live redraws), `show`, `hide`, `draw`, `pop`, `pulse`, `stream`. Eases: `io`, `out`, `back`, `lin`.
+- Tweens: `tw(e, to, t0, dur, ease)`, `prog(q => …, t0, dur, ease)` for custom motion (arcs, counters, live redraws), `show`, `hide`, `draw`, `pop`, `pulse`, `stream`. Eases: `io`, `out`, `back`, `lin`, `soft`. Continuous motion and cameras: see below.
- A lesson beat ends after its narration and its last tween, then the next starts; an `ask` beat waits for `done()`.
- **Opening lead-in**: if a beat calls `panel()` (before 0.5 s) and nothing appears within 0.8 s, `runBeat` moves the opening group (every tween starting within 1.2 s of the first reveal) to start at 0.4 s. Opt out with `{ lead: false }` in the beat's fourth slot.
- **Seeking replays**: jumping to beat N rebuilds the scene and runs earlier beats instantly. Make `run` deterministic: create objects and schedule tweens through the timeline, with inputs from chapter data and replayed `S` state. Create interactions inside `ask`; use `fx`/`fxp` for answer effects.
- Constants used in a `BEATS` literal are evaluated when it is defined, so define them above `BEATS`. Data used only inside an `ask` closure may sit below.
+## World clock and camera
+
+For continuous motion (vehicles, orbits, rolling, scrolling scenery) and camera work. Everything is a pure function of the beat time, so pause, seek and `?beat=N&t=S` show the same frame.
+
+- `clockRun(f, D)` calls `f(t)` on every frame of the beat, `t` in seconds from its start (0..D). Write positions as functions of `t` (`x = x0 + v * t`) and share them between objects and the camera; never accumulate per-frame state.
+- `const cam = camera(parent, D, { x, y, z, r, box, bg })` makes a view onto a world group. Draw in `cam.world` in world coordinates. The view `{x, y}` is the world point shown at the centre, `z` the zoom (screen px per world px), `r` the roll in degrees. Defaults: full stage, `(800, 450)`, `z` 1 (identity, so stage coordinates still work). With `box: [x, y, w, h]` the camera draws in a framed, clipped box with background `bg` (split screen, picture-in-picture); its default zoom fits the 1600 × 900 world into the box. `cam.el` is the camera's group (fade, pop or hide it; it scales about the box centre).
+- Moves, all on the beat clock: `cam.to({x, y, z, r}, t0, dur = 1, ease = soft)` blends only the keys given, from wherever the camera is at `t0`; `cam.cut(view, t0)` is a hard cut (`dur` 0); `cam.shake(amp, t0, dur, hz = 7)` is a subtle, repeatable shake (fades in and out over 0.3 s). Any key may be a function of `t`: that is a follow shot (`cam.to({ x: t => carX(t) }, 2, 1.5)` locks on over 1.5 s; `r: t => spin(t)` rolls with a rotating object). Zoom changes evenly (log scale) and keeps one world point fixed when start and end allow it.
+- Parallax: `cam.layer(k, wrap)` returns a group inside the world that moves at `k` × the camera's pan (`k` < 1 far, > 1 near; zoom and roll are not scaled per layer). With `wrap = W` the layer's content repeats every `W` world px: draw one period plus the widest view, and the camera can pan any distance. Keep repeating details (dashes, tiles, trees) on a period that divides `W`, and move followed objects by multiples of `W` when they loop, so the loop is invisible.
+- `cam.at(t)` returns the view at `t`; `cam.screen(wx, wy, t)` the screen position of a world point (no shake), for screen-space labels that track an object.
+- Split screen or picture-in-picture: two cameras with boxes, each with its own copy of the world built by the same function and driven by the same clock functions. Cross-fade between shots by fading one camera's `el` out and another's in.
+- Labels drawn in the world scale with the zoom; put text that must stay readable in screen space (the panel) or give world labels a size for the shot's zoom. A beat whose camera shows a picture from its first frame while its first scheduled reveal is late may need `{ lead: false }`.
+- Ease `soft` (cosine in-out) suits camera moves; `io`, `out`, `back`, `lin` or any `p => …` work too.
+
## Questions
```js
diff --git a/site/science/lib/engine.js b/site/science/lib/engine.js
index 568d6bd..3e33e7b 100644
--- a/site/science/lib/engine.js
+++ b/site/science/lib/engine.js
@@ -827,6 +827,74 @@ function evalTo(t, list = TW) {
}
}
+/* ---------- world clock and camera ---------- */
+const soft = p => (1 - Math.cos(Math.PI * p)) / 2; // gentle in-out, for camera moves
+// Continuous motion: f(t) runs on every frame of the beat with t in seconds from its start (0..D).
+// Keep f a pure function of t, so pause, seek and ?beat=N&t=S show the same frame.
+const clockRun = (f, D) => { f(0); prog(q => f(q * D), 0, D, lin); };
+// A camera looks at a world group through the stage (or a box, for split screen and picture-in-picture).
+// The view {x, y, z, r} is the world point at the centre, the zoom (screen px per world px) and the roll in degrees.
+// Moves are keyed on the beat clock: to(view, t0, dur, ease) blends each given key from its value at t0; a key may be a
+// function of t (follow). Unspecified keys keep following the earlier moves. dur 0 is a hard cut.
+let camN = 0;
+function camera(p, D, { box, x = 800, y = 450, z, r = 0, bg = COL.board } = {}) {
+ const [bx, by, bw, bh] = box || [0, 0, 1600, 900];
+ const el = G(p, { x: bx + bw / 2, y: by + bh / 2 });
+ let hold = el;
+ if (box) {
+ const id = 'cam' + (++camN);
+ mk('rect', { x: -bw / 2, y: -bh / 2, width: bw, height: bh, rx: 18 }, mk('clipPath', { id }, mk('defs', {}, el)));
+ hold = G(el); hold.setAttribute('clip-path', `url(#${id})`);
+ mk('rect', { x: -bw / 2, y: -bh / 2, width: bw, height: bh, fill: bg }, hold);
+ }
+ const view = mk('g', {}, hold), world = G(view);
+ if (box) mk('rect', { x: -bw / 2, y: -bh / 2, width: bw, height: bh, rx: 18, fill: 'none', stroke: COL.faint, 'stroke-width': 2 }, el);
+ const v0 = { x, y, z: z ?? (box ? Math.min(bw / 1600, bh / 900) : 1), r };
+ const ops = [], shakes = [], layers = [];
+ const val = (v, t) => typeof v === 'function' ? v(t) : v;
+ // The view at time t after the first n moves; each move remembers the view it starts from.
+ function at(t, n = ops.length) {
+ const s = { ...v0 };
+ for (let i = 0; i < n && ops[i].t0 <= t; i++) {
+ const o = ops[i], a = o.from || (o.from = at(o.t0, i));
+ const q = o.dur ? o.ease(Math.min(1, (t - o.t0) / o.dur)) : 1, b = {};
+ for (const k in o.v) b[k] = val(o.v[k], t);
+ if ('z' in b) s.z = a.z * (b.z / a.z) ** q; // even zoom speed
+ // While zooming, x/y move so that one world point stays put on screen (when start and end allow it).
+ const u = 'z' in b && Math.abs(b.z - a.z) > 1e-6 * a.z ? (1 / s.z - 1 / a.z) / (1 / b.z - 1 / a.z) : q;
+ for (const k of ['x', 'y']) if (k in b) s[k] = a[k] + (b[k] - a[k]) * u;
+ if ('r' in b) s.r = a.r + (b.r - a.r) * q;
+ }
+ return s;
+ }
+ function apply(t) {
+ const s = at(t);
+ let sx = 0, sy = 0;
+ for (const k of shakes) if (t > k.t0 && t < k.t0 + k.dur) {
+ const e = k.amp * Math.min(1, (t - k.t0) / .3, (k.t0 + k.dur - t) / .3), w = 2 * Math.PI * k.hz * t;
+ sx += e * (Math.sin(w) + .5 * Math.sin(2.3 * w + 1)) / 1.5; sy += e * (Math.sin(1.7 * w + 2) + .5 * Math.sin(3.1 * w)) / 1.5;
+ }
+ view.setAttribute('transform', `translate(${sx} ${sy}) rotate(${-s.r}) scale(${s.z}) translate(${-s.x} ${-s.y})`);
+ const dx = s.x - v0.x, dy = s.y - v0.y;
+ for (const L of layers) put(L.g, { x: L.wrap ? dx - ((L.k * dx) % L.wrap + L.wrap) % L.wrap : (1 - L.k) * dx, y: (1 - L.k) * dy });
+ }
+ const cam = { el, world, at,
+ to(v, t0, dur = 1, ease = soft) { ops.push({ v, t0, dur, ease }); ops.sort((a, b) => a.t0 - b.t0); ops.forEach(o => delete o.from); return cam; },
+ cut: (v, t0) => cam.to(v, t0, 0),
+ shake(amp, t0, dur, hz = 7) { shakes.push({ amp, t0, dur, hz }); return cam; },
+ // Parallax layer: k < 1 is far (moves slower than the camera), k > 1 near. With wrap = W the layer's content
+ // repeats every W world px: draw one period plus the widest view, and the layer never runs out.
+ layer(k = 1, wrap) { const g = G(world); layers.push({ g, k, wrap }); return g; },
+ // Screen position of a world point at time t (k = 1 layers, no shake): for labels that track an object.
+ screen(wx, wy, t) {
+ const s = at(t), a = -s.r * Math.PI / 180, ux = (wx - s.x) * s.z, uy = (wy - s.y) * s.z;
+ return [bx + bw / 2 + ux * Math.cos(a) - uy * Math.sin(a), by + bh / 2 + ux * Math.sin(a) + uy * Math.cos(a)];
+ },
+ };
+ clockRun(apply, D);
+ return cam;
+}
+
/* ---------- scene ---------- */
const scene = document.getElementById('scene');
const S = {};