@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/kinds/head-rim.ts

@@ -0,0 +1,128 @@
+// Seamless split: a mesher rounds the edge where the jaw cut meets the skin by about one cell, so
+// the head and jaw would show a groove along the cut. This pass snaps every vertex near that rim
+// back onto the exact surfaces — skin vertices onto skull = 0, cut-face vertices onto cut = 0, both
+// clamped to their side — and gives skin vertices the skull's own normal, so the two parts meet on
+// one crease line with matching shading.
+
+import type { Mesh, Vec3 } from '../core/index.ts';
+
+/** A mutable point/vector (core's Vec3 is readonly). */
+type P3 = [number, number, number];
+
+import type { Field } from '../primitives/index.ts';
+
+function grad(f: Field, p: Vec3, e: number, out: P3): number {
+  const q: P3 = [p[0], p[1], p[2]];
+  const at = (dx: number, dy: number, dz: number): number => {
+    q[0] = p[0] + dx;
+    q[1] = p[1] + dy;
+    q[2] = p[2] + dz;
+    return f(q);
+  };
+  out[0] = (at(e, 0, 0) - at(-e, 0, 0)) / (2 * e);
+  out[1] = (at(0, e, 0) - at(0, -e, 0)) / (2 * e);
+  out[2] = (at(0, 0, e) - at(0, 0, -e)) / (2 * e);
+  return f(p);
+}
+
+/** Newton step of `p` towards f = 0 (only when f > 0 if `onlyOutside`). */
+function project(f: Field, p: P3, e: number, onlyOutside: boolean): void {
+  const g: P3 = [0, 0, 0];
+  const v = grad(f, p, e, g);
+  if (onlyOutside && v <= 0) return;
+  const gg = g[0] * g[0] + g[1] * g[1] + g[2] * g[2];
+  if (gg < 1e-12) return;
+  for (let k = 0; k < 3; k++) p[k] = (p[k] ?? 0) - (v * (g[k] ?? 0)) / gg;
+}
+
+/** Part ≈ max(skull, side); `side` is the cut field signed so the part is where side < 0;
+ *  `part` is the part's full field (with ears/tusks), so their vertices are left alone. */
+export function sharpenRim(m: Mesh, skull: Field, side: Field, part: Field, res: number): Mesh {
+  const positions = new Float32Array(m.positions);
+  const normals = new Float32Array(m.normals);
+  const e = res * 0.25;
+  const gs: P3 = [0, 0, 0];
+  const gc: P3 = [0, 0, 0];
+  for (let i = 0; i < positions.length; i += 3) {
+    const p: P3 = [positions[i] ?? 0, positions[i + 1] ?? 0, positions[i + 2] ?? 0];
+    // The cut is cheap and analytic; the skull is the costly sculpt — test the cut first.
+    if (Math.abs(side(p)) > res * 2) continue;
+    const c = grad(side, p, e, gc);
+    const s = grad(skull, p, e, gs);
+    if (Math.abs(s) > res * 2) continue;
+    // Skip where an extra (ear, tusk) owns the surface.
+    if (part(p) < Math.max(s, c) - res * 0.5) continue;
+    const n: Vec3 = [normals[i] ?? 0, normals[i + 1] ?? 0, normals[i + 2] ?? 0];
+    const ls = Math.hypot(...gs) || 1;
+    const lc = Math.hypot(...gc) || 1;
+    const onSkin =
+      (n[0] * gs[0] + n[1] * gs[1] + n[2] * gs[2]) / ls >=
+      (n[0] * gc[0] + n[1] * gc[1] + n[2] * gc[2]) / lc;
+    for (let k = 0; k < 4; k++) {
+      if (onSkin) {
+        project(skull, p, e, false);
+        project(side, p, e, true);
+      } else {
+        project(side, p, e, false);
+        project(skull, p, e, true);
+      }
+    }
+    // Within ~half a cell of the other surface: snap onto the crease line itself, so no bevel
+    // strip (seen from outside as a dark groove) is left between skin and cut face.
+    const other = onSkin ? side(p) : skull(p);
+    if (other > -res * 0.6)
+      for (let k = 0; k < 6; k++) {
+        project(skull, p, e, false);
+        project(side, p, e, false);
+      }
+    positions[i] = p[0];
+    positions[i + 1] = p[1];
+    positions[i + 2] = p[2];
+    if (onSkin) {
+      grad(skull, p, e, gs);
+      const l = Math.hypot(...gs) || 1;
+      normals[i] = gs[0] / l;
+      normals[i + 1] = gs[1] / l;
+      normals[i + 2] = gs[2] / l;
+    }
+  }
+  return { ...m, positions, normals };
+}
+
+/**
+ * Where a field gradient smears across a hard crease (the jaw cut at coarse cells), a vertex
+ * normal can oppose its triangles; those vertices take their area-weighted face normal instead.
+ */
+export function creaseNormals(m: Mesh, minDot = 0.2): Mesh {
+  const P = m.positions;
+  const acc = new Float64Array(P.length);
+  for (let t = 0; t < m.indices.length; t += 3) {
+    const a = (m.indices[t] ?? 0) * 3;
+    const b = (m.indices[t + 1] ?? 0) * 3;
+    const c = (m.indices[t + 2] ?? 0) * 3;
+    const ux = (P[b] ?? 0) - (P[a] ?? 0);
+    const uy = (P[b + 1] ?? 0) - (P[a + 1] ?? 0);
+    const uz = (P[b + 2] ?? 0) - (P[a + 2] ?? 0);
+    const vx = (P[c] ?? 0) - (P[a] ?? 0);
+    const vy = (P[c + 1] ?? 0) - (P[a + 1] ?? 0);
+    const vz = (P[c + 2] ?? 0) - (P[a + 2] ?? 0);
+    const n = [uy * vz - uz * vy, uz * vx - ux * vz, ux * vy - uy * vx];
+    for (const v of [a, b, c])
+      for (let k = 0; k < 3; k++) acc[v + k] = (acc[v + k] ?? 0) + (n[k] ?? 0);
+  }
+  const normals = new Float32Array(m.normals);
+  for (let i = 0; i < normals.length; i += 3) {
+    const l = Math.hypot(acc[i] ?? 0, acc[i + 1] ?? 0, acc[i + 2] ?? 0);
+    if (l < 1e-20) continue;
+    const f = [(acc[i] ?? 0) / l, (acc[i + 1] ?? 0) / l, (acc[i + 2] ?? 0) / l];
+    const d =
+      (normals[i] ?? 0) * (f[0] ?? 0) +
+      (normals[i + 1] ?? 0) * (f[1] ?? 0) +
+      (normals[i + 2] ?? 0) * (f[2] ?? 0);
+    if (d >= minDot) continue;
+    normals[i] = f[0] ?? 0;
+    normals[i + 1] = f[1] ?? 0;
+    normals[i + 2] = f[2] ?? 0;
+  }
+  return { ...m, normals };
+}

