@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/recipes/material_swatches/README.md

@@ -0,0 +1,21 @@
+# Material swatches — the trim sheet on a test board
+
+## Identity
+Not a real-world object: a labelled board that shows every strip and cell of the shared
+procedural trim sheet (`paintTrimSheet`, `DEFAULT_SHEET`), each at true scale. It is the visual
+test of the material generator: if a strip's brick courses, plank widths or slate rows read
+wrong here, they read wrong on every asset.
+
+## Specs
+| Item | Value | Source |
+|---|---|---|
+| strip panel | 2 m wide × the strip's design height | `src/material/trim-sheet.ts` `scaleMetres` |
+| decal / foliage cell | 1 m | `src/material/trim-sheet.ts` |
+| strips | plain, brick, stone, slate, iron, wood, glass, concrete | `StripId` |
+
+## Parts
+One static board: front plinth (8 strips), raised rear plinth (6 decal + 11 foliage cells),
+block-letter labels at LOD0.
+
+## Open questions
+None. Build with `--sheet embed` to see textures in a stock viewer.

package/recipes/material_swatches/material_swatches.ts

@@ -0,0 +1,189 @@
+// Material swatches: every trim-sheet strip and cell on a labelled panel — the visual test of the
+// procedural material generator. Front plinth: the 8 strips, each a 2 m wide panel as tall as the
+// strip's design height (`DEFAULT_SHEET` scaleMetres), so one panel face = one strip rect at true
+// scale, tinted by a representative vertex colour. Rear, raised plinth: the 6 decal cells and the
+// 11 foliage cells (cutout leaf cards standing on their anchor), 1 m each. Labels are block
+// letters (3×5 font, merged pixel runs) on the plinth faces, LOD0 only.
+// Export with `--sheet` (or `toGlb(a, { sheet: paintTrimSheet() })`) to see the textures; the
+// contact sheet is vertex colour only.
+
+import {
+  box,
+  type CellId,
+  cellRect,
+  DECAL_CELLS,
+  DEFAULT_SHEET,
+  defineAsset,
+  FOLIAGE_CELLS,
+  hex,
+  type Mesh,
+  MeshBuilder,
+  merge,
+  NATURAL,
+  STRIPS,
+  type StripId,
+  type Vec3,
+} from '@developerz.ai/ts23d';
+
+const STONE = hex('#9c968c');
+const INK = hex('#1c1c1c');
+const TINT: Readonly<Partial<Record<StripId, Vec3>>> = {
+  plain: hex('#e8e4dc'),
+  brick: hex('#9a4a32'),
+  stone: hex('#c8bba0'),
+  slate: hex('#4a5058'),
+  iron: hex('#3f4a3a'),
+  wood: hex('#8a6440'),
+  glass: hex('#9fc0d0'),
+  concrete: hex('#a7a39b'),
+};
+
+// 3×5 glyphs, one 3-bit row per entry, top row first (bit 4 = left column).
+const FONT: Readonly<Record<string, readonly number[]>> = {
+  a: [2, 5, 7, 5, 5],
+  b: [6, 5, 6, 5, 6],
+  c: [3, 4, 4, 4, 3],
+  d: [6, 5, 5, 5, 6],
+  e: [7, 4, 6, 4, 7],
+  f: [7, 4, 6, 4, 4],
+  g: [3, 4, 5, 5, 3],
+  h: [5, 5, 7, 5, 5],
+  i: [7, 2, 2, 2, 7],
+  j: [1, 1, 1, 5, 2],
+  k: [5, 5, 6, 5, 5],
+  l: [4, 4, 4, 4, 7],
+  m: [5, 7, 7, 5, 5],
+  n: [6, 5, 5, 5, 5],
+  o: [2, 5, 5, 5, 2],
+  p: [6, 5, 6, 4, 4],
+  q: [2, 5, 5, 6, 3],
+  r: [6, 5, 6, 5, 5],
+  s: [3, 4, 2, 1, 6],
+  t: [7, 2, 2, 2, 2],
+  u: [5, 5, 5, 5, 7],
+  v: [5, 5, 5, 5, 2],
+  w: [5, 5, 7, 7, 5],
+  x: [5, 5, 2, 5, 5],
+  y: [5, 5, 2, 2, 2],
+  z: [7, 1, 2, 4, 7],
+};
+
+/**
+ * Block-letter label on a +X-facing plane at x = `faceX`, centred on `y`, baseline at `z`,
+ * reading along +Y (a viewer at +X). Horizontal pixel runs merge into one box each.
+ */
+function label(text: string, faceX: number, y: number, z: number, px: number): Mesh {
+  const parts: Mesh[] = [];
+  const chars = [...text.replace(/_/g, ' ')];
+  const width = chars.length * 4 * px - px;
+  chars.forEach((ch, i) => {
+    const rows = FONT[ch];
+    if (!rows) return;
+    const left = y - width / 2 + i * 4 * px;
+    rows.forEach((bits, r) => {
+      let c = 0;
+      while (c < 3) {
+        if (!((bits >> (2 - c)) & 1)) {
+          c++;
+          continue;
+        }
+        let run = 0;
+        while (c + run < 3 && (bits >> (2 - c - run)) & 1) run++;
+        parts.push(
+          box({
+            size: [0.004, run * px, px],
+            at: [faceX + 0.002, left + (c + run / 2) * px, z + (4 - r) * px],
+            color: INK,
+            omit: ['back'],
+          }),
+        );
+        c += run;
+      }
+    });
+  });
+  return merge(parts);
+}
+
+/** A +X-facing quad mapping one cell rect: left→right = u0→u1 along +Y, bottom→top = v0→v1. */
+function cellQuad(id: CellId, x: number, y: number, z: number, size: number, color: Vec3): Mesh {
+  const r = cellRect(id);
+  const b = new MeshBuilder();
+  const n: Vec3 = [1, 0, 0];
+  const h = size / 2;
+  const v = (dy: number, dz: number, u: number, w: number): number =>
+    b.vertex({ p: [x, y + dy, z + dz], n, uv: [u, w], color });
+  b.quad(
+    v(-h, 0, r.u0, r.v0),
+    v(h, 0, r.u1, r.v0),
+    v(h, size, r.u1, r.v1),
+    v(-h, size, r.u0, r.v1),
+  );
+  return b.build();
+}
+
+const FRONT = { x: 0, depth: 1.2, height: 0.2, gap: 0.4 };
+const REAR = { x: -1.6, depth: 1.2, height: 1.4, gap: 0.15 };
+
+export const material_swatches = defineAsset({
+  name: 'material_swatches',
+  kind: 'prop',
+  description:
+    'Every trim-sheet strip and cell on labelled panels: the material generator test card.',
+  // 24 strip panels (library v2) + decal and foliage cells.
+  budget: { triangles: [24000, 1200, 800] },
+  build(ctx) {
+    const stripSpan = STRIPS.length * 2 + (STRIPS.length - 1) * FRONT.gap;
+    const cells: readonly CellId[] = [...DECAL_CELLS, ...FOLIAGE_CELLS];
+    const cellSpan = cells.length + (cells.length - 1) * REAR.gap;
+    const span = Math.max(stripSpan, cellSpan) + 0.4;
+    ctx.part(
+      'plinth_front',
+      box({ size: [FRONT.depth, span, FRONT.height], at: [FRONT.x, 0, 0], color: STONE }),
+    );
+    ctx.part(
+      'plinth_rear',
+      box({ size: [REAR.depth, span, REAR.height], at: [REAR.x, 0, 0], color: STONE }),
+    );
+    const frontFace = FRONT.x + FRONT.depth / 2;
+    const rearFace = REAR.x + REAR.depth / 2;
+
+    STRIPS.forEach((id, i) => {
+      const y = -stripSpan / 2 + 1 + i * (2 + FRONT.gap);
+      const h = DEFAULT_SHEET.strips[id]?.scaleMetres ?? 1;
+      const panel = box({
+        size: [0.06, 2, h],
+        at: [FRONT.x, y, FRONT.height],
+        color: TINT[id] ?? NATURAL,
+        strip: id,
+      });
+      ctx.part(`strip_${id}`, panel, id === 'glass' ? { surface: 'glass' } : {});
+      if (ctx.lod === 0) ctx.part(`label_${id}`, label(id, frontFace, y, 0.04, 0.024));
+    });
+
+    cells.forEach((id, i) => {
+      const y = -cellSpan / 2 + 0.5 + i * (1 + REAR.gap);
+      const foliage = id.startsWith('foliage_');
+      if (foliage) {
+        // A leaf card standing on its anchor edge, white so the painted colour reads true.
+        ctx.part(`cell_${id}`, cellQuad(id, REAR.x, y, REAR.height, 1, [1, 1, 1]), {
+          surface: 'cutout',
+        });
+      } else {
+        const back = box({
+          size: [0.06, 1, 1],
+          at: [REAR.x, y, REAR.height],
+          color: TINT.plain ?? NATURAL,
+        });
+        ctx.part(
+          `cell_${id}`,
+          merge([back, cellQuad(id, REAR.x + 0.032, y, REAR.height, 1, TINT.plain ?? NATURAL)]),
+        );
+      }
+      if (ctx.lod === 0)
+        ctx.part(
+          `label_${id}`,
+          label(id.replace('foliage_', ''), rearFace, y, REAR.height - 0.12, 0.016),
+        );
+    });
+  },
+});

