Code-first video & image, rendered natively on WebGPU.
import {
type AnimatableProp,
type KeyframeTuple,
LayerAnimation,
} from "@framefields/compositions/program";
import { type FrameContext, type FrameSignal, Signal } from "@framefields/core";
import type { SimBody, SimWorld } from "./backend.js";
/**
* A value read every simulated frame: a number, a signal (sampled at the
* composition frame, like `.signal()` tracks), or `(frame) => value` where
* `frame` is the composition frame.
*/
export type PhysicsDriver =
| number
| ((frame: number) => number)
| { get(ctx?: FrameContext): number };
export interface PhysicsWorldOptions {
/** Composition frame rate. */
fps: number;
/** How many frames to simulate. Signals hold the last frame afterwards. */
frames: number;
/**
* Composition frame the simulation's frame 0 lands on (default 0). Set it
* to a scene's start so a world inside that scene starts with it.
*/
startFrame?: number;
/** Pixels per physics meter (default 100). Only changes how stiff and heavy things feel. */
pixelsPerMeter?: number;
/** Solver steps per frame (default 4). Raise for fast, thin or stacked bodies. */
substeps?: number;
/** Frames an impact envelope takes to fall to ~37% (default 8). */
impactDecay?: number;
/** Velocity change, px/s, that reads as impact 1 (default 1500). */
impactReference?: number;
}
export interface BodyCommonOptions {
/** `"dynamic"` (default) falls and collides; `"fixed"` never moves; `"kinematic"` follows `follow` and pushes others. */
type?: "dynamic" | "fixed" | "kinematic";
/** Bounciness, 0–1 (default 0.3). */
restitution?: number;
/** Default 0.6. */
friction?: number;
/** Mass per area/volume (default 1). Heavier bodies push lighter ones. */
density?: number;
/** Velocity damping per second (default 0). */
linearDamping?: number;
/** Spin damping per second (default 0). */
angularDamping?: number;
/** Multiplies world gravity for this body (default 1; 0 floats). */
gravityScale?: number;
/** Never rotates. */
lockRotation?: boolean;
/** Continuous collision detection for very fast bodies (default false). */
ccd?: boolean;
/** Collides with nothing; still moves, still reports contacts (triggers). */
sensor?: boolean;
/** Simulation frame the body wakes up; it holds its place before (default 0). */
startFrame?: number;
/**
* How the result reaches the layer: `"signals"` (default) binds the
* body's signals, `"keyframes"` writes plain keyframes, `"none"` leaves
* the layer alone (read the signals yourself).
*/
output?: "signals" | "keyframes" | "none";
}
/** What `world.live()` needs from a composition. */
export interface LiveHost {
onPrepareFrame(
callback: (ctx: { frame: number }) => Promise<void> | void,
): unknown;
prepareVision?(frame: number): Promise<void>;
}
interface Stepper<B, V, R> {
/** Last simulated frame, relative to the world's start. */
current: number;
freed: boolean;
bySim: Map<SimBody<V, R>, B>;
kinematicFrom: Map<B, { position: V; rotation: R }>;
/** Impact envelope level per body after `current`. */
level: Map<B, number>;
}
export interface PhysicsCollision<B> {
/** Composition frame of first contact. */
frame: number;
/** The other body. */
with: B;
/** Velocity change of the harder-hit body, px/s. */
speed: number;
}
export interface PhysicsBakeOptions {
/** Largest error a dropped keyframe may leave, px (default 0.25). Degrees use a fifth of it. */
tolerance?: number;
}
const CHANNEL_TOLERANCE_SCALE: Record<string, number> = {
rotation: 0.2,
rotateX: 0.2,
rotateY: 0.2,
rotateZ: 0.2,
};
export function sampleDriver(
driver: PhysicsDriver,
frame: number,
fps: number,
): number {
if (typeof driver === "number") return driver;
if (typeof driver === "function") return driver(frame);
const time = frame / fps;
return driver.get({
frame,
fps,
time,
duration: 0,
durationMs: 0,
progress: 0,
deltaTime: 1 / fps,
});
}
/** Shortest-path angle continuation so rotation never jumps by 360. */
export function unwrapDegrees(previous: number, next: number): number {
let d = next - previous;
d -= Math.round(d / 360) * 360;
return previous + d;
}
/**
* Ramer–Douglas–Peucker over one channel: the fewest linear keyframes that
* stay within `tolerance` of every simulated frame.
*/
export function simplifyKeys(
values: ArrayLike<number>,
tolerance: number,
): KeyframeTuple[] {
const n = values.length;
if (n === 0) return [];
const keep = new Uint8Array(n);
keep[0] = 1;
keep[n - 1] = 1;
const stack: Array<[number, number]> = [[0, n - 1]];
while (stack.length > 0) {
const [a, b] = stack.pop() as [number, number];
let worst = -1;
let worstErr = tolerance;
for (let i = a + 1; i < b; i++) {
const t = (i - a) / (b - a);
const lerp = values[a] + (values[b] - values[a]) * t;
const err = Math.abs(values[i] - lerp);
if (err > worstErr) {
worstErr = err;
worst = i;
}
}
if (worst >= 0) {
keep[worst] = 1;
stack.push([a, worst], [worst, b]);
}
}
const keys: KeyframeTuple[] = [];
for (let i = 0; i < n; i++) {
if (keep[i]) keys.push([i, round4(values[i]), "none"]);
}
// A constant channel needs a single key.
if (keys.length === 2 && keys[0][1] === keys[1][1]) keys.pop();
return keys;
}
function round4(v: number): number {
return Math.round(v * 1e4) / 1e4;
}
/**
* Per-frame recordings of one body, indexed by composition frame. Arrays are
* filled when the world simulates; reading a signal before that simulates.
*/
export class Recording {
readonly channels = new Map<string, Float32Array>();
private readonly signals = new Map<string, FrameSignal<number>>();
constructor(
readonly length: number,
private readonly fps: number,
private readonly ensure: () => void,
) {}
channel(name: string): Float32Array {
let arr = this.channels.get(name);
if (!arr) {
arr = new Float32Array(this.length);
this.channels.set(name, arr);
}
return arr;
}
/**
* A per-frame signal over a channel. Creating it does nothing; the first
* value read runs the simulation (offline worlds), so signals can be bound
* while bodies are still being added.
*/
signal(name: string): FrameSignal<number> {
let sig = this.signals.get(name);
if (!sig) {
const arr = this.channel(name);
const fps = this.fps;
sig = Signal.builder({
type: "custom",
fn: (ctx: { frame: number; fps?: number }) => {
this.ensure();
const f =
ctx.fps && ctx.fps !== fps
? (ctx.frame / ctx.fps) * fps
: ctx.frame;
const i = Math.max(0, Math.min(arr.length - 1, Math.round(f)));
return arr[i];
},
}) as unknown as FrameSignal<number>;
this.signals.set(name, sig);
}
return sig;
}
}
/** What the shared stepping loop needs from a 2D or 3D body. */
export interface CoreBody<V extends number[], R> {
readonly sim: SimBody<V, R>;
readonly type: "dynamic" | "fixed" | "kinematic";
readonly startFrame: number;
readonly gravityScale: number;
/** Unset: signals, or keyframes under `bakeKeyframes()`. */
readonly output?: "signals" | "keyframes" | "none";
readonly recording: Recording;
readonly collisions: PhysicsCollision<unknown>[];
readonly layer?: Record<string, unknown>;
/** Kinematic pose (backend units) at a composition frame, if it follows drivers. */
kinematicTarget?(frame: number): { position: V; rotation: R } | undefined;
/** Writes the body's state for one composition frame into its recording. */
record(index: number, previousIndex: number): void;
/** Props bound to the layer, with the recording channel each one reads. */
boundChannels(): Array<[AnimatableProp, string]>;
}
interface ForceEntry<V> {
body: CoreBody<number[], unknown>;
accel: (frame: number) => V;
}
interface ImpulseEntry<V> {
body: CoreBody<number[], unknown>;
frame: number;
dv: V;
}
/**
* Stepping, recording, impacts and output shared by `PhysicsWorld2D` and
* `PhysicsWorld3D`. V is a vector in backend units (meters).
*/
export abstract class WorldCore<
V extends number[],
R,
B extends CoreBody<V, R>,
> {
readonly fps: number;
readonly frames: number;
readonly startFrame: number;
readonly pixelsPerMeter: number;
protected readonly substeps: number;
protected readonly impactDecay: number;
protected readonly impactReference: number;
protected readonly bodies: B[] = [];
protected readonly forces: ForceEntry<V>[] = [];
protected readonly impulses: ImpulseEntry<V>[] = [];
protected readonly fields: Array<{
targets?: Set<B>;
accel: (body: B, frame: number) => V | null | undefined;
}> = [];
/** Run after each simulated frame with the pairs that started touching in it. */
protected readonly stepHooks: Array<
(frame: number, pairs: Array<[B, B]>) => void
> = [];
/** Run once the whole simulation has finished (not in live worlds). */
protected readonly simulatedHooks: Array<() => void> = [];
private readonly worldRecording: Recording;
private readonly allCollisions: Array<PhysicsCollision<B> & { body: B }> = [];
/** No more bodies, joints or forces: the world has started (or finished). */
private locked = false;
private liveMode = false;
private stepper?: Stepper<B, V, R>;
private chain: Promise<void> = Promise.resolve();
protected constructor(
protected readonly sim: SimWorld<V, SimBody<V, R>, unknown>,
protected readonly gravity: V,
options: PhysicsWorldOptions,
) {
if (!(options.fps > 0)) throw new Error("Physics: `fps` must be > 0.");
if (!(options.frames >= 1) || !Number.isInteger(options.frames)) {
throw new Error("Physics: `frames` must be a positive integer.");
}
this.fps = options.fps;
this.frames = options.frames;
this.startFrame = Math.max(0, Math.round(options.startFrame ?? 0));
this.pixelsPerMeter = options.pixelsPerMeter ?? 100;
this.substeps = Math.max(1, Math.round(options.substeps ?? 4));
this.impactDecay = Math.max(0.5, options.impactDecay ?? 8);
this.impactReference = options.impactReference ?? 1500;
this.worldRecording = this.newRecording();
}
/** First contacts so far (all of them once simulated), in frame order. */
get collisions(): ReadonlyArray<PhysicsCollision<B> & { body: B }> {
this.ensureSimulated();
return this.allCollisions;
}
/** Loudest impact envelope of any body each frame: camera shake, flashes, hit sounds. */
get impact(): FrameSignal<number> {
return this.worldRecording.signal("impact");
}
/** Runs the whole simulation now (once) and binds every body's layer per its `output`. */
simulate(): this {
if (this.liveMode)
throw new Error(
"Physics: this world is live; it steps as frames render.",
);
this.ensureSimulated();
return this;
}
/** Like {@link simulate}, but writes keyframes for every body whose `output` was left at its default. */
bakeKeyframes(options: PhysicsBakeOptions = {}): this {
if (this.locked) {
throw new Error(
"Physics: bakeKeyframes() must come before simulate(), live() or reading any body signal.",
);
}
this.bakeDefault = options;
this.ensureSimulated();
return this;
}
/**
* Steps the world as the composition renders instead of all at once: before
* each frame draws, the world advances to it, after the composition's
* vision clips (`comp.vision`) and any `inputs` have that frame ready. Use
* it when bodies follow a performer, so nothing is analysed up front and a
* preview starts at once. Frames already simulated are kept, so scrubbing
* back costs nothing; jumping ahead simulates the frames in between.
* Signals only; `bakeKeyframes()` needs the whole run up front.
*/
live(
comp: LiveHost,
options: {
inputs?: ReadonlyArray<{ ready(frame: number): Promise<void> }>;
} = {},
): this {
if (this.locked) {
throw new Error(
"Physics: live() must come before simulate() or reading any body signal.",
);
}
if (this.simulatedHooks.length) {
throw new Error(
"Physics: fracture() needs the whole run up front; use simulate() instead of live().",
);
}
this.locked = true;
this.liveMode = true;
const prepare = async (frame: number) => {
await comp.prepareVision?.(frame);
for (const input of options.inputs ?? []) await input.ready(frame);
};
this.prepareInputs = prepare;
for (const body of this.bodies) this.bind(body);
comp.onPrepareFrame((ctx) => this.advanceTo(ctx.frame));
return this;
}
/**
* Live worlds: simulates up to composition frame `frame` (no-op when it
* already has). Calls queue, so frames are stepped once, in order.
*/
advanceTo(frame: number): Promise<void> {
this.chain = this.chain.then(async () => {
const target = Math.min(
this.frames - 1,
Math.round(frame) - this.startFrame,
);
if (!this.stepper) {
await this.prepareInputs?.(this.startFrame);
this.stepper = this.begin();
}
const st = this.stepper;
while (st.current < target) {
const next = st.current + 1;
await this.prepareInputs?.(this.startFrame + next);
this.stepFrame(st, next);
}
if (st.current === this.frames - 1 && !st.freed) {
st.freed = true;
this.sim.free();
}
});
return this.chain;
}
private prepareInputs?: (frame: number) => Promise<void>;
private bakeDefault?: PhysicsBakeOptions;
protected newRecording(): Recording {
return new Recording(this.startFrame + this.frames, this.fps, () =>
this.ensureSimulated(),
);
}
protected assertOpen(): void {
if (this.locked) {
throw new Error(
"Physics: the world has already started; add every body, joint and force before simulate(), live() or reading signals.",
);
}
}
protected addBody(body: B): B {
this.assertOpen();
this.bodies.push(body);
return body;
}
protected addForce(body: B, accel: (frame: number) => V): void {
this.assertOpen();
this.forces.push({
body: body as unknown as CoreBody<number[], unknown>,
accel,
});
}
protected addField(
accel: (body: B, frame: number) => V | null | undefined,
targets?: readonly B[],
): void {
this.assertOpen();
this.fields.push({ accel, ...(targets && { targets: new Set(targets) }) });
}
protected addImpulse(body: B, frame: number, dv: V): void {
this.assertOpen();
this.impulses.push({
body: body as unknown as CoreBody<number[], unknown>,
frame: Math.round(frame),
dv,
});
}
protected ensureSimulated(): void {
if (this.locked) return;
this.locked = true;
const st = this.begin();
for (let f = 1; f < this.frames; f++) this.stepFrame(st, f);
st.freed = true;
this.sim.free();
for (const body of this.bodies) this.bind(body);
for (const hook of this.simulatedHooks) hook();
}
/** Records frame 0 and sets every channel to it, so frames not simulated yet hold the start pose. */
private begin(): Stepper<B, V, R> {
const { startFrame } = this;
const bodies = this.bodies;
const bySim = new Map<SimBody<V, R>, B>();
for (const b of bodies) bySim.set(b.sim, b);
for (const b of bodies) if (b.startFrame > 0) b.sim.setEnabled(false);
const kinematicFrom = new Map<B, { position: V; rotation: R }>();
for (const b of bodies) {
b.record(startFrame, -1);
b.recording.channel("impact");
const t = b.kinematicTarget?.(startFrame);
if (t) kinematicFrom.set(b, t);
}
this.worldRecording.channel("impact");
for (const rec of [
...bodies.map((b) => b.recording),
this.worldRecording,
]) {
for (const arr of rec.channels.values()) arr.fill(arr[startFrame]);
}
return {
current: 0,
freed: false,
bySim,
kinematicFrom,
level: new Map(bodies.map((b) => [b, 0])),
};
}
private stepFrame(st: Stepper<B, V, R>, f: number): void {
const { fps, startFrame, substeps } = this;
const dt = 1 / (fps * substeps);
const bodies = this.bodies;
const frame = startFrame + f;
const dims = this.gravity.length;
const prevVel = new Map<B, number[]>();
for (const b of bodies) {
// A body sits at its start pose on its start frame and moves after.
if (b.startFrame > 0 && f === b.startFrame + 1) b.sim.setEnabled(true);
prevVel.set(b, b.sim.velocity() as number[]);
}
const isActive = (b: B) => b.type === "dynamic" && f > b.startFrame;
// Velocity each body is expected to gain this frame from gravity,
// forces, fields and impulses: anything beyond it came from a contact.
const expected = new Map<B, number[]>();
for (const b of bodies) {
expected.set(
b,
this.gravity.map((g) => (isActive(b) ? (g * b.gravityScale) / fps : 0)),
);
}
for (const imp of this.impulses) {
if (imp.frame !== f) continue;
const body = imp.body as unknown as B;
if (!isActive(body)) continue;
const m = body.sim.mass();
body.sim.applyImpulse(imp.dv.map((v) => v * m) as V);
const e = expected.get(body) as number[];
for (let i = 0; i < dims; i++) e[i] += imp.dv[i];
}
const frameForces = this.forces
.filter((fe) => isActive(fe.body as unknown as B))
.map((fe) => {
const body = fe.body as unknown as B;
const a = fe.accel(frame);
const e = expected.get(body) as number[];
for (let i = 0; i < dims; i++) e[i] += a[i] / fps;
return { body, a };
});
const kinematicTo = new Map<B, { position: V; rotation: R }>();
for (const b of bodies) {
const t = b.kinematicTarget?.(frame);
if (t) kinematicTo.set(b, t);
}
const started = new Set<string>();
const pairs: Array<[B, B]> = [];
for (let s = 1; s <= substeps; s++) {
for (const { body, a } of frameForces) {
const m = body.sim.mass();
body.sim.applyImpulse(a.map((v) => v * m * dt) as V);
}
for (const field of this.fields) {
for (const b of bodies) {
if (!isActive(b) || (field.targets && !field.targets.has(b)))
continue;
const a = field.accel(b, frame);
if (!a) continue;
const m = b.sim.mass();
b.sim.applyImpulse(a.map((v) => v * m * dt) as V);
const e = expected.get(b) as number[];
for (let i = 0; i < dims; i++) e[i] += a[i] * dt;
}
}
for (const [b, to] of kinematicTo) {
const from = st.kinematicFrom.get(b) ?? to;
const k = s / substeps;
b.sim.setKinematicTarget(
lerpVec(from.position, to.position, k),
this.lerpRotation(from.rotation, to.rotation, k),
);
}
this.sim.step(dt);
for (const [sa, sb] of this.sim.drainCollisionStarts()) {
const a = st.bySim.get(sa);
const b = st.bySim.get(sb);
if (!a || !b) continue;
const key = `${bodies.indexOf(a)}:${bodies.indexOf(b)}`;
if (started.has(key)) continue;
started.add(key);
pairs.push([a, b]);
}
}
st.kinematicFrom = kinematicTo;
for (const b of bodies) b.record(frame, frame - 1);
const raw = new Map<B, number>();
if (pairs.length > 0) {
const ppm = this.pixelsPerMeter;
const hit = (b: B): number => {
if (b.type !== "dynamic") return 0;
const v = b.sim.velocity() as number[];
const v0 = prevVel.get(b) as number[];
const e = expected.get(b) as number[];
let sq = 0;
for (let i = 0; i < dims; i++) {
const d = v[i] - (v0[i] + e[i]);
sq += d * d;
}
return Math.sqrt(sq) * ppm;
};
for (const [a, b] of pairs) {
const speed = Math.max(hit(a), hit(b));
for (const [self, other] of [
[a, b],
[b, a],
] as const) {
raw.set(self, Math.max(raw.get(self) ?? 0, speed));
const c = { frame, with: other, speed };
self.collisions.push(c as never);
if (self === a) this.allCollisions.push({ ...c, body: a });
}
}
}
// Impact envelopes: instant attack, exponential release.
const decay = Math.exp(-1 / this.impactDecay);
let loudest = 0;
for (const b of bodies) {
const level = Math.max(
(raw.get(b) ?? 0) / this.impactReference,
(st.level.get(b) ?? 0) * decay,
);
st.level.set(b, level);
b.recording.channel("impact")[frame] = level;
if (level > loudest) loudest = level;
}
this.worldRecording.channel("impact")[frame] = loudest;
for (const hook of this.stepHooks) hook(f, pairs);
st.current = f;
}
protected abstract lerpRotation(a: R, b: R, t: number): R;
private bind(body: B): void {
const layer = body.layer as
| { animate?: (...a: LayerAnimation[]) => unknown }
| undefined;
const output = body.output ?? (this.bakeDefault ? "keyframes" : "signals");
if (typeof layer?.animate !== "function" || output === "none") return;
if (body.type === "fixed") return;
const channels = body.boundChannels();
if (output === "keyframes" && this.liveMode) {
throw new Error(
'Physics: live worlds bind signals; drop `output: "keyframes"` or use simulate().',
);
}
if (output === "signals") {
const anim = LayerAnimation.create();
for (const [prop, channel] of channels) {
anim.signal(prop, body.recording.signal(channel));
}
layer.animate(anim);
return;
}
const tolerance = this.bakeDefault?.tolerance ?? 0.25;
const anim = LayerAnimation.create();
for (const [prop, channel] of channels) {
const arr = body.recording.channel(channel);
const local = arr.subarray(this.startFrame);
const scale = CHANNEL_TOLERANCE_SCALE[prop] ?? 1;
anim.keys(prop, simplifyKeys(local, tolerance * scale));
}
layer.animate(anim);
}
}
function lerpVec<V extends number[]>(a: V, b: V, t: number): V {
return a.map((v, i) => v + (b[i] - v) * t) as V;
}