@developerz.ai/ts23d 0.0.0-stage → 0.1.0

package/src/kinds/building.ts

@@ -0,0 +1,153 @@
+// Building helpers: masses, then details. A facade is a split-grammar line per floor and side;
+// `win`/`door`/`arch`/`shop` slots become openings, everything else stays wall. Plain mode: inset
+// glass/door panels. With `kit`: real openings (reveal, sill, lintel, sash, panelled door).
+
+import type { BuildContext, Vec3 } from '../core/index.ts';
+import { split } from '../grammar/index.ts';
+import type { StripId } from '../material/index.ts';
+import { box } from '../primitives/index.ts';
+import { opening } from './openings.ts';
+
+export type Side = 'front' | 'back' | 'left' | 'right';
+
+export interface FacadeOptions {
+  readonly prefix: string;
+  /** Centre of the mass's base. */
+  readonly at: Vec3;
+  /** Footprint width (X) and depth (Y) of the mass this facade wraps. */
+  readonly footprint: readonly [number, number];
+  readonly floors: number;
+  readonly floorHeight: number;
+  /** Grammar per floor; the same line for every floor unless `ground` overrides floor 0. */
+  readonly grammar: string;
+  readonly ground?: string;
+  readonly sides: readonly Side[];
+  readonly glass: Vec3;
+  readonly frame?: Vec3;
+  /** Window height as a fraction of the floor. */
+  readonly windowRatio?: number;
+  /** Detailed openings (see `opening`): reveal in the wall colour, stone sill/lintel, sash bars. */
+  readonly kit?: {
+    readonly wall: Vec3;
+    readonly trim?: Vec3;
+    readonly depth?: number;
+    readonly panes?: readonly [number, number];
+    /** The wall's strip, so reveals continue its courses. Default 'plain'. */
+    readonly strip?: StripId;
+  };
+}
+
+const OPENINGS = new Set(['win', 'door', 'arch', 'shop']);
+
+export function facade(ctx: BuildContext, o: FacadeOptions): void {
+  const [w, d] = o.footprint;
+  const ratio = o.windowRatio ?? 0.6;
+  const depth = 0.08;
+  for (const side of o.sides) {
+    const along = side === 'front' || side === 'back' ? d : w;
+    for (let f = 0; f < o.floors; f++) {
+      const line = f === 0 && o.ground ? o.ground : o.grammar;
+      const z = o.at[2] + f * o.floorHeight;
+      split(line, along).forEach((slot, i) => {
+        if (!OPENINGS.has(slot.symbol) || slot.size < 0.2) return;
+        const isDoor = slot.symbol === 'door' || slot.symbol === 'shop';
+        const h = isDoor ? o.floorHeight * 0.85 : o.floorHeight * ratio;
+        const sill = isDoor ? 0 : (o.floorHeight - h) / 2;
+        const c = slot.start + slot.size / 2 - along / 2;
+        const inset = slot.size * 0.85;
+        const pos: Vec3 =
+          side === 'front'
+            ? [o.at[0] + w / 2, o.at[1] + c, z + sill]
+            : side === 'back'
+              ? [o.at[0] - w / 2, o.at[1] - c, z + sill]
+              : side === 'left'
+                ? [o.at[0] - c, o.at[1] + d / 2, z + sill]
+                : [o.at[0] + c, o.at[1] - d / 2, z + sill];
+        const name = `${o.prefix}_${side}_${f}_${i}`;
+        if (o.kit) {
+          const k = o.kit;
+          ctx.part(
+            name,
+            opening(
+              {
+                kind: isDoor ? 'door' : 'window',
+                width: Math.max(0.3, inset - 0.2),
+                height: h - (isDoor ? 0.25 : 0.2),
+                at: pos,
+                facing: side,
+                glass: o.glass,
+                frame: o.frame ?? [0.92, 0.9, 0.85],
+                wall: k.wall,
+                ...(k.trim ? { trim: k.trim } : {}),
+                ...(k.depth !== undefined ? { depth: k.depth } : {}),
+                ...(k.panes ? { panes: k.panes } : {}),
+                ...(k.strip ? { wallStrip: k.strip } : {}),
+              },
+              ctx.lod,
+            ),
+          );
+          return;
+        }
+        const size: Vec3 =
+          side === 'front' || side === 'back' ? [depth, inset, h] : [inset, depth, h];
+        ctx.part(
+          name,
+          box({
+            size,
+            at: pos,
+            color: isDoor ? (o.frame ?? o.glass) : o.glass,
+            strip: 'glass',
+            omit: ['bottom'],
+          }),
+        );
+      });
+    }
+  }
+}
+
+export interface SetbackTier {
+  readonly footprint: readonly [number, number];
+  readonly floors: number;
+}
+
+/** Stack of shrinking masses (Empire State, Chrysler-style towers). Returns the top z. */
+export function setbacks(
+  ctx: BuildContext,
+  o: {
+    prefix: string;
+    tiers: readonly SetbackTier[];
+    floorHeight: number;
+    color: Vec3;
+    grammar: string;
+    glass: Vec3;
+    detail: boolean;
+  },
+): number {
+  let z = 0;
+  o.tiers.forEach((t, i) => {
+    const h = t.floors * o.floorHeight;
+    ctx.part(
+      `${o.prefix}_${i}`,
+      box({
+        size: [t.footprint[0], t.footprint[1], h],
+        at: [0, 0, z],
+        color: o.color,
+        strip: 'stone',
+        omit: i === 0 ? ['bottom'] : [],
+      }),
+    );
+    if (o.detail)
+      facade(ctx, {
+        prefix: `${o.prefix}_${i}_win`,
+        at: [0, 0, z],
+        footprint: t.footprint,
+        floors: t.floors,
+        floorHeight: o.floorHeight,
+        grammar: o.grammar,
+        sides: ['front', 'back', 'left', 'right'],
+        glass: o.glass,
+      });
+    z += h;
+  });
+  return z;
+}

