@developerz.ai/ts23d 0.0.0-stage → 0.1.0

package/src/kinds/head-hair.ts

@@ -0,0 +1,152 @@
+// Scalp hair as edit lists, part of the skull field: a top-knot, mohawk ridge, chunky swept locks
+// over a cap clipped at the hairline, wiry tufts, braids. Beards and eyebrows: head-beard.ts.
+// Head units, mirrored across Y unless an edit opts out.
+
+import type { Vec3 } from '../core/index.ts';
+import type { SculptEdit } from '../primitives/index.ts';
+import { alongZ } from './head-geom.ts';
+import type { HeadLayout } from './head-layout.ts';
+import type { HeadParams } from './head-params.ts';
+
+const RAD = Math.PI / 180;
+
+export function hairEdits(p: HeadParams, l: HeadLayout): SculptEdit[] {
+  const h = p.colors.hair;
+  const [cx, , cz] = l.cranium.at;
+  const [rx, ry, rz] = l.cranium.r;
+  const top = l.crown;
+  switch (p.hair) {
+    case 'topknot':
+      return [
+        { shape: 'ellipsoid', at: [cx - 0.12, 0, top - 0.02], size: [0.11, 0.08, 0.07], color: h },
+        {
+          shape: 'sphere',
+          at: [cx - 0.16, 0, top + 0.07],
+          size: 0.075,
+          color: h,
+          blend: 0.03,
+        },
+        {
+          shape: 'capsule',
+          at: [cx - 0.2, 0, top + 0.08],
+          to: [cx - 0.42, 0, top - 0.25],
+          size: 0.04,
+          color: h,
+          blend: 0.04,
+        },
+        {
+          shape: 'torus',
+          at: [cx - 0.17, 0, top + 0.02],
+          size: [0.06, 0.018],
+          color: p.colors.metal,
+        },
+      ];
+    case 'mohawk':
+      return Array.from({ length: 6 }, (_, i): SculptEdit => {
+        const a = (-20 + i * 26) * RAD;
+        return {
+          shape: 'ellipsoid',
+          at: [cx + Math.sin(a) * rx * 0.95, 0, cz + Math.cos(a) * rz * 0.97],
+          size: [0.06, 0.035, 0.09],
+          rotate: [0, (a * 180) / Math.PI - 15, 0],
+          color: h,
+          blend: 0.03,
+        };
+      });
+    case 'swept': {
+      // Cap clipped to a rounded hairline (face and ears carved out), then big tapered locks
+      // sweeping back from the hairline — thick roots proud, tips sunk — in two shades.
+      const C: Vec3 = [cx - 0.04, 0, cz + 0.04];
+      const R: Vec3 = [rx + 0.035, ry + 0.04, rz + 0.02];
+      const on = (az: number, el: number, lift = 0): Vec3 => [
+        C[0] + (R[0] + lift) * Math.cos(el * RAD) * Math.cos(az * RAD),
+        C[1] + (R[1] + lift) * Math.cos(el * RAD) * Math.sin(az * RAD),
+        C[2] + (R[2] + lift) * Math.sin(el * RAD),
+      ];
+      const light: Vec3 = [h[0] * 1.45, h[1] * 1.45, h[2] * 1.45];
+      // A lock hugs the cap: two tapering cones root → mid → tip, mid on the surface.
+      const cone = (a: Vec3, b: Vec3, r0: number, r1: number): SculptEdit => ({
+        shape: 'cone',
+        at: a,
+        size: [r0, r1, Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2])],
+        rotate: alongZ([b[0] - a[0], b[1] - a[1], b[2] - a[2]]),
+      });
+      const lock = (az: number, el: number, len: number, r: number, i: number): SculptEdit => {
+        const a = on(az, el, -0.005);
+        const m = on(az + len * 0.3, el - len * 0.45, -0.012);
+        const b = on(az + len * 0.6, el - len, -0.045);
+        return {
+          group: [cone(a, m, r, r * 0.75), cone(m, b, r * 0.75, r * 0.15)],
+          color: i % 2 ? h : light,
+          blend: 0.035,
+          ...(az === 0 ? { mirror: false } : {}),
+        };
+      };
+      return [
+        {
+          group: [
+            { shape: 'ellipsoid', at: C, size: R },
+            {
+              shape: 'ellipsoid',
+              at: [l.faceX + 0.12, 0, l.eye[2] - 0.08],
+              size: [0.34, ry * 0.92, 0.36],
+              op: 'subtract',
+              blend: 0.03,
+            },
+            {
+              shape: 'ellipsoid',
+              at: [cx + 0.02, ry, l.eye[2] - 0.08],
+              size: [0.13, 0.25, 0.16],
+              op: 'subtract',
+              blend: 0.03,
+            },
+          ],
+          color: h,
+          blend: 0.012,
+        },
+        lock(0, 44, 50, 0.07, 1),
+        lock(22, 46, 50, 0.07, 0),
+        lock(45, 40, 45, 0.068, 1),
+        lock(70, 34, 40, 0.06, 0),
+        lock(95, 30, 35, 0.055, 1),
+        lock(120, 30, 30, 0.05, 0),
+      ];
+    }
+    case 'tufts':
+      return Array.from({ length: 5 }, (_, i): SculptEdit => {
+        const a = (i / 4 - 0.5) * 1.6;
+        const base: Vec3 = [cx - 0.1 + Math.cos(a) * 0.05, Math.sin(a) * 0.12, top - 0.04];
+        return {
+          shape: 'cone',
+          at: base,
+          size: [0.025, 0.004, 0.12 + (i % 2) * 0.05],
+          rotate: alongZ([-0.6, Math.sin(a) * 0.8, 1]),
+          color: h,
+          blend: 0.01,
+          mirror: false,
+        };
+      });
+    case 'braids':
+      return [
+        { ...capOf(l, h) },
+        {
+          shape: 'capsule',
+          at: [cx - 0.2, ry * 0.7, cz - 0.1],
+          to: [cx - 0.1, ry * 0.8, cz - 0.6],
+          size: 0.035,
+          color: h,
+          blend: 0.02,
+        },
+      ];
+    default:
+      return [];
+  }
+}
+
+const capOf = (l: HeadLayout, h: Vec3): SculptEdit => ({
+  shape: 'ellipsoid',
+  at: [l.cranium.at[0] - 0.07, 0, l.cranium.at[2] + 0.09],
+  size: [l.cranium.r[0] + 0.02, l.cranium.r[1] + 0.025, l.cranium.r[2]],
+  color: h,
+  blend: 0.02,
+});

