Skip to content

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

feat(3d): motion blur for morphs, audio deformation and 3D text; drop character forge

okanasl3a4bdd9d1988
diff --git a/.changeset/deform-motion-blur.md b/.changeset/deform-motion-blur.md
new file mode 100644
index 00000000..9711d383
--- /dev/null
+++ b/.changeset/deform-motion-blur.md
@@ -0,0 +1,5 @@
+---
+"framefields": minor
+---
+
+Camera motion blur follows motion below the model matrix: meshes moved by their morph targets or audio deformation streak by their own vertex motion, and text drawn in the 3D scene streaks glyph by glyph (its plane and per-glyph animation). After a seek, layers placed in the 3D scene by `z` alone now blur the same as when rendered in order. The `pbr_without_environment` lint also flags `clearcoat` and `anisotropy` without `Layer.environment()`.
diff --git a/.changeset/forge-glb-writer.md b/.changeset/forge-glb-writer.md
deleted file mode 100644
index f90f2b38..00000000
--- a/.changeset/forge-glb-writer.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-"framefields": minor
----
-
-`framefields/forge`: build rigged characters in code. `GltfDocument` writes GLB files with PBR materials and Khronos material extensions, skins, named morph targets and clips; `humanoidSkeleton` places a proportioned Mixamo-named skeleton that `pose`, `aim` and pose retargeting drive unchanged; `Skeleton` builds any rig with chains and mirroring; `boneGizmo` draws a rig as bones.
-
-glTF base colors now load in the right color space: `baseColorFactor` is linear in glTF and was used as a display color, so tinted glTF materials rendered darker than authored.
diff --git a/.changeset/forge-humanoid-hips.md b/.changeset/forge-humanoid-hips.md
deleted file mode 100644
index e712e5c2..00000000
--- a/.changeset/forge-humanoid-hips.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"framefields": minor
----
-
-The humanoid skeleton preset places the hip joints at anatomical width (about 9 cm from the midline on a 180 cm figure, was 16).
diff --git a/.changeset/forge-morphs-subdivide.md b/.changeset/forge-morphs-subdivide.md
deleted file mode 100644
index 42bf9bc7..00000000
--- a/.changeset/forge-morphs-subdivide.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"framefields": minor
----
-
-Per-layer `morphs` drive any morph target by name. The forge gains Loop subdivision (`subdivide`) that carries blend shapes and skin weights exactly, and writes morph targets that move few vertices as sparse accessors.
diff --git a/.changeset/forge-sculpt.md b/.changeset/forge-sculpt.md
deleted file mode 100644
index 3084f658..00000000
--- a/.changeset/forge-sculpt.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"framefields": minor
----
-
-`framefields/forge` sculpts skinned bodies: `sculpt({ parts, skeleton, cell, triangles })` combines SDF parts (ellipsoid, round cone, tube, lathe and more, with smooth joins, cuts, twist, bend and noise detail) into a closed, manifold mesh at hero resolution, simplifies it to a triangle budget, cuts material borders on smooth curves, and skins it from the parts themselves, so blended joints bend without collapsing. `limb` and `mirrorParts` build limbs along bones and the right side from the left.
diff --git a/.changeset/forge-texture-transforms.md b/.changeset/forge-texture-transforms.md
deleted file mode 100644
index 45ac49e6..00000000
--- a/.changeset/forge-texture-transforms.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"framefields": minor
----
-
-The GLB writer gains texture transforms on texture slots (`transform: { scale, offset, rotation }`), generated tangents for normal-mapped primitives, and `encodePng` for textures made in code.
diff --git a/.changeset/glass-scene-refraction.md b/.changeset/glass-scene-refraction.md
index 51a4f369..8a908f10 100644
--- a/.changeset/glass-scene-refraction.md
+++ b/.changeset/glass-scene-refraction.md
@@ -4,4 +4,4 @@
Glass refracts the 3D scene behind it, not only the layers under the 3D batch. glTF materials with `KHR_materials_transmission` render as glass with their IOR, bending by their `KHR_materials_volume` thickness through the refracted ray, so the bend follows the object's size on screen.
-Joint drivers (`drive: [{ joint, from, rotate: { x, y, z } }]`): a joint turns by a share of another joint's turn, after look-ats and before IK. Model files carry their own drivers (forge's `GltfDocument.addDriver`).
+Joint drivers (`drive: [{ joint, from, rotate: { x, y, z } }]`): a joint turns by a share of another joint's turn, after look-ats and before IK. Model files can carry their own drivers in the scene's `extras.framefields.drivers`.
diff --git a/.changeset/gltf-base-color.md b/.changeset/gltf-base-color.md
new file mode 100644
index 00000000..fd366fcf
--- /dev/null
+++ b/.changeset/gltf-base-color.md
@@ -0,0 +1,5 @@
+---
+"framefields": patch
+---
+
+glTF base colors load in the right color space: `baseColorFactor` is linear in glTF and was used as a display color, so tinted glTF materials rendered darker than authored.
diff --git a/.changeset/gltf-material-lobes.md b/.changeset/gltf-material-lobes.md
index dcf1c1d3..4ca6e6f6 100644
--- a/.changeset/gltf-material-lobes.md
+++ b/.changeset/gltf-material-lobes.md
@@ -2,6 +2,6 @@
"framefields": minor
---
-glTF models render their own layered materials: `KHR_materials_clearcoat`, `_sheen`, `_anisotropy` and `_iridescence` (and forge's `subsurface`, in `extras.framefields.subsurface`) feed the matching shading lobes, under any lobe props set on the layer.
+glTF models render their own layered materials: `KHR_materials_clearcoat`, `_sheen`, `_anisotropy` and `_iridescence` (and `subsurface`, in the material's `extras.framefields.subsurface`) feed the matching shading lobes, under any lobe props set on the layer.
Subsurface scattering now conserves energy: each color channel's light wraps past the shadow edge by how far that channel scatters, instead of a near-white glow being added over the surface and an ambient tint across it. Skin keeps its form and only its shadow edges warm; previous `subsurface` looks render less washed out.
diff --git a/.changeset/layer-morphs.md b/.changeset/layer-morphs.md
new file mode 100644
index 00000000..06dbd99a
--- /dev/null
+++ b/.changeset/layer-morphs.md
@@ -0,0 +1,5 @@
+---
+"framefields": minor
+---
+
+Per-layer `morphs` drive any morph target of a model by name.
diff --git a/.changeset/sparse-morphs-eight-influences.md b/.changeset/sparse-morphs-eight-influences.md
index 5a4da6ae..d30b5e2e 100644
--- a/.changeset/sparse-morphs-eight-influences.md
+++ b/.changeset/sparse-morphs-eight-influences.md
@@ -2,4 +2,4 @@
"framefields": minor
---
-Sparse morph targets stay sparse from the glTF file to the GPU: the morph pass gathers each vertex's deltas from entries that exist, so meshes with hundreds of corrective shapes fit in memory. Skins take up to eight influences per vertex (glTF `JOINTS_1` / `WEIGHTS_1`), in the forge writer, the loader and the renderer.
+Sparse morph targets stay sparse from the glTF file to the GPU: the morph pass gathers each vertex's deltas from entries that exist, so meshes with hundreds of corrective shapes fit in memory. Skins take up to eight influences per vertex (glTF `JOINTS_1` / `WEIGHTS_1`), in the loader and the renderer.
diff --git a/CLAUDE.md b/CLAUDE.md
index 28e2b23a..44b1614b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -20,7 +20,7 @@ Code-first video engine on native WebGPU (Dawn) in Node, no browser. pnpm + turb
- `packages/renderer`: headless Node renderer (Dawn, WebCodecs/mediabunny).
- `packages/vision-sam`: SAM 2.1 Tiny/Small and SAM 3 trackers (Apache-2.0 code; SAM 3 weights need runtime SAM License acceptance), private; `framefields` bundles it as a lazy chunk (`clip-vision.ts` imports it dynamically for `comp.vision(..., { sam2 | sam3 })`; `index.ts` re-exports types only) and exposes the trackers as `framefields/sam`. No weights ship; `packages/framefields/NOTICE.md` covers their licenses. Pins in `src/models/registry.ts`.
- `packages/storage`: content-addressed assets on any S3-compatible bucket (R2 first): manifest format, SigV4 client (aws4fetch), verified downloads, and the locator the preview uses to redirect missing pinned files to their bucket. Shared by the CLI (`framefields/storage`), the preview and the render worker, which fetches pinned assets after LFS.
-- `packages/forge`: rigged characters built in code (`framefields/forge`): `GltfDocument` GLB writer (materials + KHR extensions, skins, named morphs, clips), `Skeleton` / `humanoidSkeleton` (Mixamo names), `boneGizmo`, `sculpt` (SDF parts bound to joints → narrow-band manifold Surface Nets → QEM simplification → border cuts → skin weights from the field), `subdivide` (Loop, carrying blend shapes and weights). Pure TypeScript, no GPU; tests validate output with the Khronos validator and read it back through the engine loader. Plan: `specs/character-forge.md`.
+- `packages/gltf-fixtures`: private test fixtures (never exported or bundled): `GltfDocument` GLB writer (materials + KHR extensions, textures, skins, sparse morphs, clips) and `Skeleton`, used by the model import tests; its own tests check output with the Khronos validator and read it back through the engine loader.
- `packages/core`: shared types, `Effect` base, signals, `emojiPresentation` (the one UTS #51 rule used by layout, preload and lint).
- Others: `renderers`, `media`, `node-sdk`, `server-utils`, `client-utils`, `tensor-webgpu`, `vision`, `tsconfig`.
- `nodes/node-*`: one VFX/audio/layout node each (`src/shared/`, `src/renderers/`, `src/index.ts`). Only `node-compositor` has a `SKILL.md`; update it when Compositor behavior changes (guarded by `skillmd-check.test.ts`). Effect renderers declare `reach` and `maxPixelScale` (node-sdk) when they can: without `maxPixelScale` a scaled-up leaf using the effect stays at layout resolution.
diff --git a/nodes/node-compositor/SKILL.md b/nodes/node-compositor/SKILL.md
index d7e58793..5f50822d 100644
--- a/nodes/node-compositor/SKILL.md
+++ b/nodes/node-compositor/SKILL.md
@@ -232,7 +232,7 @@ Each track represents animatable property modifications:
- **Joint poses and aims (`pose`, `aim` on a glTF `model3d`):** after clip layers, `pose` (joint name → Euler degrees Z·Y·X and offsets, `additive` over the animated pose or from `rest`, weighted) then `aim` (bone toward its first child, or `axis`, swung onto a scene direction mapped into model space) run before look-at and IK. Joint names match exactly, else without a namespace prefix and case. Every number in `pose`, `aim`, `ik`, `lookAt` and clip weights is a track (number, keys, function, or a signal read with the render's clock); points take one track per axis. Readers are shared with the SDK (`numberAt` / `vec3At` in `compositions/program/track-sampler.ts`).
- **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, in the layer's parent space, as physics reads its x/y/z): node matrix L⁻¹ · T(p) · R(q) · S, with L the layer's own prop matrix, so pieces stay in their 3D group. While every piece is still at its frame-0 pose (or there is no track) it draws in the exact rest pose with the cut faces skipped, so the whole layer is sealed (a cut face can otherwise tie the surface's depth where pieces meet).
-- **Shutter motion blur (`motionBlur` on the camera):** after the color pass (and fog, DoF), the queued meshes and planes are drawn again into a velocity target, with this and the previous frame's model matrices, skinning, instance records (GPU copies), wind and crowd time, and this and the previous camera. Then the scene is blurred (tile max, neighbor max, gather) before bloom. Previous state lives in a per-render motion history keyed by node id and item index. When frame f - 1 is missing, the compositor first renders it with `motionHistoryOnly` (3D passes only record), so output does not depend on render order.
+- **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 and deformed vertices (morphs, audio deformation; GPU copies), wind and crowd time, and this and the previous camera. Slug text planes draw per-glyph velocity from copied glyph records. 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; meshes still deform, and every layer in the 3D scene, including ones placed by `z` alone, is recorded), 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/motion-history.ts b/nodes/node-compositor/src/renderers/motion-history.ts
index 893bc32c..6f2a5b51 100644
--- a/nodes/node-compositor/src/renderers/motion-history.ts
+++ b/nodes/node-compositor/src/renderers/motion-history.ts
@@ -2,8 +2,9 @@
* 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.
+ * records and deformed vertices (morph targets, audio deformation) are
+ * copied on the GPU, where they are made, 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.
*/
@@ -12,6 +13,7 @@ import type {
Mat4,
MeshMotionPrev,
MeshWind,
+ SlugGlyphBatch,
} from "@framefields/webgpu-renderers";
export interface MeshMotionState {
@@ -20,6 +22,8 @@ export interface MeshMotionState {
skinning?: Float32Array;
/** Byte size of the instance records copied for this frame. */
instanceBytes?: number;
+ /** Byte size of the deformed vertices copied for this frame. */
+ vertexBytes?: number;
windTime?: number;
crowdTime?: number;
}
@@ -29,7 +33,14 @@ export interface QuadMotionState {
modelMatrix: Mat4;
}
-type MotionState = MeshMotionState | QuadMotionState;
+/** A text plane: its matrix and its glyph batches (records copied). */
+export interface SlugMotionState {
+ kind: "slug";
+ modelMatrix: Mat4;
+ batches: SlugGlyphBatch[];
+}
+
+type MotionState = MeshMotionState | QuadMotionState | SlugMotionState;
/** Two frames of one value: the latest and the one before it. */
class Slots<T> {
@@ -57,12 +68,16 @@ class Slots<T> {
export class MotionHistory {
private readonly states = new Map<string, Slots<MotionState>>();
- private readonly instances = new Map<string, [GPUBuffer?, GPUBuffer?]>();
+ private readonly instances: GpuPairs;
+ private readonly vertices: GpuPairs;
private readonly camera = new Slots<Camera3DPose>();
/** Frames recorded, latest last (two kept). */
private readonly frames = new Slots<true>();
- constructor(private readonly device: GPUDevice) {}
+ constructor(device: GPUDevice) {
+ this.instances = new GpuPairs(device, "Instances");
+ this.vertices = new GpuPairs(device, "Vertices");
+ }
/** Whether rendering `frame` must render `frame - 1` first to know its motion. */
needsPrevious(frame: number): boolean {
@@ -80,6 +95,8 @@ export class MotionHistory {
now: {
skinning?: Float32Array;
instanceBuffer?: GPUBuffer;
+ /** Byte size of this frame's deformed vertices, when the GPU deforms the mesh. */
+ vertexBytes?: number;
wind?: MeshWind;
crowd?: MeshMotionPrev["crowd"];
},
@@ -92,7 +109,7 @@ export class MotionHistory {
if (now.skinning && prev.skinning?.length === now.skinning.length) {
out.skinningMatrices = prev.skinning;
}
- const copy = this.instances.get(key)?.[(frame - 1) & 1];
+ const copy = this.instances.at(key, frame - 1);
if (
now.instanceBuffer &&
copy &&
@@ -100,6 +117,10 @@ export class MotionHistory {
) {
out.instanceBuffer = copy;
}
+ const vertices = this.vertices.at(key, frame - 1);
+ if (now.vertexBytes && vertices && prev.vertexBytes === now.vertexBytes) {
+ out.vertexBuffer = vertices;
+ }
if (now.wind && prev.windTime !== undefined) {
out.wind = { ...now.wind, time: prev.windTime };
}
@@ -114,37 +135,73 @@ export class MotionHistory {
return prev?.kind === "quad" ? prev.modelMatrix : undefined;
}
- /** Records a mesh at `frame`; its instance records are copied in `encoder`. */
+ /**
+ * Records a mesh at `frame`; its instance records and deformed vertices
+ * (when the GPU deforms it) are copied in `encoder`.
+ */
recordMesh(
encoder: GPUCommandEncoder,
key: string,
frame: number,
- state: Omit<MeshMotionState, "kind" | "instanceBytes">,
- instanceBuffer: GPUBuffer | undefined,
+ state: Omit<MeshMotionState, "kind" | "instanceBytes" | "vertexBytes">,
+ buffers: {
+ instanceBuffer?: GPUBuffer;
+ /** Deformed vertices and their byte size (the buffer may be pooled and larger). */
+ vertices?: { buffer: GPUBuffer; bytes: number };
+ },
): void {
- let instanceBytes: number | undefined;
+ const { instanceBuffer, vertices } = buffers;
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.instances.copy(
+ encoder,
+ key,
+ frame,
+ instanceBuffer,
+ instanceBuffer.size,
+ GPUBufferUsage.STORAGE,
+ );
+ }
+ if (vertices) {
+ this.vertices.copy(
+ encoder,
+ key,
+ frame,
+ vertices.buffer,
+ vertices.bytes,
+ GPUBufferUsage.VERTEX,
+ );
}
this.slots(key).write(frame, {
kind: "mesh",
...state,
...(state.skinning && { skinning: state.skinning.slice() }),
- instanceBytes,
+ instanceBytes: instanceBuffer?.size,
+ vertexBytes: vertices?.bytes,
+ });
+ }
+
+ previousSlug(
+ key: string,
+ frame: number,
+ ): Omit<SlugMotionState, "kind"> | undefined {
+ const prev = this.states.get(key)?.at(frame - 1);
+ return prev?.kind === "slug" ? prev : undefined;
+ }
+
+ /** Records a text plane at `frame`; glyph records are copied (batches are rebuilt each frame). */
+ recordSlug(
+ key: string,
+ frame: number,
+ modelMatrix: Mat4,
+ batches: SlugGlyphBatch[],
+ ): void {
+ this.slots(key).write(frame, {
+ kind: "slug",
+ modelMatrix,
+ batches: batches.map((b) => ({
+ ...b,
+ instances: b.instances.slice(0, b.instanceCount * 24),
+ })),
});
}
@@ -167,6 +224,44 @@ export class MotionHistory {
}
}
+/** GPU copies of a buffer per key, one per frame parity. */
+class GpuPairs {
+ private readonly pairs = new Map<string, [GPUBuffer?, GPUBuffer?]>();
+
+ constructor(
+ private readonly device: GPUDevice,
+ private readonly label: string,
+ ) {}
+
+ at(key: string, frame: number): GPUBuffer | undefined {
+ return this.pairs.get(key)?.[frame & 1];
+ }
+
+ copy(
+ encoder: GPUCommandEncoder,
+ key: string,
+ frame: number,
+ source: GPUBuffer,
+ bytes: number,
+ usage: GPUBufferUsageFlags,
+ ): void {
+ const pair = this.pairs.get(key) ?? [];
+ const slot = frame & 1;
+ let copy = pair[slot];
+ if (!copy || copy.size !== bytes) {
+ copy?.destroy();
+ copy = this.device.createBuffer({
+ label: `MotionHistory${this.label}:${key}`,
+ size: bytes,
+ usage: usage | GPUBufferUsage.COPY_DST,
+ });
+ pair[slot] = copy;
+ this.pairs.set(key, pair);
+ }
+ encoder.copyBufferToBuffer(source, 0, copy, 0, bytes);
+ }
+}
+
const histories = new Map<string, MotionHistory>();
/** The motion history of one composition render (by render id). */
diff --git a/nodes/node-compositor/src/renderers/webgpu-renderer.ts b/nodes/node-compositor/src/renderers/webgpu-renderer.ts
index 485b9fb0..58170994 100644
--- a/nodes/node-compositor/src/renderers/webgpu-renderer.ts
+++ b/nodes/node-compositor/src/renderers/webgpu-renderer.ts
@@ -157,6 +157,11 @@ function textInkOutset(
return reach > 0 ? Math.ceil(reach) + 1 : 0;
}
+/** Bytes of a mesh's vertex buffer: 16 floats per vertex. */
+function deformedBytes(mesh: Mesh3DData): number {
+ return (mesh.positions.length / 3) * 64;
+}
+
function hasVertexAlpha(mesh: Mesh3DData): boolean {
const cached = meshHasAlpha.get(mesh);
if (cached !== undefined) return cached;
@@ -1675,10 +1680,23 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
windTime: item.opts.wind?.time,
crowdTime: item.opts.crowd?.time,
},
- item.opts.instanceBuffer,
+ {
+ instanceBuffer: item.opts.instanceBuffer,
+ vertices: item.meshBuffers && {
+ buffer: item.meshBuffers.vertexBuffer,
+ bytes: deformedBytes(item.mesh),
+ },
+ },
);
} else if (item.kind === "quad") {
h.recordQuad(key, shiftedFrame, r3d.quadModelMatrix(item.opts));
+ } else {
+ h.recordSlug(
+ key,
+ shiftedFrame,
+ r3d.quadModelMatrix(item.opts),
+ item.batches,
+ );
}
}
h.recordFrame(shiftedFrame, cam);
@@ -1711,6 +1729,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
? h.previousMesh(key, shiftedFrame, {
skinning: item.opts.skinningMatrices,
instanceBuffer: item.opts.instanceBuffer,
+ vertexBytes: item.meshBuffers && deformedBytes(item.mesh),
wind: item.opts.wind,
crowd: item.opts.crowd,
})
@@ -1731,6 +1750,15 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
item.opts,
key ? h.previousQuad(key, shiftedFrame) : undefined,
);
+ } else {
+ r3d.drawSlugVelocity(
+ vel.pass,
+ vel.cameraBindGroup,
+ item.batches,
+ item.opts,
+ item.stackBase,
+ key ? h.previousSlug(key, shiftedFrame) : undefined,
+ );
}
}
vel.pass.end();
@@ -1749,19 +1777,15 @@ 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,
ctx.renderer.format ?? "rgba8unorm",
sampleCount3d,
);
- // Morph targets are applied in object space before audio deformation and skinning.
+ // Morph targets are applied in object space before audio deformation
+ // and skinning. A history-only frame deforms too: motion blur keeps
+ // the deformed vertices as the next frame's past.
for (const item of pending3DItems) {
if (item.kind !== "mesh") continue;
if (item.opts.morphWeights?.length) {
@@ -1783,6 +1807,12 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
}
}
+ if (historyOnly) {
+ if (history) recordMotion(history, camera);
+ pending3DItems.length = 0;
+ return { finalTex: curTex, finalView: curView };
+ }
+
const itemTextures = pendingTextures();
const scene3dTex = ctx.renderer.getTemporaryTexture(
@@ -2666,12 +2696,17 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
return;
}
}
+ // A layer in the 3D scene: flagged, or placed off the z = 0 plane.
+ const isTrue3D =
+ Boolean(target?.is3D ?? lop.is3D) ||
+ Boolean(camera && ((target?.z ?? lop.z ?? 0) !== 0 || lop.is3D));
// Recording motion needs only the 3D draws: flat leaves (video,
// text, effects) skip their work in the history pass.
if (
historyOnly &&
!isContainer &&
kind !== "model3d" &&
+ !isTrue3D &&
!has3DTransform(target, lop)
)
return;
@@ -4294,10 +4329,6 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
quad3D = q;
}
- const isTrue3D =
- Boolean(target?.is3D ?? lop.is3D) ||
- Boolean(camera && ((target?.z ?? lop.z ?? 0) !== 0 || lop.is3D));
-
// Container rendering
if (isContainer) {
if (lop.transformStyle === "preserve-3d" && isTrue3D) {
diff --git a/packages/compositions/src/program/lint.test.ts b/packages/compositions/src/program/lint.test.ts
index 714278c7..730a633d 100644
--- a/packages/compositions/src/program/lint.test.ts
+++ b/packages/compositions/src/program/lint.test.ts
@@ -108,6 +108,11 @@ describe("lintComposition", () => {
]);
expect(c).toContain("shadow_unsupported_light");
expect(c).toContain("pbr_without_environment");
+ // Layered lobes alone need the environment too.
+ for (const lobe of [{ clearcoat: 1 }, { anisotropy: 0.6 }])
+ expect(codes([{ id: "c", kind: "model3d", ...lobe }])).toContain(
+ "pbr_without_environment",
+ );
expect(
codes([
{ id: "e", kind: "light", lightType: "environment" },
diff --git a/packages/compositions/src/program/lint.ts b/packages/compositions/src/program/lint.ts
index cb1e9db0..6cb0aacf 100644
--- a/packages/compositions/src/program/lint.ts
+++ b/packages/compositions/src/program/lint.ts
@@ -245,7 +245,13 @@ export function lintComposition(
`'${id}' scatters onto a surface its slopeRange / elevationRange filters reject entirely, so no instance is placed. Widen the ranges (slope is degrees from level, elevation 0..1 from the surface's lowest to highest point).`,
id,
);
- if (node.roughness !== undefined || node.metallic !== undefined)
+ // Physical and layered specular lobes read the environment's light.
+ if (
+ node.roughness !== undefined ||
+ node.metallic !== undefined ||
+ node.clearcoat !== undefined ||
+ node.anisotropy !== undefined
+ )
pbrNodes.push(id);
// Text that vanishes into what is behind it.
@@ -389,7 +395,7 @@ export function lintComposition(
push(
"info",
"pbr_without_environment",
- `roughness / metallic are set (${pbrNodes.slice(0, 3).join(", ")}${pbrNodes.length > 3 ? ", …" : ""}) but the scene has no Layer.environment(): add one for physically based shading, reflections and tone mapping.`,
+ `roughness / metallic / clearcoat / anisotropy are set (${pbrNodes.slice(0, 3).join(", ")}${pbrNodes.length > 3 ? ", …" : ""}) but the scene has no Layer.environment(): add one for physically based shading, the coat and brushed-metal reflections, and tone mapping.`,
);
}
return out;
diff --git a/packages/forge/src/gizmo.ts b/packages/forge/src/gizmo.ts
deleted file mode 100644
index ea9137fc..00000000
--- a/packages/forge/src/gizmo.ts
+++ /dev/null
@@ -1,84 +0,0 @@
-/**
- * A skeleton drawn as octahedral bones, each rigidly skinned to its joint:
- * the classic DCC bone display, for checking a rig's rest pose and its
- * motion before there is a body.
- */
-import type { PrimitiveSpec } from "./document.js";
-import type { Skeleton, Vec3 } from "./skeleton.js";
-
-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 norm = (v: Vec3): Vec3 => {
- const l = Math.hypot(v[0], v[1], v[2]) || 1;
- return [v[0] / l, v[1] / l, v[2] / l];
-};
-
-export interface BoneGizmoOptions {
- /** Bone width as a fraction of its length. Default 0.12. */
- width?: number;
-}
-
-/**
- * One octahedron per parent → child bone (flat-shaded), weighted fully to
- * the parent joint; skin indices are the skeleton's joint order, as
- * `GltfDocument.addSkeleton` writes them.
- */
-export function boneGizmo(
- skeleton: Skeleton,
- options: BoneGizmoOptions = {},
-): Required<
- Pick<PrimitiveSpec, "positions" | "normals" | "joints" | "weights">
-> {
- const width = options.width ?? 0.12;
- const positions: number[] = [];
- const normals: number[] = [];
- const joints: number[] = [];
- const weights: number[] = [];
- for (const child of skeleton.joints) {
- if (child.parent === undefined) continue;
- const parent = skeleton.joint(child.parent);
- const axis = sub(child.at, parent.at);
- const len = Math.hypot(axis[0], axis[1], axis[2]);
- if (len < 1e-6) continue;
- const d = norm(axis);
- const helper: Vec3 = Math.abs(d[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0];
- const u = norm(cross(d, helper));
- const v = cross(d, u);
- const r = len * width;
- const ring = [0, 1, 2, 3].map((k): Vec3 => {
- const a = (k * Math.PI) / 2;
- return [
- parent.at[0] +
- d[0] * len * 0.15 +
- (u[0] * Math.cos(a) + v[0] * Math.sin(a)) * r,
- parent.at[1] +
- d[1] * len * 0.15 +
- (u[1] * Math.cos(a) + v[1] * Math.sin(a)) * r,
- parent.at[2] +
- d[2] * len * 0.15 +
- (u[2] * Math.cos(a) + v[2] * Math.sin(a)) * r,
- ];
- });
- for (let k = 0; k < 4; k++) {
- const a = ring[k] as Vec3;
- const b = ring[(k + 1) % 4] as Vec3;
- for (const [p, q, s] of [
- [parent.at, b, a],
- [child.at, a, b],
- ] as [Vec3, Vec3, Vec3][]) {
- const n = norm(cross(sub(q, p), sub(s, p)));
- for (const pt of [p, q, s]) {
- positions.push(...pt);
- normals.push(...n);
- joints.push(parent.index, 0, 0, 0);
- weights.push(1, 0, 0, 0);
- }
- }
- }
- }
- return { positions, normals, joints, weights };
-}
diff --git a/packages/forge/src/humanoid.ts b/packages/forge/src/humanoid.ts
deleted file mode 100644
index 6ad9a9b7..00000000
--- a/packages/forge/src/humanoid.ts
+++ /dev/null
@@ -1,136 +0,0 @@
-/**
- * A proportioned human skeleton on Mixamo joint names, so clips, `pose`,
- * `aim` and pose retargeting (`rig: "mixamo"`) drive it unchanged.
- * Proportions are classical figure-drawing ratios measured in head
- * heights; stylized characters change `heads` (8 is heroic, 6 is stocky)
- * and the width multipliers.
- */
-import { Skeleton, type Vec3 } from "./skeleton.js";
-
-export interface HumanoidOptions {
- /** Standing height, top of the head to the soles, model units. Default 180. */
- height?: number;
- /** Height in head heights: 7.5 natural, 8 heroic, 6 stocky. Default 7.5. */
- heads?: number;
- /** Multiplies the shoulder width. Default 1. */
- shoulderWidth?: number;
- /** Multiplies the hip width. Default 1. */
- hipWidth?: number;
- /** Arms' angle below horizontal at rest: 0 is a T-pose. Default 45 (an A-pose, which skins better). */
- armAngle?: number;
- /** Thumb and four fingers, three bones each. Default true. */
- fingers?: boolean;
- /** Toe joints. Default true. */
- toes?: boolean;
- /** Joint name prefix, e.g. "mixamorig:". Default none. */
- prefix?: string;
-}
-
-const add = (a: Vec3, b: Vec3, s = 1): Vec3 => [
- a[0] + b[0] * s,
- a[1] + b[1] * s,
- a[2] + b[2] * s,
-];
-const unit = (v: Vec3): Vec3 => {
- const l = Math.hypot(v[0], v[1], v[2]);
- return [v[0] / l, v[1] / l, v[2] / l];
-};
-
-/** Bone lengths of each finger as fractions of the hand, and its spread across the palm (fraction of height, +z is the thumb side). */
-const FINGERS = [
- { name: "Index", spread: 0.012, lengths: [0.21, 0.13, 0.1] },
- { name: "Middle", spread: 0.004, lengths: [0.23, 0.15, 0.11] },
- { name: "Ring", spread: -0.004, lengths: [0.21, 0.14, 0.1] },
- { name: "Pinky", spread: -0.012, lengths: [0.17, 0.11, 0.09] },
-] as const;
-
-/**
- * A humanoid skeleton standing on y = 0, facing +z, its left at +x. Joint
- * names follow Mixamo: Hips, Spine, Spine1, Spine2, Neck, Head,
- * HeadTop_End; Left/Right Shoulder, Arm, ForeArm, Hand, HandThumb1–4,
- * HandIndex1–4 …; UpLeg, Leg, Foot, ToeBase, Toe_End.
- */
-export function humanoidSkeleton(options: HumanoidOptions = {}): Skeleton {
- const H = options.height ?? 180;
- const heads = options.heads ?? 7.5;
- const sw = options.shoulderWidth ?? 1;
- const hw = options.hipWidth ?? 1;
- const p = options.prefix ?? "";
- const n = (name: string) => `${p}${name}`;
- const head = H / heads;
- const k = (f: number) => f * H;
-
- const s = new Skeleton();
- s.add(n("Hips"), { at: [0, k(0.53), 0] });
- s.add(n("Spine"), { at: [0, k(0.585), -k(0.004)], parent: n("Hips") });
- s.add(n("Spine1"), { at: [0, k(0.645), -k(0.008)], parent: n("Spine") });
- s.add(n("Spine2"), { at: [0, k(0.715), -k(0.008)], parent: n("Spine1") });
- s.add(n("Neck"), {
- at: [0, H - 1.25 * head, -k(0.006)],
- parent: n("Spine2"),
- });
- s.add(n("Head"), { at: [0, H - 0.78 * head, k(0.004)], parent: n("Neck") });
- s.add(n("HeadTop_End"), { at: [0, H, k(0.004)], parent: n("Head") });
-
- // Arms hang from the shoulder line, about 1.45 heads below the crown.
- const shoulderY = H - 1.45 * head;
- const angle = ((options.armAngle ?? 45) * Math.PI) / 180;
- const down: Vec3 = [Math.cos(angle), -Math.sin(angle), 0];
- const arm: Vec3 = [k(0.105) * sw, shoulderY, -k(0.006)];
- const elbow = add(arm, down, k(0.186));
- const wrist = add(elbow, down, k(0.146));
- const hand = k(0.108);
- s.add(n("LeftShoulder"), {
- at: [k(0.022) * sw, shoulderY + k(0.012), -k(0.006)],
- parent: n("Spine2"),
- });
- s.add(n("LeftArm"), { at: arm, parent: n("LeftShoulder") });
- s.add(n("LeftForeArm"), { at: elbow, parent: n("LeftArm") });
- s.add(n("LeftHand"), { at: wrist, parent: n("LeftForeArm") });
-
- if (options.fingers ?? true) {
- const knuckles = add(wrist, down, 0.45 * hand);
- for (const f of FINGERS) {
- let at = add(knuckles, [0, 0, 1], k(f.spread));
- const points: Vec3[] = [at];
- for (const len of f.lengths) {
- at = add(at, down, len * hand);
- points.push(at);
- }
- s.chain(n(`LeftHand${f.name}`), points, { parent: n("LeftHand") });
- }
- // The thumb leaves the palm forward and down, across the index.
- const thumbDir = unit(add(add(down, [0, 0, 1], 0.9), [0, -1, 0], 0.25));
- let at = add(add(wrist, down, 0.12 * hand), [0, 0, 1], k(0.012));
- const thumb: Vec3[] = [at];
- for (const len of [0.2, 0.17, 0.13]) {
- at = add(at, thumbDir, len * hand);
- thumb.push(at);
- }
- s.chain(n("LeftHandThumb"), thumb, { parent: n("LeftHand") });
- }
-
- // Hip joints sit about 9 cm from the midline on a 180 cm figure; knees
- // come in under them and the feet stand about hip-width apart.
- const hipX = k(0.051) * hw;
- s.add(n("LeftUpLeg"), { at: [hipX, k(0.5), 0], parent: n("Hips") });
- s.add(n("LeftLeg"), {
- at: [hipX * 0.92, k(0.282), k(0.008)],
- parent: n("LeftUpLeg"),
- });
- s.add(n("LeftFoot"), {
- at: [hipX * 0.98, k(0.045), -k(0.01)],
- parent: n("LeftLeg"),
- });
- if (options.toes ?? true) {
- s.add(n("LeftToeBase"), {
- at: [hipX * 1.08, k(0.012), k(0.095)],
- parent: n("LeftFoot"),
- });
- s.add(n("LeftToe_End"), {
- at: [hipX * 1.12, k(0.012), k(0.145)],
- parent: n("LeftToeBase"),
- });
- }
- return s.mirror({ from: "Left", to: "Right" });
-}
diff --git a/packages/forge/src/index.ts b/packages/forge/src/index.ts
deleted file mode 100644
index 45063a47..00000000
--- a/packages/forge/src/index.ts
+++ /dev/null
@@ -1,86 +0,0 @@
-/**
- * `framefields/forge`: rigged characters and props built in code, written
- * as standard GLB files that `Layer.glb` (and every other glTF tool) loads.
- */
-export {
- type ColorInput,
- displayRgba,
- linearRgb,
- linearRgba,
-} from "./color.js";
-export {
- type AnimationPath,
- type AnimationSpec,
- type ChannelSpec,
- type DriverSpec,
- GltfDocument,
- type MaterialRef,
- type MeshRef,
- type MeshSpec,
- type MorphTargetSpec,
- type NodeRef,
- type NodeSpec,
- type PrimitiveSpec,
- type SkeletonRefs,
- type SkinRef,
- type TextureSpec,
-} from "./document.js";
-export { type BoneGizmoOptions, boneGizmo } from "./gizmo.js";
-export {
- type AccessorData,
- type AccessorOptions,
- type AccessorType,
- GlbBuilder,
-} from "./glb-builder.js";
-export { type HumanoidOptions, humanoidSkeleton } from "./humanoid.js";
-export {
- type MaterialSpec,
- materialJson,
- type TextureRef,
- type TextureSlot,
-} from "./material.js";
-export { encodePng } from "./png.js";
-export {
- type Displacement,
- type Part,
- type PartOp,
- SculptField,
-} from "./sculpt/field.js";
-export {
- type LimbOptions,
- limb,
- type MirrorPartsOptions,
- mirrorParts,
-} from "./sculpt/helpers.js";
-export {
- type IndexedMesh,
- meshDefects,
- meshField,
- meshVolume,
-} from "./sculpt/mesh.js";
-export { Noise3 } from "./sculpt/noise.js";
-export {
- type SculptOptions,
- type SculptReport,
- type SculptResult,
- sculpt,
-} from "./sculpt/sculpt.js";
-export type { Shape } from "./sculpt/shapes.js";
-export { type SimplifyOptions, simplify } from "./sculpt/simplify.js";
-export {
- type Joint,
- type JointSpec,
- type MirrorOptions,
- type Quat,
- quatConjugate,
- quatMultiply,
- quatRotate,
- Skeleton,
- type Vec3,
-} from "./skeleton.js";
-export {
- type SubdivideOptions,
- smoothNormals,
- subdivide,
-} from "./subdivide.js";
-export { computeTangents } from "./tangents.js";
diff --git a/packages/forge/src/sculpt/borders.ts b/packages/forge/src/sculpt/borders.ts
deleted file mode 100644
index fc27d5f2..00000000
--- a/packages/forge/src/sculpt/borders.ts
+++ /dev/null
@@ -1,139 +0,0 @@
-/**
- * Smooth material borders. Each vertex takes the material of the part that
- * owns the surface there; a triangle whose corners disagree is cut where
- * ownership changes along its edges (found by bisection with the field's
- * own rule, then projected onto the surface), so a sleeve or collar ends
- * on a clean curve instead of the triangles' staircase.
- */
-import type { Vec3 } from "../skeleton.js";
-import type { SculptField } from "./field.js";
-import { type IndexedMesh, project } from "./mesh.js";
-
-export interface TaggedMesh extends IndexedMesh {
- /** Per-triangle material id. */
- tags: Int32Array;
-}
-
-/** Per-vertex material ids by the field's owner at each vertex. */
-export function vertexMaterials(
- field: SculptField,
- positions: Float64Array,
- materialOf: (part: number) => number,
-): Int32Array {
- const n = positions.length / 3;
- const out = new Int32Array(n);
- for (let v = 0; v < n; v++) {
- field.distance(
- positions[v * 3] as number,
- positions[v * 3 + 1] as number,
- positions[v * 3 + 2] as number,
- );
- out[v] = materialOf(field.owner);
- }
- return out;
-}
-
-/** Each triangle's material: the one most of its corners have (the first corner's on a three-way tie). */
-export function majorityTags(
- indices: Uint32Array,
- materials: Int32Array,
-): Int32Array {
- const tags = new Int32Array(indices.length / 3);
- for (let f = 0; f < tags.length; f++) {
- const a = materials[indices[f * 3] as number] as number;
- const b = materials[indices[f * 3 + 1] as number] as number;
- const c = materials[indices[f * 3 + 2] as number] as number;
- tags[f] = b === c ? b : a;
- }
- return tags;
-}
-
-/** The mesh with every two-material triangle cut along its border. */
-export function splitBorders(
- field: SculptField,
- mesh: IndexedMesh,
- materialOf: (part: number) => number,
- cell: number,
-): TaggedMesh {
- const positions = Array.from(mesh.positions);
- const mats = Array.from(vertexMaterials(field, mesh.positions, materialOf));
- const indices: number[] = [];
- const tags: number[] = [];
- const cut = new Map<number, number>();
- const nv0 = mesh.positions.length / 3;
-
- const pos = (v: number): Vec3 => [
- positions[v * 3] as number,
- positions[v * 3 + 1] as number,
- positions[v * 3 + 2] as number,
- ];
- /** The border point on edge (a, b), shared by both triangles of the edge. */
- const border = (a: number, b: number): number => {
- const key = a < b ? a * nv0 + b : b * nv0 + a;
- const found = cut.get(key);
- if (found !== undefined) return found;
- const pa = pos(a);
- const pb = pos(b);
- const ma = mats[a] as number;
- let lo = 0;
- let hi = 1;
- for (let it = 0; it < 12; it++) {
- const t = (lo + hi) / 2;
- field.distance(
- pa[0] + (pb[0] - pa[0]) * t,
- pa[1] + (pb[1] - pa[1]) * t,
- pa[2] + (pb[2] - pa[2]) * t,
- );
- if (materialOf(field.owner) === ma) lo = t;
- else hi = t;
- }
- const t = (lo + hi) / 2;
- const p: Vec3 = [
- pa[0] + (pb[0] - pa[0]) * t,
- pa[1] + (pb[1] - pa[1]) * t,
- pa[2] + (pb[2] - pa[2]) * t,
- ];
- project(field, p, cell, field.relevant(p, cell));
- const v = positions.length / 3;
- positions.push(p[0], p[1], p[2]);
- mats.push(-1);
- cut.set(key, v);
- return v;
- };
-
- for (let f = 0; f < mesh.indices.length; f += 3) {
- const tri = [mesh.indices[f], mesh.indices[f + 1], mesh.indices[f + 2]] as [
- number,
- number,
- number,
- ];
- const m = tri.map((v) => mats[v] as number) as [number, number, number];
- if (m[0] === m[1] && m[1] === m[2]) {
- indices.push(...tri);
- tags.push(m[0]);
- continue;
- }
- if (m[0] !== m[1] && m[1] !== m[2] && m[0] !== m[2]) {
- // Three materials meet: rare at lattice scale; keep the triangle whole.
- indices.push(...tri);
- tags.push(m[0]);
- continue;
- }
- // Rotate so the odd corner is first: (a | b, c).
- const odd = m[1] === m[2] ? 0 : m[0] === m[2] ? 1 : 2;
- const a = tri[odd];
- const b = tri[(odd + 1) % 3];
- const c = tri[(odd + 2) % 3];
- const pab = border(a, b);
- const pac = border(a, c);
- indices.push(a, pab, pac);
- tags.push(m[odd]);
- indices.push(pab, b, c, pab, c, pac);
- tags.push(m[(odd + 1) % 3], m[(odd + 1) % 3]);
- }
- return {
- positions: Float64Array.from(positions),
- indices: Uint32Array.from(indices),
- tags: Int32Array.from(tags),
- };
-}
diff --git a/packages/forge/src/sculpt/field.ts b/packages/forge/src/sculpt/field.ts
deleted file mode 100644
index dff6d68e..00000000
--- a/packages/forge/src/sculpt/field.ts
+++ /dev/null
@@ -1,324 +0,0 @@
-/**
- * The sculpt's field: parts combined in order by hard or smooth unions,
- * cuts and intersections (Quilez's polynomial smooth min / max), each part
- * a shape in its own frame with optional twist, bend and noise detail. A
- * part belongs to a joint (or several), a material and a color, so the
- * same evaluation that places the surface tells skinning which bones move
- * it and which material it is.
- */
-import { type ColorInput, linearRgba } from "../color.js";
-import type { MaterialRef } from "../document.js";
-import type { Vec3 } from "../skeleton.js";
-import { Noise3 } from "./noise.js";
-import { type Shape, type ShapeField, shapeField } from "./shapes.js";
-
-export type PartOp = "union" | "subtract" | "intersect";
-
-export interface Displacement {
- /** Height of the detail, model units (outward positive). */
- amplitude: number;
- /** Feature size, model units. */
- scale: number;
- /** Default 3. */
- octaves?: number;
- /** Default 0. */
- seed?: number;
-}
-
-interface PartOptions {
- /** Name for reports and errors. */
- name?: string;
- /** Where the shape's frame sits in model space. Default the origin. */
- at?: Vec3;
- /** Euler degrees [x, y, z] (applied Z, then Y, then X, like layers). */
- rotation?: Vec3;
- /** How this part combines with every part before it. Default "union". */
- op?: PartOp;
- /** Radius of the smooth join with what came before, model units. Default 0 (a hard edge). */
- blend?: number;
- /**
- * The joint (or joints, shared by distance to their bones) that moves
- * this part. Default: the joint whose bone passes nearest the part.
- */
- joint?: string | string[];
- /** Moves with its joint only, with no blending into neighbors (armor plates, buckles). */
- rigid?: boolean;
- /** How far the part's skin influence reaches past its own surface. Default: its `blend`, at least 1.5 cells. */
- falloff?: number;
- material?: MaterialRef;
- /** Vertex color (display sRGB); blends across smooth joins. */
- color?: ColorInput;
- displace?: Displacement;
- /** Turns about the local y axis, degrees per model unit. */
- twist?: number;
- /** Bends the local y axis toward +x, degrees per model unit. */
- bend?: number;
-}
-
-/** A shape placed in the sculpt with how it joins, moves and looks. */
-export type Part = Shape & PartOptions;
-
-export interface PreparedPart {
- readonly part: Part;
- readonly index: number;
- readonly op: PartOp;
- readonly k: number;
- /** Bounding sphere in model space. */
- readonly center: Vec3;
- readonly radius: number;
- readonly color: [number, number, number, number] | undefined;
- /** Upper bound on how much faster than 1 per unit the part's field changes. */
- readonly lipschitz: number;
- distance(x: number, y: number, z: number): number;
- /** The part's own point in model space for picking its joint. */
- readonly anchor: Vec3;
-}
-
-function rotationRows(deg: Vec3 | undefined): number[] | null {
- if (!deg || (deg[0] === 0 && deg[1] === 0 && deg[2] === 0)) return null;
- const [x, y, z] = deg.map((d) => (d * Math.PI) / 180) as Vec3;
- const cx = Math.cos(x);
- const sx = Math.sin(x);
- const cy = Math.cos(y);
- const sy = Math.sin(y);
- const cz = Math.cos(z);
- const sz = Math.sin(z);
- // R = Rz·Ry·Rx, row-major.
- return [
- cz * cy,
- cz * sy * sx - sz * cx,
- cz * sy * cx + sz * sx,
- sz * cy,
- sz * sy * sx + cz * cx,
- sz * sy * cx - cz * sx,
- -sy,
- cy * sx,
- cy * cx,
- ];
-}
-
-const DEG = Math.PI / 180;
-
-function prepare(part: Part, index: number): PreparedPart {
- const shape: ShapeField = shapeField(part);
- const at = part.at ?? [0, 0, 0];
- const r = rotationRows(part.rotation);
- const toModel = (p: Vec3): Vec3 =>
- r
- ? [
- at[0] +
- (r[0] as number) * p[0] +
- (r[1] as number) * p[1] +
- (r[2] as number) * p[2],
- at[1] +
- (r[3] as number) * p[0] +
- (r[4] as number) * p[1] +
- (r[5] as number) * p[2],
- at[2] +
- (r[6] as number) * p[0] +
- (r[7] as number) * p[1] +
- (r[8] as number) * p[2],
- ]
- : [at[0] + p[0], at[1] + p[1], at[2] + p[2]];
- const twist = (part.twist ?? 0) * DEG;
- const bend = (part.bend ?? 0) * DEG;
- const noise = part.displace ? new Noise3(part.displace.seed ?? 0) : null;
- const amp = part.displace?.amplitude ?? 0;
- const freq = part.displace ? 1 / part.displace.scale : 0;
- const octaves = part.displace?.octaves ?? 3;
- const reach = shape.radius + Math.abs(shape.center[1]);
- // Twist and bend stretch space by up to the turn across the part.
- const lipschitz =
- 1 +
- Math.abs(twist) * reach +
- Math.abs(bend) * reach +
- amp * freq * 2.5 * octaves;
- const distance = (x: number, y: number, z: number): number => {
- let lx = x - at[0];
- let ly = y - at[1];
- let lz = z - at[2];
- if (r) {
- const tx =
- (r[0] as number) * lx + (r[3] as number) * ly + (r[6] as number) * lz;
- const ty =
- (r[1] as number) * lx + (r[4] as number) * ly + (r[7] as number) * lz;
- const tz =
- (r[2] as number) * lx + (r[5] as number) * ly + (r[8] as number) * lz;
- lx = tx;
- ly = ty;
- lz = tz;
- }
- if (twist) {
- const a = -twist * ly;
- const c = Math.cos(a);
- const s = Math.sin(a);
- const tx = c * lx - s * lz;
- lz = s * lx + c * lz;
- lx = tx;
- }
- if (bend) {
- const a = bend * ly;
- const c = Math.cos(a);
- const s = Math.sin(a);
- const tx = c * lx - s * ly;
- ly = s * lx + c * ly;
- lx = tx;
- }
- let d = shape.distance(lx, ly, lz);
- if (noise) d -= amp * noise.fbm(lx * freq, ly * freq, lz * freq, octaves);
- return d;
- };
- const anchor = toModel(shape.center);
- return {
- part,
- index,
- op: part.op ?? "union",
- k: Math.max(0, part.blend ?? 0),
- center: anchor,
- radius: shape.radius * (1 + Math.abs(bend) * reach) + amp,
- color: part.color === undefined ? undefined : linearRgba(part.color),
- lipschitz,
- distance,
- anchor,
- };
-}
-
-const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);
-
-/** The composite field of an ordered list of parts. */
-export class SculptField {
- readonly parts: PreparedPart[];
- /** The field's worst-case rate of change (1 for plain shapes). */
- readonly lipschitz: number;
- /** The part that owns the surface at the last evaluated point. */
- owner = -1;
- /** The blended linear color at the last point evaluated with color. */
- readonly color: [number, number, number, number] = [1, 1, 1, 1];
- private readonly base: [number, number, number, number];
- /** Per part: the widest blend of it or any part after it. */
- private readonly reach: number[];
-
- constructor(parts: Part[], base: ColorInput = "#ffffff") {
- if (!parts.length) throw new Error("sculpt: no parts");
- if ((parts[0]?.op ?? "union") !== "union")
- throw new Error("sculpt: the first part must be a union");
- this.parts = parts.map(prepare);
- this.lipschitz = Math.max(...this.parts.map((p) => p.lipschitz));
- this.reach = new Array(this.parts.length);
- let widest = 0;
- for (let i = this.parts.length - 1; i >= 0; i--) {
- widest = Math.max(widest, (this.parts[i] as PreparedPart).k);
- this.reach[i] = widest;
- }
- this.base = linearRgba(base);
- }
-
- /** Model-space box around every union part. */
- bounds(): { min: Vec3; max: Vec3 } {
- const min: Vec3 = [Infinity, Infinity, Infinity];
- const max: Vec3 = [-Infinity, -Infinity, -Infinity];
- for (const p of this.parts) {
- if (p.op !== "union") continue;
- const r = p.radius + p.k;
- for (let a = 0; a < 3; a++) {
- min[a] = Math.min(min[a] as number, (p.center[a] as number) - r);
- max[a] = Math.max(max[a] as number, (p.center[a] as number) + r);
- }
- }
- return { min, max };
- }
-
- /**
- * Parts that can change the surface inside a sphere (`c`, `r`): unions
- * and cuts whose own surface is out of reach can't, since a smooth join
- * only acts within its blend radius.
- */
- relevant(c: Vec3, r: number): number[] {
- const out: number[] = [];
- for (const p of this.parts) {
- if (p.op === "intersect") {
- out.push(p.index);
- continue;
- }
- const gap =
- Math.hypot(c[0] - p.center[0], c[1] - p.center[1], c[2] - p.center[2]) -
- p.radius -
- r;
- // A later smooth join reads what came before within its own radius.
- if (gap <= (this.reach[p.index] as number) + r) out.push(p.index);
- }
- return out;
- }
-
- /** The field at a point over `subset` (default every part); sets `owner`, and `color` when asked. */
- distance(
- x: number,
- y: number,
- z: number,
- subset?: readonly number[],
- withColor = false,
- ): number {
- let d = Number.POSITIVE_INFINITY;
- let owner = -1;
- const color = this.color;
- if (withColor) {
- color[0] = this.base[0];
- color[1] = this.base[1];
- color[2] = this.base[2];
- color[3] = this.base[3];
- }
- const n = subset ? subset.length : this.parts.length;
- for (let i = 0; i < n; i++) {
- const p = this.parts[subset ? (subset[i] as number) : i] as PreparedPart;
- const e = p.distance(x, y, z);
- if (d === Number.POSITIVE_INFINITY) {
- if (p.op === "union") {
- d = e;
- owner = p.index;
- if (withColor && p.color) color.splice(0, 4, ...p.color);
- }
- continue;
- }
- const k = p.k;
- const o = p.op === "subtract" ? -e : e;
- let h: number;
- if (p.op === "union") {
- h = k > 0 ? clamp01(0.5 + (0.5 * (o - d)) / k) : o < d ? 0 : 1;
- d = o + (d - o) * h - k * h * (1 - h);
- } else {
- h = k > 0 ? clamp01(0.5 + (0.5 * (d - o)) / k) : d > o ? 1 : 0;
- d = o + (d - o) * h + k * h * (1 - h);
- }
- // h is the share of what came before; the part owns the surface past half.
- if (h < 0.5 && (p.op === "union" || p.part.material || p.color))
- owner = p.index;
- if (withColor) {
- const c = p.color ?? (p.op === "union" ? this.base : null);
- if (c)
- for (let a = 0; a < 4; a++)
- color[a] =
- (c[a] as number) + ((color[a] as number) - (c[a] as number)) * h;
- }
- }
- this.owner = owner;
- return d;
- }
-
- /** Unit outward normal from the central-difference gradient, step `e`. */
- normal(
- x: number,
- y: number,
- z: number,
- e: number,
- subset?: readonly number[],
- ): Vec3 {
- const gx =
- this.distance(x + e, y, z, subset) - this.distance(x - e, y, z, subset);
- const gy =
- this.distance(x, y + e, z, subset) - this.distance(x, y - e, z, subset);
- const gz =
- this.distance(x, y, z + e, subset) - this.distance(x, y, z - e, subset);
- const len = Math.hypot(gx, gy, gz) || 1;
- return [gx / len, gy / len, gz / len];
- }
-}
diff --git a/packages/forge/src/sculpt/helpers.ts b/packages/forge/src/sculpt/helpers.ts
deleted file mode 100644
index d4fed7e8..00000000
--- a/packages/forge/src/sculpt/helpers.ts
+++ /dev/null
@@ -1,114 +0,0 @@
-/**
- * Shortcuts for sculpting on a skeleton: a limb from a joint to its child,
- * and the right side from the left.
- */
-import type { Skeleton, Vec3 } from "../skeleton.js";
-import type { Part } from "./field.js";
-
-type PartExtras = Omit<Part, keyof ShapeKeys | "shape">;
-type ShapeKeys = {
- from: 0;
- to: 0;
- radii: 0;
- radius: 0;
- points: 0;
- size: 0;
- height: 0;
- tube: 0;
- profile: 0;
-};
-
-export interface LimbOptions extends PartExtras {
- /** Radius at the joint and at its child (or `to`). */
- radii: [number, number];
- /** End at this joint instead of the first child. */
- to?: string;
- /** Push the ends past the joints by this fraction of the bone (overlap into the next part). Default [0, 0]. */
- extend?: [number, number];
-}
-
-/**
- * A round cone along a bone, from `joint` to its first child (or `to`),
- * moved by that joint: `limb(skeleton, "LeftForeArm", { radii: [4.2, 3.2], blend: 3 })`.
- */
-export function limb(
- skeleton: Skeleton,
- joint: string,
- options: LimbOptions,
-): Part {
- const j = skeleton.joint(joint);
- const end = options.to
- ? skeleton.joint(options.to)
- : skeleton.children(joint)[0];
- if (!end) throw new Error(`limb: joint "${joint}" has no child; give \`to\``);
- const { radii, to: _to, extend, ...rest } = options;
- const d: Vec3 = [
- end.at[0] - j.at[0],
- end.at[1] - j.at[1],
- end.at[2] - j.at[2],
- ];
- const [e0, e1] = extend ?? [0, 0];
- return {
- ...rest,
- shape: "roundCone",
- from: [j.at[0] - d[0] * e0, j.at[1] - d[1] * e0, j.at[2] - d[2] * e0],
- to: [end.at[0] + d[0] * e1, end.at[1] + d[1] * e1, end.at[2] + d[2] * e1],
- radii,
- joint: rest.joint ?? joint,
- name: rest.name ?? joint,
- };
-}
-
-export interface MirrorPartsOptions {
- /** Name fragment swapped in joint and part names. Default "Left". */
- from?: string;
- /** Default "Right". */
- to?: string;
-}
-
-const flip = (p: Vec3): Vec3 => [-p[0], p[1], p[2]];
-
-/** The part with its segment endpoints reflected; other shapes are symmetric about their frame. */
-function mirrorGeometry(p: Part): Part {
- switch (p.shape) {
- case "capsule":
- case "roundCone":
- return { ...p, from: flip(p.from), to: flip(p.to) };
- case "tube":
- return { ...p, points: p.points.map(flip) };
- default:
- return { ...p };
- }
-}
-
-/**
- * The parts reflected across x (the character's left ↔ right), with "Left"
- * and "Right" swapped in their joint names. Returns the originals followed
- * by the copies, so `parts: [...torso, ...mirrorParts(leftArm)]` builds both arms.
- */
-export function mirrorParts(
- parts: Part[],
- options: MirrorPartsOptions = {},
-): Part[] {
- const from = options.from ?? "Left";
- const to = options.to ?? "Right";
- const rename = (n: string) => n.split(from).join(to);
- const copies = parts.map((p): Part => {
- const out: Part = {
- ...mirrorGeometry(p),
- ...(p.at ? { at: flip(p.at) } : {}),
- // Reflecting x negates the turns about y and z.
- ...(p.rotation
- ? { rotation: [p.rotation[0], -p.rotation[1], -p.rotation[2]] as Vec3 }
- : {}),
- ...(p.bend ? { bend: -p.bend } : {}),
- ...(p.twist ? { twist: -p.twist } : {}),
- };
- if (p.joint !== undefined)
- out.joint =
- typeof p.joint === "string" ? rename(p.joint) : p.joint.map(rename);
- if (p.name) out.name = rename(p.name);
- return out;
- });
- return [...parts, ...copies];
-}
diff --git a/packages/forge/src/sculpt/mesh.ts b/packages/forge/src/sculpt/mesh.ts
deleted file mode 100644
index f7d5edba..00000000
--- a/packages/forge/src/sculpt/mesh.ts
+++ /dev/null
@@ -1,382 +0,0 @@
-/**
- * Meshes a sculpt field at hero resolution: the lattice is only sampled
- * in blocks the surface can pass through (a narrow band, found from the
- * field's distance bound), each block evaluating only the parts that can
- * reach it. Surface Nets place one vertex per crossed cell, which is then
- * projected onto the true surface, and a quad joins the four cells around
- * every crossed lattice edge: a closed, manifold, consistently wound mesh.
- */
-import type { Vec3 } from "../skeleton.js";
-import type { SculptField } from "./field.js";
-
-export interface IndexedMesh {
- positions: Float64Array;
- /** Triangles, counter-clockwise seen from outside. */
- indices: Uint32Array;
-}
-
-const B = 8; // cells per block side
-
-const CORNERS: ReadonlyArray<Vec3> = [
- [0, 0, 0],
- [1, 0, 0],
- [0, 1, 0],
- [1, 1, 0],
- [0, 0, 1],
- [1, 0, 1],
- [0, 1, 1],
- [1, 1, 1],
-];
-const EDGES: ReadonlyArray<[number, number]> = [
- [0, 1],
- [2, 3],
- [4, 5],
- [6, 7],
- [0, 2],
- [1, 3],
- [4, 6],
- [5, 7],
- [0, 4],
- [1, 5],
- [2, 6],
- [3, 7],
-];
-/** Per lattice axis: the step, and the four cells around the edge, wound toward +axis. */
-const AXES: ReadonlyArray<{ step: Vec3; around: ReadonlyArray<Vec3> }> = [
- {
- step: [1, 0, 0],
- around: [
- [0, 0, 0],
- [0, -1, 0],
- [0, -1, -1],
- [0, 0, -1],
- ],
- },
- {
- step: [0, 1, 0],
- around: [
- [0, 0, 0],
- [0, 0, -1],
- [-1, 0, -1],
- [-1, 0, 0],
- ],
- },
- {
- step: [0, 0, 1],
- around: [
- [0, 0, 0],
- [-1, 0, 0],
- [-1, -1, 0],
- [0, -1, 0],
- ],
- },
-];
-
-/** A cell edge's index from its two corners. */
-const EDGE_OF = new Map<number, number>(
- EDGES.map(([a, b], i) => [a * 8 + b, i]),
-);
-const edgeOfCorners = (a: number, b: number) =>
- (EDGE_OF.get(a * 8 + b) ?? EDGE_OF.get(b * 8 + a)) as number;
-/** The cell's six faces as corner cycles. */
-const FACES: ReadonlyArray<[number, number, number, number]> = [
- [0, 2, 6, 4],
- [1, 3, 7, 5],
- [0, 1, 5, 4],
- [2, 3, 7, 6],
- [0, 1, 3, 2],
- [4, 5, 7, 6],
-];
-
-/**
- * The surface sheets through a cell, each as the cell edges it crosses.
- * Crossings on a face join in pairs; a face crossed four times (a saddle)
- * pairs them by the sign at its center, the same way from both cells that
- * share it, so neighboring cells agree and the mesh stays manifold.
- */
-function cellSheets(vals: readonly number[]): number[][] {
- const parent = Array.from({ length: 12 }, (_, i) => i);
- const find = (x: number): number => {
- while (parent[x] !== x) {
- parent[x] = parent[parent[x] as number] as number;
- x = parent[x] as number;
- }
- return x;
- };
- const join = (a: number, b: number) => {
- parent[find(a)] = find(b);
- };
- const crosses = (e: number) => {
- const [a, b] = EDGES[e] as [number, number];
- return (vals[a] as number) < 0 !== (vals[b] as number) < 0;
- };
- let any = false;
- for (let e = 0; e < 12; e++) if (crosses(e)) any = true;
- if (!any) return [];
- for (const q of FACES) {
- const e = [0, 1, 2, 3].map((i) =>
- edgeOfCorners(q[i] as number, q[(i + 1) % 4] as number),
- );
- const hit = e.filter(crosses);
- if (hit.length === 2) join(hit[0] as number, hit[1] as number);
- else if (hit.length === 4) {
- const center = q.reduce((s, c) => s + (vals[c] as number), 0) / 4;
- const s0 = (vals[q[0]] as number) < 0;
- if (center < 0 === s0) {
- // q0 and q2 connect through the center: cut around q1 and around q3.
- join(e[0] as number, e[1] as number);
- join(e[2] as number, e[3] as number);
- } else {
- join(e[3] as number, e[0] as number);
- join(e[1] as number, e[2] as number);
- }
- }
- }
- const groups = new Map<number, number[]>();
- for (let e = 0; e < 12; e++) {
- if (!crosses(e)) continue;
- const r = find(e);
- const g = groups.get(r);
- if (g) g.push(e);
- else groups.set(r, [e]);
- }
- return [...groups.values()];
-}
-
-/** The lattice edge along `axis` as an edge of the cell at offset `o` around it. */
-function edgeIn(axis: number, o: Vec3): number {
- if (axis === 0) return -o[1] + 2 * -o[2];
- if (axis === 1) return 4 + -o[0] + 2 * -o[2];
- return 8 + -o[0] + 2 * -o[1];
-}
-
-interface Block {
- bi: number;
- bj: number;
- bk: number;
- parts: number[];
- values: Float32Array;
-}
-
-export interface MeshOptions {
- /** Lattice cell size, model units. */
- cell: number;
-}
-
-/** The field's zero surface as an indexed triangle mesh. */
-export function meshField(
- field: SculptField,
- options: MeshOptions,
-): IndexedMesh {
- const h = options.cell;
- const { min, max } = field.bounds();
- const pad = 2 * h;
- const origin: Vec3 = [min[0] - pad, min[1] - pad, min[2] - pad];
- const cells: Vec3 = [
- Math.ceil((max[0] - min[0] + 2 * pad) / h),
- Math.ceil((max[1] - min[1] + 2 * pad) / h),
- Math.ceil((max[2] - min[2] + 2 * pad) / h),
- ];
- const nb: Vec3 = [
- Math.ceil(cells[0] / B),
- Math.ceil(cells[1] / B),
- Math.ceil(cells[2] / B),
- ];
- if (nb[0] * nb[1] * nb[2] > 4e6)
- throw new Error(
- `sculpt: cell ${h} is too fine for a ${(max[0] - min[0]).toFixed(0)}-unit model`,
- );
- // Lattice nodes span (cells + 1) per axis, rounded up to whole blocks.
- const NX = nb[0] * B + 1;
- const NY = nb[1] * B + 1;
- const cellId = (i: number, j: number, k: number) => (k * NY + j) * NX + i;
- const node = (i: number, j: number, k: number): Vec3 => [
- origin[0] + i * h,
- origin[1] + j * h,
- origin[2] + k * h,
- ];
-
- const blocks: Block[] = [];
- const blockRadius = (B * h * Math.sqrt(3)) / 2;
- const L = field.lipschitz;
- for (let bk = 0; bk < nb[2]; bk++)
- for (let bj = 0; bj < nb[1]; bj++)
- for (let bi = 0; bi < nb[0]; bi++) {
- const c = node((bi + 0.5) * B, (bj + 0.5) * B, (bk + 0.5) * B);
- const parts = field.relevant(c, blockRadius);
- if (!parts.length) continue;
- const d = field.distance(c[0], c[1], c[2], parts);
- // The surface can't be in a block whose center is farther than its reach.
- if (Math.abs(d) > (blockRadius + h) * L) continue;
- const values = new Float32Array((B + 1) ** 3);
- let neg = false;
- let pos = false;
- for (let k = 0; k <= B; k++)
- for (let j = 0; j <= B; j++)
- for (let i = 0; i <= B; i++) {
- const p = node(bi * B + i, bj * B + j, bk * B + k);
- const v = field.distance(p[0], p[1], p[2], parts);
- values[(k * (B + 1) + j) * (B + 1) + i] = v;
- if (v < 0) neg = true;
- else pos = true;
- }
- if (neg && pos) blocks.push({ bi, bj, bk, parts, values });
- }
-
- const positions: number[] = [];
- // (cell, cell edge) → vertex: a cell holds one vertex per surface sheet through it.
- const vertexOf = new Map<number, number>();
- const key = (cell: number, edge: number) => cell * 12 + edge;
- const at = (b: Block, i: number, j: number, k: number) =>
- b.values[(k * (B + 1) + j) * (B + 1) + i] as number;
- const vals = new Array<number>(8);
- for (const b of blocks) {
- for (let k = 0; k < B; k++)
- for (let j = 0; j < B; j++)
- for (let i = 0; i < B; i++) {
- for (let c = 0; c < 8; c++) {
- const o = CORNERS[c] as Vec3;
- vals[c] = at(b, i + o[0], j + o[1], k + o[2]);
- }
- const sheets = cellSheets(vals);
- if (!sheets.length) continue;
- const gi = b.bi * B + i;
- const gj = b.bj * B + j;
- const gk = b.bk * B + k;
- const id = cellId(gi, gj, gk);
- for (const edges of sheets) {
- let sx = 0;
- let sy = 0;
- let sz = 0;
- for (const e of edges) {
- const [ea, eb] = EDGES[e] as [number, number];
- const va = vals[ea] as number;
- const vb = vals[eb] as number;
- const t = va / (va - vb);
- const ca = CORNERS[ea] as Vec3;
- const cb = CORNERS[eb] as Vec3;
- sx += ca[0] + (cb[0] - ca[0]) * t;
- sy += ca[1] + (cb[1] - ca[1]) * t;
- sz += ca[2] + (cb[2] - ca[2]) * t;
- }
- const n = edges.length;
- const p = node(gi + sx / n, gj + sy / n, gk + sz / n);
- project(field, p, h, b.parts);
- const v = positions.length / 3;
- positions.push(p[0], p[1], p[2]);
- for (const e of edges) vertexOf.set(key(id, e), v);
- }
- }
- }
-
- const indices: number[] = [];
- for (const b of blocks) {
- for (let k = 0; k < B; k++)
- for (let j = 0; j < B; j++)
- for (let i = 0; i < B; i++) {
- const v0 = at(b, i, j, k);
- for (let axis = 0; axis < 3; axis++) {
- const { step, around } = AXES[axis] as (typeof AXES)[number];
- const v1 = at(b, i + step[0], j + step[1], k + step[2]);
- if (v0 < 0 === v1 < 0) continue;
- const gi = b.bi * B + i;
- const gj = b.bj * B + j;
- const gk = b.bk * B + k;
- const q: number[] = [];
- for (const o of around) {
- // This lattice edge, as one of the 12 edges of the cell at offset o.
- const e = edgeIn(axis, o);
- const v = vertexOf.get(
- key(cellId(gi + o[0], gj + o[1], gk + o[2]), e),
- );
- if (v === undefined) break;
- q.push(v);
- }
- if (q.length < 4) continue;
- const [a, bb, c, d] = q as [number, number, number, number];
- // Each cycle winds toward +axis; the surface faces +axis where the field leaves the solid.
- if (v0 < 0) indices.push(a, bb, c, a, c, d);
- else indices.push(a, c, bb, a, d, c);
- }
- }
- }
- return {
- positions: Float64Array.from(positions),
- indices: Uint32Array.from(indices),
- };
-}
-
-/** Moves a Surface Nets point onto the zero surface by Newton steps, at most most of a cell. */
-export function project(
- field: SculptField,
- p: Vec3,
- h: number,
- parts: readonly number[],
-) {
- const start: Vec3 = [p[0], p[1], p[2]];
- for (let it = 0; it < 3; it++) {
- const d = field.distance(p[0], p[1], p[2], parts);
- if (Math.abs(d) < h * 1e-3) break;
- const n = field.normal(p[0], p[1], p[2], h * 0.25, parts);
- p[0] -= n[0] * d;
- p[1] -= n[1] * d;
- p[2] -= n[2] * d;
- }
- const dx = p[0] - start[0];
- const dy = p[1] - start[1];
- const dz = p[2] - start[2];
- const moved = Math.hypot(dx, dy, dz);
- const limit = 0.75 * h;
- if (moved > limit) {
- // A thin or sharp feature: keep the vertex in its cell's neighborhood.
- const s = limit / moved;
- p[0] = start[0] + dx * s;
- p[1] = start[1] + dy * s;
- p[2] = start[2] + dz * s;
- }
-}
-
-/** Signed volume (positive for an outward-wound closed mesh). */
-export function meshVolume(m: IndexedMesh): number {
- let v = 0;
- const P = m.positions;
- for (let t = 0; t < m.indices.length; t += 3) {
- const a = (m.indices[t] as number) * 3;
- const b = (m.indices[t + 1] as number) * 3;
- const c = (m.indices[t + 2] as number) * 3;
- const ax = P[a] as number;
- const ay = P[a + 1] as number;
- const az = P[a + 2] as number;
- const bx = P[b] as number;
- const by = P[b + 1] as number;
- const bz = P[b + 2] as number;
- const cx = P[c] as number;
- const cy = P[c + 1] as number;
- const cz = P[c + 2] as number;
- v +=
- ax * (by * cz - bz * cy) -
- ay * (bx * cz - bz * cx) +
- az * (bx * cy - by * cx);
- }
- return v / 6;
-}
-
-/** Edges used by other than exactly two triangles, and by two triangles in the same direction. */
-export function meshDefects(m: IndexedMesh): { open: number; flipped: number } {
- const count = new Map<string, number>();
- for (let t = 0; t < m.indices.length; t += 3)
- for (let e = 0; e < 3; e++) {
- const a = m.indices[t + e] as number;
- const b = m.indices[t + ((e + 1) % 3)] as number;
- const key = `${a},${b}`;
- count.set(key, (count.get(key) ?? 0) + 1);
- }
- let open = 0;
- let flipped = 0;
- for (const [key, n] of count) {
- if (n > 1) flipped++;
- const [a, b] = key.split(",");
- if (!count.has(`${b},${a}`)) open++;
- }
- return { open, flipped };
-}
diff --git a/packages/forge/src/sculpt/noise.ts b/packages/forge/src/sculpt/noise.ts
deleted file mode 100644
index 0c645cf5..00000000
--- a/packages/forge/src/sculpt/noise.ts
+++ /dev/null
@@ -1,120 +0,0 @@
-/**
- * Deterministic 3D gradient noise (Perlin's improved noise with a seeded
- * permutation) and its fractal sum, for surface detail: bark, rock, bone
- * pitting, fur clumps. Values lie in about -1..1.
- */
-
-const GRAD: ReadonlyArray<readonly [number, number, number]> = [
- [1, 1, 0],
- [-1, 1, 0],
- [1, -1, 0],
- [-1, -1, 0],
- [1, 0, 1],
- [-1, 0, 1],
- [1, 0, -1],
- [-1, 0, -1],
- [0, 1, 1],
- [0, -1, 1],
- [0, 1, -1],
- [0, -1, -1],
-];
-
-function permutation(seed: number): Uint8Array {
- const p = new Uint8Array(512);
- const base = Array.from({ length: 256 }, (_, i) => i);
- // Mulberry32: a small, well-mixed seeded generator.
- let s = seed >>> 0;
- const rand = () => {
- s = (s + 0x6d2b79f5) >>> 0;
- let t = s;
- t = Math.imul(t ^ (t >>> 15), t | 1);
- t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
- return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
- };
- for (let i = 255; i > 0; i--) {
- const j = Math.floor(rand() * (i + 1));
- [base[i], base[j]] = [base[j] as number, base[i] as number];
- }
- for (let i = 0; i < 512; i++) p[i] = base[i & 255] as number;
- return p;
-}
-
-const fade = (t: number) => t * t * t * (t * (t * 6 - 15) + 10);
-const lerp = (a: number, b: number, t: number) => a + (b - a) * t;
-
-export class Noise3 {
- private readonly p: Uint8Array;
-
- constructor(seed = 0) {
- this.p = permutation(seed);
- }
-
- private grad(h: number, x: number, y: number, z: number): number {
- const g = GRAD[h % 12] as readonly [number, number, number];
- return g[0] * x + g[1] * y + g[2] * z;
- }
-
- /** Gradient noise at a point, about -1..1. */
- at(x: number, y: number, z: number): number {
- const p = this.p;
- const xi = Math.floor(x);
- const yi = Math.floor(y);
- const zi = Math.floor(z);
- const X = xi & 255;
- const Y = yi & 255;
- const Z = zi & 255;
- const xf = x - xi;
- const yf = y - yi;
- const zf = z - zi;
- const u = fade(xf);
- const v = fade(yf);
- const w = fade(zf);
- const A = (p[X] as number) + Y;
- const AA = (p[A] as number) + Z;
- const AB = (p[A + 1] as number) + Z;
- const B = (p[X + 1] as number) + Y;
- const BA = (p[B] as number) + Z;
- const BB = (p[B + 1] as number) + Z;
- const g = (i: number) => p[i] as number;
- return lerp(
- lerp(
- lerp(this.grad(g(AA), xf, yf, zf), this.grad(g(BA), xf - 1, yf, zf), u),
- lerp(
- this.grad(g(AB), xf, yf - 1, zf),
- this.grad(g(BB), xf - 1, yf - 1, zf),
- u,
- ),
- v,
- ),
- lerp(
- lerp(
- this.grad(g(AA + 1), xf, yf, zf - 1),
- this.grad(g(BA + 1), xf - 1, yf, zf - 1),
- u,
- ),
- lerp(
- this.grad(g(AB + 1), xf, yf - 1, zf - 1),
- this.grad(g(BB + 1), xf - 1, yf - 1, zf - 1),
- u,
- ),
- v,
- ),
- w,
- );
- }
-
- /** Fractal sum of `octaves` layers, each twice the frequency and half the amplitude; about -1..1. */
- fbm(x: number, y: number, z: number, octaves: number): number {
- let sum = 0;
- let amp = 1;
- let norm = 0;
- let f = 1;
- for (let o = 0; o < octaves; o++) {
- sum += amp * this.at(x * f, y * f, z * f);
- norm += amp;
- amp *= 0.5;
- f *= 2.03;
- }
- return sum / norm;
- }
-}
diff --git a/packages/forge/src/sculpt/sculpt.test.ts b/packages/forge/src/sculpt/sculpt.test.ts
deleted file mode 100644
index c5355790..00000000
--- a/packages/forge/src/sculpt/sculpt.test.ts
+++ /dev/null
@@ -1,361 +0,0 @@
-/**
- * Sculpting: the narrow-band mesh is closed and on the true surface,
- * simplification keeps it closed and near its volume, materials split
- * into primitives along their borders, and weights from the field bend a
- * blended elbow without collapsing it.
- */
-import { parseGLB } from "@framefields/webgpu-renderers";
-import { validateBytes } from "gltf-validator";
-import { describe, expect, it } from "vitest";
-import {
- GltfDocument,
- humanoidSkeleton,
- limb,
- mirrorParts,
- type Part,
- SculptField,
- Skeleton,
- sculpt,
- type Vec3,
-} from "../index.js";
-
-const volumeOf = (positions: ArrayLike<number>, indices: ArrayLike<number>) => {
- let v = 0;
- for (let t = 0; t < indices.length; t += 3) {
- const p = [0, 1, 2].map((k) => {
- const i = (indices[t + k] as number) * 3;
- return [positions[i], positions[i + 1], positions[i + 2]] as Vec3;
- }) as [Vec3, Vec3, Vec3];
- const [a, b, c] = p;
- v +=
- a[0] * (b[1] * c[2] - b[2] * c[1]) -
- a[1] * (b[0] * c[2] - b[2] * c[0]) +
- a[2] * (b[0] * c[1] - b[1] * c[0]);
- }
- return v / 6;
-};
-
-describe("sculpt", () => {
- it("meshes a closed surface on the true field", () => {
- const r = 50;
- const { primitives, report } = sculpt({
- parts: [{ shape: "sphere", radius: r }],
- cell: 1,
- });
- expect(report.openEdges).toBe(0);
- const exact = (4 / 3) * Math.PI * r ** 3;
- expect(Math.abs(report.volume - exact) / exact).toBeLessThan(0.005);
- const p = primitives[0]?.positions ?? [];
- let worst = 0;
- for (let i = 0; i < p.length; i += 3)
- worst = Math.max(
- worst,
- Math.abs(
- Math.hypot(p[i] as number, p[i + 1] as number, p[i + 2] as number) -
- r,
- ),
- );
- // Projected onto the surface, not left at the Surface Nets average.
- expect(worst).toBeLessThan(0.01);
- });
-
- it("simplifies to a budget and stays closed", () => {
- const parts: Part[] = [
- { shape: "box", size: [80, 50, 40], radius: 6 },
- { shape: "sphere", at: [40, 25, 0], radius: 18, blend: 10 },
- {
- shape: "cylinder",
- at: [-20, 0, 0],
- radius: 10,
- height: 80,
- op: "subtract",
- blend: 3,
- },
- ];
- const full = sculpt({ parts, cell: 0.8 });
- const small = sculpt({ parts, cell: 0.8, triangles: 4000 });
- expect(full.report.triangles).toBeGreaterThan(40000);
- expect(small.report.triangles).toBeLessThanOrEqual(4000);
- expect(small.report.openEdges).toBe(0);
- expect(
- Math.abs(small.report.volume - full.report.volume) / full.report.volume,
- ).toBeLessThan(0.01);
- });
-
- it("splits materials into primitives along their borders", () => {
- const doc = new GltfDocument();
- const skin = doc.addMaterial({ color: "#e8cfb0" });
- const cloth = doc.addMaterial({ color: "#3b5a3a" });
- const { primitives, report } = sculpt({
- parts: [
- { shape: "sphere", radius: 30, material: skin },
- {
- shape: "box",
- at: [0, -20, 0],
- size: [70, 30, 70],
- blend: 4,
- material: cloth,
- },
- ],
- cell: 1,
- triangles: 6000,
- });
- expect(report.openEdges).toBe(0);
- expect(primitives.map((p) => p.material)).toEqual([skin, cloth]);
- // The pieces still close into one solid.
- const total = primitives.reduce(
- (s, p) => s + volumeOf(p.positions, p.indices ?? []),
- 0,
- );
- expect(total).toBeCloseTo(report.volume, 0);
- });
-
- it("cuts material borders on the curve where ownership changes", () => {
- const doc = new GltfDocument();
- const a = doc.addMaterial({ color: "#ff0000" });
- const b = doc.addMaterial({ color: "#0000ff" });
- // Two equal spheres, hard union: their border is the circle in x = 0.
- const { primitives, report } = sculpt({
- parts: [
- { shape: "sphere", at: [-15, 0, 0], radius: 25, material: a },
- { shape: "sphere", at: [15, 0, 0], radius: 25, material: b },
- ],
- cell: 1,
- triangles: 3000,
- });
- expect(report.openEdges).toBe(0);
- const key = (p: ArrayLike<number>, i: number) =>
- `${(p[i * 3] as number).toFixed(6)},${(p[i * 3 + 1] as number).toFixed(6)},${(p[i * 3 + 2] as number).toFixed(6)}`;
- const [pa, pb] = primitives;
- const inB = new Set(
- Array.from({ length: (pb?.positions.length ?? 0) / 3 }, (_, i) =>
- key(pb?.positions ?? [], i),
- ),
- );
- let shared = 0;
- let worst = 0;
- const P = pa?.positions ?? [];
- for (let i = 0; i < P.length / 3; i++) {
- if (!inB.has(key(P, i))) continue;
- shared++;
- worst = Math.max(worst, Math.abs(P[i * 3] as number));
- }
- expect(shared).toBeGreaterThan(30);
- expect(worst).toBeLessThan(0.02);
- });
-
- it("blends vertex colors across smooth joins", () => {
- const { primitives } = sculpt({
- parts: [
- { shape: "sphere", at: [-20, 0, 0], radius: 20, color: "#ff0000" },
- {
- shape: "sphere",
- at: [20, 0, 0],
- radius: 20,
- color: "#0000ff",
- blend: 12,
- },
- ],
- cell: 1,
- });
- const p = primitives[0];
- const colors = p?.colors ?? [];
- const pos = p?.positions ?? [];
- // The vertex nearest the middle of the join is a mix of both.
- let best = 0;
- let bestX = Number.POSITIVE_INFINITY;
- for (let i = 0; i < pos.length / 3; i++) {
- const x = Math.abs(pos[i * 3] as number);
- if (x < bestX) {
- bestX = x;
- best = i;
- }
- }
- expect(colors[best * 4]).toBeGreaterThan(0.2);
- expect(colors[best * 4 + 2]).toBeGreaterThan(0.2);
- });
-
- it("skins a blended elbow that bends without collapsing", () => {
- // An arm along +x: shoulder at 0, elbow at 60, wrist at 110.
- const skeleton = new Skeleton()
- .add("Arm", { at: [0, 0, 0] })
- .add("ForeArm", { at: [60, 0, 0], parent: "Arm" })
- .add("Hand", { at: [110, 0, 0], parent: "ForeArm" });
- const result = sculpt({
- skeleton,
- parts: [
- limb(skeleton, "Arm", { radii: [10, 8] }),
- limb(skeleton, "ForeArm", { radii: [8, 6], blend: 8 }),
- ],
- cell: 1,
- triangles: 8000,
- });
- const prim = result.primitives[0];
- const pos = prim?.positions ?? [];
- const joints = prim?.joints ?? [];
- const weights = prim?.weights ?? [];
- const n = pos.length / 3;
- const weightOf = (v: number, j: number) => {
- let w = 0;
- for (let k = 0; k < 4; k++)
- if (joints[v * 4 + k] === j && (weights[v * 4 + k] as number) > 0)
- w += weights[v * 4 + k] as number;
- return w;
- };
- for (let v = 0; v < n; v++) {
- const x = pos[v * 3] as number;
- if (x < 30) expect(weightOf(v, 0)).toBeGreaterThan(0.95);
- if (x > 85) expect(weightOf(v, 1)).toBeGreaterThan(0.95);
- }
- // The elbow shares: some vertex there is moved by both joints.
- let shared = 0;
- for (let v = 0; v < n; v++) {
- const x = pos[v * 3] as number;
- if (x > 50 && x < 70 && weightOf(v, 0) > 0.2 && weightOf(v, 1) > 0.2)
- shared++;
- }
- expect(shared).toBeGreaterThan(20);
-
- // Bend the forearm 90° about z at the elbow (linear blend skinning).
- const bent = new Float64Array(pos.length);
- for (let v = 0; v < n; v++) {
- const x = (pos[v * 3] as number) - 60;
- const y = pos[v * 3 + 1] as number;
- const w1 = weightOf(v, 1) + weightOf(v, 2);
- const w0 = 1 - w1;
- bent[v * 3] = w0 * (x + 60) + w1 * (-y + 60);
- bent[v * 3 + 1] = w0 * y + w1 * x;
- bent[v * 3 + 2] = pos[v * 3 + 2] as number;
- }
- const before = volumeOf(pos, prim?.indices ?? []);
- const after = volumeOf(bent, prim?.indices ?? []);
- expect(after / before).toBeGreaterThan(0.85);
- });
-
- it("shares a part between joints by distance to their bones", () => {
- const skeleton = new Skeleton()
- .add("Hips", { at: [0, 0, 0] })
- .add("Spine", { at: [0, 40, 0], parent: "Hips" })
- .add("Chest", { at: [0, 80, 0], parent: "Spine" })
- .add("Neck", { at: [0, 120, 0], parent: "Chest" });
- const { primitives } = sculpt({
- skeleton,
- parts: [
- {
- shape: "capsule",
- from: [0, 0, 0],
- to: [0, 120, 0],
- radius: 15,
- joint: ["Hips", "Spine", "Chest"],
- },
- ],
- cell: 1.5,
- });
- const p = primitives[0];
- const pos = p?.positions ?? [];
- const top = (y: number) => {
- let best = 0;
- let bestD = Number.POSITIVE_INFINITY;
- for (let i = 0; i < pos.length / 3; i++) {
- const d = Math.abs((pos[i * 3 + 1] as number) - y);
- if (d < bestD) {
- bestD = d;
- best = i;
- }
- }
- return p?.joints?.[best * 4];
- };
- expect(top(10)).toBe(0);
- expect(top(60)).toBe(1);
- expect(top(105)).toBe(2);
- });
-
- it("mirrors parts across the body", () => {
- const skeleton = humanoidSkeleton();
- const [left, right] = mirrorParts([
- limb(skeleton, "LeftArm", { radii: [5, 4] }),
- ]);
- expect(right?.joint).toBe("RightArm");
- if (left?.shape !== "roundCone" || right?.shape !== "roundCone")
- throw new Error("shape");
- expect(right.from[0]).toBeCloseTo(-left.from[0]);
- expect(right.to).toEqual([-left.to[0], left.to[1], left.to[2]]);
- const f = new SculptField(
- mirrorParts([limb(skeleton, "LeftArm", { radii: [5, 4] })]),
- );
- const p = skeleton.joint("LeftForeArm").at;
- expect(f.distance(p[0], p[1], p[2])).toBeCloseTo(
- f.distance(-p[0], p[1], p[2]),
- 9,
- );
- });
-
- it("writes a sculpted, skinned humanoid that validates", async () => {
- const skeleton = humanoidSkeleton({
- height: 180,
- fingers: false,
- toes: false,
- });
- const doc = new GltfDocument();
- const rig = doc.addSkeleton(skeleton);
- const skin = doc.addMaterial({ color: "#e8cfb0", roughness: 0.6 });
- const s = (n: string) => skeleton.joint(n).at;
- const body = sculpt({
- skeleton,
- parts: [
- {
- shape: "ellipsoid",
- at: s("Spine1"),
- radii: [15, 24, 10],
- joint: ["Hips", "Spine", "Spine1", "Spine2"],
- material: skin,
- },
- {
- shape: "sphere",
- at: [0, 166, 1],
- radius: 10,
- joint: "Head",
- blend: 4,
- material: skin,
- },
- limb(skeleton, "Neck", { radii: [5, 5], blend: 4, material: skin }),
- ...mirrorParts([
- limb(skeleton, "LeftArm", {
- radii: [5, 4],
- blend: 5,
- material: skin,
- }),
- limb(skeleton, "LeftForeArm", {
- radii: [4, 3],
- blend: 3,
- material: skin,
- }),
- limb(skeleton, "LeftUpLeg", {
- radii: [8, 5.5],
- blend: 6,
- material: skin,
- }),
- limb(skeleton, "LeftLeg", {
- radii: [5.5, 4],
- blend: 3,
- material: skin,
- }),
- ]),
- ],
- cell: 1.2,
- triangles: 20000,
- });
- expect(body.report.openEdges).toBe(0);
- doc.addNode({
- name: "Body",
- mesh: doc.addMesh({ name: "Body", primitives: body.primitives }),
- skin: rig.skin,
- });
- const glb = doc.toGlb();
- const report = await validateBytes(glb, { maxIssues: 20 });
- expect(report.issues.messages.filter((m) => m.severity <= 1)).toEqual([]);
- expect(parseGLB(glb).meshes[0]?.jointIndices?.length).toBe(
- body.report.vertices * 4,
- );
- });
-});
diff --git a/packages/forge/src/sculpt/sculpt.ts b/packages/forge/src/sculpt/sculpt.ts
deleted file mode 100644
index 8df471cc..00000000
--- a/packages/forge/src/sculpt/sculpt.ts
+++ /dev/null
@@ -1,199 +0,0 @@
-/**
- * Sculpt a model from parts: mesh the field at hero resolution, simplify
- * to a triangle budget, take normals and colors from the field, skin the
- * vertices to a skeleton, and split by material into glTF primitives.
- *
- * ```ts
- * const skeleton = humanoidSkeleton({ height: 186, heads: 8 });
- * const body = sculpt({
- * skeleton,
- * parts: [
- * { shape: "ellipsoid", at: [0, 120, 0], radii: [16, 22, 11], joint: ["Spine", "Spine1", "Spine2"], material: skin },
- * ...mirrorParts([limb(skeleton, "LeftArm", { radii: [5, 4], blend: 4, material: skin })]),
- * ],
- * triangles: 60000,
- * });
- * doc.addNode({ mesh: doc.addMesh({ name: "Body", primitives: body.primitives }), skin: rig.skin });
- * ```
- */
-import type { ColorInput } from "../color.js";
-import type { MaterialRef, PrimitiveSpec } from "../document.js";
-import type { Skeleton } from "../skeleton.js";
-import { majorityTags, splitBorders, vertexMaterials } from "./borders.js";
-import { type Part, SculptField } from "./field.js";
-import { meshDefects, meshField, meshVolume } from "./mesh.js";
-import { simplify } from "./simplify.js";
-import { skinWeights } from "./skin.js";
-
-export interface SculptOptions {
- parts: Part[];
- /** Skin the result to this skeleton (joint indices in its order, as `addSkeleton` writes them). */
- skeleton?: Skeleton;
- /** Lattice cell, model units. Default: the longest side of the parts' bounds / 256. */
- cell?: number;
- /** Simplify to at most this many triangles. Default: keep every triangle. */
- triangles?: number;
- /** Vertex color where no part sets one (display sRGB). Default white. */
- color?: ColorInput;
- /** Skin smoothing passes. Default 2. */
- skinSmoothing?: number;
-}
-
-export interface SculptReport {
- cell: number;
- vertices: number;
- triangles: number;
- /** Triangles straight off the lattice, before simplification. */
- sculptedTriangles: number;
- volume: number;
- /** Edges not shared by exactly two oppositely wound triangles (0 for a closed mesh). */
- openEdges: number;
- seconds: { mesh: number; simplify: number; attributes: number };
-}
-
-export interface SculptResult {
- /** One primitive per material, ready for `GltfDocument.addMesh`. */
- primitives: PrimitiveSpec[];
- report: SculptReport;
-}
-
-export function sculpt(options: SculptOptions): SculptResult {
- const field = new SculptField(options.parts, options.color);
- const { min, max } = field.bounds();
- const cell =
- options.cell ??
- Math.max(max[0] - min[0], max[1] - min[1], max[2] - min[2]) / 256;
- if (!(cell > 0)) throw new Error("sculpt: cell must be positive");
-
- let t = performance.now();
- const raw = meshField(field, { cell });
- if (!raw.indices.length)
- throw new Error("sculpt: the parts enclose no volume");
- const meshSeconds = (performance.now() - t) / 1000;
-
- // Materials by the part owning the surface: per vertex, then per
- // triangle for simplification (which keeps borders in place), then cut
- // exactly along the borders.
- const materials: (MaterialRef | undefined)[] = [];
- const materialOf = (part: number) => {
- const m = field.parts[part]?.part.material;
- const i = materials.indexOf(m);
- if (i >= 0) return i;
- materials.push(m);
- return materials.length - 1;
- };
- const rawTags = majorityTags(
- raw.indices,
- vertexMaterials(field, raw.positions, materialOf),
- );
-
- t = performance.now();
- const simplified =
- options.triangles !== undefined && options.triangles < rawTags.length
- ? simplify(raw, { triangles: options.triangles, tags: rawTags })
- : raw;
- const simplifySeconds = (performance.now() - t) / 1000;
- const mesh =
- materials.length > 1
- ? splitBorders(field, simplified, materialOf, cell)
- : { ...simplified, tags: new Int32Array(simplified.indices.length / 3) };
-
- t = performance.now();
- const nv = mesh.positions.length / 3;
- const normals = new Float32Array(nv * 3);
- const colored = field.parts.some((p) => p.color);
- const colors = colored ? new Float32Array(nv * 4) : undefined;
- for (let v = 0; v < nv; v++) {
- const x = mesh.positions[v * 3] as number;
- const y = mesh.positions[v * 3 + 1] as number;
- const z = mesh.positions[v * 3 + 2] as number;
- const near = field.relevant([x, y, z], cell);
- const n = field.normal(x, y, z, cell * 0.5, near);
- normals.set(n, v * 3);
- if (colors) {
- field.distance(x, y, z, near, true);
- colors.set(field.color, v * 4);
- }
- }
- const skin = options.skeleton
- ? skinWeights(field, options.skeleton, mesh.positions, mesh.indices, {
- smoothing: options.skinSmoothing ?? 2,
- minFalloff: cell * 1.5,
- })
- : undefined;
- const attributeSeconds = (performance.now() - t) / 1000;
-
- const defects = meshDefects(mesh);
- const primitives = materials.map((material, id) =>
- primitive(mesh, id, material, normals, colors, skin),
- );
- return {
- primitives: primitives
- .map((p, id) => ({ p, order: materials[id]?.material ?? -1 }))
- .filter(({ p }) => p.positions.length > 0)
- .sort((a, b) => a.order - b.order)
- .map(({ p }) => p),
- report: {
- cell,
- vertices: nv,
- triangles: mesh.indices.length / 3,
- sculptedTriangles: raw.indices.length / 3,
- volume: meshVolume(mesh),
- openEdges: defects.open + defects.flipped,
- seconds: {
- mesh: meshSeconds,
- simplify: simplifySeconds,
- attributes: attributeSeconds,
- },
- },
- };
-}
-
-/** The triangles tagged `id` with their own copy of the vertices they use. */
-function primitive(
- mesh: { positions: Float64Array; indices: Uint32Array; tags: Int32Array },
- id: number,
- material: MaterialRef | undefined,
- normals: Float32Array,
- colors: Float32Array | undefined,
- skin: { joints: Uint16Array; weights: Float32Array } | undefined,
-): PrimitiveSpec {
- const remap = new Map<number, number>();
- const positions: number[] = [];
- const norms: number[] = [];
- const cols: number[] = [];
- const joints: number[] = [];
- const weights: number[] = [];
- const indices: number[] = [];
- for (let f = 0; f < mesh.tags.length; f++) {
- if (mesh.tags[f] !== id) continue;
- for (let k = 0; k < 3; k++) {
- const v = mesh.indices[f * 3 + k] as number;
- let i = remap.get(v);
- if (i === undefined) {
- i = positions.length / 3;
- remap.set(v, i);
- for (let a = 0; a < 3; a++) {
- positions.push(mesh.positions[v * 3 + a] as number);
- norms.push(normals[v * 3 + a] as number);
- }
- if (colors)
- for (let a = 0; a < 4; a++) cols.push(colors[v * 4 + a] as number);
- if (skin)
- for (let a = 0; a < 4; a++) {
- joints.push(skin.joints[v * 4 + a] as number);
- weights.push(skin.weights[v * 4 + a] as number);
- }
- }
- indices.push(i);
- }
- }
- return {
- positions,
- normals: norms,
- indices,
- ...(material ? { material } : {}),
- ...(colors ? { colors: cols } : {}),
- ...(skin ? { joints, weights } : {}),
- };
-}
diff --git a/packages/forge/src/sculpt/shapes.ts b/packages/forge/src/sculpt/shapes.ts
deleted file mode 100644
index b5a8a067..00000000
--- a/packages/forge/src/sculpt/shapes.ts
+++ /dev/null
@@ -1,286 +0,0 @@
-/**
- * Signed distance functions for sculpting characters, in a part's local
- * frame (glTF axes: +y up). Segment shapes (capsule, round cone, tube) run
- * between points, so a limb is written from joint to joint. Most follow
- * Inigo Quilez's exact distances; the ellipsoid is his close bound.
- */
-import type { Vec3 } from "../skeleton.js";
-
-export type Shape =
- | { shape: "sphere"; radius: number }
- /** Semi-axes along x, y, z. */
- | { shape: "ellipsoid"; radii: Vec3 }
- /** Full size; `radius` rounds the edges. */
- | { shape: "box"; size: Vec3; radius?: number }
- /** Along y, centered. */
- | { shape: "cylinder"; radius: number; height: number }
- | { shape: "capsule"; from: Vec3; to: Vec3; radius: number }
- /** A capsule whose radius changes from `from` to `to`: limbs, horns, fingers. */
- | { shape: "roundCone"; from: Vec3; to: Vec3; radii: [number, number] }
- /**
- * A smooth tube through `points` (Catmull-Rom), radius per point or one
- * for all: tails, braids, ribbons, cords.
- */
- | { shape: "tube"; points: Vec3[]; radius: number | number[] }
- /** In the xz plane, around y. */
- | { shape: "torus"; radius: number; tube: number }
- /**
- * A closed outline in the (radius, y) half-plane revolved around y:
- * vases, helmets, pauldrons, buttons.
- */
- | { shape: "lathe"; profile: [number, number][] };
-
-/** A prepared shape: its distance function and a bounding sphere in the local frame. */
-export interface ShapeField {
- distance(x: number, y: number, z: number): number;
- center: Vec3;
- radius: number;
-}
-
-const dot = (ax: number, ay: number, az: number, b: Vec3) =>
- ax * b[0] + ay * b[1] + az * b[2];
-
-function segment(from: Vec3, to: Vec3, radius: number): ShapeField {
- const ba: Vec3 = [to[0] - from[0], to[1] - from[1], to[2] - from[2]];
- const len2 = dot(ba[0], ba[1], ba[2], ba) || 1e-12;
- return {
- distance(x, y, z) {
- const px = x - from[0];
- const py = y - from[1];
- const pz = z - from[2];
- const h = Math.min(1, Math.max(0, dot(px, py, pz, ba) / len2));
- return (
- Math.hypot(px - ba[0] * h, py - ba[1] * h, pz - ba[2] * h) - radius
- );
- },
- center: mid(from, to),
- radius: Math.sqrt(len2) / 2 + radius,
- };
-}
-
-const mid = (a: Vec3, b: Vec3): Vec3 => [
- (a[0] + b[0]) / 2,
- (a[1] + b[1]) / 2,
- (a[2] + b[2]) / 2,
-];
-
-/** Quilez's exact round cone between two spheres. */
-function roundCone(a: Vec3, b: Vec3, r1: number, r2: number): ShapeField {
- const ba: Vec3 = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
- const l2 = dot(ba[0], ba[1], ba[2], ba);
- if (l2 < 1e-12) {
- const r = Math.max(r1, r2);
- return {
- distance: (x, y, z) => Math.hypot(x - a[0], y - a[1], z - a[2]) - r,
- center: a,
- radius: r,
- };
- }
- const rr = r1 - r2;
- const a2 = l2 - rr * rr;
- const il2 = 1 / l2;
- return {
- distance(x, y, z) {
- const pax = x - a[0];
- const pay = y - a[1];
- const paz = z - a[2];
- const yv = dot(pax, pay, paz, ba);
- const zv = yv - l2;
- const qx = pax * l2 - ba[0] * yv;
- const qy = pay * l2 - ba[1] * yv;
- const qz = paz * l2 - ba[2] * yv;
- const x2 = qx * qx + qy * qy + qz * qz;
- const y2 = yv * yv * l2;
- const z2 = zv * zv * l2;
- const k = Math.sign(rr) * rr * rr * x2;
- if (Math.sign(zv) * a2 * z2 > k) return Math.sqrt(x2 + z2) * il2 - r2;
- if (Math.sign(yv) * a2 * y2 < k) return Math.sqrt(x2 + y2) * il2 - r1;
- return (Math.sqrt(x2 * a2 * il2) + yv * rr) * il2 - r1;
- },
- center: mid(a, b),
- radius: Math.sqrt(l2) / 2 + Math.max(r1, r2),
- };
-}
-
-/** Catmull-Rom samples through `points`, with radii interpolated alongside. */
-function tubeSamples(points: Vec3[], radius: number | number[]) {
- const radii = points.map((_, i) =>
- typeof radius === "number"
- ? radius
- : (radius[i] ?? radius[radius.length - 1] ?? 1),
- );
- if (points.length < 2) throw new Error("tube: needs at least two points");
- const out: { p: Vec3; r: number }[] = [];
- const steps = 6;
- const at = (i: number) =>
- points[Math.min(points.length - 1, Math.max(0, i))] as Vec3;
- for (let i = 0; i < points.length - 1; i++) {
- const p0 = at(i - 1);
- const p1 = at(i);
- const p2 = at(i + 1);
- const p3 = at(i + 2);
- for (let s = 0; s < steps; s++) {
- const t = s / steps;
- const t2 = t * t;
- const t3 = t2 * t;
- const c = (k: 0 | 1 | 2) =>
- 0.5 *
- (2 * p1[k] +
- (-p0[k] + p2[k]) * t +
- (2 * p0[k] - 5 * p1[k] + 4 * p2[k] - p3[k]) * t2 +
- (-p0[k] + 3 * p1[k] - 3 * p2[k] + p3[k]) * t3);
- const r =
- (radii[i] as number) +
- ((radii[i + 1] as number) - (radii[i] as number)) * t;
- out.push({ p: [c(0), c(1), c(2)], r });
- }
- }
- out.push({ p: at(points.length - 1), r: radii[radii.length - 1] as number });
- return out;
-}
-
-function tube(points: Vec3[], radius: number | number[]): ShapeField {
- const samples = tubeSamples(points, radius);
- const cones: ShapeField[] = [];
- for (let i = 0; i + 1 < samples.length; i++) {
- const a = samples[i] as { p: Vec3; r: number };
- const b = samples[i + 1] as { p: Vec3; r: number };
- cones.push(roundCone(a.p, b.p, a.r, b.r));
- }
- const center = mid(points[0] as Vec3, points[points.length - 1] as Vec3);
- let radiusBound = 0;
- for (const s of samples)
- radiusBound = Math.max(
- radiusBound,
- Math.hypot(s.p[0] - center[0], s.p[1] - center[1], s.p[2] - center[2]) +
- s.r,
- );
- return {
- distance(x, y, z) {
- let d = Number.POSITIVE_INFINITY;
- for (const c of cones) {
- // A cone can't be nearer than its bounding sphere allows.
- const lb =
- Math.hypot(x - c.center[0], y - c.center[1], z - c.center[2]) -
- c.radius;
- if (lb >= d) continue;
- const e = c.distance(x, y, z);
- if (e < d) d = e;
- }
- return d;
- },
- center,
- radius: radiusBound,
- };
-}
-
-/** Signed distance to a closed polygon in 2D (Quilez). */
-function polygon2d(v: [number, number][], px: number, py: number): number {
- const first = v[0] as [number, number];
- let d = (px - first[0]) ** 2 + (py - first[1]) ** 2;
- let s = 1;
- for (let i = 0, j = v.length - 1; i < v.length; j = i, i++) {
- const vi = v[i] as [number, number];
- const vj = v[j] as [number, number];
- const ex = vj[0] - vi[0];
- const ey = vj[1] - vi[1];
- const wx = px - vi[0];
- const wy = py - vi[1];
- const h = Math.min(
- 1,
- Math.max(0, (wx * ex + wy * ey) / (ex * ex + ey * ey || 1e-12)),
- );
- const bx = wx - ex * h;
- const by = wy - ey * h;
- d = Math.min(d, bx * bx + by * by);
- const c1 = py >= vi[1];
- const c2 = py < vj[1];
- const c3 = ex * wy > ey * wx;
- if ((c1 && c2 && c3) || (!c1 && !c2 && !c3)) s = -s;
- }
- return s * Math.sqrt(d);
-}
-
-/** The shape's distance field and bounds in its local frame. */
-export function shapeField(s: Shape): ShapeField {
- switch (s.shape) {
- case "sphere":
- return {
- distance: (x, y, z) => Math.hypot(x, y, z) - s.radius,
- center: [0, 0, 0],
- radius: s.radius,
- };
- case "ellipsoid": {
- const [a, b, c] = s.radii;
- return {
- distance(x, y, z) {
- const k0 = Math.hypot(x / a, y / b, z / c);
- const k1 = Math.hypot(x / (a * a), y / (b * b), z / (c * c));
- return k1 > 1e-12 ? (k0 * (k0 - 1)) / k1 : -Math.min(a, b, c);
- },
- center: [0, 0, 0],
- radius: Math.max(a, b, c),
- };
- }
- case "box": {
- const r = Math.max(0, s.radius ?? 0);
- const [hx, hy, hz] = [
- s.size[0] / 2 - r,
- s.size[1] / 2 - r,
- s.size[2] / 2 - r,
- ];
- return {
- distance(x, y, z) {
- const qx = Math.abs(x) - hx;
- const qy = Math.abs(y) - hy;
- const qz = Math.abs(z) - hz;
- return (
- Math.hypot(Math.max(qx, 0), Math.max(qy, 0), Math.max(qz, 0)) +
- Math.min(Math.max(qx, qy, qz), 0) -
- r
- );
- },
- center: [0, 0, 0],
- radius: Math.hypot(s.size[0], s.size[1], s.size[2]) / 2,
- };
- }
- case "cylinder":
- return {
- distance(x, y, z) {
- const dr = Math.hypot(x, z) - s.radius;
- const dy = Math.abs(y) - s.height / 2;
- return (
- Math.min(Math.max(dr, dy), 0) +
- Math.hypot(Math.max(dr, 0), Math.max(dy, 0))
- );
- },
- center: [0, 0, 0],
- radius: Math.hypot(s.radius, s.height / 2),
- };
- case "capsule":
- return segment(s.from, s.to, s.radius);
- case "roundCone":
- return roundCone(s.from, s.to, s.radii[0], s.radii[1]);
- case "tube":
- return tube(s.points, s.radius);
- case "torus":
- return {
- distance: (x, y, z) =>
- Math.hypot(Math.hypot(x, z) - s.radius, y) - s.tube,
- center: [0, 0, 0],
- radius: s.radius + s.tube,
- };
- case "lathe": {
- if (s.profile.length < 3)
- throw new Error("lathe: profile needs three points");
- let radius = 0;
- for (const [r, y] of s.profile)
- radius = Math.max(radius, Math.hypot(r, y));
- return {
- distance: (x, y, z) => polygon2d(s.profile, Math.hypot(x, z), y),
- center: [0, 0, 0],
- radius,
- };
- }
- }
-}
diff --git a/packages/forge/src/sculpt/simplify.ts b/packages/forge/src/sculpt/simplify.ts
deleted file mode 100644
index 2f8c2a19..00000000
--- a/packages/forge/src/sculpt/simplify.ts
+++ /dev/null
@@ -1,338 +0,0 @@
-/**
- * Quadric error simplification (Garland and Heckbert, 1997): edges collapse
- * cheapest-first, each costed by the summed squared distance to the planes
- * of the faces it has absorbed. Collapses that would tear the surface (the
- * link condition), fold a face over, or move a border between face tags
- * (materials) are refused, so the mesh stays closed and its materials keep
- * their outlines.
- */
-import type { IndexedMesh } from "./mesh.js";
-
-export interface SimplifyOptions {
- /** Stop at this many triangles or fewer. */
- triangles: number;
- /** Per-triangle tags (material ids); vertices where tags meet stay put. */
- tags?: Int32Array;
-}
-
-export interface SimplifiedMesh extends IndexedMesh {
- tags: Int32Array;
-}
-
-interface Entry {
- cost: number;
- a: number;
- b: number;
- va: number;
- vb: number;
- x: number;
- y: number;
- z: number;
-}
-
-class Heap {
- private items: Entry[] = [];
- get size() {
- return this.items.length;
- }
- push(e: Entry) {
- const a = this.items;
- a.push(e);
- let i = a.length - 1;
- while (i > 0) {
- const p = (i - 1) >> 1;
- if ((a[p] as Entry).cost <= e.cost) break;
- a[i] = a[p] as Entry;
- i = p;
- }
- a[i] = e;
- }
- pop(): Entry | undefined {
- const a = this.items;
- const top = a[0];
- const last = a.pop();
- if (!a.length || !last) return top;
- let i = 0;
- for (;;) {
- const l = 2 * i + 1;
- if (l >= a.length) break;
- const r = l + 1;
- const c =
- r < a.length && (a[r] as Entry).cost < (a[l] as Entry).cost ? r : l;
- if ((a[c] as Entry).cost >= last.cost) break;
- a[i] = a[c] as Entry;
- i = c;
- }
- a[i] = last;
- return top;
- }
-}
-
-/** Q += plane quadric of (n, d) weighted by w; 10 symmetric entries per vertex. */
-function addPlane(
- q: Float64Array,
- o: number,
- nx: number,
- ny: number,
- nz: number,
- d: number,
- w: number,
-) {
- q[o] = (q[o] as number) + w * nx * nx;
- q[o + 1] = (q[o + 1] as number) + w * nx * ny;
- q[o + 2] = (q[o + 2] as number) + w * nx * nz;
- q[o + 3] = (q[o + 3] as number) + w * nx * d;
- q[o + 4] = (q[o + 4] as number) + w * ny * ny;
- q[o + 5] = (q[o + 5] as number) + w * ny * nz;
- q[o + 6] = (q[o + 6] as number) + w * ny * d;
- q[o + 7] = (q[o + 7] as number) + w * nz * nz;
- q[o + 8] = (q[o + 8] as number) + w * nz * d;
- q[o + 9] = (q[o + 9] as number) + w * d * d;
-}
-
-export function simplify(
- mesh: IndexedMesh,
- options: SimplifyOptions,
-): SimplifiedMesh {
- const P = Float64Array.from(mesh.positions);
- const F = Uint32Array.from(mesh.indices);
- const nv = P.length / 3;
- const nf = F.length / 3;
- const tags = options.tags
- ? Int32Array.from(options.tags)
- : new Int32Array(nf);
- if (nf <= options.triangles) return { positions: P, indices: F, tags };
-
- const faceAlive = new Uint8Array(nf).fill(1);
- const vertAlive = new Uint8Array(nv).fill(1);
- const version = new Uint32Array(nv);
- const faces: number[][] = Array.from({ length: nv }, () => []);
- for (let f = 0; f < nf; f++)
- for (let c = 0; c < 3; c++)
- (faces[F[f * 3 + c] as number] as number[]).push(f);
-
- const Q = new Float64Array(nv * 10);
- const normal = (f: number, out: number[]) => {
- const a = (F[f * 3] as number) * 3;
- const b = (F[f * 3 + 1] as number) * 3;
- const c = (F[f * 3 + 2] as number) * 3;
- const ux = (P[b] as number) - (P[a] as number);
- const uy = (P[b + 1] as number) - (P[a + 1] as number);
- const uz = (P[b + 2] as number) - (P[a + 2] as number);
- const vx = (P[c] as number) - (P[a] as number);
- const vy = (P[c + 1] as number) - (P[a + 1] as number);
- const vz = (P[c + 2] as number) - (P[a + 2] as number);
- out[0] = uy * vz - uz * vy;
- out[1] = uz * vx - ux * vz;
- out[2] = ux * vy - uy * vx;
- return a;
- };
- const n3 = [0, 0, 0];
- for (let f = 0; f < nf; f++) {
- const a = normal(f, n3);
- const len = Math.hypot(n3[0] as number, n3[1] as number, n3[2] as number);
- if (len < 1e-20) continue;
- const nx = (n3[0] as number) / len;
- const ny = (n3[1] as number) / len;
- const nz = (n3[2] as number) / len;
- const d = -(
- nx * (P[a] as number) +
- ny * (P[a + 1] as number) +
- nz * (P[a + 2] as number)
- );
- for (let c = 0; c < 3; c++)
- addPlane(Q, (F[f * 3 + c] as number) * 10, nx, ny, nz, d, len / 2);
- }
-
- const locked = new Uint8Array(nv);
- if (options.tags)
- for (let v = 0; v < nv; v++) {
- const fs = faces[v] as number[];
- const t0 = tags[fs[0] as number];
- if (fs.some((f) => tags[f] !== t0)) locked[v] = 1;
- }
-
- const err = (o: number, o2: number, x: number, y: number, z: number) => {
- const q = (i: number) => (Q[o + i] as number) + (Q[o2 + i] as number);
- return (
- q(0) * x * x +
- 2 * q(1) * x * y +
- 2 * q(2) * x * z +
- 2 * q(3) * x +
- q(4) * y * y +
- 2 * q(5) * y * z +
- 2 * q(6) * y +
- q(7) * z * z +
- 2 * q(8) * z +
- q(9)
- );
- };
-
- const heap = new Heap();
- const consider = (a: number, b: number) => {
- if (locked[a] && locked[b]) return;
- const oa = a * 10;
- const ob = b * 10;
- const pa = a * 3;
- const pb = b * 3;
- const cands: [number, number, number][] = [];
- if (!locked[b])
- cands.push([P[pa] as number, P[pa + 1] as number, P[pa + 2] as number]);
- if (!locked[a])
- cands.push([P[pb] as number, P[pb + 1] as number, P[pb + 2] as number]);
- if (!locked[a] && !locked[b])
- cands.push([
- ((P[pa] as number) + (P[pb] as number)) / 2,
- ((P[pa + 1] as number) + (P[pb + 1] as number)) / 2,
- ((P[pa + 2] as number) + (P[pb + 2] as number)) / 2,
- ]);
- let best = cands[0] as [number, number, number];
- let cost = Number.POSITIVE_INFINITY;
- for (const c of cands) {
- const e = err(oa, ob, c[0], c[1], c[2]);
- if (e < cost) {
- cost = e;
- best = c;
- }
- }
- heap.push({
- cost: Math.max(0, cost),
- a,
- b,
- va: version[a] as number,
- vb: version[b] as number,
- x: best[0],
- y: best[1],
- z: best[2],
- });
- };
-
- const neighbors = (v: number, out: Set<number>) => {
- out.clear();
- for (const f of faces[v] as number[])
- if (faceAlive[f])
- for (let c = 0; c < 3; c++) {
- const w = F[f * 3 + c] as number;
- if (w !== v) out.add(w);
- }
- return out;
- };
- const na = new Set<number>();
- const nb = new Set<number>();
- for (let v = 0; v < nv; v++)
- for (const w of neighbors(v, na)) if (w > v) consider(v, w);
-
- /** Whether moving v (one of the collapsing pair) to (x, y, z) folds any face that survives. */
- const folds = (v: number, other: number, x: number, y: number, z: number) => {
- const before = [0, 0, 0];
- const after = [0, 0, 0];
- for (const f of faces[v] as number[]) {
- if (!faceAlive[f]) continue;
- let hasOther = false;
- for (let c = 0; c < 3; c++) if (F[f * 3 + c] === other) hasOther = true;
- if (hasOther) continue;
- normal(f, before);
- const o = v * 3;
- const sx = P[o] as number;
- const sy = P[o + 1] as number;
- const sz = P[o + 2] as number;
- P[o] = x;
- P[o + 1] = y;
- P[o + 2] = z;
- normal(f, after);
- P[o] = sx;
- P[o + 1] = sy;
- P[o + 2] = sz;
- const lb = Math.hypot(
- before[0] as number,
- before[1] as number,
- before[2] as number,
- );
- const la = Math.hypot(
- after[0] as number,
- after[1] as number,
- after[2] as number,
- );
- if (la < lb * 1e-3) return true;
- const cos =
- ((before[0] as number) * (after[0] as number) +
- (before[1] as number) * (after[1] as number) +
- (before[2] as number) * (after[2] as number)) /
- (lb * la);
- if (cos < 0.3) return true;
- }
- return false;
- };
-
- let live = nf;
- while (live > options.triangles && heap.size) {
- const e = heap.pop() as Entry;
- const { a, b } = e;
- if (!vertAlive[a] || !vertAlive[b]) continue;
- if (version[a] !== e.va || version[b] !== e.vb) continue;
- // Link condition: the pair may share only the two vertices opposite their edge.
- neighbors(a, na);
- if (!na.has(b)) continue;
- neighbors(b, nb);
- let shared = 0;
- for (const w of na) if (nb.has(w)) shared++;
- if (shared !== 2) continue;
- if (folds(a, b, e.x, e.y, e.z) || folds(b, a, e.x, e.y, e.z)) continue;
- // Keep a, drop b.
- const keep = locked[b] ? b : a;
- const drop = keep === a ? b : a;
- P[keep * 3] = e.x;
- P[keep * 3 + 1] = e.y;
- P[keep * 3 + 2] = e.z;
- for (let i = 0; i < 10; i++)
- Q[keep * 10 + i] =
- (Q[keep * 10 + i] as number) + (Q[drop * 10 + i] as number);
- const kept = faces[keep] as number[];
- for (const f of faces[drop] as number[]) {
- if (!faceAlive[f]) continue;
- let hasKeep = false;
- for (let c = 0; c < 3; c++) if (F[f * 3 + c] === keep) hasKeep = true;
- if (hasKeep) {
- faceAlive[f] = 0;
- live--;
- continue;
- }
- for (let c = 0; c < 3; c++)
- if (F[f * 3 + c] === drop) F[f * 3 + c] = keep;
- kept.push(f);
- }
- faces[keep] = kept.filter((f) => faceAlive[f]);
- faces[drop] = [];
- vertAlive[drop] = 0;
- // Only edges at `keep` changed (its position and quadric): re-cost them;
- // the version bump retires their old heap entries.
- version[keep] = (version[keep] as number) + 1;
- for (const w of neighbors(keep, na)) consider(keep, w);
- }
-
- const remap = new Int32Array(nv).fill(-1);
- const positions: number[] = [];
- const indices: number[] = [];
- const outTags: number[] = [];
- for (let f = 0; f < nf; f++) {
- if (!faceAlive[f]) continue;
- for (let c = 0; c < 3; c++) {
- const v = F[f * 3 + c] as number;
- if ((remap[v] as number) < 0) {
- remap[v] = positions.length / 3;
- positions.push(
- P[v * 3] as number,
- P[v * 3 + 1] as number,
- P[v * 3 + 2] as number,
- );
- }
- indices.push(remap[v] as number);
- }
- outTags.push(tags[f] as number);
- }
- return {
- positions: Float64Array.from(positions),
- indices: Uint32Array.from(indices),
- tags: Int32Array.from(outTags),
- };
-}
diff --git a/packages/forge/src/sculpt/skin.ts b/packages/forge/src/sculpt/skin.ts
deleted file mode 100644
index d571d2f3..00000000
--- a/packages/forge/src/sculpt/skin.ts
+++ /dev/null
@@ -1,224 +0,0 @@
-/**
- * Skin weights from the sculpt itself. A vertex is moved by every part
- * whose own surface reaches it, fading to nothing a `falloff` beyond that
- * surface: where two limbs blend smoothly they share the vertices of the
- * blend, a hard seam moves with whichever side it belongs to, and a rigid
- * part moves with its joint alone. A part spread over several joints (a
- * torso over the spine) shares out by distance to their bones. A few
- * passes of smoothing over the mesh then soften the seams, and each vertex
- * keeps its four strongest joints.
- */
-import type { Skeleton, Vec3 } from "../skeleton.js";
-import type { PreparedPart, SculptField } from "./field.js";
-
-export interface SkinOptions {
- /** Smoothing passes over the mesh. Default 2. */
- smoothing?: number;
- /** The smallest falloff, model units (about 1.5 lattice cells). */
- minFalloff: number;
-}
-
-export interface SkinWeights {
- joints: Uint16Array;
- weights: Float32Array;
-}
-
-interface Bone {
- joint: number;
- a: Vec3;
- b: Vec3;
-}
-
-function segmentDistance(p: Vec3, a: Vec3, b: Vec3): number {
- const bx = b[0] - a[0];
- const by = b[1] - a[1];
- const bz = b[2] - a[2];
- const l2 = bx * bx + by * by + bz * bz;
- const px = p[0] - a[0];
- const py = p[1] - a[1];
- const pz = p[2] - a[2];
- const t =
- l2 > 0 ? Math.min(1, Math.max(0, (px * bx + py * by + pz * bz) / l2)) : 0;
- return Math.hypot(px - bx * t, py - by * t, pz - bz * t);
-}
-
-/** Each joint's bone: from the joint to its first child (a point for leaves). */
-function bones(skeleton: Skeleton): Bone[] {
- return skeleton.joints.map((j) => {
- const child = skeleton.children(j.name)[0];
- return { joint: j.index, a: j.at, b: child ? child.at : j.at };
- });
-}
-
-/** The joints (bones) each part moves with. */
-export function partBones(field: SculptField, skeleton: Skeleton): Bone[][] {
- const all = bones(skeleton);
- return field.parts.map((p) => {
- const spec = p.part.joint;
- if (spec !== undefined) {
- const names = typeof spec === "string" ? [spec] : spec;
- if (!names.length)
- throw new Error(`sculpt: part ${label(p)} has an empty joint list`);
- return names.map((n) => {
- if (!skeleton.has(n))
- throw new Error(
- `sculpt: part ${label(p)} names unknown joint "${n}"`,
- );
- return all[skeleton.joint(n).index] as Bone;
- });
- }
- let best = all[0] as Bone;
- let bestD = Number.POSITIVE_INFINITY;
- for (const b of all) {
- const d = segmentDistance(p.anchor, b.a, b.b);
- if (d < bestD) {
- bestD = d;
- best = b;
- }
- }
- return [best];
- });
-}
-
-const label = (p: PreparedPart) => p.part.name ?? `#${p.index}`;
-
-/** Adds `w` to joint `j` in a small sparse list. */
-function accumulate(list: number[], j: number, w: number) {
- for (let i = 0; i < list.length; i += 2)
- if (list[i] === j) {
- list[i + 1] = (list[i + 1] as number) + w;
- return;
- }
- list.push(j, w);
-}
-
-/** Skin weights for mesh vertices (`positions`, triangles `indices`). */
-export function skinWeights(
- field: SculptField,
- skeleton: Skeleton,
- positions: Float64Array,
- indices: Uint32Array,
- options: SkinOptions,
-): SkinWeights {
- const nv = positions.length / 3;
- const partBone = partBones(field, skeleton);
- const unions = field.parts.filter((p) => p.op === "union");
- const falloff = unions.map(
- (p) => p.part.falloff ?? Math.max(p.k, options.minFalloff),
- );
- const lists: number[][] = new Array(nv);
- const fixed = new Uint8Array(nv);
-
- const share = (list: number[], p: PreparedPart, at: Vec3, w: number) => {
- const bs = partBone[p.index] as Bone[];
- if (bs.length === 1) {
- accumulate(list, (bs[0] as Bone).joint, w);
- return;
- }
- // Inverse fourth power of the distance to each bone: smooth, and near-exclusive close to a bone.
- const ws = bs.map((b) => 1 / (segmentDistance(at, b.a, b.b) ** 4 + 1e-6));
- const sum = ws.reduce((s, v) => s + v, 0);
- for (let i = 0; i < bs.length; i++)
- accumulate(list, (bs[i] as Bone).joint, (w * (ws[i] as number)) / sum);
- };
-
- for (let v = 0; v < nv; v++) {
- const at: Vec3 = [
- positions[v * 3] as number,
- positions[v * 3 + 1] as number,
- positions[v * 3 + 2] as number,
- ];
- field.distance(at[0], at[1], at[2]);
- const owner = field.parts[field.owner] as PreparedPart;
- const list: number[] = [];
- if (owner.part.rigid) {
- share(list, owner, at, 1);
- fixed[v] = 1;
- lists[v] = list;
- continue;
- }
- unions.forEach((p, i) => {
- if (p.part.rigid && p !== owner) return;
- const f = falloff[i] as number;
- const bound =
- Math.hypot(
- at[0] - p.center[0],
- at[1] - p.center[1],
- at[2] - p.center[2],
- ) - p.radius;
- if (bound > f) return;
- const e = p.distance(at[0], at[1], at[2]);
- if (e >= f) return;
- const t = e <= 0 ? 1 : 1 - e / f;
- share(list, p, at, t * t * (3 - 2 * t));
- });
- if (!list.length) share(list, owner, at, 1);
- lists[v] = list;
- }
-
- smooth(lists, fixed, indices, options.smoothing ?? 2);
-
- const joints = new Uint16Array(nv * 4);
- const weights = new Float32Array(nv * 4);
- for (let v = 0; v < nv; v++) {
- const list = lists[v] as number[];
- const pairs: [number, number][] = [];
- for (let i = 0; i < list.length; i += 2)
- pairs.push([list[i] as number, list[i + 1] as number]);
- pairs.sort((a, b) => b[1] - a[1]);
- const top = pairs.slice(0, 4);
- const sum = top.reduce((s, p) => s + p[1], 0) || 1;
- top.forEach(([j, w], i) => {
- joints[v * 4 + i] = j;
- weights[v * 4 + i] = w / sum;
- });
- }
- return { joints, weights };
-}
-
-/** Laplacian passes over the mesh's edges; rigid vertices stay fixed. */
-function smooth(
- lists: number[][],
- fixed: Uint8Array,
- indices: Uint32Array,
- passes: number,
-) {
- if (passes <= 0) return;
- const nv = lists.length;
- const adj: number[][] = Array.from({ length: nv }, () => []);
- for (let t = 0; t < indices.length; t += 3)
- for (let e = 0; e < 3; e++) {
- const a = indices[t + e] as number;
- const b = indices[t + ((e + 1) % 3)] as number;
- (adj[a] as number[]).push(b);
- }
- const normalize = (l: number[]) => {
- let s = 0;
- for (let i = 1; i < l.length; i += 2) s += l[i] as number;
- if (s > 0)
- for (let i = 1; i < l.length; i += 2) l[i] = (l[i] as number) / s;
- };
- for (const l of lists) normalize(l);
- for (let pass = 0; pass < passes; pass++) {
- const next: number[][] = new Array(nv);
- for (let v = 0; v < nv; v++) {
- const own = lists[v] as number[];
- const around = adj[v] as number[];
- if (fixed[v] || !around.length) {
- next[v] = own;
- continue;
- }
- const out: number[] = [];
- for (let i = 0; i < own.length; i += 2)
- accumulate(out, own[i] as number, 0.5 * (own[i + 1] as number));
- const w = 0.5 / around.length;
- for (const u of around) {
- const l = lists[u] as number[];
- for (let i = 0; i < l.length; i += 2)
- accumulate(out, l[i] as number, w * (l[i + 1] as number));
- }
- next[v] = out;
- }
- for (let v = 0; v < nv; v++) lists[v] = next[v] as number[];
- }
-}
diff --git a/packages/forge/src/subdivide.test.ts b/packages/forge/src/subdivide.test.ts
deleted file mode 100644
index 3df95815..00000000
--- a/packages/forge/src/subdivide.test.ts
+++ /dev/null
@@ -1,86 +0,0 @@
-/**
- * Loop subdivision splits each triangle in four, relaxes the surface, and
- * carries what rides on it exactly: a blend shape that translates the
- * whole surface still translates it, skin weights stay normalized, and
- * welded seam copies end up on one point.
- */
-import { describe, expect, it } from "vitest";
-import { subdivide } from "./index.js";
-
-/** An octahedron with one vertex split at a UV seam (vertex 6 copies 0). */
-function octahedron() {
- const positions = [
- 1, 0, 0, -1, 0, 0, 0, 1, 0, 0, -1, 0, 0, 0, 1, 0, 0, -1, 1, 0, 0,
- ];
- const indices = [
- 0, 2, 4, 2, 1, 4, 1, 3, 4, 3, 6, 4, 2, 0, 5, 1, 2, 5, 3, 1, 5, 6, 3, 5,
- ];
- const n = positions.length / 3;
- const uvs = Array.from({ length: n * 2 }, (_, i) => (i === 12 ? 1 : 0));
- const joints = Array.from({ length: n * 4 }, (_, i) => (i % 4 === 1 ? 1 : 0));
- const weights = Array.from({ length: n }, (_, v) =>
- v % 2 ? [0.25, 0.75, 0, 0] : [1, 0, 0, 0],
- ).flat();
- weights.splice(24, 4, 1, 0, 0, 0); // the seam copy weighs like vertex 0
- return {
- positions,
- indices,
- uvs,
- joints,
- weights,
- weld: [0, 1, 2, 3, 4, 5, 0],
- };
-}
-
-describe("subdivide", () => {
- it("quadruples the triangles and moves the surface toward its limit", () => {
- const o = octahedron();
- const s = subdivide({ ...o }, { weld: o.weld });
- expect(s.indices?.length).toBe(o.indices.length * 4);
- // Corners pull in toward the smooth limit surface.
- const r = Math.hypot(...Array.from(s.positions).slice(0, 3));
- expect(r).toBeLessThan(1);
- expect(r).toBeGreaterThan(0.5);
- });
-
- it("welds seam copies into one point, and keeps their own UVs", () => {
- const o = octahedron();
- const s = subdivide({ ...o }, { weld: o.weld, levels: 2 });
- const p = Array.from(s.positions);
- const u = Array.from(s.uvs ?? []);
- const n = p.length / 3;
- const at = (v: number) => p.slice(v * 3, v * 3 + 3);
- let seamPairs = 0;
- for (let a = 0; a < n; a++)
- for (let b = a + 1; b < n; b++) {
- const d = Math.hypot(...at(a).map((x, k) => x - (at(b)[k] as number)));
- if (d < 1e-9 && u[a * 2] !== u[b * 2]) seamPairs++;
- // Distinct surface points never coincide.
- if (d < 1e-9) expect(u[a * 2]).not.toBe(u[b * 2]);
- }
- expect(seamPairs).toBeGreaterThan(0);
- });
-
- it("carries blend shapes and skin weights exactly", () => {
- const o = octahedron();
- const lift = o.positions.map((_, i) => (i % 3 === 1 ? 0.5 : 0));
- const s = subdivide(
- { ...o, targets: [{ name: "lift", positions: lift }] },
- { weld: o.weld, levels: 2 },
- );
- const t = Array.from(s.targets?.[0]?.positions ?? []);
- expect(t.length).toBe(s.positions.length);
- for (let i = 0; i < t.length; i++)
- expect(t[i]).toBeCloseTo(i % 3 === 1 ? 0.5 : 0, 12);
- const w = Array.from(s.weights ?? []);
- for (let v = 0; v < w.length / 4; v++)
- expect(w.slice(v * 4, v * 4 + 4).reduce((a, b) => a + b, 0)).toBeCloseTo(
- 1,
- 9,
- );
- // Normals are unit length.
- const nn = Array.from(s.normals ?? []);
- for (let v = 0; v < nn.length / 3; v++)
- expect(Math.hypot(...nn.slice(v * 3, v * 3 + 3))).toBeCloseTo(1, 9);
- });
-});
diff --git a/packages/forge/src/subdivide.ts b/packages/forge/src/subdivide.ts
deleted file mode 100644
index 9fae8b73..00000000
--- a/packages/forge/src/subdivide.ts
+++ /dev/null
@@ -1,296 +0,0 @@
-/**
- * Loop subdivision of a triangle primitive: each triangle splits in four
- * and the surface relaxes toward its smooth limit (Loop, 1987). Everything
- * that moves with the surface rides the same linear stencil, so it stays
- * exact: blend shape deltas, skin weights (renormalized to four joints).
- * UVs are interpolated linearly per face corner, so texture seams stay
- * where they are. Vertices duplicated at a seam share one position: pass
- * `weld` (the same id for every copy) and the seam subdivides as one
- * surface instead of opening into a crease.
- */
-import type { MorphTargetSpec, PrimitiveSpec } from "./document.js";
-
-export interface SubdivideOptions {
- /** Levels (each multiplies the triangles by four). Default 1. */
- levels?: number;
- /** Per vertex: a topology id shared by copies of one surface point (UV seams). Default: the vertex index. */
- weld?: ArrayLike<number>;
-}
-
-type Numbers = ArrayLike<number>;
-
-/** A vertex of the result as an affine combination of topology vertices. */
-type Stencil = [number, number][];
-
-export function subdivide(
- p: PrimitiveSpec,
- options: SubdivideOptions = {},
-): PrimitiveSpec {
- let out = p;
- let weld = options.weld;
- for (let l = 0; l < (options.levels ?? 1); l++) {
- const r = subdivideOnce(out, weld);
- out = r.primitive;
- weld = r.weld;
- }
- return out;
-}
-
-function subdivideOnce(
- p: PrimitiveSpec,
- weldIn?: Numbers,
-): { primitive: PrimitiveSpec; weld: number[] } {
- const nv = p.positions.length / 3;
- const idx = Array.from(p.indices ?? Array.from({ length: nv }, (_, i) => i));
- const weld = weldIn
- ? Array.from(weldIn)
- : Array.from({ length: nv }, (_, i) => i);
- // Topology vertices: one per weld id.
- const topoOf = new Map<number, number>();
- const repr: number[] = [];
- const topo = weld.map((w, v) => {
- let t = topoOf.get(w);
- if (t === undefined) {
- t = repr.length;
- topoOf.set(w, t);
- repr.push(v);
- }
- return t;
- });
- const nt = repr.length;
-
- // Edges between topology vertices, with the opposite vertex of each face on them.
- const edgeKey = (a: number, b: number) => (a < b ? a * nt + b : b * nt + a);
- const opposite = new Map<number, number[]>();
- const neighbors: Set<number>[] = Array.from({ length: nt }, () => new Set());
- for (let f = 0; f < idx.length; f += 3)
- for (let k = 0; k < 3; k++) {
- const a = topo[idx[f + k] as number] as number;
- const b = topo[idx[f + ((k + 1) % 3)] as number] as number;
- const c = topo[idx[f + ((k + 2) % 3)] as number] as number;
- const key = edgeKey(a, b);
- const list = opposite.get(key) ?? [];
- list.push(c);
- opposite.set(key, list);
- (neighbors[a] as Set<number>).add(b);
- (neighbors[b] as Set<number>).add(a);
- }
- const boundary = (a: number, b: number) =>
- (opposite.get(edgeKey(a, b))?.length ?? 0) < 2;
-
- // Loop's stencils: moved old vertices, new edge vertices.
- const vertexStencil = (t: number): Stencil => {
- const ns = [...(neighbors[t] as Set<number>)];
- const rim = ns.filter((n) => boundary(t, n));
- if (rim.length >= 2)
- return [
- [t, 0.75],
- [rim[0] as number, 0.125],
- [rim[1] as number, 0.125],
- ];
- const n = ns.length;
- if (!n) return [[t, 1]];
- const beta = n === 3 ? 3 / 16 : 3 / (8 * n);
- return [[t, 1 - n * beta], ...ns.map((m): [number, number] => [m, beta])];
- };
- const edgeStencil = (a: number, b: number): Stencil => {
- const opp = opposite.get(edgeKey(a, b)) ?? [];
- if (opp.length !== 2)
- return [
- [a, 0.5],
- [b, 0.5],
- ];
- return [
- [a, 0.375],
- [b, 0.375],
- [opp[0] as number, 0.125],
- [opp[1] as number, 0.125],
- ];
- };
-
- // Output vertices: an old corner (topology vertex + its own UV), or an
- // edge's new vertex per distinct UV midpoint.
- const stencils: Stencil[] = [];
- const uvs: number[] = [];
- const uv1: number[] = [];
- const hasUv = Boolean(p.uvs);
- const hasUv1 = Boolean(p.uvs1);
- const newWeld: number[] = [];
- const oldOut = new Map<number, number>();
- const edgeOut = new Map<string, number>();
- const pushUv = (
- dst: number[],
- src: Numbers | undefined,
- a: number,
- b?: number,
- ) => {
- if (!src) return;
- const u =
- b === undefined
- ? (src[a * 2] as number)
- : ((src[a * 2] as number) + (src[b * 2] as number)) / 2;
- const v =
- b === undefined
- ? (src[a * 2 + 1] as number)
- : ((src[a * 2 + 1] as number) + (src[b * 2 + 1] as number)) / 2;
- dst.push(u, v);
- };
- const old = (v: number) => {
- let o = oldOut.get(v);
- if (o === undefined) {
- o = stencils.length;
- oldOut.set(v, o);
- stencils.push(vertexStencil(topo[v] as number));
- pushUv(uvs, p.uvs, v);
- pushUv(uv1, p.uvs1, v);
- newWeld.push(topo[v] as number);
- }
- return o;
- };
- const mid = (va: number, vb: number) => {
- const a = topo[va] as number;
- const b = topo[vb] as number;
- const uvKey = hasUv
- ? `${(((p.uvs?.[va * 2] as number) + (p.uvs?.[vb * 2] as number)) / 2).toFixed(6)},${(((p.uvs?.[va * 2 + 1] as number) + (p.uvs?.[vb * 2 + 1] as number)) / 2).toFixed(6)}`
- : "";
- const key = `${edgeKey(a, b)}|${uvKey}`;
- let o = edgeOut.get(key);
- if (o === undefined) {
- o = stencils.length;
- edgeOut.set(key, o);
- stencils.push(edgeStencil(a, b));
- pushUv(uvs, p.uvs, va, vb);
- pushUv(uv1, p.uvs1, va, vb);
- newWeld.push(nt + edgeKey(a, b));
- }
- return o;
- };
- const indices: number[] = [];
- for (let f = 0; f < idx.length; f += 3) {
- const [a, b, c] = [idx[f], idx[f + 1], idx[f + 2]] as [
- number,
- number,
- number,
- ];
- const [oa, ob, oc] = [old(a), old(b), old(c)];
- const [ab, bc, ca] = [mid(a, b), mid(b, c), mid(c, a)];
- indices.push(oa, ab, ca, ab, ob, bc, ca, bc, oc, ab, bc, ca);
- }
-
- // Per-topology-vertex values, then the stencils.
- const perTopo = (data: Numbers, size: number) => {
- const out = new Float64Array(nt * size);
- repr.forEach((v, t) => {
- for (let k = 0; k < size; k++)
- out[t * size + k] = data[v * size + k] as number;
- });
- return out;
- };
- const apply = (data: Float64Array, size: number) => {
- const out = new Array<number>(stencils.length * size).fill(0);
- stencils.forEach((s, i) => {
- for (const [t, w] of s)
- for (let k = 0; k < size; k++)
- out[i * size + k] =
- (out[i * size + k] as number) + w * (data[t * size + k] as number);
- });
- return out;
- };
- const positions = apply(perTopo(p.positions, 3), 3);
- const result: PrimitiveSpec = { ...p, positions, indices };
- if (hasUv) result.uvs = uvs;
- if (hasUv1) result.uvs1 = uv1;
- if (p.colors) result.colors = apply(perTopo(p.colors, 4), 4);
- if (p.joints && p.weights) {
- const j = p.joints;
- const w = p.weights;
- const lists = repr.map((v) => {
- const l = new Map<number, number>();
- for (let k = 0; k < 4; k++) {
- const wk = w[v * 4 + k] as number;
- if (wk > 0)
- l.set(
- j[v * 4 + k] as number,
- (l.get(j[v * 4 + k] as number) ?? 0) + wk,
- );
- }
- return l;
- });
- const joints: number[] = [];
- const weights: number[] = [];
- for (const s of stencils) {
- const acc = new Map<number, number>();
- for (const [t, sw] of s)
- for (const [jj, ww] of lists[t] as Map<number, number>)
- acc.set(jj, (acc.get(jj) ?? 0) + sw * ww);
- const top = [...acc]
- .filter(([, x]) => x > 0)
- .sort((a, b) => b[1] - a[1])
- .slice(0, 4);
- const sum = top.reduce((t, x) => t + x[1], 0) || 1;
- for (let k = 0; k < 4; k++) {
- joints.push(top[k]?.[0] ?? 0);
- weights.push((top[k]?.[1] ?? 0) / sum);
- }
- }
- result.joints = joints;
- result.weights = weights;
- }
- result.normals = smoothNormals(positions, indices, newWeld);
- if (p.targets?.length)
- result.targets = p.targets.map((t): MorphTargetSpec => {
- const delta = apply(perTopo(t.positions, 3), 3);
- if (!t.normals) return { name: t.name, positions: delta };
- const moved = positions.map((x, i) => x + (delta[i] as number));
- const shaped = smoothNormals(moved, indices, newWeld);
- return {
- name: t.name,
- positions: delta,
- normals: shaped.map((n, i) => n - (result.normals?.[i] as number)),
- };
- });
- return { primitive: result, weld: newWeld };
-}
-
-/** Area-weighted vertex normals, shared by welded copies. */
-export function smoothNormals(
- positions: Numbers,
- indices: Numbers,
- weld: Numbers,
-): number[] {
- const acc = new Map<number, [number, number, number]>();
- for (let f = 0; f < indices.length; f += 3) {
- const [a, b, c] = [indices[f], indices[f + 1], indices[f + 2]] as [
- number,
- number,
- number,
- ];
- const ux = (positions[b * 3] as number) - (positions[a * 3] as number);
- const uy =
- (positions[b * 3 + 1] as number) - (positions[a * 3 + 1] as number);
- const uz =
- (positions[b * 3 + 2] as number) - (positions[a * 3 + 2] as number);
- const vx = (positions[c * 3] as number) - (positions[a * 3] as number);
- const vy =
- (positions[c * 3 + 1] as number) - (positions[a * 3 + 1] as number);
- const vz =
- (positions[c * 3 + 2] as number) - (positions[a * 3 + 2] as number);
- const n: [number, number, number] = [
- uy * vz - uz * vy,
- uz * vx - ux * vz,
- ux * vy - uy * vx,
- ];
- for (const v of [a, b, c]) {
- const w = weld[v] as number;
- const cur = acc.get(w) ?? [0, 0, 0];
- acc.set(w, [cur[0] + n[0], cur[1] + n[1], cur[2] + n[2]]);
- }
- }
- const out: number[] = [];
- for (let v = 0; v < weld.length; v++) {
- const n = acc.get(weld[v] as number) ?? [0, 1, 0];
- const l = Math.hypot(n[0], n[1], n[2]) || 1;
- out.push(n[0] / l, n[1] / l, n[2] / l);
- }
- return out;
-}
diff --git a/packages/framefields/package.json b/packages/framefields/package.json
index b61d3a5d..92c84ad1 100644
--- a/packages/framefields/package.json
+++ b/packages/framefields/package.json
@@ -93,12 +93,6 @@
"import": "./dist/storage/index.mjs",
"default": "./dist/storage/index.mjs"
},
- "./forge": {
- "types": "./dist/forge/index.d.mts",
- "development": "./src/forge/index.ts",
- "import": "./dist/forge/index.mjs",
- "default": "./dist/forge/index.mjs"
- },
"./sam": {
"types": "./dist/sam/index.d.mts",
"development": "./src/sam/index.ts",
@@ -156,6 +150,7 @@
"@framefields/components": "workspace:*",
"@framefields/compositions": "workspace:*",
"@framefields/core": "workspace:*",
+ "@framefields/gltf-fixtures": "workspace:*",
"@framefields/node-audio-compressor": "workspace:*",
"@framefields/node-audio-delay": "workspace:*",
"@framefields/node-audio-fade": "workspace:*",
@@ -204,7 +199,6 @@
"@framefields/node-vision": "workspace:*",
"@framefields/renderer": "workspace:*",
"@framefields/renderers": "workspace:*",
- "@framefields/forge": "workspace:*",
"@framefields/storage": "workspace:*",
"@framefields/tensor-webgpu": "workspace:*",
"@framefields/tsconfig": "workspace:*",
diff --git a/packages/framefields/src/character-render.test.ts b/packages/framefields/src/character-render.test.ts
index 19eca272..22d3f135 100644
--- a/packages/framefields/src/character-render.test.ts
+++ b/packages/framefields/src/character-render.test.ts
@@ -8,7 +8,7 @@
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
-import { GlbBuilder } from "@framefields/forge";
+import { GlbBuilder } from "@framefields/gltf-fixtures";
import { afterAll, beforeAll, describe, expect, it } from "vitest";
import {
Composition,
diff --git a/packages/framefields/src/deform-motion-blur-render.test.ts b/packages/framefields/src/deform-motion-blur-render.test.ts
new file mode 100644
index 00000000..a3d45dfc
--- /dev/null
+++ b/packages/framefields/src/deform-motion-blur-render.test.ts
@@ -0,0 +1,175 @@
+/**
+ * Shutter motion blur of motion that lives below the model matrix: a mesh
+ * moved by its morph targets alone, and a text layer drawn as native glyphs
+ * in the 3D scene. Before the velocity pass saw deformed vertices and glyph
+ * planes, both rendered sharp under a moving shutter; and after a seek the
+ * history pass skipped layers placed in 3D by z alone.
+ */
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { GltfDocument } from "@framefields/gltf-fixtures";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+ Composition,
+ FontManager,
+ Layer,
+ LayerAnimation,
+ type LayoutNode,
+} from "./index.js";
+import { decodePngPixels } from "./test-utils/pixels.js";
+
+const SIZE = 400;
+const C = SIZE / 2;
+/** Morph slide over the 60-frame clip, px: 12 px per frame. */
+const SLIDE = 720;
+
+let dir = "";
+let file = "";
+
+beforeAll(async () => {
+ dir = await fs.mkdtemp(path.join(os.tmpdir(), "framefields-deform-blur-"));
+ file = path.join(dir, "slider.glb");
+ const doc = new GltfDocument();
+ const white = doc.addMaterial({ color: "#ffffff", unlit: true });
+ const h = 30;
+ doc.addNode({
+ mesh: doc.addMesh({
+ primitives: [
+ {
+ positions: [-h, -h, 0, h, -h, 0, h, h, 0, -h, h, 0],
+ normals: [0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1],
+ indices: [0, 1, 2, 0, 2, 3],
+ material: white,
+ targets: [
+ {
+ name: "slide",
+ positions: [SLIDE, 0, 0, SLIDE, 0, 0, SLIDE, 0, 0, SLIDE, 0, 0],
+ },
+ ],
+ },
+ ],
+ }),
+ });
+ await fs.writeFile(file, doc.toGlb());
+ await FontManager.register("assets/fonts/Inter.ttf");
+});
+afterAll(async () => {
+ await fs.rm(dir, { recursive: true, force: true });
+});
+
+function scene(layer: LayoutNode, motionBlur: boolean): Composition {
+ const comp = new Composition({
+ width: SIZE,
+ height: SIZE,
+ fps: 30,
+ 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,
+ motionBlur,
+ }),
+ layer,
+ ]);
+ return comp;
+}
+
+/** The quad slides from x = C - SLIDE / 2 to C + SLIDE / 2 by its morph weight. */
+const slider = () =>
+ Layer.glb(file, {
+ id: "slider",
+ x: C - SLIDE / 2,
+ y: C,
+ z: 0,
+ rotateX: 180,
+ morphs: {
+ slide: [
+ [0, 0],
+ [60, 1],
+ ],
+ },
+ }) as LayoutNode;
+
+/** A bold "I" on its own 3D plane, moving right 16 px per frame. */
+const word = () =>
+ Layer.text("I", {
+ id: "word",
+ position: "absolute",
+ x: C - 480 - 50,
+ y: C - 100,
+ z: 1,
+ width: 100,
+ height: 200,
+ fontFamily: "Inter",
+ fontWeight: 700,
+ fontSize: 160,
+ fill: "#ffffff",
+ } as never).animate(
+ LayerAnimation.create().keys("x", [
+ [0, C - 480 - 50],
+ [60, C + 480 - 50],
+ ]),
+ ) as LayoutNode;
+
+async function row(comp: Composition, frame: number, y: number) {
+ const png = await comp.renderFrame({ frame });
+ const { pixels } = await decodePngPixels(png);
+ return {
+ png,
+ line: Array.from(
+ { length: SIZE },
+ (_, x) => 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;
+
+describe("motion blur below the model matrix", () => {
+ it("streaks a mesh moved by its morph targets", async () => {
+ const sharp = await row(scene(slider(), false), 30, C);
+ const blurred = await row(scene(slider(), true), 30, C);
+ expect(partial(sharp.line)).toBeLessThan(4);
+ // 12 px per frame at a 180° shutter: each edge ramps over ~6 px.
+ expect(partial(blurred.line)).toBeGreaterThan(8);
+ });
+
+ it("renders a morphing frame the same after a seek as in order", async () => {
+ const inOrder = scene(slider(), true);
+ for (const f of [27, 28, 29]) await inOrder.renderFrame({ frame: f });
+ const sequential = (await row(inOrder, 30, C)).png;
+ const seeked = (await row(scene(slider(), true), 30, C)).png;
+ expect(seeked).toEqual(sequential);
+ });
+
+ it("streaks text glyphs on a moving 3D plane", async () => {
+ const sharp = await row(scene(word(), false), 30, C);
+ const blurred = await row(scene(word(), true), 30, C);
+ // The stem's two antialiased edges.
+ expect(partial(sharp.line)).toBeLessThan(6);
+ // 16 px per frame at a 180° shutter: each edge ramps over ~8 px.
+ expect(partial(blurred.line)).toBeGreaterThan(10);
+ const sum = (a: number[]) => a.reduce((s, v) => s + v, 0);
+ expect(sum(sharp.line)).toBeGreaterThan(0);
+ expect(
+ Math.abs(sum(blurred.line) - sum(sharp.line)) / sum(sharp.line),
+ ).toBeLessThan(0.1);
+ });
+
+ it("renders moving 3D text the same after a seek as in order", async () => {
+ // The seek's history pass records layers placed in 3D by z alone.
+ const inOrder = scene(word(), true);
+ for (const f of [27, 28, 29]) await inOrder.renderFrame({ frame: f });
+ const sequential = (await row(inOrder, 30, C)).png;
+ const seeked = (await row(scene(word(), true), 30, C)).png;
+ expect(seeked).toEqual(sequential);
+ });
+});
diff --git a/packages/framefields/src/forge-render.test.ts b/packages/framefields/src/forge-render.test.ts
deleted file mode 100644
index 960c01f4..00000000
--- a/packages/framefields/src/forge-render.test.ts
+++ /dev/null
@@ -1,175 +0,0 @@
-/**
- * Characters built with `framefields/forge` render and pose through the
- * compositor like any glTF: a Mixamo-named humanoid (drawn as its bone
- * gizmo) answers `pose`, `aim` and `retargetPose` with the `mixamo` preset.
- */
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import {
- boneGizmo,
- GltfDocument,
- humanoidSkeleton,
- limb,
- Skeleton,
- sculpt,
-} from "./forge/index.js";
-import {
- Composition,
- Layer,
- type LayoutNode,
- type PoseSource,
- retargetPose,
-} from "./index.js";
-import { decodePngPixels } from "./test-utils/pixels.js";
-
-const SIZE = 400;
-const C = SIZE / 2;
-const FEET = C + 150;
-
-let dir = "";
-let file = "";
-let arm = "";
-
-beforeAll(async () => {
- dir = await fs.mkdtemp(path.join(os.tmpdir(), "framefields-forge-"));
- file = path.join(dir, "humanoid.glb");
- const skeleton = humanoidSkeleton({ height: 300 });
- const doc = new GltfDocument();
- const rig = doc.addSkeleton(skeleton);
- const white = doc.addMaterial({ color: "#ffffff", unlit: true });
- const bones = doc.addMesh({
- name: "Bones",
- primitives: [{ ...boneGizmo(skeleton, { width: 0.25 }), material: white }],
- });
- doc.addNode({ name: "Gizmo", mesh: bones, skin: rig.skin });
- await fs.writeFile(file, doc.toGlb());
-
- // A sculpted arm standing up from y = 0: elbow at 120, wrist at 220.
- const armRig = new Skeleton()
- .add("Arm", { at: [0, 0, 0] })
- .add("ForeArm", { at: [0, 120, 0], parent: "Arm" })
- .add("Hand", { at: [0, 220, 0], parent: "ForeArm" });
- const armDoc = new GltfDocument();
- const armSkin = armDoc.addSkeleton(armRig);
- const flat = armDoc.addMaterial({ color: "#ffffff", unlit: true });
- const body = sculpt({
- skeleton: armRig,
- parts: [
- limb(armRig, "Arm", { radii: [22, 17], material: flat }),
- limb(armRig, "ForeArm", { radii: [17, 13], blend: 14, material: flat }),
- ],
- cell: 2,
- triangles: 6000,
- });
- armDoc.addNode({
- mesh: armDoc.addMesh({ primitives: body.primitives }),
- skin: armSkin.skin,
- });
- arm = path.join(dir, "arm.glb");
- await fs.writeFile(arm, armDoc.toGlb());
-});
-afterAll(async () => {
- await fs.rm(dir, { recursive: true, force: true });
-});
-
-async function render(options: Record<string, unknown>, model = file) {
- const comp = new Composition({
- width: SIZE,
- height: SIZE,
- fps: 30,
- durationFrames: 30,
- backgroundColor: "#000000",
- });
- comp.add([
- Layer.camera({
- x: C,
- y: C,
- z: -C / Math.tan((25 * Math.PI) / 180),
- targetX: C,
- targetY: C,
- targetZ: 0,
- }),
- Layer.glb(model, {
- x: C,
- y: FEET,
- z: 0,
- rotateX: 180,
- ...options,
- }) as LayoutNode,
- ]);
- const { pixels } = await decodePngPixels(
- await comp.renderFrame({ frame: 0 }),
- );
- /** Lit pixels in a screen box. */
- return (x0: number, y0: number, x1: number, y1: number) => {
- let n = 0;
- for (let y = y0; y < y1; y++)
- for (let x = x0; x < x1; x++)
- if ((pixels[(y * SIZE + x) * 4] ?? 0) > 128) n++;
- return n;
- };
-}
-
-// The character's left arm hangs to screen right (it faces the camera).
-// At rest the hand sits below the shoulder; raised, above it.
-const above = [C + 60, 15, C + 130, 95] as const;
-const below = [C + 60, 125, C + 130, 205] as const;
-
-describe("forge characters", () => {
- it("stands in its A-pose rest", async () => {
- const lit = await render({});
- expect(lit(...below)).toBeGreaterThan(80);
- expect(lit(...above)).toBe(0);
- // Both arms: the right hangs to screen left.
- expect(lit(C - 130, 125, C - 60, 205)).toBeGreaterThan(80);
- });
-
- it("raises the arm by joint pose", async () => {
- const lit = await render({ pose: { LeftArm: { rotateZ: 90 } } });
- expect(lit(...above)).toBeGreaterThan(80);
- expect(lit(...below)).toBe(0);
- });
-
- it("follows a retargeted performer through the mixamo preset", async () => {
- // A performer (scene coordinates, y down) with the left arm straight up-and-out.
- const at: Record<string, [number, number]> = {
- leftShoulder: [C + 30, 110],
- leftElbow: [C + 70, 70],
- leftWrist: [C + 110, 30],
- };
- const source: PoseSource = {
- point: (name) => {
- const p = at[name];
- return p
- ? { x: p[0], y: p[1], visibility: 1 }
- : { x: 0, y: 0, visibility: 0 };
- },
- };
- const lit = await render({
- aim: retargetPose(source, {
- rig: "mixamo",
- bones: ["leftUpperArm", "leftLowerArm"],
- }),
- });
- expect(lit(...above)).toBeGreaterThan(80);
- expect(lit(...below)).toBe(0);
- });
-
- it("bends a sculpted, auto-skinned elbow without a gap", async () => {
- // Feet of the arm at FEET; the elbow 120 px up the screen.
- const straight = await render({}, arm);
- const bent = await render({ pose: { ForeArm: { rotateZ: 90 } } }, arm);
- const elbowY = FEET - 120;
- // Straight: the forearm stands above the elbow.
- expect(straight(C - 5, elbowY - 90, C + 5, elbowY - 60)).toBeGreaterThan(
- 200,
- );
- // Bent: the forearm points to the screen left of the elbow instead…
- expect(bent(C - 5, elbowY - 90, C + 5, elbowY - 60)).toBe(0);
- expect(bent(C - 90, elbowY - 5, C - 60, elbowY + 5)).toBeGreaterThan(200);
- // …and the elbow's inside corner stays filled: no crack between the bones.
- expect(bent(C - 22, elbowY - 4, C + 4, elbowY + 4)).toBe(26 * 8);
- });
-});
diff --git a/packages/framefields/src/forge/index.ts b/packages/framefields/src/forge/index.ts
deleted file mode 100644
index eaf3bff3..00000000
--- a/packages/framefields/src/forge/index.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-/**
- * `framefields/forge`: rigged characters and props built in code (skeletons,
- * skinned meshes, named morph targets, PBR materials with Khronos
- * extensions, clips), written as standard GLB files for `Layer.glb`.
- */
-export * from "@framefields/forge";
diff --git a/packages/framefields/src/gltf-scene-render.test.ts b/packages/framefields/src/gltf-scene-render.test.ts
index 62884cb7..c698297e 100644
--- a/packages/framefields/src/gltf-scene-render.test.ts
+++ b/packages/framefields/src/gltf-scene-render.test.ts
@@ -7,7 +7,7 @@ import fs from "node:fs/promises";
import { createRequire } from "node:module";
import os from "node:os";
import path from "node:path";
-import { GlbBuilder } from "@framefields/forge";
+import { GlbBuilder } from "@framefields/gltf-fixtures";
import { Canvas, loadImage } from "skia-canvas";
import { afterAll, beforeAll, describe, expect, it } from "vitest";
import { Composition, Layer } from "./index.js";
diff --git a/packages/framefields/src/map-samplers-render.test.ts b/packages/framefields/src/map-samplers-render.test.ts
index def970ba..9230d37f 100644
--- a/packages/framefields/src/map-samplers-render.test.ts
+++ b/packages/framefields/src/map-samplers-render.test.ts
@@ -8,8 +8,8 @@
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
+import { encodePng, GltfDocument } from "@framefields/gltf-fixtures";
import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { encodePng, GltfDocument } from "./forge/index.js";
import { Composition, Layer, type LayoutNode } from "./index.js";
import { decodePngPixels } from "./test-utils/pixels.js";
diff --git a/packages/framefields/src/skin-eight-render.test.ts b/packages/framefields/src/skin-eight-render.test.ts
index 23017894..54f09b53 100644
--- a/packages/framefields/src/skin-eight-render.test.ts
+++ b/packages/framefields/src/skin-eight-render.test.ts
@@ -7,8 +7,8 @@
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
+import { GltfDocument, Skeleton } from "@framefields/gltf-fixtures";
import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { GltfDocument, Skeleton } from "./forge/index.js";
import { Composition, Layer, type LayoutNode } from "./index.js";
import { decodePngPixels } from "./test-utils/pixels.js";
diff --git a/packages/framefields/tsdown.config.ts b/packages/framefields/tsdown.config.ts
index 80c81daf..cf27d889 100644
--- a/packages/framefields/tsdown.config.ts
+++ b/packages/framefields/tsdown.config.ts
@@ -17,7 +17,6 @@ export default defineConfig({
"src/sam/index.ts",
"src/cloud/index.ts",
"src/storage/index.ts",
- "src/forge/index.ts",
"src/cli.ts",
"src/cli/check-worker.ts",
"src/cli/local-worker.ts",
diff --git a/packages/forge/package.json b/packages/gltf-fixtures/package.json
similarity index 79%
rename from packages/forge/package.json
rename to packages/gltf-fixtures/package.json
index af5e6553..6dd59216 100644
--- a/packages/forge/package.json
+++ b/packages/gltf-fixtures/package.json
@@ -1,8 +1,8 @@
{
- "name": "@framefields/forge",
+ "name": "@framefields/gltf-fixtures",
"version": "2.14.0",
"private": true,
- "description": "Build rigged, skinned glTF characters and props in code: a GLB writer with PBR material extensions, skins, morph targets and clips, and skeleton builders.",
+ "description": "Test fixtures: a GLB writer with PBR material extensions, skins, sparse morph targets and clips, and skeleton builders, for the engine's model import tests.",
"type": "module",
"sideEffects": false,
"license": "Apache-2.0",
diff --git a/packages/forge/src/color.ts b/packages/gltf-fixtures/src/color.ts
similarity index 100%
rename from packages/forge/src/color.ts
rename to packages/gltf-fixtures/src/color.ts
diff --git a/packages/forge/src/document.ts b/packages/gltf-fixtures/src/document.ts
similarity index 99%
rename from packages/forge/src/document.ts
rename to packages/gltf-fixtures/src/document.ts
index c6cb95d7..8f1f56a7 100644
--- a/packages/forge/src/document.ts
+++ b/packages/gltf-fixtures/src/document.ts
@@ -7,11 +7,11 @@
*
* ```ts
* const doc = new GltfDocument();
- * const rig = doc.addSkeleton(humanoidSkeleton({ height: 186, heads: 8 }));
+ * const rig = doc.addSkeleton(new Skeleton().add("Hips", { at: [0, 100, 0] }));
* const skin = doc.addMaterial({ color: "#e8d2b0", roughness: 0.55, sheen: { color: "#ffd9c0" } });
* const body = doc.addMesh({ name: "Body", primitives: [{ positions, normals, joints, weights, indices, material: skin }] });
- * doc.addNode({ name: "Ithrael", mesh: body, skin: rig.skin });
- * fs.writeFileSync("ithrael.glb", doc.toGlb());
+ * doc.addNode({ name: "Body", mesh: body, skin: rig.skin });
+ * fs.writeFileSync("body.glb", doc.toGlb());
* ```
*/
diff --git a/packages/forge/src/glb-builder.ts b/packages/gltf-fixtures/src/glb-builder.ts
similarity index 98%
rename from packages/forge/src/glb-builder.ts
rename to packages/gltf-fixtures/src/glb-builder.ts
index baf0e57c..99aa4d35 100644
--- a/packages/forge/src/glb-builder.ts
+++ b/packages/gltf-fixtures/src/glb-builder.ts
@@ -169,7 +169,7 @@ export class GlbBuilder {
const bin = concat(this.chunks, this.length);
const doc = new TextEncoder().encode(
JSON.stringify({
- asset: { version: "2.0", generator: "framefields forge" },
+ asset: { version: "2.0", generator: "framefields gltf-fixtures" },
...json,
...(bin.byteLength
? {
diff --git a/packages/forge/src/gltf-validator.d.ts b/packages/gltf-fixtures/src/gltf-validator.d.ts
similarity index 100%
rename from packages/forge/src/gltf-validator.d.ts
rename to packages/gltf-fixtures/src/gltf-validator.d.ts
diff --git a/packages/gltf-fixtures/src/index.ts b/packages/gltf-fixtures/src/index.ts
new file mode 100644
index 00000000..987bc466
--- /dev/null
+++ b/packages/gltf-fixtures/src/index.ts
@@ -0,0 +1,53 @@
+/**
+ * Test fixtures: a GLB writer (meshes, PBR materials with Khronos
+ * extensions, textures, skins, sparse morphs, clips) and skeletons, used to
+ * build the models the engine's import tests load. Private; not published.
+ */
+export {
+ type ColorInput,
+ displayRgba,
+ linearRgb,
+ linearRgba,
+} from "./color.js";
+export {
+ type AnimationPath,
+ type AnimationSpec,
+ type ChannelSpec,
+ type DriverSpec,
+ GltfDocument,
+ type MaterialRef,
+ type MeshRef,
+ type MeshSpec,
+ type MorphTargetSpec,
+ type NodeRef,
+ type NodeSpec,
+ type PrimitiveSpec,
+ type SkeletonRefs,
+ type SkinRef,
+ type TextureSpec,
+} from "./document.js";
+export {
+ type AccessorData,
+ type AccessorOptions,
+ type AccessorType,
+ GlbBuilder,
+} from "./glb-builder.js";
+export {
+ type MaterialSpec,
+ materialJson,
+ type TextureRef,
+ type TextureSlot,
+} from "./material.js";
+export { encodePng } from "./png.js";
+export {
+ type Joint,
+ type JointSpec,
+ type MirrorOptions,
+ type Quat,
+ quatConjugate,
+ quatMultiply,
+ quatRotate,
+ Skeleton,
+ type Vec3,
+} from "./skeleton.js";
+export { computeTangents } from "./tangents.js";
diff --git a/packages/forge/src/material.ts b/packages/gltf-fixtures/src/material.ts
similarity index 100%
rename from packages/forge/src/material.ts
rename to packages/gltf-fixtures/src/material.ts
diff --git a/packages/forge/src/png.ts b/packages/gltf-fixtures/src/png.ts
similarity index 100%
rename from packages/forge/src/png.ts
rename to packages/gltf-fixtures/src/png.ts
diff --git a/packages/forge/src/read-png.test-util.ts b/packages/gltf-fixtures/src/read-png.test-util.ts
similarity index 100%
rename from packages/forge/src/read-png.test-util.ts
rename to packages/gltf-fixtures/src/read-png.test-util.ts
diff --git a/packages/forge/src/skeleton.ts b/packages/gltf-fixtures/src/skeleton.ts
similarity index 100%
rename from packages/forge/src/skeleton.ts
rename to packages/gltf-fixtures/src/skeleton.ts
diff --git a/packages/forge/src/tangents.ts b/packages/gltf-fixtures/src/tangents.ts
similarity index 100%
rename from packages/forge/src/tangents.ts
rename to packages/gltf-fixtures/src/tangents.ts
diff --git a/packages/forge/src/forge.test.ts b/packages/gltf-fixtures/src/writer.test.ts
similarity index 88%
rename from packages/forge/src/forge.test.ts
rename to packages/gltf-fixtures/src/writer.test.ts
index 96de213f..6e1464ff 100644
--- a/packages/forge/src/forge.test.ts
+++ b/packages/gltf-fixtures/src/writer.test.ts
@@ -1,19 +1,12 @@
/**
- * Forge output is standard glTF: the Khronos validator finds no errors or
+ * The fixture writer's output is standard glTF: the Khronos validator finds no errors or
* warnings, and the engine's own loader reads back exactly what was written
* (geometry, 32-bit indices, skins, named morph targets, materials, clips).
*/
import { denseMorphDeltas, parseGLB } from "@framefields/webgpu-renderers";
import { validateBytes } from "gltf-validator";
import { describe, expect, it } from "vitest";
-import {
- boneGizmo,
- encodePng,
- GltfDocument,
- humanoidSkeleton,
- linearRgba,
- Skeleton,
-} from "./index.js";
+import { encodePng, GltfDocument, linearRgba, Skeleton } from "./index.js";
import { readPng } from "./read-png.test-util.js";
async function validate(glb: Uint8Array) {
@@ -367,39 +360,6 @@ describe("Skeleton", () => {
expect(s.joint("RightShoulder").parent).toBe("Spine");
});
- it("builds a proportioned Mixamo humanoid", () => {
- const s = humanoidSkeleton({ height: 186, heads: 8 });
- for (const name of [
- "Hips",
- "Spine",
- "Spine2",
- "Neck",
- "Head",
- "LeftArm",
- "LeftForeArm",
- "RightHand",
- "RightHandIndex4",
- "LeftHandThumb4",
- "LeftUpLeg",
- "RightLeg",
- "RightToe_End",
- ])
- expect(s.has(name), name).toBe(true);
- expect(s.joint("HeadTop_End").at[1]).toBeCloseTo(186);
- expect(Math.min(...s.joints.map((j) => j.at[1]))).toBeGreaterThanOrEqual(0);
- // Symmetric, and arm spans scale with the figure.
- expect(s.joint("RightForeArm").at[0]).toBeCloseTo(
- -s.joint("LeftForeArm").at[0],
- );
- expect(s.length("LeftForeArm")).toBeCloseTo(0.186 * 186, 5);
- // A T-pose holds the arms level.
- const t = humanoidSkeleton({ armAngle: 0 });
- expect(t.joint("LeftHand").at[1]).toBeCloseTo(t.joint("LeftArm").at[1]);
- expect(
- humanoidSkeleton({ prefix: "mixamorig:" }).has("mixamorig:LeftArm"),
- ).toBe(true);
- });
-
it("keeps rest orientations: node rotations, inverse bind matrices, mirrored copies", async () => {
// A forearm turned 90° about z at rest: its local x points up.
const turn: [number, number, number, number] = [
@@ -448,20 +408,4 @@ describe("Skeleton", () => {
);
expect(hand.translation?.[0]).toBeCloseTo(8, 6);
});
-
- it("writes a skeleton with its bone gizmo as a valid skinned GLB", async () => {
- const skeleton = humanoidSkeleton();
- const doc = new GltfDocument();
- const rig = doc.addSkeleton(skeleton);
- const bones = doc.addMesh({
- name: "Bones",
- primitives: [boneGizmo(skeleton)],
- });
- doc.addNode({ name: "Gizmo", mesh: bones, skin: rig.skin });
- const glb = doc.toGlb();
- const report = await validate(glb);
- expect(report.issues).toEqual([]);
- const model = parseGLB(glb);
- expect(model.skins![0]!.joints).toHaveLength(skeleton.joints.length);
- });
});
diff --git a/packages/forge/tsconfig.json b/packages/gltf-fixtures/tsconfig.json
similarity index 100%
rename from packages/forge/tsconfig.json
rename to packages/gltf-fixtures/tsconfig.json
diff --git a/packages/forge/tsdown.config.ts b/packages/gltf-fixtures/tsdown.config.ts
similarity index 100%
rename from packages/forge/tsdown.config.ts
rename to packages/gltf-fixtures/tsdown.config.ts
diff --git a/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts b/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts
index da1c7c1a..e4a0e50d 100644
--- a/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts
+++ b/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts
@@ -144,7 +144,14 @@ export type MeshMotionPrev = Pick<
| "instanceBuffer"
| "wind"
| "crowd"
->;
+> & {
+ /**
+ * The mesh's vertices as the GPU deformed them a frame earlier (morph
+ * targets, audio deformation), in the vertex buffer's layout. Absent:
+ * the vertices did not change shape, so this frame's buffer stands in.
+ */
+ vertexBuffer?: GPUBuffer;
+};
/** Format of the velocity target: motion px (rg), linear depth (b), coverage (a). */
export const VELOCITY_FORMAT: GPUTextureFormat = "rgba16float";
@@ -777,6 +784,7 @@ export class Mesh3DPipeline {
pass.setBindGroup(1, now);
pass.setBindGroup(2, before);
pass.setBindGroup(3, this.textureGroup(texture, sampler, undefined));
+ pass.setVertexBuffer(4, prev?.vertexBuffer ?? meshBuffers.vertexBuffer);
this.issue(
pass,
meshBuffers,
@@ -807,7 +815,16 @@ export class Mesh3DPipeline {
vertex: {
module: this.velocityModule,
entryPoint: "vs_velocity",
- buffers: this.vertexBuffers,
+ buffers: [
+ ...this.vertexBuffers,
+ // The previous frame's deformed positions (or this frame's).
+ {
+ arrayStride: 64,
+ attributes: [
+ { shaderLocation: 12, offset: 0, format: "float32x3" },
+ ],
+ },
+ ],
},
fragment: {
module: this.velocityModule,
diff --git a/packages/webgpu-renderers/src/renderer3d/morph-pipeline.ts b/packages/webgpu-renderers/src/renderer3d/morph-pipeline.ts
index aad5b352..1fd36248 100644
--- a/packages/webgpu-renderers/src/renderer3d/morph-pipeline.ts
+++ b/packages/webgpu-renderers/src/renderer3d/morph-pipeline.ts
@@ -140,7 +140,11 @@ export class MorphPipeline {
output = this.device.createBuffer({
label: "MeshMorphOutput",
size,
- usage: GPUBufferUsage.STORAGE | GPUBufferUsage.VERTEX,
+ // COPY_SRC: motion blur keeps a copy as the next frame's past.
+ usage:
+ GPUBufferUsage.STORAGE |
+ GPUBufferUsage.VERTEX |
+ GPUBufferUsage.COPY_SRC,
});
this.outputs[this.outputIndex] = output;
}
diff --git a/packages/webgpu-renderers/src/renderer3d/renderer3d.ts b/packages/webgpu-renderers/src/renderer3d/renderer3d.ts
index dab76950..0cab3663 100644
--- a/packages/webgpu-renderers/src/renderer3d/renderer3d.ts
+++ b/packages/webgpu-renderers/src/renderer3d/renderer3d.ts
@@ -171,6 +171,40 @@ export interface DrawQuad3DOpts extends SurfaceParams {
*/
const TEXT_STACK_PULL = 5e-4;
+/** A text layer's px [0, w] x [0, h] onto its plane's unit quad, in world space. */
+function slugLayerToWorld(quad: Mat4, width: number, height: number): Mat4 {
+ return Matrix4Math.multiply(
+ quad,
+ Matrix4Math.multiply(
+ Matrix4Math.translate(-0.5, -0.5, 0),
+ Matrix4Math.scale(1 / width, 1 / height, 1),
+ ),
+ );
+}
+
+/** A glyph batch's paragraph space to world: its 2D affine, then the plane. */
+function slugBatchMatrix(layerToWorld: Mat4, batch: SlugGlyphBatch): Mat4 {
+ const [a, b, c, d, e, f] = batch.transform;
+ return Matrix4Math.multiply(layerToWorld, [
+ a,
+ b,
+ 0,
+ 0,
+ c,
+ d,
+ 0,
+ 0,
+ 0,
+ 0,
+ 1,
+ 0,
+ e,
+ f,
+ 0,
+ 1,
+ ]);
+}
+
export interface DrawMesh3DOpts extends SurfaceParams {
/** Refractive index for glass materials (default 1.5). */
ior?: number;
@@ -1646,36 +1680,10 @@ export class Renderer3D {
if (!(width > 0 && height > 0)) return;
const quad = this.quadModelMatrix(opts);
const normalMatrix = opts.normalMatrix ?? Light3D.computeNormalMatrix(quad);
- // Layer px [0, w] x [0, h] onto the unit quad.
- const layerToWorld = Matrix4Math.multiply(
- quad,
- Matrix4Math.multiply(
- Matrix4Math.translate(-0.5, -0.5, 0),
- Matrix4Math.scale(1 / width, 1 / height, 1),
- ),
- );
+ const layerToWorld = slugLayerToWorld(quad, width, height);
for (let i = 0; i < batches.length; i++) {
const batch = batches[i];
- const [a, b, c, d, e, f] = batch.transform;
- const paragraphToLayer: Mat4 = [
- a,
- b,
- 0,
- 0,
- c,
- d,
- 0,
- 0,
- 0,
- 0,
- 1,
- 0,
- e,
- f,
- 0,
- 1,
- ];
this.slug3dPipeline.draw(
pass,
cameraBindGroup,
@@ -1684,7 +1692,7 @@ export class Renderer3D {
batch.instances,
batch.instanceCount,
{
- modelMatrix: Matrix4Math.multiply(layerToWorld, paragraphToLayer),
+ modelMatrix: slugBatchMatrix(layerToWorld, batch),
normalMatrix,
opacity: batch.opacity * (opts.opacity ?? 1),
slant: batch.slant,
@@ -2360,6 +2368,55 @@ export class Renderer3D {
pass.draw(4);
}
+ /**
+ * Draws a text layer's glyphs' motion since `prev` (its plane matrix and
+ * glyph batches a frame earlier) into the velocity pass. A batch whose
+ * glyphs changed (another font or count) moves with its plane alone.
+ */
+ drawSlugVelocity(
+ pass: GPURenderPassEncoder,
+ cameraBindGroup: GPUBindGroup,
+ batches: SlugGlyphBatch[],
+ opts: DrawQuad3DOpts,
+ stackBase: number,
+ prev: { modelMatrix: Mat4; batches: SlugGlyphBatch[] } | undefined,
+ ): void {
+ const { width, height } = opts;
+ if (!(width > 0 && height > 0)) return;
+ const quad = this.quadModelMatrix(opts);
+ const layerToWorld = slugLayerToWorld(quad, width, height);
+ const prevLayerToWorld = slugLayerToWorld(
+ prev?.modelMatrix ?? quad,
+ width,
+ height,
+ );
+ batches.forEach((batch, i) => {
+ const before = prev?.batches[i];
+ const same =
+ before?.font === batch.font &&
+ before.instanceCount === batch.instanceCount;
+ this.slug3dPipeline.drawVelocity(
+ pass,
+ cameraBindGroup,
+ this.mesh3dPipeline.velocityCameraLayout,
+ batch.font,
+ batch.instances,
+ batch.instanceCount,
+ {
+ modelMatrix: slugBatchMatrix(layerToWorld, batch),
+ prevModelMatrix: slugBatchMatrix(
+ prevLayerToWorld,
+ same ? before : batch,
+ ),
+ prevInstances: same ? before.instances : undefined,
+ opacity: batch.opacity * (opts.opacity ?? 1),
+ slant: batch.slant,
+ depthPull: TEXT_STACK_PULL * (stackBase + i + 1),
+ },
+ );
+ });
+ }
+
/** Draws the environment floor's motion (camera motion only) into the velocity pass. */
drawFloorVelocity(
pass: GPURenderPassEncoder,
diff --git a/packages/webgpu-renderers/src/renderer3d/slug3d-pipeline.ts b/packages/webgpu-renderers/src/renderer3d/slug3d-pipeline.ts
index aaa5f78e..fed0d5d2 100644
--- a/packages/webgpu-renderers/src/renderer3d/slug3d-pipeline.ts
+++ b/packages/webgpu-renderers/src/renderer3d/slug3d-pipeline.ts
@@ -1,8 +1,10 @@
import type { Mat4 } from "../math3d/index.js";
import { BufferPool } from "../renderer2d/buffer-pool.js";
+import { slugVelocityWgsl } from "../shaders/mesh-velocity.js";
import { slug3dWgsl } from "../shaders/slug3d.js";
import type { SlugFont } from "../slug/slug-loader.js";
import { fullCoverageView, matteLayoutEntry } from "./matte3d.js";
+import { VELOCITY_DEPTH_FORMAT, VELOCITY_FORMAT } from "./mesh3d-pipeline.js";
import {
BloomPipelineVariants,
createBasePipelines,
@@ -30,6 +32,27 @@ export interface Slug3DUniformData extends MaterialUniformData {
const INSTANCE_FLOATS = 24;
+/** A text batch's motion for the velocity pass: this and the previous frame. */
+export interface SlugMotionData {
+ modelMatrix: Mat4;
+ prevModelMatrix: Mat4;
+ /** The previous frame's glyph records (same glyphs, same order); absent = unchanged. */
+ prevInstances?: Float32Array;
+ opacity: number;
+ slant: number;
+ depthPull: number;
+}
+
+/** The glyph record attributes, at shader locations 0..5. */
+const INSTANCE_ATTRIBUTES: GPUVertexAttribute[] = [
+ { shaderLocation: 0, offset: 0, format: "float32x4" }, // aScaleBias
+ { shaderLocation: 1, offset: 16, format: "float32x4" }, // aGlyphBandScale
+ { shaderLocation: 2, offset: 32, format: "float32x4" }, // aBandMaxTexCoords
+ { shaderLocation: 3, offset: 48, format: "float32x4" }, // aAnim
+ { shaderLocation: 4, offset: 64, format: "float32x4" }, // aColor
+ { shaderLocation: 5, offset: 80, format: "float32x4" }, // aExtraParams
+];
+
/** Slug glyphs in the 3D pass: depth-tested, lit and resolution independent. */
export class Slug3DPipeline {
private device: GPUDevice;
@@ -41,6 +64,11 @@ export class Slug3DPipeline {
private modelPool: BufferPool;
private instancePool: BufferPool;
private fontBindGroups = new WeakMap<GPUTexture, GPUBindGroup>();
+ private motionPool: BufferPool;
+ private velocity?: {
+ pipeline: GPURenderPipeline;
+ layout: GPUBindGroupLayout;
+ };
// Transform, draw/material params and the shared surface block.
private modelData = new Float32Array(40 + SURFACE_PARAMS_FLOATS);
@@ -62,6 +90,10 @@ export class Slug3DPipeline {
65536,
GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
);
+ this.motionPool = new BufferPool(
+ 36 * 4,
+ GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+ );
const module = device.createShaderModule({
label: "slug3d.wgsl",
@@ -112,14 +144,7 @@ export class Slug3DPipeline {
{
arrayStride: INSTANCE_FLOATS * 4,
stepMode: "instance",
- attributes: [
- { shaderLocation: 0, offset: 0, format: "float32x4" }, // aScaleBias
- { shaderLocation: 1, offset: 16, format: "float32x4" }, // aGlyphBandScale
- { shaderLocation: 2, offset: 32, format: "float32x4" }, // aBandMaxTexCoords
- { shaderLocation: 3, offset: 48, format: "float32x4" }, // aAnim
- { shaderLocation: 4, offset: 64, format: "float32x4" }, // aColor
- { shaderLocation: 5, offset: 80, format: "float32x4" }, // aExtraParams
- ],
+ attributes: INSTANCE_ATTRIBUTES,
},
],
};
@@ -154,6 +179,119 @@ export class Slug3DPipeline {
resetPools(): void {
this.modelPool.reset();
this.instancePool.reset();
+ this.motionPool.reset();
+ }
+
+ /**
+ * Draws a text batch's screen motion into a velocity pass: its glyphs
+ * placed with this and the previous frame's plane and glyph animation,
+ * written where the outline covers the pixel.
+ */
+ drawVelocity(
+ pass: GPURenderPassEncoder,
+ velocityCameraBindGroup: GPUBindGroup,
+ velocityCameraLayout: GPUBindGroupLayout,
+ font: SlugFont,
+ instances: Float32Array,
+ instanceCount: number,
+ data: SlugMotionData,
+ ): void {
+ if (instanceCount === 0 || !font.curvesTex || !font.bandsTex) return;
+ const velocity = this.velocityPipeline(velocityCameraLayout);
+ const motion = new Float32Array(36);
+ motion.set(data.modelMatrix, 0);
+ motion.set(data.prevModelMatrix, 16);
+ motion[32] = data.opacity;
+ motion[33] = data.slant;
+ motion[35] = data.depthPull;
+ const group = this.device.createBindGroup({
+ layout: velocity.layout,
+ entries: [
+ {
+ binding: 0,
+ resource: { buffer: this.motionPool.getBuffer(this.device, motion) },
+ },
+ ],
+ });
+ const floats = instanceCount * INSTANCE_FLOATS;
+ const now = this.instancePool.getBuffer(
+ this.device,
+ instances.subarray(0, floats),
+ );
+ const before = data.prevInstances
+ ? this.instancePool.getBuffer(
+ this.device,
+ data.prevInstances.subarray(0, floats),
+ )
+ : now;
+ pass.setPipeline(velocity.pipeline);
+ pass.setBindGroup(0, velocityCameraBindGroup);
+ pass.setBindGroup(1, group);
+ pass.setBindGroup(2, this.fontBindGroup(font.curvesTex, font.bandsTex));
+ pass.setVertexBuffer(0, now);
+ pass.setVertexBuffer(1, before);
+ pass.draw(6, instanceCount);
+ }
+
+ private velocityPipeline(cameraLayout: GPUBindGroupLayout): {
+ pipeline: GPURenderPipeline;
+ layout: GPUBindGroupLayout;
+ } {
+ if (this.velocity) return this.velocity;
+ const module = this.device.createShaderModule({
+ label: "slug-velocity.wgsl",
+ code: slugVelocityWgsl,
+ });
+ const layout = this.device.createBindGroupLayout({
+ label: "Slug3DVelocityLayout",
+ entries: [
+ {
+ binding: 0,
+ visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+ buffer: { type: "uniform" },
+ },
+ ],
+ });
+ const pipeline = this.device.createRenderPipeline({
+ label: "Slug3DVelocity",
+ layout: this.device.createPipelineLayout({
+ bindGroupLayouts: [cameraLayout, layout, this.fontLayout],
+ }),
+ vertex: {
+ module,
+ entryPoint: "vs_slug_velocity",
+ buffers: [
+ {
+ arrayStride: INSTANCE_FLOATS * 4,
+ stepMode: "instance",
+ attributes: INSTANCE_ATTRIBUTES.filter(
+ (a) => a.shaderLocation !== 5,
+ ),
+ },
+ {
+ arrayStride: INSTANCE_FLOATS * 4,
+ stepMode: "instance",
+ attributes: [
+ { shaderLocation: 6, offset: 0, format: "float32x4" },
+ { shaderLocation: 7, offset: 48, format: "float32x4" },
+ ],
+ },
+ ],
+ },
+ fragment: {
+ module,
+ entryPoint: "fs_slug_velocity",
+ targets: [{ format: VELOCITY_FORMAT }],
+ },
+ depthStencil: {
+ format: VELOCITY_DEPTH_FORMAT,
+ depthWriteEnabled: true,
+ depthCompare: "less-equal",
+ },
+ primitive: { topology: "triangle-list", cullMode: "none" },
+ });
+ this.velocity = { pipeline, layout };
+ return this.velocity;
}
draw(
@@ -228,5 +366,6 @@ export class Slug3DPipeline {
destroy(): void {
this.modelPool.destroy();
this.instancePool.destroy();
+ this.motionPool.destroy();
}
}
diff --git a/packages/webgpu-renderers/src/shaders/mesh-velocity.ts b/packages/webgpu-renderers/src/shaders/mesh-velocity.ts
index eaaf4bfd..73731d9f 100644
--- a/packages/webgpu-renderers/src/shaders/mesh-velocity.ts
+++ b/packages/webgpu-renderers/src/shaders/mesh-velocity.ts
@@ -1,7 +1,7 @@
/**
* 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
+ * with this frame's bindings and the previous frame's (deformed position,
+ * 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).
@@ -11,6 +11,7 @@ import {
meshDeformWgsl,
meshStructsWgsl,
} from "./mesh3d.js";
+import { slugCoverageWgsl } from "./slug.js";
/** The velocity pass's camera: this and the previous frame's view-projection. */
const velocityCameraWgsl = `
@@ -58,9 +59,17 @@ struct VelocityOut {
};
@vertex
-fn vs_velocity(in: VertexInput, @builtin(instance_index) instanceIndex: u32) -> VelocityOut {
+fn vs_velocity(
+ in: VertexInput,
+ @location(12) prevPosition: vec3<f32>,
+ @builtin(instance_index) instanceIndex: u32,
+) -> VelocityOut {
let now = deform(in, instanceIndex);
- let before = deformPrev(in, instanceIndex);
+ // Morphs and audio deformation ran on the GPU before this pass: the
+ // previous frame starts from its own deformed position.
+ var inPrev = in;
+ inPrev.position = prevPosition;
+ let before = deformPrev(inPrev, instanceIndex);
let world = model.modelMatrix * vec4<f32>(now.localPos, 1.0);
let worldPrev = modelPrev.modelMatrix * vec4<f32>(before.localPos, 1.0);
var out: VelocityOut;
@@ -195,3 +204,100 @@ fn fs_floor_velocity(@builtin(position) pos: vec4<f32>) -> FloorVelocityOut {
return out;
}
`;
+
+/**
+ * Velocity of a text layer's Slug glyphs on their 3D plane: each glyph quad
+ * is placed with this and the previous frame's plane matrix and per-glyph
+ * animation (rotation, scale, offset), and coverage is solved from the
+ * outline as the color pass does, so only the glyphs' own pixels move.
+ */
+export const slugVelocityWgsl = `
+${velocityCameraWgsl}
+
+struct SlugMotion {
+ model : mat4x4<f32>, // paragraph px -> world, this frame
+ modelPrev : mat4x4<f32>, // and the previous frame
+ params : vec4<f32>, // x = opacity, y = slant, w = pull toward the eye
+};
+
+@group(0) @binding(0) var<uniform> vcam : VelocityCamera;
+@group(1) @binding(0) var<uniform> motion : SlugMotion;
+@group(2) @binding(0) var curvesTex : texture_2d<f32>;
+@group(2) @binding(1) var bandsTex : texture_2d<u32>;
+
+${slugCoverageWgsl}
+
+struct SlugVelocityOut {
+ @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) @interpolate(flat) glyphScale : vec2<f32>,
+ @location(5) @interpolate(flat) bandScale : vec2<f32>,
+ @location(6) @interpolate(flat) bandMax : vec2<u32>,
+ @location(7) @interpolate(flat) bandsTexCoords : vec2<u32>,
+ @location(8) alpha : f32,
+};
+
+var<private> corners : array<vec2<f32>, 6> = array<vec2<f32>, 6>(
+ vec2<f32>(-1.0, -1.0),
+ vec2<f32>(1.0, 1.0),
+ vec2<f32>(-1.0, 1.0),
+ vec2<f32>(-1.0, -1.0),
+ vec2<f32>(1.0, -1.0),
+ vec2<f32>(1.0, 1.0)
+);
+
+/** A glyph quad corner in world space, slid toward the eye as the color pass slides it. */
+fn glyphCorner(m: mat4x4<f32>, corner: vec2<f32>, scaleBias: vec4<f32>, anim: vec4<f32>) -> vec4<f32> {
+ let rot = mat2x2<f32>(cos(anim.x), sin(anim.x), -sin(anim.x), cos(anim.x));
+ let shear = mat2x2<f32>(1.0, 0.0, -motion.params.y, 1.0);
+ let p = scaleBias.zw + anim.zw + rot * shear * (corner * scaleBias.xy * anim.y);
+ let w = (m * vec4<f32>(p, 0.0, 1.0)).xyz;
+ return vec4<f32>(w + (vcam.eye.xyz - w) * motion.params.w, 1.0);
+}
+
+@vertex
+fn vs_slug_velocity(
+ @builtin(vertex_index) vertexIndex : u32,
+ @location(0) aScaleBias : vec4<f32>,
+ @location(1) aGlyphBandScale : vec4<f32>,
+ @location(2) aBandMaxTexCoords : vec4<f32>,
+ @location(3) aAnim : vec4<f32>,
+ @location(4) aColor : vec4<f32>,
+ @location(6) aPrevScaleBias : vec4<f32>,
+ @location(7) aPrevAnim : vec4<f32>,
+) -> SlugVelocityOut {
+ let corner = corners[vertexIndex];
+ let world = glyphCorner(motion.model, corner, aScaleBias, aAnim);
+ let worldPrev = glyphCorner(motion.modelPrev, corner, aPrevScaleBias, aPrevAnim);
+ var out : SlugVelocityOut;
+ out.pos = vcam.viewProj * world;
+ out.curr = out.pos;
+ out.prev = vcam.prevViewProj * worldPrev;
+ out.uv = vec2<f32>(corner.x * 0.5 + 0.5, 0.5 - corner.y * 0.5);
+ out.depth = dot(world.xyz - vcam.eye.xyz, vcam.dir.xyz);
+ out.glyphScale = aGlyphBandScale.xy;
+ out.bandScale = aGlyphBandScale.zw;
+ out.bandMax = vec2<u32>(aBandMaxTexCoords.xy);
+ out.bandsTexCoords = vec2<u32>(aBandMaxTexCoords.zw);
+ out.alpha = aColor.a * motion.params.x;
+ return out;
+}
+
+@fragment
+fn fs_slug_velocity(in : SlugVelocityOut) -> @location(0) vec4<f32> {
+ let fw = max(abs(dpdx(in.uv)) + abs(dpdy(in.uv)), vec2<f32>(0.000001));
+ let glyph = SlugGlyph(in.glyphScale, in.bandScale, in.bandMax, in.bandsTexCoords);
+ let coverage = sampleSlugCoverage(in.uv, glyph, max(vec2<f32>(1.0) / fw, vec2<f32>(1.0)));
+ // Inside the outline only: the pixels around a glyph keep what is behind.
+ if (coverage < 0.5 || in.alpha < 0.02) {
+ discard;
+ }
+ let ndc = in.curr.xy / in.curr.w;
+ let ndcPrev = in.prev.xy / max(in.prev.w, 1e-6);
+ let shift = (ndc - ndcPrev) * 0.5 * vcam.viewport.xy * vec2<f32>(1.0, -1.0);
+ return vec4<f32>(shift, in.depth, 1.0);
+}
+`;
diff --git a/plugins/framefields/skills/framefields-compose/SKILL.md b/plugins/framefields/skills/framefields-compose/SKILL.md
index 34e68cd8..39f397cb 100644
--- a/plugins/framefields/skills/framefields-compose/SKILL.md
+++ b/plugins/framefields/skills/framefields-compose/SKILL.md
@@ -406,7 +406,7 @@ 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.
+`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, morph targets, audio-deformed meshes, crowds, swarms, wind and fractured pieces. 3D layer planes (cards, video screens) move by their transform, and text in the 3D scene streaks glyph by glyph. 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, crowds
@@ -431,7 +431,7 @@ const extras = Layer3D.scatter({
});
```
-**Joint drivers** (`drive`): `{ joint, from, rotate: { x?, y?, z? } }` turns a joint by a share of another joint's turn from its rest, per local axis, after look-ats and before IK: lids following eyes, twist bones sharing a forearm's roll, correctives. Model files can carry their own (forge's `GltfDocument.addDriver`, stored in the scene's `extras.framefields.drivers`); a layer's `drive` adds to them.
+**Joint drivers** (`drive`): `{ joint, from, rotate: { x?, y?, z? } }` turns a joint by a share of another joint's turn from its rest, per local axis, after look-ats and before IK: lids following eyes, twist bones sharing a forearm's roll, correctives. Model files can carry their own (in the scene's `extras.framefields.drivers`); a layer's `drive` adds to them.
**Posing joints directly** (`pose`, by joint name; namespace prefixes and case are ignored, so `"LeftArm"` finds `"mixamorig:LeftArm"`): local Euler degrees `rotateX/Y/Z` (Z, then Y, then X, like layers) and offsets `x/y/z`, on top of the clips (`mode: "additive"`, default) or of the rest pose (`"rest"`: clips stop moving that joint), with a `weight`. Every value is a track: a number, `[[frame, v]]` keys, `(frame) => v`, or a signal (audio, physics, vision, `Signal.*`), so a head can sway on a sine or flinch at a physics hit:
@@ -461,48 +461,12 @@ Order of evaluation: clips, `pose`, `aim`, `lookAt`, `ik` (so IK can still plant
Rules: a crowd mesh keeps its own `rotateX` / `scale` under each instance (y-up glTF: `rotateX: 180`). Spring bones follow the clip's motion and the model's current orientation, not the layer's keyframed travel. Per-instance `clip`, `animOffset`, `animSpeed` in `transforms` / `instanceAt` override the crowd's seeded choices.
-**Building characters in code (`framefields/forge`)**: write rigged GLB files from TypeScript, then load them with `Layer.glb`. `humanoidSkeleton({ height, heads, shoulderWidth, hipWidth, armAngle, fingers, toes, prefix })` places Mixamo-named joints (feet on y = 0, facing +z, left at +x, A-pose by default) so `pose`, `aim` and `retarget({ rig: "mixamo" })` work unchanged; `new Skeleton().add(name, { at, parent }).chain(base, points).mirror()` builds any other rig. `GltfDocument` writes meshes (32-bit indices past 65,535 vertices, named morph targets in `extras.targetNames`), PBR materials with Khronos extensions (`clearcoat`, `sheen`, `specular`, `ior`, `transmission`, `volume`, `iridescence`, `anisotropy`, `emissiveStrength`, `unlit`, alpha `mask`) plus `subsurface` for skin, textures, skins and clips, and checks every input where it is given. Colors are display sRGB; the writer stores glTF's linear factors. `boneGizmo(skeleton)` draws the rig as octahedral bones for checking poses before there is a body.
-
-```ts
-import { boneGizmo, GltfDocument, humanoidSkeleton } from "framefields/forge";
-const skeleton = humanoidSkeleton({ height: 186, heads: 8 });
-const doc = new GltfDocument();
-const rig = doc.addSkeleton(skeleton);
-const gold = doc.addMaterial({ color: "#d99a2b", roughness: 0.35, clearcoat: { factor: 1, roughness: 0.05 } });
-doc.addNode({ mesh: doc.addMesh({ primitives: [{ ...boneGizmo(skeleton), material: gold }] }), skin: rig.skin });
-fs.writeFileSync("rig.glb", doc.toGlb());
-Layer.glb("rig.glb", { rotateX: 180, pose: { LeftArm: { rotateZ: 90 } } });
-```
-
-**Morph targets by name** (`morphs` on `Layer.glb`): set any of the file's morph targets by name, matched case-insensitively, each a number, keys or a signal; unnamed targets keep the clip's weights. The writer stores targets that move few vertices sparse, and so does the engine. `subdivide(primitive, { levels, weld })` (Loop) smooths a primitive and carries blend shapes and skin weights exactly. Texture slots take `transform: { scale, offset, rotation }` (KHR_texture_transform), the writer adds tangents to normal-mapped primitives that bring none, and each map samples with its own glTF sampler. `encodePng(rgba, width, height)` writes textures made in code.
+**Morph targets by name** (`morphs` on `Layer.glb`): set any of the file's morph targets by name, matched case-insensitively, each a number, keys or a signal; unnamed targets keep the clip's weights. Sparse morph accessors stay sparse on the GPU, so files with hundreds of corrective shapes fit. Skins take up to eight influences per vertex (`JOINTS_1` / `WEIGHTS_1`). Texture slots honor `KHR_texture_transform`, and each map samples with its own glTF sampler.
```ts
Layer.glb("head.glb", { morphs: { jawOpen: [[0, 0], [12, 0.6]], mouthSmileLeft: 0.8, eyeBlinkLeft: blink } });
```
-**Sculpting skinned bodies (`sculpt`)**: a character's body is an ordered list of parts, each an SDF shape (`sphere`, `ellipsoid`, `box`, `cylinder`, `capsule`, `roundCone`, `tube` through points, `torus`, `lathe` profile) with `at`, `rotation`, `op` (`union` / `subtract` / `intersect`), `blend` (smooth join radius), `twist`, `bend`, `displace` (noise detail), `material`, `color`, and the `joint` (or joints) that moves it (default: the nearest bone). `sculpt({ parts, skeleton, cell, triangles })` meshes it closed and manifold at hero resolution, simplifies to the triangle budget, cuts material borders on smooth curves, takes normals and blended colors from the field, and skins every vertex from the parts that reach it (smooth joins share weights, `rigid: true` parts move with one joint), returning one primitive per material plus a report (`openEdges` is 0 for a closed mesh). `limb(skeleton, "LeftForeArm", { radii: [4, 3], blend: 3 })` puts a round cone along a bone; `mirrorParts(leftParts)` adds the right side.
-
-```ts
-import { GltfDocument, humanoidSkeleton, limb, mirrorParts, sculpt } from "framefields/forge";
-const skeleton = humanoidSkeleton({ height: 180 });
-const doc = new GltfDocument();
-const rig = doc.addSkeleton(skeleton);
-const cloth = doc.addMaterial({ color: "#3e5a3c", roughness: 0.8, sheen: { color: "#9fb89a" } });
-const skin = doc.addMaterial({ color: "#d9b99b", roughness: 0.55 });
-const body = sculpt({
- skeleton, cell: 0.6, triangles: 80000,
- parts: [
- { shape: "ellipsoid", at: [0, 126, 0], radii: [17.5, 14, 10.5], joint: ["Spine1", "Spine2"], material: cloth },
- { shape: "ellipsoid", at: [0, 167, 0.5], radii: [8.6, 11, 10], joint: "Head", blend: 3, material: skin },
- ...mirrorParts([
- limb(skeleton, "LeftArm", { radii: [5.4, 4], blend: 3, material: cloth }),
- limb(skeleton, "LeftForeArm", { radii: [4, 2.8], blend: 2.5, material: skin }),
- ]),
- ],
-});
-doc.addNode({ mesh: doc.addMesh({ name: "Body", primitives: body.primitives }), skin: rig.skin });
-```
-
### Procedural worlds: terrain, sculptures, scatter
Terrain, SDF sculptures and scatters are ordinary model nodes: they take materials, lights, shadows, SSR/GI, physics, keyframes and a `texture` that can be any layer (an image path, `Layer.video`, a layout tree) drawn fresh each frame.
@@ -600,7 +564,7 @@ Layer3D.cylinder({ ..., height: 400, color: "#111", emissive: "#4da3ff", emissiv
- **Rect Area Lights (`Layer.rectLight` / `Light.rect`):** studio softbox / LED panel lights with `width`, `height`, `twoSided`, `rotation`, `x/y/z`, `targetX/Y/Z`, `intensity`, `radius`, `decay`, and `castShadow`. Uses solid-angle diffuse irradiance and representative-point GGX specular highlights that stretch across rough and glossy surfaces. Numeric light props accept `Signal`s directly (e.g. `Layer.rectLight({ intensity: bassSignal, width: 300, height: 120 })`).
- **Volumetric Fog & Light Shafts (`volumetricFog`):** `Layer.environment("night", { volumetricFog: true | { density, anisotropy, heightFalloff, baseHeight, color, lightIntensity, ambientIntensity, maxDistance, steps, noise: { scale, strength, speed, octaves } } })` raymarches participating media at half resolution with depth-aware bilateral upsampling. Any shadow-casting `directional`, `spot`, `rect`, or `point` light automatically carves volumetric light shafts (god rays) through the fog behind occluders. `density`, `anisotropy`, and `noise.strength` accept numbers or live `Signal` objects directly.
- **Glass refracts the 3D scene:** glass, acrylic and frosted meshes show the 3D objects behind them as well as the layers under the batch (the batch is drawn once without its glass to make that picture). glTF materials with `KHR_materials_transmission` render as glass with their `KHR_materials_ior`; a `KHR_materials_volume` thickness bends by the refracted ray through that depth, so the bend scales with the object on screen (corneas, potions, ice).
-- **Model files bring their own lobes:** glTF materials with `KHR_materials_clearcoat`, `_sheen`, `_anisotropy` or `_iridescence`, and forge's `subsurface` (written to `extras.framefields.subsurface`), render with those lobes; a layer's own lobe props override them. Subsurface scattering conserves energy: each channel's light wraps past the terminator by how far it scatters (`subsurfaceColor`; red farthest for skin, e.g. `"#ff5a3c"`), so form keeps its shading and only shadow edges warm; thin parts glow when back-lit.
+- **Model files bring their own lobes:** glTF materials with `KHR_materials_clearcoat`, `_sheen`, `_anisotropy` or `_iridescence`, and `subsurface` (in the material's `extras.framefields.subsurface`), render with those lobes; a layer's own lobe props override them. Subsurface scattering conserves energy: each channel's light wraps past the terminator by how far it scatters (`subsurfaceColor`; red farthest for skin, e.g. `"#ff5a3c"`), so form keeps its shading and only shadow edges warm; thin parts glow when back-lit.
- **Substrate lobes (physical shading, needs an environment):** every `Layer3D.*` mesh, `Layer.model` and 3D card accepts `clearcoat` / `clearcoatRoughness` (car paint, lacquer), `anisotropy` (-1..1) / `anisotropyRotation` (deg; brushed metal), `subsurface` / `subsurfaceColor` (wax, jade, skin), `sheen` / `sheenColor` / `sheenRoughness` (velvet, cloth), `iridescence` (0..1 or `{ intensity, thickness, ior }`; soap, oil, beetle shell) with `iridescenceThickness` (nm) / `iridescenceIor`, and `triplanar: true | { scale, sharpness }` for world-space textures on UV-less meshes. Numeric lobes take numbers or live `Signal`s (`clearcoat: bass`). Example: `Layer3D.sphere({ radius: 90, color: "#8a0f1c", metallic: 0.6, roughness: 0.35, clearcoat: 1, clearcoatRoughness: 0.05 })`.
- **HDRI environments:** pass a `.hdr` or `.exr` path instead of a preset: `Layer.environment("assets/hdri/studio.exr", { intensity: 1.2, rotation: 90 })` (or `{ hdri: path }`). The panorama lights and reflects every physical surface; preset names keep working; relative paths resolve from the working directory. EXR files must use lossless compression (NONE, RLE, ZIPS, ZIP, PIZ or PXR24); re-save B44/DWA files as ZIP.
- **Screen-space reflections & GI (`ssr`, `gi`):** `Layer.environment("night", { ssr: true, gi: true })`. `ssr` (`{ intensity, maxRoughness, thickness, steps }`) reflects nearby geometry and emissives in glossy surfaces: chrome, wet floors, lacquer, walls. `gi` (`{ intensity, radius, samples }`) adds contact occlusion and color bleeding from visible surfaces, e.g. a neon sign tinting the floor. Each costs a second 3D pass; only what is on screen can be reflected or bounce, so keep key reflected objects in frame. Use `floor` for a planar mirror that also shows off-screen objects.
diff --git a/plugins/framefields/skills/framefields-render/SKILL.md b/plugins/framefields/skills/framefields-render/SKILL.md
index 0392cfa4..6f4be976 100644
--- a/plugins/framefields/skills/framefields-render/SKILL.md
+++ b/plugins/framefields/skills/framefields-render/SKILL.md
@@ -421,8 +421,8 @@ if (!result.qa!.passed) process.exitCode = 1; // fail CI / the agent loop
| `low_contrast_text` | warning | Text below 3:1 contrast against the solid color behind it (suggests a readable one) |
| `offscreen_layer` | warning | A static absolute layer entirely outside the canvas |
| `duplicate_id` | error | Two layers share an id: the renderer keeps one and drops the other |
-| `shadow_unsupported_light` | warning | `castShadow` on a point or ambient light |
-| `pbr_without_environment` | info | `roughness` / `metallic` set but no `Layer.environment()` (no physical shading) |
+| `shadow_unsupported_light` | warning | `castShadow` on a light that casts none (ambient, environment) |
+| `pbr_without_environment` | info | `roughness` / `metallic` / `clearcoat` / `anisotropy` set but no `Layer.environment()` (no physical shading or coat reflections) |
| `static_track` | info | Every keyframe on a track holds the same value |
The document checks also run on their own, before any render: `comp.lint()` returns the same `{ severity, code, message, layerId }` entries. Run it in Step 1, right after typechecking.
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index c125bbcd..11f9d4a9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2908,33 +2908,6 @@ importers:
specifier: ^4.1.11
- packages/forge:
- devDependencies:
- '@framefields/tsconfig':
- specifier: workspace:*
- version: link:../tsconfig
- '@framefields/webgpu-renderers':
- specifier: workspace:*
- version: link:../webgpu-renderers
- '@types/node':
- specifier: ^24.1.0
- version: 24.10.14
- gltf-validator:
- specifier: 2.0.0-dev.3.10
- version: 2.0.0-dev.3.10
- tsdown:
- specifier: ^0.19.0
- tsx:
- specifier: ^4.20.3
- version: 4.21.0
- typescript:
- specifier: ^5.8.3
- version: 5.9.3
- vitest:
- specifier: ^4.1.11
-
packages/framefields:
dependencies:
'@huggingface/tokenizers':
@@ -3028,9 +3001,9 @@ importers:
'@framefields/core':
specifier: workspace:*
version: link:../core
- '@framefields/forge':
+ '@framefields/gltf-fixtures':
specifier: workspace:*
- version: link:../forge
+ version: link:../gltf-fixtures
'@framefields/node-audio-compressor':
specifier: workspace:*
version: link:../../nodes/node-audio-compressor
@@ -3228,6 +3201,33 @@ importers:
specifier: ^1.24.0
version: 1.30.0
+ packages/gltf-fixtures:
+ devDependencies:
+ '@framefields/tsconfig':
+ specifier: workspace:*
+ version: link:../tsconfig
+ '@framefields/webgpu-renderers':
+ specifier: workspace:*
+ version: link:../webgpu-renderers
+ '@types/node':
+ specifier: ^24.1.0
+ version: 24.10.14
+ gltf-validator:
+ specifier: 2.0.0-dev.3.10
+ version: 2.0.0-dev.3.10
+ tsdown:
+ specifier: ^0.19.0
+ tsx:
+ specifier: ^4.20.3
+ version: 4.21.0
+ typescript:
+ specifier: ^5.8.3
+ version: 5.9.3
+ vitest:
+ specifier: ^4.1.11
+
packages/node-sdk:
dependencies:
'@framefields/core':
diff --git a/specs/character-forge.md b/specs/character-forge.md
deleted file mode 100644
index 1b1e58e8..00000000
--- a/specs/character-forge.md
+++ /dev/null
@@ -1,135 +0,0 @@
-# Character Forge: rigged characters built in code
-
-Status (2026-11-05): `human()` and the MakeHuman assets were removed, and realistic human building is shelved (the DNA reader and RigLogic port were removed too; they are in git history at commit 8d124af5). The forge keeps the GLB writer, skeletons, `sculpt`, `subdivide` and the engine work below (glass eyes, drivers, `morphs`, sparse morphs, texture transforms). The MakeHuman notes below are history.
-
-Earlier status: Phases 1–2 done (GLB writer, skeleton, humanoid preset, bone gizmo; bound sculpting, manifold narrow-band meshing, simplification, smooth material borders, skin weights from the field; `packages/forge`, exposed as `framefields/forge`). Sharp-edge preservation for hard surfaces moves to Phase 7's hard-surface work. Human bodies and faces now start from MakeHuman's CC0 base (`human()`): realistic anatomy, edge loops and UVs, macro and feature targets, painted weights. `sculpt` stays for stylization, costume, armor and non-humans. The face rig (Phase 4) builds on MakeHuman's expression units and the ARKit 52 names. Phase 3 in progress: the loader reads clearcoat, sheen, anisotropy and iridescence and forge's `extras.framefields.subsurface`, the compositor uses them under layer overrides, and the subsurface lobe was rewritten to conserve energy (per-channel wrap). Eyes (first step of Phase 5): `human()` returns MakeHuman's eyeballs fitted to the shaped head (proxy binding), skinned to Mixamo `LeftEye` / `RightEye` pivoted at each ball's least-squares sphere center, plus the CC0 iris texture; a clear coat gives the wet highlight. Corneas are back as glass: glass now refracts the 3D scene behind it (a pre-pass of the batch without glass), and glTF transmission + IOR + volume thickness map to glass whose bend follows the refracted ray through that depth, so the iris shifts with the viewing angle. Lids follow the gaze through joint drivers (`drive`, carried in the GLB), and `addHuman` writes the whole character. Face (Phase 4): ARKit-named blend shapes from MakeHuman's expression units (symmetric ones split into sides with a soft seam), a teeth-and-tongue `mouth` part that moves with the jaw and lips, per-layer `morphs` by name, Loop subdivision that carries shapes and weights exactly, and sparse morph accessors (2 MB per face-rigged body). Skin look development: `skinTextures` bakes the color (blush, lips, mottling) and roughness into the body's UVs from regions found through the blend shapes, plus a tiling pore and crease normal map; `addHuman` uses them by default, and the writer generates tangents and writes texture transforms. Still to do in Phase 4: sculpted teeth to replace MakeHuman's helper blocks, a darkened mouth cavity, wrinkle maps driven by expression weights. Maps now sample with their own glTF samplers. Still to do in Phase 3: alpha-to-coverage for hair cards and morphs combined with skinning; the specular, IOR, transmission and volume extensions are written but not yet rendered. First character: **Ithrael Sunmourn** (`examples/36_emberwake/CHARACTERS.md`), an original hooded elven ranger with a long cloak, long hair, a sculpted face, real eyes, and a full set of expressions.
-
-## Goal
-
-`framefields/forge` builds production-quality, stylized characters from TypeScript and writes standard GLB files that every loader can read: a skeleton on Mixamo names, a skinned sculpted body, materials with several layers, cloth and hair chains, a face rig with eye joints and named blend shapes, and procedural clips. In a composition, the face is driven like the body: `face: { smile: Signal…, blink: auto }` next to `pose`, `aim`, `lookAt` and `springBones`.
-
-Out of scope: photoreal humans and strand-based hair simulation. The target look is a premium stylized sculpt, like a painted miniature come to life.
-
-## What exists and what's missing
-
-| Area | Today | Missing |
-| --- | --- | --- |
-| GLB writing | `GlbBuilder` in `framefields/src/test-utils/glb.ts` | Public API, 32-bit indices, materials, skins, morph targets, animation writing |
-| Sculpting | `sdf-geometry.ts`: six shapes, smooth booleans, Surface Nets at no more than 160 cells | Bone binding, ellipsoid / rounded cone / curve tube / lathe / sweep shapes, bend/twist/mirror/repeat operations, noise displacement, detail resolution, simplification to a budget |
-| Skinning | Loader and renderer read skins | Generating weights |
-| Morph targets | Loader and GPU morph pipeline (any count); clips animate the weights | `extras.targetNames`, per-target weights by name from a composition (`face`/`morphs`), deforming morphs with skinning |
-| Materials | PBR plus emissive strength and unlit in glTF; substrate lobes only on `Layer3D` | Reading and writing `KHR_materials_clearcoat`, `sheen`, `specular`, `ior`, `transmission`, `volume`, `iridescence`, `anisotropy`, and a subsurface material for skin; alpha-tested hair cards |
-| Eyes | None | Eye model: cornea with refraction and a wet highlight, iris parallax, dilating pupil, limbal ring, scleral tint |
-| Hair | None | Hair cards on guide curves, alpha-tested hair shading (Kajiya-Kay or Marschner, two specular lobes), spring chains per lock |
-| Cloth | Spring bones on given joints | Generated cloak and hood mesh with chains, collision against body capsules |
-| Clips | glTF clips play | Writing clips: procedural idle/breathe/walk, keyframed acting, baking a retargeted video into a clip |
-
-## Architecture
-
-```
-packages/forge (new workspace package, bundled into framefields as framefields/forge)
- src/
- glb-writer.ts public GLB writer: meshes, materials + KHR extensions, skins, morphs, clips, extras
- skeleton.ts Skeleton: joints with rest transforms, mirror(), naming presets (mixamo)
- sculpt/
- field.ts bound SDF: every shape belongs to a joint; evaluation returns distance + per-joint influence
- shapes.ts ellipsoid, roundCone, tube(curve, radii), lathe(profile), sweep(profile, path), extrude(outline)
- ops.ts bend, twist, mirror, repeatAlong(curve), displace(noise)
- mesh.ts narrow-band Surface Nets at hero resolution (sparse blocks), feature-preserving relax
- simplify.ts QEM simplification to a triangle budget; keeps UV seams, material borders and morph-relevant areas
- skin.ts weights from the field's per-joint influence, smoothed, top 4 normalized
- bake.ts vertex AO and cavity, curvature (edge wear), thickness (subsurface), normal map from the detailed field
- uv.ts per-material-island planar/cylindrical unwrap (face, iris, cards); triplanar elsewhere
- face/
- face-rig.ts face landmarks, eye/jaw/tongue joints, eyelid and brow regions
- expressions.ts FACS-style blend shapes made by moving the base mesh onto re-sculpted fields
- eyes.ts eyeball, cornea, iris and pupil meshes + eye material
- hair/
- guides.ts guide curves from a groom description (part, flow, length, clumping, curl)
- cards.ts card strips along guides with alpha texture; root-to-tip chains for spring bones
- texture.ts procedural strand alpha/ID/depth/root-tip atlas
- cloth/
- garment.ts cloak/hood/cape panels from outlines draped on the body capsule set; chains + collision capsules
- clips/
- procedural.ts breathe, idle sway, blink, saccades, walk/run from the gait solver
- keys.ts keyframed acting clips (joints + morph weights) → glTF animation
- bake.ts bake pose/aim/retarget output into a clip (for crowds)
- character.ts Character.build(spec) → GLB + report (triangles, joints, morphs, materials, watertight)
- qa.ts turntable, pose-extremes and expression contact sheets through the real renderer
-```
-
-Engine changes outside the package:
-
-- **Loader** (`webgpu-renderers/src/loaders/gltf-loader.ts`): `extras.targetNames`, the KHR material extensions above mapped onto the existing substrate lobes, `alphaMode: MASK` hair with alpha-to-coverage, morphs combined with skinning (morph first, then skin).
-- **Renderer**: an eye shading model (`KHR_materials_*` doesn't cover it; mark it with `extras.framefields.eye` so other viewers fall back to PBR); an anisotropic hair lobe for cards (`extras.framefields.hair`); subsurface skin from the existing subsurface lobe, with thickness from the baked vertex attribute.
-- **Schema** (`character-schema.ts`): `face` (named expressions as `NumberTrack`s, including signals), `morphs` (raw target names), `eyes` (`target`, `saccades`, `blink`, `pupil`), and spring-chain `colliders` (capsules on joints).
-- **Runtime** (`rig.ts`, `renderers/character.ts`): face evaluation order (clips → `morphs`/`face` → eyes look-at → blink); collision for spring chains.
-
-## Face, eyes, and expressions
-
-**Face rig joints.** `Head`, `Jaw`, `LeftEye`/`RightEye`, `LeftEyelidUpper`/`Lower` (also right), `Tongue`. The eyes rotate with real joints, so `lookAt` and saccades are joint rotations and the eyelids follow them as a corrective.
-
-**Expression set** (blend shapes named after FACS action units, with friendly names on top):
-
-| Group | Targets |
-| --- | --- |
-| Brows | browInnerUp, browDown.L/R, browOuterUp.L/R |
-| Eyes | blink.L/R, squint.L/R, wide.L/R, eyeLookUp/Down (lid follow) |
-| Nose and cheeks | sneer.L/R, cheekRaise.L/R, cheekPuff |
-| Mouth | jawOpen, smile.L/R, frown.L/R, pucker, funnel, press, stretch.L/R, upperUp.L/R, lowerDown.L/R, dimple.L/R |
-| Visemes | aa, E, ih, oh, ou, FV, MBP, L, TH, CH (derived from the units above) |
-
-Each target is made by re-sculpting the face field (lids closed, mouth corners pulled up along the cheek, and so on) and moving the base mesh's vertices onto it along the gradient. The vertex layout stays identical, so the targets are valid blend shapes.
-
-**Composition API:**
-
-```ts
-Layer.glb("ithrael.glb", {
- face: {
- expression: { contempt: 0.6, sad: [[0, 0], [48, 0.8]] }, // presets mix FACS units
- smile: Signal.sine({ min: 0, max: 0.2, period: 96 }), // any unit, any track
- speech: { audio: "vo/ithrael.wav", transcript }, // visemes from the word timestamps
- },
- eyes: { target: [960, 400, -300], saccades: true, blink: "auto", pupil: lightLevel },
-});
-```
-
-Presets: neutral, contempt, cold, sad, angry, fear, surprise, smirk, determined, and a "stillness" preset of micro-motion (slow blink, tiny gaze shifts) for Ithrael.
-
-Lip sync: visemes are derived from the scribe-v2 word timestamps through a grapheme-to-phoneme table. No external model is needed.
-
-## Hair
-
-A groom description in code: part line, flow field over the scalp, length map, clumping, curl and stray hairs. Guides grow over the scalp sculpt. Cards are laid along the clumped guides, with a procedural strand atlas texture. Each lock gets a short spring chain (3 to 5 joints) skinned to its cards and colliding with head, neck and shoulder capsules. Under the hood the cards sit on the hood's inner surface, and the loose front locks fall out of the hood.
-
-Shading: alpha-to-coverage cutout, two shifted anisotropic specular lobes (a primary white one and a secondary tinted one), a root-to-tip darkening gradient, and a baked depth/ID texture for variation.
-
-## Cloak and hood
-
-The garment panels are 2D outlines with seams (hood, mantle, long cloak split into back panels for motion). They are draped on the body's capsule set by a short offline relaxation, which gives the rest shape. Each panel then becomes a grid mesh with spring chains down its length, at 6 to 10 columns. Collision capsules on the spine, thighs and upper arms stop the cloak from passing through the legs. The cloth material uses `sheen` and a frayed alpha-tested hem. The hood is weighted to `Head`, with an inner shadow from the baked AO.
-
-## Ithrael's spec
-
-An original design, distinct from any existing character (see CHARACTERS.md): pale-gold skin, short white hair cut close on one side with long locks on the other, an antler crown threaded with living amber leaves, a petal-shaped bark-lacquer armor of amber resin over dark wood, a moss-green hooded cloak, a recurve horn bow, a gold century-ring tattoo down the right arm, and amber eyes. Her acting is stillness: slow, deliberate movement, a gaze that holds, and small expressions (contempt, cold, a sad closing of the eyes).
-
-Budgets: body 40–60k triangles, face area densest, hair 20–30k, cloak 8–12k, 70–90 joints including the face and chains, about 60 blend shapes.
-
-## Phases
-
-1. **GLB writer and skeleton.** Move `GlbBuilder` into `packages/forge` as a public writer: 32-bit indices, materials with KHR extensions, skins, morphs with `targetNames`, clips, extras. Add the skeleton with mirroring and Mixamo names. *Done when:* a round trip through our loader is exact, and the output passes the Khronos glTF validator.
-2. **Bound sculpting and auto-skinning.** Add the new shapes and operations, hero-resolution narrow-band meshing, simplification, and weights from the field. *Done when:* a body bends at the elbows and knees without collapsing, checked on a pose-extremes contact sheet with a volume-loss test.
-3. **Loader and material extensions.** Map the KHR materials onto substrate lobes, add alpha-to-coverage, and combine morphs with skinning. *Done when:* the Khronos sample models for clearcoat, sheen and alpha blending match their reference renders closely.
-4. **Face.** Add the face rig, FACS targets made by projection, the `face`/`morphs`/`eyes` schema and runtime, and visemes from timestamps. *Done when:* the expression contact sheet reads clearly, blinks close fully with the eye looking up or down, and the lips land on the right words.
-5. **Eyes.** Add the eye meshes and shading model (refraction, iris parallax, pupil, wet highlight). *Done when:* the catchlight follows the key light and the iris parallaxes under a camera orbit.
-6. **Hair.** Add grooming, cards, the strand atlas, the anisotropic hair lobe, and lock chains with collision. *Done when:* a turntable shows no harsh card edges, and the hair settles after a head turn without passing through the head.
-7. **Cloth.** Add the garment panels, draping, cloak chains and collision capsules. *Done when:* a walk clip shows the cloak swinging with no leg pass-through.
-8. **Clips and QA.** Add procedural breathe/idle/blink/saccades, keyframed acting clips (draw, release, turn-and-look), bake-to-clip, and the turntable, pose and expression sheets. *Done when:* `examples/36_emberwake` renders Ithrael's test shot (shot 18: "I said I would not let her.") with lip sync, gaze and cloak in wind.
-
-Each phase ships with tests (geometry invariants, a loader round trip, pixel probes through the real renderer), SKILL.md updates (`framefields-compose` Characters section) and `check:plugins`.
-
-## Risks
-
-- **Quality of the face sculpt.** It is the hardest part artistically. Mitigation: base the proportions on published anthropometric ratios, and iterate on the expression contact sheet at close-up camera distance before moving on.
-- **Card hair alpha sorting.** Alpha-to-coverage with MSAA avoids sorting. If our pass doesn't run MSAA, use a dithered cutout with TAA-free temporal stability, verified frame to frame.
-- **Spring chains have no self-collision between locks.** Clumped locks and capsule collision are enough at trailer distances.
-- **Simplification versus morph quality.** Simplify the base before making the targets, and keep extra density in the face area.
diff --git a/specs/ue58-engine-roadmap.md b/specs/ue58-engine-roadmap.md
index 9d8c280a..3459dba1 100644
--- a/specs/ue58-engine-roadmap.md
+++ b/specs/ue58-engine-roadmap.md
@@ -85,6 +85,8 @@ export interface RectLight3DOptions extends Light3DOptions {
- **Omnidirectional Point Light Shadows**:
- For `point` lights with `castShadow: true`, allocate 2 layers in the existing `shadowMaps : texture_depth_2d_array` using **Dual-Paraboloid Shadow Mapping** (front hemisphere $+Z$ and back hemisphere $-Z$), requiring only 2 layers per point light instead of 6 cubemap faces and fitting cleanly into the existing `texture_depth_2d_array` architecture.
+**Status (implemented):** `renderer3d/volumetric-fog-pipeline.ts` raymarches at half resolution with interleaved-gradient jitter seeded by pixel and frame, height falloff, FBM noise with wind, the Henyey-Greenstein phase and shadow-map visibility per light, then upsamples bilaterally on depth into the HDR scene before bloom. Rect lights are `lightType: "rect"` (`Layer.rectLight`), shaded by representative points (closest point on the rectangle for diffuse, the point along the reflection vector for specular, both with horizon handling), not LTC; the spec allowed either. Deviation: point-light shadows are six faces in the shared `texture_depth_2d_array` (a cube's layout, 1024 px), not dual-paraboloid, which avoids paraboloid warping on low-poly casters at the cost of four more layers. Lint: `volumetric_fog_without_lights`.
+
---
## Phase 2: Substrate-Grade Multi-Lobe PBR Materials & Real HDRI Environments
@@ -129,6 +131,8 @@ export interface SurfaceParams {
5. **Thin-Film Iridescence**: Belcour airy-phase spectral interference shifting $F(\cos\theta)$ by optical path difference $2 n_{\text{film}} d \cos\theta_t$.
6. **Triplanar Mapping**: When `triplanar` is active, sample albedo/normal/roughness maps along $(yz, xz, xy)$ world planes blended by $|\mathbf{n}_{\text{world}}|^{\text{sharpness}}$.
+**Status (implemented):** `renderer3d/surface-params.ts` packs clearcoat, anisotropy (with rotation), subsurface, sheen (with roughness), iridescence (thickness, film IOR) and triplanar (scale, sharpness) into the shared surface block, read by meshes, 3D layer planes and Slug text alike; glTF materials with the matching Khronos extensions feed the same lobes. Triplanar samples every map (base color, normal, metal-roughness, occlusion, emissive). Deviation: subsurface is an energy-conserving per-channel wrap (each channel's light reaches past the terminator by how far it scatters) plus view-dependent back-scatter; it does not read thickness from the shadow maps. Lint: `pbr_without_environment` covers `roughness`, `metallic`, `clearcoat` and `anisotropy`.
+
### 2.3 Equirectangular `.hdr` / `.exr` IBL (`HdrEnvironmentLoader`)
Extend `Layer.environment(presetOrPath, options)` to accept a file path (`"assets/hdri/studio_small.hdr"`):
- Decode Radiance `.hdr` (RGBE) in pure TypeScript (`packages/webgpu-renderers/src/loaders/hdr-loader.ts`).
@@ -382,7 +386,7 @@ Currently, `MotionBlurPipeline` (`packages/webgpu-renderers/src/renderer3d/motio
- Upgrade the MRT velocity pass to accept `prevModelMatrix`, `prevSkinningMatrices`, and `prevInstanceBuffer` (`Swarm3DPipeline` / `Layer3D.instances`).
- Fast-moving robot limbs, tumbling shards, and fractured debris get authentic directional per-object and per-bone shutter motion blur.
-**Status (implemented):** fracture geometry `webgpu-renderers/src/renderer3d/fracture-geometry.ts` (pure, unit-tested for closed pieces and exact volume), SDK `framefields/src/physics/fracture3d.ts` (`world.fracture(node, options)` on `PhysicsWorld3D`), compositor `renderers/fracture.ts`; velocity pass `shaders/mesh-velocity.ts` + `Mesh3DPipeline.drawVelocity` / `Renderer3D.beginVelocityPass`, reconstruction `shaders/motion-blur.ts` + `MotionBlurPipeline`, history `node-compositor/src/renderers/motion-history.ts`. Deviations: (1) Voronoi cells are exact (bisectors nearest first until none can reach the cell), not K-nearest. The surface is clipped by each cell's planes, and each cell face is the solid's whole cross-section on its bisector (loops chained by exact position through a point welder, holes nested, triangulated, collinear points restored) clipped to the cell's other planes, so pieces of a watertight source are closed (verified by origin-independent volume) and sum to its volume. (2) The fractured layer is one rigidly skinned mesh (one joint per piece, one draw per material, cut faces in their own `interiorColor` material), not `Layer3D.instances`: pieces differ in shape, and skinning gives motion blur per-piece velocity for free. The pieces' recorded poses (`fracture3d.track`, x y z + quaternion per piece per frame) are JSON; the renderer rebuilds and re-fractures the source deterministically when `modelData` is lost. While every piece is at its frame-0 pose the layer draws in the exact rest pose without its cut faces, so it is sealed (cut faces would otherwise tie the surface's depth along seams). (3) While whole, a fixed collider of the layer's own shape stands in; `fractureFrame: "onImpact"` (default) breaks it on the first dynamic contact, which keeps going (the stand-in's bounce is undone, minus `momentumTransfer`). `Physics.fracture` is `world.fracture` (it needs a world); live worlds are refused. An animated layer's stand-in is kinematic, following its x/y/z/rotation sampled with the compositor's own eases (`sampleLayerProp` in `compositions/src/program/track-sampler.ts`, shared with the compiler's draw-time tracks); at the break each piece is placed from the stand-in's pose and inherits its rigid motion (v + ω × r). The track lives in the layer's parent space, so pieces inside a 3D group fly in the group's space like any body; animated scale is refused (rigid pieces). Kinematic bodies with `follow` now start at their drivers' pose in both worlds. (4) Motion blur is `Layer.camera({ motionBlur })` (shutter angle, samples, max blur). The velocity pass is a second draw of the scene (meshes run the shared `meshDeformWgsl` for this and the previous frame's bindings, so model matrices, skinning, instances, swarms, wind and crowds all move; 3D layer planes use their model matrices), not a color-pass MRT, which keeps every color pipeline variant unchanged. Previous-frame state comes from a per-composition history (instance records copied on the GPU, two parity slots); after a seek the compositor renders the frame before first, recording only, so every frame comes out identical in any order. (5) Reconstruction is McGuire et al.'s tile max / neighbor max gather, with per-sample coverage selection (front sample whose blur reaches, or level/behind sample this pixel's blur reaches) normalized over the samples, which makes uniform motion an exact ramp of the streak length. Morph targets, audio deformation and Slug text planes contribute no velocity of their own yet.
+**Status (implemented):** fracture geometry `webgpu-renderers/src/renderer3d/fracture-geometry.ts` (pure, unit-tested for closed pieces and exact volume), SDK `framefields/src/physics/fracture3d.ts` (`world.fracture(node, options)` on `PhysicsWorld3D`), compositor `renderers/fracture.ts`; velocity pass `shaders/mesh-velocity.ts` + `Mesh3DPipeline.drawVelocity` / `Renderer3D.beginVelocityPass`, reconstruction `shaders/motion-blur.ts` + `MotionBlurPipeline`, history `node-compositor/src/renderers/motion-history.ts`. Deviations: (1) Voronoi cells are exact (bisectors nearest first until none can reach the cell), not K-nearest. The surface is clipped by each cell's planes, and each cell face is the solid's whole cross-section on its bisector (loops chained by exact position through a point welder, holes nested, triangulated, collinear points restored) clipped to the cell's other planes, so pieces of a watertight source are closed (verified by origin-independent volume) and sum to its volume. (2) The fractured layer is one rigidly skinned mesh (one joint per piece, one draw per material, cut faces in their own `interiorColor` material), not `Layer3D.instances`: pieces differ in shape, and skinning gives motion blur per-piece velocity for free. The pieces' recorded poses (`fracture3d.track`, x y z + quaternion per piece per frame) are JSON; the renderer rebuilds and re-fractures the source deterministically when `modelData` is lost. While every piece is at its frame-0 pose the layer draws in the exact rest pose without its cut faces, so it is sealed (cut faces would otherwise tie the surface's depth along seams). (3) While whole, a fixed collider of the layer's own shape stands in; `fractureFrame: "onImpact"` (default) breaks it on the first dynamic contact, which keeps going (the stand-in's bounce is undone, minus `momentumTransfer`). `Physics.fracture` is `world.fracture` (it needs a world); live worlds are refused. An animated layer's stand-in is kinematic, following its x/y/z/rotation sampled with the compositor's own eases (`sampleLayerProp` in `compositions/src/program/track-sampler.ts`, shared with the compiler's draw-time tracks); at the break each piece is placed from the stand-in's pose and inherits its rigid motion (v + ω × r). The track lives in the layer's parent space, so pieces inside a 3D group fly in the group's space like any body; animated scale is refused (rigid pieces). Kinematic bodies with `follow` now start at their drivers' pose in both worlds. (4) Motion blur is `Layer.camera({ motionBlur })` (shutter angle, samples, max blur). The velocity pass is a second draw of the scene (meshes run the shared `meshDeformWgsl` for this and the previous frame's bindings, so model matrices, skinning, instances, swarms, wind and crowds all move; 3D layer planes use their model matrices), not a color-pass MRT, which keeps every color pipeline variant unchanged. Previous-frame state comes from a per-composition history (instance records copied on the GPU, two parity slots); after a seek the compositor renders the frame before first, recording only, so every frame comes out identical in any order. (5) Reconstruction is McGuire et al.'s tile max / neighbor max gather, with per-sample coverage selection (front sample whose blur reaches, or level/behind sample this pixel's blur reaches) normalized over the samples, which makes uniform motion an exact ramp of the streak length. (6) Motion below the model matrix: the motion history keeps a GPU copy of each GPU-deformed mesh's final vertices (morph targets, audio deformation), and the velocity pass deforms from that previous position, so a mesh moved by its blend shapes alone streaks. Text drawn as native Slug glyphs in 3D writes velocity per glyph (this and the previous frame's plane and per-glyph animation, from copied glyph records, written where the outline covers the pixel). The history pass of a seek records every layer in the 3D scene, including ones placed there by `z` or `is3D` alone.
---