package/recipes/mountain_range/README.md

@@ -0,0 +1,45 @@
+# Mountain range — 2 × 2 km alpine map tile (Northern Alps type)
+
+## Identity
+A game-map terrain tile, not a landmark: one glacial (U-shaped) valley crossing a 2 × 2 km block,
+flanked by ridged massifs whose summits carry snow. What makes it read as *alpine* rather than
+"noise hills": **sharp ridgelines with smooth valley floors** (ridged multifractal), **gullies and
+debris fans carved by water** (hydraulic erosion), **cliff bands capped at a talus angle** (thermal
+erosion), and **altitude zonation**: conifer forest on the valley floor, alpine meadow above the
+treeline, bare rock on anything steep, snow above the snowline wherever the slope can hold it.
+Three seeded variants (`mountain_range`, `_b`, `_c`) show the seed + valley-heading parameters.
+
+## Specs
+All values are general alpine figures cited from prior knowledge, **not re-fetched in this session
+(unsourced / approximate)**; the coordinator may attach sources.
+
+| Quantity | Value | Used as | Source |
+|---|---|---|---|
+| tile size | 2000 × 2000 m | `rect` | design choice (map tile) |
+| valley floor altitude (N. Alps, glacial valleys) | 1000–1800 m | measured 1853 / 1751 / 1775 m | unsourced, approximate |
+| summit altitude (in a 2 km tile around such a valley) | 2500–3200 m | measured 2702 / 2714 / 2773 m | unsourced, approximate |
+| local relief valley → ridge over ~1 km | 700–1200 m | ~950 m | unsourced; more than ~1000 m/km makes mean slopes > 45° |
+| treeline (Alps, conifers: spruce, larch, Swiss pine) | 1800–2200 m | 2000 m | unsourced, approximate |
+| climatic snowline (Alps, summer; lower on north faces, early season) | 2600–3200 m; patches to ~2300 m in June | 2480 m (early-summer look; variant c 2550 m) | unsourced, approximate |
+| angle of repose of scree / talus | 30–40° (≈ 34° typical) | thermal `talus` 1.0 (45°) caps cliffs, scree colour on 11–24° deposit fans | unsourced, approximate |
+| slope where bare rock dominates | > ~40° | `rockSlope` 0.85 (40°) | unsourced, approximate |
+| slope above which snow rarely holds | ~50–55° | `snowSlope` 1.2 (50°) | unsourced, approximate |
+| typical valley-side slope | 25–35° | measured (LOD0 normals): median 36° / 40° / 43° (variants a / b / c), p95 ≈ 65° | unsourced, approximate |
+
+Units: metres, Z up. z = altitude − 1650 m (the `DATUM`), so the tile stands on z = 0 with a
+skirt ~100 m below the lowest valley point.
+
+## Photos (by view)
+To be added (no web access in this session). Look-alikes to compare against: the Lauterbrunnen and
+Grindelwald valleys (U-shaped glacial troughs), the Zillertal Alps, Dolomites screes for debris fans.
+
+## Parts the engine needs
+`terrain` (one mesh, one draw call): heightfield + skirt. LOD by grid density: 256 / 128 / 64 cells.
+
+## Open questions
+- Snowline: a summer climatic snowline (~2800 m) would leave these summits bare; we chose an
+  early-summer look (2480 m) so the tile shows the snow band. Raise `snowline` for late summer.
+- Real alpine tiles of 2 km rarely hold a full valley-to-summit section; relief is compressed
+  (~950 m) to keep slopes plausible at this size. Even so the median slope (36–43°) is steeper
+  than typical valley sides (25–35°): the ridged noise gives knife-edge crests. Lower `relief` or
+  the ridged `gain` for gentler, Pre-Alps terrain.