package/src/kinds/head-layout.ts

@@ -0,0 +1,63 @@
+// Head landmarks from params: where the cranium, eyes, brow, nose base, mouth, chin, jaw hinge and
+// jaw angle sit, in head units (x front, y left, z up; z 0 = chin of an undropped jaw, x 0 ≈ ear
+// canal). Every edit list reads this one table, so moving the eye line moves lids, brow and nose.
+
+import type { Vec3 } from '../core/index.ts';
+import type { HeadParams } from './head-params.ts';
+
+export interface HeadLayout {
+  /** Cranium ellipsoid centre and radii. */
+  readonly cranium: { readonly at: Vec3; readonly r: Vec3 };
+  /** Forehead front at the eye line. */
+  readonly faceX: number;
+  /** Left eye centre (mirror for the right) and eyeball radius. */
+  readonly eye: Vec3;
+  readonly eyeR: number;
+  readonly browZ: number;
+  readonly noseZ: number;
+  readonly mouthZ: number;
+  /** Front of the lips. */
+  readonly mouthX: number;
+  readonly chin: Vec3;
+  /** Jaw hinge (x, z) — the jaw part's pivot. */
+  readonly hinge: readonly [number, number];
+  /** Left jaw angle (gonion). */
+  readonly angle: Vec3;
+  /** Top of the head, units. */
+  readonly crown: number;
+  /** Bottom of the bust (the asset's z = 0), units. */
+  readonly base: number;
+}
+
+export function headLayout(p: HeadParams): HeadLayout {
+  const L = p.eyes.line;
+  const crH = p.cranium.height;
+  const rx = p.cranium.depth / 2;
+  const ry = p.cranium.width / 2;
+  const rz = crH * 0.8;
+  const cx = -0.02 - p.jaw.muzzle * 0.4;
+  const cz = L + crH * 0.2;
+  const faceX = cx + rx * 0.97;
+  const jut = p.jaw.muzzle;
+  const eyeR = p.eyes.radius;
+  const eye: Vec3 = [faceX - eyeR - p.brow.overhang, p.eyes.spacing, L];
+  const noseZ = L - p.nose.length;
+  const mouthZ = noseZ - 0.1 - p.jaw.drop * 0.3;
+  const chinZ = -p.jaw.drop;
+  const mouthX = faceX - 0.01 + jut + p.jaw.underbite * 0.3;
+  return {
+    cranium: { at: [cx, 0, cz], r: [rx, ry, rz] },
+    faceX,
+    eye,
+    eyeR,
+    browZ: L + eyeR * 0.9 + p.brow.ridge * 0.6,
+    noseZ,
+    mouthZ,
+    mouthX,
+    chin: [faceX - 0.07 + jut + p.jaw.underbite, 0, chinZ + 0.07 * p.jaw.chin],
+    hinge: [cx + 0.04, L - 0.09],
+    angle: [cx - 0.02, p.jaw.width, 0.15 - p.jaw.drop * 0.6],
+    crown: cz + rz,
+    base: -0.85 - p.jaw.drop * 0.5,
+  };
+}

