Code-first video & image, rendered natively on WebGPU.
fix(3d): review fixes for motion blur and fracture; fracture follows animation
okanaslc16c954f902e
diff --git a/nodes/node-compositor/SKILL.md b/nodes/node-compositor/SKILL.mdindex 5ac6a94c..d2dffbf4 100644--- a/nodes/node-compositor/SKILL.md+++ b/nodes/node-compositor/SKILL.md@@ -230,7 +230,7 @@ Each track represents animatable property modifications:- **Procedural Shards (`Layer3D.shard`):** Procedural polyhedron primitive generated by Sutherland-Hodgman convex half-space clipping against Fibonacci lattice normals with PCG jitter. Faceted flat normals, automatic planar UVs, Rapier 3D convex hull collision.- **Character rigs (`animationLayers`, `ik`, `lookAt`, `springBones` on a glTF `model3d`):** clips blend in order from the rest pose, each over the pose beneath by `weight` (number, `[[frame, w]]` keys, or `(frame) => w` in process), slerped per joint and restricted to `mask` joints and their descendants; `speed`, `timeOffset`, `loop` per layer. Then `lookAt` (joint `axis`, default glTF +z, clamped to `maxAngleDeg`) and analytic two-bone `ik` (`chain: [root, mid, effector]`, `poleTarget` sets the bend side); targets are scene coordinates (point, keys or function) mapped into model space through the model's transform. `springBones` (each root's chain down its first child; `stiffness`, `damping`, scene `gravity`) are Verlet-simulated from frame 0 and cached per layer, so frames come out the same in any order. A node without these keeps the single-clip path.- **Skinned crowds (`crowd` on an instances node):** `{ clips, fps (30), seed, speedRange, phase: "random" | "sync" }`; each mesh of each variant model bakes its joint matrices (or its node matrix, for rigid node meshes) for every clip once (`count + 1` samples per loop) into a GPU palette; instances take a second record (clip range, phase, playback rate) and skin in the vertex shader, interpolating two baked samples. Per instance `clip`, `animOffset`, `animSpeed` override the seeded defaults. One draw call per mesh, shadows included. Instance (and scatter) variants apply their own node `rotateX/Y/Z` and `scale` under each instance's transform.-- **Voronoi destruction (`fracture3d` on a model node):** `{ cells, seed, impactPoint (object space), interiorColor, interiorRoughness, track }`. The compositor fractures the loaded source model (`fractureModel`, cached per model and spec) into one rigidly skinned mesh (a joint per piece), then poses the joints from `track` (x, y, z, qx, qy, qz, qw per piece per frame, scene space): node matrix M⁻¹ · T(p) · R(q) · S. While every piece is still at its frame-0 pose (or there is no track) it draws in the exact rest pose with the cut faces skipped, so the whole layer is sealed (a cut face can otherwise tie the surface's depth where pieces meet).+- **Voronoi destruction (`fracture3d` on a model node):** `{ cells, seed, impactPoint (object space), interiorColor, interiorRoughness, track }`. The compositor fractures the loaded source model (`fractureModel`, cached per model and spec) into one rigidly skinned mesh (a joint per piece), then poses the joints from `track` (x, y, z, qx, qy, qz, qw per piece per frame, in the layer's parent space, as physics reads its x/y/z): node matrix L⁻¹ · T(p) · R(q) · S, with L the layer's own prop matrix, so pieces stay in their 3D group. While every piece is still at its frame-0 pose (or there is no track) it draws in the exact rest pose with the cut faces skipped, so the whole layer is sealed (a cut face can otherwise tie the surface's depth where pieces meet).- **Shutter motion blur (`motionBlur` on the camera):** after the color pass (and fog, DoF), the queued meshes and planes are drawn again into a velocity target, with this and the previous frame's model matrices, skinning, instance records (GPU copies), wind and crowd time, and this and the previous camera. Then the scene is blurred (tile max, neighbor max, gather) before bloom. Previous state lives in a per-render motion history keyed by node id and item index. When frame f - 1 is missing, the compositor first renders it with `motionHistoryOnly` (3D passes only record), so output does not depend on render order.- **Automatic mesh instancing:** consecutive opaque draws of the same shared mesh with matching material state use one GPU draw with per-object model and normal matrices. Transparent, skinned, morphed, audio-deformed and glass meshes retain separate draws; shadows retain their individual draw submissions.- **Instanced 3D Meshes (`instances3d`):** `kind: "model3d"` with `instances3d` renders hundreds or thousands of mesh instances in 1 GPU draw call (`drawIndexed(indexCount, instanceCount)`). Supports single or multi-mesh variants with round-robin or variant indexing, dynamic per-instance transforms, and per-instance emissive / color modulation. In `framefields`, created with `Layer3D.instances({ count, mesh, instanceAt, bodies, emissiveBySpeed })`.diff --git a/nodes/node-compositor/src/renderers/fracture.ts b/nodes/node-compositor/src/renderers/fracture.tsindex fe286557..a5b54744 100644--- a/nodes/node-compositor/src/renderers/fracture.ts+++ b/nodes/node-compositor/src/renderers/fracture.ts@@ -65,16 +65,18 @@ function blend(}/**- * Model-space matrices of the pieces' nodes at `frame`: a piece at scene- * pose (p, q) has node matrix M⁻¹ · T(p) · R(q) · S, so with its inverse- * bind T(−centroid) a vertex lands at p + q · S · (v − centroid).- * Undefined without a track (the rest pose).+ * Model-space matrices of the pieces' nodes at `frame`. The track is in the+ * layer's parent space (physics reads the layer's own x/y/z, as for any+ * body), and `layerProps` is the layer's matrix in that space, L. A piece+ * at pose (p, q) has node matrix L⁻¹ · T(p) · R(q) · S, so with its inverse+ * bind T(−centroid) a vertex lands at parent · (p + q · S · (v − centroid)):+ * pieces fly in their group, like other bodies. Undefined without a track.*/export function fracturePose(model: Model3DData,spec: Fracture3DSpec,frame: number,- sceneRoot: Mat4,+ layerProps: Mat4,scale: Vec3,): Mat4[] | undefined {const track = spec.track;@@ -86,7 +88,7 @@ export function fracturePose(const f = Math.min(Math.max(frame, 0), frames - 1);const f0 = Math.floor(f);const f1 = Math.min(frames - 1, f0 + 1);- const toModel = Matrix4Math.invert(sceneRoot) ?? Matrix4Math.identity();+ const toModel = Matrix4Math.invert(layerProps) ?? Matrix4Math.identity();const out: Mat4[] = [];for (let i = 0; i < pieces; i++) {const { p, q } = blend(diff --git a/nodes/node-compositor/src/renderers/webgpu-renderer.ts b/nodes/node-compositor/src/renderers/webgpu-renderer.tsindex 149842ab..1af94789 100644--- a/nodes/node-compositor/src/renderers/webgpu-renderer.ts+++ b/nodes/node-compositor/src/renderers/webgpu-renderer.ts@@ -48,6 +48,7 @@ import {type CrowdBake,type DrawMesh3DOpts,type DrawQuad3DOpts,+ type Environment3DFloor,type Environment3DOptions,type ExtrudedTextGeometryOptions,FRACTURE_INTERIOR_MATERIAL,@@ -1087,17 +1088,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {: (frame ?? 0),);const compositionFrame = props.compositionFrame ?? shiftedFrame;- // Shutter motion blur reads every 3D draw one frame earlier: after a- // seek, render the frame before first, recording only.const historyOnly = props.motionHistoryOnly === true;- if (- !historyOnly &&- frame != null &&- sceneMotionBlur(virtualMedia) &&- motionHistory(ctx.device, props.renderId).needsPrevious(shiftedFrame)- ) {- await renderMotionHistory(args, frame - 1);- }// 1. Create a temporary texture at native resolutionconst compTex = ctx.renderer.getTemporaryTexture(@@ -1115,6 +1106,18 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {durationSec,});const { targetsById } = compiled;+ // Shutter motion blur reads every 3D draw one frame earlier: after a+ // seek, render the frame before first, recording only. The history is+ // this composition's (render id and content), not the render id's: still+ // renders reuse ids across compositions.+ if (+ !historyOnly &&+ frame != null &&+ sceneMotionBlur(virtualMedia) &&+ motionHistory(ctx.device, compiled.key).needsPrevious(shiftedFrame)+ ) {+ await renderMotionHistory(args, frame - 1);+ }seekTimeline(compiled, shiftedFrame, fps ?? 24);const r3d = getRenderer3D(@@ -1439,7 +1442,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {const blur = (camOp as CameraNode | undefined)?.motionBlur;if (blur && fps) {motionBlur = blur === true ? {} : blur;- history = motionHistory(ctx.device, props.renderId);+ history = motionHistory(ctx.device, compiled.key);}// Collect Active Lights@@ -1671,6 +1674,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {color: GPUTexture,into: GPUTexture,blur: CameraMotionBlur,+ floor: Environment3DFloor | undefined,) => {const r3d = getRenderer3D(ctx.device,@@ -1684,6 +1688,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {cam,h.previousCamera(shiftedFrame) ?? cam,);+ if (floor) r3d.drawFloorVelocity(vel.pass, vel.cameraBindGroup, floor);for (const [item, key] of motionItems()) {if (item.kind === "mesh") {const prev = key@@ -2175,7 +2180,14 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {nativeHeight,[curTex, targetTexture, scene3dTex, final3dTex, ...curExcludes],);- blurScene(history, camera, final3dTex, blurredTex, motionBlur);+ blurScene(+ history,+ camera,+ final3dTex,+ blurredTex,+ motionBlur,+ floorSpec && blurredReflectionTex ? floorSpec : undefined,+ );final3dTex = blurredTex;}if (history) recordMotion(history, camera);@@ -2616,6 +2628,15 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {return;}}+ // Recording motion needs only the 3D draws: flat leaves (video,+ // text, effects) skip their work in the history pass.+ if (+ historyOnly &&+ !isContainer &&+ kind !== "model3d" &&+ !has3DTransform(target, lop)+ )+ return;if (kind === "model3d") {const r3d = getRenderer3D(ctx.device,@@ -3680,6 +3701,12 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {finalModelMatrix,model.rootTransform ?? Matrix4Math.identity(),);+ // The layer's own props as a matrix (before any parent maps them):+ // physics works in that space, the parent's, like every body.+ const layerProps = Matrix4Math.multiply(+ Matrix4Math.translate(sampledX - posX, sampledY - posY, 0),+ localM,+ );// A whole fracture rests exactly (identity joints): pieces stay sealed.const wholeFracture = Boolean(lop.fracture3d &&@@ -3688,7 +3715,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {const posed =(lop.fracture3d &&!wholeFracture &&- fracturePose(model, lop.fracture3d, shiftedFrame ?? 0, sceneRoot, [+ fracturePose(model, lop.fracture3d, shiftedFrame ?? 0, layerProps, [scX,scY,scZ,@@ -3702,7 +3729,8 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {clip,clipSec,sceneRoot,- key: String(lop.id),+ // Per composition: node ids repeat across compositions.+ key: `${compiled.key}:${lop.id}`,}): undefined);const skinCache = new Map<number, Float32Array>();@@ -6414,6 +6442,9 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {true,);currentCompTex = renderResult.finalTex;+ // The frame is recorded even when nothing 3D drew (hidden, not started),+ // so the next frame needs no history pass and the camera's motion is known.+ if (history && camera) history.recordFrame(shiftedFrame, camera);ctx.renderer.popTransform();ctx.renderer.popScissor();diff --git a/nodes/node-compositor/src/shared/bezier-solver.ts b/nodes/node-compositor/src/shared/bezier-solver.tsindex feeb0d25..7256811b 100644--- a/nodes/node-compositor/src/shared/bezier-solver.ts+++ b/nodes/node-compositor/src/shared/bezier-solver.ts@@ -2,6 +2,7 @@* Cubic Bezier and Speed Curve Solver for Motion Graphics* Provides analytical/Newton-Raphson solvers for unit easing curves and 2D spatial trajectory splines.*/+import { solveCubicBezier } from "@framefields/compositions/program";export interface Point2D {x: number;@@ -25,74 +26,7 @@ export interface SplineSegment {endFrame: number;}-/**- * Solves a cubic bezier curve defined by control points (x1, y1) and (x2, y2)- * for a given progress parameter t in [0, 1].- */-export function solveCubicBezier(- x1: number,- y1: number,- x2: number,- y2: number,- t: number,-): number {- if (t <= 0) return 0;- if (t >= 1) return 1;-- // Check for linear edge case- if (x1 === y1 && x2 === y2) return t;-- // Find u such that x(u) = t- // x(u) = 3*(1-u)^2 * u * x1 + 3*(1-u) * u^2 * x2 + u^3- // dx/du = 3*(1-u)^2 * x1 + 6*(1-u)*u * (x2 - x1) + 3*u^2 * (1 - x2)- let u = t; // initial guess- for (let i = 0; i < 8; i++) {- const oneMinusU = 1 - u;- const oneMinusU2 = oneMinusU * oneMinusU;- const u2 = u * u;-- const currentX = 3 * oneMinusU2 * u * x1 + 3 * oneMinusU * u2 * x2 + u2 * u;- const diff = currentX - t;- if (Math.abs(diff) < 1e-6) break;-- const dx =- 3 * oneMinusU2 * x1 + 6 * oneMinusU * u * (x2 - x1) + 3 * u2 * (1 - x2);-- if (Math.abs(dx) < 1e-6) break;- u -= diff / dx;- u = Math.max(0, Math.min(1, u));- }-- // Bisection fallback if Newton didn't converge within bounds- const oneMinusU = 1 - u;- const checkX =- 3 * oneMinusU * oneMinusU * u * x1 + 3 * oneMinusU * u * u * x2 + u * u * u;-- if (Math.abs(checkX - t) > 1e-3) {- let low = 0;- let high = 1;- u = t;- for (let i = 0; i < 16; i++) {- const mid = (low + high) * 0.5;- const oMid = 1 - mid;- const xMid =- 3 * oMid * oMid * mid * x1 +- 3 * oMid * mid * mid * x2 +- mid * mid * mid;- if (Math.abs(xMid - t) < 1e-5) {- u = mid;- break;- }- if (xMid < t) low = mid;- else high = mid;- u = mid;- }- }-- // Evaluate y(u)- const oU = 1 - u;- return 3 * oU * oU * u * y1 + 3 * oU * u * u * y2 + u * u * u;-}+export { solveCubicBezier };/*** Calculates the instantaneous speed (derivative |dy/dt|) at parameter t in [0, 1].diff --git a/nodes/node-compositor/src/shared/compiler.ts b/nodes/node-compositor/src/shared/compiler.tsindex c2f0ca0b..0aa26222 100644--- a/nodes/node-compositor/src/shared/compiler.ts+++ b/nodes/node-compositor/src/shared/compiler.ts@@ -2,10 +2,10 @@ import { resolveLayerDuration } from "@framefields/compositions";import {type AnimationTrack,collectNodeOps,- type EaseRef,- evaluateKeyframes,evaluateTrackAtFrame,type LayerAnimationSpec,+ mappedEase,+ sampleTrack,} from "@framefields/compositions/program";import {DEFAULT_DURATION_MS,@@ -14,7 +14,6 @@ import {type VirtualMediaData,} from "@framefields/core";import gsapModule from "gsap";-import { solveCubicBezier } from "./bezier-solver.js";const gsap = (gsapModule as any).timeline? gsapModule@@ -130,6 +129,8 @@ export type CompilerVirtualMedia = {export type CompilerNodeVM = CompilerVirtualMedia;export interface CompileResult {+ /** Render id plus a hash of the compiled nodes: one composition's identity across frames. */+ key: string;tl: gsap.core.Timeline;targetsById: Record<string, LayerStub>;/** Node ops the timeline was compiled from (tree order). */@@ -152,38 +153,6 @@ interface LiveTrack {step?: number;}-/** GSAP's shaping for a keyframe segment, so draw-time tracks ease like baked ones. */-function gsapEase(- fps: number,-): (ease: EaseRef | undefined, deltaFrames: number, t: number) => number {- return (ease, deltaFrames, t) => {- const e = mappedEase(ease, deltaFrames, fps);- const fn = typeof e === "function" ? e : gsap.parseEase(e);- return fn ? fn(t) : t;- };-}--function evaluateLive(- live: LiveTrack,- frame: number,- fps: number,- signals: Record<string, any> | undefined,-) {- const source = live.track.source ?? { type: "keyframe" };- if (source.type === "keyframe") {- return evaluateKeyframes(- live.track,- frame - live.startFrame,- gsapEase(fps),- );- }- return evaluateTrackAtFrame(live.track, frame, fps, {- startFrame: live.startFrame,- baseValues: live.stub,- signals,- });-}-/** Seeks the compiled timeline to a frame and applies its live signal tracks. */export function seekTimeline(result: CompileResult,@@ -198,7 +167,11 @@ export function seekTimeline(live.startFrame +Math.floor((f - live.startFrame) / live.step) * live.step;}- live.stub[live.track.prop] = evaluateLive(live, f, fps, result.signals);+ live.stub[live.track.prop] = sampleTrack(live.track, f, fps, {+ startFrame: live.startFrame,+ base: live.stub,+ signals: result.signals,+ });}}@@ -343,85 +316,6 @@ export function setCachedTimeline(cacheKey: string, value: CompileResult) {cache.set(cacheKey, { cacheTime: Date.now(), value });}-export function mappedEase(- ease?: EaseRef,- durationFrames?: number,- fps = 24,-): string | ((p: number) => number) {- if (!ease) return "none";- const { name, dir, params } = ease;- if (name === "none") return "none";-- // Custom closed-form Spring ease solver- if ((name as string) === "spring") {- const damping = Math.max(0.001, params?.[0] ?? 10);- const stiffness = Math.max(0.001, params?.[1] ?? 100);- const mass = Math.max(0.001, params?.[2] ?? 1);-- return (p: number) => {- const safeFps = fps > 0 ? fps : 24;- const durSec =- durationFrames && durationFrames > 0 ? durationFrames / safeFps : 1.0;- const t = p * durSec;-- const m = mass;- const k = stiffness;- const c = damping;-- const w0 = Math.sqrt(k / m);- const zeta = c / (2 * Math.sqrt(k * m));-- let x = 0;- if (zeta < 1) {- const wd = w0 * Math.sqrt(1 - zeta * zeta);- const A = -1;- const B = (-zeta * w0) / wd;- x =- Math.exp(-zeta * w0 * t) *- (A * Math.cos(wd * t) + B * Math.sin(wd * t));- } else if (zeta === 1) {- const A = -1;- const B = -w0;- x = Math.exp(-w0 * t) * (A + B * t);- } else {- const r1 = -w0 * (zeta - Math.sqrt(zeta * zeta - 1));- const r2 = -w0 * (zeta + Math.sqrt(zeta * zeta - 1));- const C1 = -1 / (1 - r1 / r2);- const C2 = -1 - C1;- x = C1 * Math.exp(r1 * t) + C2 * Math.exp(r2 * t);- }- return 1 + x;- };- }-- if ((name as string) === "cubic") {- const x1 = params?.[0] ?? 0.25;- const y1 = params?.[1] ?? 0.1;- const x2 = params?.[2] ?? 0.25;- const y2 = params?.[3] ?? 1.0;- return (p: number) => solveCubicBezier(x1, y1, x2, y2, p);- }-- if ((name as string) === "hold") {- // GSAP rounds time to 1e-7 s, so on its own end frame a short segment's- // progress can land ~1e-5 under 1; 1e-4 of a segment is safe slack for the- // jump (it would only fire a frame early on segments over 10,000 frames).- return (p: number) => (p >= 1 - 1e-4 ? 1 : 0);- }-- const easeName = name as string;- let suffix = "";- if (params && params.length > 0) {- suffix = `(${params.join(", ")})`;- } else if (name === "back") {- suffix = "(1.7)";- } else if (name === "elastic") {- suffix = "(1, 0.3)";- }-- return `${easeName}.${dir}${suffix}`;-}-/** Props that switch rather than tween: each key is a set from its frame on. */const DISCRETE_PROPS: ReadonlySet<string> = new Set(["hidden", "muted"]);@@ -458,7 +352,11 @@ function compileTrackToTimeline(endFrame: startFrame + endF,...(stepped && { step }),};- stub[prop] = evaluateLive(entry, startFrame, fps, signals);+ stub[prop] = sampleTrack(track, startFrame, fps, {+ startFrame,+ base: stub,+ signals,+ });live.push(entry);return { dropped: 0, maxAuthoredFrame: 0 };}@@ -1097,6 +995,7 @@ export function compileTimeline(tl.seek(0);const compileResult: CompileResult = {+ key: cacheKey,tl,targetsById,nodes: nodeOps,diff --git a/nodes/node-compositor/src/shared/track-sampler.test.ts b/nodes/node-compositor/src/shared/track-sampler.test.tsnew file mode 100644index 00000000..e5b2b609--- /dev/null+++ b/nodes/node-compositor/src/shared/track-sampler.test.ts@@ -0,0 +1,95 @@+/**+ * The shared track sampler (what physics follows a layer with) must agree+ * with the compiled GSAP timeline (what the compositor draws) frame for+ * frame, eases, layer offsets and stepped timing included.+ */+import {+ type AnimatedLayer,+ sampleLayerProp,+} from "@framefields/compositions/program";+import { describe, expect, it } from "vitest";+import { compileTimeline, seekTimeline } from "./compiler.js";++const FPS = 30;++function layer(extra: Partial<AnimatedLayer>): AnimatedLayer {+ return {+ id: "mover",+ x: 10,+ rotateZ: 0,+ startFrame: 6,+ durationFrames: 90,+ animation: {+ tracks: [+ {+ id: "tx",+ prop: "x",+ keyframes: [+ { id: "a", frame: 0, value: 0 },+ {+ id: "b",+ frame: 20,+ value: 300,+ ease: { name: "power3", dir: "inOut" },+ },+ {+ id: "c",+ frame: 45,+ value: 120,+ ease: { name: "back", dir: "out" },+ },+ {+ id: "d",+ frame: 60,+ value: 500,+ ease: { name: "cubic", dir: "out", params: [0.2, 0.8, 0.3, 1] },+ },+ ],+ },+ {+ id: "rz",+ prop: "rotateZ",+ keyframes: [+ { id: "a", frame: 5, value: 0 },+ {+ id: "b",+ frame: 50,+ value: 270,+ ease: { name: "elastic", dir: "out" },+ },+ ],+ },+ ],+ },+ ...extra,+ } as AnimatedLayer;+}++function compare(l: AnimatedLayer) {+ const vm = {+ operation: { op: "Compositor", width: 800, height: 600 },+ children: [{ operation: { op: "CompositorLayer", ...l } }],+ };+ const compiled = compileTimeline(`sampler-${Math.random()}`, vm as never, {+ fps: FPS,+ durationSec: 4,+ });+ const stub = compiled.targetsById.mover as unknown as Record<string, number>;+ for (let f = 0; f <= 100; f += 3) {+ seekTimeline(compiled, f, FPS);+ for (const prop of ["x", "rotateZ"]) {+ expect(sampleLayerProp(l, prop, f, FPS)).toBeCloseTo(stub[prop]!, 3);+ }+ }+}++describe("sampleLayerProp", () => {+ it("matches the GSAP timeline for eased keys at a layer offset", () => {+ compare(layer({}));+ });++ it("matches stepped timing", () => {+ const l = layer({});+ compare({ ...l, animation: { ...l.animation, frameStep: 4 } });+ });+});diff --git a/packages/compositions/package.json b/packages/compositions/package.jsonindex b7275947..36626fbc 100644--- a/packages/compositions/package.json+++ b/packages/compositions/package.json@@ -57,6 +57,7 @@"@framefields/renderers": "workspace:*","@framefields/webgpu-renderers": "workspace:*","@mediabunny/mp3-encoder": "^1.61.6",+ "gsap": "^3.15.0","yoga-layout": "^3.2.1"},"publishConfig": {diff --git a/packages/compositions/src/program/index.ts b/packages/compositions/src/program/index.tsindex 4c64317e..b71ddcdd 100644--- a/packages/compositions/src/program/index.ts+++ b/packages/compositions/src/program/index.ts@@ -19,4 +19,5 @@ export * from "./schema.js";export * from "./sequence.js";export * from "./stagger.js";export * from "./to-virtual-media.js";+export * from "./track-sampler.js";export * from "./validate.js";diff --git a/packages/compositions/src/program/track-sampler.ts b/packages/compositions/src/program/track-sampler.tsnew file mode 100644index 00000000..d34d7bcb--- /dev/null+++ b/packages/compositions/src/program/track-sampler.ts@@ -0,0 +1,243 @@+/**+ * Sampling a layer's animation at a frame exactly as the compositor draws+ * it: keyframe segments shaped by GSAP's eases (what the compiled GSAP+ * timeline plays), other sources (wiggle, spring, signals) by the program+ * evaluator. The compositor's draw-time tracks and anything that must agree+ * with the picture outside a render (physics following a layer) share it.+ */+import gsapModule from "gsap";+import { evaluateKeyframes, evaluateTrackAtFrame } from "./evaluator.js";+import type { AnimationTrack, EaseRef } from "./schema.js";++type EaseFn = (p: number) => number;+interface GsapEases {+ parseEase(ease: string): EaseFn | undefined;+}+const gsap = ((gsapModule as unknown as { default?: GsapEases }).default ??+ gsapModule) as unknown as GsapEases;++/**+ * Solves a cubic bezier curve defined by control points (x1, y1) and (x2, y2)+ * for a given progress parameter t in [0, 1].+ */+export function solveCubicBezier(+ x1: number,+ y1: number,+ x2: number,+ y2: number,+ t: number,+): number {+ if (t <= 0) return 0;+ if (t >= 1) return 1;++ // Check for linear edge case+ if (x1 === y1 && x2 === y2) return t;++ // Find u such that x(u) = t+ // x(u) = 3*(1-u)^2 * u * x1 + 3*(1-u) * u^2 * x2 + u^3+ // dx/du = 3*(1-u)^2 * x1 + 6*(1-u)*u * (x2 - x1) + 3*u^2 * (1 - x2)+ let u = t; // initial guess+ for (let i = 0; i < 8; i++) {+ const oneMinusU = 1 - u;+ const oneMinusU2 = oneMinusU * oneMinusU;+ const u2 = u * u;++ const currentX = 3 * oneMinusU2 * u * x1 + 3 * oneMinusU * u2 * x2 + u2 * u;+ const diff = currentX - t;+ if (Math.abs(diff) < 1e-6) break;++ const dx =+ 3 * oneMinusU2 * x1 + 6 * oneMinusU * u * (x2 - x1) + 3 * u2 * (1 - x2);++ if (Math.abs(dx) < 1e-6) break;+ u -= diff / dx;+ u = Math.max(0, Math.min(1, u));+ }++ // Bisection fallback if Newton didn't converge within bounds+ const oneMinusU = 1 - u;+ const checkX =+ 3 * oneMinusU * oneMinusU * u * x1 + 3 * oneMinusU * u * u * x2 + u * u * u;++ if (Math.abs(checkX - t) > 1e-3) {+ let low = 0;+ let high = 1;+ u = t;+ for (let i = 0; i < 16; i++) {+ const mid = (low + high) * 0.5;+ const oMid = 1 - mid;+ const xMid =+ 3 * oMid * oMid * mid * x1 ++ 3 * oMid * mid * mid * x2 ++ mid * mid * mid;+ if (Math.abs(xMid - t) < 1e-5) {+ u = mid;+ break;+ }+ if (xMid < t) low = mid;+ else high = mid;+ u = mid;+ }+ }++ // Evaluate y(u)+ const oU = 1 - u;+ return 3 * oU * oU * u * y1 + 3 * oU * u * u * y2 + u * u * u;+}++export function mappedEase(+ ease?: EaseRef,+ durationFrames?: number,+ fps = 24,+): string | ((p: number) => number) {+ if (!ease) return "none";+ const { name, dir, params } = ease;+ if (name === "none") return "none";++ // Custom closed-form Spring ease solver+ if ((name as string) === "spring") {+ const damping = Math.max(0.001, params?.[0] ?? 10);+ const stiffness = Math.max(0.001, params?.[1] ?? 100);+ const mass = Math.max(0.001, params?.[2] ?? 1);++ return (p: number) => {+ const safeFps = fps > 0 ? fps : 24;+ const durSec =+ durationFrames && durationFrames > 0 ? durationFrames / safeFps : 1.0;+ const t = p * durSec;++ const m = mass;+ const k = stiffness;+ const c = damping;++ const w0 = Math.sqrt(k / m);+ const zeta = c / (2 * Math.sqrt(k * m));++ let x = 0;+ if (zeta < 1) {+ const wd = w0 * Math.sqrt(1 - zeta * zeta);+ const A = -1;+ const B = (-zeta * w0) / wd;+ x =+ Math.exp(-zeta * w0 * t) *+ (A * Math.cos(wd * t) + B * Math.sin(wd * t));+ } else if (zeta === 1) {+ const A = -1;+ const B = -w0;+ x = Math.exp(-w0 * t) * (A + B * t);+ } else {+ const r1 = -w0 * (zeta - Math.sqrt(zeta * zeta - 1));+ const r2 = -w0 * (zeta + Math.sqrt(zeta * zeta - 1));+ const C1 = -1 / (1 - r1 / r2);+ const C2 = -1 - C1;+ x = C1 * Math.exp(r1 * t) + C2 * Math.exp(r2 * t);+ }+ return 1 + x;+ };+ }++ if ((name as string) === "cubic") {+ const x1 = params?.[0] ?? 0.25;+ const y1 = params?.[1] ?? 0.1;+ const x2 = params?.[2] ?? 0.25;+ const y2 = params?.[3] ?? 1.0;+ return (p: number) => solveCubicBezier(x1, y1, x2, y2, p);+ }++ if ((name as string) === "hold") {+ // GSAP rounds time to 1e-7 s, so on its own end frame a short segment's+ // progress can land ~1e-5 under 1; 1e-4 of a segment is safe slack for the+ // jump (it would only fire a frame early on segments over 10,000 frames).+ return (p: number) => (p >= 1 - 1e-4 ? 1 : 0);+ }++ const easeName = name as string;+ let suffix = "";+ if (params && params.length > 0) {+ suffix = `(${params.join(", ")})`;+ } else if (name === "back") {+ suffix = "(1.7)";+ } else if (name === "elastic") {+ suffix = "(1, 0.3)";+ }++ return `${easeName}.${dir}${suffix}`;+}++/** GSAP's shaping for a keyframe segment, so draw-time tracks ease like baked ones. */+export function gsapEase(+ fps: number,+): (ease: EaseRef | undefined, deltaFrames: number, t: number) => number {+ return (ease, deltaFrames, t) => {+ const e = mappedEase(ease, deltaFrames, fps);+ const fn = typeof e === "function" ? e : gsap.parseEase(e);+ return fn ? fn(t) : t;+ };+}++export interface TrackSampleContext {+ /** The layer's start frame: keyframes are relative to it. */+ startFrame?: number;+ /** Stepped timing ("on twos" = 2): the value holds for this many frames. */+ step?: number;+ /** The layer's own values, for sources that modulate them. */+ base?: Record<string, unknown>;+ signals?: Record<string, unknown>;+}++/** A track's value at composition frame `frame`. */+export function sampleTrack(+ track: AnimationTrack,+ frame: number,+ fps: number,+ ctx: TrackSampleContext = {},+): number | boolean | string {+ const startFrame = ctx.startFrame ?? 0;+ const step = ctx.step ?? 1;+ const f =+ step > 1+ ? startFrame + Math.floor((frame - startFrame) / step) * step+ : frame;+ const source = track.source ?? { type: "keyframe" };+ if (source.type === "keyframe") {+ return evaluateKeyframes(track, f - startFrame, gsapEase(fps));+ }+ return evaluateTrackAtFrame(track, f, fps, {+ startFrame,+ baseValues: ctx.base,+ signals: ctx.signals,+ });+}++/** What `sampleLayerProp` reads from a layer. */+export interface AnimatedLayer {+ startFrame?: number;+ animation?: { tracks?: AnimationTrack[]; frameStep?: number };+ [prop: string]: unknown;+}++/**+ * A layer's numeric prop at composition frame `frame`: its own value, then+ * each of its tracks on that prop in order (a later track overrides).+ */+export function sampleLayerProp(+ layer: AnimatedLayer,+ prop: string,+ frame: number,+ fps: number,+ fallback = 0,+): number {+ const own = layer[prop];+ let value = typeof own === "number" && Number.isFinite(own) ? own : fallback;+ const animation = layer.animation;+ for (const track of animation?.tracks ?? []) {+ if (track.prop !== prop) continue;+ const v = sampleTrack(track, frame, fps, {+ startFrame: layer.startFrame ?? 0,+ step: animation?.frameStep,+ base: layer,+ });+ if (typeof v === "number" && Number.isFinite(v)) value = v;+ }+ return value;+}diff --git a/packages/framefields/src/motion-blur-render.test.ts b/packages/framefields/src/motion-blur-render.test.tsindex a6fbf42d..d2425a92 100644--- a/packages/framefields/src/motion-blur-render.test.ts+++ b/packages/framefields/src/motion-blur-render.test.ts@@ -233,4 +233,39 @@ describe("shutter motion blur", () => {}expect(partialB).toBeGreaterThan(partialA * 1.3);});++ it("keeps each composition's motion history its own", async () => {+ // Still renders reuse render ids across compositions: B must not read+ // A's frame 20 (same node id, moving the other way) as its own.+ const backward = () => scene([mover(-24)]);+ await backward().renderFrame({ frame: 20 });+ const after = await scene([mover(24)]).renderFrame({ frame: 21 });+ const fresh = scene([mover(24)]);+ await fresh.renderFrame({ frame: 20 });+ expect(after).toEqual(await fresh.renderFrame({ frame: 21 }));+ });++ it("blurs with an environment floor and bloom", async () => {+ const comp = scene([+ Layer.environment({ floor: { y: C + 60 }, bloom: true } as never),+ Layer3D.sphere({+ id: "orb",+ x: C,+ y: C,+ radius: 30,+ color: "#ffffff",+ emissive: "#ffffff",+ emissiveIntensity: 4,+ }).animate(+ LayerAnimation.create().keys("x", [+ [0, C - 600],+ [60, C + 600],+ ]),+ ),+ ]);+ const { pixels } = await decodePngPixels(+ await comp.renderFrame({ frame: 30 }),+ );+ expect(pixels.some((v, i) => i % 4 === 0 && v > 200)).toBe(true);+ });});diff --git a/packages/framefields/src/physics/backend.ts b/packages/framefields/src/physics/backend.tsindex ae25929b..3bb390db 100644--- a/packages/framefields/src/physics/backend.ts+++ b/packages/framefields/src/physics/backend.ts@@ -90,6 +90,8 @@ export interface SimBody<V, R> {mass(): number;setEnabled(enabled: boolean): void;applyImpulse(impulse: V): void;+ /** Teleports the body (wakes it): position, and rotation. */+ setPose(position: V, rotation: R): void;/** Sets linear and angular velocity (wakes the body). */setVelocity(linear: V, angular: R extends number ? number : Vec3): void;setKinematicTarget(position: V, rotation: R): void;@@ -229,6 +231,10 @@ class RapierWorld2D implements SimWorld2D {mass: () => body.mass(),setEnabled: (on) => body.setEnabled(on),applyImpulse: ([x, y]) => body.applyImpulse({ x, y }, true),+ setPose: ([x, y], angle) => {+ body.setTranslation({ x, y }, true);+ body.setRotation(angle, true);+ },setVelocity: ([x, y], w) => {body.setLinvel({ x, y }, true);body.setAngvel(w, true);@@ -367,6 +373,10 @@ class RapierWorld3D implements SimWorld3D {mass: () => body.mass(),setEnabled: (on) => body.setEnabled(on),applyImpulse: (v) => body.applyImpulse(vec3(v), true),+ setPose: (p, [x, y, z, w]) => {+ body.setTranslation(vec3(p), true);+ body.setRotation({ x, y, z, w }, true);+ },setVelocity: (v, w) => {body.setLinvel(vec3(v), true);body.setAngvel(vec3(w), true);diff --git a/packages/framefields/src/physics/fracture-render.test.ts b/packages/framefields/src/physics/fracture-render.test.tsindex 2784addf..9ac9df04 100644--- a/packages/framefields/src/physics/fracture-render.test.ts+++ b/packages/framefields/src/physics/fracture-render.test.ts@@ -9,6 +9,7 @@ import {CompositorProgramSchema,Layer,Layer3D,+ LayerAnimation,type LayoutNode,} from "../index.js";import { decodePngPixels } from "../test-utils/pixels.js";@@ -163,4 +164,118 @@ describe("Physics.fracture", () => {const replay = await scene([copy]).renderFrame({ frame: 25 });expect(replay).toEqual(direct);});++ it("breaks a moving layer where it is, its pieces carrying its motion", async () => {+ // Slides right 4 px per frame and turns; breaks at frame 12 with no+ // burst and no gravity: the pieces keep flying as the layer did.+ const slide = () =>+ slab("slab").animate(+ LayerAnimation.create()+ .keys("x", [+ [0, C - 80],+ [40, C + 80],+ ])+ .keys("rotateZ", [+ [0, 0],+ [40, 20],+ ]),+ );+ const whole = scene([slide()]);+ const target = slide();+ const comp = scene([target]);+ const world = await Physics.world3d({ fps: FPS, frames: 40, gravity: 0 });+ const broken = world.fracture(target, { cells: 10, fractureFrame: 12 });+ world.simulate();+ expect(broken.frame).toBe(12);+ const centroid = async (c: Composition, f: number) => {+ const { pixels } = await decodePngPixels(+ await c.renderFrame({ frame: f }),+ );+ let sx = 0;+ let n = 0;+ for (let i = 0; i < pixels.length; i += 4) {+ if ((pixels[i] ?? 0) > 128) {+ sx += (i / 4) % SIZE;+ n++;+ }+ }+ return sx / n;+ };+ for (const f of [12, 13, 20]) {+ // Linear keys sampled with the renderer's eases: the pieces track+ // the animation the whole layer would have followed.+ expect(+ Math.abs((await centroid(comp, f)) - (await centroid(whole, f))),+ ).toBeLessThan(1.5);+ }+ });++ it("collides along its animation and breaks on what it hits", async () => {+ const target = slab("slab").animate(+ LayerAnimation.create().keys("x", [+ [0, C - 150],+ [30, C + 150],+ ]),+ );+ const ball = Layer3D.sphere({+ id: "ball",+ x: C + 40,+ y: C,+ radius: 20,+ color: "#ffffff",+ material: "unlit",+ });+ const world = await Physics.world3d({ fps: FPS, frames: 30, gravity: 0 });+ const broken = world.fracture(target, { cells: 8 });+ world.body(ball);+ world.simulate();+ // The slab's right face (x + 80) meets the ball's left (C + 20) near frame 9.+ expect(broken.frame).toBeGreaterThan(6);+ expect(broken.frame).toBeLessThan(12);+ });++ it("refuses a layer whose scale is animated", async () => {+ const target = slab("slab").animate(+ LayerAnimation.create().keys("scale", [+ [0, 1],+ [30, 2],+ ]),+ );+ const world = await Physics.world3d({ fps: FPS, frames: 30 });+ expect(() => world.fracture(target, { cells: 8 })).toThrow(+ /animates scale/,+ );+ });++ it("flies its pieces in the space of a 3D group, like other bodies", async () => {+ const group = (child: LayoutNode) =>+ Layer.box({+ position: "absolute",+ x: 60,+ y: 0,+ width: SIZE,+ height: SIZE,+ is3D: true,+ transformStyle: "preserve-3d",+ children: [child],+ });+ const target = slab("slab");+ const comp = scene([group(target)]);+ const world = await Physics.world3d({ fps: FPS, frames: 20, gravity: 0 });+ world.fracture(target, { cells: 8, fractureFrame: 5 });+ world.simulate();+ // Still pieces (no burst, no gravity) stay exactly where the whole layer was.+ const before = await comp.renderFrame({ frame: 3 });+ const after = await comp.renderFrame({ frame: 15 });+ const { pixels: a } = await decodePngPixels(before);+ const { pixels: b } = await decodePngPixels(after);+ let diff = 0;+ let lit = 0;+ for (let i = 0; i < a.length; i += 4) {+ if ((a[i] ?? 0) > 128) lit++;+ if (Math.abs((a[i] ?? 0) - (b[i] ?? 0)) > 60) diff++;+ }+ expect(lit).toBeGreaterThan(1000);+ expect(diff).toBeLessThan(lit * 0.02);+ });});diff --git a/packages/framefields/src/physics/fracture3d.ts b/packages/framefields/src/physics/fracture3d.tsindex 24b35d2e..b3f85eac 100644--- a/packages/framefields/src/physics/fracture3d.ts+++ b/packages/framefields/src/physics/fracture3d.ts@@ -5,9 +5,11 @@* into the node (`fracture3d.track`), where the renderer turns them into* the joints of one rigidly skinned mesh.*/-import type {- Fracture3DSpec,- LayoutNode,+import {+ type AnimatedLayer,+ type Fracture3DSpec,+ type LayoutNode,+ sampleLayerProp,} from "@framefields/compositions/program";import {createRandom,@@ -16,8 +18,15 @@ import {Matrix4Math,type Model3DData,} from "@framefields/webgpu-renderers";-import type { Vec3 } from "./backend.js";-import type { LayerLike, PhysicsBody3D, PhysicsWorld3D } from "./world3d.js";+import type { Quat, Vec3 } from "./backend.js";+import {+ type Body3DOptions,+ type LayerLike,+ type PhysicsBody3D,+ type PhysicsWorld3D,+ quatFromEuler,+ rotateByQuat,+} from "./world3d.js";export interface Fracture3DOptions {/** Voronoi pieces (2..256). Default 48. */@@ -28,7 +37,9 @@ export interface Fracture3DOptions {impactPoint?: [number, number, number];/*** Composition frame the layer breaks at, or `"onImpact"` (default): the- * first frame a body hits it.+ * first frame a body hits it. An animated layer (position, rotation)+ * collides along its path while whole and breaks where it is, its pieces+ * carrying its motion.*/fractureFrame?: number | "onImpact";/** Color of the faces the break exposes. Default "#d8d2c4". */@@ -106,6 +117,62 @@ const apply = (m: Mat4, p: Vec3): Vec3 => [m[2] * p[0] + m[6] * p[1] + m[10] * p[2] + m[14],];+const SCALE_PROPS = ["scale", "scaleX", "scaleY", "scaleZ"];++/** The animated props among `props` (tracks on them). */+function animatedProps(node: LayerLike, props: readonly string[]): string[] {+ const tracks = (node.animation as AnimatedLayer["animation"])?.tracks ?? [];+ return props.filter((p) => tracks.some((t) => t.prop === p));+}++/** Rigid pieces cannot change size: a fractured layer's scale holds still. */+function assertRigid(node: LayerLike): void {+ const scaling = animatedProps(node, SCALE_PROPS);+ if (!scaling.length) return;+ const id = typeof node.id === "string" ? ` "${node.id}"` : "";+ throw new Error(+ `Physics.fracture: layer${id} animates ${scaling.join(", ")}; rigid pieces cannot change size. Keep a fractured layer's scale still (position and rotation may animate).`,+ );+}++/**+ * The layer's animated position and rotation as kinematic drivers, sampled+ * as the compositor draws them (GSAP eases, stepped timing, signals), so the+ * stand-in collider is where the layer is; undefined when it holds still.+ * Read lazily: animation added after `fracture()` counts.+ */+function followLayer(+ node: LayerLike,+ fps: number,+): Body3DOptions["follow"] | undefined {+ const layer = node as AnimatedLayer;+ const at = (prop: string) => (frame: number) =>+ sampleLayerProp(layer, prop, frame, fps);+ // The renderer reads rotateZ, falling back to the 2D `rotation`.+ const rotateZ = (frame: number) =>+ animatedProps(node, ["rotateZ"]).length || typeof node.rotateZ === "number"+ ? sampleLayerProp(layer, "rotateZ", frame, fps)+ : sampleLayerProp(layer, "rotation", frame, fps);+ return {+ x: at("x"),+ y: at("y"),+ z: at("z"),+ rotateX: at("rotateX"),+ rotateY: at("rotateY"),+ rotateZ,+ };+}++const MOVING_PROPS = [+ "x",+ "y",+ "z",+ "rotateX",+ "rotateY",+ "rotateZ",+ "rotation",+];+/** @internal */export function createFracture(world: PhysicsWorld3D,@@ -120,6 +187,7 @@ export function createFracture(`Physics.fracture: layer${id} has no mesh. Fracture a Layer3D primitive, extruded text, or a model node that carries modelData.`,);}+ assertRigid(node);const pose = nodePose(node);const toObject = Matrix4Math.invert(pose.matrix) ?? Matrix4Math.identity();const spec: Fracture3DSpec = {@@ -136,7 +204,19 @@ export function createFracture(const { cells } = fractureModel(model, spec);node.fracture3d = spec;- const intact = world.body(target, { type: "fixed", output: "none" });+ // While whole, a collider of its own shape stands in: fixed, or kinematic+ // along the layer's animation.+ const moving = animatedProps(node, MOVING_PROPS).length > 0;+ const intact = world.body(+ target,+ moving+ ? {+ type: "kinematic",+ output: "none",+ follow: followLayer(node, world.fps),+ }+ : { type: "fixed", output: "none" },+ );const pieces = cells.map((cell) =>world.shapedBody(undefined,@@ -174,25 +254,45 @@ export function createFracture(if (!due) return;fracture.brokeAt = f;intact.sim.setEnabled(false);- breakApart(world, pieces, options, radius, pose.position, hitter, f);+ breakApart(world, pieces, options, radius, intact, pose, hitter, f);});world.onSimulated(() => {+ assertRigid(node);spec.track = recordTrack(pieces, world.startFrame + world.frames);});return fracture;}-/** Wakes every piece: outward from the impact, plus some of the hitter's momentum. */+/** Where the stand-in is and how it moves (px, quaternion, px/s, rad/s). */+function standInState(world: PhysicsWorld3D, intact: PhysicsBody3D) {+ const ppm = world.pixelsPerMeter;+ return {+ position: intact.sim.position().map((v) => v * ppm) as Vec3,+ rotation: intact.sim.rotation(),+ velocity: intact.sim.velocity().map((v) => v * ppm) as Vec3,+ spin: intact.sim.angularVelocity() as Vec3,+ };+}++/**+ * Wakes every piece where the layer is now (the stand-in's pose, which+ * follows its animation), carrying the layer's own motion, plus a burst+ * outward from the impact and some of the hitter's momentum.+ */function breakApart(world: PhysicsWorld3D,pieces: readonly PhysicsBody3D[],options: Fracture3DOptions,radius: number,- center: Vec3,+ intact: PhysicsBody3D,+ rest: NodePose,hitter: PhysicsBody3D | undefined,frame: number,): void {const ppm = world.pixelsPerMeter;+ const layer = standInState(world, intact);+ const q0 = quatFromEuler(...rest.rotation);+ const undoRest: Quat = [-q0[0], -q0[1], -q0[2], q0[3]];const hitAt = hitter?.sim.position().map((v) => v * ppm) as Vec3 | undefined;const transfer = options.momentumTransfer ?? 0.35;// The stand-in collider just bounced the hitter; it should have gone on@@ -209,22 +309,49 @@ function breakApart(hitter.sim.angularVelocity(),);}- const impact = options.impactPoint ?? hitAt ?? center;+ const impact = options.impactPoint ?? hitAt ?? layer.position;const speed = options.explosionSpeed ?? 0;const spin = options.spin ?? speed / 3;const rand = createRandom((options.seed ?? 1) * 7717 + 3);for (const piece of pieces) {- const p = piece.center();+ // The piece rests at the layer's authored pose: move it with the layer.+ const c = piece.center();+ const local = rotateByQuat(+ [+ c[0] - rest.position[0],+ c[1] - rest.position[1],+ c[2] - rest.position[2],+ ],+ undoRest,+ );+ const arm = rotateByQuat(local, layer.rotation);+ const p: Vec3 = [+ layer.position[0] + arm[0],+ layer.position[1] + arm[1],+ layer.position[2] + arm[2],+ ];+ // Rigid motion of the layer at this point: v + ω × r.+ const w0 = layer.spin;+ const carried: Vec3 = [+ layer.velocity[0] + w0[1] * arm[2] - w0[2] * arm[1],+ layer.velocity[1] + w0[2] * arm[0] - w0[0] * arm[2],+ layer.velocity[2] + w0[0] * arm[1] - w0[1] * arm[0],+ ];const d: Vec3 = [p[0] - impact[0], p[1] - impact[1], p[2] - impact[2]];const dist = Math.hypot(...d) || 1;const falloff = 1 / (1 + (dist / Math.max(1, radius)) ** 2);const v = d.map(- (x, i) => (x / dist) * speed * falloff + hitVel[i]! * transfer * falloff,+ (x, i) =>+ carried[i]! ++ (x / dist) * speed * falloff ++ hitVel[i]! * transfer * falloff,) as Vec3;const axis = [rand() - 0.5, rand() - 0.5, rand() - 0.5];const len = Math.hypot(...axis) || 1;- const w = axis.map((a) => (a / len) * spin * (0.5 + rand())) as Vec3;- piece.wake(frame, v, w);+ const w = axis.map(+ (a, i) => (a / len) * spin * (0.5 + rand()) + (w0[i]! * 180) / Math.PI,+ ) as Vec3;+ piece.wake(frame, v, w, { position: p, rotation: layer.rotation });}}diff --git a/packages/framefields/src/physics/world2d.ts b/packages/framefields/src/physics/world2d.tsindex 2ae1a6a9..18c13d71 100644--- a/packages/framefields/src/physics/world2d.ts+++ b/packages/framefields/src/physics/world2d.ts@@ -362,6 +362,10 @@ export class PhysicsWorld2D extends WorldCore<Vec2, number, PhysicsBody2D> {options,this.newRecording(),);+ // A kinematic body following drivers starts where they put it, not at+ // the layer's own pose (else its first step sweeps through the gap).+ const start = body.kinematicTarget(this.startFrame);+ if (start) simBody.setPose(start.position, start.rotation);return this.addBody(body);}diff --git a/packages/framefields/src/physics/world3d.ts b/packages/framefields/src/physics/world3d.tsindex 89594efb..c06f449b 100644--- a/packages/framefields/src/physics/world3d.ts+++ b/packages/framefields/src/physics/world3d.ts@@ -104,7 +104,8 @@ export function quatFromEuler(rx: number, ry: number, rz: number): Quat {return quatMul(quatMul(qz, qy), qx);}-function quatMul(a: Quat, b: Quat): Quat {+/** @internal */+export function quatMul(a: Quat, b: Quat): Quat {const [ax, ay, az, aw] = a;const [bx, by, bz, bw] = b;return [@@ -188,12 +189,27 @@ export class PhysicsBody3D implements CoreBody<Vec3, Quat> {/*** @internal Starts the body now, mid-simulation (`frame` relative to the* world's start): it moves from the next frame, at this velocity (px/s,- * degrees per second).+ * degrees per second), from `pose` (px) when given.*/- wake(frame: number, velocity: Vec3, angularVelocity: Vec3): void {+ wake(+ frame: number,+ velocity: Vec3,+ angularVelocity: Vec3,+ pose?: { position: Vec3; rotation: Quat },+ ): void {this.wokeAt = frame;const ppm = this.world.pixelsPerMeter;this.sim.setEnabled(true);+ if (pose) {+ this.sim.setPose(+ [+ pose.position[0] / ppm,+ pose.position[1] / ppm,+ pose.position[2] / ppm,+ ],+ pose.rotation,+ );+ }this.sim.setVelocity([velocity[0] / ppm, velocity[1] / ppm, velocity[2] / ppm],[@@ -349,7 +365,8 @@ export class PhysicsBody3D implements CoreBody<Vec3, Quat> {}}-function rotateByQuat(v: Vec3, q: Quat): Vec3 {+/** @internal */+export function rotateByQuat(v: Vec3, q: Quat): Vec3 {const r = quatMul(quatMul(q, [v[0], v[1], v[2], 0]), [-q[0],-q[1],@@ -479,6 +496,10 @@ export class PhysicsWorld3D extends WorldCore<Vec3, Quat, PhysicsBody3D> {options,this.newRecording(),);+ // A kinematic body following drivers starts where they put it, not at+ // the layer's own pose (else its first step sweeps through the gap).+ const start = body.kinematicTarget(this.startFrame);+ if (start) simBody.setPose(start.position, start.rotation);return this.addBody(body);}diff --git a/packages/webgpu-renderers/src/renderer3d/motion-blur-pipeline.ts b/packages/webgpu-renderers/src/renderer3d/motion-blur-pipeline.tsindex 4ef1190e..c590f5b5 100644--- a/packages/webgpu-renderers/src/renderer3d/motion-blur-pipeline.ts+++ b/packages/webgpu-renderers/src/renderer3d/motion-blur-pipeline.ts@@ -17,7 +17,14 @@ export interface MotionBlurPassOptions {softDepth?: number;}-const TILE_FORMAT: GPUTextureFormat = "rgba16float";+/** Format of the tile textures `render` takes. */+export const MOTION_BLUR_TILE_FORMAT: GPUTextureFormat = "rgba16float";+const TILE_FORMAT = MOTION_BLUR_TILE_FORMAT;++/** Side of a tile (the longest blur), px, for these options. */+export function motionBlurTileSize(options: MotionBlurPassOptions): number {+ return Math.max(4, Math.min(160, Math.round(options.maxBlur ?? 48)));+}export class MotionBlurPipeline {private readonly device: GPUDevice;@@ -27,8 +34,6 @@ export class MotionBlurPipeline {private readonly reconstruct = new Map<GPUTextureFormat, GPURenderPipeline>();/** One uniform block per blur this frame: an encoder may blur several scenes. */private readonly params: BufferPool;- private tiles: { a: GPUTexture; b: GPUTexture; w: number; h: number } | null =- null;constructor(device: GPUDevice) {this.device = device;@@ -58,31 +63,11 @@ export class MotionBlurPipeline {});}- private tileTextures(w: number, h: number): { a: GPUTexture; b: GPUTexture } {- if (this.tiles && this.tiles.w === w && this.tiles.h === h)- return this.tiles;- this.tiles?.a.destroy();- this.tiles?.b.destroy();- const make = (label: string) =>- this.device.createTexture({- label,- size: { width: w, height: h },- format: TILE_FORMAT,- usage:- GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,- });- this.tiles = {- a: make("motion-blur-tile-max"),- b: make("motion-blur-neighbor-max"),- w,- h,- };- return this.tiles;- }-/*** Blurs `color` (premultiplied) by `velocity` (`VELOCITY_FORMAT`, same- * size) into `target` (a view of `targetFormat`, same size).+ * size) into `target` (a view of `targetFormat`, same size). `tiles`+ * returns a render-attachment texture of the tile grid's size: the+ * caller owns them, since one frame may blur scenes of several sizes.*/render(encoder: GPUCommandEncoder,@@ -90,14 +75,16 @@ export class MotionBlurPipeline {velocity: GPUTexture,target: GPUTextureView,targetFormat: GPUTextureFormat,- options: MotionBlurPassOptions = {},+ options: MotionBlurPassOptions,+ tiles: (label: string, width: number, height: number) => GPUTexture,): void {- const k = Math.max(4, Math.min(160, Math.round(options.maxBlur ?? 48)));+ const k = motionBlurTileSize(options);const width = color.width;const height = color.height;const tw = Math.ceil(width / k);const th = Math.ceil(height / k);- const { a, b } = this.tileTextures(tw, th);+ const a = tiles("MotionBlurTileMax", tw, th);+ const b = tiles("MotionBlurNeighborMax", tw, th);const params = this.params.getBuffer(this.device,new Float32Array([@@ -168,7 +155,5 @@ export class MotionBlurPipeline {destroy(): void {this.params.destroy();- this.tiles?.a.destroy();- this.tiles?.b.destroy();}}diff --git a/packages/webgpu-renderers/src/renderer3d/renderer3d.ts b/packages/webgpu-renderers/src/renderer3d/renderer3d.tsindex 269e67d3..814c2aa6 100644--- a/packages/webgpu-renderers/src/renderer3d/renderer3d.ts+++ b/packages/webgpu-renderers/src/renderer3d/renderer3d.ts@@ -50,14 +50,20 @@ import { BufferPool } from "../renderer2d/buffer-pool.js";import { SamplerCache } from "../renderer2d/sampler-cache.js";import { UniformBindGroupCache } from "../renderer2d/uniform-bind-group-cache.js";import { dofBokehWgsl } from "../shaders/dof-bokeh.js";-import { quadVelocityWgsl } from "../shaders/mesh-velocity.js";+import {+ floorVelocityWgsl,+ quadVelocityWgsl,+} from "../shaders/mesh-velocity.js";import type { SlugGlyphBatch } from "../slug/slug-pipeline.js";import { AudioMeshDeformPipeline } from "./audio-mesh-deform-pipeline.js";import { type BloomOptions, BloomPipeline } from "./bloom-pipeline.js";import { FloorReflectionPipeline } from "./floor-reflection-pipeline.js";import { GeometryOutlinePipeline } from "./geometry-outline-pipeline.js";import { GeometryResolvePipeline } from "./geometry-resolve-pipeline.js";-import { getOrCreateHdrEnvironment } from "./hdr-environment.js";+import {+ getOrCreateHdrEnvironment,+ type HdrEnvironment,+} from "./hdr-environment.js";import { decodeKtx2, isKtx2 } from "./ktx2.js";import {type GPUMeshBuffers,@@ -71,6 +77,7 @@ import {} from "./mesh3d-pipeline.js";import { MorphPipeline } from "./morph-pipeline.js";import {+ MOTION_BLUR_TILE_FORMAT,type MotionBlurPassOptions,MotionBlurPipeline,} from "./motion-blur-pipeline.js";@@ -332,7 +339,7 @@ export class Renderer3D {private passWritesHdr = false;private cameraUniformData = new Float32Array(80); // 320 bytes = 80 floatsprivate velocityCameraPool = new BufferPool(- 192,+ 256,GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,);private quadMotionPool = new BufferPool(@@ -344,6 +351,17 @@ export class Renderer3D {pipeline: GPURenderPipeline;layout: GPUBindGroupLayout;};+ private floorVelocity?: {+ pipeline: GPURenderPipeline;+ layout: GPUBindGroupLayout;+ };+ /**+ * Environments looked up this frame: a pass asks several times, and a+ * file path is checked on disk (stat) once per frame, not per lookup.+ */+ private hdrEnvironments = new Map<string, HdrEnvironment>();+ /** The HDR target blurred by `applyMotionBlur`: what bloom reads after it. */+ private hdrBlurred: GPUTexture | null = null;private meshBuffersCache = new WeakMap<Mesh3DData, GPUMeshBuffers>();private materialTextures = new WeakMap<Material3D,@@ -525,7 +543,22 @@ export class Renderer3D {return texture;}+ private hdrEnvironment(+ source: NonNullable<Environment3DOptions["hdri"]>,+ ): HdrEnvironment {+ if (typeof source !== "string") {+ return getOrCreateHdrEnvironment(this.device, source);+ }+ let env = this.hdrEnvironments.get(source);+ if (!env) {+ env = getOrCreateHdrEnvironment(this.device, source);+ this.hdrEnvironments.set(source, env);+ }+ return env;+ }+resetPools(): void {+ this.hdrEnvironments.clear();for (const [key, texture] of this.attachments) {if (this.attachmentsUsed.has(key)) continue;texture.destroy();@@ -588,7 +621,7 @@ export class Renderer3D {/** The HDR radiance target the last `beginPass(…, writeHdr)` drew into. */hdrSource(): GPUTexture | null {- return this.hdrTexture;+ return this.hdrBlurred ?? this.hdrTexture;}private getOrCreateHdrTexture(width: number, height: number): GPUTexture {@@ -773,7 +806,7 @@ export class Renderer3D {environment?: Environment3DOptions | null,): HdriUniforms | undefined {if (!environment?.hdri) return undefined;- const env = getOrCreateHdrEnvironment(this.device, environment.hdri);+ const env = this.hdrEnvironment(environment.hdri);return { maxMip: env.mipLevelCount - 1, sh: env.sh };}@@ -846,7 +879,7 @@ export class Renderer3D {usage: GPUTextureUsage.TEXTURE_BINDING,});const envTex = environment?.hdri- ? getOrCreateHdrEnvironment(this.device, environment.hdri).cube+ ? this.hdrEnvironment(environment.hdri).cube: this.placeholderEnvTexture;const map =withShadow && this.shadowTexture@@ -1369,6 +1402,7 @@ export class Renderer3D {}this.passWritesHdr = writeHdr;+ this.hdrBlurred = null;if (writeHdr) {this.hdrTexture = this.getOrCreateHdrTexture(surfaceWidth, surfaceHeight);if (msaa) {@@ -2172,13 +2206,15 @@ export class Renderer3D {format: VELOCITY_DEPTH_FORMAT,usage: GPUTextureUsage.RENDER_ATTACHMENT,});- const data = new Float32Array(48);- data.set(Camera3D.computeViewProjectionMatrix(camera), 0);+ const data = new Float32Array(64);+ const viewProj = Camera3D.computeViewProjectionMatrix(camera);+ data.set(viewProj, 0);data.set(Camera3D.computeViewProjectionMatrix(prevCamera), 16);+ data.set(Matrix4Math.invert(viewProj) ?? Matrix4Math.identity(), 32);const fwd = Vector3Math.normalize(Vector3Math.subtract(camera.target, camera.eye),);- data.set([...camera.eye, 1, ...fwd, 0, width, height, 0, 0], 32);+ data.set([...camera.eye, 1, ...fwd, 0, width, height, 0, 0], 48);const cameraBindGroup = this.device.createBindGroup({layout: this.mesh3dPipeline.velocityCameraLayout,entries: [@@ -2290,6 +2326,77 @@ export class Renderer3D {pass.draw(4);}+ /** Draws the environment floor's motion (camera motion only) into the velocity pass. */+ drawFloorVelocity(+ pass: GPURenderPassEncoder,+ cameraBindGroup: GPUBindGroup,+ floor: Environment3DFloor,+ ): void {+ this.floorVelocity ??= this.fullscreenVelocityPipeline(+ "Renderer3DFloorVelocity",+ floorVelocityWgsl,+ "vs_floor_velocity",+ "fs_floor_velocity",+ );+ const { pipeline, layout } = this.floorVelocity;+ const group = this.device.createBindGroup({+ layout,+ entries: [+ {+ binding: 0,+ resource: {+ buffer: this.quadMotionPool.getBuffer(+ this.device,+ new Float32Array([floor.y, 0, 0, 0]),+ ),+ },+ },+ ],+ });+ pass.setPipeline(pipeline);+ pass.setBindGroup(0, cameraBindGroup);+ pass.setBindGroup(1, group);+ pass.draw(3);+ }++ private fullscreenVelocityPipeline(+ label: string,+ code: string,+ vertex: string,+ fragment: string,+ ): { pipeline: GPURenderPipeline; layout: GPUBindGroupLayout } {+ const module = this.device.createShaderModule({ label, code });+ const layout = this.device.createBindGroupLayout({+ label: `${label}Layout`,+ entries: [+ {+ binding: 0,+ visibility: GPUShaderStage.FRAGMENT,+ buffer: { type: "uniform" },+ },+ ],+ });+ const pipeline = this.device.createRenderPipeline({+ label,+ layout: this.device.createPipelineLayout({+ bindGroupLayouts: [this.mesh3dPipeline.velocityCameraLayout, layout],+ }),+ vertex: { module, entryPoint: vertex },+ fragment: {+ module,+ entryPoint: fragment,+ targets: [{ format: VELOCITY_FORMAT }],+ },+ depthStencil: {+ format: VELOCITY_DEPTH_FORMAT,+ depthWriteEnabled: true,+ depthCompare: "less-equal",+ },+ primitive: { topology: "triangle-list" },+ });+ return { pipeline, layout };+ }+private quadVelocityPipeline(): {pipeline: GPURenderPipeline;layout: GPUBindGroupLayout;@@ -2352,15 +2459,37 @@ export class Renderer3D {target: GPUTextureView,options: MotionBlurPassOptions = {},): void {- this.motionBlurPipeline ??= new MotionBlurPipeline(this.device);- this.motionBlurPipeline.render(- encoder,- color,- velocity,- target,- this.format,- options,- );+ const blur = (this.motionBlurPipeline ??= new MotionBlurPipeline(+ this.device,+ ));+ const usage =+ GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING;+ const tiles = (label: string, width: number, height: number) =>+ this.attachment(label, width, height, {+ format: MOTION_BLUR_TILE_FORMAT,+ usage,+ });+ blur.render(encoder, color, velocity, target, this.format, options, tiles);+ // Bloom reads the pass's HDR radiance: it streaks with the picture.+ const hdr = this.passWritesHdr ? this.hdrTexture : null;+ if (hdr && hdr.width === color.width && hdr.height === color.height) {+ const blurred = this.attachment(+ "Renderer3DHdrBlurred",+ hdr.width,+ hdr.height,+ { format: hdr.format, usage },+ );+ blur.render(+ encoder,+ hdr,+ velocity,+ blurred.createView(),+ hdr.format,+ options,+ tiles,+ );+ this.hdrBlurred = blurred;+ }}loadModel(diff --git a/packages/webgpu-renderers/src/shaders/mesh-velocity.ts b/packages/webgpu-renderers/src/shaders/mesh-velocity.tsindex d46f5148..eaaf4bfd 100644--- a/packages/webgpu-renderers/src/shaders/mesh-velocity.ts+++ b/packages/webgpu-renderers/src/shaders/mesh-velocity.ts@@ -12,16 +12,22 @@ import {meshStructsWgsl,} from "./mesh3d.js";-export const meshVelocityWgsl = `-${meshStructsWgsl}-+/** The velocity pass's camera: this and the previous frame's view-projection. */+const velocityCameraWgsl = `struct VelocityCamera {viewProj : mat4x4<f32>,prevViewProj : mat4x4<f32>,+ invViewProj : mat4x4<f32>,eye : vec4<f32>,dir : vec4<f32>,viewport : vec4<f32>, // xy = target size, px};+`;++export const meshVelocityWgsl = `+${meshStructsWgsl}++${velocityCameraWgsl}@group(0) @binding(0) var<uniform> vcam : VelocityCamera;@group(1) @binding(0) var<uniform> model : ModelUniforms;@@ -91,13 +97,7 @@ fn fs_velocity(in: VelocityOut) -> @location(0) vec4<f32> {* the background's motion.*/export const quadVelocityWgsl = `-struct VelocityCamera {- viewProj : mat4x4<f32>,- prevViewProj : mat4x4<f32>,- eye : vec4<f32>,- dir : vec4<f32>,- viewport : vec4<f32>,-};+${velocityCameraWgsl}struct QuadMotion {model : mat4x4<f32>,@@ -142,3 +142,56 @@ fn fs_quad_velocity(in: QuadVelocityOut) -> @location(0) vec4<f32> {return vec4<f32>(motion, in.depth, 1.0);}`;++/**+ * Velocity of the environment's floor plane (y = floorY, infinite, drawn by+ * ray intersection like the color pass): still in the world, it moves only+ * with the camera.+ */+export const floorVelocityWgsl = `+${velocityCameraWgsl}++struct FloorMotion {+ params : vec4<f32>, // x = floor y+};++@group(0) @binding(0) var<uniform> vcam : VelocityCamera;+@group(1) @binding(0) var<uniform> floorM : FloorMotion;++@vertex+fn vs_floor_velocity(@builtin(vertex_index) i: u32) -> @builtin(position) vec4<f32> {+ let p = array<vec2<f32>, 3>(vec2(-1.0, -1.0), vec2(3.0, -1.0), vec2(-1.0, 3.0));+ return vec4<f32>(p[i], 0.0, 1.0);+}++struct FloorVelocityOut {+ @location(0) color : vec4<f32>,+ @builtin(frag_depth) depth : f32,+};++@fragment+fn fs_floor_velocity(@builtin(position) pos: vec4<f32>) -> FloorVelocityOut {+ let size = vcam.viewport.xy;+ let ndc = vec2<f32>(pos.x / size.x * 2.0 - 1.0, 1.0 - pos.y / size.y * 2.0);+ let a = vcam.invViewProj * vec4<f32>(ndc, 0.0, 1.0);+ let b = vcam.invViewProj * vec4<f32>(ndc, 1.0, 1.0);+ let p0 = a.xyz / a.w;+ let ray = b.xyz / b.w - p0;+ if (abs(ray.y) < 1e-9) {+ discard;+ }+ let t = (floorM.params.x - p0.y) / ray.y;+ if (t < 0.0) {+ discard;+ }+ let world = vec4<f32>(p0 + ray * t, 1.0);+ let clip = vcam.viewProj * world;+ let clipPrev = vcam.prevViewProj * world;+ let motion = (clip.xy / clip.w - clipPrev.xy / max(clipPrev.w, 1e-6)) *+ 0.5 * size * vec2<f32>(1.0, -1.0);+ var out: FloorVelocityOut;+ out.color = vec4<f32>(motion, dot(world.xyz - vcam.eye.xyz, vcam.dir.xyz), 1.0);+ out.depth = clamp(clip.z / clip.w, 0.0, 1.0);+ return out;+}+`;diff --git a/plugins/framefields/skills/framefields-compose/SKILL.md b/plugins/framefields/skills/framefields-compose/SKILL.mdindex bda8f806..a983e83b 100644--- a/plugins/framefields/skills/framefields-compose/SKILL.md+++ b/plugins/framefields/skills/framefields-compose/SKILL.md@@ -585,7 +585,7 @@ stage.animate(LayerAnimation.create().signal("y", world.impact, { multiplier: 14- **Particles:** for clouds, dust, sparks, fluids and flow fields use `Layer.particles` (GPU, below), not hundreds of physics bodies. Keep physics bodies for a few dozen things that must collide and stack (cards, letters, products).- **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` solids (`roundedBox`, `sphere`, `cylinder`, `capsule`, `torus`, `ring`, `prism`, `pyramid`, `polyhedron`, `icosahedron`, `icosphere`, `shard`) and models (convex hull of the mesh); same options with 3-vectors, `world.hinge(a, b, at, axis)`, `world.walls({ width, height, depth })`. Use `Layer3D.instances({ count: bodies.length, mesh: Layer3D.shard({ radius: 24 }), bodies, emissiveBySpeed: { speedThreshold: 200, maxSpeed: 1200, color: "#ff5511", intensity: 4 } })` to render hundreds of physics bodies in a single GPU draw call.-- **Destruction:** `const broken = world.fracture(statue, { cells: 48, impactPoint: [x, y, z], fractureFrame: "onImpact" | frame, explosionSpeed: 300, interiorColor: "#e9dcc0" })` cuts a `Layer3D` solid, extruded text or model (with `modelData`) into Voronoi pieces. It looks whole (a fixed collider of its own shape) until the frame or the first body that hits it, which carries on through, then the pieces fall as rigid bodies (`broken.pieces`, `broken.frame` after simulating). The node changes in place: add it as usual. One draw call per material; pieces crowd around `impactPoint`. Needs `simulate()` (not `live()`).+- **Destruction:** `const broken = world.fracture(statue, { cells: 48, impactPoint: [x, y, z], fractureFrame: "onImpact" | frame, explosionSpeed: 300, interiorColor: "#e9dcc0" })` cuts a `Layer3D` solid, extruded text or model (with `modelData`) into Voronoi pieces. It looks whole (a fixed collider of its own shape) until the frame or the first body that hits it, which carries on through, then the pieces fall as rigid bodies (`broken.pieces`, `broken.frame` after simulating). The node changes in place: add it as usual. One draw call per material; pieces crowd around `impactPoint`. An animated layer (position, rotation) collides along its path while whole and breaks where it is, its pieces carrying its motion; inside a 3D group the pieces fly in the group's space, like other bodies. Its scale must not animate (rigid pieces). Needs `simulate()` (not `live()`).- **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).diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 58702133..464569bf 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -569,6 +569,50 @@ importers:specifier: 2.0.2version: 2.0.2+ examples/34_spatial_styling:+ 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+ vitest:+ specifier: ^4.1.11+ version: 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]))++ examples/35_robot_uprising:+ 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+ vitest:+ specifier: ^4.1.11+ version: 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]))+nodes/node-apply-lut:dependencies:'@framefields/core':@@ -2795,6 +2839,9 @@ importers:'@mediabunny/mp3-encoder':specifier: ^1.61.6version: 1.61.6([email protected])+ gsap:+ specifier: ^3.15.0+ version: 3.15.0mediabunny:specifier: ^1.61.6version: 1.61.6@@ -8496,7 +8543,7 @@ snapshots:obug: 2.2.1std-env: 4.2.0tinyrainbow: 3.1.0- vitest: 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]))+ vitest: 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]))'@vitest/[email protected]':dependencies:diff --git a/specs/ue58-engine-roadmap.md b/specs/ue58-engine-roadmap.mdindex 51f61497..f3f30500 100644--- a/specs/ue58-engine-roadmap.md+++ b/specs/ue58-engine-roadmap.md@@ -382,7 +382,7 @@ Currently, `MotionBlurPipeline` (`packages/webgpu-renderers/src/renderer3d/motio- Upgrade the MRT velocity pass to accept `prevModelMatrix`, `prevSkinningMatrices`, and `prevInstanceBuffer` (`Swarm3DPipeline` / `Layer3D.instances`).- Fast-moving robot limbs, tumbling shards, and fractured debris get authentic directional per-object and per-bone shutter motion blur.-**Status (implemented):** fracture geometry `webgpu-renderers/src/renderer3d/fracture-geometry.ts` (pure, unit-tested for closed pieces and exact volume), SDK `framefields/src/physics/fracture3d.ts` (`world.fracture(node, options)` on `PhysicsWorld3D`), compositor `renderers/fracture.ts`; velocity pass `shaders/mesh-velocity.ts` + `Mesh3DPipeline.drawVelocity` / `Renderer3D.beginVelocityPass`, reconstruction `shaders/motion-blur.ts` + `MotionBlurPipeline`, history `node-compositor/src/renderers/motion-history.ts`. Deviations: (1) Voronoi cells are exact (bisectors nearest first until none can reach the cell), not K-nearest. The surface is clipped by each cell's planes, and each cell face is the solid's whole cross-section on its bisector (loops chained by exact position through a point welder, holes nested, triangulated, collinear points restored) clipped to the cell's other planes, so pieces of a watertight source are closed (verified by origin-independent volume) and sum to its volume. (2) The fractured layer is one rigidly skinned mesh (one joint per piece, one draw per material, cut faces in their own `interiorColor` material), not `Layer3D.instances`: pieces differ in shape, and skinning gives motion blur per-piece velocity for free. The pieces' recorded poses (`fracture3d.track`, x y z + quaternion per piece per frame) are JSON; the renderer rebuilds and re-fractures the source deterministically when `modelData` is lost. While every piece is at its frame-0 pose the layer draws in the exact rest pose without its cut faces, so it is sealed (cut faces would otherwise tie the surface's depth along seams). (3) While whole, a fixed collider of the layer's own shape stands in; `fractureFrame: "onImpact"` (default) breaks it on the first dynamic contact, which keeps going (the stand-in's bounce is undone, minus `momentumTransfer`). `Physics.fracture` is `world.fracture` (it needs a world); live worlds are refused. (4) Motion blur is `Layer.camera({ motionBlur })` (shutter angle, samples, max blur). The velocity pass is a second draw of the scene (meshes run the shared `meshDeformWgsl` for this and the previous frame's bindings, so model matrices, skinning, instances, swarms, wind and crowds all move; 3D layer planes use their model matrices), not a color-pass MRT, which keeps every color pipeline variant unchanged. Previous-frame state comes from a per-composition history (instance records copied on the GPU, two parity slots); after a seek the compositor renders the frame before first, recording only, so every frame comes out identical in any order. (5) Reconstruction is McGuire et al.'s tile max / neighbor max gather, with per-sample coverage selection (front sample whose blur reaches, or level/behind sample this pixel's blur reaches) normalized over the samples, which makes uniform motion an exact ramp of the streak length. Morph targets, audio deformation and Slug text planes contribute no velocity of their own yet.+**Status (implemented):** fracture geometry `webgpu-renderers/src/renderer3d/fracture-geometry.ts` (pure, unit-tested for closed pieces and exact volume), SDK `framefields/src/physics/fracture3d.ts` (`world.fracture(node, options)` on `PhysicsWorld3D`), compositor `renderers/fracture.ts`; velocity pass `shaders/mesh-velocity.ts` + `Mesh3DPipeline.drawVelocity` / `Renderer3D.beginVelocityPass`, reconstruction `shaders/motion-blur.ts` + `MotionBlurPipeline`, history `node-compositor/src/renderers/motion-history.ts`. Deviations: (1) Voronoi cells are exact (bisectors nearest first until none can reach the cell), not K-nearest. The surface is clipped by each cell's planes, and each cell face is the solid's whole cross-section on its bisector (loops chained by exact position through a point welder, holes nested, triangulated, collinear points restored) clipped to the cell's other planes, so pieces of a watertight source are closed (verified by origin-independent volume) and sum to its volume. (2) The fractured layer is one rigidly skinned mesh (one joint per piece, one draw per material, cut faces in their own `interiorColor` material), not `Layer3D.instances`: pieces differ in shape, and skinning gives motion blur per-piece velocity for free. The pieces' recorded poses (`fracture3d.track`, x y z + quaternion per piece per frame) are JSON; the renderer rebuilds and re-fractures the source deterministically when `modelData` is lost. While every piece is at its frame-0 pose the layer draws in the exact rest pose without its cut faces, so it is sealed (cut faces would otherwise tie the surface's depth along seams). (3) While whole, a fixed collider of the layer's own shape stands in; `fractureFrame: "onImpact"` (default) breaks it on the first dynamic contact, which keeps going (the stand-in's bounce is undone, minus `momentumTransfer`). `Physics.fracture` is `world.fracture` (it needs a world); live worlds are refused. An animated layer's stand-in is kinematic, following its x/y/z/rotation sampled with the compositor's own eases (`sampleLayerProp` in `compositions/src/program/track-sampler.ts`, shared with the compiler's draw-time tracks); at the break each piece is placed from the stand-in's pose and inherits its rigid motion (v + ω × r). The track lives in the layer's parent space, so pieces inside a 3D group fly in the group's space like any body; animated scale is refused (rigid pieces). Kinematic bodies with `follow` now start at their drivers' pose in both worlds. (4) Motion blur is `Layer.camera({ motionBlur })` (shutter angle, samples, max blur). The velocity pass is a second draw of the scene (meshes run the shared `meshDeformWgsl` for this and the previous frame's bindings, so model matrices, skinning, instances, swarms, wind and crowds all move; 3D layer planes use their model matrices), not a color-pass MRT, which keeps every color pipeline variant unchanged. Previous-frame state comes from a per-composition history (instance records copied on the GPU, two parity slots); after a seek the compositor renders the frame before first, recording only, so every frame comes out identical in any order. (5) Reconstruction is McGuire et al.'s tile max / neighbor max gather, with per-sample coverage selection (front sample whose blur reaches, or level/behind sample this pixel's blur reaches) normalized over the samples, which makes uniform motion an exact ramp of the streak length. Morph targets, audio deformation and Slug text planes contribute no velocity of their own yet.---