Skip to content

Code-first video & image, rendered natively on WebGPU.

feat(physics): Rapier rigid-body physics as signals, person tracking, dancer example

okanasl4625cc762086
diff --git a/.changeset/physics-rapier.md b/.changeset/physics-rapier.md
new file mode 100644
index 00000000..3672d828
--- /dev/null
+++ b/.changeset/physics-rapier.md
@@ -0,0 +1,7 @@
+---
+"framefields": minor
+---
+
+Add rigid-body physics: `Physics.world2d` / `Physics.world3d` (Rapier, deterministic) simulate once while the composition is built and replay as per-frame signals. Bodies come from layers (boxes, circles, convex hulls of shapes, measured text, Layer3D primitives and models); `simulate()` binds each layer, and every body exposes `impact`, `speed`, velocity and pose signals for driving any prop or effect. Includes ground/walls, pins, hinges, welds, springs, ropes, signal-driven forces and kinematic bodies, collision lists, and `bakeKeyframes()` for plain keyframes.
+
+`world.field()` adds position-dependent forces (wind, vortices, flow fields). `comp.trackPerson(source)` tracks a performer before rendering — smoothed pose keypoints and a soft silhouette per frame, placeable into composition pixels and cacheable as JSON — so limbs can be kinematic colliders and the silhouette a force field.
diff --git a/examples/28_physics_dancer/README.md b/examples/28_physics_dancer/README.md
new file mode 100644
index 00000000..86e9e6d6
--- /dev/null
+++ b/examples/28_physics_dancer/README.md
@@ -0,0 +1,28 @@
+# 28 — Physics dancer
+
+A 6.6-second shot where rigid-body physics meets on-device vision. Word cards fall onto a
+dancer's raised hands and head and tumble to the floor; a cloud of ~800 particles flows around
+her as the silk dress sweeps through it.
+
+```bash
+pnpm fonts # Syne from google/fonts → assets/fonts/
+pnpm render sim # tracks the dancer (once, ~30 s, cached in output/) and runs the physics
+pnpm render # output/physics-dancer.mp4
+pnpm render:src # same, on the engine's source (no package builds)
+```
+
+The clip is example 19's `assets/dancer.mp4`; generate it there with `pnpm assets`.
+
+## How it works
+
+| Piece | API |
+|---|---|
+| Pose and silhouette for every frame, before rendering | `comp.trackPerson(clip)` → `PersonTrack`, placed with `.place({ width, height, fit })`, cached with `toJSON()` / `PersonTrack.fromJSON()` |
+| Arms and head that catch the cards | kinematic circle bodies along shoulder → elbow → wrist (and past the wrist for the hand), `follow`ing `person.point(name, frame)` |
+| The dress pushing particles and cards | `world.field()` with `person.sample(frame, x, y)`: out along the silhouette's gradient, much harder where the silhouette just arrived (the sweep) |
+| Fluid feel | small circles with `linearDamping` 2.2, near-zero gravity, a slow swirling current and a soft pull home |
+| Particles behind her | a second copy of the clip, cut out with `.withVision({ mode: "matte" })`, above the particles |
+| Hot particles | `.colorSignal("fillColor", …)` from each body's `speed` |
+| Screen shake | the whole stage's `y` driven by `world.impact` |
+
+Cards are sized with `FontManager.measure`, so the text always fits.
diff --git a/examples/28_physics_dancer/package.json b/examples/28_physics_dancer/package.json
new file mode 100644
index 00000000..31d11e23
--- /dev/null
+++ b/examples/28_physics_dancer/package.json
@@ -0,0 +1,21 @@
+{
+ "name": "@framefields/example-28-physics-dancer",
+ "version": "2.2.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "fonts": "tsx src/fetch-fonts.ts",
+ "render": "tsx src/render.ts",
+ "render:src": "tsx --tsconfig tsconfig.dev.json --conditions=development src/render.ts",
+ "typecheck": "tsc --noEmit -p ."
+ },
+ "dependencies": {
+ "framefields": "workspace:*"
+ },
+ "devDependencies": {
+ "@framefields/tsconfig": "workspace:*",
+ "@types/node": "^24.1.0",
+ "tsx": "^4.20.3",
+ "typescript": "^5.8.3"
+ }
+}
diff --git a/examples/28_physics_dancer/src/fetch-fonts.ts b/examples/28_physics_dancer/src/fetch-fonts.ts
new file mode 100644
index 00000000..3a50b598
--- /dev/null
+++ b/examples/28_physics_dancer/src/fetch-fonts.ts
@@ -0,0 +1,19 @@
+/**
+ * pnpm fonts → assets/fonts/Syne.ttf from google/fonts (SIL OFL).
+ * Font files are gitignored; this script is the record of where they came from.
+ * Idempotent: an existing file is kept.
+ */
+import fs from "node:fs/promises";
+import { FONT_FILE, FONTS } from "./theme.js";
+
+const SRC =
+ "https://raw.githubusercontent.com/google/fonts/main/ofl/syne/Syne%5Bwght%5D.ttf";
+
+await fs.mkdir(FONTS, { recursive: true });
+if (!(await fs.stat(FONT_FILE).catch(() => null))) {
+ const res = await fetch(SRC);
+ if (!res.ok) throw new Error(`${SRC}: HTTP ${res.status}`);
+ await fs.writeFile(FONT_FILE, Buffer.from(await res.arrayBuffer()));
+ console.log(FONT_FILE);
+}
+process.exit(0);
diff --git a/examples/28_physics_dancer/src/film.ts b/examples/28_physics_dancer/src/film.ts
new file mode 100644
index 00000000..c32d5e7a
--- /dev/null
+++ b/examples/28_physics_dancer/src/film.ts
@@ -0,0 +1,302 @@
+/**
+ * A dancer in a field of physics: word cards drop onto her raised hands and
+ * head, and a cloud of particles flows around her as the dress sweeps through.
+ *
+ * - Her arms and head are kinematic colliders that follow the tracked pose.
+ * - Her silhouette (dress included) is a force field that pushes everything out,
+ * hardest where it is sweeping in.
+ * - A vision cutout of the same clip sits above the particles, so they pass behind her.
+ */
+import {
+ Composition,
+ FontManager,
+ Layer,
+ LayerAnimation,
+ type PersonTrack,
+ Physics,
+ type PhysicsBody2D,
+ type PhysicsWorld2D,
+ type PoseKeypointName,
+ Signal,
+} from "framefields";
+import { performer } from "./performer.js";
+import {
+ CREAM,
+ DANCER,
+ DURATION,
+ EMBER,
+ FLOOR,
+ FONT_FILE,
+ FPS,
+ GOLD,
+ H,
+ HOT,
+ INK,
+ RUST,
+ registerFonts,
+ VIOLET,
+ W,
+} from "./theme.js";
+
+const WORDS = [
+ { text: "PHYSICS", bg: EMBER, fg: INK, at: 30 },
+ { text: "MEETS", bg: INK, fg: CREAM, at: 46 },
+ { text: "VISION", bg: CREAM, fg: INK, at: 62 },
+ { text: "IN", bg: GOLD, fg: INK, at: 78 },
+ { text: "FRAMEFIELDS", bg: VIOLET, fg: CREAM, at: 94 },
+];
+const CARD_FONT_SIZE = 64;
+const PARTICLE_COLORS = [INK, RUST, EMBER, GOLD];
+
+/** Balls along a limb (u = 0 at `a`, 1 at `b`, beyond 1 past `b`) that follow the pose. */
+function limb(
+ world: PhysicsWorld2D,
+ person: PersonTrack,
+ a: PoseKeypointName,
+ b: PoseKeypointName,
+ us: number[],
+ r: number,
+): void {
+ for (const u of us) {
+ const at = (frame: number) => {
+ const p = person.point(a, frame);
+ const q = person.point(b, frame);
+ return [p.x + (q.x - p.x) * u, p.y + (q.y - p.y) * u] as const;
+ };
+ const [x, y] = at(0);
+ world.body(
+ { x: x - r, y: y - r, width: 2 * r, height: 2 * r },
+ {
+ type: "kinematic",
+ shape: "circle",
+ friction: 0.9,
+ follow: { x: (f) => at(f)[0] - r, y: (f) => at(f)[1] - r },
+ },
+ );
+ }
+}
+
+/** Word cards sized to their text, dropped over whichever hand is highest. */
+function cards(world: PhysicsWorld2D, person: PersonTrack) {
+ return WORDS.map((w, i) => {
+ const m = FontManager.measure(w.text, {
+ fontFamily: "Syne",
+ fontSize: CARD_FONT_SIZE,
+ });
+ const width = Math.ceil(m.width + 72);
+ const height = Math.ceil(m.height + 40);
+ const hand = (["leftWrist", "rightWrist"] as const)
+ .map((k) => person.point(k, w.at + 12))
+ .reduce((p, q) => (p.y < q.y ? p : q));
+ const layer = Layer.box({
+ id: `card-${i}`,
+ position: "absolute",
+ x: hand.x - width / 2 + (i % 2 ? 30 : -30),
+ y: -height - 200,
+ width,
+ height,
+ rotation: (i % 2 ? 1 : -1) * (6 + i * 2),
+ borderRadius: 18,
+ background: w.bg,
+ children: [
+ Layer.text(w.text, {
+ fontFamily: "Syne",
+ fontSize: CARD_FONT_SIZE,
+ fill: w.fg,
+ width,
+ height,
+ align: "center",
+ verticalAlign: "middle",
+ }),
+ ],
+ });
+ const body = world.body(layer, {
+ restitution: 0.25,
+ friction: 0.7,
+ density: 1.5,
+ angularDamping: 1.2,
+ startFrame: w.at,
+ });
+ return { layer, body };
+ });
+}
+
+/** A loose cloud of small particles around her, avoiding where she stands. */
+function particles(world: PhysicsWorld2D, person: PersonTrack) {
+ let seed = 7;
+ const rand = () => {
+ seed = (seed * 16807) % 2147483647;
+ return seed / 2147483647;
+ };
+ const out: Array<{
+ layer: ReturnType<typeof Layer.shape>;
+ body: PhysicsBody2D;
+ color: string;
+ home: [number, number];
+ }> = [];
+ for (let y = 430; y < FLOOR - 10; y += 24) {
+ for (let x = 20; x < W - 20; x += 24) {
+ const px = x + (rand() - 0.5) * 12;
+ const py = y + (rand() - 0.5) * 12;
+ if (person.sample(0, px, py).alpha > 0.15 || rand() > 0.5) continue;
+ const r = 6 + rand() * 6;
+ const color =
+ PARTICLE_COLORS[Math.floor(rand() * PARTICLE_COLORS.length)];
+ const layer = Layer.shape("circle", {
+ position: "absolute",
+ x: px - r,
+ y: py - r,
+ width: 2 * r,
+ height: 2 * r,
+ fill: color,
+ });
+ const body = world.body(layer, {
+ restitution: 0.05,
+ friction: 0.02,
+ density: 0.25,
+ linearDamping: 2.2,
+ gravityScale: 0.06,
+ lockRotation: true,
+ });
+ out.push({ layer, body, color, home: [px, py] });
+ }
+ }
+ return out;
+}
+
+/** Out of the silhouette: `strength` where she is, plus `sweep` where she is arriving. */
+function silhouettePush(person: PersonTrack, strength: number, sweep: number) {
+ return (s: {
+ x: number;
+ y: number;
+ frame: number;
+ }): [number, number] | null => {
+ const now = person.sample(s.frame, s.x, s.y);
+ if (now.alpha < 0.02) return null;
+ const before = person.sample(s.frame - 1, s.x, s.y);
+ const g = Math.hypot(now.gx, now.gy) || 1;
+ const k =
+ now.alpha * strength + Math.max(0, now.alpha - before.alpha) * sweep;
+ return [(-now.gx / g) * k, (-now.gy / g) * k];
+ };
+}
+
+export async function buildFilm(): Promise<Composition> {
+ await registerFonts();
+ const comp = new Composition({
+ width: W,
+ height: H,
+ fps: FPS,
+ durationFrames: DURATION,
+ backgroundColor: "#E9D3B4",
+ fonts: [FONT_FILE],
+ });
+ const person = await performer(comp);
+
+ const world = await Physics.world2d({
+ fps: FPS,
+ frames: DURATION,
+ gravity: 2600,
+ substeps: 6,
+ impactDecay: 5,
+ });
+ world.walls({ width: W, height: FLOOR });
+
+ for (const side of ["left", "right"] as const) {
+ limb(world, person, `${side}Shoulder`, `${side}Elbow`, [0, 0.5, 1], 26);
+ limb(
+ world,
+ person,
+ `${side}Elbow`,
+ `${side}Wrist`,
+ [0.33, 0.66, 1, 1.25],
+ 24,
+ );
+ }
+ limb(world, person, "leftShoulder", "rightShoulder", [0.5], 40);
+ limb(world, person, "nose", "nose", [0], 52);
+
+ const words = cards(world, person);
+ const cloud = particles(world, person);
+ const cloudBodies = cloud.map((p) => p.body);
+ const home = new Map(cloud.map((p) => [p.body, p.home]));
+
+ world.field(silhouettePush(person, 11000, 140000), { bodies: cloudBodies });
+ world.field(silhouettePush(person, 16000, 60000), {
+ bodies: words.map((w) => w.body),
+ });
+ // A slow swirling current keeps the cloud alive; a soft pull home keeps it on stage.
+ world.field(
+ (s) => {
+ const t = s.frame / FPS;
+ const [hx, hy] = home.get(s.body) ?? [s.x, s.y];
+ return [
+ 140 * Math.sin(s.y * 0.009 + t * 1.7) + (hx - s.x) * 0.35,
+ 110 * Math.cos(s.x * 0.007 - t * 1.3) + (hy - s.y) * 0.6,
+ ];
+ },
+ { bodies: cloudBodies },
+ );
+ world.simulate();
+
+ // Particles glow as they speed up.
+ for (const p of cloud) {
+ const heat = Array.from({ length: DURATION }, (_, f) =>
+ Math.min(1, p.body.speed.get({ frame: f, fps: FPS } as never) / 900),
+ );
+ p.layer.animate(
+ LayerAnimation.create().colorSignal(
+ "fillColor",
+ Signal.fromArray(heat, FPS),
+ {
+ colorA: p.color,
+ colorB: HOT,
+ },
+ ),
+ );
+ }
+
+ comp.add(
+ Layer.box({
+ id: "stage",
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: W,
+ height: H,
+ children: [
+ Layer.video(DANCER, {
+ id: "plate",
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: W,
+ height: H,
+ fit: "cover",
+ }),
+ ...cloud.map((p) => p.layer),
+ Layer.video(DANCER, {
+ id: "cutout",
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: W,
+ height: H,
+ fit: "cover",
+ muted: true,
+ }).withVision({ mode: "matte" }),
+ ...words.map((w) => w.layer),
+ ],
+ }).animate(
+ LayerAnimation.create().signal("y", world.impact, { multiplier: 10 }),
+ ),
+ );
+
+ for (const w of words) {
+ const hit = w.body.collisions[0];
+ console.log(
+ `${w.layer.id}: first contact at frame ${hit?.frame ?? "-"} (${hit?.with.type ?? "none"})`,
+ );
+ }
+ return comp;
+}
diff --git a/examples/28_physics_dancer/src/performer.ts b/examples/28_physics_dancer/src/performer.ts
new file mode 100644
index 00000000..fd81fb14
--- /dev/null
+++ b/examples/28_physics_dancer/src/performer.ts
@@ -0,0 +1,30 @@
+import fs from "node:fs";
+import path from "node:path";
+import { type Composition, PersonTrack } from "framefields";
+import { DANCER, H, TRACK_CACHE, W } from "./theme.js";
+
+/**
+ * The dancer's pose and silhouette for every frame, placed in composition
+ * pixels. Tracking runs once (about 30 s) and is cached in output/.
+ */
+export async function performer(comp: Composition): Promise<PersonTrack> {
+ if (!fs.existsSync(DANCER)) {
+ throw new Error(
+ `Missing ${DANCER}. Generate it with \`pnpm assets\` in examples/19_framefields_film.`,
+ );
+ }
+ let track: PersonTrack;
+ if (fs.existsSync(TRACK_CACHE)) {
+ track = PersonTrack.fromJSON(
+ JSON.parse(fs.readFileSync(TRACK_CACHE, "utf8")),
+ );
+ } else {
+ console.log("Tracking the dancer (pose + silhouette)…");
+ track = await comp.trackPerson(DANCER, {
+ onProgress: (f, n) => f % 40 === 0 && console.log(` ${f}/${n}`),
+ });
+ fs.mkdirSync(path.dirname(TRACK_CACHE), { recursive: true });
+ fs.writeFileSync(TRACK_CACHE, JSON.stringify(track.toJSON()));
+ }
+ return track.place({ width: W, height: H, fit: "cover" });
+}
diff --git a/examples/28_physics_dancer/src/render.ts b/examples/28_physics_dancer/src/render.ts
new file mode 100644
index 00000000..411eafb1
--- /dev/null
+++ b/examples/28_physics_dancer/src/render.ts
@@ -0,0 +1,26 @@
+/**
+ * pnpm render → output/physics-dancer.mp4
+ * pnpm render sim → runs tracking and physics only, prints first contacts
+ *
+ * Frames render in order: the cutout runs vision on the previous frame, so
+ * single frames out of order would show a ghost of another moment.
+ */
+import path from "node:path";
+import { buildFilm } from "./film.js";
+import { OUTPUT } from "./theme.js";
+
+const [mode = "video"] = process.argv.slice(2);
+const film = await buildFilm();
+
+if (mode !== "sim") {
+ const started = Date.now();
+ const result = await film.renderVideo({
+ outputPath: path.join(OUTPUT, "physics-dancer.mp4"),
+ quality: "high",
+ });
+ await result.cleanup?.().catch(() => {});
+ console.log(
+ `${result.filePath} (${((Date.now() - started) / 1000).toFixed(1)} s)`,
+ );
+}
+process.exit(0);
diff --git a/examples/28_physics_dancer/src/theme.ts b/examples/28_physics_dancer/src/theme.ts
new file mode 100644
index 00000000..df8fd0c0
--- /dev/null
+++ b/examples/28_physics_dancer/src/theme.ts
@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { FontManager } from "framefields";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const FONTS = path.resolve(HERE, "../assets/fonts");
+export const OUTPUT = path.resolve(HERE, "../output");
+/** The dancer clip from example 19 (generated there by `pnpm assets`). */
+export const DANCER = path.resolve(
+ HERE,
+ "../../19_framefields_film/assets/dancer.mp4",
+);
+/** Pose + silhouette analysis of the clip, cached after the first run. */
+export const TRACK_CACHE = path.join(OUTPUT, "dancer-track.json");
+
+export const W = 1920;
+export const H = 1080;
+export const FPS = 24;
+/** The clip: 6.6 s at 24 fps. */
+export const DURATION = 158;
+/** The studio floor line in the clip, px. */
+export const FLOOR = 1012;
+
+export const INK = "#1E1512";
+export const RUST = "#7A2E14";
+export const EMBER = "#FF5A1F";
+export const CREAM = "#FFF4E0";
+export const GOLD = "#F2B33D";
+export const VIOLET = "#5B3DF5";
+export const HOT = "#FFE7B0";
+
+export const FONT_FILE = path.join(FONTS, "Syne.ttf");
+
+export async function registerFonts(): Promise<void> {
+ if (!fs.existsSync(FONT_FILE)) {
+ throw new Error(`Missing ${FONT_FILE}. Run \`pnpm fonts\` first.`);
+ }
+ await FontManager.register({ family: "Syne", source: FONT_FILE });
+}
diff --git a/examples/28_physics_dancer/tsconfig.dev.json b/examples/28_physics_dancer/tsconfig.dev.json
new file mode 100644
index 00000000..c5e4355b
--- /dev/null
+++ b/examples/28_physics_dancer/tsconfig.dev.json
@@ -0,0 +1,9 @@
+{
+ "extends": "./tsconfig.json",
+ "include": [
+ "src/**/*",
+ "../../nodes/**/*",
+ "../../packages/**/*",
+ "../../node_modules/@framefields/**/*"
+ ]
+}
diff --git a/examples/28_physics_dancer/tsconfig.json b/examples/28_physics_dancer/tsconfig.json
new file mode 100644
index 00000000..999801f9
--- /dev/null
+++ b/examples/28_physics_dancer/tsconfig.json
@@ -0,0 +1,10 @@
+{
+ "extends": "@framefields/tsconfig/base.json",
+ "compilerOptions": {
+ "module": "NodeNext",
+ "moduleResolution": "NodeNext",
+ "target": "ES2022",
+ "noEmit": true
+ },
+ "include": ["src/**/*"]
+}
diff --git a/packages/framefields/package.json b/packages/framefields/package.json
index 5bced045..64b74ecb 100644
--- a/packages/framefields/package.json
+++ b/packages/framefields/package.json
@@ -109,6 +109,8 @@
"zod": "^4.3.6"
},
"optionalDependencies": {
+ "@dimforge/rapier2d-deterministic-compat": "0.21.0",
+ "@dimforge/rapier3d-deterministic-compat": "0.21.0",
"onnxruntime-web": "^1.24.0"
},
"devDependencies": {
diff --git a/packages/framefields/src/index.ts b/packages/framefields/src/index.ts
index 86afb25a..2b870ab4 100644
--- a/packages/framefields/src/index.ts
+++ b/packages/framefields/src/index.ts
@@ -240,6 +240,11 @@ import {
Vision,
type VisionProps,
} from "./effects/index.js";
+import {
+ type PersonTrack,
+ type TrackPersonOptions,
+ trackPerson,
+} from "./person-track.js";
import {
type FrameGridOptions,
HeadlessMediaRenderer,
@@ -785,6 +790,39 @@ export {
type LightingRig,
type LightingRigOptions,
} from "./lighting.js";
+export {
+ PersonTrack,
+ type PersonTrackJSON,
+ type PersonTrackPlacement,
+ type PoseKeypointName,
+ type TrackPersonOptions,
+} from "./person-track.js";
+export {
+ type Body2DOptions,
+ type Body3DOptions,
+ type BodyCommonOptions,
+ type FieldSample2D,
+ type FieldSample3D,
+ Physics,
+ type PhysicsBakeOptions,
+ PhysicsBody2D,
+ PhysicsBody3D,
+ type PhysicsBox3D,
+ type PhysicsCollision,
+ type PhysicsDriver,
+ type PhysicsGroundOptions,
+ type PhysicsRect,
+ type PhysicsRope3DOptions,
+ type PhysicsRopeOptions,
+ type PhysicsSpring3DOptions,
+ type PhysicsSpringOptions,
+ type PhysicsWallsOptions,
+ PhysicsWorld2D,
+ PhysicsWorld3D,
+ type PhysicsWorldOptions,
+ type World2DOptions,
+ type World3DOptions,
+} from "./physics/index.js";
export {
type Carousel3DOptions,
type Cube3DOptions,
@@ -1106,6 +1144,25 @@ export class Composition {
return this._visionBundle;
}
+ /**
+ * Tracks one person through a clip before rendering: smoothed pose
+ * keypoints and a soft silhouette per frame (see {@link PersonTrack}).
+ * Use it to drive physics with a performer (limbs as kinematic bodies,
+ * the silhouette as a force field) or to keyframe things to a body.
+ * Analysis takes a few hundred ms per frame; cache it with `toJSON()` /
+ * `PersonTrack.fromJSON()`.
+ */
+ public async trackPerson(
+ source: string,
+ options: TrackPersonOptions = {},
+ ): Promise<PersonTrack> {
+ const fps = options.fps ?? this.fps;
+ const durationMs = this.durationMs ?? (await this.computeDuration());
+ const totalFrames =
+ options.totalFrames ?? Math.max(1, Math.round((durationMs / 1000) * fps));
+ return trackPerson(source, { ...options, fps, totalFrames });
+ }
+
/**
* One-shot, ffmpeg-free vision analysis of a media source.
*
diff --git a/packages/framefields/src/person-track.test.ts b/packages/framefields/src/person-track.test.ts
new file mode 100644
index 00000000..51abd185
--- /dev/null
+++ b/packages/framefields/src/person-track.test.ts
@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import { PersonTrack, type PersonTrackJSON } from "./index.js";
+
+/** Two frames of a 160×80 clip: a wrist moving right, a 40×40 square silhouette moving right. */
+function synthetic(): PersonTrack {
+ const frames = 2;
+ const keypoints = new Array(frames * 17 * 3).fill(0);
+ const set = (f: number, k: number, x: number, y: number) =>
+ keypoints.splice((f * 17 + k) * 3, 3, x, y, 1);
+ set(0, 9, 20, 10); // leftWrist
+ set(1, 9, 60, 30);
+ const cell = 4;
+ const w = 40;
+ const h = 20;
+ const mask = new Uint8Array(frames * w * h);
+ for (let f = 0; f < frames; f++) {
+ for (let y = 5; y < 15; y++)
+ for (let x = 5 + f * 10; x < 15 + f * 10; x++)
+ mask[f * w * h + y * w + x] = 255;
+ }
+ const json: PersonTrackJSON = {
+ version: 1,
+ fps: 24,
+ frames,
+ sourceWidth: 160,
+ sourceHeight: 80,
+ keypoints,
+ mask: {
+ cell,
+ width: w,
+ height: h,
+ data: Buffer.from(mask).toString("base64"),
+ },
+ };
+ return PersonTrack.fromJSON(JSON.parse(JSON.stringify(json)));
+}
+
+describe("PersonTrack", () => {
+ it("interpolates keypoints and maps them into a layer box", () => {
+ const t = synthetic();
+ expect(t.point("leftWrist", 0.5)).toMatchObject({
+ x: 40,
+ y: 20,
+ visibility: 1,
+ });
+ // 160×80 covering 320×320 at (100, 0): scale 4, centered → x offset 100 − 160.
+ const placed = t.place({
+ x: 100,
+ y: 0,
+ width: 320,
+ height: 320,
+ fit: "cover",
+ });
+ expect(placed.point("leftWrist", 0)).toMatchObject({
+ x: 100 - 160 + 80,
+ y: 40,
+ });
+ const sig = placed.signals("leftWrist");
+ expect(sig.x.get({ frame: 1, fps: 24 } as never)).toBeCloseTo(
+ 100 - 160 + 240,
+ );
+ });
+
+ it("samples the silhouette with a gradient pointing inward", () => {
+ const t = synthetic();
+ // Frame 0 square spans source px 20–60 × 20–60.
+ expect(t.sample(0, 40, 40).alpha).toBeGreaterThan(0.9);
+ expect(t.sample(0, 120, 40).alpha).toBe(0);
+ const edge = t.sample(0, 62, 40);
+ expect(edge.alpha).toBeGreaterThan(0);
+ expect(edge.gx).toBeLessThan(0); // inside is to the left
+ expect(t.sample(1, 40, 40).alpha).toBeLessThan(t.sample(1, 80, 40).alpha);
+ });
+
+ it("round-trips through JSON", () => {
+ const t = synthetic();
+ const again = PersonTrack.fromJSON(t.toJSON());
+ expect(again.point("leftWrist", 1)).toEqual(t.point("leftWrist", 1));
+ expect(again.sample(0, 40, 40)).toEqual(t.sample(0, 40, 40));
+ });
+});
diff --git a/packages/framefields/src/person-track.ts b/packages/framefields/src/person-track.ts
new file mode 100644
index 00000000..8001a196
--- /dev/null
+++ b/packages/framefields/src/person-track.ts
@@ -0,0 +1,511 @@
+import { type FrameSignal, Signal } from "@framefields/core";
+import { COCO17_KEYPOINT_NAMES, VisionRunner } from "@framefields/vision";
+import { mediaDecoderCache } from "@framefields/webgpu-renderers";
+import type { VisionProps } from "./effects/index.js";
+
+export type PoseKeypointName = (typeof COCO17_KEYPOINT_NAMES)[number];
+
+export interface TrackPersonOptions {
+ /** Frames per second to sample (default: the composition's). */
+ fps?: number;
+ /** How many frames (default: the composition's length). */
+ totalFrames?: number;
+ /** Track 17 COCO keypoints (default true). */
+ pose?: boolean;
+ /** Track the person's silhouette, dress and held things included (default true). */
+ mask?: boolean;
+ /** Silhouette cell size in source pixels (default 8: a 1920×1080 clip gives a 240×135 grid). */
+ maskCell?: number;
+ /** Frames of zero-lag smoothing on keypoints (default 2; 0 for raw). */
+ smoothing?: number;
+ /** Keypoints below this visibility count as missing and are filled from neighbours (default 0.3). */
+ minVisibility?: number;
+ variant?: VisionProps["variant"];
+ confidence?: number;
+ modelsDir?: string;
+ baseUrl?: string;
+ onProgress?: (frame: number, total: number) => void;
+}
+
+/** Where the clip sits in the composition, like a media layer's box and `fit`. */
+export interface PersonTrackPlacement {
+ x?: number;
+ y?: number;
+ width: number;
+ height: number;
+ fit?: "cover" | "contain" | "fill";
+}
+
+/** Plain-JSON form, for caching an analysis between runs. */
+export interface PersonTrackJSON {
+ version: 1;
+ fps: number;
+ frames: number;
+ sourceWidth: number;
+ sourceHeight: number;
+ /** frames × 17 × [x, y, visibility], source px, smoothed. */
+ keypoints?: number[];
+ mask?: { cell: number; width: number; height: number; data: string };
+}
+
+interface Transform {
+ sx: number;
+ sy: number;
+ ox: number;
+ oy: number;
+}
+
+const IDENTITY: Transform = { sx: 1, sy: 1, ox: 0, oy: 0 };
+
+/**
+ * One person tracked through a clip ahead of rendering: smoothed pose
+ * keypoints and a soft silhouette, frame by frame. Unlike the render-time
+ * vision signals it is complete before the first frame renders, so it can
+ * drive physics (limbs as kinematic bodies, the silhouette as a force field),
+ * be keyframed, or be inspected. `place()` maps it into composition pixels.
+ */
+export class PersonTrack {
+ readonly fps: number;
+ readonly frames: number;
+ readonly sourceWidth: number;
+ readonly sourceHeight: number;
+ private readonly kp?: Float32Array;
+ private readonly maskData?: {
+ cell: number;
+ width: number;
+ height: number;
+ data: Uint8Array;
+ };
+ private blurred?: Float32Array[];
+
+ private constructor(
+ json: Omit<PersonTrackJSON, "keypoints" | "mask" | "version">,
+ kp: Float32Array | undefined,
+ mask: PersonTrack["maskData"],
+ private readonly t: Transform = IDENTITY,
+ shared?: PersonTrack,
+ ) {
+ this.fps = json.fps;
+ this.frames = json.frames;
+ this.sourceWidth = json.sourceWidth;
+ this.sourceHeight = json.sourceHeight;
+ this.kp = kp;
+ this.maskData = mask;
+ if (shared) this.blurred = shared.blurredMasks();
+ }
+
+ static fromJSON(json: PersonTrackJSON): PersonTrack {
+ const mask = json.mask
+ ? {
+ cell: json.mask.cell,
+ width: json.mask.width,
+ height: json.mask.height,
+ data: new Uint8Array(Buffer.from(json.mask.data, "base64")),
+ }
+ : undefined;
+ return new PersonTrack(
+ json,
+ json.keypoints ? Float32Array.from(json.keypoints) : undefined,
+ mask,
+ );
+ }
+
+ toJSON(): PersonTrackJSON {
+ const m = this.maskData;
+ return {
+ version: 1,
+ fps: this.fps,
+ frames: this.frames,
+ sourceWidth: this.sourceWidth,
+ sourceHeight: this.sourceHeight,
+ ...(this.kp && {
+ keypoints: Array.from(this.kp, (v) => Math.round(v * 100) / 100),
+ }),
+ ...(m && {
+ mask: {
+ cell: m.cell,
+ width: m.width,
+ height: m.height,
+ data: Buffer.from(m.data).toString("base64"),
+ },
+ }),
+ };
+ }
+
+ /** The same track in composition pixels for a clip laid out at `placement`. */
+ place(placement: PersonTrackPlacement): PersonTrack {
+ const { width: W, height: H } = placement;
+ const sw = this.sourceWidth;
+ const sh = this.sourceHeight;
+ let sx = W / sw;
+ let sy = H / sh;
+ if (placement.fit !== "fill") {
+ const s =
+ placement.fit === "contain" ? Math.min(sx, sy) : Math.max(sx, sy);
+ sx = s;
+ sy = s;
+ }
+ const t: Transform = {
+ sx,
+ sy,
+ ox: (placement.x ?? 0) + (W - sw * sx) / 2,
+ oy: (placement.y ?? 0) + (H - sh * sy) / 2,
+ };
+ return new PersonTrack(this, this.kp, this.maskData, t, this);
+ }
+
+ /** Whether the clip had pose / silhouette tracking. */
+ get hasPose(): boolean {
+ return this.kp !== undefined;
+ }
+ get hasMask(): boolean {
+ return this.maskData !== undefined;
+ }
+
+ /** A keypoint at a frame (fractional frames interpolate), placed px. */
+ point(
+ name: PoseKeypointName,
+ frame: number,
+ ): { x: number; y: number; visibility: number } {
+ const kp = this.requirePose();
+ const k = keypointIndex(name);
+ const f = Math.max(0, Math.min(this.frames - 1, frame));
+ const f0 = Math.floor(f);
+ const f1 = Math.min(this.frames - 1, f0 + 1);
+ const u = f - f0;
+ const at = (fi: number, c: number) => kp[(fi * 17 + k) * 3 + c];
+ const lerp = (c: number) => at(f0, c) + (at(f1, c) - at(f0, c)) * u;
+ return {
+ x: lerp(0) * this.t.sx + this.t.ox,
+ y: lerp(1) * this.t.sy + this.t.oy,
+ visibility: lerp(2),
+ };
+ }
+
+ /** Per-frame signals for a keypoint (placed px), for `.signal("x", …)` or physics `follow`. */
+ signals(
+ name: PoseKeypointName,
+ options: { startFrame?: number } = {},
+ ): {
+ x: FrameSignal<number>;
+ y: FrameSignal<number>;
+ visibility: FrameSignal<number>;
+ } {
+ const start = options.startFrame ?? 0;
+ const x = new Float32Array(start + this.frames);
+ const y = new Float32Array(start + this.frames);
+ const v = new Float32Array(start + this.frames);
+ for (let f = 0; f < start + this.frames; f++) {
+ const p = this.point(name, f - start);
+ x[f] = p.x;
+ y[f] = p.y;
+ v[f] = p.visibility;
+ }
+ return {
+ x: Signal.fromArray(x, this.fps),
+ y: Signal.fromArray(y, this.fps),
+ visibility: Signal.fromArray(v, this.fps),
+ };
+ }
+
+ /**
+ * The silhouette near a point (placed px) at a frame: `alpha` 0–1 (softened
+ * over a few cells), and its gradient `gx`, `gy` per px, pointing into the
+ * body. Push things out with `-gradient`; `alpha > 0.5` is inside.
+ */
+ sample(
+ frame: number,
+ x: number,
+ y: number,
+ ): { alpha: number; gx: number; gy: number } {
+ const m = this.requireMask();
+ const grids = this.blurredMasks();
+ const fi = Math.max(0, Math.min(this.frames - 1, Math.round(frame)));
+ const grid = grids[fi];
+ // Placed px → mask cells.
+ const cx = (x - this.t.ox) / this.t.sx / m.cell - 0.5;
+ const cy = (y - this.t.oy) / this.t.sy / m.cell - 0.5;
+ const read = (gx: number, gy: number) => {
+ if (gx < 0 || gy < 0 || gx >= m.width || gy >= m.height) return 0;
+ return grid[gy * m.width + gx];
+ };
+ const bil = (px: number, py: number) => {
+ const x0 = Math.floor(px);
+ const y0 = Math.floor(py);
+ const ux = px - x0;
+ const uy = py - y0;
+ const a = read(x0, y0) + (read(x0 + 1, y0) - read(x0, y0)) * ux;
+ const b =
+ read(x0, y0 + 1) + (read(x0 + 1, y0 + 1) - read(x0, y0 + 1)) * ux;
+ return a + (b - a) * uy;
+ };
+ const alpha = bil(cx, cy);
+ const pxPerCellX = m.cell * this.t.sx;
+ const pxPerCellY = m.cell * this.t.sy;
+ return {
+ alpha,
+ gx: (bil(cx + 1, cy) - bil(cx - 1, cy)) / (2 * pxPerCellX),
+ gy: (bil(cx, cy + 1) - bil(cx, cy - 1)) / (2 * pxPerCellY),
+ };
+ }
+
+ private requirePose(): Float32Array {
+ if (!this.kp) throw new Error("PersonTrack: tracked without `pose`.");
+ return this.kp;
+ }
+
+ private requireMask(): NonNullable<PersonTrack["maskData"]> {
+ if (!this.maskData) throw new Error("PersonTrack: tracked without `mask`.");
+ return this.maskData;
+ }
+
+ /** Silhouette per frame, softened by a small box blur so gradients reach past the edge. */
+ private blurredMasks(): Float32Array[] {
+ if (this.blurred) return this.blurred;
+ const m = this.requireMask();
+ const { width: w, height: h } = m;
+ const r = 2;
+ const out: Float32Array[] = [];
+ const tmp = new Float32Array(w * h);
+ for (let f = 0; f < this.frames; f++) {
+ const src = m.data.subarray(f * w * h, (f + 1) * w * h);
+ const dst = new Float32Array(w * h);
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ let s = 0;
+ let n = 0;
+ for (let k = -r; k <= r; k++) {
+ const xx = x + k;
+ if (xx >= 0 && xx < w) {
+ s += src[y * w + xx];
+ n++;
+ }
+ }
+ tmp[y * w + x] = s / n / 255;
+ }
+ }
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ let s = 0;
+ let n = 0;
+ for (let k = -r; k <= r; k++) {
+ const yy = y + k;
+ if (yy >= 0 && yy < h) {
+ s += tmp[yy * w + x];
+ n++;
+ }
+ }
+ dst[y * w + x] = s / n;
+ }
+ }
+ out.push(dst);
+ }
+ this.blurred = out;
+ return out;
+ }
+
+ /** @internal */
+ static fromAnalysis(
+ meta: {
+ fps: number;
+ frames: number;
+ sourceWidth: number;
+ sourceHeight: number;
+ },
+ kp: Float32Array | undefined,
+ mask: PersonTrack["maskData"],
+ ): PersonTrack {
+ return new PersonTrack(meta, kp, mask);
+ }
+}
+
+function keypointIndex(name: PoseKeypointName): number {
+ const i = COCO17_KEYPOINT_NAMES.indexOf(name);
+ if (i < 0) {
+ throw new Error(
+ `PersonTrack: unknown keypoint "${name}". Use one of ${COCO17_KEYPOINT_NAMES.join(", ")}.`,
+ );
+ }
+ return i;
+}
+
+/** Runs pose and segmentation over a clip and returns a {@link PersonTrack}. */
+export async function trackPerson(
+ source: string,
+ options: TrackPersonOptions & { fps: number; totalFrames: number },
+): Promise<PersonTrack> {
+ const { fps, totalFrames } = options;
+ const wantPose = options.pose ?? true;
+ const wantMask = options.mask ?? true;
+ const cell = Math.max(1, Math.round(options.maskCell ?? 8));
+ const minVis = options.minVisibility ?? 0.3;
+ const runner = VisionRunner.create({
+ modelsDir: options.modelsDir,
+ baseUrl: options.baseUrl,
+ ...(options.confidence !== undefined && { confidence: options.confidence }),
+ ...(options.variant !== undefined && { variant: options.variant }),
+ });
+ const decoder = mediaDecoderCache.getVideo(source, true);
+
+ let sourceWidth = 0;
+ let sourceHeight = 0;
+ const kp = wantPose ? new Float32Array(totalFrames * 17 * 3) : undefined;
+ let maskW = 0;
+ let maskH = 0;
+ let maskData: Uint8Array | undefined;
+
+ try {
+ for (let i = 0; i < totalFrames; i++) {
+ const decoded = await decoder.getFrame(i / fps);
+ if (!decoded?.buffer || decoded.width <= 0) continue;
+ const frame = {
+ data: decoded.buffer,
+ width: decoded.width,
+ height: decoded.height,
+ };
+ if (!sourceWidth) {
+ sourceWidth = frame.width;
+ sourceHeight = frame.height;
+ maskW = Math.ceil(sourceWidth / cell);
+ maskH = Math.ceil(sourceHeight / cell);
+ if (wantMask) maskData = new Uint8Array(totalFrames * maskW * maskH);
+ }
+ if (kp) {
+ const { people } = await runner.pose(frame);
+ const person = people[0];
+ if (person) {
+ person.keypoints.forEach((p, k) => {
+ kp.set([p.x, p.y, p.visibility], (i * 17 + k) * 3);
+ });
+ }
+ }
+ if (maskData) {
+ const seg = await runner.segment(frame);
+ const union = personSilhouette(seg);
+ if (union)
+ downsampleMean(
+ union,
+ frame.width,
+ frame.height,
+ cell,
+ maskData,
+ i * maskW * maskH,
+ maskW,
+ maskH,
+ );
+ }
+ options.onProgress?.(i + 1, totalFrames);
+ }
+ } finally {
+ runner.close();
+ decoder.destroy();
+ }
+ if (!sourceWidth)
+ throw new Error(`trackPerson: could not decode any frame of "${source}".`);
+ if (kp) smoothKeypoints(kp, totalFrames, minVis, options.smoothing ?? 2);
+
+ return PersonTrack.fromAnalysis(
+ { fps, frames: totalFrames, sourceWidth, sourceHeight },
+ kp,
+ maskData && { cell, width: maskW, height: maskH, data: maskData },
+ );
+}
+
+type Segmentation = Awaited<ReturnType<VisionRunner["segment"]>>;
+
+/**
+ * The largest person's mask, plus instances that overlap it and are no more
+ * than twice its size (a flowing dress often comes back as "kite").
+ */
+function personSilhouette(seg: Segmentation): Uint8Array | undefined {
+ const people = seg.masks.filter((m) => m.category === "person");
+ if (people.length === 0) return undefined;
+ const person = people.reduce((a, b) => (b.area > a.area ? b : a));
+ const box = seg.detections[person.detectionIndex]?.boundingBox;
+ const out = new Uint8Array(person.mask);
+ if (!box) return out;
+ for (const m of seg.masks) {
+ if (m === person || m.area > person.area * 2) continue;
+ const b = seg.detections[m.detectionIndex]?.boundingBox;
+ if (!b) continue;
+ const ix = Math.max(
+ 0,
+ Math.min(box.originX + box.width, b.originX + b.width) -
+ Math.max(box.originX, b.originX),
+ );
+ const iy = Math.max(
+ 0,
+ Math.min(box.originY + box.height, b.originY + b.height) -
+ Math.max(box.originY, b.originY),
+ );
+ if (ix * iy < 0.3 * b.width * b.height) continue;
+ for (let i = 0; i < out.length; i++)
+ if (m.mask[i] > out[i]) out[i] = m.mask[i];
+ }
+ return out;
+}
+
+function downsampleMean(
+ src: Uint8Array,
+ w: number,
+ h: number,
+ cell: number,
+ dst: Uint8Array,
+ offset: number,
+ mw: number,
+ mh: number,
+): void {
+ for (let my = 0; my < mh; my++) {
+ for (let mx = 0; mx < mw; mx++) {
+ let sum = 0;
+ let n = 0;
+ for (let y = my * cell; y < Math.min(h, (my + 1) * cell); y++) {
+ for (let x = mx * cell; x < Math.min(w, (mx + 1) * cell); x++) {
+ sum += src[y * w + x];
+ n++;
+ }
+ }
+ dst[offset + my * mw + mx] = n ? Math.round(sum / n) : 0;
+ }
+ }
+}
+
+/**
+ * Fills missing keypoints from their nearest seen frames, then runs a
+ * forward and a backward exponential filter (no lag, no overshoot).
+ */
+function smoothKeypoints(
+ kp: Float32Array,
+ frames: number,
+ minVis: number,
+ smoothing: number,
+): void {
+ for (let k = 0; k < 17; k++) {
+ const idx = (f: number, c: number) => (f * 17 + k) * 3 + c;
+ const seen: number[] = [];
+ for (let f = 0; f < frames; f++) if (kp[idx(f, 2)] >= minVis) seen.push(f);
+ if (seen.length === 0) continue;
+ let s = 0;
+ for (let f = 0; f < frames; f++) {
+ if (kp[idx(f, 2)] >= minVis) continue;
+ while (s + 1 < seen.length && seen[s + 1] < f) s++;
+ const a = seen[s];
+ const b = seen.find((v) => v > f);
+ for (const c of [0, 1]) {
+ if (f < a || b === undefined) kp[idx(f, c)] = kp[idx(a, c)];
+ else {
+ const u = (f - a) / (b - a);
+ kp[idx(f, c)] = kp[idx(a, c)] + (kp[idx(b, c)] - kp[idx(a, c)]) * u;
+ }
+ }
+ }
+ if (smoothing <= 0) continue;
+ const alpha = 1 / (1 + smoothing);
+ for (const c of [0, 1]) {
+ for (let f = 1; f < frames; f++)
+ kp[idx(f, c)] += (kp[idx(f - 1, c)] - kp[idx(f, c)]) * (1 - alpha);
+ for (let f = frames - 2; f >= 0; f--)
+ kp[idx(f, c)] += (kp[idx(f + 1, c)] - kp[idx(f, c)]) * (1 - alpha);
+ }
+ }
+}
diff --git a/packages/framefields/src/physics/backend.ts b/packages/framefields/src/physics/backend.ts
new file mode 100644
index 00000000..4b99c277
--- /dev/null
+++ b/packages/framefields/src/physics/backend.ts
@@ -0,0 +1,474 @@
+/**
+ * The simulation backend the physics worlds drive. Worlds talk to this
+ * engine-neutral surface only, so another solver can be dropped in later;
+ * Rapier (deterministic builds, identical results on every platform) is the
+ * one shipped. Units here are SI: meters, radians, seconds, y down.
+ */
+import type RAPIER2D from "@dimforge/rapier2d-deterministic-compat";
+import type RAPIER3D from "@dimforge/rapier3d-deterministic-compat";
+
+export type Vec2 = [number, number];
+export type Vec3 = [number, number, number];
+/** Quaternion as [x, y, z, w]. */
+export type Quat = [number, number, number, number];
+
+export type BodyType = "dynamic" | "fixed" | "kinematic";
+
+interface MaterialSpec {
+ density: number;
+ friction: number;
+ restitution: number;
+}
+
+export type Shape2D =
+ | { kind: "box"; hx: number; hy: number; radius?: number }
+ | { kind: "ball"; radius: number }
+ /** Flat [x0, y0, x1, y1, …] around the body origin. */
+ | { kind: "hull"; points: number[] };
+
+export type Shape3D =
+ | { kind: "box"; hx: number; hy: number; hz: number; radius?: number }
+ | { kind: "ball"; radius: number }
+ /** Axis along y. */
+ | { kind: "cylinder"; halfHeight: number; radius: number }
+ /** Flat [x0, y0, z0, …] around the body origin. */
+ | { kind: "hull"; points: number[] };
+
+interface BodySpecBase extends MaterialSpec {
+ type: BodyType;
+ linearDamping: number;
+ angularDamping: number;
+ gravityScale: number;
+ lockRotation: boolean;
+ ccd: boolean;
+ enabled: boolean;
+ /** Touches nothing (joint anchors). */
+ sensor?: boolean;
+}
+
+export interface BodySpec2D extends BodySpecBase {
+ position: Vec2;
+ angle: number;
+ velocity: Vec2;
+ angularVelocity: number;
+ shape: Shape2D;
+}
+
+export interface BodySpec3D extends BodySpecBase {
+ position: Vec3;
+ rotation: Quat;
+ velocity: Vec3;
+ angularVelocity: Vec3;
+ shape: Shape3D;
+}
+
+export type JointSpec<V> =
+ | { type: "revolute"; anchorA: V; anchorB: V; axis?: Vec3 }
+ | { type: "spherical"; anchorA: V; anchorB: V }
+ | { type: "fixed"; anchorA: V; anchorB: V }
+ | { type: "rope"; anchorA: V; anchorB: V; length: number }
+ | {
+ type: "spring";
+ anchorA: V;
+ anchorB: V;
+ restLength: number;
+ stiffness: number;
+ damping: number;
+ };
+
+export interface SimBody<V, R> {
+ position(): V;
+ rotation(): R;
+ velocity(): V;
+ /** 2D: rad/s; 3D: rad/s per axis. */
+ angularVelocity(): R extends number ? number : Vec3;
+ sleeping(): boolean;
+ mass(): number;
+ setEnabled(enabled: boolean): void;
+ applyImpulse(impulse: V): void;
+ setKinematicTarget(position: V, rotation: R): void;
+}
+
+export type SimBody2D = SimBody<Vec2, number>;
+export type SimBody3D = SimBody<Vec3, Quat>;
+
+export interface SimWorld<V, B, S> {
+ addBody(spec: S): B;
+ addJoint(a: B, b: B, spec: JointSpec<V>): void;
+ step(dt: number): void;
+ /** Pairs that started touching during the last step. */
+ drainCollisionStarts(): Array<[B, B]>;
+ free(): void;
+}
+
+export type SimWorld2D = SimWorld<Vec2, SimBody2D, BodySpec2D>;
+export type SimWorld3D = SimWorld<Vec3, SimBody3D, BodySpec3D>;
+
+export interface PhysicsBackend {
+ createWorld2D(gravity: Vec2): SimWorld2D;
+ createWorld3D(gravity: Vec3): SimWorld3D;
+}
+
+// ---------------------------------------------------------------------------
+// Rapier
+// ---------------------------------------------------------------------------
+
+type Rapier2D = typeof RAPIER2D;
+type Rapier3D = typeof RAPIER3D;
+
+// Variable specifiers keep bundlers from inlining the optional WASM packages.
+const RAPIER_2D = "@dimforge/rapier2d-deterministic-compat";
+const RAPIER_3D = "@dimforge/rapier3d-deterministic-compat";
+
+async function loadRapier<T>(specifier: string): Promise<T> {
+ let mod: { default?: T } & T;
+ try {
+ mod = (await import(/* @vite-ignore */ specifier)) as { default?: T } & T;
+ } catch (error) {
+ throw new Error(
+ `Physics needs the optional dependency "${specifier}". Install it with \`npm i ${specifier}\`.`,
+ { cause: error },
+ );
+ }
+ const rapier = (mod.default ?? mod) as T & { init(): Promise<void> };
+ await rapier.init();
+ return rapier;
+}
+
+let rapier2d: Promise<Rapier2D> | undefined;
+let rapier3d: Promise<Rapier3D> | undefined;
+
+/** Loads and initializes Rapier once per process; 2D and 3D are separate modules. */
+export async function rapierBackend(dims: 2 | 3): Promise<PhysicsBackend> {
+ if (dims === 2) {
+ rapier2d ??= loadRapier<Rapier2D>(RAPIER_2D);
+ const R = await rapier2d;
+ return {
+ createWorld2D: (gravity) => new RapierWorld2D(R, gravity),
+ createWorld3D: () => {
+ throw new Error("This backend was loaded for 2D.");
+ },
+ };
+ }
+ rapier3d ??= loadRapier<Rapier3D>(RAPIER_3D);
+ const R = await rapier3d;
+ return {
+ createWorld2D: () => {
+ throw new Error("This backend was loaded for 3D.");
+ },
+ createWorld3D: (gravity) => new RapierWorld3D(R, gravity),
+ };
+}
+
+class RapierWorld2D implements SimWorld2D {
+ private readonly world: RAPIER2D.World;
+ private readonly events: RAPIER2D.EventQueue;
+ private readonly byCollider = new Map<number, SimBody2D>();
+ private readonly started: Array<[SimBody2D, SimBody2D]> = [];
+
+ constructor(
+ private readonly R: Rapier2D,
+ gravity: Vec2,
+ ) {
+ this.world = new R.World({ x: gravity[0], y: gravity[1] });
+ this.events = new R.EventQueue(true);
+ }
+
+ addBody(spec: BodySpec2D): SimBody2D {
+ const R = this.R;
+ const desc = bodyDesc(R, spec.type)
+ .setTranslation(spec.position[0], spec.position[1])
+ .setRotation(spec.angle)
+ .setLinvel(spec.velocity[0], spec.velocity[1])
+ .setAngvel(spec.angularVelocity)
+ .setLinearDamping(spec.linearDamping)
+ .setAngularDamping(spec.angularDamping)
+ .setGravityScale(spec.gravityScale)
+ .setCcdEnabled(spec.ccd)
+ .setEnabled(spec.enabled);
+ if (spec.lockRotation) desc.lockRotations();
+ const body = this.world.createRigidBody(desc);
+ const collider = this.world.createCollider(
+ shapeDesc2D(R, spec.shape)
+ .setDensity(spec.density)
+ .setFriction(spec.friction)
+ .setRestitution(spec.restitution)
+ .setActiveEvents(R.ActiveEvents.COLLISION_EVENTS)
+ .setSensor(spec.sensor ?? false),
+ body,
+ );
+ const sim: SimBody2D & { raw: RAPIER2D.RigidBody } = {
+ raw: body,
+ position: () => {
+ const t = body.translation();
+ return [t.x, t.y];
+ },
+ rotation: () => body.rotation(),
+ velocity: () => {
+ const v = body.linvel();
+ return [v.x, v.y];
+ },
+ angularVelocity: () => body.angvel(),
+ sleeping: () => body.isSleeping(),
+ mass: () => body.mass(),
+ setEnabled: (on) => body.setEnabled(on),
+ applyImpulse: ([x, y]) => body.applyImpulse({ x, y }, true),
+ setKinematicTarget: ([x, y], angle) => {
+ body.setNextKinematicTranslation({ x, y });
+ body.setNextKinematicRotation(angle);
+ },
+ };
+ this.byCollider.set(collider.handle, sim);
+ return sim;
+ }
+
+ addJoint(a: SimBody2D, b: SimBody2D, spec: JointSpec<Vec2>): void {
+ const R = this.R;
+ const a1 = { x: spec.anchorA[0], y: spec.anchorA[1] };
+ const a2 = { x: spec.anchorB[0], y: spec.anchorB[1] };
+ let data: RAPIER2D.JointData;
+ switch (spec.type) {
+ case "revolute":
+ case "spherical":
+ data = R.JointData.revolute(a1, a2);
+ break;
+ case "fixed":
+ data = R.JointData.fixed(a1, 0, a2, 0);
+ break;
+ case "rope":
+ data = R.JointData.rope(spec.length, a1, a2);
+ break;
+ case "spring":
+ data = R.JointData.spring(
+ spec.restLength,
+ spec.stiffness,
+ spec.damping,
+ a1,
+ a2,
+ );
+ break;
+ }
+ // Jointed bodies pass through each other where they meet.
+ this.world
+ .createImpulseJoint(data, rawBody(a), rawBody(b), true)
+ .setContactsEnabled(false);
+ }
+
+ step(dt: number): void {
+ this.world.timestep = dt;
+ this.world.step(this.events);
+ this.events.drainCollisionEvents((h1, h2, started) => {
+ if (!started) return;
+ const a = this.byCollider.get(h1);
+ const b = this.byCollider.get(h2);
+ if (a && b) this.started.push([a, b]);
+ });
+ }
+
+ drainCollisionStarts(): Array<[SimBody2D, SimBody2D]> {
+ return this.started.splice(0);
+ }
+
+ free(): void {
+ this.events.free();
+ this.world.free();
+ }
+}
+
+class RapierWorld3D implements SimWorld3D {
+ private readonly world: RAPIER3D.World;
+ private readonly events: RAPIER3D.EventQueue;
+ private readonly byCollider = new Map<number, SimBody3D>();
+ private readonly started: Array<[SimBody3D, SimBody3D]> = [];
+
+ constructor(
+ private readonly R: Rapier3D,
+ gravity: Vec3,
+ ) {
+ this.world = new R.World({ x: gravity[0], y: gravity[1], z: gravity[2] });
+ this.events = new R.EventQueue(true);
+ }
+
+ addBody(spec: BodySpec3D): SimBody3D {
+ const R = this.R;
+ const [qx, qy, qz, qw] = spec.rotation;
+ const desc = bodyDesc(R, spec.type)
+ .setTranslation(spec.position[0], spec.position[1], spec.position[2])
+ .setRotation({ x: qx, y: qy, z: qz, w: qw })
+ .setLinvel(spec.velocity[0], spec.velocity[1], spec.velocity[2])
+ .setAngvel(vec3(spec.angularVelocity))
+ .setLinearDamping(spec.linearDamping)
+ .setAngularDamping(spec.angularDamping)
+ .setGravityScale(spec.gravityScale)
+ .setCcdEnabled(spec.ccd)
+ .setEnabled(spec.enabled);
+ if (spec.lockRotation) desc.lockRotations();
+ const body = this.world.createRigidBody(desc);
+ const shape = shapeDesc3D(R, spec.shape);
+ const collider = this.world.createCollider(
+ shape
+ .setDensity(spec.density)
+ .setFriction(spec.friction)
+ .setRestitution(spec.restitution)
+ .setActiveEvents(R.ActiveEvents.COLLISION_EVENTS)
+ .setSensor(spec.sensor ?? false),
+ body,
+ );
+ const sim: SimBody3D & { raw: RAPIER3D.RigidBody } = {
+ raw: body,
+ position: () => {
+ const t = body.translation();
+ return [t.x, t.y, t.z];
+ },
+ rotation: () => {
+ const q = body.rotation();
+ return [q.x, q.y, q.z, q.w];
+ },
+ velocity: () => {
+ const v = body.linvel();
+ return [v.x, v.y, v.z];
+ },
+ angularVelocity: () => {
+ const w = body.angvel();
+ return [w.x, w.y, w.z];
+ },
+ sleeping: () => body.isSleeping(),
+ mass: () => body.mass(),
+ setEnabled: (on) => body.setEnabled(on),
+ applyImpulse: (v) => body.applyImpulse(vec3(v), true),
+ setKinematicTarget: (p, [x, y, z, w]) => {
+ body.setNextKinematicTranslation(vec3(p));
+ body.setNextKinematicRotation({ x, y, z, w });
+ },
+ };
+ this.byCollider.set(collider.handle, sim);
+ return sim;
+ }
+
+ addJoint(a: SimBody3D, b: SimBody3D, spec: JointSpec<Vec3>): void {
+ const R = this.R;
+ const a1 = vec3(spec.anchorA);
+ const a2 = vec3(spec.anchorB);
+ let data: RAPIER3D.JointData;
+ switch (spec.type) {
+ case "revolute":
+ data = R.JointData.revolute(a1, a2, vec3(spec.axis ?? [0, 0, 1]));
+ break;
+ case "spherical":
+ data = R.JointData.spherical(a1, a2);
+ break;
+ case "fixed": {
+ const identity = { x: 0, y: 0, z: 0, w: 1 };
+ data = R.JointData.fixed(a1, identity, a2, identity);
+ break;
+ }
+ case "rope":
+ data = R.JointData.rope(spec.length, a1, a2);
+ break;
+ case "spring":
+ data = R.JointData.spring(
+ spec.restLength,
+ spec.stiffness,
+ spec.damping,
+ a1,
+ a2,
+ );
+ break;
+ }
+ // Jointed bodies pass through each other where they meet.
+ this.world
+ .createImpulseJoint(data, rawBody(a), rawBody(b), true)
+ .setContactsEnabled(false);
+ }
+
+ step(dt: number): void {
+ this.world.timestep = dt;
+ this.world.step(this.events);
+ this.events.drainCollisionEvents((h1, h2, started) => {
+ if (!started) return;
+ const a = this.byCollider.get(h1);
+ const b = this.byCollider.get(h2);
+ if (a && b) this.started.push([a, b]);
+ });
+ }
+
+ drainCollisionStarts(): Array<[SimBody3D, SimBody3D]> {
+ return this.started.splice(0);
+ }
+
+ free(): void {
+ this.events.free();
+ this.world.free();
+ }
+}
+
+function vec3([x, y, z]: Vec3): { x: number; y: number; z: number } {
+ return { x, y, z };
+}
+
+function rawBody<T>(body: unknown): T {
+ return (body as { raw: T }).raw;
+}
+
+function bodyDesc<R extends Rapier2D | Rapier3D>(
+ R: R,
+ type: BodyType,
+): ReturnType<R["RigidBodyDesc"]["dynamic"]> {
+ const D = R.RigidBodyDesc;
+ const desc =
+ type === "fixed"
+ ? D.fixed()
+ : type === "kinematic"
+ ? D.kinematicPositionBased()
+ : D.dynamic();
+ return desc as ReturnType<R["RigidBodyDesc"]["dynamic"]>;
+}
+
+function shapeDesc2D(R: Rapier2D, shape: Shape2D): RAPIER2D.ColliderDesc {
+ switch (shape.kind) {
+ case "ball":
+ return R.ColliderDesc.ball(shape.radius);
+ case "box": {
+ const r = Math.min(shape.radius ?? 0, shape.hx, shape.hy);
+ return r > 0
+ ? R.ColliderDesc.roundCuboid(shape.hx - r, shape.hy - r, r)
+ : R.ColliderDesc.cuboid(shape.hx, shape.hy);
+ }
+ case "hull": {
+ const desc = R.ColliderDesc.convexHull(new Float32Array(shape.points));
+ if (!desc)
+ throw new Error(
+ "Physics: could not build a convex hull for this shape.",
+ );
+ return desc;
+ }
+ }
+}
+
+function shapeDesc3D(R: Rapier3D, shape: Shape3D): RAPIER3D.ColliderDesc {
+ switch (shape.kind) {
+ case "ball":
+ return R.ColliderDesc.ball(shape.radius);
+ case "box": {
+ const r = Math.min(shape.radius ?? 0, shape.hx, shape.hy, shape.hz);
+ return r > 0
+ ? R.ColliderDesc.roundCuboid(
+ shape.hx - r,
+ shape.hy - r,
+ shape.hz - r,
+ r,
+ )
+ : R.ColliderDesc.cuboid(shape.hx, shape.hy, shape.hz);
+ }
+ case "cylinder":
+ return R.ColliderDesc.cylinder(shape.halfHeight, shape.radius);
+ case "hull": {
+ const desc = R.ColliderDesc.convexHull(new Float32Array(shape.points));
+ if (!desc)
+ throw new Error(
+ "Physics: could not build a convex hull for this shape.",
+ );
+ return desc;
+ }
+ }
+}
diff --git a/packages/framefields/src/physics/core.ts b/packages/framefields/src/physics/core.ts
new file mode 100644
index 00000000..10a478bd
--- /dev/null
+++ b/packages/framefields/src/physics/core.ts
@@ -0,0 +1,548 @@
+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";
+}
+
+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;
+ }
+
+ signal(name: string): FrameSignal<number> {
+ this.ensure();
+ let sig = this.signals.get(name);
+ if (!sig) {
+ sig = Signal.fromArray(this.channel(name), this.fps);
+ 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;
+ }> = [];
+ private readonly worldRecording: Recording;
+ private readonly allCollisions: Array<PhysicsCollision<B> & { body: B }> = [];
+ private simulated = false;
+
+ 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();
+ }
+
+ /** Every first contact in the simulation, 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 simulation (once) and binds every body's layer per its `output`. */
+ simulate(): this {
+ 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.simulated) {
+ throw new Error(
+ "Physics: bakeKeyframes() must come before simulate() or reading any body signal.",
+ );
+ }
+ this.bakeDefault = options;
+ this.ensureSimulated();
+ return this;
+ }
+
+ private bakeDefault?: PhysicsBakeOptions;
+
+ protected newRecording(): Recording {
+ return new Recording(this.startFrame + this.frames, this.fps, () =>
+ this.ensureSimulated(),
+ );
+ }
+
+ protected assertOpen(): void {
+ if (this.simulated) {
+ throw new Error(
+ "Physics: the world has already simulated; add every body, joint and force before simulate() 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.simulated) return;
+ this.simulated = true;
+ this.run();
+ this.sim.free();
+ for (const body of this.bodies) this.bind(body);
+ }
+
+ private run(): void {
+ const { fps, frames, startFrame, substeps } = this;
+ const dt = 1 / (fps * substeps);
+ const bodies = this.bodies;
+ const n = startFrame + frames;
+ const rawImpact = new Map<B, Float32Array>();
+ for (const b of bodies) rawImpact.set(b, new Float32Array(n));
+ 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);
+ for (const b of bodies) b.record(startFrame, -1);
+
+ const dims = this.gravity.length;
+ const prevVel = new Map<B, number[]>();
+ let kinematicFrom = new Map<B, { position: V; rotation: R }>();
+ for (const b of bodies) {
+ const t = b.kinematicTarget?.(startFrame);
+ if (t) kinematicFrom.set(b, t);
+ }
+
+ for (let f = 1; f < frames; f++) {
+ const frame = startFrame + f;
+ 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[]);
+ }
+ // Velocity each body is expected to gain this frame from gravity,
+ // forces and impulses: anything beyond it came from a contact.
+ const expected = new Map<B, number[]>();
+ for (const b of bodies) {
+ const active = b.type === "dynamic" && f > b.startFrame;
+ expected.set(
+ b,
+ this.gravity.map((g) => (active ? (g * b.gravityScale) / fps : 0)),
+ );
+ }
+ const isActive = (b: B) => b.type === "dynamic" && f > b.startFrame;
+ 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 = 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 = bySim.get(sa);
+ const b = 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]);
+ }
+ }
+ kinematicFrom = kinematicTo;
+
+ for (const b of bodies) b.record(frame, frame - 1);
+
+ 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) {
+ const raw = rawImpact.get(self) as Float32Array;
+ raw[frame] = Math.max(raw[frame], 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);
+ const worldImpact = this.worldRecording.channel("impact");
+ for (const b of bodies) {
+ const raw = rawImpact.get(b) as Float32Array;
+ const env = b.recording.channel("impact");
+ let level = 0;
+ for (let i = startFrame; i < n; i++) {
+ level = Math.max(raw[i] / this.impactReference, level * decay);
+ env[i] = level;
+ if (level > worldImpact[i]) worldImpact[i] = level;
+ }
+ }
+
+ // Before the world starts every channel holds its frame-0 value.
+ for (const rec of [
+ ...bodies.map((b) => b.recording),
+ this.worldRecording,
+ ]) {
+ for (const arr of rec.channels.values()) {
+ arr.fill(arr[startFrame], 0, startFrame);
+ }
+ }
+ }
+
+ 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 === "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;
+}
diff --git a/packages/framefields/src/physics/index.ts b/packages/framefields/src/physics/index.ts
new file mode 100644
index 00000000..5364e7c9
--- /dev/null
+++ b/packages/framefields/src/physics/index.ts
@@ -0,0 +1,58 @@
+import { rapierBackend } from "./backend.js";
+import { PhysicsWorld2D, type World2DOptions } from "./world2d.js";
+import { PhysicsWorld3D, type World3DOptions } from "./world3d.js";
+
+/**
+ * Rigid-body physics baked into signals. A world simulates once, while the
+ * composition is built (Rapier's deterministic build, so every machine gets
+ * the same motion), and replays as per-frame signals: layers follow their
+ * bodies, and `impact`, `speed`, … drive any other prop or effect.
+ *
+ * ```ts
+ * const world = await Physics.world2d({ fps: 30, frames: 150 });
+ * world.walls({ width: W, height: H });
+ * const card = world.body(cardLayer, { restitution: 0.4 });
+ * world.simulate();
+ * flash.animate(LayerAnimation.create().signal("opacity", card.impact));
+ * ```
+ */
+export const Physics = {
+ /** A 2D world in layer pixels (y down). Loads the physics engine on first use. */
+ async world2d(options: World2DOptions): Promise<PhysicsWorld2D> {
+ return new PhysicsWorld2D(await rapierBackend(2), options);
+ },
+ /** A 3D world for Layer3D primitives and models, in scene pixels (y down). */
+ async world3d(options: World3DOptions): Promise<PhysicsWorld3D> {
+ return new PhysicsWorld3D(await rapierBackend(3), options);
+ },
+};
+
+export type {
+ BodyCommonOptions,
+ PhysicsBakeOptions,
+ PhysicsCollision,
+ PhysicsDriver,
+ PhysicsWorldOptions,
+} from "./core.js";
+export {
+ type Body2DOptions,
+ type FieldSample2D,
+ PhysicsBody2D,
+ type PhysicsGroundOptions,
+ type PhysicsRect,
+ type PhysicsRopeOptions,
+ type PhysicsSpringOptions,
+ type PhysicsWallsOptions,
+ PhysicsWorld2D,
+ type World2DOptions,
+} from "./world2d.js";
+export {
+ type Body3DOptions,
+ type FieldSample3D,
+ PhysicsBody3D,
+ type PhysicsBox3D,
+ type PhysicsRope3DOptions,
+ type PhysicsSpring3DOptions,
+ PhysicsWorld3D,
+ type World3DOptions,
+} from "./world3d.js";
diff --git a/packages/framefields/src/physics/physics-render.test.ts b/packages/framefields/src/physics/physics-render.test.ts
new file mode 100644
index 00000000..683c4883
--- /dev/null
+++ b/packages/framefields/src/physics/physics-render.test.ts
@@ -0,0 +1,170 @@
+/**
+ * Physics through the real renderer: layers land where their bodies are,
+ * with the renderer's pivot and rotation direction, and body signals drive
+ * other props.
+ */
+import { describe, expect, it } from "vitest";
+import { Composition, Layer, Layer3D, LayerAnimation } from "../index.js";
+import { decodePngPixels, getPixel } from "../test-utils/pixels.js";
+import { Physics } from "./index.js";
+
+const FPS = 30;
+
+function comp(width = 400, height = 400) {
+ return new Composition({
+ width,
+ height,
+ fps: FPS,
+ durationFrames: 60,
+ backgroundColor: "#000000",
+ });
+}
+
+async function frame(c: Composition, f: number) {
+ return decodePngPixels(await c.renderFrame({ frame: f }));
+}
+
+describe("physics render", () => {
+ it("renders a turned layer exactly over its body (pivot and rotation direction)", async () => {
+ const c = comp();
+ const plank = Layer.box({
+ id: "plank",
+ position: "absolute",
+ x: 120,
+ y: 120,
+ width: 200,
+ height: 40,
+ anchorX: 0,
+ anchorY: 0,
+ rotation: 40,
+ background: "#ffffff",
+ });
+ c.add(plank);
+ const world = await Physics.world2d({ fps: FPS, frames: 30, gravity: 0 });
+ const body = world.body(plank, { angularVelocity: 60 });
+ world.simulate();
+
+ const f = 20;
+ const img = await frame(c, f);
+ let sx = 0;
+ let sy = 0;
+ let n = 0;
+ for (let y = 0; y < img.height; y++) {
+ for (let x = 0; x < img.width; x++) {
+ const w = getPixel(img, x, y).r / 255;
+ sx += x * w;
+ sy += y * w;
+ n += w;
+ }
+ }
+ const ctx = { frame: f, fps: FPS } as never;
+ expect(sx / n).toBeCloseTo(body.centerX.get(ctx) as number, -0.5);
+ expect(sy / n).toBeCloseTo(body.centerY.get(ctx) as number, -0.5);
+ // Near both ends along the turned axis (clockwise, y down): plank;
+ // across it: background. A flipped rotation direction fails this.
+ const angle = ((body.rotation.get(ctx) as number) * Math.PI) / 180;
+ const cx = body.centerX.get(ctx) as number;
+ const cy = body.centerY.get(ctx) as number;
+ const along = (d: number) => [
+ cx + d * Math.cos(angle),
+ cy + d * Math.sin(angle),
+ ];
+ const across = (d: number) => [
+ cx - d * Math.sin(angle),
+ cy + d * Math.cos(angle),
+ ];
+ for (const [x, y] of [along(85), along(-85)]) {
+ expect(getPixel(img, x, y).r).toBeGreaterThan(200);
+ }
+ for (const [x, y] of [across(60), across(-60)]) {
+ expect(getPixel(img, x, y).r).toBeLessThan(20);
+ }
+ });
+
+ it("drops a box onto the floor and flashes on impact", async () => {
+ const c = comp();
+ const box = Layer.box({
+ id: "box",
+ position: "absolute",
+ x: 150,
+ y: 0,
+ width: 100,
+ height: 60,
+ background: "#ffffff",
+ });
+ const flash = Layer.box({
+ id: "flash",
+ position: "absolute",
+ x: 0,
+ y: 380,
+ width: 400,
+ height: 20,
+ background: "#ff0000",
+ opacity: 0,
+ });
+ c.add([box, flash]);
+ const world = await Physics.world2d({
+ fps: FPS,
+ frames: 60,
+ impactDecay: 3,
+ });
+ world.walls({ width: 400, height: 380 });
+ const body = world.body(box, { restitution: 0 });
+ world.simulate();
+ flash.animate(
+ LayerAnimation.create().signal("opacity", body.impact, { multiplier: 2 }),
+ );
+
+ const hit = body.collisions[0].frame;
+ const before = await frame(c, hit - 2);
+ const during = await frame(c, hit);
+ const after = await frame(c, 59);
+
+ expect(getPixel(before, 200, 390).r).toBeLessThan(20);
+ expect(getPixel(during, 200, 390).r).toBeGreaterThan(150);
+ // Resting on the floor (y 380): bottom rows white, the start spot empty.
+ expect(getPixel(after, 200, 350).r).toBeGreaterThan(200);
+ expect(getPixel(after, 200, 30).r).toBeLessThan(20);
+ });
+
+ it("drops a 3D sphere onto the ground", async () => {
+ const c = new Composition({
+ width: 800,
+ height: 600,
+ fps: FPS,
+ durationFrames: 60,
+ backgroundColor: "#000000",
+ });
+ c.add([
+ Layer.camera({
+ x: 400,
+ y: 300,
+ z: -900,
+ targetX: 400,
+ targetY: 300,
+ targetZ: 0,
+ }),
+ Layer.ambientLight("#ffffff", 1),
+ ]);
+ const ball = Layer3D.sphere({
+ id: "ball",
+ radius: 60,
+ x: 400,
+ y: -200,
+ z: 0,
+ color: "#ff3030",
+ });
+ c.add(ball);
+ const world = await Physics.world3d({ fps: FPS, frames: 60 });
+ world.ground({ y: 360 });
+ world.body(ball, { restitution: 0, angularDamping: 2 });
+ world.simulate();
+
+ const start = await frame(c, 0);
+ const end = await frame(c, 59);
+ expect(getPixel(start, 400, 300).r).toBeLessThan(20);
+ const rest = getPixel(end, 400, 300);
+ expect(rest.r).toBeGreaterThan(120);
+ expect(rest.g).toBeLessThan(rest.r / 2);
+ });
+});
diff --git a/packages/framefields/src/physics/physics.test.ts b/packages/framefields/src/physics/physics.test.ts
new file mode 100644
index 00000000..6e007f24
--- /dev/null
+++ b/packages/framefields/src/physics/physics.test.ts
@@ -0,0 +1,360 @@
+import { describe, expect, it } from "vitest";
+import { Layer, Layer3D, Signal } from "../index.js";
+import { simplifyKeys, unwrapDegrees } from "./core.js";
+import { Physics } from "./index.js";
+import { eulerFromQuat, quatFromEuler } from "./world3d.js";
+
+const FPS = 30;
+const at = (s: { get(ctx?: never): number }, frame: number) =>
+ s.get({ frame, fps: FPS } as never);
+
+function card(
+ id: string,
+ x: number,
+ y: number,
+ extra: Record<string, unknown> = {},
+) {
+ return Layer.box({
+ id,
+ position: "absolute",
+ x,
+ y,
+ width: 200,
+ height: 100,
+ background: "#fff",
+ ...extra,
+ });
+}
+
+type Track = {
+ prop: string;
+ source?: { type: string };
+ keyframes: Array<{ frame: number; value: number }>;
+};
+const tracksOf = (layer: unknown) =>
+ ((layer as { animation?: { tracks: Track[] } }).animation?.tracks ??
+ []) as Track[];
+
+describe("Physics.world2d", () => {
+ it("drops a box onto the ground and binds the layer to signals", async () => {
+ const world = await Physics.world2d({ fps: FPS, frames: 90 });
+ world.ground({ y: 1000 });
+ const layer = card("a", 860, 100);
+ const body = world.body(layer, { restitution: 0 });
+ world.simulate();
+
+ expect(at(body.y, 0)).toBeCloseTo(100, 3);
+ // Rests on the ground: bottom edge at y = 1000.
+ expect(at(body.y, 89) + 100).toBeCloseTo(1000, 0);
+ expect(Math.abs(at(body.x, 89) - 860)).toBeLessThan(2);
+ expect(at(body.sleeping, 89)).toBe(1);
+
+ const props = tracksOf(layer).map((t) => [t.prop, t.source?.type]);
+ expect(props).toEqual([
+ ["x", "signal"],
+ ["y", "signal"],
+ ["rotation", "signal"],
+ ]);
+ });
+
+ it("records first contacts and an impact envelope that decays", async () => {
+ const world = await Physics.world2d({
+ fps: FPS,
+ frames: 60,
+ impactDecay: 4,
+ });
+ const ground = world.ground({ y: 1000 });
+ const body = world.body(card("a", 860, 500), { restitution: 0 });
+ world.simulate();
+
+ expect(body.collisions.length).toBeGreaterThan(0);
+ const hit = body.collisions[0];
+ expect(hit.with).toBe(ground);
+ expect(hit.speed).toBeGreaterThan(500);
+ expect(world.collisions[0].frame).toBe(hit.frame);
+
+ expect(at(body.impact, hit.frame - 1)).toBe(0);
+ const peak = at(body.impact, hit.frame);
+ expect(peak).toBeGreaterThan(0.3);
+ expect(at(body.impact, hit.frame + 4)).toBeLessThan(peak * 0.5);
+ // The ground hears the hit too, and the world takes the loudest.
+ expect(at(ground.impact, hit.frame)).toBeCloseTo(peak, 5);
+ expect(at(world.impact, hit.frame)).toBeCloseTo(peak, 5);
+ });
+
+ it("is deterministic", async () => {
+ const run = async () => {
+ const world = await Physics.world2d({ fps: FPS, frames: 120 });
+ world.walls({ width: 1920, height: 1080 });
+ const bodies = Array.from({ length: 12 }, (_, i) =>
+ world.body(
+ card(`c${i}`, 200 + (i % 4) * 300, -200 - i * 140, {
+ rotation: i * 13,
+ }),
+ {
+ angularVelocity: i * 20,
+ },
+ ),
+ );
+ world.simulate();
+ return bodies.flatMap((b) => [
+ at(b.x, 119),
+ at(b.y, 119),
+ at(b.rotation, 119),
+ ]);
+ };
+ expect(await run()).toEqual(await run());
+ });
+
+ it("starts from the layer's pose with any pivot, scale and rotation", async () => {
+ const world = await Physics.world2d({ fps: FPS, frames: 2, gravity: 0 });
+ const layer = card("a", 300, 400, {
+ rotation: 30,
+ anchorX: 0,
+ anchorY: 0,
+ scale: 1.5,
+ });
+ const body = world.body(layer);
+ world.simulate();
+ expect(at(body.x, 1)).toBeCloseTo(300, 3);
+ expect(at(body.y, 1)).toBeCloseTo(400, 3);
+ expect(at(body.rotation, 1)).toBeCloseTo(30, 3);
+ // Center of a 300×150 box pivoting on its top-left corner, turned 30° clockwise.
+ const a = Math.PI / 6;
+ expect(at(body.centerX, 1)).toBeCloseTo(
+ 300 + 150 * Math.cos(a) - 75 * Math.sin(a),
+ 2,
+ );
+ expect(at(body.centerY, 1)).toBeCloseTo(
+ 400 + 150 * Math.sin(a) + 75 * Math.cos(a),
+ 2,
+ );
+ });
+
+ it("holds a body until its start frame and the signals until the world's", async () => {
+ const world = await Physics.world2d({
+ fps: FPS,
+ frames: 40,
+ startFrame: 100,
+ });
+ const body = world.body(card("a", 0, 0), { startFrame: 10 });
+ world.simulate();
+ expect(at(body.y, 0)).toBe(0);
+ expect(at(body.y, 110)).toBe(0);
+ expect(at(body.y, 112)).toBeGreaterThan(0);
+ expect(at(body.vy, 139)).toBeGreaterThan(0);
+ });
+
+ it("uses circles and convex hulls for shape layers", async () => {
+ const world = await Physics.world2d({ fps: FPS, frames: 90 });
+ world.ground({ y: 1000 });
+ const ball = world.body(
+ Layer.shape("circle", {
+ position: "absolute",
+ x: 100,
+ y: 0,
+ width: 200,
+ height: 200,
+ }),
+ { restitution: 0 },
+ );
+ const star = world.body(
+ Layer.shape("star", {
+ position: "absolute",
+ x: 600,
+ y: 0,
+ width: 200,
+ height: 200,
+ }),
+ );
+ const text = world.body(card("t", 1200, 0), {
+ shape: "circle",
+ size: [100, 100],
+ });
+ world.simulate();
+ expect(at(ball.y, 89) + 200).toBeCloseTo(1000, 0);
+ expect(at(star.y, 89)).toBeGreaterThan(600);
+ expect(at(text.centerY, 89)).toBeCloseTo(950, 0);
+ });
+
+ it("bakes simplified keyframes instead of signals", async () => {
+ const world = await Physics.world2d({ fps: FPS, frames: 90 });
+ world.ground({ y: 1000 });
+ const layer = card("a", 860, 100);
+ const body = world.body(layer, { restitution: 0, lockRotation: true });
+ world.bakeKeyframes();
+
+ const tracks = tracksOf(layer);
+ expect(tracks.map((t) => t.prop)).toEqual(["x", "y"]);
+ const y = tracks.find((t) => t.prop === "y") as Track;
+ expect(y.source?.type ?? "keyframes").not.toBe("signal");
+ expect(y.keyframes.length).toBeGreaterThan(2);
+ expect(y.keyframes.length).toBeLessThan(90);
+ expect(y.keyframes[0]).toMatchObject({ frame: 0, value: 100 });
+ const last = y.keyframes[y.keyframes.length - 1];
+ expect(last.frame).toBe(89);
+ expect(last.value).toBeCloseTo(at(body.y, 89), 2);
+ const x = tracks.find((t) => t.prop === "x") as Track;
+ expect(x.keyframes).toHaveLength(1);
+ });
+
+ it("moves kinematic bodies from drivers and lets them push", async () => {
+ const world = await Physics.world2d({ fps: FPS, frames: 60, gravity: 0 });
+ const pusher = world.body(card("p", 0, 400), {
+ type: "kinematic",
+ follow: {
+ x: Signal.fromArray(
+ Array.from({ length: 60 }, (_, f) => f * 20),
+ FPS,
+ ),
+ },
+ });
+ const target = world.body(card("t", 500, 400));
+ world.simulate();
+ expect(at(pusher.x, 30)).toBeCloseTo(600, 0);
+ expect(at(target.x, 59)).toBeGreaterThan(700);
+ });
+
+ it("applies forces, impulses and joints", async () => {
+ const world = await Physics.world2d({ fps: FPS, frames: 60, gravity: 0 });
+ const pushed = world.body(card("a", 0, 0));
+ world.force(pushed, { x: (frame) => (frame < 30 ? 600 : 0) });
+ const kicked = world.body(card("b", 0, 300));
+ world.impulse(kicked, 10, [0, -900]);
+ const swing = world.body(card("c", 1000, 0), { gravityScale: 1 });
+ world.pin(swing, [1000, 50]);
+ world.force(swing, { y: 2400 });
+ world.simulate();
+ expect(at(pushed.vx, 29)).toBeCloseTo(580, -1);
+ expect(at(pushed.vx, 59)).toBeCloseTo(at(pushed.vx, 31), 1);
+ expect(at(kicked.vy, 9)).toBe(0);
+ expect(at(kicked.vy, 10)).toBeCloseTo(-900, 0);
+ // Pinned at its left edge's middle: swings down around the pin, never falls away.
+ const swingAngles = Array.from({ length: 60 }, (_, f) =>
+ Math.abs(at(swing.rotation, f)),
+ );
+ expect(Math.max(...swingAngles)).toBeGreaterThan(60);
+ expect(
+ Math.hypot(at(swing.centerX, 59) - 1000, at(swing.centerY, 59) - 50),
+ ).toBeCloseTo(100, -1);
+ });
+
+ it("pushes bodies with a position-dependent field", async () => {
+ const world = await Physics.world2d({ fps: FPS, frames: 30, gravity: 0 });
+ const left = world.body(card("l", 300, 500));
+ const right = world.body(card("r", 1400, 500));
+ const still = world.body(card("s", 800, 0));
+ // Away from x = 960, only for the first two bodies.
+ world.field((s) => [s.x < 960 ? -1200 : 1200, 0], {
+ bodies: [left, right],
+ });
+ world.simulate();
+ expect(at(left.vx, 29)).toBeLessThan(-1000);
+ expect(at(right.vx, 29)).toBeGreaterThan(1000);
+ expect(at(still.vx, 29)).toBe(0);
+ // A field is not a contact: no impacts.
+ expect(at(left.impact, 29)).toBe(0);
+ });
+
+ it("rejects layers without a position and locks after simulating", async () => {
+ const world = await Physics.world2d({ fps: FPS, frames: 2 });
+ expect(() => world.body(Layer.box({ width: 10, height: 10 }))).toThrow(
+ /x.*y/,
+ );
+ const b = world.body(card("a", 0, 0));
+ void b.y;
+ expect(() => world.body(card("b", 0, 0))).toThrow(/already simulated/);
+ });
+});
+
+describe("Physics.world3d", () => {
+ it("drops a sphere and a box onto the ground", async () => {
+ const world = await Physics.world3d({ fps: FPS, frames: 120 });
+ world.ground({ y: 600 });
+ const sphere = Layer3D.sphere({ id: "s", radius: 80, x: 0, y: 0, z: 0 });
+ const box = Layer3D.roundedBox({
+ id: "b",
+ width: 160,
+ height: 100,
+ depth: 160,
+ radius: 10,
+ x: 400,
+ y: -200,
+ z: 0,
+ rotateZ: 20,
+ });
+ const s = world.body(sphere, { restitution: 0, angularDamping: 2 });
+ const b = world.body(box, { restitution: 0 });
+ world.simulate();
+ expect(at(s.y, 119)).toBeCloseTo(520, 0);
+ expect(at(b.y, 119)).toBeCloseTo(550, 0);
+ expect(Math.abs(at(b.rotateZ, 119)) % 90).toBeLessThan(1);
+ expect(tracksOf(box).map((t) => t.prop)).toEqual([
+ "x",
+ "y",
+ "z",
+ "rotateX",
+ "rotateY",
+ "rotateZ",
+ ]);
+ });
+
+ it("converts rotations with the renderer's Euler order", () => {
+ for (const e of [
+ [10, 20, 30],
+ [-75, 40, 170],
+ [0, 89, 0],
+ [120, -30, -60],
+ ] as const) {
+ const back = eulerFromQuat(quatFromEuler(e[0], e[1], e[2]), [
+ e[0],
+ e[1],
+ e[2],
+ ]);
+ expect(back[0]).toBeCloseTo(e[0], 3);
+ expect(back[1]).toBeCloseTo(e[1], 3);
+ expect(back[2]).toBeCloseTo(e[2], 3);
+ }
+ });
+
+ it("is deterministic", async () => {
+ const run = async () => {
+ const world = await Physics.world3d({ fps: FPS, frames: 90 });
+ world.walls({ x: 0, y: 0, z: 0, width: 800, height: 800, depth: 800 });
+ const bodies = Array.from({ length: 10 }, (_, i) =>
+ world.body(
+ Layer3D.roundedBox({
+ width: 80,
+ height: 80,
+ depth: 80,
+ x: (i % 3) * 60 - 60,
+ y: -300 - i * 100,
+ z: 0,
+ rotateX: i * 17,
+ }),
+ ),
+ );
+ world.simulate();
+ return bodies.flatMap((b) => [
+ at(b.x, 89),
+ at(b.y, 89),
+ at(b.rotateY, 89),
+ ]);
+ };
+ expect(await run()).toEqual(await run());
+ });
+});
+
+describe("helpers", () => {
+ it("unwraps angles across ±180", () => {
+ expect(unwrapDegrees(170, -170)).toBe(190);
+ expect(unwrapDegrees(-350, 5)).toBe(-355);
+ });
+
+ it("keeps only the keyframes a linear track needs", () => {
+ const line = Array.from({ length: 50 }, (_, i) => i * 2);
+ expect(simplifyKeys(line, 0.1).map((k) => k[0])).toEqual([0, 49]);
+ const vee = Array.from({ length: 21 }, (_, i) => Math.abs(i - 10));
+ expect(simplifyKeys(vee, 0.1).map((k) => k[0])).toEqual([0, 10, 20]);
+ });
+});
diff --git a/packages/framefields/src/physics/world2d.ts b/packages/framefields/src/physics/world2d.ts
new file mode 100644
index 00000000..2ae1a6a9
--- /dev/null
+++ b/packages/framefields/src/physics/world2d.ts
@@ -0,0 +1,788 @@
+import type {
+ AnimatableProp,
+ LayoutNode,
+} from "@framefields/compositions/program";
+import type { FrameSignal } from "@framefields/core";
+import {
+ buildShapeSvgPath,
+ parseSvgPathToSegments,
+ type ShapeGeometryConfig,
+} from "@framefields/webgpu-renderers";
+import { FontManager } from "../fonts/manager.js";
+import type {
+ BodySpec2D,
+ PhysicsBackend,
+ Shape2D,
+ SimBody2D,
+ SimWorld2D,
+ Vec2,
+} from "./backend.js";
+import {
+ type BodyCommonOptions,
+ type CoreBody,
+ type PhysicsCollision,
+ type PhysicsDriver,
+ type PhysicsWorldOptions,
+ type Recording,
+ sampleDriver,
+ unwrapDegrees,
+ WorldCore,
+} from "./core.js";
+
+export interface World2DOptions extends PhysicsWorldOptions {
+ /** px/s², y down. A number pulls straight down. Default 2400. */
+ gravity?: number | [number, number];
+}
+
+/** A plain rectangle for bodies with no layer (invisible obstacles, funnels). */
+export interface PhysicsRect {
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+ rotation?: number;
+ borderRadius?: number;
+}
+
+export interface Body2DOptions extends BodyCommonOptions {
+ /**
+ * Collider: `"auto"` (default) reads the layer — circles stay circles,
+ * rounded boxes keep their radius, polygons/stars/paths use their convex
+ * hull. Force `"box"`, `"circle"` or `"hull"` (the shape's outline).
+ */
+ shape?: "auto" | "box" | "circle" | "hull";
+ /** Collider size override `[width, height]`, px. Text layers are measured when they have no size. */
+ size?: [number, number];
+ /** px/s. */
+ velocity?: [number, number];
+ /** Degrees per second, clockwise. */
+ angularVelocity?: number;
+ /**
+ * Kinematic bodies: where the layer is each frame, as its own `x` / `y`
+ * (top-left) and `rotation` (degrees). Missing ones keep the start pose.
+ */
+ follow?: { x?: PhysicsDriver; y?: PhysicsDriver; rotation?: PhysicsDriver };
+}
+
+type LayerLike = Record<string, unknown> & {
+ kind?: string;
+ animate?: (...a: unknown[]) => unknown;
+};
+
+/**
+ * A simulated body. Its signals hold one value per composition frame; bind
+ * them to any prop or effect uniform (`.signal("opacity", body.impact)`).
+ * Reading a signal runs the simulation if it has not run yet.
+ */
+export class PhysicsBody2D implements CoreBody<Vec2, number> {
+ readonly collisions: PhysicsCollision<PhysicsBody2D>[] = [];
+ /** @internal */ readonly recording: Recording;
+ /** @internal */ readonly sim: SimBody2D;
+
+ /** @internal */
+ constructor(
+ /** @internal */ readonly world: PhysicsWorld2D,
+ sim: SimBody2D,
+ readonly type: "dynamic" | "fixed" | "kinematic",
+ readonly layer: LayerLike | undefined,
+ /** Layer box size (unscaled), scale and pivot, to turn the center back into x/y. */
+ private readonly frame: {
+ width: number;
+ height: number;
+ scale: number;
+ anchorX: number;
+ anchorY: number;
+ rotation: number;
+ },
+ private readonly options: Body2DOptions,
+ recording: Recording,
+ ) {
+ this.sim = sim;
+ this.recording = recording;
+ }
+
+ get startFrame(): number {
+ return Math.max(0, Math.round(this.options.startFrame ?? 0));
+ }
+ get gravityScale(): number {
+ return this.options.gravityScale ?? 1;
+ }
+ get output(): Body2DOptions["output"] {
+ return this.options.output;
+ }
+
+ /** The layer's `x` (top-left) every frame. */
+ get x(): FrameSignal<number> {
+ return this.recording.signal("x");
+ }
+ /** The layer's `y` (top-left) every frame. */
+ get y(): FrameSignal<number> {
+ return this.recording.signal("y");
+ }
+ /** Degrees, clockwise, continuous (no jump at 360). */
+ get rotation(): FrameSignal<number> {
+ return this.recording.signal("rotation");
+ }
+ /** Body center, px. */
+ get centerX(): FrameSignal<number> {
+ return this.recording.signal("centerX");
+ }
+ get centerY(): FrameSignal<number> {
+ return this.recording.signal("centerY");
+ }
+ /** px/s. */
+ get vx(): FrameSignal<number> {
+ return this.recording.signal("vx");
+ }
+ get vy(): FrameSignal<number> {
+ return this.recording.signal("vy");
+ }
+ /** px/s. */
+ get speed(): FrameSignal<number> {
+ return this.recording.signal("speed");
+ }
+ /** Degrees per second. */
+ get angularVelocity(): FrameSignal<number> {
+ return this.recording.signal("angularVelocity");
+ }
+ /**
+ * Hit envelope: jumps on each new contact (1 ≈ a 1500 px/s velocity
+ * change, see `impactReference`) and decays over `impactDecay` frames.
+ */
+ get impact(): FrameSignal<number> {
+ return this.recording.signal("impact");
+ }
+ /** 1 while the body is at rest, else 0. */
+ get sleeping(): FrameSignal<number> {
+ return this.recording.signal("sleeping");
+ }
+
+ /** @internal */
+ kinematicTarget(
+ frame: number,
+ ): { position: Vec2; rotation: number } | undefined {
+ const follow = this.options.follow;
+ if (this.type !== "kinematic" || !follow) return undefined;
+ const f = this.frame;
+ const fps = this.world.fps;
+ const x =
+ follow.x === undefined ? undefined : sampleDriver(follow.x, frame, fps);
+ const y =
+ follow.y === undefined ? undefined : sampleDriver(follow.y, frame, fps);
+ const rotation =
+ follow.rotation === undefined
+ ? f.rotation
+ : sampleDriver(follow.rotation, frame, fps);
+ const start = this.initialLayerXY();
+ const center = layerToCenter(x ?? start[0], y ?? start[1], rotation, f);
+ const ppm = this.world.pixelsPerMeter;
+ return {
+ position: [center[0] / ppm, center[1] / ppm],
+ rotation: (rotation * Math.PI) / 180,
+ };
+ }
+
+ private initialLayerXY(): Vec2 {
+ const l = this.layer;
+ return [Number(l?.x ?? 0), Number(l?.y ?? 0)];
+ }
+
+ /** @internal */
+ record(index: number, previous: number): void {
+ const ppm = this.world.pixelsPerMeter;
+ const [mx, my] = this.sim.position();
+ const cx = mx * ppm;
+ const cy = my * ppm;
+ const rec = this.recording;
+ const rotation = rec.channel("rotation");
+ const deg = (this.sim.rotation() * 180) / Math.PI;
+ rotation[index] =
+ previous < 0
+ ? unwrapDegrees(this.frame.rotation, deg)
+ : unwrapDegrees(rotation[previous], deg);
+ const [x, y] = centerToLayer(cx, cy, rotation[index], this.frame);
+ rec.channel("x")[index] = x;
+ rec.channel("y")[index] = y;
+ rec.channel("centerX")[index] = cx;
+ rec.channel("centerY")[index] = cy;
+ const [vx, vy] = this.sim.velocity();
+ rec.channel("vx")[index] = vx * ppm;
+ rec.channel("vy")[index] = vy * ppm;
+ rec.channel("speed")[index] = Math.hypot(vx, vy) * ppm;
+ rec.channel("angularVelocity")[index] =
+ (this.sim.angularVelocity() * 180) / Math.PI;
+ rec.channel("sleeping")[index] = this.sim.sleeping() ? 1 : 0;
+ }
+
+ /** @internal */
+ boundChannels(): Array<[AnimatableProp, string]> {
+ const out: Array<[AnimatableProp, string]> = [
+ ["x", "x"],
+ ["y", "y"],
+ ];
+ if (!this.options.lockRotation) out.push(["rotation", "rotation"]);
+ return out;
+ }
+
+ /** @internal World-space point (px) → this body's local frame (meters), at the start pose. */
+ localAnchor(point: Vec2 | undefined): Vec2 {
+ if (!point) return [0, 0];
+ const ppm = this.world.pixelsPerMeter;
+ const [px, py] = this.sim.position();
+ const a = -this.sim.rotation();
+ const dx = point[0] / ppm - px;
+ const dy = point[1] / ppm - py;
+ return [
+ dx * Math.cos(a) - dy * Math.sin(a),
+ dx * Math.sin(a) + dy * Math.cos(a),
+ ];
+ }
+
+ /** @internal Start-pose center in px. */
+ center(): Vec2 {
+ const ppm = this.world.pixelsPerMeter;
+ const [x, y] = this.sim.position();
+ return [x * ppm, y * ppm];
+ }
+}
+
+/** What a {@link PhysicsWorld2D.field} sees for one body. */
+export interface FieldSample2D {
+ /** Body center, px. */
+ x: number;
+ y: number;
+ /** px/s. */
+ vx: number;
+ vy: number;
+ /** Composition frame. */
+ frame: number;
+ body: PhysicsBody2D;
+}
+
+export interface PhysicsSpringOptions {
+ /** Rest length, px (default: the distance at the start). */
+ length?: number;
+ /** Oscillations per second (default 2). Higher is stiffer. */
+ frequency?: number;
+ /** 0 bounces forever, 1 settles without overshoot (default 0.2). */
+ dampingRatio?: number;
+ /** Attachment point on body A, world px at the start (default its center). */
+ anchorA?: [number, number];
+ /** Attachment point on body B (or the world point), world px. */
+ anchorB?: [number, number];
+}
+
+export interface PhysicsRopeOptions {
+ /** Maximum length, px (default: the distance at the start). */
+ length?: number;
+ anchorA?: [number, number];
+ anchorB?: [number, number];
+}
+
+export interface PhysicsGroundOptions {
+ /** Top edge of the ground, px. */
+ y: number;
+ friction?: number;
+ restitution?: number;
+}
+
+export interface PhysicsWallsOptions {
+ x?: number;
+ y?: number;
+ width: number;
+ height: number;
+ /** Close the top too (default false: things can fall in). */
+ ceiling?: boolean;
+ /** Wall thickness outside the box, px (default 400). */
+ thickness?: number;
+ friction?: number;
+ restitution?: number;
+}
+
+/**
+ * A deterministic 2D rigid-body world (Rapier) in layer pixels. Build it,
+ * add bodies from layers, then `simulate()`: each body's layer is bound to
+ * its simulated `x` / `y` / `rotation`, and every body exposes signals
+ * (`impact`, `speed`, …) for driving anything else. The simulation runs
+ * once while the composition is built, so frames render in any order and
+ * identically on every machine.
+ */
+export class PhysicsWorld2D extends WorldCore<Vec2, number, PhysicsBody2D> {
+ /** @internal */
+ constructor(backend: PhysicsBackend, options: World2DOptions) {
+ const ppm = options.pixelsPerMeter ?? 100;
+ const g = options.gravity ?? 2400;
+ const gravity: Vec2 =
+ typeof g === "number" ? [0, g / ppm] : [g[0] / ppm, g[1] / ppm];
+ const sim = backend.createWorld2D(gravity);
+ super(sim as never, gravity, options);
+ }
+
+ /**
+ * Adds a body for a layer (absolutely positioned: `x`, `y`, and a size)
+ * or for a plain rectangle. The layer's current pose is the start pose.
+ */
+ body(
+ target: LayoutNode | PhysicsRect,
+ options: Body2DOptions = {},
+ ): PhysicsBody2D {
+ this.assertOpen();
+ const isLayer = typeof (target as unknown as LayerLike).kind === "string";
+ const layer = isLayer ? (target as unknown as LayerLike) : undefined;
+ const geom = layerGeometry(target as unknown as LayerLike, options);
+ const ppm = this.pixelsPerMeter;
+ const type = options.type ?? "dynamic";
+ const [cx, cy] = layerToCenter(geom.x, geom.y, geom.rotation, geom);
+ const v = options.velocity ?? [0, 0];
+ const spec: BodySpec2D = {
+ type,
+ position: [cx / ppm, cy / ppm],
+ angle: (geom.rotation * Math.PI) / 180,
+ velocity: [v[0] / ppm, v[1] / ppm],
+ angularVelocity: ((options.angularVelocity ?? 0) * Math.PI) / 180,
+ linearDamping: options.linearDamping ?? 0,
+ angularDamping: options.angularDamping ?? 0,
+ gravityScale: options.gravityScale ?? 1,
+ lockRotation: options.lockRotation ?? false,
+ ccd: options.ccd ?? false,
+ enabled: true,
+ sensor: options.sensor ?? false,
+ density: options.density ?? 1,
+ friction: options.friction ?? 0.6,
+ restitution: options.restitution ?? 0.3,
+ shape: scaleShape(geom.shape, 1 / ppm),
+ };
+ const simBody = (this.sim as unknown as SimWorld2D).addBody(spec);
+ const body = new PhysicsBody2D(
+ this,
+ simBody,
+ type,
+ layer,
+ geom,
+ options,
+ this.newRecording(),
+ );
+ return this.addBody(body);
+ }
+
+ /** A fixed, very wide floor whose top edge sits at `y`. */
+ ground(options: PhysicsGroundOptions): PhysicsBody2D {
+ const t = 2000;
+ const w = 1e6;
+ return this.body(
+ { x: -w / 2, y: options.y, width: w, height: t },
+ {
+ type: "fixed",
+ friction: options.friction,
+ restitution: options.restitution ?? 0.2,
+ },
+ );
+ }
+
+ /** Fixed floor, left and right walls (and optionally a ceiling) around a box, e.g. the canvas. */
+ walls(options: PhysicsWallsOptions): {
+ floor: PhysicsBody2D;
+ left: PhysicsBody2D;
+ right: PhysicsBody2D;
+ ceiling?: PhysicsBody2D;
+ } {
+ const { width: W, height: H } = options;
+ const x = options.x ?? 0;
+ const y = options.y ?? 0;
+ const t = options.thickness ?? 400;
+ const mat = {
+ type: "fixed" as const,
+ friction: options.friction,
+ restitution: options.restitution ?? 0.2,
+ };
+ const tall = H * 4 + t;
+ const result = {
+ floor: this.body(
+ { x: x - t, y: y + H, width: W + 2 * t, height: t },
+ mat,
+ ),
+ left: this.body(
+ { x: x - t, y: y + H - tall, width: t, height: tall },
+ mat,
+ ),
+ right: this.body(
+ { x: x + W, y: y + H - tall, width: t, height: tall },
+ mat,
+ ),
+ ceiling: undefined as PhysicsBody2D | undefined,
+ };
+ if (options.ceiling) {
+ result.ceiling = this.body(
+ { x: x - t, y: y - t, width: W + 2 * t, height: t },
+ mat,
+ );
+ }
+ return result;
+ }
+
+ /** Pins a body to the world at a point (default its center); it can still swing around it. */
+ pin(body: PhysicsBody2D, at?: [number, number]): this {
+ const point = at ?? body.center();
+ const anchor = this.anchorBody(point);
+ this.joint(body, anchor, {
+ type: "revolute",
+ anchorA: body.localAnchor(point),
+ anchorB: [0, 0],
+ });
+ return this;
+ }
+
+ /** Joins two bodies at a world point so they swing around it (a hinge). */
+ hinge(a: PhysicsBody2D, b: PhysicsBody2D, at: [number, number]): this {
+ this.joint(a, b, {
+ type: "revolute",
+ anchorA: a.localAnchor(at),
+ anchorB: b.localAnchor(at),
+ });
+ return this;
+ }
+
+ /** Glues two bodies together rigidly. */
+ weld(a: PhysicsBody2D, b: PhysicsBody2D): this {
+ const at = a.center();
+ this.joint(a, b, {
+ type: "fixed",
+ anchorA: [0, 0],
+ anchorB: b.localAnchor(at),
+ });
+ return this;
+ }
+
+ /** A damped spring between two bodies, or from a body to a world point. */
+ spring(
+ a: PhysicsBody2D,
+ b: PhysicsBody2D | [number, number],
+ options: PhysicsSpringOptions = {},
+ ): this {
+ const { other, pa, pb } = this.endpoints(
+ a,
+ b,
+ options.anchorA,
+ options.anchorB,
+ );
+ const ppm = this.pixelsPerMeter;
+ const length =
+ (options.length ?? Math.hypot(pb[0] - pa[0], pb[1] - pa[1])) / ppm;
+ const mass = effectiveMass(a, other);
+ const w = 2 * Math.PI * (options.frequency ?? 2);
+ this.joint(a, other, {
+ type: "spring",
+ anchorA: a.localAnchor(pa),
+ anchorB: other.localAnchor(pb),
+ restLength: length,
+ stiffness: mass * w * w,
+ damping: 2 * (options.dampingRatio ?? 0.2) * mass * w,
+ });
+ return this;
+ }
+
+ /** A rope: never longer than `length`, slack when closer. */
+ rope(
+ a: PhysicsBody2D,
+ b: PhysicsBody2D | [number, number],
+ options: PhysicsRopeOptions = {},
+ ): this {
+ const { other, pa, pb } = this.endpoints(
+ a,
+ b,
+ options.anchorA,
+ options.anchorB,
+ );
+ const length = options.length ?? Math.hypot(pb[0] - pa[0], pb[1] - pa[1]);
+ this.joint(a, other, {
+ type: "rope",
+ anchorA: a.localAnchor(pa),
+ anchorB: other.localAnchor(pb),
+ length: length / this.pixelsPerMeter,
+ });
+ return this;
+ }
+
+ /** A steady push, px/s² (mass-independent): wind, magnets, audio. Drivers are read every frame. */
+ force(
+ body: PhysicsBody2D,
+ accel: { x?: PhysicsDriver; y?: PhysicsDriver },
+ ): this {
+ const ppm = this.pixelsPerMeter;
+ this.addForce(body, (frame) => [
+ accel.x === undefined ? 0 : sampleDriver(accel.x, frame, this.fps) / ppm,
+ accel.y === undefined ? 0 : sampleDriver(accel.y, frame, this.fps) / ppm,
+ ]);
+ return this;
+ }
+
+ /**
+ * A force field: called for every awake dynamic body (or just `bodies`)
+ * each solver step with its center and velocity in px, px/s; returns an
+ * acceleration `[ax, ay]` px/s² (or nothing). Wind, vortices, magnets,
+ * flow fields, a dancer's silhouette pushing particles.
+ */
+ field(
+ accel: (sample: FieldSample2D) => [number, number] | null | undefined,
+ options: { bodies?: readonly PhysicsBody2D[] } = {},
+ ): this {
+ const ppm = this.pixelsPerMeter;
+ this.addField((body, frame) => {
+ const [x, y] = body.sim.position();
+ const [vx, vy] = body.sim.velocity();
+ const a = accel({
+ x: x * ppm,
+ y: y * ppm,
+ vx: vx * ppm,
+ vy: vy * ppm,
+ frame,
+ body,
+ });
+ return a ? [a[0] / ppm, a[1] / ppm] : null;
+ }, options.bodies);
+ return this;
+ }
+
+ /** An instant kick at a simulation frame: adds `[vx, vy]` px/s to the body's velocity. */
+ impulse(
+ body: PhysicsBody2D,
+ frame: number,
+ velocity: [number, number],
+ ): this {
+ const ppm = this.pixelsPerMeter;
+ this.addImpulse(body, frame, [velocity[0] / ppm, velocity[1] / ppm]);
+ return this;
+ }
+
+ protected lerpRotation(a: number, b: number, t: number): number {
+ return a + (b - a) * t;
+ }
+
+ private joint(
+ a: PhysicsBody2D,
+ b: PhysicsBody2D,
+ spec: Parameters<SimWorld2D["addJoint"]>[2],
+ ): void {
+ this.assertOpen();
+ (this.sim as unknown as SimWorld2D).addJoint(a.sim, b.sim, spec);
+ }
+
+ private anchorBody(point: [number, number]): PhysicsBody2D {
+ return this.body(
+ { x: point[0] - 0.5, y: point[1] - 0.5, width: 1, height: 1 },
+ { type: "fixed", output: "none", sensor: true },
+ );
+ }
+
+ private endpoints(
+ a: PhysicsBody2D,
+ b: PhysicsBody2D | [number, number],
+ anchorA?: [number, number],
+ anchorB?: [number, number],
+ ): { other: PhysicsBody2D; pa: Vec2; pb: Vec2 } {
+ const pa = anchorA ?? a.center();
+ if (Array.isArray(b)) {
+ const pb = anchorB ?? b;
+ return { other: this.anchorBody(pb), pa, pb };
+ }
+ return { other: b, pa, pb: anchorB ?? b.center() };
+ }
+}
+
+function effectiveMass(a: PhysicsBody2D, b: PhysicsBody2D): number {
+ const ma = a.type === "dynamic" ? a.sim.mass() : 0;
+ const mb = b.type === "dynamic" ? b.sim.mass() : 0;
+ if (ma > 0 && mb > 0) return (ma * mb) / (ma + mb);
+ return Math.max(ma, mb, 1e-3);
+}
+
+interface LayerGeometry {
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+ scale: number;
+ anchorX: number;
+ anchorY: number;
+ rotation: number;
+ /** Collider in px, around the box center, already scaled. */
+ shape: Shape2D;
+}
+
+function num(v: unknown, fallback: number): number {
+ return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+
+function layerGeometry(
+ layer: LayerLike,
+ options: Body2DOptions,
+): LayerGeometry {
+ const id = typeof layer.id === "string" ? ` "${layer.id}"` : "";
+ if (typeof layer.x !== "number" || typeof layer.y !== "number") {
+ throw new Error(
+ `Physics: layer${id} needs numeric \`x\` and \`y\` (absolute position) to become a body.`,
+ );
+ }
+ let width =
+ options.size?.[0] ??
+ (typeof layer.width === "number" ? layer.width : undefined);
+ let height =
+ options.size?.[1] ??
+ (typeof layer.height === "number" ? layer.height : undefined);
+ if ((width === undefined || height === undefined) && layer.kind === "text") {
+ const m = FontManager.measure(String(layer.text ?? ""), {
+ fontFamily: String(layer.fontFamily ?? "Inter"),
+ fontSize: num(layer.fontSize, 48),
+ fontWeight: layer.fontWeight as never,
+ letterSpacing: num(layer.letterSpacing, 0),
+ lineHeight:
+ typeof layer.lineHeight === "number" ? layer.lineHeight : undefined,
+ });
+ width ??= m.width;
+ height ??= m.height;
+ }
+ if (
+ width === undefined ||
+ height === undefined ||
+ width <= 0 ||
+ height <= 0
+ ) {
+ throw new Error(
+ `Physics: layer${id} needs a numeric \`width\` and \`height\` (or the \`size\` option) to become a body.`,
+ );
+ }
+ const scale = num(layer.scale, 1);
+ const geom = {
+ x: layer.x,
+ y: layer.y,
+ width,
+ height,
+ scale,
+ anchorX: num(layer.anchorX, 0.5),
+ anchorY: num(layer.anchorY, 0.5),
+ rotation: num(layer.rotation, 0),
+ };
+ return {
+ ...geom,
+ shape: scaleShape(
+ colliderShape(layer, width, height, options.shape ?? "auto"),
+ scale,
+ ),
+ };
+}
+
+function colliderShape(
+ layer: LayerLike,
+ w: number,
+ h: number,
+ mode: NonNullable<Body2DOptions["shape"]>,
+): Shape2D {
+ const isShape = layer.kind === "shape";
+ const shapeType = isShape ? String(layer.shapeType ?? "rect") : "rect";
+ const radius = num(layer.borderRadius, num(layer.cornerRadius, 0));
+ const box: Shape2D = { kind: "box", hx: w / 2, hy: h / 2, radius };
+ if (mode === "box") return box;
+ if (mode === "circle" || (mode === "auto" && shapeType === "circle")) {
+ return { kind: "ball", radius: Math.min(w, h) / 2 };
+ }
+ if (mode === "auto" && shapeType === "rect") return box;
+ if (mode === "hull" || mode === "auto") {
+ const points = outlinePoints(layer, shapeType, w, h);
+ return points.length >= 6 ? { kind: "hull", points } : box;
+ }
+ return box;
+}
+
+/** The shape's outline as flat points around the box center, px. */
+function outlinePoints(
+ layer: LayerLike,
+ shapeType: string,
+ w: number,
+ h: number,
+): number[] {
+ const d =
+ shapeType === "path"
+ ? String(layer.d ?? "")
+ : buildShapeSvgPath({
+ shapeType: shapeType as ShapeGeometryConfig["shapeType"],
+ width: w,
+ height: h,
+ cornerRadius: num(layer.cornerRadius, num(layer.borderRadius, 0)),
+ polygonSides: layer.polygonSides as number | undefined,
+ starPoints: layer.starPoints as number | undefined,
+ starInnerRadiusRatio: layer.starInnerRadiusRatio as
+ | number
+ | undefined,
+ arrowHeadWidth: layer.arrowHeadWidth as number | undefined,
+ arrowHeadLength: layer.arrowHeadLength as number | undefined,
+ arrowShaftWidth: layer.arrowShaftWidth as number | undefined,
+ });
+ const out: number[] = [];
+ for (const seg of parseSvgPathToSegments(d)) {
+ out.push(
+ seg.p0.x - w / 2,
+ seg.p0.y - h / 2,
+ seg.p1.x - w / 2,
+ seg.p1.y - h / 2,
+ );
+ }
+ return out;
+}
+
+function scaleShape(shape: Shape2D, s: number): Shape2D {
+ switch (shape.kind) {
+ case "ball":
+ return { kind: "ball", radius: shape.radius * s };
+ case "box":
+ return {
+ kind: "box",
+ hx: shape.hx * s,
+ hy: shape.hy * s,
+ radius: (shape.radius ?? 0) * s,
+ };
+ case "hull":
+ return { kind: "hull", points: shape.points.map((v) => v * s) };
+ }
+}
+
+interface PivotFrame {
+ width: number;
+ height: number;
+ scale: number;
+ anchorX: number;
+ anchorY: number;
+}
+
+/**
+ * Layers rotate and scale around their pivot (`anchorX/Y` of the unscaled
+ * box); bodies rotate around their center. These convert between the two.
+ */
+function pivotOffset(rotationDeg: number, f: PivotFrame): Vec2 {
+ const a = (rotationDeg * Math.PI) / 180;
+ const dx = (0.5 - f.anchorX) * f.width * f.scale;
+ const dy = (0.5 - f.anchorY) * f.height * f.scale;
+ return [
+ dx * Math.cos(a) - dy * Math.sin(a),
+ dx * Math.sin(a) + dy * Math.cos(a),
+ ];
+}
+
+function layerToCenter(
+ x: number,
+ y: number,
+ rotationDeg: number,
+ f: PivotFrame,
+): Vec2 {
+ const [ox, oy] = pivotOffset(rotationDeg, f);
+ return [x + f.anchorX * f.width + ox, y + f.anchorY * f.height + oy];
+}
+
+function centerToLayer(
+ cx: number,
+ cy: number,
+ rotationDeg: number,
+ f: PivotFrame,
+): Vec2 {
+ const [ox, oy] = pivotOffset(rotationDeg, f);
+ return [cx - ox - f.anchorX * f.width, cy - oy - f.anchorY * f.height];
+}
diff --git a/packages/framefields/src/physics/world3d.ts b/packages/framefields/src/physics/world3d.ts
new file mode 100644
index 00000000..748414d6
--- /dev/null
+++ b/packages/framefields/src/physics/world3d.ts
@@ -0,0 +1,845 @@
+import type {
+ AnimatableProp,
+ LayoutNode,
+} from "@framefields/compositions/program";
+import type { FrameSignal } from "@framefields/core";
+import type {
+ BodySpec3D,
+ PhysicsBackend,
+ Quat,
+ Shape3D,
+ SimBody3D,
+ SimWorld3D,
+ Vec3,
+} from "./backend.js";
+import {
+ type BodyCommonOptions,
+ type CoreBody,
+ type PhysicsCollision,
+ type PhysicsDriver,
+ type PhysicsWorldOptions,
+ type Recording,
+ sampleDriver,
+ unwrapDegrees,
+ WorldCore,
+} from "./core.js";
+
+export interface World3DOptions extends PhysicsWorldOptions {
+ /** px/s², y down. A number pulls straight down. Default 2400. */
+ gravity?: number | [number, number, number];
+}
+
+/** A plain box for bodies with no layer (invisible obstacles). Centered on x/y/z like Layer3D. */
+export interface PhysicsBox3D {
+ x: number;
+ y: number;
+ z: number;
+ width: number;
+ height: number;
+ depth: number;
+ rotateX?: number;
+ rotateY?: number;
+ rotateZ?: number;
+}
+
+export interface Body3DOptions extends BodyCommonOptions {
+ /**
+ * Collider: `"auto"` (default) reads the Layer3D primitive (box, sphere,
+ * cylinder) and falls back to the mesh's convex hull for models and
+ * tapered or uneven shapes. Force `"box"`, `"sphere"`, `"cylinder"` or `"hull"`.
+ */
+ shape?: "auto" | "box" | "sphere" | "cylinder" | "hull";
+ /** Collider size override `[width, height, depth]`, px (before the layer's scale). */
+ size?: [number, number, number];
+ /** px/s. */
+ velocity?: [number, number, number];
+ /** Degrees per second around x, y, z. */
+ angularVelocity?: [number, number, number];
+ /** Kinematic bodies: the layer's `x` / `y` / `z` and `rotateX/Y/Z` each frame. */
+ follow?: {
+ x?: PhysicsDriver;
+ y?: PhysicsDriver;
+ z?: PhysicsDriver;
+ rotateX?: PhysicsDriver;
+ rotateY?: PhysicsDriver;
+ rotateZ?: PhysicsDriver;
+ };
+}
+
+type LayerLike = Record<string, unknown> & { kind?: string };
+
+const DEG = Math.PI / 180;
+
+/** Quaternion of the renderer's Euler order: R = Rz · Ry · Rx (degrees). */
+export function quatFromEuler(rx: number, ry: number, rz: number): Quat {
+ const half = (d: number) => (d * DEG) / 2;
+ const qx: Quat = [Math.sin(half(rx)), 0, 0, Math.cos(half(rx))];
+ const qy: Quat = [0, Math.sin(half(ry)), 0, Math.cos(half(ry))];
+ const qz: Quat = [0, 0, Math.sin(half(rz)), Math.cos(half(rz))];
+ return quatMul(quatMul(qz, qy), qx);
+}
+
+function quatMul(a: Quat, b: Quat): Quat {
+ const [ax, ay, az, aw] = a;
+ const [bx, by, bz, bw] = b;
+ return [
+ aw * bx + ax * bw + ay * bz - az * by,
+ aw * by - ax * bz + ay * bw + az * bx,
+ aw * bz + ax * by - ay * bx + az * bw,
+ aw * bw - ax * bx - ay * by - az * bz,
+ ];
+}
+
+/**
+ * Euler angles (degrees, R = Rz · Ry · Rx) for a quaternion, choosing of the
+ * two equivalent solutions the one closest to `previous` and unwrapping each
+ * angle, so rotations stay continuous frame to frame.
+ */
+export function eulerFromQuat(q: Quat, previous?: Vec3): Vec3 {
+ const [x, y, z, w] = q;
+ const r00 = 1 - 2 * (y * y + z * z);
+ const r10 = 2 * (x * y + w * z);
+ const r20 = 2 * (x * z - w * y);
+ const r21 = 2 * (y * z + w * x);
+ const r22 = 1 - 2 * (x * x + y * y);
+ const r01 = 2 * (x * y - w * z);
+ const r11 = 1 - 2 * (x * x + z * z);
+ const sy = Math.max(-1, Math.min(1, -r20));
+ let a: Vec3;
+ if (Math.abs(sy) > 0.999999) {
+ // Gimbal lock: only x - z (or x + z) is defined; keep x where it was.
+ const ay = Math.asin(sy);
+ const keepX = previous ? previous[0] * DEG : 0;
+ const az = Math.atan2(-r01, r11) + (sy > 0 ? keepX : -keepX);
+ a = [keepX, ay, az];
+ } else {
+ a = [Math.atan2(r21, r22), Math.asin(sy), Math.atan2(r10, r00)];
+ }
+ const first: Vec3 = [a[0] / DEG, a[1] / DEG, a[2] / DEG];
+ if (!previous) return first;
+ const second: Vec3 = [first[0] + 180, 180 - first[1], first[2] + 180];
+ const unwrap = (c: Vec3): Vec3 => [
+ unwrapDegrees(previous[0], c[0]),
+ unwrapDegrees(previous[1], c[1]),
+ unwrapDegrees(previous[2], c[2]),
+ ];
+ const p = unwrap(first);
+ const s = unwrap(second);
+ const dist = (c: Vec3) =>
+ Math.abs(c[0] - previous[0]) +
+ Math.abs(c[1] - previous[1]) +
+ Math.abs(c[2] - previous[2]);
+ return dist(p) <= dist(s) ? p : s;
+}
+
+/**
+ * A simulated 3D body. Like {@link PhysicsBody2D}, its signals hold one
+ * value per composition frame and reading one runs the simulation.
+ */
+export class PhysicsBody3D implements CoreBody<Vec3, Quat> {
+ readonly collisions: PhysicsCollision<PhysicsBody3D>[] = [];
+ /** @internal */ readonly recording: Recording;
+ /** @internal */ readonly sim: SimBody3D;
+
+ /** @internal */
+ constructor(
+ /** @internal */ readonly world: PhysicsWorld3D,
+ sim: SimBody3D,
+ readonly type: "dynamic" | "fixed" | "kinematic",
+ readonly layer: LayerLike | undefined,
+ private readonly start: { position: Vec3; rotation: Vec3 },
+ private readonly options: Body3DOptions,
+ recording: Recording,
+ ) {
+ this.sim = sim;
+ this.recording = recording;
+ }
+
+ get startFrame(): number {
+ return Math.max(0, Math.round(this.options.startFrame ?? 0));
+ }
+ get gravityScale(): number {
+ return this.options.gravityScale ?? 1;
+ }
+ get output(): Body3DOptions["output"] {
+ return this.options.output;
+ }
+
+ /** Center, px (what Layer3D's `x` / `y` / `z` mean). */
+ get x(): FrameSignal<number> {
+ return this.recording.signal("x");
+ }
+ get y(): FrameSignal<number> {
+ return this.recording.signal("y");
+ }
+ get z(): FrameSignal<number> {
+ return this.recording.signal("z");
+ }
+ /** Degrees, continuous. */
+ get rotateX(): FrameSignal<number> {
+ return this.recording.signal("rotateX");
+ }
+ get rotateY(): FrameSignal<number> {
+ return this.recording.signal("rotateY");
+ }
+ get rotateZ(): FrameSignal<number> {
+ return this.recording.signal("rotateZ");
+ }
+ /** px/s. */
+ get vx(): FrameSignal<number> {
+ return this.recording.signal("vx");
+ }
+ get vy(): FrameSignal<number> {
+ return this.recording.signal("vy");
+ }
+ get vz(): FrameSignal<number> {
+ return this.recording.signal("vz");
+ }
+ get speed(): FrameSignal<number> {
+ return this.recording.signal("speed");
+ }
+ /** Hit envelope, as on 2D bodies. */
+ get impact(): FrameSignal<number> {
+ return this.recording.signal("impact");
+ }
+ /** 1 while the body is at rest, else 0. */
+ get sleeping(): FrameSignal<number> {
+ return this.recording.signal("sleeping");
+ }
+
+ /** @internal */
+ kinematicTarget(
+ frame: number,
+ ): { position: Vec3; rotation: Quat } | undefined {
+ const follow = this.options.follow;
+ if (this.type !== "kinematic" || !follow) return undefined;
+ const fps = this.world.fps;
+ const read = (d: PhysicsDriver | undefined, fallback: number) =>
+ d === undefined ? fallback : sampleDriver(d, frame, fps);
+ const p = this.start.position;
+ const r = this.start.rotation;
+ const ppm = this.world.pixelsPerMeter;
+ return {
+ position: [
+ read(follow.x, p[0]) / ppm,
+ read(follow.y, p[1]) / ppm,
+ read(follow.z, p[2]) / ppm,
+ ],
+ rotation: quatFromEuler(
+ read(follow.rotateX, r[0]),
+ read(follow.rotateY, r[1]),
+ read(follow.rotateZ, r[2]),
+ ),
+ };
+ }
+
+ /** @internal */
+ record(index: number, previous: number): void {
+ const ppm = this.world.pixelsPerMeter;
+ const rec = this.recording;
+ const [x, y, z] = this.sim.position();
+ rec.channel("x")[index] = x * ppm;
+ rec.channel("y")[index] = y * ppm;
+ rec.channel("z")[index] = z * ppm;
+ const rx = rec.channel("rotateX");
+ const ry = rec.channel("rotateY");
+ const rz = rec.channel("rotateZ");
+ const prev: Vec3 =
+ previous < 0
+ ? this.start.rotation
+ : [rx[previous], ry[previous], rz[previous]];
+ const e = eulerFromQuat(this.sim.rotation(), prev);
+ rx[index] = e[0];
+ ry[index] = e[1];
+ rz[index] = e[2];
+ const [vx, vy, vz] = this.sim.velocity();
+ rec.channel("vx")[index] = vx * ppm;
+ rec.channel("vy")[index] = vy * ppm;
+ rec.channel("vz")[index] = vz * ppm;
+ rec.channel("speed")[index] = Math.hypot(vx, vy, vz) * ppm;
+ rec.channel("sleeping")[index] = this.sim.sleeping() ? 1 : 0;
+ }
+
+ /** @internal */
+ boundChannels(): Array<[AnimatableProp, string]> {
+ const out: Array<[AnimatableProp, string]> = [
+ ["x", "x"],
+ ["y", "y"],
+ ["z", "z"],
+ ];
+ if (!this.options.lockRotation) {
+ out.push(
+ ["rotateX", "rotateX"],
+ ["rotateY", "rotateY"],
+ ["rotateZ", "rotateZ"],
+ );
+ }
+ return out;
+ }
+
+ /** @internal World point (px) → local frame (meters) at the start pose. */
+ localAnchor(point: Vec3 | undefined): Vec3 {
+ if (!point) return [0, 0, 0];
+ const ppm = this.world.pixelsPerMeter;
+ const p = this.sim.position();
+ const [qx, qy, qz, qw] = this.sim.rotation();
+ const v: Vec3 = [
+ point[0] / ppm - p[0],
+ point[1] / ppm - p[1],
+ point[2] / ppm - p[2],
+ ];
+ return rotateByQuat(v, [-qx, -qy, -qz, qw]);
+ }
+
+ /** @internal Start-pose center, px. */
+ center(): Vec3 {
+ const ppm = this.world.pixelsPerMeter;
+ const [x, y, z] = this.sim.position();
+ return [x * ppm, y * ppm, z * ppm];
+ }
+}
+
+function rotateByQuat(v: Vec3, q: Quat): Vec3 {
+ const r = quatMul(quatMul(q, [v[0], v[1], v[2], 0]), [
+ -q[0],
+ -q[1],
+ -q[2],
+ q[3],
+ ]);
+ return [r[0], r[1], r[2]];
+}
+
+/** What a {@link PhysicsWorld3D.field} sees for one body. */
+export interface FieldSample3D {
+ x: number;
+ y: number;
+ z: number;
+ vx: number;
+ vy: number;
+ vz: number;
+ frame: number;
+ body: PhysicsBody3D;
+}
+
+export interface PhysicsSpring3DOptions {
+ length?: number;
+ frequency?: number;
+ dampingRatio?: number;
+ anchorA?: Vec3;
+ anchorB?: Vec3;
+}
+
+export interface PhysicsRope3DOptions {
+ length?: number;
+ anchorA?: Vec3;
+ anchorB?: Vec3;
+}
+
+/**
+ * A deterministic 3D rigid-body world (Rapier) for Layer3D primitives and
+ * models, in the 3D scene's pixels (y down). Same flow as 2D: add bodies,
+ * `simulate()`, and each layer's `x/y/z` and `rotateX/Y/Z` follow the
+ * simulation; bodies expose signals for everything else.
+ */
+export class PhysicsWorld3D extends WorldCore<Vec3, Quat, PhysicsBody3D> {
+ /** @internal */
+ constructor(backend: PhysicsBackend, options: World3DOptions) {
+ const ppm = options.pixelsPerMeter ?? 100;
+ const g = options.gravity ?? 2400;
+ const gravity: Vec3 =
+ typeof g === "number"
+ ? [0, g / ppm, 0]
+ : [g[0] / ppm, g[1] / ppm, g[2] / ppm];
+ super(backend.createWorld3D(gravity) as never, gravity, options);
+ }
+
+ /** Adds a body for a Layer3D primitive or model (centered on its `x/y/z`), or a plain box. */
+ body(
+ target: LayoutNode | PhysicsBox3D,
+ options: Body3DOptions = {},
+ ): PhysicsBody3D {
+ this.assertOpen();
+ const isLayer = typeof (target as unknown as LayerLike).kind === "string";
+ const layer = isLayer ? (target as unknown as LayerLike) : undefined;
+ const t = target as unknown as LayerLike;
+ const position: Vec3 = [num(t.x, 0), num(t.y, 0), num(t.z, 0)];
+ const rotation: Vec3 = [
+ num(t.rotateX, 0),
+ num(t.rotateY, 0),
+ num(t.rotateZ, 0),
+ ];
+ const ppm = this.pixelsPerMeter;
+ const type = options.type ?? "dynamic";
+ const v = options.velocity ?? [0, 0, 0];
+ const w = options.angularVelocity ?? [0, 0, 0];
+ const spec: BodySpec3D = {
+ type,
+ position: [position[0] / ppm, position[1] / ppm, position[2] / ppm],
+ rotation: quatFromEuler(rotation[0], rotation[1], rotation[2]),
+ velocity: [v[0] / ppm, v[1] / ppm, v[2] / ppm],
+ angularVelocity: [w[0] * DEG, w[1] * DEG, w[2] * DEG],
+ linearDamping: options.linearDamping ?? 0,
+ angularDamping: options.angularDamping ?? 0,
+ gravityScale: options.gravityScale ?? 1,
+ lockRotation: options.lockRotation ?? false,
+ ccd: options.ccd ?? false,
+ enabled: true,
+ sensor: options.sensor ?? false,
+ density: options.density ?? 1,
+ friction: options.friction ?? 0.6,
+ restitution: options.restitution ?? 0.3,
+ shape: scaleShape(colliderShape3D(t, options), 1 / ppm),
+ };
+ const simBody = (this.sim as unknown as SimWorld3D).addBody(spec);
+ const body = new PhysicsBody3D(
+ this,
+ simBody,
+ type,
+ layer,
+ { position, rotation },
+ options,
+ this.newRecording(),
+ );
+ return this.addBody(body);
+ }
+
+ /** A fixed, very large floor whose top face sits at `y`. */
+ ground(options: {
+ y: number;
+ friction?: number;
+ restitution?: number;
+ }): PhysicsBody3D {
+ const t = 2000;
+ return this.body(
+ { x: 0, y: options.y + t / 2, z: 0, width: 1e6, height: t, depth: 1e6 },
+ {
+ type: "fixed",
+ friction: options.friction,
+ restitution: options.restitution ?? 0.2,
+ },
+ );
+ }
+
+ /** Fixed floor and four walls around a box centered on `x`/`z`, floor at `y + height/2`. */
+ walls(options: {
+ x?: number;
+ y?: number;
+ z?: number;
+ width: number;
+ height: number;
+ depth: number;
+ thickness?: number;
+ friction?: number;
+ restitution?: number;
+ }): PhysicsBody3D[] {
+ const { width: W, height: H, depth: D } = options;
+ const [x, y, z] = [options.x ?? 0, options.y ?? 0, options.z ?? 0];
+ const t = options.thickness ?? 400;
+ const mat = {
+ type: "fixed" as const,
+ friction: options.friction,
+ restitution: options.restitution ?? 0.2,
+ };
+ const tall = H * 4;
+ const wy = y + H / 2 - tall / 2;
+ return [
+ this.body(
+ {
+ x,
+ y: y + H / 2 + t / 2,
+ z,
+ width: W + 2 * t,
+ height: t,
+ depth: D + 2 * t,
+ },
+ mat,
+ ),
+ this.body(
+ {
+ x: x - W / 2 - t / 2,
+ y: wy,
+ z,
+ width: t,
+ height: tall,
+ depth: D + 2 * t,
+ },
+ mat,
+ ),
+ this.body(
+ {
+ x: x + W / 2 + t / 2,
+ y: wy,
+ z,
+ width: t,
+ height: tall,
+ depth: D + 2 * t,
+ },
+ mat,
+ ),
+ this.body(
+ { x, y: wy, z: z - D / 2 - t / 2, width: W, height: tall, depth: t },
+ mat,
+ ),
+ this.body(
+ { x, y: wy, z: z + D / 2 + t / 2, width: W, height: tall, depth: t },
+ mat,
+ ),
+ ];
+ }
+
+ /** Pins a body to the world at a point (default its center); it can still turn around it. */
+ pin(body: PhysicsBody3D, at?: Vec3): this {
+ const point = at ?? body.center();
+ const anchor = this.anchorBody(point);
+ this.joint(body, anchor, {
+ type: "spherical",
+ anchorA: body.localAnchor(point),
+ anchorB: [0, 0, 0],
+ });
+ return this;
+ }
+
+ /** Joins two bodies at a world point, turning only around `axis` (default z, facing the camera). */
+ hinge(
+ a: PhysicsBody3D,
+ b: PhysicsBody3D,
+ at: Vec3,
+ axis: Vec3 = [0, 0, 1],
+ ): this {
+ this.joint(a, b, {
+ type: "revolute",
+ anchorA: a.localAnchor(at),
+ anchorB: b.localAnchor(at),
+ axis,
+ });
+ return this;
+ }
+
+ /** Glues two bodies together rigidly. */
+ weld(a: PhysicsBody3D, b: PhysicsBody3D): this {
+ this.joint(a, b, {
+ type: "fixed",
+ anchorA: [0, 0, 0],
+ anchorB: b.localAnchor(a.center()),
+ });
+ return this;
+ }
+
+ spring(
+ a: PhysicsBody3D,
+ b: PhysicsBody3D | Vec3,
+ options: PhysicsSpring3DOptions = {},
+ ): this {
+ const { other, pa, pb } = this.endpoints(
+ a,
+ b,
+ options.anchorA,
+ options.anchorB,
+ );
+ const ppm = this.pixelsPerMeter;
+ const length = (options.length ?? dist(pa, pb)) / ppm;
+ const ma = a.type === "dynamic" ? a.sim.mass() : 0;
+ const mb = other.type === "dynamic" ? other.sim.mass() : 0;
+ const mass =
+ ma > 0 && mb > 0 ? (ma * mb) / (ma + mb) : Math.max(ma, mb, 1e-3);
+ const w = 2 * Math.PI * (options.frequency ?? 2);
+ this.joint(a, other, {
+ type: "spring",
+ anchorA: a.localAnchor(pa),
+ anchorB: other.localAnchor(pb),
+ restLength: length,
+ stiffness: mass * w * w,
+ damping: 2 * (options.dampingRatio ?? 0.2) * mass * w,
+ });
+ return this;
+ }
+
+ rope(
+ a: PhysicsBody3D,
+ b: PhysicsBody3D | Vec3,
+ options: PhysicsRope3DOptions = {},
+ ): this {
+ const { other, pa, pb } = this.endpoints(
+ a,
+ b,
+ options.anchorA,
+ options.anchorB,
+ );
+ this.joint(a, other, {
+ type: "rope",
+ anchorA: a.localAnchor(pa),
+ anchorB: other.localAnchor(pb),
+ length: (options.length ?? dist(pa, pb)) / this.pixelsPerMeter,
+ });
+ return this;
+ }
+
+ /** A steady push, px/s² (mass-independent). Drivers are read every frame. */
+ force(
+ body: PhysicsBody3D,
+ accel: { x?: PhysicsDriver; y?: PhysicsDriver; z?: PhysicsDriver },
+ ): this {
+ const ppm = this.pixelsPerMeter;
+ const read = (d: PhysicsDriver | undefined, frame: number) =>
+ d === undefined ? 0 : sampleDriver(d, frame, this.fps) / ppm;
+ this.addForce(body, (frame) => [
+ read(accel.x, frame),
+ read(accel.y, frame),
+ read(accel.z, frame),
+ ]);
+ return this;
+ }
+
+ /** A force field, as in 2D: returns `[ax, ay, az]` px/s² for a body at `x/y/z` px. */
+ field(
+ accel: (sample: FieldSample3D) => Vec3 | null | undefined,
+ options: { bodies?: readonly PhysicsBody3D[] } = {},
+ ): this {
+ const ppm = this.pixelsPerMeter;
+ this.addField((body, frame) => {
+ const [x, y, z] = body.sim.position();
+ const [vx, vy, vz] = body.sim.velocity();
+ const a = accel({
+ x: x * ppm,
+ y: y * ppm,
+ z: z * ppm,
+ vx: vx * ppm,
+ vy: vy * ppm,
+ vz: vz * ppm,
+ frame,
+ body,
+ });
+ return a ? [a[0] / ppm, a[1] / ppm, a[2] / ppm] : null;
+ }, options.bodies);
+ return this;
+ }
+
+ /** An instant kick at a simulation frame: adds `[vx, vy, vz]` px/s. */
+ impulse(body: PhysicsBody3D, frame: number, velocity: Vec3): this {
+ const ppm = this.pixelsPerMeter;
+ this.addImpulse(body, frame, [
+ velocity[0] / ppm,
+ velocity[1] / ppm,
+ velocity[2] / ppm,
+ ]);
+ return this;
+ }
+
+ protected lerpRotation(a: Quat, b: Quat, t: number): Quat {
+ // Normalized lerp along the short arc; fine for per-substep steps.
+ const sign =
+ a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3] < 0 ? -1 : 1;
+ const q = a.map((v, i) => v + (b[i] * sign - v) * t) as Quat;
+ const len = Math.hypot(...q) || 1;
+ return q.map((v) => v / len) as Quat;
+ }
+
+ private joint(
+ a: PhysicsBody3D,
+ b: PhysicsBody3D,
+ spec: Parameters<SimWorld3D["addJoint"]>[2],
+ ): void {
+ this.assertOpen();
+ (this.sim as unknown as SimWorld3D).addJoint(a.sim, b.sim, spec);
+ }
+
+ private anchorBody(point: Vec3): PhysicsBody3D {
+ return this.body(
+ { x: point[0], y: point[1], z: point[2], width: 1, height: 1, depth: 1 },
+ { type: "fixed", output: "none", sensor: true },
+ );
+ }
+
+ private endpoints(
+ a: PhysicsBody3D,
+ b: PhysicsBody3D | Vec3,
+ anchorA?: Vec3,
+ anchorB?: Vec3,
+ ): { other: PhysicsBody3D; pa: Vec3; pb: Vec3 } {
+ const pa = anchorA ?? a.center();
+ if (Array.isArray(b)) {
+ const pb = anchorB ?? b;
+ return { other: this.anchorBody(pb), pa, pb };
+ }
+ return { other: b, pa, pb: anchorB ?? b.center() };
+ }
+}
+
+function dist(a: Vec3, b: Vec3): number {
+ return Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2]);
+}
+
+function num(v: unknown, fallback: number): number {
+ return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+
+interface PrimitiveSpec {
+ type?: string;
+ width?: number;
+ height?: number;
+ depth?: number;
+ radius?: number;
+ radiusTop?: number;
+ radiusBottom?: number;
+ taper?: number;
+}
+
+/** Collider in px around the layer's center, with the layer's scale applied. */
+function colliderShape3D(t: LayerLike, options: Body3DOptions): Shape3D {
+ const id = typeof t.id === "string" ? ` "${t.id}"` : "";
+ const s = num(t.scale, 1);
+ const scale: Vec3 = [
+ s * num(t.scaleX, 1),
+ s * num(t.scaleY, 1),
+ s * num(t.scaleZ, 1),
+ ];
+ const uniform = scale[0] === scale[1] && scale[1] === scale[2];
+ const prim = (t.primitive3d ?? {}) as PrimitiveSpec;
+ const mode = options.shape ?? "auto";
+ const hull = (): Shape3D | undefined => {
+ const pts = meshPoints(t.modelData);
+ if (!pts) return undefined;
+ return { kind: "hull", points: pts.map((v, i) => v * scale[i % 3]) };
+ };
+
+ if (options.size || mode === "box") {
+ const [w, h, d] = options.size ?? boxSize(t, prim) ?? [0, 0, 0];
+ if (w > 0 && h > 0 && d > 0) {
+ return {
+ kind: "box",
+ hx: (w * scale[0]) / 2,
+ hy: (h * scale[1]) / 2,
+ hz: (d * scale[2]) / 2,
+ radius:
+ prim.type === "roundedBox"
+ ? num(prim.radius, 0) * Math.min(...scale)
+ : 0,
+ };
+ }
+ }
+ if (mode === "hull") {
+ const h = hull();
+ if (h) return h;
+ }
+ const sphere =
+ mode === "sphere" || (mode === "auto" && prim.type === "sphere");
+ if (sphere && (uniform || mode === "sphere")) {
+ const r = num(prim.radius, 0) || Math.max(...(boxSize(t, prim) ?? [0])) / 2;
+ if (r > 0) return { kind: "ball", radius: r * Math.max(...scale) };
+ }
+ const rTop = num(prim.radiusTop, num(prim.radius, 0));
+ const rBottom = num(prim.radiusBottom, num(prim.radius, 0));
+ const cylinder =
+ mode === "cylinder" || (mode === "auto" && prim.type === "cylinder");
+ if (cylinder && rTop === rBottom && rTop > 0 && scale[0] === scale[2]) {
+ return {
+ kind: "cylinder",
+ halfHeight: (num(prim.height, 0) * scale[1]) / 2,
+ radius: rTop * scale[0],
+ };
+ }
+ if (
+ mode === "auto" &&
+ prim.type === "roundedBox" &&
+ (prim.taper ?? 1) === 1
+ ) {
+ const [w, h, d] = [
+ num(prim.width, 0),
+ num(prim.height, 0),
+ num(prim.depth, 0),
+ ];
+ return {
+ kind: "box",
+ hx: (w * scale[0]) / 2,
+ hy: (h * scale[1]) / 2,
+ hz: (d * scale[2]) / 2,
+ radius: num(prim.radius, 0) * Math.min(...scale),
+ };
+ }
+ const h = hull();
+ if (h) return h;
+ const size = boxSize(t, prim);
+ if (size) {
+ return {
+ kind: "box",
+ hx: (size[0] * scale[0]) / 2,
+ hy: (size[1] * scale[1]) / 2,
+ hz: (size[2] * scale[2]) / 2,
+ };
+ }
+ throw new Error(
+ `Physics: layer${id} has no mesh or size to build a 3D collider from; pass \`size: [w, h, d]\`.`,
+ );
+}
+
+function boxSize(t: LayerLike, prim: PrimitiveSpec): Vec3 | undefined {
+ if (prim.type === "roundedBox")
+ return [num(prim.width, 0), num(prim.height, 0), num(prim.depth, 0)];
+ if (prim.type === "sphere") {
+ const d = num(prim.radius, 0) * 2;
+ return [d, d, d];
+ }
+ if (prim.type === "cylinder") {
+ const d =
+ Math.max(
+ num(prim.radiusTop, num(prim.radius, 0)),
+ num(prim.radiusBottom, num(prim.radius, 0)),
+ ) * 2;
+ return [d, num(prim.height, 0), d];
+ }
+ if (
+ typeof t.width === "number" &&
+ typeof t.height === "number" &&
+ typeof t.depth === "number"
+ ) {
+ return [t.width, t.height, t.depth];
+ }
+ return undefined;
+}
+
+/** Every vertex of a model, flat xyz, at most ~4k points (the hull needs no more). */
+function meshPoints(modelData: unknown): number[] | undefined {
+ const meshes = (
+ modelData as
+ | { meshes?: Array<{ positions?: ArrayLike<number> }> }
+ | undefined
+ )?.meshes;
+ if (!meshes?.length) return undefined;
+ let total = 0;
+ for (const m of meshes) total += (m.positions?.length ?? 0) / 3;
+ if (total < 4) return undefined;
+ const stride = Math.max(1, Math.floor(total / 4096));
+ const out: number[] = [];
+ let i = 0;
+ for (const m of meshes) {
+ const p = m.positions;
+ if (!p) continue;
+ for (let v = 0; v < p.length; v += 3, i++) {
+ if (i % stride === 0) out.push(p[v], p[v + 1], p[v + 2]);
+ }
+ }
+ return out;
+}
+
+function scaleShape(shape: Shape3D, s: number): Shape3D {
+ switch (shape.kind) {
+ case "ball":
+ return { kind: "ball", radius: shape.radius * s };
+ case "box":
+ return {
+ kind: "box",
+ hx: shape.hx * s,
+ hy: shape.hy * s,
+ hz: shape.hz * s,
+ radius: (shape.radius ?? 0) * s,
+ };
+ case "cylinder":
+ return {
+ kind: "cylinder",
+ halfHeight: shape.halfHeight * s,
+ radius: shape.radius * s,
+ };
+ case "hull":
+ return { kind: "hull", points: shape.points.map((v) => v * s) };
+ }
+}
diff --git a/packages/framefields/tsdown.config.ts b/packages/framefields/tsdown.config.ts
index 0e278c86..78f7a1a3 100644
--- a/packages/framefields/tsdown.config.ts
+++ b/packages/framefields/tsdown.config.ts
@@ -23,6 +23,7 @@ export default defineConfig({
/^@napi-rs\//,
/^@resvg\//,
/^@mediabunny\//,
+ /^@dimforge\//,
/^@lottiefiles\//,
"mediabunny",
"onnxruntime-node",
diff --git a/plugins/framefields/skills/framefields-compose/SKILL.md b/plugins/framefields/skills/framefields-compose/SKILL.md
index 6148cd27..be775a71 100644
--- a/plugins/framefields/skills/framefields-compose/SKILL.md
+++ b/plugins/framefields/skills/framefields-compose/SKILL.md
@@ -369,6 +369,50 @@ Layer3D.cylinder({ ..., color: "#111", emissive: "#4da3ff", emissiveIntensity: 3
---
+## Physics (`Physics.world2d` / `Physics.world3d`)
+
+Use for anything that should *fall, bounce, stack, swing or collide*: gravity drops of words or cards, UI pieces tumbling into a pile, a "jiggle" on a spring, balls rattling in a box, dominoes, physics-driven 3D products. Use keyframes instead for motion that should hit an exact designed pose at an exact frame.
+
+A world runs **once** while the composition is built (Rapier, deterministic build: identical on every machine) and replays as per-frame signals, so frames render in any order. `simulate()` binds each body's layer (`x`, `y`, `rotation`; in 3D `x/y/z`, `rotateX/Y/Z`):
+
+```typescript
+import { Layer, LayerAnimation, Physics } from "framefields";
+
+const world = await Physics.world2d({ fps: FPS, frames: 150 }); // gravity 2400 px/s², y down
+world.walls({ width: W, height: H - 160 }); // floor + sides (ceiling: true to close)
+
+const cards = words.map((word, i) => {
+ const card = Layer.box({ position: "absolute", x: 140, y: -300 - i * 260, width: 560, height: 170, rotation: -8, borderRadius: 28, background: EMBER /* … */ });
+ world.body(card, { restitution: 0.35, startFrame: i * 6 }); // staggered drop
+ return card;
+});
+world.simulate();
+
+// Every body exposes signals; bind them to anything (props, effect uniforms):
+glow.animate(LayerAnimation.create().signal("opacity", world.impact, { multiplier: 1.5 })); // loudest hit
+stage.animate(LayerAnimation.create().signal("y", world.impact, { multiplier: 14 })); // camera shake
+```
+
+- **Bodies come from layers** with numeric `x`, `y` and a size; the layer's pose (incl. `rotation`, `scale`, `anchorX/Y`) is the start pose. Colliders follow the layer: circles are balls, `borderRadius` rounds the box, polygons / stars / paths use their convex hull, text without a size is measured. Override with `shape: "box" | "circle" | "hull"` and `size: [w, h]`. Plain `{ x, y, width, height }` makes an invisible obstacle.
+- **Body options:** `type: "dynamic" | "fixed" | "kinematic"`, `restitution` (0.3), `friction` (0.6), `density` (1), `velocity: [vx, vy]` px/s, `angularVelocity` °/s, `linearDamping`, `angularDamping`, `gravityScale` (0 floats), `lockRotation`, `ccd` (very fast bodies), `sensor`, `startFrame` (holds its pose until then), `output: "signals" | "keyframes" | "none"`.
+- **Signals per body:** `x`, `y`, `rotation`, `centerX`, `centerY`, `vx`, `vy`, `speed`, `angularVelocity`, `sleeping`, `impact` (jumps on each new contact, 1 ≈ a 1500 px/s hit, decays over `impactDecay` frames). `world.impact` is the loudest body each frame. `body.collisions` / `world.collisions` list first contacts `{ frame, with, speed }`: place hit sounds or flashes at those frames.
+- **Scene:** `world.ground({ y })`, `world.walls({ x, y, width, height, ceiling })`.
+- **Joints:** `world.pin(body, [x, y])` (swing around a point), `world.hinge(a, b, [x, y])`, `world.weld(a, b)`, `world.spring(a, bOrPoint, { frequency: 2, dampingRatio: 0.2, length })`, `world.rope(a, bOrPoint, { length })`. Points are world px.
+- **Driving the simulation:** `world.force(body, { x, y })` (px/s², mass-independent), `world.impulse(body, frame, [vx, vy])` (a kick), kinematic `follow: { x, y, rotation }`. Each of these takes a number, a signal (audio, `Signal.fromArray`) or `(frame) => value`: e.g. a floor that bounces on the kick.
+- **Force fields:** `world.field((s) => [ax, ay], { bodies })` is called every solver step with a body's center `s.x`, `s.y` (px), velocity `s.vx`, `s.vy` and `s.frame`; return px/s² or nothing. Wind, vortices, attractors, flow fields — and performers (below).
+- **Performers in the simulation:** `const person = (await comp.trackPerson("dancer.mp4")).place({ width: W, height: H, fit: "cover" })` analyses the clip *before* rendering (pose + silhouette, a few hundred ms/frame; cache with `toJSON()` / `PersonTrack.fromJSON()`). Then:
+ - limbs as kinematic colliders that catch and bat things: `world.body({ x, y, width: 2 * r, height: 2 * r }, { type: "kinematic", shape: "circle", follow: { x: (f) => person.point("leftWrist", f).x - r, y: (f) => person.point("leftWrist", f).y - r } })`, a few balls along each shoulder → elbow → wrist;
+ - the silhouette (dress included) as a force field: `person.sample(frame, x, y)` returns `alpha` (inside > 0.5) and a gradient `gx`, `gy` pointing inward, so `world.field((s) => { const m = person.sample(s.frame, s.x, s.y); … return [-m.gx * k, -m.gy * k]; })` makes particles and props flow around a moving body.
+ - Layer a vision cutout of the same clip (`Layer.video(src).withVision({ mode: "matte" })`) above the particles so they pass behind the performer.
+- **Particles today:** up to ~600 small `Layer.shape("circle")` bodies with `linearDamping` ≈ 1–1.5, low `friction`, `gravityScale` < 1 read as a fluid; tint them by speed with `.colorSignal("fillColor", heat, { colorA, colorB })` built from `body.speed`.
+- **Keyframes instead of signals:** `world.bakeKeyframes({ tolerance: 0.25 })` in place of `simulate()` writes plain, simplified linear keyframes (editable, plain JSON).
+- **3D:** `Physics.world3d` takes `Layer3D.roundedBox / sphere / cylinder` and models (convex hull of the mesh); same options with 3-vectors, `world.hinge(a, b, at, axis)`, `world.walls({ width, height, depth })`.
+- **Timing:** signals are on the composition clock. In a scene that starts at frame `S`, pass `startFrame: S` to the world. Before it and after `frames` the signals hold their first/last value. Add every body, joint and force before `simulate()` (or before reading any signal): the world then locks.
+- **Feel:** gravity 2400 px/s² reads snappy on a 1080p canvas; `pixelsPerMeter` (100) scales how heavy things feel. Raise `substeps` (4) for tall stacks or thin, fast bodies.
+- Install note: physics uses the optional dependency `@dimforge/rapier2d-deterministic-compat` / `rapier3d-deterministic-compat` (installed by default with framefields).
+
+---
+
## Critical Authoring Rules & Gotchas
1. **Local Keyframe Coordinates:** Keyframes are strictly relative to the node's own timeline window (`0` = node appearance). Never offset keyframe frames by the parent's `startFrame`.
diff --git a/plugins/framefields/skills/framefields-effects/SKILL.md b/plugins/framefields/skills/framefields-effects/SKILL.md
index a139af5b..1f3b0da1 100644
--- a/plugins/framefields/skills/framefields-effects/SKILL.md
+++ b/plugins/framefields/skills/framefields-effects/SKILL.md
@@ -236,7 +236,18 @@ const vision = comp.withVision({ classes: ["person"] });
layer.blurRegion(vision.objects.byCategory("person"), { strength: 30 });
```
-### 5. Analyze Before Authoring
+### 5. Track a Performer Before Rendering
+Render-time vision signals lag a frame and only exist while rendering. For anything that must know the motion up front (physics, keyframes, layout), track the person first:
+```typescript
+const person = (await comp.trackPerson("assets/dancer.mp4")).place({ width: W, height: H, fit: "cover" });
+person.point("rightWrist", 48); // { x, y, visibility } in composition px, smoothed, gaps filled
+person.signals("nose").x; // per-frame signal for .signal("x", …)
+person.sample(48, x, y); // silhouette alpha + inward gradient (dress and held things included)
+writeFileSync("dancer-track.json", JSON.stringify(person.toJSON())); // reuse with PersonTrack.fromJSON
+```
+Options: `pose`, `mask` (both default true), `maskCell` (silhouette grid, default 8 px), `smoothing` (frames, default 2), `variant`. See *Physics* in `framefields-compose` for limbs as colliders and the silhouette as a force field.
+
+### 6. Analyze Before Authoring
One-shot, ffmpeg-free report of what is in a clip (tracks, classes, mask coverage):
```typescript
const report = await comp.analyzeVisionSequence("assets/street.mp4", {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6dda4d0b..653d39d0 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -413,6 +413,47 @@ importers:
specifier: ^5.8.3
version: 5.9.3
+ examples/28_physics_dancer:
+ dependencies:
+ framefields:
+ specifier: workspace:*
+ version: link:../../packages/framefields
+ devDependencies:
+ '@framefields/tsconfig':
+ specifier: workspace:*
+ version: link:../../packages/tsconfig
+ '@types/node':
+ specifier: ^24.1.0
+ version: 24.10.14
+ tsx:
+ specifier: ^4.20.3
+ version: 4.21.0
+ typescript:
+ specifier: ^5.8.3
+ version: 5.9.3
+
+ examples/e_kofte:
+ dependencies:
+ framefields:
+ specifier: workspace:*
+ version: link:../../packages/framefields
+ mediabunny:
+ specifier: ^1.61.6
+ version: 1.61.6
+ devDependencies:
+ '@framefields/tsconfig':
+ specifier: workspace:*
+ version: link:../../packages/tsconfig
+ '@types/node':
+ specifier: ^24.1.0
+ version: 24.10.14
+ tsx:
+ specifier: ^4.20.3
+ version: 4.21.0
+ typescript:
+ specifier: ^5.8.3
+ version: 5.9.3
+
nodes/node-apply-lut:
dependencies:
'@framefields/core':
@@ -2515,6 +2556,12 @@ importers:
specifier: ^4.1.11
optionalDependencies:
+ '@dimforge/rapier2d-deterministic-compat':
+ specifier: 0.21.0
+ version: 0.21.0
+ '@dimforge/rapier3d-deterministic-compat':
+ specifier: 0.21.0
+ version: 0.21.0
onnxruntime-web:
specifier: ^1.24.0
version: 1.30.0
@@ -3201,6 +3248,12 @@ packages:
resolution: {integrity: sha512-QxULHAm7cNu72w97JUNCBFODFaXpbDg+dP8b/oWFAZ2MTRppA3U00Y2L1HqaS4J6yBqxwa/Y3nMBaxVKbB/NsA==}
engines: {node: '>=20.19.0'}
+ '@dimforge/[email protected]':
+ resolution: {integrity: sha512-qVwHqqpRX73ktQRqiAa/0JdBfWdzsGHg8r8d+snaZB0WRXaTs3m7GU6jN+Qf3gEjMEUqk3Rc9q87yGXHkktTbA==}
+
+ '@dimforge/[email protected]':
+ resolution: {integrity: sha512-n7JuU62Obljlgq+OeH2DHhTmRSjRzwuJPl54tS9pFIzVQyvXsO5CH+a5KkIRBtnFWDbg1Zicv9BulG0jfBAopA==}
+
'@emnapi/[email protected]':
resolution: {integrity: sha512-AvT9QFpxK0Zd8J0jopedNm+w/2fIzvtPKPjqyw9jwvBaReTTqPBk9Hixaz7KbjimP+QNz605/XnjFcDAL2pqBg==}
@@ -6648,6 +6701,12 @@ snapshots:
'@csstools/[email protected]':
optional: true
+ '@dimforge/[email protected]':
+ optional: true
+
+ '@dimforge/[email protected]':
+ optional: true
+
'@emnapi/[email protected]':
dependencies:
'@emnapi/wasi-threads': 1.1.0