package/src/kinds/head-mesh.ts

@@ -0,0 +1,157 @@
+// Head edit lists → meshes. One skull field is split by the jaw cutter into `head` (skull − cut,
+// smooth-unioned with the ears) and `jaw` (skull ∩ cut, with the tusks), so the two parts share
+// the exact same outer surface; their cut faces are painted mouth-dark for when the jaw opens.
+// Eyeballs are their own spheres: sclera, iris, pupil by angle from the +X gaze.
+
+import type { Mesh, Vec3 } from '../core/index.ts';
+import { type Field, type SculptEdit, sculptField, sd, sdf } from '../primitives/index.ts';
+import type { HeadLayout } from './head-layout.ts';
+import type { HeadParams } from './head-params.ts';
+import { creaseNormals, sharpenRim } from './head-rim.ts';
+
+/** The jaw region (head units): an ellipsoid around chin and lower lip, cut flat at the mouth
+ *  line. Its skin seam runs along the lips, down the marionette lines and under the chin — creases
+ *  a face already has — instead of across the cheek. */
+export function jawRegion(
+  p: HeadParams,
+  l: HeadLayout,
+): { field: Field; centre: Vec3; radii: Vec3 } {
+  const chin = l.chin;
+  const reach = Math.max(p.mouth.width * 1.25, (p.tusks?.spread ?? 0) + p.mouth.width * 0.5);
+  const centre: Vec3 = [l.mouthX - 0.15, 0, l.mouthZ];
+  const radii: Vec3 = [Math.max(0.27, l.mouthX - chin[0] + 0.2), reach, l.mouthZ - chin[2] + 0.1];
+  const e = sd.ellipsoid(centre, radii);
+  return { field: (q) => Math.max(q[2] - l.mouthZ, e(q)), centre, radii };
+}
+
+const unionBounds = (a: readonly [Vec3, Vec3], b?: readonly [Vec3, Vec3]): [Vec3, Vec3] =>
+  b
+    ? [
+        [Math.min(a[0][0], b[0][0]), Math.min(a[0][1], b[0][1]), Math.min(a[0][2], b[0][2])],
+        [Math.max(a[1][0], b[1][0]), Math.max(a[1][1], b[1][1]), Math.max(a[1][2], b[1][2])],
+      ]
+    : [a[0], a[1]];
+
+/** The jaw region as a sculpt group (ellipsoid ∩ below the mouth line), grown by `grow`. */
+function regionGroup(l: HeadLayout, r: { centre: Vec3; radii: Vec3 }, grow: number): SculptEdit {
+  const cx = r.centre[0];
+  const [rx, ry, rz] = r.radii;
+  return {
+    group: [
+      { shape: 'ellipsoid', at: r.centre, size: [rx + grow, ry + grow, rz + grow] },
+      {
+        shape: 'roundBox',
+        at: [cx, 0, l.mouthZ + grow - 1],
+        size: [4, 4, 2],
+        op: 'intersect',
+      },
+    ],
+    mirror: false,
+    blend: 0,
+  };
+}
+
+export interface HeadEditSet {
+  readonly skull: readonly SculptEdit[];
+  readonly ears: readonly SculptEdit[];
+  readonly tusks: readonly SculptEdit[];
+  readonly bust: readonly SculptEdit[];
+}
+
+/** `head` and `jaw` meshes in head units at cell size `res` (units). Each is ONE sculpt (skull +
+ *  ears − region, skull ∩ region + tusks), so the sculpt's range skipping covers every edit. */
+export function headAndJaw(
+  p: HeadParams,
+  l: HeadLayout,
+  set: HeadEditSet,
+  res: number,
+): { head: Mesh; jaw: Mesh } {
+  const opts = { color: p.colors.skin, mirror: 'y' as const };
+  const region = jawRegion(p, l);
+  const cut = region.field;
+  // The jaw reaches a little past the cut and sits a hair proud of the skin, so it laps over the
+  // head like a lip: no gap opens along the seam where meshing leaves the two rims a cell apart.
+  const lap = res * 0.75;
+  const proud = res * 0.15;
+  const ears: SculptEdit[] = set.ears.length > 0 ? [{ group: set.ears, blend: 0.02 }] : [];
+  const tusks: SculptEdit[] = set.tusks.length > 0 ? [{ group: set.tusks, blend: 0.01 }] : [];
+  const h = sculptField(
+    [...set.skull, ...ears, { ...regionGroup(l, region, 0), op: 'subtract' }],
+    opts,
+  );
+  const jRaw = sculptField(
+    [...set.skull, { ...regionGroup(l, region, lap), op: 'intersect' }, ...tusks],
+    opts,
+  );
+  const jField: Field = (q) => jRaw.field(q) - proud;
+  const mouth = p.colors.mouth;
+  // Only the skin-only skull is needed near the cut (paint + rim snapping): evaluated lazily.
+  const skull = sculptField(set.skull, opts).field;
+  const deep = -Math.max(res * 4, 0.03);
+  const paint =
+    (colorAt: (q: Vec3) => Vec3) =>
+    (q: Vec3): Vec3 =>
+      Math.abs(cut(q)) < res * 1.5 && skull(q) < deep ? mouth : colorAt(q);
+  const [ec, er] = [region.centre, region.radii];
+  const jb: [Vec3, Vec3] = [
+    [ec[0] - er[0] - lap, -er[1] - lap, ec[2] - er[2] - lap],
+    [ec[0] + er[0] + lap, er[1] + lap, ec[2] + lap + 0.01],
+  ];
+  const tb = set.tusks.length > 0 ? sculptField(set.tusks, opts).bounds : undefined;
+  const head = sdf({
+    field: h.field,
+    bounds: h.bounds,
+    resolution: res,
+    color: paint(h.colorAt),
+    symmetry: 'y',
+  });
+  const jaw = sdf({
+    field: jField,
+    bounds: unionBounds(jb, tb),
+    resolution: res,
+    color: paint(jRaw.colorAt),
+    symmetry: 'y',
+  });
+  // Coarse cells: snapping folds triangles over, and nobody sees a seam at that distance.
+  if (res > 0.03) return { head: creaseNormals(head), jaw: creaseNormals(jaw) };
+  const jawSkull: Field = (q) => skull(q) - proud;
+  return {
+    // The head's rim lies under the jaw's lap, so only the jaw rim (the visible one) is snapped.
+    head: creaseNormals(head),
+    jaw: creaseNormals(sharpenRim(jaw, jawSkull, (q) => cut(q) - lap, jField, res)),
+  };
+}
+
+export function bustMesh(p: HeadParams, set: HeadEditSet, res: number): Mesh {
+  const s = sculptField(set.bust, { color: p.colors.skin, mirror: 'y' });
+  return sdf({
+    field: s.field,
+    bounds: s.bounds,
+    resolution: res,
+    color: (q) => s.colorAt(q),
+    symmetry: 'y',
+  });
+}
+
+/** Eyeball of radius `r` centred on the origin, gazing +X. */
+export function eyeMesh(p: HeadParams, r: number, res: number): Mesh {
+  const c = p.colors;
+  const iris = Math.cos(0.62);
+  const limbus = Math.cos(0.7);
+  const pupil = Math.cos(0.3);
+  return sdf({
+    field: (q) => Math.hypot(q[0], q[1], q[2]) - r,
+    bounds: [
+      [-r * 1.3, -r * 1.3, -r * 1.3],
+      [r * 1.3, r * 1.3, r * 1.3],
+    ],
+    resolution: res,
+    color: (q) => {
+      const cos = q[0] / (Math.hypot(q[0], q[1], q[2]) || 1);
+      if (cos > pupil) return c.pupil;
+      if (cos > iris) return c.iris;
+      if (cos > limbus) return [c.iris[0] * 0.45, c.iris[1] * 0.45, c.iris[2] * 0.45];
+      return c.sclera;
+    },
+  });
+}

