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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.mdindex 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 & Gotchas1. **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.mdindex 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 AuthoringOne-shot, ffmpeg-free report of what is in a clip (tracks, classes, mask coverage):```typescriptconst report = await comp.analyzeVisionSequence("assets/street.mp4", {diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 6dda4d0b..653d39d0 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -413,6 +413,47 @@ importers:specifier: ^5.8.3version: 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.11version: 4.1.11(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected](@noble/[email protected])([email protected]))([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected])([email protected]))optionalDependencies:+ '@dimforge/rapier2d-deterministic-compat':+ specifier: 0.21.0+ version: 0.21.0+ '@dimforge/rapier3d-deterministic-compat':+ specifier: 0.21.0+ version: 0.21.0onnxruntime-web:specifier: ^1.24.0version: 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