package/recipes/mountain_range/mountain_range.ts

@@ -0,0 +1,128 @@
+// Mountain range: a 2 × 2 km alpine map tile. Numbers and their caveats: README.md (dossier).
+//
+// Pipeline, all seeded from ctx.rng (three variants = three seeds + valley headings):
+//   1. masses — ridged multifractal (sharp ridgelines, smooth lows) domain-warped so ranges fold,
+//      over a U-shaped glacial trough along `valley`, plus low fBm hills.
+//   2. erosion on one 256² grid shared by every LOD — hydraulic droplets carve gullies and drop
+//      fans, then thermal erosion caps cliffs at 45°.
+//   3. colour — forest below the treeline, meadow above, rock on steep ground, scree on fans, damp
+//      gullies, snow above the snowline where the slope holds it.
+//   4. mesh — heightfield at 256 / 128 / 64 cells by LOD, sampling the eroded grid, with a skirt
+//      down to z = 0 (a solid tile). One part, one draw call.
+
+import {
+  type BuildContext,
+  defineFamily,
+  fbm,
+  gradientNoise2,
+  heightfield,
+  hex,
+  hydraulicErosion,
+  ridged,
+  sampler,
+  terrainColor,
+  terrainGrid,
+  thermalErosion,
+  warp,
+} from '@developerz.ai/ts23d';
+
+/** Altitude (m above sea level) of z = 0. */
+const DATUM = 1650;
+const HALF = 1000;
+const RECT = [-HALF, -HALF, HALF, HALF] as const;
+
+const PALETTE = {
+  forest: hex('#2f4a2a'),
+  grass: hex('#6f8a45'),
+  scree: hex('#8a8272'),
+  rock: hex('#5a5652'),
+  snow: hex('#f2f4f7'),
+  wet: hex('#4a4a3c'),
+};
+
+interface Params {
+  /** Unit direction of the main valley in plan. */
+  readonly valley: readonly [number, number];
+  /** Valley floor and ridge relief, m. */
+  readonly floor: number;
+  readonly relief: number;
+  readonly treeline: number;
+  readonly snowline: number;
+  /** Hydraulic droplets on the 257² grid (~2 per point carves strongly). */
+  readonly droplets: number;
+}
+
+function build(ctx: BuildContext, p: Readonly<Params>): void {
+  const rng = ctx.rng;
+  const [vx, vy] = p.valley;
+  const wx = fbm(gradientNoise2(rng.fork('warp-x')), { scale: 900, octaves: 3 });
+  const wy = fbm(gradientNoise2(rng.fork('warp-y')), { scale: 900, octaves: 3 });
+  const range = warp(
+    ridged(gradientNoise2(rng.fork('range')), { scale: 1700, octaves: 6, gain: 0.35 }),
+    wx,
+    wy,
+    350,
+  );
+  const hills = fbm(gradientNoise2(rng.fork('hills')), { scale: 700, octaves: 5 });
+  const altitude = (x: number, y: number): number => {
+    // Distance across the valley axis, meandering by up to 300 m; U-shaped trough profile.
+    const along = x * vx + y * vy;
+    const across = -x * vy + y * vx - 300 * wx(along * 0.7, 0);
+    const d = Math.min(1, (across / 450) ** 2);
+    return p.floor + p.relief * range(x, y) * (0.2 + 0.8 * d) + 60 * hills(x, y) + 120 * d;
+  };
+  let grid = terrainGrid({ rect: RECT, cells: 256, height: (x, y) => altitude(x, y) - DATUM });
+  grid = hydraulicErosion(grid, rng.fork('erosion'), { droplets: p.droplets });
+  grid = thermalErosion(grid, { talus: 1, iterations: 25 });
+  const color = terrainColor(grid, {
+    palette: PALETTE,
+    datum: DATUM,
+    treeline: p.treeline,
+    snowline: p.snowline,
+    rockSlope: 0.85,
+    snowSlope: 1.2,
+    noise: fbm(gradientNoise2(rng.fork('jitter')), { scale: 120, octaves: 3 }),
+    jitter: 70,
+  });
+  const cells = ctx.pick([256, 128, 64]);
+  ctx.part(
+    'terrain',
+    heightfield({
+      rect: RECT,
+      cells: [cells, cells],
+      height: sampler(grid),
+      color,
+      skirt: 0,
+      skirtColor: hex('#5a4a3a'),
+    }),
+  );
+}
+
+export const mountainRange = defineFamily<Params>({
+  kind: 'terrain',
+  description:
+    '2 × 2 km alpine map tile: eroded ridges, a glacial valley, forest, meadow, rock and snow bands.',
+  tags: ['terrain', 'landscape', 'alpine', 'erosion', 'map'],
+  budget: { triangles: [140000, 40000, 10000] },
+  defaults: {
+    valley: [1, 0],
+    floor: 1720,
+    relief: 950,
+    treeline: 2000,
+    snowline: 2480,
+    droplets: 100000,
+  },
+  build,
+});
+
+export const mountain_range = mountainRange.variant({ name: 'mountain_range', seed: 1 });
+export const mountain_range_b = mountainRange.variant({
+  name: 'mountain_range_b',
+  seed: 2,
+  params: { valley: [0.8, 0.6] },
+});
+export const mountain_range_c = mountainRange.variant({
+  name: 'mountain_range_c',
+  seed: 3,
+  params: { valley: [0.6, -0.8], relief: 1050, snowline: 2550 },
+});

