Code-first video & image, rendered natively on WebGPU.
feat(3d): Voronoi fracture and per-object shutter motion blur
okanaslff92cd04506b
diff --git a/.changeset/ue58-worlds-characters-destruction.md b/.changeset/ue58-worlds-characters-destruction.mdnew file mode 100644index 00000000..2f893754--- /dev/null+++ b/.changeset/ue58-worlds-characters-destruction.md@@ -0,0 +1,5 @@+---+"framefields": minor+---++3D worlds, characters and destruction. `Layer3D.terrain`, `Layer3D.sdf` and `Layer3D.scatter` (with wind) build procedural landscapes, smooth-CSG sculptures and scattered foliage, and any layer (video, image, layout) can texture a 3D mesh. glTF models blend clip layers and take two-bone IK, look-at and spring bones, and `Layer3D.instances` plays skinned crowds in one draw call. `world.fracture(node, options)` shatters a solid, extruded text or model into Voronoi pieces that break on impact or at a frame. `Layer.camera({ motionBlur })` adds per-object shutter motion blur from a velocity buffer, covering skinned joints, instances, swarms and fractured pieces, and renders the same frame in order or after a seek.diff --git a/nodes/node-compositor/SKILL.md b/nodes/node-compositor/SKILL.mdindex 65c0d521..5ac6a94c 100644--- a/nodes/node-compositor/SKILL.md+++ b/nodes/node-compositor/SKILL.md@@ -230,6 +230,8 @@ 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).+- **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 })`.- **GPU 3D Swarms (`swarm3d`):** `kind: "model3d"` with `swarm3d` runs continuous 3D particle simulation in a WebGPU compute shader with 3D curl noise, 3D vortex fields (`swirl`, `pull`, `axial`), ground plane collisions with Coulomb sliding friction and rotational roll torque, and kinetic heat accumulation/cooling, packing directly into GPU instance buffers.diff --git a/nodes/node-compositor/src/renderers/fracture.ts b/nodes/node-compositor/src/renderers/fracture.tsnew file mode 100644index 00000000..fe286557--- /dev/null+++ b/nodes/node-compositor/src/renderers/fracture.ts@@ -0,0 +1,100 @@+/**+ * Voronoi destruction in the compositor: a model node with `fracture3d`+ * draws its fractured twin (one joint per piece) posed from the physics+ * track; without a track the pieces rest in place and it looks whole.+ */+import type { Fracture3DSpec } from "@framefields/compositions/program";+import {+ fractureModel,+ type Mat4,+ Matrix4Math,+ type Model3DData,+ trsMatrix,+ type Vec3,+} from "@framefields/webgpu-renderers";++/**+ * Whether the pieces are all still where they started at `frame` (or there+ * is no track): the layer looks whole, and its cut faces, hidden inside,+ * need not draw (where pieces meet, a cut face can tie the surface's depth).+ */+export function fractureWhole(+ model: Model3DData,+ spec: Fracture3DSpec,+ frame: number,+): boolean {+ const track = spec.track;+ const stride = (model.nodes?.length ?? 0) * 7;+ if (!track?.length || !stride) return true;+ const frames = Math.floor(track.length / stride);+ const at = Math.min(Math.max(Math.ceil(frame), 0), frames - 1) * stride;+ for (let i = 0; i < stride; i++) if (track[at + i] !== track[i]) return false;+ return true;+}++/** The fractured model for a node's source model (cached per model and spec). */+export function fracturedModel(+ model: Model3DData,+ spec: Fracture3DSpec,+): Model3DData {+ return fractureModel(model, spec).model;+}++type Quat = [number, number, number, number];++function poseAt(track: number[], at: number): { p: Vec3; q: Quat } {+ return {+ p: [track[at]!, track[at + 1]!, track[at + 2]!],+ q: [track[at + 3]!, track[at + 4]!, track[at + 5]!, track[at + 6]!],+ };+}++function blend(+ a: { p: Vec3; q: Quat },+ b: { p: Vec3; q: Quat },+ t: number,+): { p: Vec3; q: Quat } {+ if (t <= 0) return a;+ const sign = a.q.reduce((s, v, i) => s + v * b.q[i]!, 0) < 0 ? -1 : 1;+ const q = a.q.map((v, i) => v + (b.q[i]! * sign - v) * t) as Quat;+ const len = Math.hypot(...q) || 1;+ return {+ p: a.p.map((v, i) => v + (b.p[i]! - v) * t) as Vec3,+ q: q.map((v) => v / len) as Quat,+ };+}++/**+ * 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).+ */+export function fracturePose(+ model: Model3DData,+ spec: Fracture3DSpec,+ frame: number,+ sceneRoot: Mat4,+ scale: Vec3,+): Mat4[] | undefined {+ const track = spec.track;+ const pieces = model.nodes?.length ?? 0;+ const stride = pieces * 7;+ if (!track?.length || !stride || track.length % stride !== 0)+ return undefined;+ const frames = track.length / stride;+ 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 out: Mat4[] = [];+ for (let i = 0; i < pieces; i++) {+ const { p, q } = blend(+ poseAt(track, f0 * stride + i * 7),+ poseAt(track, f1 * stride + i * 7),+ f - f0,+ );+ out.push(Matrix4Math.multiply(toModel, trsMatrix(p, q, scale)));+ }+ return out;+}diff --git a/nodes/node-compositor/src/renderers/motion-history.ts b/nodes/node-compositor/src/renderers/motion-history.tsnew file mode 100644index 00000000..893bc32c--- /dev/null+++ b/nodes/node-compositor/src/renderers/motion-history.ts@@ -0,0 +1,184 @@+/**+ * What each 3D draw looked like one frame earlier, for shutter motion blur.+ * A scene records every mesh and plane (by a key stable across frames) and+ * its camera as it renders frame f; frame f + 1 reads them back. Instance+ * records are copied on the GPU (swarms simulate there), into a pair of+ * buffers by frame parity so rendering a frame again still finds f - 1.+ * A frame whose predecessor is not recorded (a seek) renders f - 1 first+ * (`needsPrevious`), so every frame comes out the same in any order.+ */+import type {+ Camera3DPose,+ Mat4,+ MeshMotionPrev,+ MeshWind,+} from "@framefields/webgpu-renderers";++export interface MeshMotionState {+ kind: "mesh";+ modelMatrix: Mat4;+ skinning?: Float32Array;+ /** Byte size of the instance records copied for this frame. */+ instanceBytes?: number;+ windTime?: number;+ crowdTime?: number;+}++export interface QuadMotionState {+ kind: "quad";+ modelMatrix: Mat4;+}++type MotionState = MeshMotionState | QuadMotionState;++/** Two frames of one value: the latest and the one before it. */+class Slots<T> {+ frame = Number.NaN;+ value?: T;+ prevFrame = Number.NaN;+ prevValue?: T;++ write(frame: number, value: T): void {+ if (frame !== this.frame) {+ this.prevFrame = this.frame;+ this.prevValue = this.value;+ }+ this.frame = frame;+ this.value = value;+ }++ /** The value at `frame`, if it is one of the two held. */+ at(frame: number): T | undefined {+ if (frame === this.frame) return this.value;+ if (frame === this.prevFrame) return this.prevValue;+ return undefined;+ }+}++export class MotionHistory {+ private readonly states = new Map<string, Slots<MotionState>>();+ private readonly instances = new Map<string, [GPUBuffer?, GPUBuffer?]>();+ private readonly camera = new Slots<Camera3DPose>();+ /** Frames recorded, latest last (two kept). */+ private readonly frames = new Slots<true>();++ constructor(private readonly device: GPUDevice) {}++ /** Whether rendering `frame` must render `frame - 1` first to know its motion. */+ needsPrevious(frame: number): boolean {+ return frame > 0 && this.frames.at(frame - 1) === undefined;+ }++ previousCamera(frame: number): Camera3DPose | undefined {+ return this.camera.at(frame - 1);+ }++ /** A mesh's state at `frame - 1`, shaped for the velocity pass. */+ previousMesh(+ key: string,+ frame: number,+ now: {+ skinning?: Float32Array;+ instanceBuffer?: GPUBuffer;+ wind?: MeshWind;+ crowd?: MeshMotionPrev["crowd"];+ },+ ): MeshMotionPrev | undefined {+ const prev = this.states.get(key)?.at(frame - 1);+ if (prev?.kind !== "mesh") return undefined;+ const out: MeshMotionPrev = { modelMatrix: prev.modelMatrix };+ // A mesh that changed shape (other joints, other instance count) has+ // no comparable past: it moves by its matrix alone.+ if (now.skinning && prev.skinning?.length === now.skinning.length) {+ out.skinningMatrices = prev.skinning;+ }+ const copy = this.instances.get(key)?.[(frame - 1) & 1];+ if (+ now.instanceBuffer &&+ copy &&+ prev.instanceBytes === now.instanceBuffer.size+ ) {+ out.instanceBuffer = copy;+ }+ if (now.wind && prev.windTime !== undefined) {+ out.wind = { ...now.wind, time: prev.windTime };+ }+ if (now.crowd && prev.crowdTime !== undefined) {+ out.crowd = { ...now.crowd, time: prev.crowdTime };+ }+ return out;+ }++ previousQuad(key: string, frame: number): Mat4 | undefined {+ const prev = this.states.get(key)?.at(frame - 1);+ return prev?.kind === "quad" ? prev.modelMatrix : undefined;+ }++ /** Records a mesh at `frame`; its instance records are copied in `encoder`. */+ recordMesh(+ encoder: GPUCommandEncoder,+ key: string,+ frame: number,+ state: Omit<MeshMotionState, "kind" | "instanceBytes">,+ instanceBuffer: GPUBuffer | undefined,+ ): void {+ let instanceBytes: number | undefined;+ if (instanceBuffer) {+ instanceBytes = instanceBuffer.size;+ const pair = this.instances.get(key) ?? [];+ const slot = frame & 1;+ let copy = pair[slot];+ if (!copy || copy.size !== instanceBytes) {+ copy?.destroy();+ copy = this.device.createBuffer({+ label: `MotionHistoryInstances:${key}`,+ size: instanceBytes,+ usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,+ });+ pair[slot] = copy;+ this.instances.set(key, pair);+ }+ encoder.copyBufferToBuffer(instanceBuffer, 0, copy, 0, instanceBytes);+ }+ this.slots(key).write(frame, {+ kind: "mesh",+ ...state,+ ...(state.skinning && { skinning: state.skinning.slice() }),+ instanceBytes,+ });+ }++ recordQuad(key: string, frame: number, modelMatrix: Mat4): void {+ this.slots(key).write(frame, { kind: "quad", modelMatrix });+ }++ recordFrame(frame: number, camera: Camera3DPose): void {+ this.camera.write(frame, camera);+ this.frames.write(frame, true);+ }++ private slots(key: string): Slots<MotionState> {+ let s = this.states.get(key);+ if (!s) {+ s = new Slots();+ this.states.set(key, s);+ }+ return s;+ }+}++const histories = new Map<string, MotionHistory>();++/** The motion history of one composition render (by render id). */+export function motionHistory(+ device: GPUDevice,+ renderId: string,+): MotionHistory {+ let h = histories.get(renderId);+ if (!h) {+ if (histories.size > 64) histories.clear();+ h = new MotionHistory(device);+ histories.set(renderId, h);+ }+ return h;+}diff --git a/nodes/node-compositor/src/renderers/webgpu-renderer.ts b/nodes/node-compositor/src/renderers/webgpu-renderer.tsindex 8fac3a33..149842ab 100644--- a/nodes/node-compositor/src/renderers/webgpu-renderer.ts+++ b/nodes/node-compositor/src/renderers/webgpu-renderer.ts@@ -3,6 +3,8 @@import { resolveMediaSourceUrl } from "@framefields/client-utils";import { decodeAudioSource } from "@framefields/compositions";import {+ type CameraMotionBlur,+ type CameraNode,type CompositionNodeBase,type CrowdConfig,collectNodeOps,@@ -48,6 +50,7 @@ import {type DrawQuad3DOpts,type Environment3DOptions,type ExtrudedTextGeometryOptions,+ FRACTURE_INTERIOR_MATERIAL,fitSpansToText,type GPUMeshBuffers,generateExtrudedTextGeometry,@@ -92,7 +95,9 @@ import {poseCharacter,} from "./character.js";import { shouldPaintContainerBackground } from "./container-bg.js";+import { fracturedModel, fracturePose, fractureWhole } from "./fracture.js";import { compatibleMeshDraws } from "./mesh-instancing.js";+import { type MotionHistory, motionHistory } from "./motion-history.js";import {composeQuat,meshWind,@@ -1082,6 +1087,17 @@ 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(@@ -1313,6 +1329,9 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {/** Where a relief keeps its look from: the default camera at the scene's field of view. */let reliefEye: [number, number, number] = [0, 0, 0];let dofEnabled = false;+ /** Shutter motion blur of the 3D scene, and what its draws looked like a frame ago. */+ let motionBlur: CameraMotionBlur | null = null;+ let history: MotionHistory | null = null;const sceneLights: Light3DOptions[] = [];let sceneEnvironment: Environment3DOptions | null = null;let sceneBloom: BloomOptions | null = null;@@ -1417,6 +1436,12 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {camStub?.maxBlurRadius ?? camOp?.dof?.maxBlurRadius ?? 24;}+ const blur = (camOp as CameraNode | undefined)?.motionBlur;+ if (blur && fps) {+ motionBlur = blur === true ? {} : blur;+ history = motionHistory(ctx.device, props.renderId);+ }+// Collect Active Lightsfor (const lvm of lightVMs) {const lop = lvm.operation as any;@@ -1548,7 +1573,8 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {}}- type Pending3DItem =+ /** `owner`: the node id, so motion blur finds the item a frame earlier. */+ type Pending3DItem = (| { kind: "quad"; texture: GPUTexture; opts: DrawQuad3DOpts }| {// A text layer's glyphs, drawn natively on its plane.@@ -1565,7 +1591,8 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {texture?: GPUTexture;opts: DrawMesh3DOpts;meshBuffers?: GPUMeshBuffers;- };+ }+ ) & { owner?: string };const pending3DItems: Pending3DItem[] = [];/** Textures the queued 3D items still read: their layers, mattes and reliefs. */const pendingTextures = (): GPUTexture[] =>@@ -1599,6 +1626,100 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {};};+ /** Each queued item with its motion key: owner id and its index among the owner's items. */+ const motionItems = (): Array<[Pending3DItem, string | undefined]> => {+ const seen = new Map<string, number>();+ return pending3DItems.map((item) => {+ if (item.owner === undefined) return [item, undefined];+ const n = seen.get(item.owner) ?? 0;+ seen.set(item.owner, n + 1);+ return [item, `${item.owner}#${n}`];+ });+ };+ /** Writes this frame's draws (and camera) into the motion history. */+ const recordMotion = (h: MotionHistory, cam: Camera3DPose) => {+ const r3d = getRenderer3D(+ ctx.device,+ ctx.renderer.format ?? "rgba8unorm",+ sampleCount3d,+ );+ for (const [item, key] of motionItems()) {+ if (!key) continue;+ if (item.kind === "mesh") {+ h.recordMesh(+ encoder,+ key,+ shiftedFrame,+ {+ modelMatrix: r3d.meshModelMatrix(item.opts),+ skinning: item.opts.skinningMatrices,+ windTime: item.opts.wind?.time,+ crowdTime: item.opts.crowd?.time,+ },+ item.opts.instanceBuffer,+ );+ } else if (item.kind === "quad") {+ h.recordQuad(key, shiftedFrame, r3d.quadModelMatrix(item.opts));+ }+ }+ h.recordFrame(shiftedFrame, cam);+ };+ /** Draws the queued items' screen motion since the last frame, then blurs `color` by it into `into`. */+ const blurScene = (+ h: MotionHistory,+ cam: Camera3DPose,+ color: GPUTexture,+ into: GPUTexture,+ blur: CameraMotionBlur,+ ) => {+ const r3d = getRenderer3D(+ ctx.device,+ ctx.renderer.format ?? "rgba8unorm",+ sampleCount3d,+ );+ const vel = r3d.beginVelocityPass(+ encoder,+ nativeWidth,+ nativeHeight,+ cam,+ h.previousCamera(shiftedFrame) ?? cam,+ );+ for (const [item, key] of motionItems()) {+ if (item.kind === "mesh") {+ const prev = key+ ? h.previousMesh(key, shiftedFrame, {+ skinning: item.opts.skinningMatrices,+ instanceBuffer: item.opts.instanceBuffer,+ wind: item.opts.wind,+ crowd: item.opts.crowd,+ })+ : undefined;+ r3d.drawMeshVelocity(+ vel.pass,+ vel.cameraBindGroup,+ item.meshBuffers ?? item.mesh,+ item.texture,+ item.opts,+ prev,+ );+ } else if (item.kind === "quad") {+ r3d.drawQuadVelocity(+ vel.pass,+ vel.cameraBindGroup,+ item.texture,+ item.opts,+ key ? h.previousQuad(key, shiftedFrame) : undefined,+ );+ }+ }+ vel.pass.end();+ r3d.applyMotionBlur(encoder, color, vel.velocity, into.createView(), {+ shutterAngle: blur.shutter,+ sampleCount: blur.samples,+ maxBlur: blur.maxBlur,+ });+ };+const flush3DPass = (curTex: GPUTexture,curView: GPUTextureView,@@ -1607,6 +1728,11 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {if (pending3DItems.length === 0 || !camera) {return { finalTex: curTex, finalView: curView };}+ if (historyOnly) {+ if (history) recordMotion(history, camera);+ pending3DItems.length = 0;+ return { finalTex: curTex, finalView: curView };+ }const r3d = getRenderer3D(ctx.device,@@ -2043,6 +2169,17 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {final3dTex = dofResultTex;}+ if (motionBlur && history) {+ const blurredTex = ctx.renderer.getTemporaryTexture(+ nativeWidth,+ nativeHeight,+ [curTex, targetTexture, scene3dTex, final3dTex, ...curExcludes],+ );+ blurScene(history, camera, final3dTex, blurredTex, motionBlur);+ final3dTex = blurredTex;+ }+ if (history) recordMotion(history, camera);+if (sceneBloom) {const bloomTex = ctx.renderer.getTemporaryTexture(nativeWidth,@@ -2537,6 +2674,9 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {{ cause: err },);}+ // Voronoi destruction draws the model's pieces, posed by physics below.+ if (model && lop.fracture3d)+ model = fracturedModel(model, lop.fracture3d);if (!model || model.meshes.length === 0) return;@@ -3089,6 +3229,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {crowd: crowdOpts(crowdBakes[k], mesh),};pending3DItems.push({+ owner: lop.id,kind: "mesh",mesh,texture: mat ? await r3d.materialTexture(mat) : undefined,@@ -3468,6 +3609,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {firstInstance,};pending3DItems.push({+ owner: lop.id,kind: "mesh",mesh,texture: mat ? await r3d.materialTexture(mat) : undefined,@@ -3501,6 +3643,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {firstInstance: sparkFirst,};pending3DItems.push({+ owner: lop.id,kind: "mesh",mesh,texture: mat ? await r3d.materialTexture(mat) : undefined,@@ -3537,18 +3680,31 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {finalModelMatrix,model.rootTransform ?? Matrix4Math.identity(),);- const posed = model.nodes- ? poseCharacter({- model,- node: lop,- frame: shiftedFrame ?? 0,- fps: fps || 30,- clip,- clipSec,- sceneRoot,- key: String(lop.id),- })- : undefined;+ // A whole fracture rests exactly (identity joints): pieces stay sealed.+ const wholeFracture = Boolean(+ lop.fracture3d &&+ fractureWhole(model, lop.fracture3d, shiftedFrame ?? 0),+ );+ const posed =+ (lop.fracture3d &&+ !wholeFracture &&+ fracturePose(model, lop.fracture3d, shiftedFrame ?? 0, sceneRoot, [+ scX,+ scY,+ scZ,+ ])) ||+ (model.nodes+ ? poseCharacter({+ model,+ node: lop,+ frame: shiftedFrame ?? 0,+ fps: fps || 30,+ clip,+ clipSec,+ sceneRoot,+ key: String(lop.id),+ })+ : undefined);const skinCache = new Map<number, Float32Array>();const placeMesh = (mesh: Mesh3DData,@@ -3620,6 +3776,8 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {}for (const mesh of model.meshes) {+ if (wholeFracture && mesh.materialName === FRACTURE_INTERIOR_MATERIAL)+ continue;const mat = mesh.materialName? model.materials[mesh.materialName]: undefined;@@ -3845,6 +4003,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {if (mat) meshOpts.maps = await r3d.materialMaps(mat);pending3DItems.push({+ owner: lop.id,kind: "mesh",mesh,texture: mat ? await r3d.materialTexture(mat) : undefined,@@ -4309,6 +4468,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {}pending3DItems.push({+ owner: lop.id,kind: "quad",texture: activeGroupTex,opts: quadOpts,@@ -6022,6 +6182,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {);if (!glyphBatches || quadHasContent) {pending3DItems.push({+ owner: lop.id,kind: "quad",texture: renderedTex,opts: quadOpts,@@ -6029,6 +6190,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {}if (glyphBatches && glyphBatches.length > 0) {pending3DItems.push({+ owner: lop.id,kind: "slug",batches: glyphBatches,opts: quadOpts,@@ -6282,6 +6444,59 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {}};+/** Whether a composition's camera asks for shutter motion blur. */+function sceneMotionBlur(virtualMedia: VirtualMediaData): boolean {+ return collectNodeOps(virtualMedia.children).some((vm) => {+ const op = vm.operation as+ | { kind?: string; motionBlur?: unknown }+ | undefined;+ return op?.kind === "camera" && Boolean(op.motionBlur);+ });+}++/**+ * Renders `frame` of the composition into a scratch target only to record+ * its 3D motion history (the frame after it reads it).+ */+async function renderMotionHistory(+ args: Parameters<WebGPUNodeRenderer>[0],+ frame: number,+): Promise<void> {+ const { ctx, encoder, props, targetTexture, targetWidth, targetHeight } =+ args;+ const excludeTextures = [...(props.excludeTextures ?? []), targetTexture];+ const scratch = ctx.renderer.getTemporaryTexture(+ targetWidth,+ targetHeight,+ excludeTextures,+ );+ const view = scratch.createView();+ const sub = {+ ...args,+ targetView: view,+ targetTexture: scratch,+ pass: ctx.renderer.beginFrame(+ encoder,+ view,+ { r: 0, g: 0, b: 0, a: 0 },+ targetWidth,+ targetHeight,+ "clear",+ ),+ props: {+ ...props,+ frame,+ ...(props.compositionFrame !== undefined && {+ compositionFrame: props.compositionFrame - 1,+ }),+ motionHistoryOnly: true,+ excludeTextures,+ },+ };+ await CompositorWebGPURenderer(sub);+ sub.pass.end();+}+/** Pixels of room around a border texture for its anti-aliased edge. */const BORDER_AA_MARGIN = 2;diff --git a/packages/compositions/src/program/procedural-schema.ts b/packages/compositions/src/program/procedural-schema.tsindex 180b5ba3..ef5241da 100644--- a/packages/compositions/src/program/procedural-schema.ts+++ b/packages/compositions/src/program/procedural-schema.ts@@ -213,3 +213,24 @@ export const TextureLayerSchema = znode: z.custom<unknown>((v) => typeof v === "object" && v !== null),}).strict();++/**+ * Voronoi destruction (`world.fracture`): the model is cut into `cells`+ * pieces, drawn as one rigidly skinned mesh posed per frame from `track`.+ * Without a track the pieces rest in place and the model looks whole.+ */+export const Fracture3DSchema = z+ .object({+ /** Voronoi pieces, 2..256. Default 48. */+ cells: z.number().int().min(2).max(256).optional(),+ seed: z.number().optional(),+ /** Object-space point the pieces crowd around. */+ impactPoint: Vec3Schema.optional(),+ /** Exposed faces' color. Default "#d8d2c4". */+ interiorColor: z.string().optional(),+ interiorRoughness: z.number().min(0).max(1).optional(),+ /** Per composition frame, per piece: x, y, z (scene px), qx, qy, qz, qw. */+ track: z.array(z.number()).optional(),+ })+ .strict();+export type Fracture3DSpec = z.infer<typeof Fracture3DSchema>;diff --git a/packages/compositions/src/program/schema.ts b/packages/compositions/src/program/schema.tsindex f8ca0705..947c13df 100644--- a/packages/compositions/src/program/schema.ts+++ b/packages/compositions/src/program/schema.ts@@ -40,6 +40,8 @@ import {TwoBoneIkSchema,} from "./character-schema.js";import {+ Fracture3DSchema,+ type Fracture3DSpec,Primitive3DSpecSchema,Scatter3DSchema,type Scatter3DSpec,@@ -1420,6 +1422,24 @@ export const CameraShakeSchema = zexport type CameraShake = z.input<typeof CameraShakeSchema>;+/**+ * Per-object shutter motion blur for the 3D scene: every mesh, skinned+ * joint, instance and fractured piece streaks by its own motion over the+ * shutter (and the camera's), reconstructed from a velocity buffer.+ */+export const CameraMotionBlurSchema = z+ .object({+ /** Shutter angle, degrees: 180 is the film look, 360 the whole frame interval. Default 180. */+ shutter: z.number().min(1).max(720).default(180),+ /** Taps along each pixel's motion, 4..64. Default 20. */+ samples: z.number().int().min(4).max(64).default(20),+ /** Longest streak from a pixel, px (also the tile size). Default 48. */+ maxBlur: z.number().min(4).max(160).default(48),+ })+ .strict();++export type CameraMotionBlur = z.input<typeof CameraMotionBlurSchema>;+export interface CameraNode {id: string;kind: "camera";@@ -1436,6 +1456,8 @@ export interface CameraNode {lens?: CameraLens;dof?: CameraDoF;shake?: CameraShake;+ /** Shutter motion blur of the 3D scene; `true` takes the defaults. */+ motionBlur?: boolean | CameraMotionBlur;startFrame?: number;durationFrames?: number;animation?: LayerAnimationSpec;@@ -1458,6 +1480,7 @@ export const CameraNodeSchema: z.ZodType<CameraNode> = zlens: CameraLensSchema.optional(),dof: CameraDoFSchema.optional(),shake: CameraShakeSchema.optional(),+ motionBlur: z.union([z.boolean(), CameraMotionBlurSchema]).optional(),startFrame: z.number().int().min(0).default(0),durationFrames: z.number().int().min(1).optional(),animation: LayerAnimationSchema.default({ tracks: [] }),@@ -1808,6 +1831,8 @@ export interface Model3DNode {swarm3d?: unknown;/** Layer3D.scatter: instances placed on another model's surface. */scatter3d?: Scatter3DSpec;+ /** Voronoi destruction: the mesh drawn as pieces posed by physics (`world.fracture`). */+ fracture3d?: Fracture3DSpec;/** Procedural wind sway (bends vertices downwind by height above the mesh base). */wind?: WindConfig;/** Any layer (image, video, layout) drawn each frame and wrapped onto the mesh by its UVs. */@@ -2149,6 +2174,7 @@ export const Model3DNodeSchema: z.ZodType<Model3DNode> = zinstances3d: z.unknown().optional(),swarm3d: z.unknown().optional(),scatter3d: Scatter3DSchema.optional(),+ fracture3d: Fracture3DSchema.optional(),wind: WindSchema.optional(),textureLayer: TextureLayerSchema.optional(),textureLayerId: z.string().optional(),diff --git a/packages/framefields/src/index.ts b/packages/framefields/src/index.tsindex 57c6c33e..6de0b3bd 100644--- a/packages/framefields/src/index.ts+++ b/packages/framefields/src/index.ts@@ -934,6 +934,8 @@ export {type BodyCommonOptions,type FieldSample2D,type FieldSample3D,+ Fracture3D,+ type Fracture3DOptions,Physics,type PhysicsBakeOptions,PhysicsBody2D,diff --git a/packages/framefields/src/motion-blur-render.test.ts b/packages/framefields/src/motion-blur-render.test.tsnew file mode 100644index 00000000..a6fbf42d--- /dev/null+++ b/packages/framefields/src/motion-blur-render.test.ts@@ -0,0 +1,236 @@+/**+ * Shutter motion blur of 3D scenes through the real renderer: objects+ * streak along their own motion (model matrix, skinning, instances,+ * fractured pieces), still things stay sharp, and a frame renders the same+ * whether reached in order or by a seek.+ */+import { describe, expect, it } from "vitest";+import {+ Composition,+ Layer,+ Layer3D,+ LayerAnimation,+ type LayoutNode,+ Physics,+} from "./index.js";+import { decodePngPixels } from "./test-utils/pixels.js";++const SIZE = 400;+const C = SIZE / 2;++function scene(+ layers: LayoutNode[],+ motionBlur: boolean | { shutter?: number } = true,+ camera: Record<string, unknown> = {},+): Composition {+ const comp = new Composition({+ width: SIZE,+ height: SIZE,+ fps: 30,+ durationFrames: 60,+ backgroundColor: "#000000",+ });+ comp.add([+ Layer.camera({+ x: C,+ y: C,+ // One model unit per pixel at z = 0.+ z: -C / Math.tan((25 * Math.PI) / 180),+ targetX: C,+ targetY: C,+ targetZ: 0,+ motionBlur,+ ...camera,+ }),+ ...layers,+ ]);+ return comp;+}++/** A white box moving right at `speed` px per frame. */+const mover = (speed: number, y = C) =>+ Layer3D.roundedBox({+ id: "mover",+ x: C,+ y,+ z: 0,+ width: 60,+ height: 60,+ depth: 20,+ radius: 0,+ color: "#ffffff",+ material: "unlit",+ }).animate(+ LayerAnimation.create().keys("x", [+ [0, C - 30 * speed],+ [60, C + 30 * speed],+ ]),+ );++async function row(comp: Composition, frame: number, y: number) {+ const { pixels } = await decodePngPixels(await comp.renderFrame({ frame }));+ return Array.from(+ { length: SIZE },+ (_, x) => pixels[(y * SIZE + x) * 4] ?? 0,+ );+}+async function column(comp: Composition, frame: number, x: number) {+ const { pixels } = await decodePngPixels(await comp.renderFrame({ frame }));+ return Array.from(+ { length: SIZE },+ (_, y) => pixels[(y * SIZE + x) * 4] ?? 0,+ );+}+/** Pixels partly covered: neither background nor solid. */+const partial = (line: number[]) =>+ line.filter((v) => v > 12 && v < 243).length;+/** Width of the leading edge's ramp, from 5% to 95% coverage, px. */+function ramp(line: number[]): number {+ const start = line.findIndex((v) => v > 12);+ const end = line.findIndex((v, i) => i > start && v > 243);+ return end - start;+}++describe("shutter motion blur", () => {+ it("streaks a moving mesh along its motion only", async () => {+ const sharp = await row(scene([mover(24)], false), 30, C);+ const blurred = await row(scene([mover(24)]), 30, C);+ expect(ramp(sharp)).toBeLessThan(3);+ // 24 px per frame at a 180° shutter: each edge ramps over ~12 px.+ expect(ramp(blurred)).toBeGreaterThan(9);+ expect(ramp(blurred)).toBeLessThan(15);+ // A 360° shutter streaks twice as far.+ const open = await row(scene([mover(24)], { shutter: 360 }), 30, C);+ expect(ramp(open)).toBeGreaterThan(ramp(blurred) + 6);+ // The streak spreads coverage past the box's edges, keeping its total.+ const sum = (a: number[]) => a.reduce((s, v) => s + v, 0);+ expect(Math.abs(sum(blurred) - sum(sharp)) / sum(sharp)).toBeLessThan(0.05);+ // Across the motion the edges stay sharp.+ const across = await column(scene([mover(24)]), 30, C);+ expect(partial(across)).toBeLessThan(6);+ });++ it("leaves a still scene exactly as it was", async () => {+ const still = (blur: boolean) =>+ scene(+ [+ Layer3D.roundedBox({+ id: "still",+ x: C,+ y: C,+ width: 100,+ height: 80,+ depth: 40,+ rotateY: 30,+ color: "#d0a060",+ }),+ Layer.directionalLight({ x: -200, y: -300, z: -300 }),+ ],+ blur,+ );+ const a = await still(false).renderFrame({ frame: 12 });+ const b = await still(true).renderFrame({ frame: 12 });+ expect(b).toEqual(a);+ });++ it("renders a frame the same after a seek as in order", async () => {+ const inOrder = scene([mover(10)]);+ for (const f of [17, 18, 19]) await inOrder.renderFrame({ frame: f });+ const sequential = await inOrder.renderFrame({ frame: 20 });+ const seeked = await scene([mover(10)]).renderFrame({ frame: 20 });+ expect(seeked).toEqual(sequential);+ });++ it("blurs a camera pan over still objects", async () => {+ const pan = LayerAnimation.create()+ .keys("x", [+ [0, C - 300],+ [60, C + 300],+ ])+ .keys("targetX", [+ [0, C - 300],+ [60, C + 300],+ ]);+ const comp = (blur: boolean) => {+ const c = new Composition({+ width: SIZE,+ height: SIZE,+ fps: 30,+ durationFrames: 60,+ backgroundColor: "#000000",+ });+ c.add([+ Layer.camera({+ id: "cam",+ x: C,+ y: C,+ z: -C / Math.tan((25 * Math.PI) / 180),+ targetX: C,+ targetY: C,+ targetZ: 0,+ motionBlur: blur,+ }).animate(pan),+ Layer3D.roundedBox({+ id: "post",+ x: C,+ y: C,+ width: 40,+ height: 200,+ depth: 20,+ radius: 0,+ color: "#ffffff",+ material: "unlit",+ }),+ ]);+ return c;+ };+ // 10 px per frame on screen: a ~5 px ramp at 180°.+ expect(ramp(await row(comp(false), 30, C))).toBeLessThan(3);+ const panned = ramp(await row(comp(true), 30, C));+ expect(panned).toBeGreaterThan(3);+ expect(panned).toBeLessThan(8);+ });++ it("blurs fractured pieces by their own motion (skinned velocity)", async () => {+ const build = async (blur: boolean) => {+ const slab = Layer3D.roundedBox({+ id: "slab",+ x: C,+ y: C - 60,+ width: 160,+ height: 60,+ depth: 60,+ radius: 0,+ color: "#ffffff",+ material: "unlit",+ });+ const world = await Physics.world3d({ fps: 30, frames: 40 });+ world.fracture(slab, {+ cells: 12,+ fractureFrame: 5,+ explosionSpeed: 900,+ });+ world.simulate();+ return scene([slab], blur);+ };+ const sharp = await build(false);+ const blurred = await build(true);+ // Whole and still before the break: identical.+ expect(await blurred.renderFrame({ frame: 3 })).toEqual(+ await sharp.renderFrame({ frame: 3 }),+ );+ const { pixels: a } = await decodePngPixels(+ await sharp.renderFrame({ frame: 12 }),+ );+ const { pixels: b } = await decodePngPixels(+ await blurred.renderFrame({ frame: 12 }),+ );+ let partialA = 0;+ let partialB = 0;+ for (let i = 0; i < a.length; i += 4) {+ if ((a[i] ?? 0) > 12 && (a[i] ?? 0) < 243) partialA++;+ if ((b[i] ?? 0) > 12 && (b[i] ?? 0) < 243) partialB++;+ }+ expect(partialB).toBeGreaterThan(partialA * 1.3);+ });+});diff --git a/packages/framefields/src/physics/backend.ts b/packages/framefields/src/physics/backend.tsindex 307fe3d5..ae25929b 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;+ /** Sets linear and angular velocity (wakes the body). */+ setVelocity(linear: V, angular: R extends number ? number : Vec3): void;setKinematicTarget(position: V, rotation: R): void;}@@ -227,6 +229,10 @@ class RapierWorld2D implements SimWorld2D {mass: () => body.mass(),setEnabled: (on) => body.setEnabled(on),applyImpulse: ([x, y]) => body.applyImpulse({ x, y }, true),+ setVelocity: ([x, y], w) => {+ body.setLinvel({ x, y }, true);+ body.setAngvel(w, true);+ },setKinematicTarget: ([x, y], angle) => {body.setNextKinematicTranslation({ x, y });body.setNextKinematicRotation(angle);@@ -361,6 +367,10 @@ class RapierWorld3D implements SimWorld3D {mass: () => body.mass(),setEnabled: (on) => body.setEnabled(on),applyImpulse: (v) => body.applyImpulse(vec3(v), true),+ setVelocity: (v, w) => {+ body.setLinvel(vec3(v), true);+ body.setAngvel(vec3(w), true);+ },setKinematicTarget: (p, [x, y, z, w]) => {body.setNextKinematicTranslation(vec3(p));body.setNextKinematicRotation({ x, y, z, w });diff --git a/packages/framefields/src/physics/core.ts b/packages/framefields/src/physics/core.tsindex 27d42811..2d64c445 100644--- a/packages/framefields/src/physics/core.ts+++ b/packages/framefields/src/physics/core.ts@@ -281,6 +281,12 @@ export abstract class WorldCore<targets?: Set<B>;accel: (body: B, frame: number) => V | null | undefined;}> = [];+ /** Run after each simulated frame with the pairs that started touching in it. */+ protected readonly stepHooks: Array<+ (frame: number, pairs: Array<[B, B]>) => void+ > = [];+ /** Run once the whole simulation has finished (not in live worlds). */+ protected readonly simulatedHooks: Array<() => void> = [];private readonly worldRecording: Recording;private readonly allCollisions: Array<PhysicsCollision<B> & { body: B }> = [];/** No more bodies, joints or forces: the world has started (or finished). */@@ -361,6 +367,11 @@ export abstract class WorldCore<"Physics: live() must come before simulate() or reading any body signal.",);}+ if (this.simulatedHooks.length) {+ throw new Error(+ "Physics: fracture() needs the whole run up front; use simulate() instead of live().",+ );+ }this.locked = true;this.liveMode = true;const prepare = async (frame: number) => {@@ -457,6 +468,7 @@ export abstract class WorldCore<st.freed = true;this.sim.free();for (const body of this.bodies) this.bind(body);+ for (const hook of this.simulatedHooks) hook();}/** Records frame 0 and sets every channel to it, so frames not simulated yet hold the start pose. */@@ -619,6 +631,7 @@ export abstract class WorldCore<if (level > loudest) loudest = level;}this.worldRecording.channel("impact")[frame] = loudest;+ for (const hook of this.stepHooks) hook(f, pairs);st.current = f;}diff --git a/packages/framefields/src/physics/fracture-render.test.ts b/packages/framefields/src/physics/fracture-render.test.tsnew file mode 100644index 00000000..2784addf--- /dev/null+++ b/packages/framefields/src/physics/fracture-render.test.ts@@ -0,0 +1,166 @@+/**+ * Voronoi destruction through the real renderer: a fractured layer looks+ * whole until it breaks, then its pieces fall as rigid bodies; a hit breaks+ * it on contact.+ */+import { describe, expect, it } from "vitest";+import {+ Composition,+ CompositorProgramSchema,+ Layer,+ Layer3D,+ type LayoutNode,+} from "../index.js";+import { decodePngPixels } from "../test-utils/pixels.js";+import { Physics } from "./index.js";++const FPS = 30;+const SIZE = 400;+const C = SIZE / 2;++function scene(layers: LayoutNode[]): Composition {+ const comp = new Composition({+ width: SIZE,+ height: SIZE,+ fps: FPS,+ durationFrames: 60,+ backgroundColor: "#000000",+ });+ comp.add([+ Layer.camera({+ x: C,+ y: C,+ z: -C / Math.tan((25 * Math.PI) / 180),+ targetX: C,+ targetY: C,+ targetZ: 0,+ }),+ ...layers,+ ]);+ return comp;+}++const slab = (id: string) =>+ Layer3D.roundedBox({+ id,+ x: C,+ y: C,+ z: 0,+ width: 160,+ height: 60,+ depth: 60,+ radius: 0,+ color: "#ffffff",+ material: "unlit",+ });++/** Lit pixels and their mean y. */+async function coverage(comp: Composition, frame: number) {+ const { pixels } = await decodePngPixels(await comp.renderFrame({ frame }));+ let lit = 0;+ let sy = 0;+ for (let i = 0; i < pixels.length; i += 4) {+ if ((pixels[i] ?? 0) > 128) {+ lit++;+ sy += Math.floor(i / 4 / SIZE);+ }+ }+ return { lit, meanY: sy / Math.max(1, lit), pixels };+}++describe("Physics.fracture", () => {+ it("looks whole until its fracture frame, then falls apart", async () => {+ const whole = scene([slab("whole")]);+ const target = slab("slab");+ const comp = scene([target]);+ const world = await Physics.world3d({ fps: FPS, frames: 40 });+ world.ground({ y: C + 140 });+ const broken = world.fracture(target, {+ cells: 16,+ fractureFrame: 10,+ explosionSpeed: 300,+ interiorColor: "#ff0000",+ });+ world.simulate();+ expect(broken.frame).toBe(10);+ expect(broken.pieces.length).toBeGreaterThan(8);++ const ref = await coverage(whole, 5);+ const before = await coverage(comp, 5);+ // The pieces tile the slab exactly: the same picture, no cut faces showing.+ let diff = 0;+ for (let i = 0; i < ref.pixels.length; i += 4) {+ if (Math.abs((ref.pixels[i] ?? 0) - (before.pixels[i] ?? 0)) > 40) diff++;+ }+ expect(diff).toBeLessThan(ref.lit * 0.01);++ const after = await coverage(comp, 39);+ // Pieces fell (y down) onto the ground; red cut faces show.+ expect(after.meanY).toBeGreaterThan(before.meanY + 50);+ let red = 0;+ for (let i = 0; i < after.pixels.length; i += 4) {+ if ((after.pixels[i] ?? 0) > 150 && (after.pixels[i + 1] ?? 0) < 80)+ red++;+ }+ expect(red).toBeGreaterThan(50);+ });++ it("breaks on impact, and the spec carries the pieces' track", async () => {+ const target = slab("slab");+ const ball = Layer3D.sphere({+ id: "ball",+ x: C,+ y: C - 200,+ z: 0,+ radius: 20,+ color: "#ffffff",+ material: "unlit",+ });+ const comp = scene([target, ball]);+ const world = await Physics.world3d({ fps: FPS, frames: 40 });+ const broken = world.fracture(target, { cells: 12, seed: 4 });+ world.body(ball, { velocity: [0, 600, 0] });+ world.simulate();+ // Falling ~170 px at 600 px/s plus gravity: contact within a few frames of 0.25 s.+ expect(broken.frame).toBeGreaterThan(4);+ expect(broken.frame).toBeLessThan(12);++ const spec = comp.toSpec();+ expect(CompositorProgramSchema.safeParse(spec).success).toBe(true);+ const fracture = (target as unknown as { fracture3d: { track: number[] } })+ .fracture3d;+ expect(fracture.track.length).toBe(40 * broken.pieces.length * 7);++ // Pieces stay put before the hit and move after it.+ const at = (f: number, piece: number) =>+ fracture.track.slice(+ (f * broken.pieces.length + piece) * 7,+ (f * broken.pieces.length + piece) * 7 + 3,+ );+ const f0 = broken.frame ?? 0;+ expect(at(0, 0)).toEqual(at(f0, 0));+ const moved = broken.pieces.some(+ (_, i) => Math.hypot(...at(39, i).map((v, k) => v - at(0, i)[k]!)) > 20,+ );+ expect(moved).toBe(true);+ });++ it("rebuilds the pieces when modelData is lost (a JSON spec)", async () => {+ const target = slab("slab");+ const world = await Physics.world3d({ fps: FPS, frames: 30 });+ world.ground({ y: C + 140 });+ world.fracture(target, {+ cells: 10,+ fractureFrame: 5,+ explosionSpeed: 200,+ });+ world.simulate();+ const direct = await scene([target]).renderFrame({ frame: 25 });+ // The renderer rebuilds the box from its options and fractures it again.+ const copy = JSON.parse(+ JSON.stringify({ ...target, modelData: undefined }),+ ) as LayoutNode;+ const replay = await scene([copy]).renderFrame({ frame: 25 });+ expect(replay).toEqual(direct);+ });+});diff --git a/packages/framefields/src/physics/fracture3d.ts b/packages/framefields/src/physics/fracture3d.tsnew file mode 100644index 00000000..24b35d2e--- /dev/null+++ b/packages/framefields/src/physics/fracture3d.ts@@ -0,0 +1,253 @@+/**+ * Voronoi destruction: a mesh layer stays whole (a fixed collider of its+ * own shape) until its fracture frame, or until a body hits it, then its+ * pieces wake as rigid bodies and fly apart. The pieces' recorded poses go+ * into the node (`fracture3d.track`), where the renderer turns them into+ * the joints of one rigidly skinned mesh.+ */+import type {+ Fracture3DSpec,+ LayoutNode,+} from "@framefields/compositions/program";+import {+ createRandom,+ fractureModel,+ type Mat4,+ Matrix4Math,+ type Model3DData,+} from "@framefields/webgpu-renderers";+import type { Vec3 } from "./backend.js";+import type { LayerLike, PhysicsBody3D, PhysicsWorld3D } from "./world3d.js";++export interface Fracture3DOptions {+ /** Voronoi pieces (2..256). Default 48. */+ cells?: number;+ /** Same seed, same pieces. Default 1. */+ seed?: number;+ /** Scene point (px) the pieces crowd around and fly from. */+ impactPoint?: [number, number, number];+ /**+ * Composition frame the layer breaks at, or `"onImpact"` (default): the+ * first frame a body hits it.+ */+ fractureFrame?: number | "onImpact";+ /** Color of the faces the break exposes. Default "#d8d2c4". */+ interiorColor?: string;+ /** Roughness of the exposed faces. Default 0.9. */+ interiorRoughness?: number;+ /** Outward speed at the impact point, px/s, fading with distance. Default 0. */+ explosionSpeed?: number;+ /** Random tumble, degrees per second. Default a third of `explosionSpeed`. */+ spin?: number;+ /** Share of the hitting body's velocity the nearest pieces take. Default 0.35. */+ momentumTransfer?: number;+ density?: number;+ friction?: number;+ restitution?: number;+}++/** A fractured layer: its pieces, and the collider that stands in for it while whole. */+export class Fracture3D {+ /** @internal */ brokeAt?: number;++ /** @internal */+ constructor(+ readonly node: LayoutNode,+ readonly pieces: readonly PhysicsBody3D[],+ readonly intact: PhysicsBody3D,+ private readonly world: PhysicsWorld3D,+ ) {}++ /** Composition frame it broke at (after simulating); undefined if it never did. */+ get frame(): number | undefined {+ return this.brokeAt === undefined+ ? undefined+ : this.world.startFrame + this.brokeAt;+ }+}++const NEVER = Number.MAX_SAFE_INTEGER;+const num = (v: unknown, fallback: number) =>+ typeof v === "number" && Number.isFinite(v) ? v : fallback;++interface NodePose {+ position: Vec3;+ rotation: Vec3;+ scale: Vec3;+ matrix: Mat4;+}++/** The node's placement as the renderer builds it: T · Rz · Ry · Rx · S. */+function nodePose(t: LayerLike): NodePose {+ 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, num(t.rotation, 0)),+ ];+ 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 rad = (d: number) => (d * Math.PI) / 180;+ let m = Matrix4Math.translate(...position);+ m = Matrix4Math.multiply(m, Matrix4Math.rotateZ(rad(rotation[2])));+ m = Matrix4Math.multiply(m, Matrix4Math.rotateY(rad(rotation[1])));+ m = Matrix4Math.multiply(m, Matrix4Math.rotateX(rad(rotation[0])));+ m = Matrix4Math.multiply(m, Matrix4Math.scale(...scale));+ return { position, rotation, scale, matrix: m };+}++const apply = (m: Mat4, p: Vec3): Vec3 => [+ m[0] * p[0] + m[4] * p[1] + m[8] * p[2] + m[12],+ m[1] * p[0] + m[5] * p[1] + m[9] * p[2] + m[13],+ m[2] * p[0] + m[6] * p[1] + m[10] * p[2] + m[14],+];++/** @internal */+export function createFracture(+ world: PhysicsWorld3D,+ target: LayoutNode,+ options: Fracture3DOptions,+): Fracture3D {+ const node = target as unknown as LayerLike;+ const model = node.modelData as Model3DData | undefined;+ if (!model?.meshes?.length) {+ const id = typeof node.id === "string" ? ` "${node.id}"` : "";+ throw new Error(+ `Physics.fracture: layer${id} has no mesh. Fracture a Layer3D primitive, extruded text, or a model node that carries modelData.`,+ );+ }+ const pose = nodePose(node);+ const toObject = Matrix4Math.invert(pose.matrix) ?? Matrix4Math.identity();+ const spec: Fracture3DSpec = {+ cells: Math.max(2, Math.min(256, Math.round(options.cells ?? 48))),+ seed: options.seed ?? 1,+ ...(options.impactPoint && {+ impactPoint: apply(toObject, options.impactPoint),+ }),+ ...(options.interiorColor && { interiorColor: options.interiorColor }),+ ...(options.interiorRoughness !== undefined && {+ interiorRoughness: options.interiorRoughness,+ }),+ };+ const { cells } = fractureModel(model, spec);+ node.fracture3d = spec;++ const intact = world.body(target, { type: "fixed", output: "none" });+ const pieces = cells.map((cell) =>+ world.shapedBody(+ undefined,+ apply(pose.matrix, cell.centroid),+ pose.rotation,+ {+ kind: "hull",+ // A hair smaller than the piece, so neighbors start apart.+ points: cell.hull.map((v, i) => v * pose.scale[i % 3]! * 0.97),+ },+ {+ type: "dynamic",+ startFrame: NEVER,+ output: "none",+ density: options.density,+ friction: options.friction,+ restitution: options.restitution ?? 0.2,+ },+ ),+ );+ const fracture = new Fracture3D(target, pieces, intact, world);+ const radius = model.bounds.boundingSphereRadius * Math.max(...pose.scale);++ world.onStep((f, pairs) => {+ if (fracture.brokeAt !== undefined) return;+ const ff = options.fractureFrame ?? "onImpact";+ const hit = pairs.find(+ ([a, b]) =>+ (a === intact && b.type === "dynamic") ||+ (b === intact && a.type === "dynamic"),+ );+ const hitter = hit ? (hit[0] === intact ? hit[1] : hit[0]) : undefined;+ const due =+ ff === "onImpact" ? Boolean(hitter) : f >= ff - world.startFrame;+ if (!due) return;+ fracture.brokeAt = f;+ intact.sim.setEnabled(false);+ breakApart(world, pieces, options, radius, pose.position, hitter, f);+ });+ world.onSimulated(() => {+ spec.track = recordTrack(pieces, world.startFrame + world.frames);+ });+ return fracture;+}++/** Wakes every piece: outward from the impact, plus some of the hitter's momentum. */+function breakApart(+ world: PhysicsWorld3D,+ pieces: readonly PhysicsBody3D[],+ options: Fracture3DOptions,+ radius: number,+ center: Vec3,+ hitter: PhysicsBody3D | undefined,+ frame: number,+): void {+ const ppm = world.pixelsPerMeter;+ 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+ // through, handing some of its momentum to the pieces.+ const hitVel: Vec3 = [0, 0, 0];+ if (hitter) {+ const at = world.startFrame + frame - 1;+ const rec = hitter.recording;+ hitVel[0] = rec.channel("vx")[at] ?? 0;+ hitVel[1] = rec.channel("vy")[at] ?? 0;+ hitVel[2] = rec.channel("vz")[at] ?? 0;+ hitter.sim.setVelocity(+ hitVel.map((v) => (v * (1 - transfer)) / ppm) as Vec3,+ hitter.sim.angularVelocity(),+ );+ }+ const impact = options.impactPoint ?? hitAt ?? center;+ 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();+ 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,+ ) 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);+ }+}++/** Every piece's pose per composition frame: [x, y, z, qx, qy, qz, qw] each. */+function recordTrack(+ pieces: readonly PhysicsBody3D[],+ frames: number,+): number[] {+ const channels = pieces.map((b) =>+ ["x", "y", "z", "qx", "qy", "qz", "qw"].map((c) => b.recording.channel(c)),+ );+ const out: number[] = new Array(frames * pieces.length * 7);+ let k = 0;+ for (let f = 0; f < frames; f++) {+ for (const ch of channels) {+ for (let c = 0; c < 7; c++) {+ const v = ch[c]![f] ?? 0;+ // 1e-5 px and 1e-7 per quaternion component: compact JSON, and+ // pieces resting side by side stay sealed (no sub-pixel cracks).+ out[k++] =+ c < 3 ? Math.round(v * 1e5) / 1e5 : Math.round(v * 1e7) / 1e7;+ }+ }+ }+ return out;+}diff --git a/packages/framefields/src/physics/index.ts b/packages/framefields/src/physics/index.tsindex 5364e7c9..17aef5bd 100644--- a/packages/framefields/src/physics/index.ts+++ b/packages/framefields/src/physics/index.ts@@ -34,6 +34,7 @@ export type {PhysicsDriver,PhysicsWorldOptions,} from "./core.js";+export { Fracture3D, type Fracture3DOptions } from "./fracture3d.js";export {type Body2DOptions,type FieldSample2D,diff --git a/packages/framefields/src/physics/world3d.ts b/packages/framefields/src/physics/world3d.tsindex 390175e3..89594efb 100644--- a/packages/framefields/src/physics/world3d.ts+++ b/packages/framefields/src/physics/world3d.ts@@ -23,6 +23,11 @@ import {unwrapDegrees,WorldCore,} from "./core.js";+import {+ createFracture,+ type Fracture3D,+ type Fracture3DOptions,+} from "./fracture3d.js";export interface World3DOptions extends PhysicsWorldOptions {/** px/s², y down. A number pulls straight down. Default 2400. */@@ -85,7 +90,8 @@ export interface Body3DOptions extends Omit<BodyCommonOptions, "lockRotation"> {};}-type LayerLike = Record<string, unknown> & { kind?: string };+/** @internal */+export type LayerLike = Record<string, unknown> & { kind?: string };const DEG = Math.PI / 180;@@ -175,7 +181,27 @@ export class PhysicsBody3D implements CoreBody<Vec3, Quat> {}get startFrame(): number {- return Math.max(0, Math.round(this.options.startFrame ?? 0));+ return this.wokeAt ?? Math.max(0, Math.round(this.options.startFrame ?? 0));+ }+ private wokeAt?: number;++ /**+ * @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).+ */+ wake(frame: number, velocity: Vec3, angularVelocity: Vec3): void {+ this.wokeAt = frame;+ const ppm = this.world.pixelsPerMeter;+ this.sim.setEnabled(true);+ this.sim.setVelocity(+ [velocity[0] / ppm, velocity[1] / ppm, velocity[2] / ppm],+ [+ angularVelocity[0] * DEG,+ angularVelocity[1] * DEG,+ angularVelocity[2] * DEG,+ ],+ );}get gravityScale(): number {return this.options.gravityScale ?? 1;@@ -267,7 +293,12 @@ export class PhysicsBody3D implements CoreBody<Vec3, Quat> {previous < 0? this.start.rotation: [rx[previous], ry[previous], rz[previous]];- const e = eulerFromQuat(this.sim.rotation(), prev);+ const q = this.sim.rotation();+ rec.channel("qx")[index] = q[0];+ rec.channel("qy")[index] = q[1];+ rec.channel("qz")[index] = q[2];+ rec.channel("qw")[index] = q[3];+ const e = eulerFromQuat(q, prev);rx[index] = e[0];ry[index] = e[1];rz[index] = e[2];@@ -391,6 +422,24 @@ export class PhysicsWorld3D extends WorldCore<Vec3, Quat, PhysicsBody3D> {num(options.rotateY ?? t.rotateY, 0),num(options.rotateZ ?? t.rotateZ, 0),];+ return this.shapedBody(+ layer,+ position,+ rotation,+ colliderShape3D(t, options),+ options,+ );+ }++ /** @internal A body with an explicit collider (px), at a pose in px and degrees. */+ shapedBody(+ layer: LayerLike | undefined,+ position: Vec3,+ rotation: Vec3,+ shape: Shape3D,+ options: Body3DOptions,+ ): PhysicsBody3D {+ this.assertOpen();const ppm = this.pixelsPerMeter;const type = options.type ?? "dynamic";const v = options.velocity ?? [0, 0, 0];@@ -418,7 +467,7 @@ export class PhysicsWorld3D extends WorldCore<Vec3, Quat, PhysicsBody3D> {density: options.density ?? 1,friction: options.friction ?? 0.6,restitution: options.restitution ?? 0.3,- shape: scaleShape(colliderShape3D(t, options), 1 / ppm),+ shape: scaleShape(shape, 1 / ppm),};const simBody = (this.sim as unknown as SimWorld3D).addBody(spec);const body = new PhysicsBody3D(@@ -433,6 +482,31 @@ export class PhysicsWorld3D extends WorldCore<Vec3, Quat, PhysicsBody3D> {return this.addBody(body);}+ /** @internal Runs after each simulated frame (frame relative to the world's start). */+ onStep(+ hook: (frame: number, pairs: Array<[PhysicsBody3D, PhysicsBody3D]>) => void,+ ): void {+ this.assertOpen();+ this.stepHooks.push(hook);+ }++ /** @internal Runs once the simulation has finished. */+ onSimulated(hook: () => void): void {+ this.assertOpen();+ this.simulatedHooks.push(hook);+ }++ /**+ * Breaks a Layer3D primitive, extruded text or loaded model into Voronoi+ * pieces that stay together, looking intact, until the fracture frame (or+ * until something hits it), then fly apart as rigid bodies. The node is+ * changed in place: add it to the composition as usual. All pieces draw+ * in one call per material, the cut faces in `interiorColor`.+ */+ fracture(target: LayoutNode, options: Fracture3DOptions = {}): Fracture3D {+ return createFracture(this, target, options);+ }+/** A fixed, very large floor whose top face sits at `y`. */ground(options: {y: number;diff --git a/packages/node-sdk/renderer/index.ts b/packages/node-sdk/renderer/index.tsindex 021efd0d..110e6b98 100644--- a/packages/node-sdk/renderer/index.ts+++ b/packages/node-sdk/renderer/index.ts@@ -48,6 +48,11 @@ export interface NodeRenderProps<isVideoMode?: boolean;isPlaying?: boolean;excludeTextures?: GPUTexture[];+ /**+ * Render only to record the 3D scene's motion (shutter motion blur reads+ * every draw one frame earlier); nothing drawn is shown.+ */+ motionHistoryOnly?: boolean;/** Signal values that override the node's own (text animators read them). */signals?: Record<string, unknown>;renderChild?: (diff --git a/packages/webgpu-renderers/src/renderer3d/fracture-geometry.test.ts b/packages/webgpu-renderers/src/renderer3d/fracture-geometry.test.tsnew file mode 100644index 00000000..91428104--- /dev/null+++ b/packages/webgpu-renderers/src/renderer3d/fracture-geometry.test.ts@@ -0,0 +1,155 @@+import { describe, expect, it } from "vitest";+import type { Mesh3DData, Model3DData } from "../loaders/types.js";+import type { Vec3 } from "../math3d/vector3.js";+import {+ FRACTURE_INTERIOR_MATERIAL,+ fractureModel,+} from "./fracture-geometry.js";+import { generatePrimitiveGeometry } from "./primitive-geometry.js";++/** Each piece's triangles (surface and cut faces), by joint. */+function pieceTriangles(model: Model3DData): Map<number, Vec3[][]> {+ const out = new Map<number, Vec3[][]>();+ for (const mesh of model.meshes) {+ const p = mesh.positions;+ const at = (i: number): Vec3 => [p[i * 3]!, p[i * 3 + 1]!, p[i * 3 + 2]!];+ for (let t = 0; t < mesh.indices.length; t += 3) {+ const i0 = mesh.indices[t]!;+ const joint = mesh.jointIndices![i0 * 4]!;+ const tri = [at(i0), at(mesh.indices[t + 1]!), at(mesh.indices[t + 2]!)];+ const list = out.get(joint);+ if (list) list.push(tri);+ else out.set(joint, [tri]);+ }+ }+ return out;+}++/**+ * How far the surface is from closed: a closed, consistently wound surface+ * encloses the same signed volume measured from any origin (T-junctions and+ * zero-area slivers along a seam do not open it). Relative to the volume.+ */+function leak(tris: Vec3[][]): number {+ const v0 = volume(tris);+ const o: Vec3 = [137, -211, 89];+ const shifted = tris.map((t) =>+ t.map((p) => p.map((x, k) => x - o[k]!) as Vec3),+ );+ return Math.abs(volume(shifted) - v0) / Math.max(1e-9, Math.abs(v0));+}++function volume(tris: Vec3[][]): number {+ let v = 0;+ for (const [a, b, c] of tris as [Vec3, Vec3, Vec3][]) {+ v +=+ (a[0] * (b[1] * c[2] - b[2] * c[1]) ++ a[1] * (b[2] * c[0] - b[0] * c[2]) ++ a[2] * (b[0] * c[1] - b[1] * c[0])) /+ 6;+ }+ return v;+}++const box = () =>+ generatePrimitiveGeometry({+ type: "roundedBox",+ width: 200,+ height: 120,+ depth: 80,+ radius: 0,+ color: "#3366cc",+ });++describe("fractureModel", () => {+ it("splits a solid into closed pieces that fill it exactly", () => {+ const { model, cells } = fractureModel(box(), { cells: 24, seed: 3 });+ expect(cells.length).toBeGreaterThan(16);+ expect(cells.length).toBeLessThanOrEqual(24);+ const pieces = pieceTriangles(model);+ expect(pieces.size).toBe(cells.length);+ let total = 0;+ for (const [joint, tris] of pieces) {+ expect(leak(tris)).toBeLessThan(1e-6);+ const v = volume(tris);+ expect(v).toBeGreaterThan(0);+ // Float32 positions against the double-precision measure.+ expect(Math.abs(v / cells[joint]!.volume - 1)).toBeLessThan(1e-5);+ total += v;+ }+ expect(total).toBeCloseTo(200 * 120 * 80, 0);+ // Cut faces carry the interior material; the outside keeps the source's.+ const names = model.meshes.map((m) => m.materialName);+ expect(names).toContain(FRACTURE_INTERIOR_MATERIAL);+ expect(model.skins?.[0]?.joints.length).toBe(cells.length);+ });++ it("is deterministic and crowds pieces around the impact point", () => {+ const a = fractureModel(box(), {+ cells: 32,+ seed: 9,+ impactPoint: [90, 0, 0],+ });+ const b = fractureModel(box(), {+ cells: 32,+ seed: 9,+ impactPoint: [90, 0, 0],+ });+ expect(a.cells.map((c) => c.centroid)).toEqual(+ b.cells.map((c) => c.centroid),+ );+ const near = a.cells.filter((c) => c.centroid[0] > 50);+ const far = a.cells.filter((c) => c.centroid[0] < -50);+ expect(near.length).toBeGreaterThan(far.length * 2);+ const avg = (cs: typeof near) =>+ cs.reduce((s, c) => s + c.volume, 0) / Math.max(1, cs.length);+ expect(avg(near)).toBeLessThan(avg(far));+ });++ it("closes cuts through non-convex solids, holes included", () => {+ const torus = generatePrimitiveGeometry({+ type: "torus",+ radius: 80,+ tube: 26,+ radialSegments: 24,+ tubularSegments: 48,+ });+ const { model, cells } = fractureModel(torus, { cells: 12, seed: 5 });+ const pieces = pieceTriangles(model);+ let total = 0;+ for (const tris of pieces.values()) {+ expect(leak(tris)).toBeLessThan(1e-6);+ total += volume(tris);+ }+ expect(cells.length).toBeGreaterThan(6);+ // The tessellated torus's own volume.+ const src = torus.meshes[0] as Mesh3DData;+ const whole = pieceTriangles({+ ...torus,+ meshes: [+ {+ ...src,+ jointIndices: new Float32Array((src.positions.length / 3) * 4),+ },+ ],+ }).get(0)!;+ expect(total).toBeCloseTo(volume(whole), -1);+ });++ it("keeps hull points around each centroid", () => {+ const { cells } = fractureModel(box(), { cells: 8, seed: 2 });+ for (const c of cells) {+ expect(c.hull.length % 3).toBe(0);+ expect(c.hull.length).toBeGreaterThanOrEqual(12);+ let mean = [0, 0, 0];+ for (let i = 0; i < c.hull.length; i += 3)+ mean = mean.map((m, k) => m + c.hull[i + k]!);+ // The centroid sits inside its piece: hull points surround it.+ for (let k = 0; k < 3; k++) {+ const vals = c.hull.filter((_, i) => i % 3 === k);+ expect(Math.min(...vals)).toBeLessThan(0);+ expect(Math.max(...vals)).toBeGreaterThan(0);+ }+ }+ });+});diff --git a/packages/webgpu-renderers/src/renderer3d/fracture-geometry.ts b/packages/webgpu-renderers/src/renderer3d/fracture-geometry.tsnew file mode 100644index 00000000..d22a5beb--- /dev/null+++ b/packages/webgpu-renderers/src/renderer3d/fracture-geometry.ts@@ -0,0 +1,974 @@+/**+ * Deterministic Voronoi fracture of a mesh into convex-cell pieces.+ *+ * Seeds are scattered inside the solid (denser around an impact point);+ * each seed's Voronoi cell is the box clipped by the bisector planes of its+ * neighbors (exact: neighbors are taken nearest first until none can cut).+ * The source triangles are then clipped by each cell's planes, and every+ * cut is closed with a cap: the cut segments are chained into loops on the+ * plane and triangulated, holes included, so pieces of a watertight source+ * are watertight too. Cut points are computed from canonically ordered+ * edge endpoints, so neighbors produce bit-identical vertices and loops+ * chain by exact position.+ *+ * The result is one model whose vertices are rigidly skinned to one joint+ * per piece: posing the joints moves the pieces, all in one draw per+ * material. At rest every joint is the identity and the model looks intact.+ */+import earcut from "earcut";+import { poseNodes } from "../loaders/pose.js";+import type {+ Material3D,+ Mesh3DData,+ Model3DData,+ ModelNode3D,+} from "../loaders/types.js";+import { type Mat4, Matrix4Math } from "../math3d/matrix4.js";+import { createRandom } from "../math3d/noise.js";+import type { Vec3 } from "../math3d/vector3.js";+import { parseHexOrRgbColor } from "./text-extruder.js";++export interface FractureOptions {+ /** Voronoi cells (2..256). Default 48. */+ cells?: number;+ seed?: number;+ /** Object-space point the cells crowd around (smaller pieces there). */+ impactPoint?: Vec3;+ /** Color of the newly exposed faces. Default "#d8d2c4". */+ interiorColor?: string;+ /** Roughness of the newly exposed faces. Default 0.9. */+ interiorRoughness?: number;+}++export interface FractureCell {+ /** Center of mass at rest, object space. */+ centroid: Vec3;+ volume: number;+ /** Hull points around the centroid, flat xyz (at most 256). */+ hull: number[];+}++export interface FracturedModel {+ /** One joint per cell (`nodes[i]` sits at `cells[i].centroid`). */+ model: Model3DData;+ cells: FractureCell[];+}++/** Name of the material on cut faces. */+export const FRACTURE_INTERIOR_MATERIAL = "fracture-interior";++type Rgba = [number, number, number, number];++interface FVertex {+ p: Vec3;+ n: Vec3;+ uv: [number, number];+ c: Rgba;+}++interface FPoly {+ v: FVertex[];+ /** Source mesh index, or -1 for cut faces. */+ group: number;+}++interface Plane {+ n: Vec3;+ d: number;+ /** The neighbor seed this bisector separates from (cell planes only). */+ other?: number;+}++/**+ * Makes points within `tol` of each other one point: a cut through a+ * collinear junction meets the same spot from different edges, and the+ * cap's loops chain by exact position.+ */+class PointWelder {+ private readonly grid = new Map<number, Vec3[]>();+ constructor(private readonly tol: number) {}++ private static hash(x: number, y: number, z: number): number {+ return (+ (Math.imul(x, 73856093) ^+ Math.imul(y, 19349663) ^+ Math.imul(z, 83492791)) |+ 0+ );+ }++ weld(p: Vec3): Vec3 {+ const t = this.tol;+ const f = [p[0] / t, p[1] / t, p[2] / t];+ const c = f.map(Math.floor) as Vec3;+ // A point within `tol` lies in its own grid cell or the nearer neighbor on each axis.+ const step = f.map((v, k) => (v - c[k]! < 0.5 ? -1 : 1));+ for (let m = 0; m < 8; m++) {+ const x = c[0] + (m & 1 ? step[0]! : 0);+ const y = c[1] + (m & 2 ? step[1]! : 0);+ const z = c[2] + (m & 4 ? step[2]! : 0);+ const hit = this.grid+ .get(PointWelder.hash(x, y, z))+ ?.find(+ (q) =>+ Math.abs(q[0] - p[0]) <= t &&+ Math.abs(q[1] - p[1]) <= t &&+ Math.abs(q[2] - p[2]) <= t,+ );+ if (hit) return hit;+ }+ const k = PointWelder.hash(c[0], c[1], c[2]);+ const list = this.grid.get(k);+ if (list) list.push(p);+ else this.grid.set(k, [p]);+ return p;+ }+}++/** Clip tolerances: what counts as on a plane, and the point welder. */+interface ClipContext {+ eps: number;+ welder: PointWelder;+}++const dot = (a: Vec3, b: Vec3) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];+const sub = (a: Vec3, b: Vec3): Vec3 => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];+const cross = (a: Vec3, b: Vec3): Vec3 => [+ a[1] * b[2] - a[2] * b[1],+ a[2] * b[0] - a[0] * b[2],+ a[0] * b[1] - a[1] * b[0],+];+const normalize = (v: Vec3): Vec3 => {+ const l = Math.hypot(v[0], v[1], v[2]) || 1;+ return [v[0] / l, v[1] / l, v[2] / l];+};+const key = (p: Vec3) => `${p[0]},${p[1]},${p[2]}`;+const lexLess = (a: Vec3, b: Vec3) =>+ a[0] !== b[0] ? a[0] < b[0] : a[1] !== b[1] ? a[1] < b[1] : a[2] < b[2];++// --- Source triangles -------------------------------------------------------++function transformPoint(m: Mat4, p: Vec3): Vec3 {+ return [+ m[0] * p[0] + m[4] * p[1] + m[8] * p[2] + m[12],+ m[1] * p[0] + m[5] * p[1] + m[9] * p[2] + m[13],+ m[2] * p[0] + m[6] * p[1] + m[10] * p[2] + m[14],+ ];+}++function transformNormal(m: Mat4, n: Vec3): Vec3 {+ const inv = Matrix4Math.invert(m) ?? Matrix4Math.identity();+ // Inverse transpose, upper 3x3.+ return normalize([+ inv[0] * n[0] + inv[1] * n[1] + inv[2] * n[2],+ inv[4] * n[0] + inv[5] * n[1] + inv[6] * n[2],+ inv[8] * n[0] + inv[9] * n[1] + inv[10] * n[2],+ ]);+}++/** Each triangle mesh's rest placement in object space (root transform included). */+function restPlacements(model: Model3DData): Mat4[] {+ const root = model.rootTransform ?? Matrix4Math.identity();+ const world = model.nodes ? poseNodes(model, undefined, 0) : [];+ return model.meshes.map((m) =>+ m.skin === undefined && m.node !== undefined && world[m.node]+ ? Matrix4Math.multiply(root, world[m.node]!)+ : root,+ );+}++/** Source triangles in object space, welded: equal positions (to `tol`) become identical. */+function sourcePolys(model: Model3DData, welder: PointWelder): FPoly[] {+ const placements = restPlacements(model);+ const weld = (p: Vec3) => welder.weld(p);+ const polys: FPoly[] = [];+ model.meshes.forEach((mesh, group) => {+ if (mesh.topology && mesh.topology !== "triangle-list") return;+ const m = placements[group]!;+ const vertex = (i: number): FVertex => {+ const pos = mesh.positions;+ const nor = mesh.normals;+ const p = transformPoint(m, [+ pos[i * 3]!,+ pos[i * 3 + 1]!,+ pos[i * 3 + 2]!,+ ]);+ return {+ p: weld(p),+ n: nor.length+ ? transformNormal(m, [nor[i * 3]!, nor[i * 3 + 1]!, nor[i * 3 + 2]!])+ : [0, -1, 0],+ uv: mesh.uvs.length ? [mesh.uvs[i * 2]!, mesh.uvs[i * 2 + 1]!] : [0, 0],+ c: mesh.colors+ ? [+ mesh.colors[i * 4]!,+ mesh.colors[i * 4 + 1]!,+ mesh.colors[i * 4 + 2]!,+ mesh.colors[i * 4 + 3]!,+ ]+ : [1, 1, 1, 1],+ };+ };+ const idx = mesh.indices;+ for (let t = 0; t + 2 < idx.length; t += 3) {+ const v = [vertex(idx[t]!), vertex(idx[t + 1]!), vertex(idx[t + 2]!)];+ if (key(v[0]!.p) === key(v[1]!.p) || key(v[1]!.p) === key(v[2]!.p))+ continue;+ if (key(v[0]!.p) === key(v[2]!.p)) continue;+ polys.push({ v, group });+ }+ });+ return polys;+}++/** Every edge shared by exactly two triangles, consistently. */+function isWatertight(polys: FPoly[]): boolean {+ const count = new Map<string, number>();+ for (const poly of polys) {+ const n = poly.v.length;+ for (let i = 0; i < n; i++) {+ const a = key(poly.v[i]!.p);+ const b = key(poly.v[(i + 1) % n]!.p);+ const k = a < b ? `${a}|${b}` : `${b}|${a}`;+ count.set(k, (count.get(k) ?? 0) + 1);+ }+ }+ for (const c of count.values()) if (c !== 2) return false;+ return count.size > 0;+}++/** Ray parity: whether `p` is inside the closed triangle soup. */+function inside(polys: FPoly[], p: Vec3): boolean {+ // An irrational-ish direction misses edges and vertices in practice.+ const dir: Vec3 = normalize([0.5773, 0.6123, 0.5401]);+ let hits = 0;+ for (const poly of polys) {+ const [a, b, c] = poly.v as [FVertex, FVertex, FVertex];+ const e1 = sub(b.p, a.p);+ const e2 = sub(c.p, a.p);+ const h = cross(dir, e2);+ const det = dot(e1, h);+ if (Math.abs(det) < 1e-12) continue;+ const f = 1 / det;+ const s = sub(p, a.p);+ const u = f * dot(s, h);+ if (u < 0 || u > 1) continue;+ const q = cross(s, e1);+ const v = f * dot(dir, q);+ if (v < 0 || u + v > 1) continue;+ if (f * dot(e2, q) > 0) hits++;+ }+ return hits % 2 === 1;+}++// --- Clipping and capping ----------------------------------------------------++/** The point where edge (a, b) meets the plane, from canonically ordered endpoints. */+function cut(+ a: FVertex,+ b: FVertex,+ plane: Plane,+ welder: PointWelder,+): FVertex {+ const [x, y] = lexLess(a.p, b.p) ? [a, b] : [b, a];+ const dx = dot(plane.n, x.p) - plane.d;+ const dy = dot(plane.n, y.p) - plane.d;+ const t = dx / (dx - dy);+ const mix = (u: number, w: number) => u + (w - u) * t;+ return {+ p: welder.weld([+ mix(x.p[0], y.p[0]),+ mix(x.p[1], y.p[1]),+ mix(x.p[2], y.p[2]),+ ]),+ n: normalize([+ mix(x.n[0], y.n[0]),+ mix(x.n[1], y.n[1]),+ mix(x.n[2], y.n[2]),+ ]),+ uv: [mix(x.uv[0], y.uv[0]), mix(x.uv[1], y.uv[1])],+ c: [+ mix(x.c[0], y.c[0]),+ mix(x.c[1], y.c[1]),+ mix(x.c[2], y.c[2]),+ mix(x.c[3], y.c[3]),+ ],+ };+}++class Segments {+ private readonly edges = new Map<string, [FVertex, FVertex]>();++ /** Adds a→b; a pending b→a cancels instead (an edge between two kept faces). */+ add(a: FVertex, b: FVertex): void {+ const ka = key(a.p);+ const kb = key(b.p);+ const reverse = `${kb}|${ka}`;+ if (this.edges.delete(reverse)) return;+ this.edges.set(`${ka}|${kb}`, [a, b]);+ }++ /** Closed loops of points, following a→b. */+ loops(): FVertex[][] {+ const from = new Map<string, [FVertex, FVertex][]>();+ for (const seg of this.edges.values()) {+ const k = key(seg[0].p);+ const list = from.get(k);+ if (list) list.push(seg);+ else from.set(k, [seg]);+ }+ const out: FVertex[][] = [];+ for (const [start, list] of from) {+ while (list.length) {+ const loop = this.walk(start, list.pop()!, from);+ if (loop && loop.length >= 3) out.push(loop);+ }+ }+ return out;+ }++ private walk(+ start: string,+ first: [FVertex, FVertex],+ from: Map<string, [FVertex, FVertex][]>,+ ): FVertex[] | undefined {+ const loop: FVertex[] = [first[0]];+ let at = first[1];+ for (let guard = 0; guard < 1_000_000; guard++) {+ const k = key(at.p);+ if (k === start) return loop;+ loop.push(at);+ const next = from.get(k)?.pop();+ if (!next) return undefined;+ at = next[1];+ }+ return undefined;+ }+}++/**+ * Keeps the part of each polygon with n·p ≤ d and returns the cut's boundary+ * segments, oriented so the cap they bound faces +n.+ */+function clipPolys(+ polys: FPoly[],+ plane: Plane,+ ctx: ClipContext,+): { kept: FPoly[]; segments: Segments } {+ const { eps } = ctx;+ const kept: FPoly[] = [];+ const segments = new Segments();+ for (const poly of polys) {+ const dist = poly.v.map((v) => {+ const s = dot(plane.n, v.p) - plane.d;+ return Math.abs(s) <= eps ? 0 : s;+ });+ if (dist.every((s) => s > 0)) continue;+ if (dist.every((s) => s <= 0)) {+ kept.push(poly);+ if (dist.every((s) => s === 0)) continue;+ boundaryOf(poly.v, dist, segments);+ continue;+ }+ const out: FVertex[] = [];+ const on: boolean[] = [];+ const n = poly.v.length;+ for (let i = 0; i < n; i++) {+ const a = poly.v[i]!;+ const b = poly.v[(i + 1) % n]!;+ const da = dist[i]!;+ const db = dist[(i + 1) % n]!;+ if (da <= 0) {+ out.push(a);+ on.push(da === 0);+ }+ if ((da < 0 && db > 0) || (da > 0 && db < 0)) {+ out.push(cut(a, b, plane, ctx.welder));+ on.push(true);+ }+ }+ if (out.length < 3) continue;+ kept.push({ v: out, group: poly.group });+ boundaryOf(+ out,+ on.map((o) => (o ? 0 : -1)),+ segments,+ );+ }+ return { kept, segments };+}++/** Polygon edges lying on the plane, reversed (the cap runs the other way). */+function boundaryOf(v: FVertex[], dist: number[], segments: Segments): void {+ const n = v.length;+ for (let i = 0; i < n; i++) {+ if (dist[i] === 0 && dist[(i + 1) % n] === 0) {+ segments.add(v[(i + 1) % n]!, v[i]!);+ }+ }+}++/** An orthonormal basis (u, v) of the plane with u × v = n. */+function planeBasis(n: Vec3): [Vec3, Vec3] {+ const helper: Vec3 = Math.abs(n[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0];+ const u = normalize(cross(helper, n));+ return [u, cross(n, u)];+}++const signedArea = (pts: [number, number][]) => {+ let a = 0;+ for (let i = 0; i < pts.length; i++) {+ const p = pts[i]!;+ const q = pts[(i + 1) % pts.length]!;+ a += p[0] * q[1] - q[0] * p[1];+ }+ return a / 2;+};++function pointInPolygon(+ p: [number, number],+ poly: [number, number][],+): boolean {+ let c = false;+ for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) {+ const a = poly[i]!;+ const b = poly[j]!;+ if (+ a[1] > p[1] !== b[1] > p[1] &&+ p[0] < ((b[0] - a[0]) * (p[1] - a[1])) / (b[1] - a[1]) + a[0]+ )+ c = !c;+ }+ return c;+}++/**+ * earcut drops collinear boundary points, but the faces around the cap+ * still end there: split the cap triangle whose edge passes through each+ * dropped point, so the cap meets its neighbors vertex to vertex.+ */+function restoreCollinear(tris: number[], coords: number[]): number[] {+ const n = coords.length / 2;+ const used = new Set(tris);+ const out = tris.slice();+ const x = (i: number) => coords[i * 2]!;+ const y = (i: number) => coords[i * 2 + 1]!;+ for (let m = 0; m < n; m++) {+ if (used.has(m)) continue;+ for (let t = 0; t + 2 < out.length; t += 3) {+ const e = [0, 1, 2].find((k) =>+ onSegment(m, out[t + k]!, out[t + ((k + 1) % 3)]!, x, y),+ );+ if (e === undefined) continue;+ const a = out[t + e]!;+ const b = out[t + ((e + 1) % 3)]!;+ const c = out[t + ((e + 2) % 3)]!;+ out.splice(t, 3, a, m, c);+ out.push(m, b, c);+ used.add(m);+ break;+ }+ }+ return out;+}++function onSegment(+ m: number,+ a: number,+ b: number,+ x: (i: number) => number,+ y: (i: number) => number,+): boolean {+ const abx = x(b) - x(a);+ const aby = y(b) - y(a);+ const len2 = abx * abx + aby * aby;+ if (len2 === 0) return false;+ const t = ((x(m) - x(a)) * abx + (y(m) - y(a)) * aby) / len2;+ if (t <= 0 || t >= 1) return false;+ const crossz = (x(m) - x(a)) * aby - (y(m) - y(a)) * abx;+ return Math.abs(crossz) <= 1e-7 * len2;+}++/** Triangulates the loops of a cut (outer loops counter-clockwise about n, holes clockwise). */+function capPolys(loops: FVertex[][], plane: Plane, uvScale: number): FPoly[] {+ const [u, v] = planeBasis(plane.n);+ const flat = loops.map((loop) =>+ loop.map((x) => [dot(x.p, u), dot(x.p, v)] as [number, number]),+ );+ const areas = flat.map(signedArea);+ const outers = loops.map((_, i) => i).filter((i) => areas[i]! > 0);+ const holesOf = new Map<number, number[]>(outers.map((i) => [i, []]));+ for (let h = 0; h < loops.length; h++) {+ if (areas[h]! >= 0) continue;+ // The smallest outer loop around the hole holds it.+ const owner = outers+ .filter((o) => pointInPolygon(flat[h]![0]!, flat[o]!))+ .sort((a, b) => areas[a]! - areas[b]!)[0];+ if (owner !== undefined) holesOf.get(owner)!.push(h);+ }+ const out: FPoly[] = [];+ const vertexAt = (x: FVertex): FVertex => ({+ p: x.p,+ n: plane.n,+ uv: [dot(x.p, u) / uvScale, dot(x.p, v) / uvScale],+ c: [1, 1, 1, 1],+ });+ for (const o of outers) {+ const ring = [o, ...holesOf.get(o)!];+ const coords: number[] = [];+ const holeStarts: number[] = [];+ const verts: FVertex[] = [];+ for (const r of ring) {+ if (r !== o) holeStarts.push(verts.length);+ for (let k = 0; k < loops[r]!.length; k++) {+ coords.push(...flat[r]![k]!);+ verts.push(loops[r]![k]!);+ }+ }+ const tris = restoreCollinear(+ earcut(coords, holeStarts.length ? holeStarts : undefined, 2),+ coords,+ );+ for (let t = 0; t + 2 < tris.length; t += 3) {+ let a = verts[tris[t]!]!;+ let b = verts[tris[t + 1]!]!;+ const c = verts[tris[t + 2]!]!;+ if (dot(cross(sub(b.p, a.p), sub(c.p, a.p)), plane.n) < 0)+ [a, b] = [b, a];+ out.push({ v: [vertexAt(a), vertexAt(b), vertexAt(c)], group: -1 });+ }+ }+ return out;+}++/** Clips a closed soup by a plane and closes the cut. */+function clipAndCap(+ polys: FPoly[],+ plane: Plane,+ ctx: ClipContext,+ uvScale: number,+): FPoly[] {+ const { kept, segments } = clipPolys(polys, plane, ctx);+ return kept.concat(capPolys(segments.loops(), plane, uvScale));+}++// --- Voronoi cells -----------------------------------------------------------++function boxPolys(min: Vec3, max: Vec3): FPoly[] {+ const c = (x: number, y: number, z: number): FVertex => ({+ p: [x ? max[0] : min[0], y ? max[1] : min[1], z ? max[2] : min[2]],+ n: [0, 0, 0],+ uv: [0, 0],+ c: [1, 1, 1, 1],+ });+ // Outward winding: cross(b - a, c - a) points out.+ const quads = [+ [c(0, 0, 0), c(0, 1, 0), c(1, 1, 0), c(1, 0, 0)],+ [c(0, 0, 1), c(1, 0, 1), c(1, 1, 1), c(0, 1, 1)],+ [c(0, 0, 0), c(0, 0, 1), c(0, 1, 1), c(0, 1, 0)],+ [c(1, 0, 0), c(1, 1, 0), c(1, 1, 1), c(1, 0, 1)],+ [c(0, 0, 0), c(1, 0, 0), c(1, 0, 1), c(0, 0, 1)],+ [c(0, 1, 0), c(0, 1, 1), c(1, 1, 1), c(1, 1, 0)],+ ];+ return quads.map((v) => ({ v, group: -1 }));+}++/** The planes that bound seed i's Voronoi cell inside the box. */+function cellPlanes(+ seeds: Vec3[],+ i: number,+ min: Vec3,+ max: Vec3,+ eps: number,+): { planes: Plane[]; min: Vec3; max: Vec3 } {+ const s = seeds[i]!;+ const ctx: ClipContext = { eps, welder: new PointWelder(eps * 4) };+ let cell = boxPolys(min, max);+ const planes: Plane[] = [];+ const order = seeds+ .map((p, j) => ({ j, d: Math.hypot(...sub(p, s)) }))+ .filter((o) => o.j !== i && o.d > 0)+ .sort((a, b) => a.d - b.d || a.j - b.j);+ for (const { j, d } of order) {+ let reach = 0;+ for (const poly of cell)+ for (const v of poly.v)+ reach = Math.max(reach, Math.hypot(...sub(v.p, s)));+ // No farther seed's bisector can reach the cell.+ if (d / 2 > reach) break;+ const p = seeds[j]!;+ const n = normalize(sub(p, s));+ const plane: Plane = {+ n,+ d: dot(n, [(p[0] + s[0]) / 2, (p[1] + s[1]) / 2, (p[2] + s[2]) / 2]),+ other: j,+ };+ const cuts = cell.some((poly) =>+ poly.v.some((v) => dot(n, v.p) - plane.d > eps),+ );+ if (!cuts) continue;+ cell = clipAndCap(cell, plane, ctx, 1);+ planes.push(plane);+ }+ const lo: Vec3 = [Infinity, Infinity, Infinity];+ const hi: Vec3 = [-Infinity, -Infinity, -Infinity];+ for (const poly of cell)+ for (const v of poly.v)+ for (let k = 0; k < 3; k++) {+ lo[k] = Math.min(lo[k]!, v.p[k]!);+ hi[k] = Math.max(hi[k]!, v.p[k]!);+ }+ return { planes, min: lo, max: hi };+}++function gaussian(rand: () => number): number {+ const u = Math.max(1e-12, rand());+ return Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * rand());+}++function scatterSeeds(+ polys: FPoly[],+ min: Vec3,+ max: Vec3,+ options: FractureOptions,+ solid: boolean,+): Vec3[] {+ const count = Math.max(2, Math.min(256, Math.round(options.cells ?? 48)));+ const rand = createRandom((options.seed ?? 1) * 92821 + 17);+ const size = sub(max, min);+ const sigma = 0.18 * Math.max(...size);+ const seeds: Vec3[] = [];+ const impact = options.impactPoint;+ for (+ let attempt = 0;+ seeds.length < count && attempt < count * 60;+ attempt+++ ) {+ const near = impact && rand() < 0.6;+ const p: Vec3 = near+ ? [+ impact[0] + gaussian(rand) * sigma,+ impact[1] + gaussian(rand) * sigma,+ impact[2] + gaussian(rand) * sigma,+ ]+ : [+ min[0] + rand() * size[0],+ min[1] + rand() * size[1],+ min[2] + rand() * size[2],+ ];+ if (p.some((v, k) => v < min[k]! || v > max[k]!)) continue;+ if (solid && !inside(polys, p)) continue;+ seeds.push(p);+ }+ return seeds;+}++/** Keeps the part of the polygons inside every plane (no caps). */+function clipInside(+ polys: FPoly[],+ planes: Plane[],+ ctx: ClipContext,+): FPoly[] {+ let out = polys;+ for (const plane of planes) {+ if (!out.length) break;+ out = clipPolys(out, plane, ctx).kept;+ }+ return out;+}++/**+ * One cell's piece: the surface inside the cell, plus one face per cell+ * plane, the solid's whole cross-section on that plane (so its loops close+ * and holes nest) clipped to the cell's other planes.+ */+function cellPiece(+ polys: FPoly[],+ cell: { planes: Plane[]; min: Vec3; max: Vec3 },+ ctx: ClipContext,+ pad: number,+ uvScale: number,+ section: (plane: Plane) => FVertex[][],+): FPoly[] {+ const near = polys.filter((poly) =>+ [0, 1, 2].every(+ (k) =>+ poly.v.some((v) => v.p[k]! >= cell.min[k]! - pad) &&+ poly.v.some((v) => v.p[k]! <= cell.max[k]! + pad),+ ),+ );+ const piece = clipInside(near, cell.planes, ctx);+ cell.planes.forEach((plane, j) => {+ const loops = section(plane);+ if (!loops.length) return;+ const others = cell.planes.filter((_, k) => k !== j);+ piece.push(...clipInside(capPolys(loops, plane, uvScale), others, ctx));+ });+ return piece;+}++// --- Assembly ----------------------------------------------------------------++/** Volume and center of mass of a closed, outward-wound soup. */+function massProperties(polys: FPoly[]): { volume: number; centroid: Vec3 } {+ let volume = 0;+ const c: Vec3 = [0, 0, 0];+ const avg: Vec3 = [0, 0, 0];+ let count = 0;+ for (const poly of polys) {+ const a = poly.v[0]!.p;+ for (let k = 1; k + 1 < poly.v.length; k++) {+ const b = poly.v[k]!.p;+ const d = poly.v[k + 1]!.p;+ const v = dot(a, cross(b, d)) / 6;+ volume += v;+ for (let i = 0; i < 3; i++) c[i]! += ((a[i]! + b[i]! + d[i]!) / 4) * v;+ }+ for (const x of poly.v) {+ for (let i = 0; i < 3; i++) avg[i]! += x.p[i];+ count++;+ }+ }+ if (Math.abs(volume) > 1e-9) {+ return {+ volume: Math.abs(volume),+ centroid: c.map((x) => x / volume) as Vec3,+ };+ }+ return {+ volume: 0,+ centroid: avg.map((x) => x / Math.max(1, count)) as Vec3,+ };+}++function hullPoints(polys: FPoly[], centroid: Vec3): number[] {+ const seen = new Map<string, Vec3>();+ for (const poly of polys) for (const v of poly.v) seen.set(key(v.p), v.p);+ const pts = [...seen.values()];+ const stride = Math.max(1, Math.ceil(pts.length / 256));+ const out: number[] = [];+ for (let i = 0; i < pts.length; i += stride) {+ out.push(...sub(pts[i]!, centroid));+ }+ return out;+}++class MeshAccumulator {+ positions: number[] = [];+ normals: number[] = [];+ uvs: number[] = [];+ colors: number[] = [];+ joints: number[] = [];+ indices: number[] = [];++ add(poly: FPoly, joint: number): void {+ const base = this.positions.length / 3;+ for (const v of poly.v) {+ this.positions.push(...v.p);+ this.normals.push(...v.n);+ this.uvs.push(...v.uv);+ this.colors.push(...v.c);+ this.joints.push(joint, 0, 0, 0);+ }+ for (let k = 1; k + 1 < poly.v.length; k++) {+ this.indices.push(base, base + k, base + k + 1);+ }+ }++ build(+ name: string,+ materialName: string | undefined,+ colors: boolean,+ ): Mesh3DData {+ const n = this.positions.length / 3;+ const weights = new Float32Array(n * 4);+ for (let i = 0; i < n; i++) weights[i * 4] = 1;+ return {+ name,+ positions: new Float32Array(this.positions),+ normals: new Float32Array(this.normals),+ uvs: new Float32Array(this.uvs),+ ...(colors && { colors: new Float32Array(this.colors) }),+ indices: new Uint32Array(this.indices),+ jointIndices: new Float32Array(this.joints),+ jointWeights: weights,+ materialName,+ skin: 0,+ };+ }+}++function bounds(meshes: Mesh3DData[]): Model3DData["bounds"] {+ const min: Vec3 = [Infinity, Infinity, Infinity];+ const max: Vec3 = [-Infinity, -Infinity, -Infinity];+ for (const m of meshes)+ for (let i = 0; i < m.positions.length; i += 3)+ for (let k = 0; k < 3; k++) {+ min[k] = Math.min(min[k]!, m.positions[i + k]!);+ max[k] = Math.max(max[k]!, m.positions[i + k]!);+ }+ if (!Number.isFinite(min[0])) {+ min.fill(0);+ max.fill(0);+ }+ const size = sub(max, min);+ return {+ min,+ max,+ center: [+ (min[0] + max[0]) / 2,+ (min[1] + max[1]) / 2,+ (min[2] + max[2]) / 2,+ ],+ size,+ boundingSphereRadius: Math.hypot(...size) / 2,+ };+}++function assemble(+ source: Model3DData,+ pieces: { polys: FPoly[]; centroid: Vec3 }[],+ options: FractureOptions,+): Model3DData {+ const groups = new Map<number, MeshAccumulator>();+ pieces.forEach((piece, joint) => {+ for (const poly of piece.polys) {+ let acc = groups.get(poly.group);+ if (!acc) {+ acc = new MeshAccumulator();+ groups.set(poly.group, acc);+ }+ acc.add(poly, joint);+ }+ });+ const materials: Record<string, Material3D> = { ...source.materials };+ const [r, g, b] = parseHexOrRgbColor(options.interiorColor ?? "#d8d2c4");+ materials[FRACTURE_INTERIOR_MATERIAL] = {+ name: FRACTURE_INTERIOR_MATERIAL,+ diffuseColor: [r, g, b, 1],+ roughness: options.interiorRoughness ?? 0.9,+ metallic: 0,+ twoSided: true,+ };+ const meshes: Mesh3DData[] = [...groups.entries()]+ .sort((a, b) => a[0] - b[0])+ .map(([group, acc]) => {+ if (group < 0)+ return acc.build(+ "fracture-interior",+ FRACTURE_INTERIOR_MATERIAL,+ false,+ );+ const src = source.meshes[group]!;+ return acc.build(+ src.name ?? `fracture-${group}`,+ src.materialName,+ Boolean(src.colors),+ );+ });+ const nodes: ModelNode3D[] = pieces.map((p, i) => ({+ name: `piece-${i}`,+ parent: -1,+ translation: [...p.centroid],+ rotation: [0, 0, 0, 1],+ scale: [1, 1, 1],+ }));+ const ibm = new Float32Array(pieces.length * 16);+ pieces.forEach((p, i) => {+ ibm.set(+ Matrix4Math.translate(-p.centroid[0], -p.centroid[1], -p.centroid[2]),+ i * 16,+ );+ });+ return {+ name: `${source.name ?? "model"}-fractured`,+ meshes,+ materials,+ nodes,+ skins: [{ joints: nodes.map((_, i) => i), inverseBindMatrices: ibm }],+ animations: [],+ bounds: bounds(meshes),+ };+}++const cache = new WeakMap<Model3DData, Map<string, FracturedModel>>();++/**+ * Breaks a model into Voronoi pieces (cached per model and options). Pieces+ * smaller than a thousandth of the largest are dropped.+ */+export function fractureModel(+ model: Model3DData,+ options: FractureOptions = {},+): FracturedModel {+ const k = JSON.stringify([+ options.cells ?? 48,+ options.seed ?? 1,+ options.impactPoint ?? null,+ options.interiorColor ?? null,+ options.interiorRoughness ?? null,+ ]);+ let byKey = cache.get(model);+ if (!byKey) {+ byKey = new Map();+ cache.set(model, byKey);+ }+ const hit = byKey.get(k);+ if (hit) return hit;+ const result = buildFracture(model, options);+ byKey.set(k, result);+ return result;+}++function buildFracture(+ model: Model3DData,+ options: FractureOptions,+): FracturedModel {+ const extent = Math.max(1e-6, model.bounds.boundingSphereRadius * 2);+ const eps = extent * 1e-7;+ const ctx: ClipContext = { eps, welder: new PointWelder(extent * 1e-6) };+ const polys = sourcePolys(model, ctx.welder);+ const lo: Vec3 = [Infinity, Infinity, Infinity];+ const hi: Vec3 = [-Infinity, -Infinity, -Infinity];+ for (const poly of polys)+ for (const v of poly.v)+ for (let k = 0; k < 3; k++) {+ lo[k] = Math.min(lo[k]!, v.p[k]!);+ hi[k] = Math.max(hi[k]!, v.p[k]!);+ }+ if (!polys.length) return { model: assemble(model, [], options), cells: [] };+ const solid = isWatertight(polys);+ const seeds = scatterSeeds(polys, lo, hi, options, solid);+ const pad = extent * 0.01;+ const boxMin: Vec3 = [lo[0] - pad, lo[1] - pad, lo[2] - pad];+ const boxMax: Vec3 = [hi[0] + pad, hi[1] + pad, hi[2] + pad];+ // A bisector's cross-section serves both cells it separates, reversed.+ const sections = new Map<string, FVertex[][]>();+ const raw = seeds.map((_, i) => {+ const cell = cellPlanes(seeds, i, boxMin, boxMax, eps);+ const section = (plane: Plane): FVertex[][] => {+ const j = plane.other ?? -1;+ const mine = sections.get(`${i},${j}`);+ if (mine) return mine;+ const theirs = sections.get(`${j},${i}`);+ if (theirs) return theirs.map((loop) => loop.slice().reverse());+ const loops = clipPolys(polys, plane, ctx).segments.loops();+ sections.set(`${i},${j}`, loops);+ return loops;+ };+ return cellPiece(polys, cell, ctx, pad, extent / 4, section);+ });+ const measured = raw+ .filter((p) => p.length > 0)+ .map((p) => ({ polys: p, ...massProperties(p) }));+ const largest = Math.max(0, ...measured.map((m) => m.volume));+ const pieces = measured.filter((m) => !solid || m.volume > largest * 1e-3);+ return {+ model: assemble(model, pieces, options),+ cells: pieces.map((p) => ({+ centroid: p.centroid,+ volume: p.volume,+ hull: hullPoints(p.polys, p.centroid),+ })),+ };+}diff --git a/packages/webgpu-renderers/src/renderer3d/index.ts b/packages/webgpu-renderers/src/renderer3d/index.tsindex bb0ca9cb..402850a2 100644--- a/packages/webgpu-renderers/src/renderer3d/index.ts+++ b/packages/webgpu-renderers/src/renderer3d/index.ts@@ -1,6 +1,7 @@export * from "./audio-mesh-deform-pipeline.js";export * from "./bloom-pipeline.js";export * from "./floor-reflection-pipeline.js";+export * from "./fracture-geometry.js";export * from "./glass-pipeline.js";export * from "./hdr-environment.js";export * from "./matte3d.js";diff --git a/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts b/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.tsindex 7de0df52..ae111325 100644--- a/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts+++ b/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts@@ -1,4 +1,5 @@import { BufferPool } from "../renderer2d/buffer-pool.js";+import { meshVelocityWgsl } from "../shaders/mesh-velocity.js";import { mesh3dWgsl } from "../shaders/mesh3d.js";import { fullCoverageView, matteLayoutEntry } from "./matte3d.js";import {@@ -122,6 +123,25 @@ export interface MeshUniformData extends SurfaceParams {crowd?: MeshCrowd;}+/**+ * A mesh's state one frame earlier, for the velocity pass; unset fields+ * repeat this frame's (no motion from them).+ */+export type MeshMotionPrev = Pick<+ MeshUniformData,+ | "modelMatrix"+ | "normalMatrix"+ | "skinningMatrices"+ | "instanceBuffer"+ | "wind"+ | "crowd"+>;++/** Format of the velocity target: motion px (rg), linear depth (b), coverage (a). */+export const VELOCITY_FORMAT: GPUTextureFormat = "rgba16float";+/** Depth format of the velocity pass. */+export const VELOCITY_DEPTH_FORMAT: GPUTextureFormat = "depth24plus";+export interface GPUMeshBuffers {vertexBuffer: GPUBuffer;indexBuffer: GPUBuffer;@@ -206,6 +226,11 @@ export class Mesh3DPipeline {// Transform, tint, draw/material params, shade, shared surface block, maps.private modelData = new Float32Array(MESH_MODEL_FLOATS);+ private readonly vertexBuffers: GPUVertexBufferLayout[];+ /** Velocity-pass camera: this and the previous view-projection. */+ public readonly velocityCameraLayout: GPUBindGroupLayout;+ private velocityModule?: GPUShaderModule;+ private readonly velocityPipelines = new Map<string, GPURenderPipeline>();constructor(device: GPUDevice,@@ -326,6 +351,18 @@ export class Mesh3DPipeline {],};+ this.vertexBuffers = [...(vertexState.buffers as GPUVertexBufferLayout[])];+ this.velocityCameraLayout = device.createBindGroupLayout({+ label: "Mesh3DVelocityCameraLayout",+ entries: [+ {+ binding: 0,+ visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,+ buffer: { type: "uniform" },+ },+ ],+ });+const base: PipelineVariantBase = {label: "Mesh3DPipeline",layout: pipelineLayout,@@ -625,25 +662,7 @@ export class Mesh3DPipeline {...data,hasMapUvs: Boolean(meshBuffers.mapUvBuffer),});- const white = this.defaultWhiteTexture;- const maps = data.maps;- const textureBindGroup = this.device.createBindGroup({- layout: this.textureLayout,- entries: [- { binding: 0, resource: sampler },- { binding: 1, resource: (texture ?? white).createView() },- {- binding: 2,- resource: (maps?.normal ?? this.flatNormalTexture).createView(),- },- {- binding: 3,- resource: (maps?.metallicRoughness ?? white).createView(),- },- { binding: 4, resource: (maps?.occlusion ?? white).createView() },- { binding: 5, resource: (maps?.emissive ?? white).createView() },- ],- });+ const textureBindGroup = this.textureGroup(texture, sampler, data.maps);const wireframe =data.wireframe === true &&@@ -683,28 +702,153 @@ export class Mesh3DPipeline {pass.setBindGroup(1, modelBindGroup);pass.setBindGroup(2, textureBindGroup);pass.setBindGroup(3, lightsBindGroup);+ this.issue(+ pass,+ meshBuffers,+ wireframe,+ data,+ instanceCount,+ firstInstance,+ );+ }++ /**+ * Draws the mesh's screen motion since `prev` into a velocity pass+ * (`VELOCITY_FORMAT`): the vertex runs this frame's and the previous+ * frame's deformation, so skinning, instances, wind and crowds move it+ * too.+ */+ drawVelocity(+ pass: GPURenderPassEncoder,+ velocityCameraBindGroup: GPUBindGroup,+ meshBuffers: GPUMeshBuffers,+ texture: GPUTexture | undefined,+ sampler: GPUSampler,+ data: MeshUniformData,+ prev: MeshMotionPrev | undefined,+ instanceCount = 1,+ firstInstance = 0,+ ): void {+ const hasMapUvs = Boolean(meshBuffers.mapUvBuffer);+ const now = this.packModel({ ...data, hasMapUvs });+ const before = this.packModel({ ...data, ...prev, hasMapUvs });+ const wireframe =+ data.wireframe === true &&+ (!meshBuffers.topology || meshBuffers.topology === "triangle-list");+ if (wireframe && !meshBuffers.wireIndexBuffer) {+ throw new Error("Wireframe requires mesh buffers with edge indices");+ }+ const topology: GPUPrimitiveTopology =+ meshBuffers.topology === "point-list"+ ? "point-list"+ : wireframe || meshBuffers.topology === "line-list"+ ? "line-list"+ : "triangle-list";+ pass.setPipeline(this.velocityPipeline(topology));+ pass.setBindGroup(0, velocityCameraBindGroup);+ pass.setBindGroup(1, now);+ pass.setBindGroup(2, before);+ pass.setBindGroup(3, this.textureGroup(texture, sampler, undefined));+ this.issue(+ pass,+ meshBuffers,+ wireframe,+ data,+ instanceCount,+ firstInstance,+ );+ }++ private velocityPipeline(topology: GPUPrimitiveTopology): GPURenderPipeline {+ let pipeline = this.velocityPipelines.get(topology);+ if (pipeline) return pipeline;+ this.velocityModule ??= this.device.createShaderModule({+ label: "mesh-velocity.wgsl",+ code: meshVelocityWgsl,+ });+ pipeline = this.device.createRenderPipeline({+ label: `Mesh3DVelocity-${topology}`,+ layout: this.device.createPipelineLayout({+ bindGroupLayouts: [+ this.velocityCameraLayout,+ this.modelLayout,+ this.modelLayout,+ this.textureLayout,+ ],+ }),+ vertex: {+ module: this.velocityModule,+ entryPoint: "vs_velocity",+ buffers: this.vertexBuffers,+ },+ fragment: {+ module: this.velocityModule,+ entryPoint: "fs_velocity",+ targets: [{ format: VELOCITY_FORMAT }],+ },+ depthStencil: {+ format: VELOCITY_DEPTH_FORMAT,+ depthWriteEnabled: true,+ depthCompare: "less-equal",+ },+ primitive: { topology, cullMode: "none" },+ });+ this.velocityPipelines.set(topology, pipeline);+ return pipeline;+ }++ private textureGroup(+ texture: GPUTexture | undefined,+ sampler: GPUSampler,+ maps: MeshMaterialMaps | undefined,+ ): GPUBindGroup {+ const white = this.defaultWhiteTexture;+ return this.device.createBindGroup({+ layout: this.textureLayout,+ entries: [+ { binding: 0, resource: sampler },+ { binding: 1, resource: (texture ?? white).createView() },+ {+ binding: 2,+ resource: (maps?.normal ?? this.flatNormalTexture).createView(),+ },+ {+ binding: 3,+ resource: (maps?.metallicRoughness ?? white).createView(),+ },+ { binding: 4, resource: (maps?.occlusion ?? white).createView() },+ { binding: 5, resource: (maps?.emissive ?? white).createView() },+ ],+ });+ }++ /** Binds the vertex and index buffers and draws (instanced when asked). */+ private issue(+ pass: GPURenderPassEncoder,+ meshBuffers: GPUMeshBuffers,+ wireframe: boolean,+ data: MeshUniformData,+ instanceCount: number,+ firstInstance: number,+ ): void {pass.setVertexBuffer(0, meshBuffers.vertexBuffer);pass.setVertexBuffer(1, this.colorsFor(meshBuffers));pass.setVertexBuffer(2,meshBuffers.mapUvBuffer ?? meshBuffers.vertexBuffer,);+ const wire = wireframe && meshBuffers.wireIndexBuffer;pass.setIndexBuffer(- wireframe ? meshBuffers.wireIndexBuffer! : meshBuffers.indexBuffer,+ wire || meshBuffers.indexBuffer,meshBuffers.indexFormat,);+ const count = wire+ ? (meshBuffers.wireIndexCount ?? 0)+ : meshBuffers.indexCount;if (instanceCount > 1 || data.isInstanced) {- pass.drawIndexed(- wireframe ? meshBuffers.wireIndexCount! : meshBuffers.indexCount,- instanceCount,- 0,- 0,- firstInstance,- );+ pass.drawIndexed(count, instanceCount, 0, 0, firstInstance);} else {- pass.drawIndexed(- wireframe ? meshBuffers.wireIndexCount! : meshBuffers.indexCount,- );+ pass.drawIndexed(count);}}@@ -732,29 +876,14 @@ export class Mesh3DPipeline {);pass.setBindGroup(0, lightCameraBindGroup);pass.setBindGroup(1, this.packModel(data));- pass.setVertexBuffer(0, meshBuffers.vertexBuffer);- pass.setVertexBuffer(1, this.colorsFor(meshBuffers));- pass.setVertexBuffer(- 2,- meshBuffers.mapUvBuffer ?? meshBuffers.vertexBuffer,+ this.issue(+ pass,+ meshBuffers,+ wireframe,+ data,+ instanceCount,+ firstInstance,);- pass.setIndexBuffer(- wireframe ? meshBuffers.wireIndexBuffer! : meshBuffers.indexBuffer,- meshBuffers.indexFormat,- );- if (instanceCount > 1 || data.isInstanced) {- pass.drawIndexed(- wireframe ? meshBuffers.wireIndexCount! : meshBuffers.indexCount,- instanceCount,- 0,- 0,- firstInstance,- );- } else {- pass.drawIndexed(- wireframe ? meshBuffers.wireIndexCount! : meshBuffers.indexCount,- );- }}private colorsFor(meshBuffers: GPUMeshBuffers): GPUBuffer {diff --git a/packages/webgpu-renderers/src/renderer3d/motion-blur-pipeline.ts b/packages/webgpu-renderers/src/renderer3d/motion-blur-pipeline.tsindex 8fa704e6..4ef1190e 100644--- a/packages/webgpu-renderers/src/renderer3d/motion-blur-pipeline.ts+++ b/packages/webgpu-renderers/src/renderer3d/motion-blur-pipeline.ts@@ -1,182 +1,174 @@/**- * @file packages/webgpu-renderers/src/renderer3d/motion-blur-pipeline.ts- * WebGPU render pipeline for camera shutter motion blur using screen-space velocity buffers.+ * Shutter motion blur of a 3D scene from its velocity buffer (see+ * `shaders/motion-blur.ts`): tile max, neighbor max, then a depth-aware+ * reconstruction gather into the target.*/-+import { BufferPool } from "../renderer2d/buffer-pool.js";import { motionBlurWgsl } from "../shaders/motion-blur.js";export interface MotionBlurPassOptions {+ /** Shutter angle, degrees. Default 180. */shutterAngle?: number;+ /** Taps along each pixel's motion. Default 20. */sampleCount?: number;- maxVelocity?: number;- depthThreshold?: number;- curveType?: "box" | "gaussian" | "triangle";- width: number;- height: number;+ /** Longest blur from a pixel (and the tile size), px. Default 48. */+ maxBlur?: number;+ /** Depth softness between in front and behind, scene px. Default 20. */+ softDepth?: number;}+const TILE_FORMAT: GPUTextureFormat = "rgba16float";+export class MotionBlurPipeline {- private device: GPUDevice;- private pipeline: GPURenderPipeline;- private bindGroupLayout: GPUBindGroupLayout;- private uniformBuffer: GPUBuffer;- private sampler: GPUSampler;+ private readonly device: GPUDevice;+ private readonly module: GPUShaderModule;+ private readonly tileMax: GPURenderPipeline;+ private readonly neighborMax: GPURenderPipeline;+ 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;-- const shaderModule = device.createShaderModule({- label: "motion-blur-shader",+ this.module = device.createShaderModule({+ label: "motion-blur.wgsl",code: motionBlurWgsl,});+ this.tileMax = this.pipeline("fs_tile_max", TILE_FORMAT);+ this.neighborMax = this.pipeline("fs_neighbor_max", TILE_FORMAT);+ this.params = new BufferPool(+ 32,+ GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,+ );+ }- this.bindGroupLayout = device.createBindGroupLayout({- label: "motion-blur-bgl",- entries: [- {- binding: 0,- visibility: GPUShaderStage.FRAGMENT,- texture: { sampleType: "float" },- },- {- binding: 1,- visibility: GPUShaderStage.FRAGMENT,- texture: { sampleType: "float" },- },- {- binding: 2,- visibility: GPUShaderStage.FRAGMENT,- texture: { sampleType: "depth" },- },- {- binding: 3,- visibility: GPUShaderStage.FRAGMENT,- sampler: { type: "filtering" },- },- {- binding: 4,- visibility: GPUShaderStage.FRAGMENT,- buffer: { type: "uniform" },- },- ],- });-- const pipelineLayout = device.createPipelineLayout({- label: "motion-blur-layout",- bindGroupLayouts: [this.bindGroupLayout],- });-- this.pipeline = device.createRenderPipeline({- label: "motion-blur-pipeline",- layout: pipelineLayout,- vertex: {- module: shaderModule,- entryPoint: "vs_main",- },+ private pipeline(entry: string, format: GPUTextureFormat): GPURenderPipeline {+ return this.device.createRenderPipeline({+ label: `motion-blur-${entry}`,+ layout: "auto",+ vertex: { module: this.module, entryPoint: "vs_main" },fragment: {- module: shaderModule,- entryPoint: "fs_motion_blur",- targets: [- {- format: "rgba8unorm",- blend: {- color: {- srcFactor: "one",- dstFactor: "one-minus-src-alpha",- operation: "add",- },- alpha: {- srcFactor: "one",- dstFactor: "one-minus-src-alpha",- operation: "add",- },- },- },- ],- },- primitive: {- topology: "triangle-strip",+ module: this.module,+ entryPoint: entry,+ targets: [{ format }],},+ primitive: { topology: "triangle-list" },});+ }- this.uniformBuffer = device.createBuffer({- label: "motion-blur-uniforms",- size: 32, // 8 * 4 bytes- usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,- });-- this.sampler = device.createSampler({- label: "motion-blur-sampler",- magFilter: "linear",- minFilter: "linear",- });+ 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;}- public render(- commandEncoder: GPUCommandEncoder,- colorView: GPUTextureView,- velocityView: GPUTextureView,- depthView: GPUTextureView,- targetView: GPUTextureView,- options: MotionBlurPassOptions,+ /**+ * Blurs `color` (premultiplied) by `velocity` (`VELOCITY_FORMAT`, same+ * size) into `target` (a view of `targetFormat`, same size).+ */+ render(+ encoder: GPUCommandEncoder,+ color: GPUTexture,+ velocity: GPUTexture,+ target: GPUTextureView,+ targetFormat: GPUTextureFormat,+ options: MotionBlurPassOptions = {},): void {- const shutterFraction = (options.shutterAngle ?? 180) / 360;- const sampleCount = options.sampleCount ?? 16;- const maxVelocity = options.maxVelocity ?? 64;- const depthThreshold = options.depthThreshold ?? 0.05;- const curveType =- options.curveType === "box"- ? 0- : options.curveType === "triangle"- ? 2- : 1;-- const uniformData = new ArrayBuffer(32);- const f32View = new Float32Array(uniformData);- const u32View = new Uint32Array(uniformData);-- f32View[0] = shutterFraction;- u32View[1] = sampleCount;- f32View[2] = maxVelocity;- u32View[3] = 16; // tileDilation- f32View[4] = options.width;- f32View[5] = options.height;- f32View[6] = depthThreshold;- u32View[7] = curveType;-- this.device.queue.writeBuffer(this.uniformBuffer, 0, uniformData);-- const bindGroup = this.device.createBindGroup({- label: "motion-blur-bg",- layout: this.bindGroupLayout,- entries: [- { binding: 0, resource: colorView },- { binding: 1, resource: velocityView },- { binding: 2, resource: depthView },- { binding: 3, resource: this.sampler },- { binding: 4, resource: { buffer: this.uniformBuffer } },- ],- });+ const k = Math.max(4, Math.min(160, Math.round(options.maxBlur ?? 48)));+ 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 params = this.params.getBuffer(+ this.device,+ new Float32Array([+ width,+ height,+ tw,+ th,+ (options.shutterAngle ?? 180) / 360 / 2,+ k,+ Math.max(1, Math.round(options.sampleCount ?? 20)),+ options.softDepth ?? 20,+ ]),+ );+ const velocityView = velocity.createView();+ this.pass(encoder, this.tileMax, a.createView(), [+ { binding: 0, resource: { buffer: params } },+ { binding: 1, resource: velocityView },+ ]);+ this.pass(encoder, this.neighborMax, b.createView(), [+ { binding: 0, resource: { buffer: params } },+ { binding: 2, resource: a.createView() },+ ]);+ let reconstruct = this.reconstruct.get(targetFormat);+ if (!reconstruct) {+ reconstruct = this.pipeline("fs_reconstruct", targetFormat);+ this.reconstruct.set(targetFormat, reconstruct);+ }+ this.pass(encoder, reconstruct, target, [+ { binding: 0, resource: { buffer: params } },+ { binding: 1, resource: velocityView },+ { binding: 2, resource: b.createView() },+ { binding: 3, resource: color.createView() },+ ]);+ }- const pass = commandEncoder.beginRenderPass({- label: "motion-blur-pass",+ private pass(+ encoder: GPUCommandEncoder,+ pipeline: GPURenderPipeline,+ view: GPUTextureView,+ entries: GPUBindGroupEntry[],+ ): void {+ const pass = encoder.beginRenderPass({+ label: pipeline.label,colorAttachments: [{- view: targetView,+ view,loadOp: "clear",storeOp: "store",clearValue: { r: 0, g: 0, b: 0, a: 0 },},],});-- pass.setPipeline(this.pipeline);- pass.setBindGroup(0, bindGroup);- pass.draw(4);+ pass.setPipeline(pipeline);+ pass.setBindGroup(+ 0,+ this.device.createBindGroup({+ layout: pipeline.getBindGroupLayout(0),+ entries,+ }),+ );+ pass.draw(3);pass.end();}- public destroy(): void {- this.uniformBuffer.destroy();+ resetPools(): void {+ this.params.reset();+ }++ 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 9d7e12e1..269e67d3 100644--- a/packages/webgpu-renderers/src/renderer3d/renderer3d.ts+++ b/packages/webgpu-renderers/src/renderer3d/renderer3d.ts@@ -50,6 +50,7 @@ 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 type { SlugGlyphBatch } from "../slug/slug-pipeline.js";import { AudioMeshDeformPipeline } from "./audio-mesh-deform-pipeline.js";import { type BloomOptions, BloomPipeline } from "./bloom-pipeline.js";@@ -63,9 +64,16 @@ import {Mesh3DPipeline,type MeshCrowd,type MeshMaterialMaps,+ type MeshMotionPrev,type MeshWind,+ VELOCITY_DEPTH_FORMAT,+ VELOCITY_FORMAT,} from "./mesh3d-pipeline.js";import { MorphPipeline } from "./morph-pipeline.js";+import {+ type MotionBlurPassOptions,+ MotionBlurPipeline,+} from "./motion-blur-pipeline.js";import { Quad3DPipeline, type Relief3D } from "./quad3d-pipeline.js";import { SHADOW_DEPTH_FORMAT } from "./shadow-depth.js";import {@@ -323,6 +331,19 @@ export class Renderer3D {/** Whether the current pass also writes HDR radiance (bloom). */private passWritesHdr = false;private cameraUniformData = new Float32Array(80); // 320 bytes = 80 floats+ private velocityCameraPool = new BufferPool(+ 192,+ GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,+ );+ private quadMotionPool = new BufferPool(+ 128,+ GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,+ );+ private motionBlurPipeline?: MotionBlurPipeline;+ private quadVelocity?: {+ pipeline: GPURenderPipeline;+ layout: GPUBindGroupLayout;+ };private meshBuffersCache = new WeakMap<Mesh3DData, GPUMeshBuffers>();private materialTextures = new WeakMap<Material3D,@@ -414,7 +435,9 @@ export class Renderer3D {this.instancePool = new BufferPool(65536,- GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,+ GPUBufferUsage.STORAGE |+ GPUBufferUsage.COPY_DST |+ GPUBufferUsage.COPY_SRC,);// Initialize DoF Bokeh Pipeline@@ -514,6 +537,9 @@ export class Renderer3D {this.volumetricFogPipeline?.resetPools();this.ssrGiPipeline?.resetPools();this.cameraPool.reset();+ this.velocityCameraPool.reset();+ this.quadMotionPool.reset();+ this.motionBlurPipeline?.resetPools();// The cached camera buffer goes back to the pool and may be handed// out again (e.g. to a shadow pass's light camera): never reuse it// across a reset.@@ -2120,6 +2146,223 @@ export class Renderer3D {);}+ /**+ * Begins the velocity pass for shutter motion blur: draw the scene's+ * meshes and planes with `drawMeshVelocity` / `drawQuadVelocity`, end+ * the pass, then `applyMotionBlur` with the returned texture.+ */+ beginVelocityPass(+ encoder: GPUCommandEncoder,+ width: number,+ height: number,+ camera: Camera3DPose,+ prevCamera: Camera3DPose,+ ): {+ pass: GPURenderPassEncoder;+ cameraBindGroup: GPUBindGroup;+ velocity: GPUTexture;+ } {+ const usage =+ GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING;+ const velocity = this.attachment("Renderer3DVelocity", width, height, {+ format: VELOCITY_FORMAT,+ usage,+ });+ const depth = this.attachment("Renderer3DVelocityDepth", width, height, {+ format: VELOCITY_DEPTH_FORMAT,+ usage: GPUTextureUsage.RENDER_ATTACHMENT,+ });+ const data = new Float32Array(48);+ data.set(Camera3D.computeViewProjectionMatrix(camera), 0);+ data.set(Camera3D.computeViewProjectionMatrix(prevCamera), 16);+ const fwd = Vector3Math.normalize(+ Vector3Math.subtract(camera.target, camera.eye),+ );+ data.set([...camera.eye, 1, ...fwd, 0, width, height, 0, 0], 32);+ const cameraBindGroup = this.device.createBindGroup({+ layout: this.mesh3dPipeline.velocityCameraLayout,+ entries: [+ {+ binding: 0,+ resource: {+ buffer: this.velocityCameraPool.getBuffer(this.device, data),+ },+ },+ ],+ });+ const pass = encoder.beginRenderPass({+ label: "Renderer3DVelocityPass",+ colorAttachments: [+ {+ view: velocity.createView(),+ loadOp: "clear",+ storeOp: "store",+ clearValue: { r: 0, g: 0, b: 0, a: 0 },+ },+ ],+ depthStencilAttachment: {+ view: depth.createView(),+ depthClearValue: 1,+ depthLoadOp: "clear",+ depthStoreOp: "discard",+ },+ });+ return { pass, cameraBindGroup, velocity };+ }++ /** Draws a mesh's motion since `prev` (its state a frame earlier) into the velocity pass. */+ drawMeshVelocity(+ pass: GPURenderPassEncoder,+ cameraBindGroup: GPUBindGroup,+ meshOrBuffers: Mesh3DData | GPUMeshBuffers,+ texture: GPUTexture | undefined,+ opts: DrawMesh3DOpts,+ prev: MeshMotionPrev | undefined,+ ): void {+ const meshBuffers =+ "vertexBuffer" in meshOrBuffers+ ? meshOrBuffers+ : this.getOrCreateMeshBuffers(meshOrBuffers, opts.wireframe);+ const m = this.meshModelMatrix(opts);+ const address = ADDRESS_MODES[opts.textureWrap ?? "clamp"];+ const sampler = this.samplerCache.getSampler(this.device, {+ addressModeU: address,+ addressModeV: address,+ });+ this.mesh3dPipeline.drawVelocity(+ pass,+ cameraBindGroup,+ meshBuffers,+ texture,+ sampler,+ {+ modelMatrix: m,+ normalMatrix: opts.normalMatrix ?? Light3D.computeNormalMatrix(m),+ colorTint: opts.colorTint,+ wireframe: opts.wireframe,+ isSkinned: opts.isSkinned,+ skinningMatrices: opts.skinningMatrices,+ alphaCutoff: opts.alphaCutoff,+ uvRect: opts.uvRect,+ wind: opts.wind,+ crowd: opts.crowd,+ isInstanced: Boolean(+ opts.instanceBuffer || (opts.instanceCount && opts.instanceCount > 1),+ ),+ instanceBuffer: opts.instanceBuffer,+ matrixInstances: opts.matrixInstances,+ },+ prev,+ opts.instanceCount ?? 1,+ opts.firstInstance ?? 0,+ );+ }++ /** Draws a 3D layer plane's motion since `prevModelMatrix` into the velocity pass. */+ drawQuadVelocity(+ pass: GPURenderPassEncoder,+ cameraBindGroup: GPUBindGroup,+ texture: GPUTexture,+ opts: DrawQuad3DOpts,+ prevModelMatrix: Mat4 | undefined,+ ): void {+ const quad = this.quadVelocityPipeline();+ const m = this.quadModelMatrix(opts);+ const data = new Float32Array(32);+ data.set(m, 0);+ data.set(prevModelMatrix ?? m, 16);+ const group = this.device.createBindGroup({+ layout: quad.layout,+ entries: [+ {+ binding: 0,+ resource: {+ buffer: this.quadMotionPool.getBuffer(this.device, data),+ },+ },+ { binding: 1, resource: this.samplerCache.getSampler(this.device, {}) },+ { binding: 2, resource: texture.createView() },+ ],+ });+ pass.setPipeline(quad.pipeline);+ pass.setBindGroup(0, cameraBindGroup);+ pass.setBindGroup(1, group);+ pass.draw(4);+ }++ private quadVelocityPipeline(): {+ pipeline: GPURenderPipeline;+ layout: GPUBindGroupLayout;+ } {+ if (this.quadVelocity) return this.quadVelocity;+ const module = this.device.createShaderModule({+ label: "quad-velocity.wgsl",+ code: quadVelocityWgsl,+ });+ const layout = this.device.createBindGroupLayout({+ label: "Renderer3DQuadVelocityLayout",+ entries: [+ {+ binding: 0,+ visibility: GPUShaderStage.VERTEX,+ buffer: { type: "uniform" },+ },+ {+ binding: 1,+ visibility: GPUShaderStage.FRAGMENT,+ sampler: { type: "filtering" },+ },+ {+ binding: 2,+ visibility: GPUShaderStage.FRAGMENT,+ texture: { sampleType: "float" },+ },+ ],+ });+ const pipeline = this.device.createRenderPipeline({+ label: "Renderer3DQuadVelocity",+ layout: this.device.createPipelineLayout({+ bindGroupLayouts: [this.mesh3dPipeline.velocityCameraLayout, layout],+ }),+ vertex: { module, entryPoint: "vs_quad_velocity" },+ fragment: {+ module,+ entryPoint: "fs_quad_velocity",+ targets: [{ format: VELOCITY_FORMAT }],+ },+ depthStencil: {+ format: VELOCITY_DEPTH_FORMAT,+ depthWriteEnabled: true,+ depthCompare: "less-equal",+ },+ primitive: { topology: "triangle-strip", cullMode: "none" },+ });+ this.quadVelocity = { pipeline, layout };+ return this.quadVelocity;+ }++ /**+ * Shutter motion blur: blurs `color` by the velocity pass's `velocity`+ * into `target` (a view of a texture in this renderer's format, same size).+ */+ applyMotionBlur(+ encoder: GPUCommandEncoder,+ color: GPUTexture,+ velocity: GPUTexture,+ target: GPUTextureView,+ options: MotionBlurPassOptions = {},+ ): void {+ this.motionBlurPipeline ??= new MotionBlurPipeline(this.device);+ this.motionBlurPipeline.render(+ encoder,+ color,+ velocity,+ target,+ this.format,+ options,+ );+ }+loadModel(srcOrData: string | ArrayBuffer | Uint8Array,format:@@ -2491,6 +2734,9 @@ export class Renderer3D {}destroy(): void {+ this.motionBlurPipeline?.destroy();+ this.velocityCameraPool.destroy();+ this.quadMotionPool.destroy();for (const texture of this.attachments.values()) texture.destroy();this.attachments.clear();this.bloomPipeline?.destroy();diff --git a/packages/webgpu-renderers/src/shaders/mesh-velocity.ts b/packages/webgpu-renderers/src/shaders/mesh-velocity.tsnew file mode 100644index 00000000..d46f5148--- /dev/null+++ b/packages/webgpu-renderers/src/shaders/mesh-velocity.ts@@ -0,0 +1,144 @@+/**+ * Velocity pass for shutter motion blur: each mesh vertex is deformed twice,+ * with this frame's bindings and the previous frame's (model matrix,+ * skinning palette, instance records, wind and crowd time), by the same code+ * the color pass runs, and projected with this and the previous camera. The+ * target holds the screen motion in pixels (rg), linear depth (b) and+ * coverage (a).+ */+import {+ meshDeformStructWgsl,+ meshDeformWgsl,+ meshStructsWgsl,+} from "./mesh3d.js";++export const meshVelocityWgsl = `+${meshStructsWgsl}++struct VelocityCamera {+ viewProj : mat4x4<f32>,+ prevViewProj : mat4x4<f32>,+ eye : vec4<f32>,+ dir : vec4<f32>,+ viewport : vec4<f32>, // xy = target size, px+};++@group(0) @binding(0) var<uniform> vcam : VelocityCamera;+@group(1) @binding(0) var<uniform> model : ModelUniforms;+@group(1) @binding(1) var<storage, read> skinning : SkinningUniforms;+@group(1) @binding(4) var<storage, read> instances : array<InstanceData>;+@group(2) @binding(0) var<uniform> modelPrev : ModelUniforms;+@group(2) @binding(1) var<storage, read> skinningPrev : SkinningUniforms;+@group(2) @binding(4) var<storage, read> instancesPrev : array<InstanceData>;+@group(3) @binding(0) var texSampler : sampler;+@group(3) @binding(1) var mainTex : texture_2d<f32>;++fn rotateVecByQuat(v: vec3<f32>, q: vec4<f32>) -> vec3<f32> {+ let t = 2.0 * cross(q.xyz, v);+ return v + q.w * t + cross(q.xyz, t);+}++${meshDeformStructWgsl}+${meshDeformWgsl("", "model", "skinning", "instances")}+${meshDeformWgsl("Prev", "modelPrev", "skinningPrev", "instancesPrev")}++struct VelocityOut {+ @builtin(position) pos : vec4<f32>,+ @location(0) curr : vec4<f32>,+ @location(1) prev : vec4<f32>,+ @location(2) uv : vec2<f32>,+ @location(3) depth : f32,+ @location(4) alpha : f32,+};++@vertex+fn vs_velocity(in: VertexInput, @builtin(instance_index) instanceIndex: u32) -> VelocityOut {+ let now = deform(in, instanceIndex);+ let before = deformPrev(in, instanceIndex);+ let world = model.modelMatrix * vec4<f32>(now.localPos, 1.0);+ let worldPrev = modelPrev.modelMatrix * vec4<f32>(before.localPos, 1.0);+ var out: VelocityOut;+ out.pos = vcam.viewProj * world;+ out.curr = out.pos;+ out.prev = vcam.prevViewProj * worldPrev;+ out.uv = model.uvRect.xy + in.uv * model.uvRect.zw;+ out.depth = dot(world.xyz - vcam.eye.xyz, vcam.dir.xyz);+ out.alpha = in.color.a * now.instColor.a;+ return out;+}++@fragment+fn fs_velocity(in: VelocityOut) -> @location(0) vec4<f32> {+ // Cut-out texels (alpha-tested leaves, cards) leave no motion behind.+ let cutoff = model.shade.a;+ if (cutoff > 0.0) {+ let a = textureSample(mainTex, texSampler, in.uv).a * in.alpha;+ if (a < cutoff) {+ discard;+ }+ }+ let ndc = in.curr.xy / in.curr.w;+ let ndcPrev = in.prev.xy / max(in.prev.w, 1e-6);+ // NDC y points up, pixels down.+ let motion = (ndc - ndcPrev) * 0.5 * vcam.viewport.xy * vec2<f32>(1.0, -1.0);+ return vec4<f32>(motion, in.depth, 1.0);+}+`;++/**+ * Velocity of a 3D layer plane (the unit quad its model matrix places):+ * this and the previous frame's model matrix; transparent texels leave+ * the background's motion.+ */+export const quadVelocityWgsl = `+struct VelocityCamera {+ viewProj : mat4x4<f32>,+ prevViewProj : mat4x4<f32>,+ eye : vec4<f32>,+ dir : vec4<f32>,+ viewport : vec4<f32>,+};++struct QuadMotion {+ model : mat4x4<f32>,+ modelPrev : mat4x4<f32>,+};++@group(0) @binding(0) var<uniform> vcam : VelocityCamera;+@group(1) @binding(0) var<uniform> quad : QuadMotion;+@group(1) @binding(1) var quadSampler : sampler;+@group(1) @binding(2) var quadTex : texture_2d<f32>;++struct QuadVelocityOut {+ @builtin(position) pos : vec4<f32>,+ @location(0) curr : vec4<f32>,+ @location(1) prev : vec4<f32>,+ @location(2) uv : vec2<f32>,+ @location(3) depth : f32,+};++@vertex+fn vs_quad_velocity(@builtin(vertex_index) i: u32) -> QuadVelocityOut {+ let corner = vec2<f32>(f32(i & 1u), f32(i >> 1u));+ let local = vec4<f32>(corner - 0.5, 0.0, 1.0);+ let world = quad.model * local;+ var out: QuadVelocityOut;+ out.pos = vcam.viewProj * world;+ out.curr = out.pos;+ out.prev = vcam.prevViewProj * (quad.modelPrev * local);+ out.uv = corner;+ out.depth = dot(world.xyz - vcam.eye.xyz, vcam.dir.xyz);+ return out;+}++@fragment+fn fs_quad_velocity(in: QuadVelocityOut) -> @location(0) vec4<f32> {+ if (textureSample(quadTex, quadSampler, in.uv).a < 0.02) {+ discard;+ }+ let ndc = in.curr.xy / in.curr.w;+ let ndcPrev = in.prev.xy / max(in.prev.w, 1e-6);+ let motion = (ndc - ndcPrev) * 0.5 * vcam.viewport.xy * vec2<f32>(1.0, -1.0);+ return vec4<f32>(motion, in.depth, 1.0);+}+`;diff --git a/packages/webgpu-renderers/src/shaders/mesh3d.ts b/packages/webgpu-renderers/src/shaders/mesh3d.tsindex 362ac5c6..219d69b6 100644--- a/packages/webgpu-renderers/src/shaders/mesh3d.ts+++ b/packages/webgpu-renderers/src/shaders/mesh3d.ts@@ -10,9 +10,8 @@import { lighting3dWgsl, lightsBindingsWgsl } from "./lighting3d.js";import { matte3dWgsl } from "./matte3d.js";-export const mesh3dWgsl = `-${lighting3dWgsl}-+/** Mesh uniform, skinning, instance and vertex input structs (shared by the mesh passes). */+export const meshStructsWgsl = `struct ModelUniforms {modelMatrix : mat4x4<f32>,normalMatrix : mat4x4<f32>,@@ -47,19 +46,6 @@ struct InstanceData {emissive : vec4<f32>, // rgb = sRGB emissive color, w = emissiveIntensity};-@group(0) @binding(0) var<uniform> cam : CameraUniforms;-@group(1) @binding(0) var<uniform> model : ModelUniforms;-@group(1) @binding(1) var<storage, read> skinning : SkinningUniforms;-${matte3dWgsl(1, 2)}@group(1) @binding(3) var backdropTex : texture_2d<f32>;-@group(1) @binding(4) var<storage, read> instances : array<InstanceData>;-@group(2) @binding(0) var texSampler : sampler;-@group(2) @binding(1) var mainTex : texture_2d<f32>;-@group(2) @binding(2) var normalTex : texture_2d<f32>;-@group(2) @binding(3) var metalRoughTex : texture_2d<f32>;-@group(2) @binding(4) var occlusionTex : texture_2d<f32>;-@group(2) @binding(5) var emissiveTex : texture_2d<f32>;-${lightsBindingsWgsl}-struct VertexInput {@location(0) position : vec3<f32>,@location(1) uv : vec2<f32>,@@ -73,75 +59,75 @@ struct VertexInput {@location(9) emissiveUv : vec2<f32>,};-struct VertexOutput {- @builtin(position) clipPos : vec4<f32>,- @location(0) uv : vec2<f32>,- @location(1) worldPos : vec3<f32>,- @location(2) worldNormal : vec3<f32>,- @location(3) linearDepth : f32,- @location(4) color : vec4<f32>,- @location(5) normalUv : vec2<f32>,- @location(6) mrUv : vec2<f32>,- @location(7) aoUv : vec2<f32>,- @location(8) emissiveUv : vec2<f32>,- @location(9) emissive : vec4<f32>,-};+`;-fn rotateVecByQuat(v: vec3<f32>, q: vec4<f32>) -> vec3<f32> {- let t = 2.0 * cross(q.xyz, v);- return v + q.w * t + cross(q.xyz, t);-}+/** The deformed vertex in mesh space (before the model matrix). */+export const meshDeformStructWgsl = `+struct MeshDeform {+ localPos : vec3<f32>,+ localNorm : vec3<f32>,+ instColor : vec4<f32>,+ instEmissive : vec4<f32>,+};+`;+/**+ * WGSL for the mesh vertex deformation (skinning, skinned crowds,+ * instancing, wind) as \`fn deform${n}(in, instanceIndex) -> MeshDeform\`,+ * reading the named model uniform, skinning and instance bindings. The+ * color pass and the velocity pass (current and previous frame) share it.+ */+export function meshDeformWgsl(+ n: string,+ model: string,+ skin: string,+ inst: string,+): string {+ return `// Wind lean in radians at a plant rooted at ground point root: a steady// push plus a traveling wave and a faster flutter, so neighbors sway together// and the far field lags the near one.-fn windAngle(root: vec2<f32>) -> f32 {- let w = model.wind;- let phase = dot(root, model.windFrame.xy) * w.z - w.w * w.y;+fn windAngle${n}(root: vec2<f32>) -> f32 {+ let w = ${model}.wind;+ let phase = dot(root, ${model}.windFrame.xy) * w.z - w.w * w.y;return w.x * (0.55 + 0.35 * sin(phase) + 0.1 * sin(phase * 2.7 + 1.3));}// Bends a vertex (mesh space, scale s) downwind: the base stays put,// the tip leans furthest, along an arc so the stem keeps its length.-fn windBend(local: vec3<f32>, angle: f32, s: f32) -> vec3<f32> {- let h = max(model.windFrame.z - local.y, 0.0);- let k = clamp(h * model.windFrame.w, 0.0, 1.0);+fn windBend${n}(local: vec3<f32>, angle: f32, s: f32) -> vec3<f32> {+ let h = max(${model}.windFrame.z - local.y, 0.0);+ let k = clamp(h * ${model}.windFrame.w, 0.0, 1.0);let a = angle * k * k;- let downwind = vec3<f32>(model.windFrame.x, 0.0, model.windFrame.y);+ let downwind = vec3<f32>(${model}.windFrame.x, 0.0, ${model}.windFrame.y);return downwind * (sin(a) * h * s) + vec3<f32>(0.0, (1.0 - cos(a)) * h * s, 0.0);}// A crowd joint: two baked frames of the palette, blended.-fn crowdJoint(base0: u32, base1: u32, t: f32, joint: u32) -> mat4x4<f32> {- return skinning.jointMatrices[base0 + joint] * (1.0 - t) +- skinning.jointMatrices[base1 + joint] * t;+fn crowdJoint${n}(base0: u32, base1: u32, t: f32, joint: u32) -> mat4x4<f32> {+ return ${skin}.jointMatrices[base0 + joint] * (1.0 - t) ++ ${skin}.jointMatrices[base1 + joint] * t;}-@vertex-fn vs_main(- in: VertexInput,- @builtin(instance_index) instanceIndex: u32,-) -> VertexOutput {- var out: VertexOutput;-+fn deform${n}(in: VertexInput, instanceIndex: u32) -> MeshDeform {var localPos = in.position;var localNorm = in.normal;// Crowd instances (flag bit 3) carry a second record: (clip's first// baked frame, its frames per loop, phase in frames, frames per second), and skin from a// baked joint palette at their own point in their own clip.- let flags = u32(model.params.w);+ let flags = u32(${model}.params.w);let crowd = (flags & 8u) != 0u;var palette0 = 0u;var palette1 = 0u;var paletteT = 0.0;if (crowd) {- let anim = instances[instanceIndex * 2u + 1u].posScale;+ let anim = ${inst}[instanceIndex * 2u + 1u].posScale;let count = max(anim.y, 1.0);- let f = anim.z + model.crowd.x * anim.w;+ let f = anim.z + ${model}.crowd.x * anim.w;let wrapped = f - floor(f / count) * count;let f0 = floor(wrapped);- let jc = u32(model.crowd.z);+ let jc = u32(${model}.crowd.z);palette0 = (u32(anim.x) + u32(f0)) * jc;// Each clip bakes count + 1 samples (its end too): no wrap inside a loop.palette1 = (u32(anim.x) + u32(f0) + 1u) * jc;@@ -149,7 +135,7 @@ fn vs_main(}// Linear Blend Skinning (LBS) on GPU- if (model.params.z > 0.5) {+ if (${model}.params.z > 0.5) {let j0 = u32(in.joints.x);let j1 = u32(in.joints.y);let j2 = u32(in.joints.z);@@ -165,18 +151,18 @@ fn vs_main(if (crowd) {// A node-attached (rigid) mesh bakes its node as joint 0.if (totalWeight <= 0.001) {- skinMat = crowdJoint(palette0, palette1, paletteT, 0u);+ skinMat = crowdJoint${n}(palette0, palette1, paletteT, 0u);} else {- skinMat = crowdJoint(palette0, palette1, paletteT, j0) * w0 +- crowdJoint(palette0, palette1, paletteT, j1) * w1 +- crowdJoint(palette0, palette1, paletteT, j2) * w2 +- crowdJoint(palette0, palette1, paletteT, j3) * w3;+ skinMat = crowdJoint${n}(palette0, palette1, paletteT, j0) * w0 ++ crowdJoint${n}(palette0, palette1, paletteT, j1) * w1 ++ crowdJoint${n}(palette0, palette1, paletteT, j2) * w2 ++ crowdJoint${n}(palette0, palette1, paletteT, j3) * w3;}} else if (totalWeight > 0.001) {- skinMat = skinning.jointMatrices[j0] * w0 +- skinning.jointMatrices[j1] * w1 +- skinning.jointMatrices[j2] * w2 +- skinning.jointMatrices[j3] * w3;+ skinMat = ${skin}.jointMatrices[j0] * w0 ++ ${skin}.jointMatrices[j1] * w1 ++ ${skin}.jointMatrices[j2] * w2 ++ ${skin}.jointMatrices[j3] * w3;}if (crowd || totalWeight > 0.001) {let pos4 = skinMat * vec4<f32>(in.position, 1.0);@@ -189,24 +175,24 @@ fn vs_main(// Hardware instancing: transform local vertex by instance transform// Static read prevents Tint from dropping the storage buffer binding- let dummyInst = instances[0].posScale.x;+ let dummyInst = ${inst}[0].posScale.x;var instColor = vec4<f32>(1.0);var instEmissive = vec4<f32>(0.0);- let windy = model.wind.x != 0.0;- if ((u32(model.params.w) & 4u) != 0u) {- let a = instances[instanceIndex * 2u];- let b = instances[instanceIndex * 2u + 1u];+ let windy = ${model}.wind.x != 0.0;+ if ((u32(${model}.params.w) & 4u) != 0u) {+ let a = ${inst}[instanceIndex * 2u];+ let b = ${inst}[instanceIndex * 2u + 1u];let instanceModel = mat4x4<f32>(a.posScale, a.quat, a.color, a.emissive);let instanceNormal = mat4x4<f32>(b.posScale, b.quat, b.color, b.emissive);localPos = (instanceModel * vec4<f32>(localPos, 1.0)).xyz;localNorm = (instanceNormal * vec4<f32>(localNorm, 0.0)).xyz;- } else if ((u32(model.params.w) & 1u) != 0u) {- let inst = instances[select(instanceIndex, instanceIndex * 2u, crowd)];+ } else if ((u32(${model}.params.w) & 1u) != 0u) {+ let inst = ${inst}[select(instanceIndex, instanceIndex * 2u, crowd)];let scaledPos = localPos * inst.posScale.w;var bend = vec3<f32>(0.0);if (windy) {- bend = windBend(localPos, windAngle(inst.posScale.xz), inst.posScale.w);+ bend = windBend${n}(localPos, windAngle${n}(inst.posScale.xz), inst.posScale.w);}localPos = rotateVecByQuat(scaledPos, inst.quat) + inst.posScale.xyz + bend;localNorm = rotateVecByQuat(localNorm, inst.quat);@@ -215,10 +201,66 @@ fn vs_main(} else {localPos.x += dummyInst * 0.0;if (windy) {- localPos += windBend(localPos, windAngle(vec2<f32>(0.0)), 1.0);+ localPos += windBend${n}(localPos, windAngle${n}(vec2<f32>(0.0)), 1.0);}}+ return MeshDeform(localPos, localNorm, instColor, instEmissive);+}+`;+}++export const mesh3dWgsl = `+${lighting3dWgsl}++${meshStructsWgsl}+@group(0) @binding(0) var<uniform> cam : CameraUniforms;+@group(1) @binding(0) var<uniform> model : ModelUniforms;+@group(1) @binding(1) var<storage, read> skinning : SkinningUniforms;+${matte3dWgsl(1, 2)}@group(1) @binding(3) var backdropTex : texture_2d<f32>;+@group(1) @binding(4) var<storage, read> instances : array<InstanceData>;+@group(2) @binding(0) var texSampler : sampler;+@group(2) @binding(1) var mainTex : texture_2d<f32>;+@group(2) @binding(2) var normalTex : texture_2d<f32>;+@group(2) @binding(3) var metalRoughTex : texture_2d<f32>;+@group(2) @binding(4) var occlusionTex : texture_2d<f32>;+@group(2) @binding(5) var emissiveTex : texture_2d<f32>;+${lightsBindingsWgsl}++struct VertexOutput {+ @builtin(position) clipPos : vec4<f32>,+ @location(0) uv : vec2<f32>,+ @location(1) worldPos : vec3<f32>,+ @location(2) worldNormal : vec3<f32>,+ @location(3) linearDepth : f32,+ @location(4) color : vec4<f32>,+ @location(5) normalUv : vec2<f32>,+ @location(6) mrUv : vec2<f32>,+ @location(7) aoUv : vec2<f32>,+ @location(8) emissiveUv : vec2<f32>,+ @location(9) emissive : vec4<f32>,+};++fn rotateVecByQuat(v: vec3<f32>, q: vec4<f32>) -> vec3<f32> {+ let t = 2.0 * cross(q.xyz, v);+ return v + q.w * t + cross(q.xyz, t);+}++${meshDeformStructWgsl}+${meshDeformWgsl("", "model", "skinning", "instances")}+@vertex+fn vs_main(+ in: VertexInput,+ @builtin(instance_index) instanceIndex: u32,+) -> VertexOutput {+ var out: VertexOutput;++ let deformed = deform(in, instanceIndex);+ let localPos = deformed.localPos;+ let localNorm = deformed.localNorm;+ let instColor = deformed.instColor;+ let instEmissive = deformed.instEmissive;+let worldPos4 = model.modelMatrix * vec4<f32>(localPos, 1.0);out.worldPos = worldPos4.xyz;diff --git a/packages/webgpu-renderers/src/shaders/motion-blur.ts b/packages/webgpu-renderers/src/shaders/motion-blur.tsindex 5fdb9af9..0e511f23 100644--- a/packages/webgpu-renderers/src/shaders/motion-blur.ts+++ b/packages/webgpu-renderers/src/shaders/motion-blur.ts@@ -1,110 +1,140 @@/**- * @file packages/webgpu-renderers/src/shaders/motion-blur.ts- * WGSL Shader Module for Velocity-Directed Line Integral Camera Motion Blur.+ * Shutter motion blur from a velocity buffer: McGuire, Hennessy, Bukowski+ * and Osman, "A Reconstruction Filter for Plausible Motion Blur" (I3D 2012).+ *+ * 1. Tile max: the dominant motion in each K×K tile (K = the longest blur).+ * 2. Neighbor max: the dominant motion among each tile's 3×3 neighbors, so a+ * fast object blurs over the background next to it.+ * 3. Reconstruction: each pixel gathers samples along its neighborhood's+ * motion; a sample counts when it is in front and its blur reaches here,+ * or level / behind and this pixel's blur reaches it (else the pixel's+ * own color stands in), so moving edges smear over a sharp background+ * and a still foreground stays sharp. Normalized per sample rather than+ * by McGuire's cone weights: uniform motion gives the exact ramp.+ *+ * Velocity texels: rg = motion since the previous frame (px), b = linear+ * depth, a = coverage (0 = empty: infinitely far, still).*/-export const motionBlurWgsl = /* wgsl */ `-struct MotionBlurUniforms {- shutterFraction: f32, // shutterAngle / 360.0- sampleCount: u32, // e.g. 16- maxVelocity: f32, // in pixels- tileDilation: u32,- viewportWidth: f32,- viewportHeight: f32,- depthThreshold: f32,- curveType: u32, // 0: box, 1: gaussian, 2: triangle+struct Params {+ size : vec2<f32>, // target, px+ tiles : vec2<f32>, // tile grid+ shutter : f32, // half the exposure as a fraction of the frame interval+ maxRadius : f32, // K: the longest blur from a pixel, px+ samples : f32,+ softZ : f32, // depth softness, scene px};-@group(0) @binding(0) var colorTexture: texture_2d<f32>;-@group(0) @binding(1) var velocityTexture: texture_2d<f32>;-@group(0) @binding(2) var depthTexture: texture_depth_2d;-@group(0) @binding(3) var colorSampler: sampler;-@group(0) @binding(4) var<uniform> u: MotionBlurUniforms;+@group(0) @binding(0) var<uniform> P : Params;+@group(0) @binding(1) var velocityTex : texture_2d<f32>;+@group(0) @binding(2) var tileTex : texture_2d<f32>;+@group(0) @binding(3) var colorTex : texture_2d<f32>;-fn computeVertexPos(vertexIndex: u32) -> vec4<f32> {- var pos = array<vec2<f32>, 4>(- vec2<f32>(-1.0, -1.0),- vec2<f32>( 1.0, -1.0),- vec2<f32>(-1.0, 1.0),- vec2<f32>( 1.0, 1.0)- );- return vec4<f32>(pos[vertexIndex], 0.0, 1.0);+@vertex+fn vs_main(@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);}-@vertex-fn vs(@builtin(vertex_index) vertexIndex: u32) -> @builtin(position) vec4<f32> {- return computeVertexPos(vertexIndex);+/** Blur half-extent at a texel: the motion over half the exposure, at most K. */+fn blurAt(texel: vec4<f32>) -> vec2<f32> {+ let v = texel.xy * P.shutter * texel.a;+ let len = length(v);+ return select(v, v * (P.maxRadius / len), len > P.maxRadius);}-@vertex-fn vs_main(@builtin(vertex_index) vertexIndex: u32) -> @builtin(position) vec4<f32> {- return computeVertexPos(vertexIndex);+fn depthAt(texel: vec4<f32>) -> f32 {+ return select(1e9, texel.b, texel.a > 0.5);}-fn executeMotionBlur(pos: vec4<f32>) -> vec4<f32> {- let uv = pos.xy / vec2<f32>(u.viewportWidth, u.viewportHeight);- let centerDepth = textureLoad(depthTexture, vec2<i32>(pos.xy), 0);- let rawVel = textureSampleLevel(velocityTexture, colorSampler, uv, 0.0).xy;-- // Scale velocity by shutter exposure fraction- var vel = rawVel * u.shutterFraction;- let speed = length(vel);-- if (speed < 0.5) {- return textureSampleLevel(colorTexture, colorSampler, uv, 0.0);- }-- // Clamp to configured max velocity limit- if (speed > u.maxVelocity) {- vel = (vel / speed) * u.maxVelocity;- }-- let velUV = vel / vec2<f32>(u.viewportWidth, u.viewportHeight);- let halfSamples = f32(u.sampleCount) * 0.5;-- var accumColor = vec4<f32>(0.0);- var totalWeight = 0.0;-- for (var i = 0u; i < u.sampleCount; i = i + 1u) {- let t = (f32(i) - halfSamples) / halfSamples;- let sampleUV = uv + velUV * t;-- if (sampleUV.x < 0.0 || sampleUV.x > 1.0 || sampleUV.y < 0.0 || sampleUV.y > 1.0) {- continue;- }-- let sampleDepth = textureSampleLevel(depthTexture, colorSampler, sampleUV, 0);- let depthDelta = abs(sampleDepth - centerDepth);- let depthWeight = clamp(1.0 - depthDelta / max(u.depthThreshold, 0.0001), 0.05, 1.0);-- var curveW = 1.0;- if (u.curveType == 1u) {- curveW = exp(-2.5 * t * t);- } else if (u.curveType == 2u) {- curveW = 1.0 - abs(t);+@fragment+fn fs_tile_max(@builtin(position) pos: vec4<f32>) -> @location(0) vec4<f32> {+ let k = i32(P.maxRadius);+ let origin = vec2<i32>(pos.xy) * k;+ let limit = vec2<i32>(P.size) - 1;+ var best = vec2<f32>(0.0);+ var bestLen = 0.0;+ for (var y = 0; y < k; y++) {+ for (var x = 0; x < k; x++) {+ let at = min(origin + vec2<i32>(x, y), limit);+ let v = blurAt(textureLoad(velocityTex, at, 0));+ let len = dot(v, v);+ if (len > bestLen) {+ best = v;+ bestLen = len;+ }}-- let w = curveW * depthWeight;- let sampleCol = textureSampleLevel(colorTexture, colorSampler, sampleUV, 0.0);-- accumColor += sampleCol * w;- totalWeight += w;}-- if (totalWeight <= 0.0) {- return textureSampleLevel(colorTexture, colorSampler, uv, 0.0);- }-- return accumColor / totalWeight;+ return vec4<f32>(best, 0.0, 1.0);}@fragment-fn fs(@builtin(position) pos: vec4<f32>) -> @location(0) vec4<f32> {- return executeMotionBlur(pos);+fn fs_neighbor_max(@builtin(position) pos: vec4<f32>) -> @location(0) vec4<f32> {+ let tile = vec2<i32>(pos.xy);+ let limit = vec2<i32>(P.tiles) - 1;+ var best = vec2<f32>(0.0);+ var bestLen = 0.0;+ for (var y = -1; y <= 1; y++) {+ for (var x = -1; x <= 1; x++) {+ let at = clamp(tile + vec2<i32>(x, y), vec2<i32>(0), limit);+ let v = textureLoad(tileTex, at, 0).xy;+ let len = dot(v, v);+ if (len > bestLen) {+ best = v;+ bestLen = len;+ }+ }+ }+ return vec4<f32>(best, 0.0, 1.0);+}++/** Whether a blur of half-extent len (px) reaches distance d, antialiased over a pixel. */+fn reaches(d: f32, len: f32) -> f32 {+ return clamp(len - d + 0.5, 0.0, 1.0);+}++/** 1 where depth a is in front of depth b, fading over softZ. */+fn inFront(a: f32, b: f32) -> f32 {+ return clamp(1.0 - (a - b) / P.softZ, 0.0, 1.0);+}++/** Interleaved gradient noise (Jimenez): a deterministic per-pixel jitter. */+fn ign(p: vec2<f32>) -> f32 {+ return fract(52.9829189 * fract(dot(p, vec2<f32>(0.06711056, 0.00583715))));}@fragment-fn fs_motion_blur(@builtin(position) pos: vec4<f32>) -> @location(0) vec4<f32> {- return executeMotionBlur(pos);+fn fs_reconstruct(@builtin(position) pos: vec4<f32>) -> @location(0) vec4<f32> {+ let px = vec2<i32>(pos.xy);+ let limit = vec2<i32>(P.size) - 1;+ let cX = textureLoad(colorTex, px, 0);+ let tile = min(px / i32(P.maxRadius), vec2<i32>(P.tiles) - 1);+ let vn = textureLoad(tileTex, tile, 0).xy;+ if (length(vn) <= 0.5) {+ return cX;+ }+ let texX = textureLoad(velocityTex, px, 0);+ let lenX = length(blurAt(texX));+ let zX = depthAt(texX);++ let n = i32(P.samples);+ var sum = cX;+ let jitter = ign(pos.xy) - 0.5;+ for (var i = 0; i < n; i++) {+ let t = mix(-1.0, 1.0, (f32(i) + jitter + 1.0) / f32(n + 1));+ let offset = vn * t;+ let py = clamp(vec2<i32>(floor(pos.xy + offset)), vec2<i32>(0), limit);+ let texY = textureLoad(velocityTex, py, 0);+ let lenY = length(blurAt(texY));+ let d = length(offset);+ // Over the exposure, this pixel shows Y's surface when Y is in front+ // and Y's blur reaches here, or when Y is level or behind and this+ // pixel's own blur reaches Y; otherwise its own color. Uniform+ // motion comes out exact: a linear ramp the length of the streak.+ let f = inFront(depthAt(texY), zX);+ let w = f * reaches(d, lenY) + (1.0 - f) * reaches(d, lenX);+ sum += mix(cX, textureLoad(colorTex, py, 0), w);+ }+ return sum / f32(n + 1);}`;diff --git a/plugins/framefields/skills/framefields-compose/SKILL.md b/plugins/framefields/skills/framefields-compose/SKILL.mdindex e01fa5b4..bda8f806 100644--- a/plugins/framefields/skills/framefields-compose/SKILL.md+++ b/plugins/framefields/skills/framefields-compose/SKILL.md@@ -404,6 +404,10 @@ Where depth jumps (an object's outline) the surface stretches across with the ed---+### Motion blur (3D)++`Layer.camera({ ..., motionBlur: true })` (or `{ shutter: 180, samples: 20, maxBlur: 48 }`) streaks every mesh by its own motion over the shutter, along with the camera's: moving layers, skinned joints, crowds, swarms, wind and fractured pieces. 3D layer planes (cards, video screens) move by their transform. Still things stay sharp, and a frame renders the same in order or after a seek (the frame before is rendered first, recording only). `shutter` is in degrees (180 = film, 360 = the whole frame interval). `maxBlur` caps the streak in px. A layer's own `motionBlurShutter` still streaks a whole flat layer by its position; use the camera's for 3D.+### Characters: blending, IK, look-at, springs, crowdsglTF characters (`Layer.glb` / `Layer.gltf`) take layered clips and procedural constraints. Joint names come from the file. Targets are scene coordinates: a point, keys `[[frame, x, y, z]]`, or `(frame) => [x, y, z]`.@@ -581,6 +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()`).- **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/specs/ue58-engine-roadmap.md b/specs/ue58-engine-roadmap.mdindex 69933b74..51f61497 100644--- a/specs/ue58-engine-roadmap.md+++ b/specs/ue58-engine-roadmap.md@@ -382,6 +382,8 @@ 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.+---## Schema, Lint & Skill Synchronization Requirements