Guides
From a first pile of characters to a soundtrack and a motion check in CI.
Physics: bake a scene, read poses
A Stage is one planck.js (Box2D) world. You add actors, bake it once in fixed steps (240 Hz by default) and it stores one pose per frame for every actor. After that, reading a pose is a pure function of the frame, so it doesn't matter in which order, or how often, frames are drawn.
import { Stage, Body, SpringyBody, LAYER, poseAt } from "romp/core";
const s = new Stage(); // px; y down; gravity a little heavier than life
s.ground([{ x: 10, y: 0 }, { x: 10, y: 470 }, { x: 790, y: 470 }, { x: 790, y: 0 }]);
// A shelf only the letters (layer B) and the flung character (layer C) touch.
const shelf = s.ground([{ x: 250, y: 205 }, { x: 550, y: 205 }], { layer: LAYER.B });
s.add(new SpringyBody({ id: "p", x: 497, y: -30, w: 64, h: 84, spawn: 22, ground: shelf, groundY: 205,
layer: LAYER.B, mask: LAYER.B | LAYER.C }));
s.add(new Body({ id: "zip", shape: "circle", x: 880, y: 175, w: 70, h: 70, spawn: 40, vx: -1500,
layer: LAYER.C, mask: LAYER.FLOOR | LAYER.B | LAYER.A | LAYER.C }));
s.add(new Body({ id: "ada", x: 120, y: -30, w: 96, h: 86, spawn: 92, vy: 800, upright: true,
layer: LAYER.A, mask: LAYER.FLOOR | LAYER.A | LAYER.C })); // skips the shelf
s.bake({ frames: 225, fps: 30 });
const p = poseAt(s.get<Body>("ada"), frame); // { shown, x, y, angle } (centre, px)
- Units: metres in the world and px on screen (
pxPerMetre, default 100).new Stage({ yDown: false })for y-up scenes such as three.js. - Bodies take their feet position, size,
shape("rounded","box"or"circle"), aspawnframe, a launch velocity and spin, restitution,upright, and a collisionlayerandmask. - Impacts are recorded as the world bakes: a sudden loss of speed in the gravity direction, with its frame, time and speed.
body.landedis the first one. SpringyBodywelds itself to its ground where it first lands on that ground (a knock in mid-air doesn't weld it), so it can be knocked over and wobble back.Dropis a dropped prop that stays upright: a contactfoot, agravityScale(small props fall snappier),spinAtandtiltthat unwind to zero exactly at touchdown, depth driftz: [from, to]arrested on contact, arockdirection, and its ownledgewith aframeoffset to draw it in its parent's coordinates (flight(frame),framePose(frame)).Leapis a ballistic leap through a surface (a fish), with agravityscale andframeoffset, recording where it crosses it.- Your own actors implement
build(stage),control(t, dt),sample(t)and, optionally,apply(pose, t);stage.add()setsactor.stagefirst, andstage.pose(t)hands every actor its interpolated pose (a pose with a NaN in it arrives as{ shown: false }).baked(key, build)memoises a stage per scene. - Matching an existing renderer: booleans and strings switch at the halfway point between baked frames;
poseAt(actor, frame, { discrete: "previous" })holds the earlier frame's value instead. - Spawn actors off screen (above the frame, say) so the motion check never sees one pop into place.
Motion: reactions from real impacts
impactResponse(body, frame) turns a body's recorded impacts into a character's reaction, each sized by how hard it hit and decaying on its own curve. For characters that land against each other in a pile, pass a style that keeps the squash from spreading past the body into a neighbour, e.g. impactResponse(body, frame, seed, 900, { squash: 0.15, widen: 0.2 }). Draw each character the same shape as its body (a round body drawn round) and rotate the drawing about the body's centre, not its feet, so what you see is what collides:
import { impactResponse, jiggleParts } from "romp/core";
const look = impactResponse(body, frame, seed);
// squashX / squashY: squash about the feet on landing, stretch while falling fast
// tilt / lift: the hat (or antenna) lags and settles: follow-through
// blink: eyes shut on a hard impact, plus unsynced idle blinks
// jiggle: a single secondary-motion value
// Several parts that follow through in turn (brim, then crown, then pom-pom):
const last = body.impacts.filter((h) => h.frame <= frame).at(-1);
const parts = last ? jiggleParts(["brim", "crown", "pom"], frame - last.frame, last.speed / 900) : {};
Without physics, the same vocabulary is available as pure functions of the frame: landing(frame, land) (a scripted landing), hop(frame, period, height) (a hop cycle with squash on contact), idle(frame) (breathing and blinks), blinkAt(frame, seed), boing(dt) (a decaying oscillation) and rock(impacts, frame) (a rigid prop rocking about its contact point). ease, spring(), ringOut() and stagger() are closed-form curves for everything that isn't simulated. Use a spring or ease.out for entrances, never a straight line.
Two ways to play: live or frame by frame
Write one seek(t) that draws film time t. Both modes call it.
Live (a viewer page)
The Clock drives seek(t) from requestAnimationFrame. While sound is playing, the picture follows the audio clock (AudioContext.currentTime), so the two can't drift; otherwise it follows performance.now(). playLive plays the soundtrack from any point: scrub to 3.2 s and press play, and everything scheduled before 3.2 s is skipped.
import { Clock } from "romp/core";
import { playLive } from "romp/audio";
import { cartoon } from "romp/audio/cartoon";
const audio = new AudioContext();
let live;
const clock = new Clock({
seek, duration: 7.5, loop: true, audio,
onPlay: async (t) => { live = await playLive(audio, schedule, { from: t, extend: cartoon }); },
onStop: () => live?.stop(),
});
playButton.onclick = () => (clock.playing ? clock.pause() : clock.play());
scrubber.oninput = () => clock.seek(+scrubber.value); // restarts the sound there if playing
Frame by frame (Remotion, or a page captured to MP4)
Read poses by frame and render the same schedule offline:
// in a Remotion component
const pose = poseAt(body, useCurrentFrame());
// the soundtrack, offline (deterministic: same schedule, same samples)
import { renderOffline, renderWav } from "romp/audio";
const buffer = await renderOffline(schedule, { duration: 7.5, extend: cartoon });
export const render = () => renderWav(schedule, { duration: 7.5, extend: cartoon }); // for `romp sound`
Sound: one schedule
A soundtrack is a function that schedules every note and cue in film seconds through at(t). Live, at maps film time to the context's time and returns null for anything already played; offline it's the identity.
import { Instruments, type Schedule } from "romp/audio";
export const schedule: Schedule = (s, bus, at) => {
const band = new Instruments(s); // pluck, kick, shaker, rhodes, piano, upright, rim, brush
for (let b = 0; b < 16; b++) {
const t = at(b * 60 / 112); if (t == null) continue;
if (b % 2 === 0) band.kick(t, bus.drums, { vel: 0.22 });
band.shaker(t, bus.drums, { vel: 0.03, seed: b });
}
for (const hit of body.impacts) { // the same impacts the picture reacts to
const t = at(hit.t); if (t == null) continue;
s.boing(t - 1 / 30, bus.sfx, { k: hit.speed / 900, big: size / 95 }); // a frame early
}
};
- The mix (
createMix) has music, drums, sfx and voice buses with a shared room, a 70 Hz high-pass, a low shelf and a glue compressor. - The voices (
Synth): marimba, bell, Karplus–Strong plucks, whooshes, taps, splashes, risers, thumps and more, all synthesised.romp/audio/cartoonaddsplop,boing,babble(gibberish voices:hero,squeaky,low,sleepy,playful, … or your own{ f0, swing, rate }),slurp,beep,ding,tock,pip,swishandscribble. - In key: set
s.harmony = (t) => pitchClassSetand every tonal effect snaps to the chord sounding at that moment (fitTo).
The rules worth keeping: restraint (only each beat's focal event gets a sound), one family (tonal effects on one voice, in the score's key), transients lead the picture by about a frame (LEAD), no identical repeats (every voice takes a seed), and keep the energy between 200 Hz and 6 kHz so it survives a phone speaker. romp sound normalises the result to −16 LUFS.
The motion check
It steps every frame, follows each tracked element's on-screen centre, box, size and opacity, and flags:
| Issue | What it means |
|---|---|
| pop | Appears or vanishes in frame at 30% or more of its largest size, and opaque. It should grow, fade or fly in. |
| strobe | Moves more than about 100 px in one frame (scaled from an 886 px-wide frame). At 30 fps that reads as a jump. |
| teleport | Jumps more than about 300 px while visible on both frames. |
| spike | Acceleration jumps far above its neighbours': a kink where two moves don't match speed. |
| cropped | Shown and on screen, but more than 25% of its own box is outside the frame for more than 0.5 s in a row: a character's head cut off by the edge. Entering or leaving (its on-frame share only rises, or only falls) is fine. Tune with croppedFraction and croppedSeconds. |
| lost | Has been in frame, then leaves it entirely (still shown) and stays out for more than 1 s: it bounced off the stage, fell out of the picture or wandered off. An entrance from off-frame is fine. Mark a real exit with allowExit; tune with lostSeconds. |
Exempt: real impacts (an element marked as at an impact, or impacts frames you pass), deliberate fast moves (whips, in seconds), frames where a transition covers the picture (covered), entrances and exits that fade, grow or shrink, seamless objects that swap in for an identical twin, and allowCrop objects that may run off the edge (track(name, { allowCrop: true }), data-romp-allow-crop, userData.allowCrop in three.js). The cropped check needs the frame's width and height; romp check and motionReport pass both.
Remotion or any DOM page
import { track } from "romp/remotion";
import { nearImpact } from "romp/core";
<div {...track("hero", { impact: nearImpact(hero.impacts, frame) })} style={…} />
// check.tsx: the composition to check (or a function of --arg)
export default (lang) => ({ component: MyVideo, props: { lang }, durationInFrames: 1527, fps: 30,
width: 1080, height: 1920, covered: [[4.2, 4.9]] });
bunx romp check check.tsx --public public --arg '"en"' # exit 1 on issues; --json for machines
On a page of your own, step your seek(t), collect each frame with collectDom(root) and call analyze(frames, { fps, width, height }): the demo on the home page does exactly that.
three.js
import { motionReport } from "romp/three";
const { issues } = motionReport({ seek, scene, camera, fps: 30, W: 886, H: 1920, from: 0, to: 30, whips, covered });
Name the objects worth checking (obj.name = "van"); deliberate landings go in obj.userData.impacts (seconds), swapped twins set userData.seamless.
Anything else
Build { f, row: { name: { x, y, shown, onScreen, area, opacity, box? } } } per frame and call analyze(frames, { fps, width, height }); formatReport() prints it.
The CLI
romp check <entry.tsx> [--public dir] [--from s] [--to s] [--arg json] [--json]
romp sound <module.ts> --out file.wav [--arg json] [--lufs -16]
romp check bundles the entry with esbuild, plays it in headless Chromium with @remotion/player and seeks every frame. romp sound bundles a module exporting render(arg) (an AudioBuffer or a base64 WAV), renders it in headless Chromium and loudness-normalises it with ffmpeg when it's on your PATH.