package/src/kinds/head-tone.ts

@@ -0,0 +1,52 @@
+// Hand-painted tone for sculpted head/bust vertex colour: the painter's three passes done from the
+// distance field itself — cavity (crevices, folds, sockets go darker and a touch more saturated),
+// a warm key from above (top planes lifted and warmed), and a cool bounce underneath. Pure field
+// sampling at the surface point, so it is deterministic and costs ~9 field evaluations per vertex.
+
+import type { Vec3 } from '../core/index.ts';
+import type { Field } from '../primitives/index.ts';
+
+export interface ToneOptions {
+  /** Probe distance for the cavity test, head units (≈ the size of a fold). */
+  readonly reach: number;
+  /** 0 = flat colour, 1 = full painted tone. */
+  readonly strength?: number;
+}
+
+/** Wraps `colorAt` with cavity darkening and a warm-top / cool-under gradient. */
+export function toned(field: Field, colorAt: (q: Vec3) => Vec3, o: ToneOptions): (q: Vec3) => Vec3 {
+  const k = o.strength ?? 1;
+  const d = o.reach;
+  const e = d * 0.25;
+  return (q) => {
+    const c = colorAt(q);
+    const [x, y, z] = q;
+    const gx = field([x + e, y, z]) - field([x - e, y, z]);
+    const gy = field([x, y + e, z]) - field([x, y - e, z]);
+    const gz = field([x, y, z + e]) - field([x, y, z - e]);
+    const gl = Math.hypot(gx, gy, gz) || 1;
+    const n: Vec3 = [gx / gl, gy / gl, gz / gl];
+    // Cavity: walk out along the normal; a crevice brings other surface closer than the walk.
+    let occ = 0;
+    for (let i = 1; i <= 3; i++) {
+      const t = (d * i) / 3;
+      occ += Math.max(0, t - field([x + n[0] * t, y + n[1] * t, z + n[2] * t])) / t / i;
+    }
+    const cav = Math.min(1, occ * 2.5) * k;
+    const up = n[2] * k;
+    const lift = up > 0 ? 1 + up * 0.22 : 1 + up * 0.3;
+    const warm: Vec3 =
+      up > 0 ? [1 + up * 0.12, 1 + up * 0.05, 1 - up * 0.15] : [1 + up * 0.1, 1, 1 - up * 0.12];
+    const dark = 1 - cav * 0.55;
+    const lum = (c[0] + c[1] + c[2]) / 3;
+    // Saturate into the crevice: push each channel away from the grey by the cavity.
+    const sat = 1 + cav * 0.35;
+    return [
+      clamp((lum + (c[0] - lum) * sat) * dark * lift * warm[0]),
+      clamp((lum + (c[1] - lum) * sat) * dark * lift * warm[1]),
+      clamp((lum + (c[2] - lum) * sat) * dark * lift * warm[2]),
+    ];
+  };
+}
+
+const clamp = (v: number): number => Math.min(Math.max(v, 0), 1);