package/src/kinds/faces.ts

@@ -0,0 +1,138 @@
+// Convex-polygon toolkit for the building kinds: half-plane clipping in plan, and emitting a flat
+// convex 3D polygon onto a trim strip AT TRUE SCALE. A strip tiles along U only, so the polygon is
+// cut into bands `scaleMetres` tall along its V direction (courses start on `vOrigin`); each band
+// maps V 0→1 across the strip. That is how slates run down a slope and bricks up a gable.
+
+import {
+  cross,
+  dot,
+  type MeshBuilder,
+  normalize,
+  sub,
+  type Vec2,
+  type Vec3,
+} from '../core/index.ts';
+import { DEFAULT_SHEET, type StripId, stripRect } from '../material/index.ts';
+
+const EPS = 1e-9;
+
+/** Keep the part of a convex polygon where the linear function `f` is ≤ 0. */
+export function clipPoly<P extends Vec2 | Vec3>(poly: readonly P[], f: (p: P) => number): P[] {
+  const out: P[] = [];
+  const n = poly.length;
+  for (let i = 0; i < n; i++) {
+    const a = poly[i];
+    const b = poly[(i + 1) % n];
+    if (a === undefined || b === undefined) continue;
+    const fa = f(a);
+    const fb = f(b);
+    if (fa <= EPS) out.push(a);
+    if (fa <= EPS !== fb <= EPS) {
+      const t = fa / (fa - fb);
+      out.push(a.map((v, k) => v + ((b[k] ?? v) - v) * t) as unknown as P);
+    }
+  }
+  return dedupe(out);
+}
+
+/** Drop consecutive duplicate points (clipping through a vertex emits it twice). */
+export function dedupe<P extends Vec2 | Vec3>(poly: readonly P[]): P[] {
+  const out: P[] = [];
+  for (const p of poly) {
+    const q = out.at(-1);
+    if (!q || p.some((v, k) => Math.abs(v - (q[k] ?? 0)) > 1e-7)) out.push(p);
+  }
+  const first = out[0];
+  const last = out.at(-1);
+  if (out.length > 1 && first && last && first.every((v, k) => Math.abs(v - (last[k] ?? 0)) < 1e-7))
+    out.pop();
+  return out;
+}
+
+/** Signed area of a 2D polygon (CCW positive). */
+export const area2 = (poly: readonly Vec2[]): number =>
+  poly.reduce((s, a, i) => {
+    const b = poly[(i + 1) % poly.length] ?? a;
+    return s + a[0] * b[1] - b[0] * a[1];
+  }, 0) / 2;
+
+/** Vertical extent of one band (one full V of the strip) in metres, from the house sheet. */
+export const stripScale = (strip: StripId): number => DEFAULT_SHEET.strips[strip]?.scaleMetres ?? 1;
+
+export interface FaceOptions {
+  /** Convex and planar; either winding (it is turned to face `normal`). */
+  readonly points: readonly Vec3[];
+  readonly normal: Vec3;
+  /** Direction V grows along (up a slope, up a wall); projected into the face plane. */
+  readonly up: Vec3;
+  /** A point on the line where courses start (eave, wall foot). */
+  readonly vOrigin: Vec3;
+  readonly color: Vec3 | ((p: Vec3) => Vec3);
+  readonly strip: StripId;
+  /** false: one polygon, V squeezed over the whole face (far LODs). Default true. */
+  readonly banded?: boolean;
+}
+
+/** Emit a convex face into `b`, banded at the strip's true scale. Returns triangles added. */
+export function emitFace(b: MeshBuilder, o: FaceOptions): number {
+  if (o.points.length < 3) return 0;
+  const n = normalize(o.normal);
+  const points = dot(newell(o.points), n) < 0 ? [...o.points].reverse() : o.points;
+  const vDir = normalize(sub(o.up, scaleV(n, dot(o.up, n))));
+  const uDir = cross(vDir, n);
+  const rect = stripRect(o.strip);
+  const scale = stripScale(o.strip);
+  const vOf = (p: Vec3): number => dot(sub(p, o.vOrigin), vDir);
+  const vs = points.map(vOf);
+  const lo = Math.min(...vs);
+  const hi = Math.max(...vs);
+  if (hi - lo < 1e-6) return 0;
+  const colour = (p: Vec3): Vec3 => (typeof o.color === 'function' ? o.color(p) : o.color);
+  const bands: [number, number][] = [];
+  if (o.banded === false) bands.push([lo, hi]);
+  else {
+    for (let k = Math.floor(lo / scale + 1e-9); k * scale < hi - 1e-9; k++) {
+      bands.push([k * scale, (k + 1) * scale]);
+    }
+  }
+  let tris = 0;
+  for (const [v0, v1] of bands) {
+    const span = v1 - v0;
+    const poly = clipPoly(
+      clipPoly(points, (p) => v0 - vOf(p)),
+      (p) => vOf(p) - v1,
+    );
+    if (poly.length < 3) continue;
+    const ids = poly.map((p) => {
+      const f = Math.min(1, Math.max(0, (vOf(p) - v0) / span));
+      return b.vertex({
+        p,
+        n,
+        uv: [
+          rect.u0 + (dot(p, uDir) / rect.metres) * (rect.u1 - rect.u0),
+          rect.v0 + f * (rect.v1 - rect.v0),
+        ],
+        color: colour(p),
+      });
+    });
+    const first = ids[0] ?? 0;
+    for (let i = 1; i + 1 < ids.length; i++) b.tri(first, ids[i] ?? 0, ids[i + 1] ?? 0);
+    tris += ids.length - 2;
+  }
+  return tris;
+}
+
+/** Newell's polygon normal (unnormalised): robust for any planar polygon. */
+export function newell(poly: readonly Vec3[]): Vec3 {
+  const n: [number, number, number] = [0, 0, 0];
+  for (let i = 0; i < poly.length; i++) {
+    const a = poly[i] ?? [0, 0, 0];
+    const b = poly[(i + 1) % poly.length] ?? a;
+    n[0] += (a[1] - b[1]) * (a[2] + b[2]);
+    n[1] += (a[2] - b[2]) * (a[0] + b[0]);
+    n[2] += (a[0] - b[0]) * (a[1] + b[1]);
+  }
+  return n;
+}
+
+const scaleV = (v: Vec3, s: number): Vec3 => [v[0] * s, v[1] * s, v[2] * s];

