@developerz.ai/ts23d 0.0.0-stage → 0.1.0

package/src/kinds/vegetation-presets.ts

@@ -0,0 +1,184 @@
+// Species presets: plain `TreeParams` objects — spread one and override what you need
+// (`{ ...oak, leaves: { ...oak.leaves, color: hex('#7a8a2a') } }` is an autumn oak).
+// `typical` sizes are mature open-grown trees; sources in each comment and in recipes/<name>/README.md.
+
+import { hex } from '../material/index.ts';
+import type { TreeParams } from './vegetation-params.ts';
+
+/** Quercus robur (English oak): 20–25 m, crown about as wide; girth 4–12 m. Spreading, crooked limbs. */
+export const oak: TreeParams = {
+  shape: 'hemispherical',
+  baseSize: 0.3,
+  ratioPower: 1.15,
+  taper: 0.3,
+  levels: [
+    { branches: 0, length: 0.55, downAngle: 0, curveVar: 5, segments: 8 },
+    {
+      branches: 8,
+      length: 0.95,
+      downAngle: 58,
+      downAngleV: -18,
+      curve: -8,
+      curveVar: 16,
+      segments: 7,
+    },
+    { branches: 6, length: 0.55, downAngle: 50, curve: 12, curveVar: 18, start: 0.2, segments: 4 },
+    { branches: 5, length: 0.5, downAngle: 45, curveVar: 14, start: 0.15, segments: 2 },
+  ],
+  bark: hex('#4a4036'),
+  barkTop: hex('#5a5045'),
+  leaves: {
+    shape: 'lobed',
+    size: 1.7,
+    width: 0.8,
+    perStem: 5,
+    color: hex('#3d6022'),
+    colorVar: 0.16,
+  },
+  roots: 5,
+  impostor: 'blob',
+  typical: { height: 22, spread: 22, dbh: 1.3 },
+};
+
+/** Pinus sylvestris (Scots pine): 25–35 m, DBH up to 1 m; long clean bole, orange upper bark,
+ * flat-topped crown in the top third, dark blue-green needle tufts on upturned tips. */
+export const pine: TreeParams = {
+  shape: 'cylindrical',
+  baseSize: 0.6,
+  ratioPower: 1.2,
+  taper: 0.12,
+  levels: [
+    { branches: 0, length: 0.94, downAngle: 0, curveVar: 3, segments: 10 },
+    {
+      branches: 13,
+      length: 0.34,
+      downAngle: 94,
+      downAngleV: -14,
+      curve: 16,
+      curveVar: 14,
+      segments: 5,
+    },
+    { branches: 5, length: 0.42, downAngle: 60, curve: 18, curveVar: 14, start: 0.3, segments: 3 },
+  ],
+  bark: hex('#4a3a30'),
+  barkTop: hex('#c0652c'),
+  leaves: {
+    shape: 'tuft',
+    size: 2.1,
+    width: 0.95,
+    perStem: 5,
+    from: 0.5,
+    flat: 0.8,
+    color: hex('#24422e'),
+    colorVar: 0.1,
+  },
+  roots: 4,
+  impostor: 'blob',
+  typical: { height: 25, spread: 9, dbh: 0.6 },
+};
+
+/** Cocos nucifera (coconut palm): up to 30 m; single ringed stem 30–40 cm; 4–6 m pinnate fronds. */
+export const palm: TreeParams = {
+  shape: 'cylindrical',
+  baseSize: 0.95,
+  ratioPower: 1.1,
+  taper: 0.7,
+  lean: 12,
+  levels: [
+    { branches: 0, length: 1, downAngle: 0, curve: 24, curveVar: 1.5, segments: 12 },
+    {
+      branches: 22,
+      length: 0.26,
+      downAngle: 115,
+      downAngleV: -85,
+      rotate: 137.5,
+      curve: -55,
+      curveVar: 4,
+      segments: 8,
+    },
+  ],
+  bark: hex('#6b5d4a'),
+  barkTop: hex('#8a7a62'),
+  leaves: {
+    shape: 'frond',
+    size: 0,
+    width: 0.2,
+    perStem: 26,
+    color: hex('#4f7a2a'),
+    colorVar: 0.12,
+  },
+  roots: 9,
+  fruit: { count: 7, radius: 0.13, color: hex('#5f6a22') },
+  impostor: 'cards',
+  typical: { height: 20, spread: 9, dbh: 0.35 },
+};
+
+/** Betula pendula (silver birch): 15–25 m, narrow crown, white bark with black marks, weeping twigs. */
+export const birch: TreeParams = {
+  shape: 'flame',
+  baseSize: 0.3,
+  ratioPower: 1.4,
+  taper: 0.1,
+  levels: [
+    { branches: 0, length: 1, downAngle: 0, curveVar: 3, segments: 10 },
+    {
+      branches: 22,
+      length: 0.32,
+      downAngle: 45,
+      downAngleV: 10,
+      curve: -25,
+      curveVar: 8,
+      segments: 4,
+    },
+    { branches: 5, length: 0.55, downAngle: 30, curve: -45, curveVar: 10, start: 0.2, segments: 3 },
+  ],
+  bark: hex('#d9d6cc'),
+  barkMarks: { color: hex('#24221f'), amount: 0.12 },
+  leaves: {
+    shape: 'oval',
+    size: 0.8,
+    width: 0.7,
+    perStem: 4,
+    color: hex('#6f9a32'),
+    colorVar: 0.15,
+  },
+  impostor: 'blob',
+  typical: { height: 18, spread: 8, dbh: 0.4 },
+};
+
+/** Salix babylonica (weeping willow): 10–15 m, wider than tall; long hanging leafy strands. */
+export const willow: TreeParams = {
+  shape: 'hemispherical',
+  baseSize: 0.25,
+  ratioPower: 1.7,
+  taper: 0.35,
+  levels: [
+    { branches: 0, length: 0.55, downAngle: 0, curveVar: 5, segments: 6 },
+    {
+      branches: 8,
+      length: 0.95,
+      downAngle: 42,
+      curve: 40,
+      curveBack: -70,
+      curveVar: 8,
+      segments: 6,
+    },
+    { branches: 7, length: 0.55, downAngle: 35, curve: -80, curveVar: 8, start: 0.3, segments: 4 },
+  ],
+  bark: hex('#4f463a'),
+  leaves: {
+    shape: 'strand',
+    size: 2.6,
+    width: 0.22,
+    perStem: 4,
+    color: hex('#8aa83e'),
+    colorVar: 0.12,
+    hang: 0.92,
+  },
+  roots: 6,
+  impostor: 'blob',
+  typical: { height: 12, spread: 14, dbh: 0.8 },
+};
+
+export const SPECIES = { oak, pine, palm, birch, willow } as const;
+export type SpeciesName = keyof typeof SPECIES;