package/recipes/oak/README.md

@@ -0,0 +1,30 @@
+# Oak — English oak (*Quercus robur*), mature open-grown specimen
+
+## Identity
+A parkland/field oak rather than a forest-grown one: open-grown oaks are as wide as they are tall,
+which is the silhouette people recognise. Signature features: a **short, massive bole** (1–1.5 m)
+that splits low into **several thick, sinuous, near-horizontal limbs**; a **broad domed crown**;
+dense dark-green foliage in lobed clusters; a buttressed root flare.
+
+## Specs
+| Dimension | Value (m) | Source |
+|---|---|---|
+| height (mature) | 22 (range 20–40) | https://en.wikipedia.org/wiki/Quercus_robur · https://www.woodlandtrust.org.uk/trees-woods-and-wildlife/british-trees/a-z-of-british-trees/english-oak/ |
+| crown spread | 22 (open-grown ≈ height) | Woodland Trust (above): "broad, spreading crown" |
+| trunk diameter at breast height (1.3 m) | 1.3 (girth ≈ 4.1 m; Wikipedia gives 4–12 m girth for mature trees) | Wikipedia (above) |
+| crown base (clear bole) | ≈ 4 m | photo-estimated |
+
+## Photos (by view)
+| View | URL | Notes |
+|---|---|---|
+| side, open-grown | https://commons.wikimedia.org/wiki/Category:Quercus_robur_(habitus) | crown ≈ as wide as tall |
+| bole + limbs | https://commons.wikimedia.org/wiki/Category:Quercus_robur_trunks | low split, sinuous limbs |
+| leaves | https://commons.wikimedia.org/wiki/Category:Quercus_robur_leaves | lobed outline → `lobed` card |
+
+## Parts the engine needs
+`trunk`, `roots` (flare), `crown` (sway group, 2° @ 0.4 Hz about X) › `branches`, `leaves`.
+
+## Open questions
+Sizes vary enormously with age and site (20–40 m). We model a ~150-year field oak at 22 × 22 m with
+1.3 m DBH. Sources were cited from prior knowledge and not re-fetched in this session; re-check the
+numbers if a specific specimen is wanted.