package/src/kinds/head-params.ts

@@ -0,0 +1,153 @@
+// Head kind parameters: the typed knobs of a stylised head, in HEAD UNITS (1 = chin to crown of a
+// human-proportioned skull; the builder scales by `height` metres at the end), plus the guard that
+// turns an unusable set into a T3D_RECIPE_INVALID with the fix.
+
+import { Ts23dError, type Vec3 } from '../core/index.ts';
+
+export type EarShape = 'round' | 'pointed';
+export type HairStyle = 'none' | 'topknot' | 'mohawk' | 'swept' | 'tufts' | 'braids';
+export type BeardStyle = 'none' | 'short' | 'braided' | 'goatee';
+export type BustStyle = 'pauldrons' | 'hood' | 'tunic';
+
+export interface HeadColors {
+  readonly skin: Vec3;
+  /** Darker skin: lips edge, nostrils, inner ear, wrinkles. */
+  readonly shade: Vec3;
+  readonly lips: Vec3;
+  readonly sclera: Vec3;
+  readonly iris: Vec3;
+  readonly pupil: Vec3;
+  readonly teeth: Vec3;
+  readonly mouth: Vec3;
+  readonly hair: Vec3;
+  readonly cloth: Vec3;
+  readonly leather: Vec3;
+  readonly metal: Vec3;
+  /** Cloak / mantle over the shoulders; default `leather`. */
+  readonly cape?: Vec3;
+  /** Fur trim on the bust (mantle, hood lining); default `leather`. */
+  readonly fur?: Vec3;
+  /** War paint / tattoo stripes (orc), or none. */
+  readonly paint?: Vec3;
+}
+
+export interface HeadParams {
+  /** Chin to crown, metres (adult human ≈ 0.23). */
+  readonly height: number;
+  /** Full width / depth of the brain case; `height` = crown above the eye line. */
+  readonly cranium: { readonly width: number; readonly depth: number; readonly height: number };
+  /** Ridge radius, how far it juts past the eyes, and the scowl (inner ends lowered). */
+  /** Ridge radius, overhang past the eyes, scowl (inner ends lowered), eyebrow hair radius
+   *  (omit or 0 = no eyebrows). */
+  readonly brow: {
+    readonly ridge: number;
+    readonly overhang: number;
+    readonly scowl: number;
+    readonly hair?: number;
+  };
+  readonly cheeks: { readonly size: number; readonly width: number };
+  /** Half-width at the jaw angle, chin size, lower-jaw jut past the upper lip, chin drop,
+   *  muzzle (how far mouth and jaw push forward of the brow: prognathism). */
+  readonly jaw: {
+    readonly muzzle: number;
+    readonly width: number;
+    readonly chin: number;
+    readonly underbite: number;
+    readonly drop: number;
+  };
+  /** Eye line → nose base, nostril half-width, tip radius, hook (droop), bridge projection. */
+  readonly nose: {
+    readonly length: number;
+    readonly width: number;
+    readonly tip: number;
+    readonly hook: number;
+    readonly bridge: number;
+  };
+  /** Length (root → tip), width, sweep back (deg), tilt up (deg). */
+  readonly ears: {
+    readonly shape: EarShape;
+    readonly length: number;
+    readonly width: number;
+    readonly sweep: number;
+    readonly lift: number;
+  };
+  /** Eyeball radius, centre-to-midline, eye line (fraction of height), lid angles (deg). */
+  readonly eyes: {
+    readonly radius: number;
+    readonly spacing: number;
+    readonly line: number;
+    readonly lid: number;
+    readonly lowerLid: number;
+  };
+  /** Half-width, lip thickness, grin (0 = closed line, 1 = wide toothy smile). */
+  readonly mouth: { readonly width: number; readonly lips: number; readonly grin: number };
+  readonly tusks: {
+    readonly length: number;
+    readonly radius: number;
+    readonly spread: number;
+    readonly flare: number;
+  } | null;
+  readonly neck: { readonly radius: number };
+  readonly bust: { readonly shoulders: number; readonly style: BustStyle };
+  readonly hair: HairStyle;
+  readonly beard: BeardStyle;
+  /** Wart / bump count scattered on the skin (seeded). */
+  readonly warts: number;
+  readonly colors: HeadColors;
+}
+
+const bad = (cause: string, fix: string): never => {
+  throw new Ts23dError('T3D_RECIPE_INVALID', { cause, fix });
+};
+
+/** Every number in a params object, with its path, for the finite/positive sweep. */
+function numbers(o: unknown, path: string, out: Array<[string, number]>): void {
+  if (typeof o === 'number') out.push([path, o]);
+  else if (o && typeof o === 'object' && !Array.isArray(o))
+    for (const [k, v] of Object.entries(o)) numbers(v, path ? `${path}.${k}` : k, out);
+}
+
+const SIGNED = new Set([
+  'brow.scowl',
+  'jaw.underbite',
+  'nose.hook',
+  'ears.lift',
+  'ears.sweep',
+  'nose.bridge',
+]);
+const ZERO_OK = new Set([
+  'mouth.grin',
+  'warts',
+  'jaw.drop',
+  'jaw.muzzle',
+  'brow.overhang',
+  'brow.hair',
+]);
+
+/** Throws T3D_RECIPE_INVALID (with a fix) when `p` cannot make a head. */
+export function checkHead(p: HeadParams): HeadParams {
+  if (!(p.height >= 0.05 && p.height <= 3))
+    bad(`head height ${p.height} m`, 'give height in metres, chin to crown: human 0.23, orc ≈ 0.3');
+  const flat: Array<[string, number]> = [];
+  numbers({ ...p, colors: undefined, height: undefined }, '', flat);
+  for (const [k, v] of flat) {
+    if (!Number.isFinite(v)) bad(`head param ${k} is ${v}`, 'use finite numbers (head units)');
+    if (SIGNED.has(k)) continue;
+    if (v < 0 || (v === 0 && !ZERO_OK.has(k)))
+      bad(`head param ${k} is ${v}`, `make ${k} > 0 (head units: 1 = chin to crown)`);
+  }
+  const e = p.eyes;
+  if (e.line < 0.3 || e.line > 0.7)
+    bad(`eyes.line ${e.line}`, 'keep the eye line between 0.3 and 0.7 of the head height');
+  if (e.spacing < e.radius * 1.1)
+    bad(
+      `eyes.spacing ${e.spacing} < eyes.radius ${e.radius} × 1.1: the eyeballs overlap`,
+      'raise eyes.spacing (centre to midline) or shrink eyes.radius',
+    );
+  if (e.lid <= e.lowerLid * -1 || e.lid > 80)
+    bad(`eye lids ${e.lid}°/${e.lowerLid}° leave no opening`, 'use lid in (−lowerLid, 80] degrees');
+  if (p.mouth.grin > 1) bad(`mouth.grin ${p.mouth.grin}`, 'grin runs 0 (closed) … 1 (wide)');
+  if (p.tusks && p.tusks.length > 0.6)
+    bad(`tusks.length ${p.tusks.length}`, 'tusks longer than 0.6 head units read as horns');
+  return p;
+}