package/src/kinds/vegetation-skeleton.ts

@@ -0,0 +1,168 @@
+// The botanical skeleton: Weber–Penn recursive stems as plain polylines + radii. Always grown at
+// full depth and LOD0 resolution from one seeded stream, so every LOD is the same tree; meshing
+// decides what to emit. Children start inside their parent (centre offset r_parent − r_child along
+// the attachment normal), so each one physically grows out of the bark.
+
+import type { Rng, Vec3 } from '../core/index.ts';
+import { arcLengths, transportFrames } from '../primitives/index.ts';
+import { type BranchLevel, shapeRatio, type TreeParams } from './vegetation-params.ts';
+
+export interface Stem {
+  readonly level: number;
+  readonly pts: readonly Vec3[];
+  readonly radii: readonly number[];
+  readonly length: number;
+  /** Index of the parent stem, −1 for the trunk. */
+  readonly parent: number;
+  /** Attachment point on the parent's bark (cluster cards root here at LOD1). */
+  readonly surface: Vec3;
+  /** Nominal length before shape/variation: drives the child count. */
+  readonly maxLength: number;
+}
+
+const deg = Math.PI / 180;
+const unit = (a: Vec3): Vec3 => {
+  const l = Math.hypot(a[0], a[1], a[2]) || 1;
+  return [a[0] / l, a[1] / l, a[2] / l];
+};
+
+/** Rodrigues rotation of v about unit axis k by angle a (radians). */
+export function rotate(v: Vec3, k: Vec3, a: number): Vec3 {
+  const c = Math.cos(a);
+  const s = Math.sin(a);
+  const d = (k[0] * v[0] + k[1] * v[1] + k[2] * v[2]) * (1 - c);
+  return [
+    v[0] * c + (k[1] * v[2] - k[2] * v[1]) * s + k[0] * d,
+    v[1] * c + (k[2] * v[0] - k[0] * v[2]) * s + k[1] * d,
+    v[2] * c + (k[0] * v[1] - k[1] * v[0]) * s + k[2] * d,
+  ];
+}
+
+/** Axis that turns `dir` towards +Z when rotated by a positive angle. */
+function upAxis(dir: Vec3): Vec3 {
+  const k: Vec3 = [dir[1], -dir[0], 0]; // dir × Z
+  return Math.hypot(k[0], k[1]) < 1e-4 ? [0, 1, 0] : unit(k);
+}
+
+/** A stem's polyline: `res` segments, bending by curve/curveBack plus seeded wobble. */
+function path(start: Vec3, dir0: Vec3, len: number, lv: BranchLevel, trunk: boolean, rng: Rng) {
+  const res = Math.max(1, lv.segments);
+  const step = len / res;
+  const pts: Vec3[] = [start];
+  let dir = dir0;
+  let p = start;
+  for (let i = 0; i < res; i++) {
+    const half = lv.curveBack !== undefined && i >= res / 2;
+    const bend = half
+      ? (lv.curveBack ?? 0) / Math.ceil(res / 2)
+      : (lv.curve ?? 0) / (lv.curveBack !== undefined ? Math.max(1, Math.floor(res / 2)) : res);
+    const wob = lv.curveVar ?? 0;
+    // The trunk stays in the XZ plane and bends about Y: + curve swings it back against the lean
+    // (−X), so a leaning palm bows and its crown comes back over its base.
+    if (trunk) dir = rotate(dir, [0, 1, 0], -(bend + rng.range(-wob, wob)) * deg);
+    else {
+      dir = rotate(dir, upAxis(dir), (bend + rng.range(-wob, wob)) * deg);
+      dir = rotate(dir, [0, 0, 1], rng.range(-wob, wob) * deg);
+    }
+    dir = unit(dir);
+    p = [p[0] + dir[0] * step, p[1] + dir[1] * step, p[2] + dir[2] * step];
+    pts.push(p);
+  }
+  return pts;
+}
+
+export function grow(p: TreeParams, size: { height: number; dbh: number }, rng: Rng): Stem[] {
+  const t0 = p.levels[0];
+  if (!t0) return [];
+  const L0 = size.height * t0.length;
+  const r0 = size.dbh / 2;
+  const lean = (p.lean ?? 0) * deg;
+  const trunkPts = path([0, 0, -0.05], [Math.sin(lean), 0, Math.cos(lean)], L0, t0, true, rng);
+  const arc0 = arcLengths(trunkPts);
+  const bh = 1.3; // breast height, metres (forestry DBH convention)
+  const trunkR = arc0.map((s) => {
+    const f = Math.max(0, (s - bh) / Math.max(0.1, L0 - bh));
+    return r0 * (1 - (1 - p.taper) * f);
+  });
+  const stems: Stem[] = [
+    {
+      level: 0,
+      pts: trunkPts,
+      radii: trunkR,
+      length: L0,
+      parent: -1,
+      surface: [0, 0, 0],
+      maxLength: L0,
+    },
+  ];
+  for (let si = 0; si < stems.length; si++) {
+    const par = stems[si];
+    const lv = par ? p.levels[par.level + 1] : undefined;
+    if (!par || !lv) continue;
+    const arc = arcLengths(par.pts);
+    const frames = transportFrames(par.pts);
+    const s0 = (par.level === 0 ? p.baseSize : (lv.start ?? 0.1)) * par.length;
+    const s1 = par.length * 0.97;
+    const fill = par.level === 0 ? 1 : Math.min(1, par.length / par.maxLength);
+    const n = par.level === 0 ? lv.branches : Math.round(lv.branches * (0.25 + 0.75 * fill));
+    let phi = rng.range(0, 360);
+    for (let i = 0; i < n; i++) {
+      const s = s0 + ((s1 - s0) * (i + rng.range(0.15, 0.85))) / Math.max(1, n);
+      let j = 0;
+      while (j < arc.length - 2 && (arc[j + 1] ?? 0) < s) j++;
+      const a = par.pts[j] ?? [0, 0, 0];
+      const b = par.pts[j + 1] ?? a;
+      const f = (s - (arc[j] ?? 0)) / ((arc[j + 1] ?? 1) - (arc[j] ?? 0) || 1);
+      const c: Vec3 = [
+        a[0] + (b[0] - a[0]) * f,
+        a[1] + (b[1] - a[1]) * f,
+        a[2] + (b[2] - a[2]) * f,
+      ];
+      const rp = (par.radii[j] ?? 0) * (1 - f) + (par.radii[j + 1] ?? 0) * f;
+      const T = unit([b[0] - a[0], b[1] - a[1], b[2] - a[2]]);
+      const fr = frames[j] ?? { n: [1, 0, 0], b: [0, 1, 0] };
+      phi += (lv.rotate ?? 137.5) + rng.range(-10, 10);
+      const cp = Math.cos(phi * deg);
+      const sp = Math.sin(phi * deg);
+      const raw: Vec3 = [
+        cp * fr.n[0] + sp * fr.b[0],
+        cp * fr.n[1] + sp * fr.b[1],
+        cp * fr.n[2] + sp * fr.b[2],
+      ];
+      const tdot = raw[0] * T[0] + raw[1] * T[1] + raw[2] * T[2];
+      const np = unit([raw[0] - tdot * T[0], raw[1] - tdot * T[1], raw[2] - tdot * T[2]]);
+      const zone = (s - s0) / Math.max(1e-6, s1 - s0);
+      const down = (lv.downAngle + (lv.downAngleV ?? 0) * zone + rng.range(-5, 5)) * deg;
+      const dir = unit([
+        T[0] * Math.cos(down) + np[0] * Math.sin(down),
+        T[1] * Math.cos(down) + np[1] * Math.sin(down),
+        T[2] * Math.cos(down) + np[2] * Math.sin(down),
+      ]);
+      const vary = 1 + rng.range(-(lv.lengthVar ?? 0.15), lv.lengthVar ?? 0.15);
+      const maxLength = lv.length * par.length;
+      const base =
+        par.level === 0
+          ? maxLength * shapeRatio(p.shape, (par.length - s) / Math.max(1e-6, par.length - s0))
+          : lv.length * (par.length - 0.6 * s);
+      const len = Math.max(0.15, base * vary);
+      const r0c = par.radii[0] ?? rp;
+      const rc = Math.max(0.006, Math.min(0.8 * rp, r0c * (len / par.length) ** p.ratioPower));
+      const start: Vec3 = [
+        c[0] + np[0] * (rp - rc),
+        c[1] + np[1] * (rp - rc),
+        c[2] + np[2] * (rp - rc),
+      ];
+      const pts = path(start, dir, len, lv, false, rng);
+      stems.push({
+        level: par.level + 1,
+        pts,
+        radii: pts.map((_, k) => rc * (1 - (0.75 * k) / Math.max(1, pts.length - 1))),
+        length: len,
+        parent: si,
+        surface: [c[0] + np[0] * rp, c[1] + np[1] * rp, c[2] + np[2] * rp],
+        maxLength,
+      });
+    }
+  }
+  return stems;
+}