package/src/kinds/head-armour.ts

@@ -0,0 +1,151 @@
+// The orc's armoured bust gear as sculpt groups: layered metal pauldron lames (domes trimmed by a
+// tilted plane, each with a rolled rim), bone spikes, a leather baldric that follows the chest
+// (a shell of the chest ∩ a diagonal slab) with an iron buckle, and a fur mantle of clumped,
+// tapering strands. 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, unit } from './head-geom.ts';
+import type { HeadParams } from './head-params.ts';
+
+const RAD = Math.PI / 180;
+const shade = (c: Vec3, k: number): Vec3 => [c[0] * k, c[1] * k, c[2] * k];
+
+/** Half-space kept above the plane through `p` whose normal is +Z rolled `deg` about X. */
+const above = (p: Vec3, deg: number, op: 'intersect' | 'subtract' = 'intersect'): SculptEdit => {
+  const n: Vec3 = [0, -Math.sin(deg * RAD), Math.cos(deg * RAD)];
+  return {
+    shape: 'roundBox',
+    at: [p[0] + n[0], p[1] + n[1], p[2] + n[2]],
+    size: [4, 4, 2],
+    rotate: [deg, 0, 0],
+    op,
+  };
+};
+
+/** Thin slab (thickness `t`) through `p`, normal +Z rolled `deg` about X. */
+const slab = (p: Vec3, deg: number, t: number): SculptEdit => ({
+  shape: 'roundBox',
+  at: p,
+  size: [4, 4, t],
+  rotate: [deg, 0, 0],
+  op: 'intersect',
+});
+
+/** Chest ellipsoid of the bust (shared with head-bust.ts so the strap hugs it). */
+export const chestOf = (cx: number, s: number, b: number): { at: Vec3; r: Vec3 } => ({
+  at: [cx - 0.04, 0, b + 0.2],
+  r: [0.36, s * 0.75, 0.42],
+});
+
+export function armour(p: HeadParams, cx: number, s: number, b: number, nz: number): SculptEdit[] {
+  const c = p.colors;
+  const metal = c.metal;
+  const out: SculptEdit[] = [];
+  // Pauldrons: three lames, top one biggest, stepping down and out; rims a darker iron.
+  for (let k = 0; k < 3; k++) {
+    const at: Vec3 = [cx - 0.03, s * (0.78 + k * 0.1), b + 0.53 - k * 0.12];
+    const r: Vec3 = [0.31 - k * 0.02, 0.27 - k * 0.03, 0.19 - k * 0.02];
+    const tilt = -(28 + k * 14);
+    const cut: Vec3 = [at[0], at[1], at[2] - r[2] * 0.35];
+    out.push(
+      {
+        group: [{ shape: 'ellipsoid', at, size: r }, above(cut, tilt)],
+        color: shade(metal, 1 - k * 0.12),
+        blend: 0.008,
+      },
+      {
+        group: [
+          { shape: 'ellipsoid', at, size: [r[0] + 0.018, r[1] + 0.018, r[2] + 0.018] },
+          slab(cut, tilt, 0.035),
+        ],
+        color: shade(metal, 0.55),
+        blend: 0.004,
+      },
+    );
+    // Rivets along the top of each lame's rim.
+    for (let j = 0; j < 4; j++) {
+      const t = (j - 1.5) * 0.11;
+      out.push({
+        shape: 'sphere',
+        at: [at[0] + t, at[1] + Math.sin(-tilt * RAD) * r[1] * 0.55, cut[2] + 0.03],
+        size: 0.016,
+        color: shade(metal, 1.4),
+        blend: 0.004,
+      });
+    }
+  }
+  // Bone spikes along the top lame's ridge.
+  for (let k = 0; k < 3; k++)
+    out.push({
+      shape: 'cone',
+      at: [cx - 0.17 + k * 0.14, s * 0.84, b + 0.68 - Math.abs(k - 1) * 0.03],
+      size: [0.065, 0.006, 0.26 - Math.abs(k - 1) * 0.08],
+      rotate: alongZ(unit([(k - 1) * 0.35, 0.45, 1])),
+      color: c.teeth,
+      blend: 0.01,
+    });
+  // Baldric: a shell of the chest cut to a diagonal band, over the left shoulder; iron buckle.
+  const chest = chestOf(cx, s, b);
+  const grow = (g: number): Vec3 => [chest.r[0] + g, chest.r[1] + g, chest.r[2] + g];
+  const band: Vec3 = [cx, 0, b + 0.28];
+  out.push(
+    {
+      group: [{ shape: 'ellipsoid', at: chest.at, size: grow(0.03) }, slab(band, 52, 0.17)],
+      color: c.leather,
+      blend: 0.006,
+      mirror: false,
+    },
+    {
+      group: [
+        { shape: 'ellipsoid', at: chest.at, size: grow(0.055) },
+        {
+          shape: 'roundBox',
+          at: [cx + 0.3, 0.02, b + 0.3],
+          size: [0.3, 0.15, 0.15],
+          rotate: [52, 0, 0],
+          op: 'intersect',
+        },
+        {
+          shape: 'ellipsoid',
+          at: [cx + 0.42, 0.02, b + 0.3],
+          size: [0.1, 0.045, 0.045],
+          op: 'subtract',
+        },
+      ],
+      color: shade(metal, 0.8),
+      blend: 0.004,
+      mirror: false,
+    },
+  );
+  // Fur mantle: a thick base roll, then clumped strands fanning out and down from it.
+  const fur = c.fur ?? c.leather;
+  const R = p.neck.radius + 0.1;
+  out.push({
+    shape: 'torus',
+    at: [cx - 0.08, 0, nz + 0.02],
+    size: [R, 0.07],
+    color: shade(fur, 0.75),
+    blend: 0.04,
+  });
+  for (let row = 0; row < 2; row++)
+    for (let i = 0; i < 10; i++) {
+      const a = (-85 + i * 20 + row * 10) * RAD;
+      const rr = R + row * 0.05;
+      const root: Vec3 = [
+        cx - 0.08 + Math.cos(a) * rr,
+        Math.abs(Math.sin(a)) * rr + 0.015,
+        nz + 0.07 - row * 0.06,
+      ];
+      const dir = unit([Math.cos(a), Math.abs(Math.sin(a)), -0.5 - ((i + row) % 2) * 0.35]);
+      out.push({
+        shape: 'cone',
+        at: root,
+        size: [0.07 - row * 0.01, 0.012, 0.13 + ((i + row) % 3) * 0.03],
+        rotate: alongZ(dir),
+        color: (i + row) % 2 ? fur : shade(fur, 0.7),
+        blend: 0.03,
+      });
+    }
+  return out;
+}