package/recipes/oak/oak.ts

@@ -0,0 +1,19 @@
+// English oak (Quercus robur), open-grown mature specimen: 22 m tall, crown as wide as it is tall,
+// 1.3 m trunk at breast height (≈ 4.1 m girth). Spreading crooked limbs, lobed leaf clusters,
+// buttressed root flare. The `tree` kind does the botany; this file is the spec. recipes/oak/README.md.
+
+import { treeReal, trees } from '@developerz.ai/ts23d';
+
+const size = { height: 22, spread: 22, dbh: 1.3 };
+
+export const oak = trees.variant({
+  name: 'oak',
+  description:
+    'English oak (Quercus robur), mature open-grown: broad domed crown on a short thick bole',
+  sources: [
+    'https://en.wikipedia.org/wiki/Quercus_robur (20–40 m; trunk girth 4–12 m)',
+    'https://www.woodlandtrust.org.uk/trees-woods-and-wildlife/british-trees/a-z-of-british-trees/english-oak/ (mature height 20–40 m, broad spreading crown)',
+  ],
+  real: treeReal({ ...size, source: 'recipes/oak/README.md' }),
+  params: { species: 'oak', ...size },
+});

package/recipes/orc_head/README.md

@@ -0,0 +1,78 @@
+# Orc warrior bust — original stylised design
+
+## Identity
+A brutish orc warlord, read from the 3/4 view by: a **hunched brute silhouette** (trapezius sloping
+from behind the ears to the shoulders, the neck nearly as wide as the head), a **massive
+underbitten jaw** with **lower tusks rising outside the upper lip**, a **heavy brow shelf** (a
+flattened bar with a glabella knot, scowling down at the centre) shadowing **small deep-set ember
+eyes**, a **flat broad nose**, **cheekbone ridges** running back to swept **pointed ears**, a **bound
+warrior's knot** falling to the nape, war paint, **pectorals and deltoids** on the bare chest, and
+**spiked plate pauldrons** (a domed cap and a shingled lame, hollow shells with worn bright rims)
+over a **fur mantle** — cut as a collectible bust on a turned plinth.
+
+## Design spec (head units: 1 = chin to crown = 0.30 m, ≈ 1.3 × human)
+| Feature | Value (units) | Metres | Note |
+|---|---|---|---|
+| chin → crown | 1.00 | 0.300 | the `height` param |
+| overall bust L × W × H | — | 0.405 × 0.660 × 0.587 | `real`, ±5 %; length includes the knot's tail |
+| cranium width / depth / above eye line | 0.70 / 0.74 / 0.31 | 0.21 / 0.22 / 0.09 | low, sloped dome: the face is the mass |
+| eye line | 0.56 | — | higher than human: the jaw is the mass |
+| eyeball radius / spacing | 0.054 / 0.155 | 0.016 / pupils 0.093 apart | `measures` gate, ±2 % |
+| brow ridge / overhang / scowl | 0.075 / 0.06 / 0.04 | | a shelf, not two bumps |
+| jaw half-width at angle / chin | 0.40 / 1.3 | 0.120 | human 0.22; square rounded-box chin |
+| muzzle (prognathism) / underbite / chin drop | 0.10 / 0.10 / 0.10 | | lower lip thickens with the underbite |
+| tusks length / base radius | 0.22 / 0.055 | 0.066 / 0.017 | 3 cone segments from the lower lip, flared |
+| neck radius | 0.38 | 0.114 | |
+| shoulders (half-span) / mass | 1.00 / 1 | 0.300 | `bust.mass` 1 = brute: torso lifted (hunch), thick traps |
+| plinth | 0.17 + hunch | ≈ 0.08 | disc + socle; cut faces painted plinth stone |
+
+## Palette (sRGB)
+| Role | Hex |
+|---|---|
+| skin / shade / lips | `#5c8034` / `#33501e` / `#4f6f30` (painted tone: crevices darker, tops warmer) |
+| eyes: sclera / iris (+ emissive glow `#ff7a1a` × 2.5) | `#8a5a1a` / `#ffb030` |
+| tusks + bone spikes | `#e2d6b0` |
+| hair (warrior's knot) / fur mantle (strands alternate ×0.72) | `#231a14` / `#5e4a34` |
+| war paint (cheek claw marks, crest stripe, chin stripes) | `#8a1c12` |
+| pauldron iron (cap ×1, lame ×0.85, worn rims ×1.3, rivets ×1.35, crest ×0.75) / leather baldric | `#55524d` / `#5a3a22` |
+| plinth / cut faces | `#6f6c6c` (linear 0.16, 0.15, 0.15) / ×1.3 |
+
+## Parts the engine needs
+| Part | Pivot | Motion |
+|---|---|---|
+| `bust` | origin, base on z = 0 | static |
+| `head` | origin | static (skull, neck, ears, hair) |
+| `jaw` | jaw hinge (in front of the ear), opens about +Y | static by default; `head(ctx, { jawSway: 4 })` bakes a sway with `clearOf: ['head']` |
+| `eye_l`, `eye_r` | eyeball centres, gaze +X | static; rotate them to aim |
+
+The jaw region is the chin + lower lip (an ellipsoid cut flat at the mouth line), so its seam runs
+along the lips, the marionette lines and under the chin. Its cut faces are painted mouth-dark for
+when it opens; it laps 0.75 cells over the head so no gap shows.
+
+## LODs
+Sculpt cell = 2 % / 4.5 % / 14 % of head height (bust 1.6 ×). LOD0/1 bake vertex AO across all
+parts (16/10 rays); every LOD carries the painted tone (cavity, warm top, cool under). LOD1/2 drop
+the teeth and tongue; LOD2 drops warts, wiry tufts and the AO bake, floors ear/tusk/nose radii at
+about a cell, makes the pauldron plates solid and the plinth one drum so nothing opens or floats.
+
+## References (stylised anatomy, not likeness)
+| Topic | Link | Used for |
+|---|---|---|
+| Loomis head: eye line at half height, brow/nose/chin thirds | https://finearttutorials.com/guide/loomis-method/ | human eye line 0.5, nose base 0.32, mouth 0.22 |
+| Proportions of the head (ears between brow and nose base, head ≈ 5 eyes wide) | https://artyfactory.com/portraits/pencil-portraits/proportions-of-a-head.html | ear placement, eye size vs head width |
+| Primary → secondary → tertiary forms (block brow/cheek/jaw first, then cut lids and folds) | https://www.creativebloq.com/how-to/how-to-sculpt-and-pose-a-cartoon-head-in-zbrush | the edit order in `head-face.ts` |
+| Orc: widen head and jawline to break human proportion; sculpt bony forms (cheekbones) early | https://www.creativebloq.com/3d/how-create-orc-zbrush-61411834 | orc jaw width 0.40 vs human 0.22, zygomatic ridge |
+| Stylised bust method: primary → secondary → tertiary shapes | https://cgzen.gumroad.com/l/stylized-bust | torso masses before gear |
+| Stylised orc head study (silhouette, form language) | https://blenderartists.org/t/orc-head-study-stylized-characters/1655542 | massing check |
+| Stylised hair: large clumps first, hairline → crown, one primary flow direction | https://gamesartist.co.uk/curly-hair-ls/ · https://www.cgchannel.com/2023/03/tutorial-creating-stylized-hairstyles-using-zbrush | `swept` locks in head-hair.ts |
+| Dreams (Media Molecule, Evans, SIGGRAPH 2015): sculptures as ordered SDF edits + smooth-min | https://www.mediamolecule.com/blog/article/siggraph_2015 · slides https://advances.realtimerendering.com/s2015/AlexEvans_SIGGRAPH-2015-sml.pdf | the whole approach |
+
+Design is original: no character, logo, name or likeness from any game is copied. "Chunky
+hand-painted stylised fantasy" is the idiom (exaggerated primary forms, generous fillets, flat
+vertex colour with baked AO), not a specific source.
+
+## Known gaps
+Pauldron plates are smooth shells (no hammered dents or scratches); fur strands are cones, not
+noise-broken clumps; no skin pores or wrinkle noise; the jaw part's seam still shows as a faint
+line round the chin up close; the bust's U-cut leaves the belly reading slightly pear-shaped from
+dead front.

