API reference
Every export, by entry point. The build fails if this page names anything romp doesn't export.
romp/core
Stage
One planck.js world, baked once.
new Stage({ pxPerMetre?: 100, gravity?: 9.81 * 2.2, yDown?: true })
stage.ground(points, { friction?, layer? }): PlanckBody
stage.add(actor): actor // sets actor.stage, then actor.build(stage)
stage.bake({ frames? | duration?, fps?: 30, hz?: 240 }): Stage
stage.pose(t, { discrete? }): void // calls each actor's apply(pose, t); NaN poses arrive as { shown: false }
stage.get<A>(id): A
stage.m(px) · stage.px(metres) · stage.v(x, y)
LAYER
Collision layer bits: FLOOR, A, B, C, D. Give a body a layer and the mask of layers it touches.
Body
A rigid body that records its impacts.
new Body({ id, x, y, w, h, shape?: "rounded" | "box" | "circle", spawn?, vx?, vy?, spin?,
restitution?, friction?, density?, upright?, angularDamping?, layer?, mask?, bullet?, gravityScale? })
body.impacts: { frame, t, speed, vx, side? }[] body.landed: number (first landing frame; side hits don't count)
SpringyBody
Welds itself to ground where it first lands on it, so it can be knocked over and wobble back.
new SpringyBody({ ...BodyOptions, ground: PlanckBody, groundY: number, hz?: 2, damping?: 0.18 })
springy.isWelded: boolean
Drop
A dropped prop that stays upright. Contact arrests everything: spin, tilt and depth drift reach rest exactly at touchdown.
new Drop({ ...BodyOptions, foot?, ledge?: { x0, x1, y }, frame?: { x, y }, spinAt?, tilt?, z?: [from, to], rock?: 1 | -1 })
drop.flight(frame): { u, spin, tilt, z, rockDir } // pair rockDir with rock() for the rock about its tip
drop.framePose(frame, { discrete? }): BodyPose // the pose minus `frame`, in its parent's coordinates
Leap
A ballistic leap through a surface line; records each crossing with its velocity.
new Leap({ id, x, y, vx, vy, surface, size?, spawn?, gravity?: 1, frame?: { x, y } })
leap.crossings: { frame, t, x, out, vx, vy }[] pose: { shown, x, y, angle, heading, speed }
poseAt
poseAt(actor, frame, { discrete?: "nearest" | "previous" }): Pose
Interpolated between baked frames: numbers lerp; booleans and strings switch at the halfway point ("nearest") or hold the earlier frame ("previous").
poseAtTime
poseAtTime(actor, seconds, fps = 30, { discrete? }): Pose
baked · clearBaked
baked(key, () => stage.bake(…)): Stage clearBaked(): void
impactResponse
impactResponse(body, frame, seed?, speedRef = 900, style?: { squash?: 0.28, widen?: 0.85 }): { squashX, squashY, tilt, lift, blink, jiggle }
jiggleParts · jiggle
jiggle(dt, strength = 1): number
jiggleParts(parts: string[], dt, strength = 1, lag = 1.5): Record<string, number>
landing · hop · idle · blinkAt · boing · rock · nearImpact
landing(frame, land, seed?, strength?): CharacterPose
hop(frame, period = 16, height = 70, seed?): { y, pose }
idle(frame, seed?): CharacterPose blinkAt(frame, seed?): 0..1
boing(dt, freq?, decay?): number nearImpact(impacts, frame, window = 2): boolean
rock(impacts, frame, fps?, { hz?, zeta?, max?, dir? }): { angle, squash }
ease · spring · ringOut · stagger · SPRING · lerp · span · clamp01
Closed-form curves: ease.out, ease.in, ease.inOut; spring(elapsed, SPRING.smooth), ringOut(elapsed, SPRING.bouncy), stagger(t0, i, frames = 3, fps = 30).
Clock
new Clock({ seek, duration, loop?, audio?, onPlay?(t), onStop?() })
clock.play(from?) · clock.pause() · clock.seek(t) · clock.t · clock.playing
Drives seek(t) on requestAnimationFrame; follows audio.currentTime while it's running.
romp/check
analyze
analyze(frames: { f, row: Record<name, Sample> }[], { fps?, width?, height?, whips?, covered?, impacts?, seamless?,
croppedFraction?: 0.25, croppedSeconds?: 0.5, allowCrop?: string[], lostSeconds?: 1, allowExit?: string[], strobePx?, teleportPx? }): Report
Sample = { x, y, shown, onScreen, area, opacity, impact?, seamless?, box?: { x0, y0, x1, y1 }, allowCrop? }
Report = { tracked, frames, issues: { frame, name, kind: "pop" | "strobe" | "teleport" | "spike" | "cropped" | "lost", detail }[] }
The cropped and lost checks run when both width and height are given.
inFrameShare
inFrameShare(box, W, H): 0..1 // the share of a box inside the frame
formatReport
formatReport(report, fps = 30): string
collectDom
collectDom(root = document.body): Record<name, Sample> // every [data-romp] element, relative to root, with its box
romp/remotion
track
track(name, { impact?, seamless?, allowCrop? }): { "data-romp", "data-romp-impact"?, "data-romp-seamless"?, "data-romp-allow-crop"? }
Also re-exports collectDom, analyze and formatReport. A romp check entry default-exports a CheckEntry (or a function of --arg returning one): { component, props?, durationInFrames, fps, width, height, whips?, covered?, croppedFraction?, croppedSeconds?, allowCrop? }.
romp/three
motionReport
motionReport({ seek, scene, camera, fps, W, H, from?, to?, whips?, covered? }): Report
Tracks every named object; userData.impacts (seconds), userData.seamless and userData.allowCrop mark deliberate moments. Runs the cropped check (it knows W and H).
screenBox · screenArea · opacityOf
screenBox(object, camera, W, H): { x0, y0, x1, y1 } | null screenArea(object, camera, W, H): px² opacityOf(object): 0..1
romp/audio
Synth
The voices, on an (Offline)AudioContext, deterministic: marimba, bell, marker, rim, flap, whoosh, tap, splash, ignite, crackle, crickets, surf, wind, hum, birds, riser, thump, click, engine, reverb; set s.harmony = (t) => Set<pitchClass> to keep tonal effects in key.
Instruments
new Instruments(synth): pluck · kick · shaker · rhodes · piano · upright · rim · brush
createMix
createMix(synth, { levels?, sends?, room? }): { master, music, drums, sfx, voice }
renderOffline · renderWav
renderOffline(schedule, { duration, sampleRate?, channels?, extend? }): Promise<AudioBuffer>
renderWav(schedule, options): Promise<string> // base64 WAV
playLive
playLive(audioContext, schedule, { from?, latency?: 0.08, extend? }): Promise<{ origin, stop() }>
fitTo · midiHz · rng · wavBase64 · LEAD
fitTo(pitchClasses, midi): midi midiHz(midi): Hz rng(seed): () => 0..1
wavBase64(audioBuffer): string LEAD = 1 / 30 // transients lead the picture by a frame
A Schedule is (synth, buses, at) => void, where at(filmSeconds) is a context time, or null for something already played.
romp/audio/cartoon
cartoon
Pass as extend to add: plop, boing, babble, slurp, beep, ding, tock, pip, swish, scribble.
VOICES
Babble voice presets: { f0, swing, rate } per name (hero, low, sleepy, chill, loud, warm, sunny, squeaky, playful, singsong).
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]