package/src/kinds/head-beard.ts

@@ -0,0 +1,133 @@
+// Facial hair as sculpt groups, part of the skull field (so a beard splits with the jaw):
+// eyebrows riding just proud of the brow ridge (tapered, arched), and beards built as one clipped
+// volume — a mass around jaw and chin, trimmed above a cheek line that rises to the ears, the lips
+// carved clear — plus a two-segment moustache and optional braid. Head units, mirrored across Y.
+
+import type { Vec3 } from '../core/index.ts';
+import type { SculptEdit } from '../primitives/index.ts';
+import { along, unit } from './head-geom.ts';
+import type { HeadLayout } from './head-layout.ts';
+import type { HeadParams } from './head-params.ts';
+
+const RAD = Math.PI / 180;
+
+/** Eyebrows: two capsule segments (inner thick → outer thin) offset off the brow ridge. */
+export function browEdits(p: HeadParams, l: HeadLayout): SculptEdit[] {
+  const h = p.brow.hair ?? 0;
+  if (h <= 0) return [];
+  const [ex, ey] = l.eye;
+  const r = l.eyeR;
+  const lift: Vec3 = [p.brow.ridge * 0.55 + 0.012, 0, p.brow.ridge * 0.8 + 0.018];
+  const inner: Vec3 = [ex + r * 0.75 + lift[0], 0.035, l.browZ - p.brow.scowl + lift[2]];
+  const outer: Vec3 = [
+    ex + r * 0.1 + lift[0] * 0.6,
+    ey + r * 1.25,
+    l.browZ + p.brow.scowl * 0.5 + lift[2] * 0.7,
+  ];
+  const mid: Vec3 = [
+    (inner[0] + outer[0]) / 2,
+    inner[1] + (outer[1] - inner[1]) * 0.55,
+    (inner[2] + outer[2]) / 2 + 0.014,
+  ];
+  return [
+    {
+      group: [
+        { shape: 'capsule', at: inner, to: mid, size: h },
+        { shape: 'capsule', at: mid, to: outer, size: h * 0.65, blend: 0.006 },
+      ],
+      color: p.colors.hair,
+      blend: 0.006,
+    },
+  ];
+}
+
+/** Box whose top face is the plane through `p` tilted `deg` about Y (positive: higher at back). */
+const below = (p: Vec3, deg: number): SculptEdit => {
+  const n: Vec3 = [-Math.sin(deg * RAD), 0, Math.cos(deg * RAD)];
+  return {
+    shape: 'roundBox',
+    at: [p[0] - n[0], p[1], p[2] - n[2]],
+    size: [4, 4, 2],
+    rotate: [0, -deg, 0],
+    op: 'intersect',
+    blend: 0.02,
+  };
+};
+
+export function beardEdits(p: HeadParams, l: HeadLayout): SculptEdit[] {
+  if (p.beard === 'none') return [];
+  const h = p.colors.hair;
+  const light: Vec3 = [h[0] * 1.35, h[1] * 1.35, h[2] * 1.35];
+  const [ax, ay, az] = l.angle;
+  const ch = l.chin;
+  const mw = p.mouth.width;
+  const lipT = p.mouth.lips;
+  const full = p.beard !== 'goatee';
+  const mass: SculptEdit = full
+    ? {
+        shape: 'ellipsoid',
+        at: [(ax + ch[0]) / 2 + 0.03, 0, (az + ch[2]) / 2 + 0.01],
+        size: [(ch[0] - ax) / 2 + 0.08, ay + 0.065, 0.17],
+      }
+    : { shape: 'ellipsoid', at: [ch[0] + 0.01, 0, ch[2] + 0.02], size: [0.09, mw * 0.9, 0.11] };
+  const out: SculptEdit[] = [
+    {
+      group: [
+        mass,
+        // Chin volume: the beard grows forward and down off the chin.
+        {
+          shape: 'ellipsoid',
+          at: [ch[0] + 0.025, 0, ch[2] - 0.03],
+          size: [0.08, full ? 0.13 : 0.08, 0.1],
+          blend: 0.04,
+        },
+        // Trimmed below a cheek line that rises towards the ears.
+        below([l.mouthX, 0, l.mouthZ + 0.03], full ? 28 : 0),
+        // Lips carved clear.
+        {
+          shape: 'ellipsoid',
+          at: [l.mouthX + 0.02, 0, l.mouthZ - lipT * 0.3],
+          size: [0.07, mw * 1.05, lipT * 2.3],
+          op: 'subtract',
+          blend: 0.012,
+        },
+        // Clump grooves down the chin.
+        ...[-0.05, 0.05].map(
+          (y): SculptEdit => ({
+            shape: 'capsule',
+            at: [ch[0] + 0.12, y, l.mouthZ - 0.06],
+            to: [ch[0] + 0.06, y * 1.3, ch[2] - 0.14],
+            size: 0.008,
+            op: 'subtract',
+            blend: 0.012,
+            mirror: false,
+          }),
+        ),
+      ],
+      color: h,
+      blend: 0.012,
+    },
+  ];
+  if (p.beard === 'braided')
+    out.push({
+      shape: 'capsule',
+      at: [ch[0] + 0.03, 0.035, ch[2] - 0.08],
+      to: [ch[0] + 0.01, 0.045, ch[2] - 0.34],
+      size: 0.032,
+      color: light,
+      blend: 0.02,
+    });
+  // Moustache: from under the nose, over the lip corners, drooping past them.
+  const root: Vec3 = [l.mouthX + 0.02, 0.012, l.mouthZ + lipT * 1.9];
+  const bend: Vec3 = [l.mouthX - 0.005, mw * 0.85, l.mouthZ + lipT * 0.6];
+  const tip = along(bend, unit([-0.4, 0.5, -1]), 0.05);
+  out.push({
+    group: [
+      { shape: 'capsule', at: root, to: bend, size: 0.024 },
+      { shape: 'capsule', at: bend, to: tip, size: 0.016, blend: 0.01 },
+    ],
+    color: light,
+    blend: 0.008,
+  });
+  return out;
+}