romp

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]