package/recipes/orc_head/orc_head.ts

@@ -0,0 +1,41 @@
+// Stylised orc warrior bust — an original design in the chunky hand-painted fantasy idiom: massive
+// underbitten jaw with lower tusks rising outside the upper lip, a heavy brow shelf over small ember
+// eyes, flat broad nose, swept ears, a bound warrior's knot, war paint; a hunched brute torso
+// (trapezius from ear to shoulder, pectorals, deltoids) under spiked plate pauldrons and a fur
+// mantle, cut as a collectible bust on a turned plinth. The `head` kind sculpts it (race preset
+// `orc`, chin to crown 0.30 m); this file is the spec.
+// Design dossier: recipes/orc_head/README.md.
+
+import { defineAsset, head, hex } from '@developerz.ai/ts23d';
+
+export const orc_head = defineAsset({
+  name: 'orc_head',
+  kind: 'character',
+  description:
+    'Stylised orc warrior bust on a plinth: underbite and lower tusks, heavy brow, ember eyes, warrior knot, hunched trapezius, spiked plate pauldrons, fur mantle',
+  tags: ['character', 'fantasy', 'orc', 'bust', 'sculpt'],
+  license: 'CC0-1.0',
+  sources: ['recipes/orc_head/README.md (design dossier: proportions, palette, references)'],
+  // Design spec, not a real-world one: overall bust size and eye spacing from the dossier.
+  real: {
+    length: 0.405,
+    width: 0.66,
+    height: 0.587,
+    measures: [
+      {
+        label: 'eye spacing (pupil to pupil)',
+        value: 0.093,
+        axis: 'y',
+        between: ['eye_l', 'eye_r'],
+        source: '0.155 × 2 head units × 0.30 m',
+      },
+    ],
+  },
+  // Measured: sculpt cells 2 % / 4.5 % / 14 % of head height (LOD0/1 also bake vertex AO).
+  budget: { triangles: [77000, 15400, 2000] },
+  // Ember eyes: the whole eyeball glows (dark amber sclera, bright iris).
+  glow: [{ parts: ['eye_*'], color: hex('#ff7a1a'), strength: 2.5 }],
+  build(ctx) {
+    head(ctx, { race: 'orc' });
+  },
+});