package/src/kinds/head-torso.ts

@@ -0,0 +1,230 @@
+// The bust's anatomy, cut and plinth: ribcage, pectorals, deltoids, the trapezius sloping from
+// behind the ear to the shoulder (it is what joins a head to a body), clavicles and the sternal
+// notch — all scaled by `bust.mass` (0 bony … 1 brute) — trimmed by the classic collectible-bust
+// cut (a U under the chest rising to the arms) and set on a turned socle + disc plinth.
+// Head units, mirrored across Y; `torsoForms(f, g)` grows every form by g for clothing shells.
+
+import type { Vec3 } from '../core/index.ts';
+import { type Field, type SculptEdit, sd } from '../primitives/index.ts';
+import { alongX } from './head-geom.ts';
+import type { HeadLayout } from './head-layout.ts';
+import type { HeadParams } from './head-params.ts';
+
+/** Where the bust sits relative to the head: centre x, shoulder half-span, base, neck root… */
+export interface BustFrame {
+  readonly cx: number;
+  readonly s: number;
+  /** Reference z the torso is laid out from (the floor lifted by the build's hunch). */
+  readonly b: number;
+  /** The asset's floor: bottom of the plinth. */
+  readonly floor: number;
+  /** Neck root (top of the sternum), z. */
+  readonly nz: number;
+  readonly m: number;
+  /** Neck radius. */
+  readonly n: number;
+  /** Where the trapezius meets the neck, z (high behind the ear on a brute). */
+  readonly trapZ: number;
+  /** Top of the plinth = bottom of the chest cut, z. */
+  readonly cutZ: number;
+}
+
+const sub = (a: Vec3, b: Vec3): Vec3 => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const mid = (a: Vec3, b: Vec3): Vec3 => [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2, (a[2] + b[2]) / 2];
+const dist = (a: Vec3, b: Vec3): number => Math.hypot(...sub(a, b));
+
+/** Plinth height, head units. */
+const PLINTH = 0.17;
+
+export function frameOf(p: HeadParams, l: HeadLayout): BustFrame {
+  const m = p.bust.mass ?? 0.5;
+  // A brute's shoulders ride up round its ears (the hunch): lift the torso, lengthen the socle.
+  const b = l.base + 0.06 + 0.1 * m;
+  const nz = b + 0.6;
+  return {
+    cx: l.cranium.at[0] + p.jaw.muzzle * 0.3,
+    s: p.bust.shoulders,
+    b,
+    floor: l.base,
+    nz,
+    m,
+    n: p.neck.radius,
+    trapZ: nz + 0.12 + (l.hinge[1] - 0.2 - nz - 0.12) * m,
+    cutZ: l.base + PLINTH + 0.06 + 0.1 * m,
+  };
+}
+
+/** Anatomy volumes (plain adds), every one grown by `g`. */
+export function torsoForms(f: BustFrame, g = 0): SculptEdit[] {
+  const { cx, s, b, m, n } = f;
+  const grow = (r: Vec3): Vec3 => [r[0] + g, r[1] + g, r[2] + g];
+  const top: Vec3 = [cx - 0.12, n * 0.5, f.trapZ];
+  const acromion: Vec3 = [cx - 0.05, s * 0.78, b + 0.62 + 0.05 * m];
+  return [
+    // Ribcage: the barrel everything hangs on.
+    {
+      shape: 'ellipsoid',
+      at: [cx - 0.05, 0, b + 0.36],
+      size: grow([0.25 + 0.07 * m, s * 0.66, 0.38]),
+    },
+    // Pectorals: two slabs angled up to the shoulder; their lower edge is the chest's shadow line.
+    {
+      shape: 'ellipsoid',
+      at: [cx + 0.1 + 0.05 * m, s * 0.27, b + 0.46 + 0.02 * m],
+      size: grow([0.09 + 0.06 * m, s * 0.27, 0.11 + 0.03 * m]),
+      rotate: [-12, 0, 16],
+      blend: 0.05,
+    },
+    // Deltoids: a cap over each shoulder joint.
+    {
+      shape: 'ellipsoid',
+      at: [cx - 0.03, s * 0.8, b + 0.5 + 0.03 * m],
+      size: grow([0.13 + 0.06 * m, 0.11 + 0.05 * m, 0.16 + 0.05 * m]),
+      rotate: [-18, 0, 0],
+      blend: 0.08,
+    },
+    // Trapezius: a broad flat sheet from the neck behind the ear down to the acromion — the slope
+    // of a brute (local X along the slope, Y front-back, Z its thickness).
+    {
+      shape: 'ellipsoid',
+      at: mid(top, acromion),
+      size: [dist(top, acromion) / 2 + 0.08 + g, 0.11 + 0.12 * m + g, 0.05 + 0.1 * m + g],
+      rotate: alongX(sub(acromion, top)),
+      blend: 0.08 + 0.08 * m,
+    },
+    // Upper arm: a stump the bust cut ends, filling the shoulder under any pauldron.
+    {
+      shape: 'capsule',
+      at: [cx - 0.04, s * 0.8, b + 0.55],
+      to: [cx - 0.02, s * 0.9, b + 0.05],
+      size: 0.12 + 0.05 * m + g,
+      blend: 0.06,
+    },
+    // Clavicles: a bony ridge from the sternal notch out to the shoulder (clothes drape over it).
+    {
+      shape: 'capsule',
+      at: [cx + 0.2 + 0.04 * m, 0.045, f.nz - 0.03],
+      to: [cx + 0.0, s * 0.68, b + 0.6 + 0.04 * m],
+      size: 0.02 + 0.006 * (1 - m) + g,
+      blend: 0.035,
+    },
+    // Latissimus: widens the back under the armpit (a V-taper on a brute).
+    {
+      shape: 'ellipsoid',
+      at: [cx - 0.1, s * 0.55, b + 0.3],
+      size: grow([0.17 + 0.05 * m, 0.12 + 0.1 * m, 0.2]),
+      blend: 0.08,
+    },
+    // Upper back: the hump of trapezius and rhomboids behind the neck.
+    {
+      shape: 'ellipsoid',
+      at: [cx - 0.18, 0, f.nz + 0.04 + 0.08 * m],
+      size: grow([0.12 + 0.06 * m, s * 0.32, 0.16 + 0.12 * m]),
+      blend: 0.1,
+    },
+  ];
+}
+
+/** Signed distance to the bust-cut region (negative inside): ≈ 0 on the cut faces. */
+export function cutField(f: BustFrame): Field {
+  const rz = 0.64;
+  const ry = f.s * 1.08;
+  const cz = f.cutZ + rz;
+  const e = sd.ellipsoid([f.cx, 0, cz], [1.6, ry, rz]);
+  const box = sd.box([f.cx, 0, cz + 1], [3.2, ry * 2, 2]);
+  return (q) => Math.min(e(q), box(q));
+}
+
+/** Keeps a group to the bust silhouette: the U-cut under the chest, rising to cut the arms. */
+export function bustCut(f: BustFrame, g = 0): SculptEdit {
+  const rz = 0.64;
+  const ry = f.s * 1.08 + g;
+  // (cutField mirrors these numbers.)
+  const cz = f.cutZ + rz - g;
+  return {
+    group: [
+      { shape: 'ellipsoid', at: [f.cx, 0, cz], size: [1.6, ry, rz] },
+      { shape: 'roundBox', at: [f.cx, 0, cz + 1], size: [3.2, ry * 2, 2] },
+    ],
+    op: 'intersect',
+    blend: 0.012,
+  };
+}
+
+/** The bare body: anatomy in `color`, sternal notch and groove, then the bust cut. */
+export function bodyEdits(p: HeadParams, f: BustFrame, color: Vec3): SculptEdit[] {
+  const { cx, b, m, nz } = f;
+  const shade = p.colors.shade;
+  return [
+    {
+      group: [
+        ...torsoForms(f),
+        {
+          shape: 'sphere',
+          at: [cx + 0.24 + 0.04 * m, 0, nz - 0.04],
+          size: 0.035,
+          op: 'subtract',
+          blend: 0.04,
+          color: shade,
+        },
+        {
+          shape: 'capsule',
+          at: [cx + 0.26 + 0.06 * m, 0, b + 0.5],
+          to: [cx + 0.26 + 0.05 * m, 0, b + 0.22],
+          size: 0.01 + 0.006 * m,
+          op: 'subtract',
+          blend: 0.04,
+          color: shade,
+        },
+        bustCut(f),
+      ],
+      color,
+    },
+  ];
+}
+
+/** Solid cylinder about Z from z0 to z1 (a capsule cut by a slab). */
+const cylinder = (at: Vec3, r: number, z0: number, z1: number): SculptEdit => ({
+  group: [
+    { shape: 'capsule', at: [at[0], at[1], z0 - r], to: [at[0], at[1], z1 + r], size: r },
+    {
+      shape: 'roundBox',
+      at: [at[0], at[1], (z0 + z1) / 2],
+      size: [4, 4, z1 - z0],
+      op: 'intersect',
+    },
+  ],
+});
+
+/** A turned plinth: wide disc with a bead moulding, then a narrower socle up to the chest cut.
+ *  Both start below the floor, so the bust's flat base cut alone makes the underside. */
+/** `minT`: floor for the disc's thickness (≈ a cell), so far LODs keep the bust on the ground. */
+export function plinthEdits(p: HeadParams, f: BustFrame, minT = 0): SculptEdit[] {
+  const c = p.colors.plinth ?? ([0.16, 0.15, 0.15] as Vec3);
+  const light: Vec3 = [c[0] * 1.35, c[1] * 1.35, c[2] * 1.35];
+  const x = f.cx - 0.04;
+  const R = 0.3 + 0.08 * f.s;
+  // Coarse cells would lose a thin disc: one solid drum from the floor to the chest cut instead.
+  if (minT > 0.07)
+    return [
+      { ...cylinder([x, 0, 0], R * 1.05, f.floor - 0.1, f.cutZ + 0.02), color: c, mirror: false },
+    ];
+  const disc = f.floor + 0.07;
+  return [
+    { ...cylinder([x, 0, 0], R, f.floor - 0.1, disc), color: c, mirror: false },
+    {
+      shape: 'torus',
+      at: [x, 0, disc],
+      size: [R - 0.03, 0.025],
+      color: light,
+      blend: 0.01,
+      mirror: false,
+    },
+    {
+      ...cylinder([x, 0, 0], R * 0.62, disc, f.cutZ + 0.02),
+      color: c,
+      blend: 0.02,
+      mirror: false,
+    },
+  ];
+}