package/src/kinds/head-presets.ts

@@ -0,0 +1,152 @@
+// Race presets for the head kind: plain `HeadParams` data in head units (1 = chin to crown) —
+// spread one and override (`{ ...orc, tusks: null }` is a tuskless orc). Original stylised designs
+// in the chunky hand-painted fantasy idiom, not copies of any game's characters. Proportions and
+// palettes are documented per recipe in recipes/<race>_head/README.md.
+
+import { hex } from '../material/index.ts';
+import type { HeadParams } from './head-params.ts';
+
+/** Classical proportions, slightly heroic: eye line at half height, thirds brow/nose/chin. */
+export const human: HeadParams = {
+  height: 0.23,
+  cranium: { width: 0.66, depth: 0.86, height: 0.5 },
+  brow: { ridge: 0.035, overhang: 0.03, scowl: 0.012, hair: 0.018 },
+  cheeks: { size: 1, width: 1 },
+  jaw: { muzzle: 0, width: 0.22, chin: 1.05, underbite: 0, drop: 0 },
+  nose: { length: 0.18, width: 0.06, tip: 0.036, hook: 0, bridge: 0 },
+  ears: { shape: 'round', length: 0.27, width: 0.15, sweep: 12, lift: 0 },
+  eyes: { radius: 0.052, spacing: 0.135, line: 0.5, lid: 20, lowerLid: 30 },
+  mouth: { width: 0.1, lips: 0.018, grin: 0 },
+  tusks: null,
+  neck: { radius: 0.27 },
+  bust: { shoulders: 0.95, style: 'tunic' },
+  hair: 'swept',
+  beard: 'short',
+  warts: 0,
+  colors: {
+    skin: hex('#d9a07a'),
+    shade: hex('#a8644a'),
+    lips: hex('#b86b5c'),
+    sclera: hex('#ece6dc'),
+    iris: hex('#3d6e9e'),
+    pupil: hex('#141414'),
+    teeth: hex('#ece2c8'),
+    mouth: hex('#4a1a18'),
+    hair: hex('#5a3a22'),
+    cloth: hex('#2e4f8a'),
+    cape: hex('#7a2420'),
+    leather: hex('#6b4428'),
+    metal: hex('#c9a24a'),
+  },
+};
+
+/** Massive underbitten jaw, tusks, heavy brow over small deep eyes, flat broad nose, thick neck. */
+export const orc: HeadParams = {
+  height: 0.3,
+  cranium: { width: 0.7, depth: 0.8, height: 0.34 },
+  brow: { ridge: 0.065, overhang: 0.075, scowl: 0.035 },
+  cheeks: { size: 1.35, width: 1.15 },
+  jaw: { muzzle: 0.1, width: 0.37, chin: 1.6, underbite: 0.07, drop: 0.1 },
+  nose: { length: 0.15, width: 0.09, tip: 0.04, hook: -0.01, bridge: -0.045 },
+  ears: { shape: 'pointed', length: 0.3, width: 0.17, sweep: 25, lift: 8 },
+  eyes: { radius: 0.05, spacing: 0.155, line: 0.56, lid: 16, lowerLid: 26 },
+  mouth: { width: 0.17, lips: 0.03, grin: 0 },
+  tusks: { length: 0.27, radius: 0.05, spread: 0.14, flare: 0.35 },
+  neck: { radius: 0.32 },
+  bust: { shoulders: 1.05, style: 'pauldrons' },
+  hair: 'topknot',
+  beard: 'none',
+  warts: 6,
+  colors: {
+    skin: hex('#5f8b3a'),
+    shade: hex('#3c5c24'),
+    lips: hex('#4f6f30'),
+    sclera: hex('#8a5a1a'),
+    iris: hex('#ffb030'),
+    pupil: hex('#140a06'),
+    teeth: hex('#e2d6b0'),
+    mouth: hex('#2a0e0c'),
+    hair: hex('#1c1714'),
+    cloth: hex('#6b2a20'),
+    leather: hex('#5a3a22'),
+    metal: hex('#6e6a62'),
+    fur: hex('#5e4a34'),
+    paint: hex('#8a1c12'),
+  },
+};
+
+/** Small and sly: huge leaf ears, long hooked nose, wide toothy grin, big bright eyes. */
+export const goblin: HeadParams = {
+  height: 0.19,
+  cranium: { width: 0.66, depth: 0.84, height: 0.5 },
+  brow: { ridge: 0.03, overhang: 0.015, scowl: 0.025 },
+  cheeks: { size: 1.15, width: 1.1 },
+  jaw: { muzzle: 0.06, width: 0.2, chin: 0.85, underbite: 0, drop: 0 },
+  nose: { length: 0.2, width: 0.07, tip: 0.05, hook: 0.07, bridge: 0.12 },
+  ears: { shape: 'pointed', length: 0.62, width: 0.3, sweep: 22, lift: 18 },
+  eyes: { radius: 0.072, spacing: 0.15, line: 0.5, lid: 16, lowerLid: 26 },
+  mouth: { width: 0.2, lips: 0.016, grin: 0.75 },
+  tusks: null,
+  neck: { radius: 0.2 },
+  bust: { shoulders: 0.75, style: 'hood' },
+  hair: 'tufts',
+  beard: 'none',
+  warts: 4,
+  colors: {
+    skin: hex('#9cb84a'),
+    shade: hex('#6a8a2c'),
+    lips: hex('#7a8e36'),
+    sclera: hex('#f0e6a0'),
+    iris: hex('#e0a020'),
+    pupil: hex('#120c04'),
+    teeth: hex('#e8dcae'),
+    mouth: hex('#3a1010'),
+    hair: hex('#3a3024'),
+    cloth: hex('#6a4a7a'),
+    leather: hex('#5a3a22'),
+    metal: hex('#a88a4a'),
+  },
+};
+
+/** Broad and bearded: wide skull, big bulbous nose, braided beard, deep-set eyes. */
+export const dwarf: HeadParams = {
+  ...human,
+  height: 0.24,
+  cranium: { width: 0.74, depth: 0.86, height: 0.48 },
+  brow: { ridge: 0.05, overhang: 0.05, scowl: 0.02, hair: 0.024 },
+  cheeks: { size: 1.25, width: 1.1 },
+  jaw: { muzzle: 0.02, width: 0.27, chin: 1.2, underbite: 0, drop: 0.02 },
+  nose: { length: 0.2, width: 0.08, tip: 0.06, hook: 0.02, bridge: 0.02 },
+  eyes: { radius: 0.045, spacing: 0.14, line: 0.52, lid: 10, lowerLid: 24 },
+  neck: { radius: 0.34 },
+  bust: { shoulders: 1.1, style: 'tunic' },
+  hair: 'braids',
+  beard: 'braided',
+  colors: { ...human.colors, skin: hex('#d49470'), hair: hex('#8a3f1c'), cloth: hex('#4a5a2a') },
+};
+
+/** Slender and ageless: long swept-back ears, high cheekbones, fine nose, almond eyes. */
+export const elf: HeadParams = {
+  ...human,
+  height: 0.235,
+  cranium: { width: 0.62, depth: 0.86, height: 0.52 },
+  brow: { ridge: 0.025, overhang: 0.02, scowl: -0.01, hair: 0.012 },
+  cheeks: { size: 1.1, width: 1.05 },
+  jaw: { muzzle: 0, width: 0.19, chin: 0.85, underbite: 0, drop: 0 },
+  nose: { length: 0.18, width: 0.045, tip: 0.028, hook: 0, bridge: 0.01 },
+  ears: { shape: 'pointed', length: 0.42, width: 0.16, sweep: 40, lift: 24 },
+  eyes: { radius: 0.05, spacing: 0.13, line: 0.5, lid: 14, lowerLid: 22 },
+  bust: { shoulders: 0.85, style: 'tunic' },
+  hair: 'swept',
+  beard: 'none',
+  colors: {
+    ...human.colors,
+    skin: hex('#e8c0a0'),
+    hair: hex('#e0d090'),
+    iris: hex('#3a8a5a'),
+    cloth: hex('#2a6a4a'),
+  },
+};
+
+export const HEADS = { human, orc, goblin, dwarf, elf } as const;
+export type HeadPreset = keyof typeof HEADS;