package/recipes/palm/README.md

@@ -0,0 +1,30 @@
+# Palm — coconut palm (*Cocos nucifera*), mature
+
+## Identity
+The tall variety, typical of beaches. Signature features: a **slender, ringed, bowed stem** of
+nearly constant diameter, slightly swollen at the base; a **starburst crown of ~20–30 pinnate
+fronds** whose leaflets hang in a V and whose lower fronds droop below horizontal; and **coconuts
+clustered under the frond bases**.
+
+## Specs
+| Dimension | Value (m) | Source |
+|---|---|---|
+| height | 20 (up to 30) | https://en.wikipedia.org/wiki/Coconut |
+| stem diameter | 0.35 (typical 0.3–0.4) | https://en.wikipedia.org/wiki/Cocos_nucifera · photo-estimated |
+| frond length | 4–6 (model: ≈ 5.2) | Wikipedia "Coconut": "pinnate leaves 4–6 m long" |
+| crown spread | 9 (≈ 2 × horizontal frond reach) | derived from frond length and droop |
+| fronds | 22 (live crown holds ~25–30) | Wikipedia (above) |
+
+## Photos (by view)
+| View | URL | Notes |
+|---|---|---|
+| habit | https://commons.wikimedia.org/wiki/Category:Cocos_nucifera_(habitus) | bowed stem, crown back over the base |
+| crown detail | https://commons.wikimedia.org/wiki/Category:Cocos_nucifera_leaves | V-folded leaflets |
+
+## Parts the engine needs
+`trunk`, `roots` (root plate), `crown` (sway) › `branches` (rachises + coconuts), `leaves` (leaflets).
+
+## Open questions
+The stem bows (lean 12°, curving back by 24°) so the crown sits back over the base and the
+footprint stays at the crown spread; strongly leaning shoreline palms would also need `real.length`
+widened. Sources were cited from prior knowledge and not re-fetched in this session.