package/src/kinds/vegetation.ts

@@ -0,0 +1,199 @@
+// Vegetation kind: `tree(ctx, …)` grows a Weber–Penn skeleton from species params and emits a
+// game tree — `trunk`, `roots` (buttress flare), and a swaying group `crown` holding `branches`
+// (merged) and `leaves` (merged cards) — then fits it onto its real height and crown spread.
+// LOD policy: LOD0 every level and every leaf card; LOD1 one level fewer (trees with ≥ 3 levels),
+// halved path resolution, twigs replaced by cluster cards; LOD2 an impostor under 300 triangles.
+
+import {
+  BUDGETS,
+  type BuildContext,
+  defineFamily,
+  type Mesh,
+  merge,
+  type RealDimensions,
+  Ts23dError,
+  translate,
+  triangleCount,
+  type Vec3,
+} from '../core/index.ts';
+import { frondLeaflets, fruit } from './vegetation-fronds.ts';
+import { blob, frondCards } from './vegetation-impostor.ts';
+import { clusterCards, crownShade, leafCards } from './vegetation-leaves.ts';
+import {
+  barkTint,
+  fitFactors,
+  radialSegments,
+  rootsMesh,
+  scaleMesh,
+  stemsMesh,
+  trunkMesh,
+} from './vegetation-mesh.ts';
+import type { TreeParams } from './vegetation-params.ts';
+import { SPECIES } from './vegetation-presets.ts';
+import { grow } from './vegetation-skeleton.ts';
+
+export interface TreeOptions {
+  /** A preset name (`oak`, `pine`, `palm`, `birch`, `willow`) or a full parameter set. */
+  readonly species?: string | TreeParams;
+  /** Overrides on top of the species. */
+  readonly params?: Partial<TreeParams>;
+  /** Total height, metres (ground to crown top). */
+  readonly height: number;
+  /** Crown spread (X and Y), metres. Default: the species' typical ratio to height. */
+  readonly spread?: number;
+  /** Trunk diameter at breast height (1.3 m), metres. Default: the species' typical ratio. */
+  readonly dbh?: number;
+  readonly seed?: number;
+  /** Part-name prefix: `oak_3` → `oak_3_trunk`, `oak_3_crown`, … */
+  readonly prefix?: string;
+}
+
+export interface TreeInfo {
+  readonly parts: { trunk: string; crown: string; branches: string; leaves: string; roots: string };
+  readonly height: number;
+  readonly spread: number;
+  readonly dbh: number;
+}
+
+export function treeParams(o: Pick<TreeOptions, 'species' | 'params'>): TreeParams {
+  const s = o.species ?? 'oak';
+  const base = typeof s === 'string' ? SPECIES[s as keyof typeof SPECIES] : s;
+  if (!base) {
+    throw new Ts23dError('T3D_RECIPE_INVALID', {
+      cause: `unknown tree species '${String(s)}'`,
+      fix: `use one of ${Object.keys(SPECIES).join(', ')} or pass a TreeParams object (spread a preset and override)`,
+    });
+  }
+  return { ...base, ...o.params };
+}
+
+export function tree(ctx: BuildContext, o: TreeOptions): TreeInfo {
+  const p = treeParams(o);
+  if (!(o.height > 0) || p.levels.length < 2 || p.levels.length > 4) {
+    throw new Ts23dError('T3D_RECIPE_INVALID', {
+      cause: `tree height ${o.height} m with ${p.levels.length} branch levels`,
+      fix: 'height must be > 0 and levels must hold the trunk plus 1–3 branch levels',
+    });
+  }
+  const k = o.height / p.typical.height;
+  const spread = o.spread ?? p.typical.spread * k;
+  const dbh = o.dbh ?? p.typical.dbh * k;
+  const pre = o.prefix ? `${o.prefix}_` : '';
+  const parts = {
+    trunk: `${pre}trunk`,
+    crown: `${pre}crown`,
+    branches: `${pre}branches`,
+    leaves: `${pre}leaves`,
+    roots: `${pre}roots`,
+  };
+  const rng = ctx.rng.fork(`tree:${o.prefix ?? ''}:${o.seed ?? 0}`);
+  const stems = grow(p, { height: o.height, dbh }, rng.fork('skeleton'));
+  const trunkStem = stems[0];
+  if (!trunkStem) return { parts, height: o.height, spread, dbh };
+  const deepest = p.levels.length - 1;
+  const lod = ctx.lod;
+  const top = trunkStem.pts[trunkStem.pts.length - 1]?.[2] ?? o.height;
+  const shade = crownShade(stems, 1);
+  let trunk: (r: number) => Mesh;
+  let roots: ((r: number) => Mesh) | null = null;
+  let branches: Mesh | null = null;
+  let leaves: Mesh;
+  if (lod === 2) {
+    const imp =
+      p.impostor === 'cards' ? frondCards(stems, p, 1) : blob(stems, p, rng.fork('impostor'));
+    trunk = () => barkTint(imp.trunk, p, top, rng.fork('bark'));
+    leaves = imp.leaves;
+  } else {
+    const hi = lod === 0 || deepest < 2 ? deepest : deepest - 1;
+    trunk = (r) => trunkMesh(trunkStem, p, lod, r, rng.fork('bark'));
+    if (p.roots) roots = (r) => rootsMesh(trunkStem, p, lod, r, rng.fork('roots'));
+    const wood = [
+      barkTint(stemsMesh(stems, 1, hi, lod, p.bark), p, top, rng.fork('bark:branches')),
+    ];
+    if (p.fruit && lod === 0)
+      wood.push(fruit(trunkStem, p.baseSize - 0.01, p.fruit, rng.fork('fruit')));
+    branches = merge(wood);
+    const lr = rng.fork('leaves');
+    leaves =
+      p.leaves.shape === 'frond'
+        ? frondLeaflets(
+            stems,
+            deepest,
+            p.leaves,
+            lod === 0 ? p.leaves.perStem : Math.ceil(p.leaves.perStem / 2),
+            shade,
+            lr,
+          )
+        : hi === deepest
+          ? leafCards(stems, deepest, radialSegments(deepest, lod), p.leaves, shade, lr)
+          : clusterCards(stems, deepest, p.leaves, shade, lr);
+  }
+  // Fit onto the real envelope; the trunk is rebuilt thinner by 1/sy so DBH (across Y) is exact.
+  const s = fitFactors(
+    [trunk(1), branches, leaves, roots?.(1) ?? null].filter((m): m is Mesh => m !== null),
+    [spread, spread, o.height],
+  );
+  const fit = (m: Mesh): Mesh => scaleMesh(m, s);
+  const base = trunkStem.pts[Math.round(p.baseSize * (trunkStem.pts.length - 1))] ?? [0, 0, 0];
+  const pivot: Vec3 = [base[0] * s[0], base[1] * s[1], base[2] * s[2]];
+  const back: Vec3 = [-pivot[0], -pivot[1], -pivot[2]];
+  ctx.part(parts.trunk, fit(trunk(1 / s[1])));
+  if (roots) ctx.part(parts.roots, fit(roots(1 / s[1])));
+  ctx.group(parts.crown, {
+    at: pivot,
+    motion: { kind: 'sway', axis: [1, 0, 0], degrees: 2, hz: 0.4 },
+    // The crown grows out of the trunk: they meet by design, and the clash gate's conservative
+    // full-turn sway volume would otherwise flag the wood that holds it.
+    clearOf: roots ? [parts.trunk, parts.roots] : [parts.trunk],
+  });
+  if (branches && triangleCount(branches) > 0)
+    ctx.part(parts.branches, translate(fit(branches), back), { parent: parts.crown });
+  ctx.part(parts.leaves, translate(fit(leaves), back), { parent: parts.crown });
+  return { parts, height: o.height, spread, dbh };
+}
+
+/** `real` for a tree recipe: overall envelope plus DBH (trunk across Y) and total height. */
+export function treeReal(o: {
+  height: number;
+  spread: number;
+  dbh: number;
+  prefix?: string;
+  source?: string;
+}): RealDimensions {
+  const pre = o.prefix ? `${o.prefix}_` : '';
+  const src = o.source ? { source: o.source } : {};
+  return {
+    length: o.spread,
+    width: o.spread,
+    height: o.height,
+    measures: [
+      {
+        label: 'trunk diameter at breast height',
+        value: o.dbh,
+        axis: 'y',
+        parts: [`${pre}trunk`],
+        ...src,
+      },
+      {
+        label: 'total height',
+        value: o.height,
+        axis: 'z',
+        parts: [`${pre}trunk`, `${pre}crown`, `${pre}branches`, `${pre}leaves`, `${pre}roots`],
+        ...src,
+      },
+    ],
+  };
+}
+
+export type TreeFamilyParams = Omit<TreeOptions, 'prefix'>;
+
+/** One family, many species: `trees.variant({ name: 'oak', params: { species: 'oak', height: 22 } })`. */
+export const trees = defineFamily<TreeFamilyParams>({
+  kind: 'vegetation',
+  tags: ['vegetation', 'tree'],
+  budget: BUDGETS.tree,
+  defaults: { species: 'oak', height: 22 },
+  build: (ctx, p) => {
+    tree(ctx, p);
+  },
+});