package/src/kinds/head.ts

@@ -0,0 +1,176 @@
+// Head kind: `head(ctx, …)` sculpts a stylised fantasy head + bust from a race preset (orc, goblin,
+// human, dwarf, elf) or a full `HeadParams`, and emits the engine contract: `bust` (on z = 0),
+// `head`, `jaw` (pivot at the hinge, opens about Y), `eye_l` / `eye_r` (pivots at the eyeball
+// centres, gaze +X so an engine can aim them). Head units are scaled by `height` metres.
+// LOD policy: sculpt cell 2 % / 4.5 % / 14 % of the head height (HEAD_RES); LOD2 drops warts, wiry
+// tufts and the AO bake and floors ear/tusk thickness at about a cell so they survive. Vertex AO is
+// baked across all parts at LOD0/1 (creases, under the jaw, eye sockets).
+
+import {
+  type BuildContext,
+  type Mesh,
+  merge,
+  place,
+  type Rng,
+  Ts23dError,
+  type Vec3,
+} from '../core/index.ts';
+import { bakeAo } from '../passes/index.ts';
+import { sculptField } from '../primitives/index.ts';
+import { beardEdits, browEdits } from './head-beard.ts';
+import { bustEdits } from './head-bust.ts';
+import { earEdits, paintEdits, tuskEdits, wartEdits } from './head-extras.ts';
+import { primaryEdits, skullEdits } from './head-face.ts';
+import { hairEdits } from './head-hair.ts';
+import { type HeadLayout, headLayout } from './head-layout.ts';
+import { bustMesh, eyeMesh, type HeadEditSet, headAndJaw } from './head-mesh.ts';
+import { checkHead, type HeadParams } from './head-params.ts';
+import { HEADS, type HeadPreset } from './head-presets.ts';
+import { cutField, frameOf } from './head-torso.ts';
+
+/** Overrides: top-level keys replace, nested objects merge one level (`{ jaw: { underbite: 0.1 } }`). */
+export type HeadOverrides = { readonly [K in keyof HeadParams]?: Partial<HeadParams[K]> };
+
+export interface HeadOptions {
+  readonly race?: HeadPreset | HeadParams;
+  readonly params?: HeadOverrides;
+  /** Part-name prefix: `orc` → `orc_head`, `orc_jaw`, `orc_eye_l` … Default none. */
+  readonly prefix?: string;
+  /** Where the bust base sits, metres. */
+  readonly at?: Vec3;
+  /** Baked jaw motion (degrees either side of rest, 0 = static pivot). Default 0. */
+  readonly jawSway?: number;
+}
+
+export interface HeadInfo {
+  readonly parts: { bust: string; head: string; jaw: string; eyeL: string; eyeR: string };
+  /** Overall height of bust + head, metres. */
+  readonly height: number;
+  readonly params: HeadParams;
+}
+
+export function headParams(o: Pick<HeadOptions, 'race' | 'params'> = {}): HeadParams {
+  const r = o.race ?? 'human';
+  const base = typeof r === 'string' ? HEADS[r] : r;
+  if (!base)
+    throw new Ts23dError('T3D_RECIPE_INVALID', {
+      cause: `unknown head race '${String(r)}'`,
+      fix: `use one of ${Object.keys(HEADS).join(', ')} or pass a HeadParams object`,
+    });
+  const out: Record<string, unknown> = { ...base };
+  for (const [k, v] of Object.entries(o.params ?? {})) {
+    const was = out[k];
+    out[k] =
+      v && typeof v === 'object' && !Array.isArray(v) && was && typeof was === 'object'
+        ? { ...was, ...v }
+        : v;
+  }
+  return checkHead(out as unknown as HeadParams);
+}
+
+/** Moves the eyes forward/back so they sit in the face surface: probe the brain case + face
+ *  plate along −X at the eye, then sink the eyeball by `brow.overhang`. */
+function seatEyes(p: HeadParams, l: HeadLayout): HeadLayout {
+  const f = sculptField(primaryEdits(l), { color: p.colors.skin }).field;
+  const [, ey, ez] = l.eye;
+  let x = l.faceX + 0.4;
+  for (let i = 0; i < 400 && f([x, ey, ez]) > 0; i++) x -= 0.002;
+  const r = l.eyeR;
+  return { ...l, eye: [x - r * 0.7 - p.brow.overhang * 0.3, ey, ez] };
+}
+
+/** The bust's cell as a multiple of the head's (the bust carries less detail). */
+const BUST_CELL = 1.6;
+
+/** Sculpt cell edge per LOD, in head units (× height = metres). */
+export const HEAD_RES = [0.02, 0.045, 0.14] as const;
+
+/** Every edit list of a head, in head units (pure: same params + rng state → same edits). */
+export function headEdits(
+  p: HeadParams,
+  rng: Rng,
+  lod: 0 | 1 | 2 = 0,
+): HeadEditSet & { layout: HeadLayout } {
+  const l = seatEyes(p, headLayout(p));
+  const res = HEAD_RES[lod];
+  const warts = lod < 2 ? wartEdits(p, l, rng) : [];
+  const hair = lod < 2 || p.hair !== 'tufts' ? hairEdits(p, l) : [];
+  return {
+    layout: l,
+    skull: [
+      ...skullEdits(p, l, res),
+      ...hair,
+      ...browEdits(p, l),
+      ...beardEdits(p, l),
+      ...warts,
+      ...paintEdits(p, l),
+    ],
+    ears: earEdits(p, l, res * 0.7),
+    tusks: tuskEdits(p, l, res * 0.45),
+    bust: bustEdits(p, l, res * BUST_CELL),
+    bustCut: cutField(frameOf(p, l)),
+  };
+}
+
+export function head(ctx: BuildContext, o: HeadOptions = {}): HeadInfo {
+  const p = headParams(o);
+  const set = headEdits(p, ctx.rng.fork('head'), ctx.lod);
+  const l = set.layout;
+  const H = p.height;
+  const res = HEAD_RES[ctx.lod];
+  const { head: hm, jaw: jm } = headAndJaw(p, l, set, res);
+  const bm = bustMesh(p, set, res * BUST_CELL);
+  const eye = eyeMesh(p, l.eyeR, l.eyeR / ctx.pick([7, 3.5, 2.2]));
+  const [ox, oy, oz] = o.at ?? [0, 0, 0];
+  const toWorld = (m: Mesh, at: Vec3 = [0, 0, 0]): Mesh =>
+    place(m, { scale: H, at: [ox + at[0] * H, oy + at[1] * H, oz + (at[2] - l.base) * H] });
+  // Coarse LODs: the coarse socket would swallow the eyeball, so it sits a little proud.
+  const ex = l.eye[0] + (ctx.lod > 0 ? res * 0.4 : 0);
+  const [, ey, ez] = l.eye;
+  const world = {
+    bust: toWorld(bm),
+    head: toWorld(hm),
+    jaw: toWorld(jm),
+    eye_l: toWorld(eye, [ex, ey, ez]),
+    eye_r: toWorld(eye, [ex, -ey, ez]),
+  };
+  // AO occluders leave out the other half of the jaw split: its cut face lies flush against ours
+  // and would draw a dark line along the seam.
+  const occ = (skip: Mesh): Mesh => merge(Object.values(world).filter((m) => m !== skip));
+  const occHead = occ(world.jaw);
+  const occJaw = occ(world.head);
+  const ao = (m: Mesh, by: Mesh = occHead): Mesh =>
+    ctx.lod < 2
+      ? bakeAo(m, { samples: ctx.pick([16, 10, 8]), radius: (0.12 * H) / 0.23, strength: 0.55 }, by)
+      : m;
+  const pre = o.prefix ? `${o.prefix}_` : '';
+  const pivot = (x: number, y: number, z: number): Vec3 => [
+    ox + x * H,
+    oy + y * H,
+    oz + (z - l.base) * H,
+  ];
+  const local = (m: Mesh, at: Vec3, by?: Mesh): Mesh =>
+    place(ao(m, by), { at: [-at[0], -at[1], -at[2]] });
+  const hinge = pivot(l.hinge[0], 0, l.hinge[1]);
+  const eyeL = pivot(ex, ey, ez);
+  const eyeR = pivot(ex, -ey, ez);
+  const names = {
+    bust: `${pre}bust`,
+    head: `${pre}head`,
+    jaw: `${pre}jaw`,
+    eyeL: `${pre}eye_l`,
+    eyeR: `${pre}eye_r`,
+  };
+  ctx.part(names.bust, ao(world.bust));
+  ctx.part(names.head, ao(world.head));
+  const sway = o.jawSway ?? 0;
+  ctx.part(names.jaw, local(world.jaw, hinge, occJaw), {
+    at: hinge,
+    ...(sway > 0
+      ? { motion: { kind: 'sway', axis: [0, 1, 0], degrees: sway, hz: 0.5 }, clearOf: [names.head] }
+      : {}),
+  });
+  ctx.part(names.eyeL, local(world.eye_l, eyeL), { at: eyeL });
+  ctx.part(names.eyeR, local(world.eye_r, eyeR), { at: eyeR });
+  return { parts: names, height: (l.crown - l.base) * H, params: p };
+}