package/recipes/palm/palm.ts

@@ -0,0 +1,19 @@
+// Coconut palm (Cocos nucifera), mature: 20 m bowed stem of 0.35 m, ~22 pinnate fronds 4–6 m
+// long forming a 9 m crown, a hand of coconuts under the frond bases. The `tree` kind does the
+// botany; this file is the spec. recipes/palm/README.md.
+
+import { treeReal, trees } from '@developerz.ai/ts23d';
+
+const size = { height: 20, spread: 9, dbh: 0.35 };
+
+export const palm = trees.variant({
+  name: 'palm',
+  description:
+    'Coconut palm (Cocos nucifera): slender bowed ringed stem, crown of drooping pinnate fronds',
+  sources: [
+    'https://en.wikipedia.org/wiki/Coconut (up to 30 m; pinnate leaves 4–6 m long)',
+    'https://en.wikipedia.org/wiki/Cocos_nucifera',
+  ],
+  real: treeReal({ ...size, source: 'recipes/palm/README.md' }),
+  params: { species: 'palm', ...size },
+});

package/recipes/pine/README.md

@@ -0,0 +1,29 @@
+# Pine — Scots pine (*Pinus sylvestris*), mature
+
+## Identity
+The mature form, not the conical sapling. A sapling would read as a generic Christmas-tree conifer;
+an old Scots pine is unmistakable. Signature features: a **long, clean, slightly sinuous bole**
+(the crown sits in the top ~40%); bark that is **grey-brown and plated low down and turns
+orange-red higher up**; a **flat-topped, irregular crown**; **dark blue-green needle pads lying
+level** on gently upturned branch tips.
+
+## Specs
+| Dimension | Value (m) | Source |
+|---|---|---|
+| height (mature) | 25 (range 25–35) | https://en.wikipedia.org/wiki/Pinus_sylvestris |
+| trunk diameter at breast height | 0.6 (up to 1 m) | Wikipedia (above) |
+| crown spread | 9 (typical 6–12) | https://www.woodlandtrust.org.uk/trees-woods-and-wildlife/british-trees/a-z-of-british-trees/scots-pine/ · photo-estimated |
+| clear bole | ≈ 15 m (crown base at ~60% of height) | photo-estimated |
+
+## Photos (by view)
+| View | URL | Notes |
+|---|---|---|
+| habit, mature | https://commons.wikimedia.org/wiki/Category:Pinus_sylvestris_(habitus) | flat top, high crown |
+| upper bark | https://commons.wikimedia.org/wiki/Category:Pinus_sylvestris_bark | orange flaking bark → `barkTop` |
+
+## Parts the engine needs
+`trunk`, `roots`, `crown` (sway) › `branches`, `leaves`.
+
+## Open questions
+Crown spread is not given in most floras. 9 m is estimated from photos of mature open-grown trees.
+Sources were cited from prior knowledge and not re-fetched in this session.

package/recipes/pine/pine.ts

@@ -0,0 +1,19 @@
+// Scots pine (Pinus sylvestris), mature: 25 m tall, 9 m crown in the top half, 0.6 m DBH. Long
+// clean bole turning orange-red up high, flat-topped crown, dark blue-green needle tufts on
+// upturned branch tips. The `tree` kind does the botany; this file is the spec. recipes/pine/README.md.
+
+import { treeReal, trees } from '@developerz.ai/ts23d';
+
+const size = { height: 25, spread: 9, dbh: 0.6 };
+
+export const pine = trees.variant({
+  name: 'pine',
+  description:
+    'Scots pine (Pinus sylvestris), mature: tall bare bole, orange upper bark, high flat-topped crown',
+  sources: [
+    'https://en.wikipedia.org/wiki/Pinus_sylvestris (up to 35 m tall, trunk up to 1 m diameter; orange upper bark)',
+    'https://www.woodlandtrust.org.uk/trees-woods-and-wildlife/british-trees/a-z-of-british-trees/scots-pine/ (mature 35 m; flat-topped crown in age)',
+  ],
+  real: treeReal({ ...size, source: 'recipes/pine/README.md' }),
+  params: { species: 'pine', ...size },
+});