package/src/kinds/vehicle.ts

@@ -0,0 +1,144 @@
+// Vehicle helpers: wheels that spin, tracks, propellers. Named parts follow the engine contract:
+// `axle_*` and `wheel_*` spin about local Y, `prop_*`/`rotor_*` spin about their own axis.
+
+import { type BuildContext, place, type Vec3 } from '../core/index.ts';
+import { parseWhyte } from '../grammar/index.ts';
+import { box, cylinder } from '../primitives/index.ts';
+
+const segs = (ctx: BuildContext, hi: number): number => [hi, Math.max(8, hi / 2), 6][ctx.lod] ?? 6;
+
+/** A pair of wheels on one spinning axle. */
+export function axle(
+  ctx: BuildContext,
+  o: {
+    name: string;
+    at: Vec3;
+    radius: number;
+    gauge: number;
+    width: number;
+    color: Vec3;
+    rps: number;
+  },
+): void {
+  ctx.group(o.name, { at: o.at, motion: { kind: 'spin', axis: [0, 1, 0], rps: o.rps } });
+  for (const [s, y] of [
+    ['l', o.gauge / 2],
+    ['r', -o.gauge / 2],
+  ] as const) {
+    ctx.part(
+      `${o.name}_wheel_${s}`,
+      cylinder({
+        radius: o.radius,
+        length: o.width,
+        segments: segs(ctx, 24),
+        axis: 'y',
+        at: [0, y, 0],
+        color: o.color,
+        strip: 'iron',
+      }),
+      { parent: o.name },
+    );
+  }
+}
+
+/** Lays out wheel groups from a Whyte arrangement along X; returns axle x-positions per role. */
+export function whyteAxles(
+  arrangement: string,
+  o: { leading: number; driving: number; trailing: number; spacing: number },
+): { role: string; x: number; radius: number }[] {
+  const groups = parseWhyte(arrangement);
+  const out: { role: string; x: number; radius: number }[] = [];
+  let x = 0;
+  for (const g of groups) {
+    const r = g.role === 'driving' ? o.driving : g.role === 'leading' ? o.leading : o.trailing;
+    for (let i = 0; i < g.count / 2; i++) {
+      out.push({ role: g.role, x: x + r, radius: r });
+      x += r * 2 + o.spacing;
+    }
+  }
+  const mid = x / 2;
+  // Front (+X) is the leading end.
+  return out.map((a) => ({ ...a, x: mid - a.x }));
+}
+
+/** One side of a tracked running gear: road wheels (spinning) + a flat track loop. */
+export function trackRun(
+  ctx: BuildContext,
+  o: {
+    side: 'l' | 'r';
+    y: number;
+    length: number;
+    wheels: number;
+    radius: number;
+    width: number;
+    color: Vec3;
+    track: Vec3;
+  },
+): void {
+  const pitch = o.length / o.wheels;
+  for (let i = 0; i < o.wheels; i++) {
+    const x = -o.length / 2 + pitch * (i + 0.5);
+    ctx.part(
+      `road_wheel_${o.side}_${i}`,
+      cylinder({
+        radius: o.radius,
+        length: o.width * 0.8,
+        segments: segs(ctx, 20),
+        axis: 'y',
+        at: [0, 0, 0],
+        color: o.color,
+        strip: 'iron',
+      }),
+      { at: [x, o.y, o.radius + 0.06], motion: { kind: 'spin', axis: [0, 1, 0], rps: -0.6 } },
+    );
+  }
+  const t = 0.06;
+  ctx.part(
+    `track_${o.side}_bottom`,
+    box({
+      size: [o.length + o.radius, o.width, t],
+      at: [0, o.y, 0],
+      color: o.track,
+      strip: 'iron',
+    }),
+  );
+  ctx.part(
+    `track_${o.side}_top`,
+    box({
+      size: [o.length, o.width, t],
+      at: [0, o.y, o.radius * 2 + 0.06],
+      color: o.track,
+      strip: 'iron',
+    }),
+  );
+}
+
+/** A propeller hub + blades that spin about X (nose direction). */
+export function propeller(
+  ctx: BuildContext,
+  o: { name: string; at: Vec3; radius: number; blades: number; color: Vec3; parent?: string },
+): void {
+  ctx.group(o.name, {
+    at: o.at,
+    ...(o.parent ? { parent: o.parent } : {}),
+    motion: { kind: 'spin', axis: [1, 0, 0], rps: 6 },
+  });
+  ctx.part(
+    `${o.name}_hub`,
+    cylinder({
+      radius: o.radius * 0.12,
+      length: o.radius * 0.3,
+      segments: segs(ctx, 12),
+      axis: 'x',
+      color: o.color,
+    }),
+    { parent: o.name },
+  );
+  // One blade built pointing up (+Z) from the hub, then rolled about the spin axis per blade.
+  const blade = box({ size: [0.03, o.radius * 0.12, o.radius], color: o.color });
+  for (let i = 0; i < o.blades; i++) {
+    ctx.part(`${o.name}_blade_${i}`, place(blade, { roll: (i / o.blades) * Math.PI * 2 }), {
+      parent: o.name,
+    });
+  }
+}