Skip to content

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

feat(3d): material maps sample with their own glTF samplers; plan for DNA characters

okanasl2b8b36df603d
diff --git a/.changeset/per-map-samplers.md b/.changeset/per-map-samplers.md
new file mode 100644
index 00000000..c3464586
--- /dev/null
+++ b/.changeset/per-map-samplers.md
@@ -0,0 +1,5 @@
+---
+"framefields": patch
+---
+
+glTF material maps (normal, metallic-roughness, occlusion, emissive) sample with their own samplers instead of the base color's, so a tiling detail map repeats under a clamped base color, and wrap modes apply per axis. Camera `x` / `y` / `z` keyframe tracks now move the camera (they were shadowed by its static position).
diff --git a/packages/framefields/src/map-samplers-render.test.ts b/packages/framefields/src/map-samplers-render.test.ts
new file mode 100644
index 00000000..def970ba
--- /dev/null
+++ b/packages/framefields/src/map-samplers-render.test.ts
@@ -0,0 +1,143 @@
+/**
+ * Each material map samples with its own glTF sampler: a striped normal map
+ * set to repeat, tiled six times by its texture transform, stripes the whole
+ * quad even though the base color map clamps. Before maps had their own
+ * samplers, every map took the base color's clamp and the stripes stopped
+ * after the first tile.
+ */
+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 { encodePng, GltfDocument } from "./forge/index.js";
+import { Composition, Layer, type LayoutNode } from "./index.js";
+import { decodePngPixels } from "./test-utils/pixels.js";
+
+const SIZE = 320;
+const C = SIZE / 2;
+const HALF = 120;
+const TILES = 6;
+
+let dir = "";
+let file = "";
+
+/** 16 × 16 tangent-space normals in vertical bands 4 texels wide, tilted alternately left and right. */
+function stripes(): Uint8Array {
+ const n = 16;
+ const rgba = new Uint8Array(n * n * 4);
+ for (let y = 0; y < n; y++)
+ for (let x = 0; x < n; x++) {
+ const tilt = Math.floor(x / 4) % 2 ? 0.7 : -0.7;
+ const z = Math.sqrt(1 - tilt * tilt);
+ rgba.set(
+ [
+ Math.round((tilt * 0.5 + 0.5) * 255),
+ 128,
+ Math.round((z * 0.5 + 0.5) * 255),
+ 255,
+ ],
+ (y * n + x) * 4,
+ );
+ }
+ return encodePng(rgba, n, n);
+}
+
+beforeAll(async () => {
+ dir = await fs.mkdtemp(path.join(os.tmpdir(), "framefields-samplers-"));
+ file = path.join(dir, "quad.glb");
+ const doc = new GltfDocument();
+ const white = encodePng(new Uint8Array(4 * 4 * 4).fill(255), 4, 4);
+ const material = doc.addMaterial({
+ roughness: 0.9,
+ colorTexture: doc.addTexture({
+ image: white,
+ mimeType: "image/png",
+ wrap: "clamp",
+ }),
+ normalTexture: {
+ texture: doc.addTexture({
+ image: stripes(),
+ mimeType: "image/png",
+ wrap: "repeat",
+ }),
+ transform: { scale: [TILES, TILES] },
+ },
+ });
+ doc.addNode({
+ mesh: doc.addMesh({
+ primitives: [
+ {
+ positions: [
+ -HALF,
+ -HALF,
+ 0,
+ HALF,
+ -HALF,
+ 0,
+ HALF,
+ HALF,
+ 0,
+ -HALF,
+ HALF,
+ 0,
+ ],
+ normals: [0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1],
+ uvs: [0, 1, 1, 1, 1, 0, 0, 0],
+ indices: [0, 1, 2, 0, 2, 3],
+ material,
+ },
+ ],
+ }),
+ });
+ await fs.writeFile(file, doc.toGlb());
+});
+afterAll(async () => {
+ await fs.rm(dir, { recursive: true, force: true });
+});
+
+describe("per-map samplers", () => {
+ it("tiles a repeating normal map across a quad whose base color clamps", async () => {
+ const comp = new Composition({
+ width: SIZE,
+ height: SIZE,
+ fps: 30,
+ durationFrames: 1,
+ backgroundColor: "#000000",
+ });
+ comp.add([
+ Layer.camera({
+ x: C,
+ y: C,
+ z: -C / Math.tan((25 * Math.PI) / 180),
+ targetX: C,
+ targetY: C,
+ targetZ: 0,
+ }),
+ // Grazing from the left: the two tilts light differently.
+ Layer.directionalLight({
+ x: C - 1000,
+ y: C,
+ z: -300,
+ targetX: C,
+ targetY: C,
+ targetZ: 0,
+ intensity: 2,
+ }),
+ Layer.glb(file, { x: C, y: C, z: 0, rotateX: 180 }) as LayoutNode,
+ ]);
+ const { pixels } = await decodePngPixels(
+ await comp.renderFrame({ frame: 0 }),
+ );
+ // Bands along the middle row: light / dark changes past the mean.
+ const row = Array.from({ length: 2 * HALF - 20 }, (_, i) => {
+ const x = C - HALF + 10 + i;
+ return pixels[(C * SIZE + x) * 4 + 1] ?? 0;
+ });
+ const mean = row.reduce((a, b) => a + b, 0) / row.length;
+ let changes = 0;
+ for (let i = 1; i < row.length; i++)
+ if (row[i - 1]! > mean !== row[i]! > mean) changes++;
+ // Six tiles of four bands: about 24 changes. One clamped tile gives about 4.
+ expect(changes).toBeGreaterThan(16);
+ });
+});
diff --git a/packages/webgpu-renderers/src/loaders/gltf-features.test.ts b/packages/webgpu-renderers/src/loaders/gltf-features.test.ts
index 40e01583..ec6ba16f 100644
--- a/packages/webgpu-renderers/src/loaders/gltf-features.test.ts
+++ b/packages/webgpu-renderers/src/loaders/gltf-features.test.ts
@@ -114,6 +114,37 @@ describe("glTF texture features", () => {
expect(mat.textureWrap).toBe("clamp");
});
+ it("reads each map's own sampler, so a detail map can tile under a clamped base color", () => {
+ const doc = quadGltf({
+ pbrMetallicRoughness: { baseColorTexture: { index: 0 } },
+ normalTexture: { index: 1 },
+ occlusionTexture: { index: 2 },
+ });
+ doc.textures = [
+ { source: 0, sampler: 0 },
+ { source: 0, sampler: 1 },
+ { source: 0 },
+ ];
+ doc.samplers = [
+ { wrapS: 33071, wrapT: 33071 },
+ { wrapS: 10497, wrapT: 33648, magFilter: 9728 },
+ ];
+ const mat = parse(doc).materials.M!;
+ expect(mat.textureWrap).toBe("clamp");
+ expect(mat.mapSampling?.normal).toEqual({
+ wrapU: "repeat",
+ wrapV: "mirror",
+ filter: "nearest",
+ });
+ // No sampler: glTF's default, repeat and linear.
+ expect(mat.mapSampling?.occlusion).toEqual({
+ wrapU: "repeat",
+ wrapV: "repeat",
+ filter: "linear",
+ });
+ expect(mat.mapSampling?.metallicRoughness).toBeUndefined();
+ });
+
it("prefers WebP and Basis extension sources", () => {
const doc = quadGltf({
pbrMetallicRoughness: { baseColorTexture: { index: 0 } },
diff --git a/packages/webgpu-renderers/src/loaders/gltf-loader.ts b/packages/webgpu-renderers/src/loaders/gltf-loader.ts
index e3e10659..efd23a25 100644
--- a/packages/webgpu-renderers/src/loaders/gltf-loader.ts
+++ b/packages/webgpu-renderers/src/loaders/gltf-loader.ts
@@ -9,10 +9,12 @@ import type {
AnimationClip3D,
LoadModelOptions,
Material3D,
+ MaterialMapSlot,
MaterialSurface,
Model3DData,
ModelNode3D,
NodeAnimationTrack3D,
+ TextureSampling,
} from "./types.js";
const COMPONENTS: Record<string, number> = {
@@ -963,33 +965,48 @@ export class GltfLoader {
if (base) {
material.diffuseTextureBuffer = base.bytes;
material.diffuseTextureMime = base.mime;
- const wrap = base.sampler?.wrapS;
- material.textureWrap =
- wrap === 33071 ? "clamp" : wrap === 33648 ? "mirror" : "repeat";
- if (base.sampler?.magFilter === 9728) material.textureFilter = "nearest";
+ const sampling = textureSampling(base.sampler);
+ material.textureWrap = sampling.wrapU;
+ if (sampling.filter === "nearest") material.textureFilter = "nearest";
}
- const mapBytes = (info: GltfTextureInfo | undefined, slot: string) =>
- image(info, slot)?.bytes;
- const normal = mapBytes(mat.normalTexture, "normal");
+ const mapBytes = (
+ info: GltfTextureInfo | undefined,
+ slot: string,
+ key: MaterialMapSlot,
+ ) => {
+ const map = image(info, slot);
+ if (!map) return undefined;
+ material.mapSampling = {
+ ...material.mapSampling,
+ [key]: textureSampling(map.sampler),
+ };
+ return map.bytes;
+ };
+ const normal = mapBytes(mat.normalTexture, "normal", "normal");
if (normal) {
material.normalTextureBuffer = normal;
material.normalScale = mat.normalTexture?.scale ?? 1;
}
- const mr = mapBytes(pbr?.metallicRoughnessTexture, "metallic-roughness");
+ const mr = mapBytes(
+ pbr?.metallicRoughnessTexture,
+ "metallic-roughness",
+ "metallicRoughness",
+ );
if (mr) {
material.metallicRoughnessTextureBuffer = mr;
// With a map the factors scale it, and glTF's default factor is 1.
material.roughness = pbr?.roughnessFactor ?? 1;
material.metallic = pbr?.metallicFactor ?? 1;
}
- const occlusion = mapBytes(mat.occlusionTexture, "occlusion");
+ const occlusion = mapBytes(mat.occlusionTexture, "occlusion", "occlusion");
if (occlusion) {
material.occlusionTextureBuffer = occlusion;
material.occlusionStrength = mat.occlusionTexture?.strength ?? 1;
}
// glTF's emissiveFactor defaults to 0: a map alone does not glow.
const emissiveMap =
- material.emissive && mapBytes(mat.emissiveTexture, "emissive");
+ material.emissive &&
+ mapBytes(mat.emissiveTexture, "emissive", "emissive");
if (emissiveMap) material.emissiveTextureBuffer = emissiveMap;
return material;
}
@@ -1526,3 +1543,17 @@ function applyTextureTransform(
uvs[i + 1] = s * u + c * v + offset[1];
}
}
+
+const WRAP: Record<number, TextureSampling["wrapU"]> = {
+ 33071: "clamp",
+ 33648: "mirror",
+};
+
+/** A glTF sampler as addressing and filtering (glTF's defaults: repeat, linear). */
+function textureSampling(sampler: GltfSampler | undefined): TextureSampling {
+ return {
+ wrapU: WRAP[sampler?.wrapS ?? 10497] ?? "repeat",
+ wrapV: WRAP[sampler?.wrapT ?? 10497] ?? "repeat",
+ filter: sampler?.magFilter === 9728 ? "nearest" : "linear",
+ };
+}
diff --git a/packages/webgpu-renderers/src/loaders/types.ts b/packages/webgpu-renderers/src/loaders/types.ts
index d13013c2..01da45db 100644
--- a/packages/webgpu-renderers/src/loaders/types.ts
+++ b/packages/webgpu-renderers/src/loaders/types.ts
@@ -34,6 +34,21 @@ export interface Mesh3DData {
skin?: number;
}
+/** The maps of a material besides its base color. */
+export type MaterialMapSlot =
+ | "normal"
+ | "metallicRoughness"
+ | "occlusion"
+ | "emissive";
+
+/** Addressing and filtering of one texture. */
+export interface TextureSampling {
+ wrapU: "repeat" | "clamp" | "mirror";
+ wrapV: "repeat" | "clamp" | "mirror";
+ /** Magnification filter. */
+ filter: "linear" | "nearest";
+}
+
export interface Material3D {
name: string;
diffuseColor?: [number, number, number, number]; // RGBA, display (sRGB) 0..1
@@ -56,6 +71,11 @@ export interface Material3D {
textureWrap?: "repeat" | "clamp" | "mirror";
/** Magnification filter (glTF sampler magFilter); "nearest" keeps texels sharp. */
textureFilter?: "linear" | "nearest";
+ /**
+ * How each other map is sampled, when it says (glTF: its own sampler).
+ * A map without an entry samples like the base color map.
+ */
+ mapSampling?: Partial<Record<MaterialMapSlot, TextureSampling>>;
normalTexture?: string;
twoSided?: boolean;
/** "mask" discards texels below `alphaCutoff`; "blend" draws after the opaque meshes. */
diff --git a/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts b/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts
index ae111325..718ba7ae 100644
--- a/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts
+++ b/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts
@@ -28,6 +28,13 @@ export interface MeshMaterialMaps {
occlusionStrength?: number;
/** Multiplies the emissive color. */
emissive?: GPUTexture;
+ /** Each map's own sampler; a map without one samples like the base color. */
+ samplers?: Partial<
+ Record<
+ "normal" | "metallicRoughness" | "occlusion" | "emissive",
+ GPUSampler
+ >
+ >;
}
export interface MeshGlass {
@@ -306,6 +313,12 @@ export class Mesh3DPipeline {
visibility: GPUShaderStage.FRAGMENT,
texture: { sampleType: "float" as const },
})),
+ // Their samplers: 6 normal, 7 metallic-roughness, 8 occlusion, 9 emissive
+ ...[6, 7, 8, 9].map((binding) => ({
+ binding,
+ visibility: GPUShaderStage.FRAGMENT,
+ sampler: { type: "filtering" as const },
+ })),
],
});
@@ -818,6 +831,10 @@ export class Mesh3DPipeline {
},
{ binding: 4, resource: (maps?.occlusion ?? white).createView() },
{ binding: 5, resource: (maps?.emissive ?? white).createView() },
+ { binding: 6, resource: maps?.samplers?.normal ?? sampler },
+ { binding: 7, resource: maps?.samplers?.metallicRoughness ?? sampler },
+ { binding: 8, resource: maps?.samplers?.occlusion ?? sampler },
+ { binding: 9, resource: maps?.samplers?.emissive ?? sampler },
],
});
}
diff --git a/packages/webgpu-renderers/src/renderer3d/renderer3d.ts b/packages/webgpu-renderers/src/renderer3d/renderer3d.ts
index dcf4a640..74f581fe 100644
--- a/packages/webgpu-renderers/src/renderer3d/renderer3d.ts
+++ b/packages/webgpu-renderers/src/renderer3d/renderer3d.ts
@@ -23,8 +23,10 @@ import {
import type {
LoadModelOptions,
Material3D,
+ MaterialMapSlot,
Mesh3DData,
Model3DData,
+ TextureSampling,
} from "../loaders/types.js";
import {
type Environment3DFloor,
@@ -2599,6 +2601,7 @@ export class Renderer3D {
occlusionStrength: material.occlusionStrength ?? 1,
}),
...(emissive && { emissive }),
+ samplers: this.mapSamplers(material),
};
})();
this.materialMapCache.set(material, pending);
@@ -2606,6 +2609,22 @@ export class Renderer3D {
return pending;
}
+ /** A sampler for each map that says how it is sampled. */
+ private mapSamplers(material: Material3D): MeshMaterialMaps["samplers"] {
+ const out: NonNullable<MeshMaterialMaps["samplers"]> = {};
+ for (const [slot, s] of Object.entries(material.mapSampling ?? {}) as [
+ MaterialMapSlot,
+ TextureSampling,
+ ][])
+ out[slot] = this.samplerCache.getSampler(this.device, {
+ addressModeU: ADDRESS_MODES[s.wrapU],
+ addressModeV: ADDRESS_MODES[s.wrapV],
+ magFilter: s.filter,
+ ...(s.filter === "nearest" && { maxAnisotropy: 1 }),
+ });
+ return out;
+ }
+
private uploadMaterialTexture(
material: Material3D,
): Promise<GPUTexture | undefined> {
diff --git a/packages/webgpu-renderers/src/shaders/mesh3d.ts b/packages/webgpu-renderers/src/shaders/mesh3d.ts
index f74f9a04..d33438e1 100644
--- a/packages/webgpu-renderers/src/shaders/mesh3d.ts
+++ b/packages/webgpu-renderers/src/shaders/mesh3d.ts
@@ -225,6 +225,10 @@ ${matte3dWgsl(1, 2)}@group(1) @binding(3) var backdropTex : texture_2d<f32>;
@group(2) @binding(3) var metalRoughTex : texture_2d<f32>;
@group(2) @binding(4) var occlusionTex : texture_2d<f32>;
@group(2) @binding(5) var emissiveTex : texture_2d<f32>;
+@group(2) @binding(6) var normalSampler : sampler;
+@group(2) @binding(7) var metalRoughSampler : sampler;
+@group(2) @binding(8) var occlusionSampler : sampler;
+@group(2) @binding(9) var emissiveSampler : sampler;
${lightsBindingsWgsl}
struct VertexOutput {
@@ -393,10 +397,10 @@ fn shadeMesh(in: VertexOutput, isFront: bool) -> MeshFragment {
// Every sample and derivative up front, in uniform control flow.
measureSpecularFilter(in.worldNormal);
var texColor = textureSample(mainTex, texSampler, in.uv);
- var normalSample = textureSample(normalTex, texSampler, in.normalUv).xyz;
- var mrSample = textureSample(metalRoughTex, texSampler, in.mrUv);
- var aoSample = textureSample(occlusionTex, texSampler, in.aoUv).r;
- var emissiveSample = textureSample(emissiveTex, texSampler, in.emissiveUv).rgb;
+ var normalSample = textureSample(normalTex, normalSampler, in.normalUv).xyz;
+ var mrSample = textureSample(metalRoughTex, metalRoughSampler, in.mrUv);
+ var aoSample = textureSample(occlusionTex, occlusionSampler, in.aoUv).r;
+ var emissiveSample = textureSample(emissiveTex, emissiveSampler, in.emissiveUv).rgb;
let dp1 = dpdx(in.worldPos);
let dp2 = dpdy(in.worldPos);
let duv1 = dpdx(in.normalUv);
diff --git a/specs/character-forge.md b/specs/character-forge.md
index 64bbe86f..94ef513c 100644
--- a/specs/character-forge.md
+++ b/specs/character-forge.md
@@ -1,6 +1,6 @@
# Character Forge: rigged characters built in code
-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). Still to do in Phase 4: sculpted teeth to replace MakeHuman's helper blocks, a darkened mouth cavity, and wrinkle maps driven by expression weights. 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.
+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 (DNA plan, Phase 1). 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
diff --git a/specs/dna-face-rig.md b/specs/dna-face-rig.md
new file mode 100644
index 00000000..abccd2ef
--- /dev/null
+++ b/specs/dna-face-rig.md
@@ -0,0 +1,117 @@
+# DNA characters: MetaHuman-compatible faces and bodies
+
+Status: Phase 1 done: each material map samples with its own glTF sampler (loader `mapSampling`, a sampler binding per map in the mesh shader). Phases 2 onward are planned.
+
+## Goal
+
+Load a character exported from MetaHuman Creator (Export > DCC Export: a head DNA file, a body DNA file and textures) into a composition, and animate it with the same rig evaluation Unreal Engine uses: face controls drive joints, corrective blend shapes and wrinkle-map weights. The character then animates with the same tracks as forge humans: `morphs` (ARKit names), `pose`, `aim`, `lookAt`, IK and retargeting from vision.
+
+This sits next to `human()`, not in place of it. `human()` stays the path for people built in code from CC0 data. DNA characters are for users who bring a character made in MetaHuman Creator. Their realism comes from the rig: hundreds of correctives, and wrinkle maps that fade in with each expression. Both kinds of character share the renderer improvements this work brings, wrinkle maps above all.
+
+## Source and terms
+
+- [OpenRigLogic](https://github.com/EpicGames/openriglogic) (Epic Games, MIT): the DNA library (read and write DNA files) and RigLogic (rig evaluation), C++ with Python bindings. Branch `5.8` is the stable one; `main` is experimental. We pin a `5.8` commit.
+- **Code:** we port what we need to TypeScript under MIT. The copyright and license text go into `packages/framefields/NOTICE.md`, and the ported files name their source.
+- **Names:** under the repository's `TRADEMARKS.md`, the MIT license covers code, not names. We may say the code is based on OpenRigLogic, and that a feature reads MetaHuman DNA files. No API, package or feature is named after MetaHuman, RigLogic or OpenRigLogic.
+- **Characters:** none ship. DNA files and textures come from the user's own MetaHuman export, under Epic's MetaHuman terms. Sample DNA from Fab is under the Fab Standard License: use it locally for testing, never commit it. Before release, read the current MetaHuman license on using exported characters outside Unreal Engine and quote it in the docs (open question 1).
+- **Downloads:** cloning OpenRigLogic, and building it locally as a test oracle, needs the user's go-ahead like any download.
+
+## Why a TypeScript port, not native bindings or WebAssembly
+
+- The engine has no native addons outside Dawn, and the forge is pure TypeScript. A port keeps it that way, and runs wherever the renderer runs (CLI, preview, render service).
+- The evaluation is small in essence: a sparse matrix-vector product per output kind, plus pose-space products, conditional tables, RBF and twist/swing. The C++ size (`src/riglogic` about 740 KB, `src/dna` about 400 KB) is mostly SIMD variants (block-4 and block-8 layouts, quaternion and Euler paths), builders, writers and the machine-learned behavior. One scalar reference evaluator in TypeScript covers the behavior.
+- Its matrix form maps to a WebGPU compute pass later, like the morph pipeline.
+- **Fallback:** if the port stalls on format breadth, compile the C++ to WebAssembly with Emscripten and load it as a lazy chunk, like the vision models.
+
+## Design
+
+### Package
+
+`packages/dna` (private, Apache-2.0 plus the MIT notice for the ported parts), bundled into `framefields` as a lazy chunk and exposed as `framefields/dna`. It has no GPU code. The compositor imports it dynamically only when a layer uses a DNA character.
+
+### 1. DNA reader
+
+- Reads the binary format through its layers:
+ - header and descriptor: name, archetype, gender, age, coordinate system, units, LOD count;
+ - definition: control, joint, blend shape, animated map and mesh names; joint hierarchy; neutral joint transforms; LOD mappings;
+ - behavior: GUI-to-raw control map, PSDs, joint matrices per joint group, blend shape channel mapping, animated-map conditional tables;
+ - geometry: mesh vertices, normals, UVs, faces, skin weights, blend shape target deltas;
+ - extension layers as they appear: twist/swing, RBF, joint behavior metadata, machine-learned behavior.
+- Reads only what is asked: layer filter (behavior only, or with geometry), LOD selection (load LOD 0, or LOD 3 for wide shots). A head with every LOD is large; with one LOD it stays reasonable.
+- Checks versions and fails with a clear message on a DNA version it does not know.
+
+### 2. DNA to model
+
+- `dnaToGlb(head, body?, { lod, textures })` in the forge writes a GLB through `GltfDocument`: meshes, skins, blend shapes as named morph targets (sparse), joint hierarchy with neutral transforms, materials from the export's textures (skin, eyes, teeth, eyelashes), and the rig behavior attached as data.
+- The coordinate system and units are converted from the descriptor to glTF's (meters or centimeters, y-up).
+- Going through the GLB means the existing loader, skinning, morphs, materials, `pose`, `lookAt` and retargeting all work unchanged. The rig evaluator is the only new runtime piece.
+- The behavior data (several MB) is stored in the GLB as a buffer view named in the scene's `extras.framefields.rig`, so the file is self-contained. Alternative: keep the `.dna` next to the GLB and reference it (open question 3).
+
+### 3. Rig evaluator
+
+A scalar port with RigLogic's semantics, outputs matched to the C++ within 1e-5:
+
+1. **Controls:** GUI controls → raw controls (clamped ranges); the user sets either.
+2. **PSD:** pose-space inputs appended from products of raw controls.
+3. **Joints:** per joint group, a sparse matrix times the input vector gives joint deltas (translation, rotation, scale) from the neutral pose, truncated by LOD.
+4. **Blend shapes:** a linear map from inputs to blend shape channel weights.
+5. **Animated maps:** conditional tables (piecewise slope-intercept) give wrinkle-mask multipliers.
+6. **Twist/swing and RBF** (mostly body): RBF poses solved from joint rotations drive correctives. These fix the shoulder and elbow collapse that plain linear blend skinning shows.
+7. **Machine-learned behavior:** read, and evaluated last (open question 4).
+
+API: `const rig = new RigEvaluator(reader, { lod })`, then `rig.evaluate(controls)` returns `{ joints, blendShapes, animatedMaps }` into reusable typed arrays, with no allocation per frame.
+
+### 4. Engine wiring
+
+- `Layer.glb(file, { face: { controls: { "CTRL_expressions_jawOpen": track, … } } })`: when the GLB carries rig behavior, the compositor evaluates it each frame.
+ - Joint deltas compose onto the neutral pose before `pose`.
+ - Blend shape weights merge with `morphs`: a named `morphs` track overrides.
+ - Animated map weights go to the material.
+- Order: clips → face rig → `pose` → `aim` → `lookAt` → `drive` → IK → springs.
+- `morphs` with ARKit names on a DNA character go through a mapping table (ARKit 52 → face controls), so the same tracks animate a forge human or a DNA character. Face tracking from video later drives both.
+- Cost: a head has hundreds of joints and thousands of matrix entries. Scalar evaluation on the CPU should take well under a millisecond per frame. It moves to the GPU only if profiling says so.
+
+### 5. Wrinkle maps (renderer)
+
+- A material can carry wrinkle layers: extra normal (and optionally color) maps, plus mask textures whose channels each select a face region. The animated map weights, per region, blend the wrinkle normals in.
+- Written as `extras.framefields.wrinkles` on the material (maps, masks and channel → animated-map name), read by the loader, applied in `mesh3d.ts`.
+- Builds on **per-map samplers** (Phase 1, done): every map samples with its own wrap and filter.
+- The forge human gains wrinkle maps too: bake wrinkle normals for the forehead, eye corners, nasolabial fold and brow furrow from where each expression shape compresses the skin, with masks driven by the ARKit weights. A separate step after the DNA work, using the same renderer feature.
+
+### 6. Body DNA and retargeting
+
+- Body joints come with Unreal's mannequin names (`pelvis`, `spine_01`, `clavicle_l`, `upperarm_l`, …). Add an `"unreal"` preset to `retarget({ rig })`, and joint aliases so `pose` with Mixamo names reaches the right bones.
+- Head and body join at the neck: the head's skeleton is a subtree of the body's. `dnaToGlb(head, body)` merges them into one skeleton.
+
+## Verification
+
+- **Oracle:** build the pinned OpenRigLogic (CMake) with its Python bindings under `scratch/`, after the user approves the clone.
+- **Committed fixture:** a small synthetic DNA file written with the C++ writer from data we make up (a few joints, controls, PSDs, blend shapes, a conditional table, one tiny mesh). It contains no MetaHuman content, so it can be committed. A script regenerates it.
+- **Parity tests:**
+ - the reader against the oracle on every layer of the fixture;
+ - evaluator outputs against the oracle for random controls (fixed seed), within 1e-5.
+- **Real character smoke test:** the user's own export (or Fab sample content) loaded locally:
+ - the GLB passes the Khronos validator;
+ - rendered frames of a neutral face, then jawOpen, smile, blink and brow raise, with wrinkles on and off;
+ - the timings recorded.
+
+ Skipped in CI when absent, like the MakeHuman cache tests.
+
+## Phases
+
+1. Per-map samplers in the renderer (prerequisite for wrinkle maps, fixes the pore map).
+2. DNA reader: header, descriptor, definition, geometry. `dnaToGlb` renders a neutral head with its textures.
+3. Behavior layer and evaluator: controls, PSD, joints, blend shapes. Face controls animate the head. Parity tests.
+4. Animated maps and wrinkle maps in the renderer.
+5. ARKit mapping and `morphs` on DNA characters; ARKit-named faces drive both kinds of character.
+6. Body DNA: twist/swing, RBF correctives, the `"unreal"` retarget preset, head and body merged.
+7. Machine-learned behavior, if present in exports and worth it.
+8. Docs: the `framefields-compose` skill (DNA characters, face controls, wrinkles), NOTICE, changesets, an example film shot with a DNA character, and the license wording from open question 1.
+
+## Open questions
+
+1. What does the current MetaHuman license allow for exported characters rendered outside Unreal Engine, in our CLI, our render service and users' outputs? The docs must state it accurately before release.
+2. Is there a MetaHuman export available for testing (UE 5.8 with MetaHuman Creator)? If not, Fab's sample content works for local testing.
+3. Store the rig behavior inside the GLB, or keep the `.dna` next to it?
+4. Do current exports use the machine-learned behavior layer, and does the face need it to look right?
+5. Grooms (hair, brows, lashes) are not in the export. Eyelash and eyebrow cards come with the head mesh; hair needs the forge's planned hair cards.