@developerz.ai/ts23d 0.0.0-stage → 0.1.0

package/src/material/paint/plates.ts

@@ -0,0 +1,72 @@
+// Riveted iron plates (kind 'plates'): lapped plates (each overlaps its left neighbour by a
+// step), domed rivet rows along every seam, hammered surface, rust streaks running down from
+// rivets, chipped paint showing bare metal on edges.
+// params: width 1.0 · height 0.5 · lap 0.003 · rivet 0.014 (radius) · pitch 0.09 · inset 0.05
+//         rust 0.4 · chips 0.3
+
+import { type Canvas, noiseAt, param, smooth } from './canvas.ts';
+import { Courses } from './courses.ts';
+import { rustStreaks } from './masks.ts';
+import { hash2 } from './noise.ts';
+import type { StripRecipe } from './types.ts';
+
+/** Distance (m) from `q` to the nearest multiple of `pitch`. */
+function along(q: number, pitch: number): number {
+  const t = q / pitch;
+  return Math.abs(t - Math.round(t)) * pitch;
+}
+
+export function paintPlates(c: Canvas, r: StripRecipe, seed: number): void {
+  const p = r.params;
+  const lap = param(p, 'lap', 0.003);
+  const rivet = param(p, 'rivet', 0.014);
+  const pitch = param(p, 'pitch', 0.09);
+  const inset = param(p, 'inset', 0.05);
+  const chips = param(p, 'chips', 0.3);
+  const metal = r.metalness ?? 0;
+  const plates = new Courses(c, {
+    course: param(p, 'height', 0.5),
+    length: param(p, 'width', 1),
+    irregular: 0,
+    stagger: 0.5,
+    seed,
+  });
+  const pu = c.metresU / c.w;
+  const pv = c.metresV / c.h;
+  for (let y = 0; y < c.h; y++) {
+    const ym = (y + 0.5) * pv;
+    const k = plates.at(ym);
+    const dy = Math.min(ym - plates.y0, plates.y1 - ym);
+    for (let x = 0; x < c.w; x++) {
+      const i = y * c.w + x;
+      const xm = (x + 0.5) * pu;
+      const ux = plates.ux[x] ?? 0;
+      const dx = plates.dx[x] ?? 0;
+      const id = plates.id[x] ?? 0;
+      const hammer = noiseAt(c, xm, ym, 0.05, 0.05, seed + 3, 3);
+      const fine = noiseAt(c, xm, ym, 0.004, 0.004, seed + 9, 2);
+      // Lap: the plate sits `lap` proud of the one to its left; a tiny groove on every seam.
+      const seam = Math.min(dx, dy);
+      let h = lap * smooth(0, 0.004, ux) + 0.0004 * hammer - 0.001 * (1 - smooth(0, 0.0015, seam));
+      // Rivet rows: `inset` from each vertical seam and from each course edge, every `pitch`.
+      const ry = Math.abs(dy - inset);
+      const rx = Math.abs(dx - inset);
+      const d1 = Math.sqrt(rx * rx + along(ym - plates.y0, pitch) ** 2);
+      const d2 = Math.sqrt(ry * ry + along(xm, pitch) ** 2);
+      const d = Math.min(dx > inset * 2 ? 1 : d1, dy > inset * 2 ? 1 : d2);
+      const dome = d < rivet ? Math.sqrt(1 - (d / rivet) ** 2) : 0;
+      h += dome * rivet * 0.5;
+      const chip = smooth(
+        0.35,
+        0.45,
+        noiseAt(c, xm, ym, 0.03, 0.03, seed + 21, 4) - (seam * 6 + 0.2) + chips * 0.3,
+      );
+      c.height[i] = h - chip * 0.0003;
+      c.tone[i] =
+        (0.8 + 0.06 * hash2(k, id, seed)) * (1 + 0.06 * hammer + 0.03 * fine) * (1 + 0.15 * dome);
+      c.rough[i] = r.roughness + 0.08 * fine - 0.25 * chip;
+      c.metal[i] = metal + (1 - metal) * chip;
+    }
+  }
+  rustStreaks(c, param(p, 'rust', 0.4), seed + 77);
+}

package/src/material/paint/shapes.ts

@@ -0,0 +1,28 @@
+// Tiny SDF-style helpers for cell motifs: distances in metres, no allocation.
+
+/** Distance from (px, py) to the segment (ax, ay)–(bx, by). */
+export function segment(px: number, py: number, ax: number, ay: number, bx: number, by: number) {
+  const dx = bx - ax;
+  const dy = by - ay;
+  const t = Math.max(0, Math.min(1, ((px - ax) * dx + (py - ay) * dy) / (dx * dx + dy * dy)));
+  return Math.hypot(px - ax - t * dx, py - ay - t * dy);
+}
+
+/** Signed distance to an axis-aligned rectangle (negative inside). */
+export function rect(px: number, py: number, x0: number, y0: number, x1: number, y1: number) {
+  const qx = Math.max(x0 - px, px - x1);
+  const qy = Math.max(y0 - py, py - y1);
+  return qx > 0 || qy > 0 ? Math.hypot(Math.max(qx, 0), Math.max(qy, 0)) : Math.max(qx, qy);
+}
+
+/** Dome profile in [0, 1] for a round boss of radius `r` at distance `d`. */
+export const dome = (d: number, r: number): number => (d < r ? Math.sqrt(1 - (d / r) ** 2) : 0);
+
+/** Distance to the nearest of `n` points evenly spaced on a circle of radius `ring`. */
+export function boltRing(px: number, py: number, ring: number, n: number, phase = 0): number {
+  const a = Math.atan2(py, px) - phase;
+  const step = (Math.PI * 2) / n;
+  const k = Math.round(a / step);
+  const ba = k * step + phase;
+  return Math.hypot(px - ring * Math.cos(ba), py - ring * Math.sin(ba));
+}

package/src/material/paint/slate.ts

@@ -0,0 +1,52 @@
+// Roof slate (kind 'slate'): overlapping courses — each visible slate rises from where it slides
+// under the course above to a thick, chipped lower edge that casts the shadow line — staggered
+// vertical gaps, riven (laminar) face, per-slate tone and tilt.
+// params: course 0.11 (exposure) · length 0.25 · gap 0.003 · thick 0.007 · variation 0.3
+
+import { type Canvas, noiseAt, param, smooth } from './canvas.ts';
+import { Courses } from './courses.ts';
+import { hash2 } from './noise.ts';
+import type { StripRecipe } from './types.ts';
+
+export function paintSlate(c: Canvas, r: StripRecipe, seed: number): void {
+  const p = r.params;
+  const course = param(p, 'course', 0.11);
+  const gap = param(p, 'gap', 0.003);
+  const thick = param(p, 'thick', 0.007);
+  const variation = param(p, 'variation', 0.3);
+  const rows = new Courses(c, {
+    course,
+    length: param(p, 'length', 0.25),
+    irregular: 0.15,
+    stagger: 0.5,
+    seed,
+  });
+  const pu = c.metresU / c.w;
+  const pv = c.metresV / c.h;
+  for (let y = 0; y < c.h; y++) {
+    const ym = (y + 0.5) * pv;
+    const k = rows.at(ym);
+    const span = rows.y1 - rows.y0;
+    for (let x = 0; x < c.w; x++) {
+      const i = y * c.w + x;
+      const xm = (x + 0.5) * pu;
+      const id = rows.id[x] ?? 0;
+      const h = hash2(k, id, seed);
+      const chip = (noiseAt(c, xm, ym, 0.015, 0.01, seed + 5, 3) + 0.3) * span * 0.08;
+      const uy = Math.max(0, ym - rows.y0 - Math.max(0, chip));
+      const t = uy / span;
+      const lam = noiseAt(c, xm, ym, 0.12, 0.004, seed + 9, 3);
+      const fine = noiseAt(c, xm, ym, 0.005, 0.005, seed + 13, 2);
+      const sideGap = smooth(gap * 0.5, gap * 1.2, rows.dx[x] ?? 0);
+      const bevel = smooth(0, 0.004, uy);
+      const tilt = (hash2(id, k, seed + 1) - 0.5) * 0.002 * ((rows.ux[x] ?? 0) / 0.25);
+      c.height[i] =
+        (thick * (1 - t) * bevel + 0.0005 * lam + tilt) * sideGap - thick * (1 - sideGap);
+      c.tone[i] =
+        (0.62 - variation * 0.5 + variation * h) *
+        (1 + 0.08 * lam + 0.04 * fine) *
+        (0.55 + 0.45 * sideGap);
+      c.rough[i] = r.roughness + 0.08 * lam + 0.05 * fine;
+    }
+  }
+}

package/src/material/paint/stamp.ts

@@ -0,0 +1,40 @@
+// Stamp a supplied PNG into a cell canvas: bilinear resample to the cell, flipped so the image's
+// top row lands at world-up (high V, where box/planar put a face's top). Flat relief, the
+// recipe-free roughness default; the image's own colour is kept (vertex colour still multiplies).
+
+import type { Canvas } from './canvas.ts';
+import { decodePng } from './decode-png.ts';
+
+export const STAMP_ROUGHNESS = 0.6;
+
+export function stampImage(c: Canvas, png: Uint8Array): void {
+  const img = decodePng(png);
+  const out = new Uint8Array(c.w * c.h * 4);
+  for (let y = 0; y < c.h; y++) {
+    const sy = Math.min(
+      img.height - 1,
+      Math.max(0, ((c.h - 1 - y + 0.5) / c.h) * img.height - 0.5),
+    );
+    const y0 = Math.floor(sy);
+    const y1 = Math.min(img.height - 1, y0 + 1);
+    const fy = sy - y0;
+    for (let x = 0; x < c.w; x++) {
+      const sx = Math.min(img.width - 1, Math.max(0, ((x + 0.5) / c.w) * img.width - 0.5));
+      const x0 = Math.floor(sx);
+      const x1 = Math.min(img.width - 1, x0 + 1);
+      const fx = sx - x0;
+      for (let k = 0; k < 4; k++) {
+        const a = img.data[(y0 * img.width + x0) * 4 + k] ?? 0;
+        const b = img.data[(y0 * img.width + x1) * 4 + k] ?? 0;
+        const d = img.data[(y1 * img.width + x0) * 4 + k] ?? 0;
+        const e = img.data[(y1 * img.width + x1) * 4 + k] ?? 0;
+        const top = a + (b - a) * fx;
+        out[(y * c.w + x) * 4 + k] = Math.round(top + (d + (e - d) * fx - top) * fy);
+      }
+    }
+  }
+  c.rgba = out;
+  c.height.fill(0);
+  c.rough.fill(STAMP_ROUGHNESS);
+  c.metal.fill(0);
+}

package/src/material/paint/strip.ts

@@ -0,0 +1,42 @@
+// Dispatch a StripRecipe to its painter, then the shared grime pass (`params.grime`, 0..1).
+
+import { paintBond } from './bond.ts';
+import type { Canvas } from './canvas.ts';
+import { param } from './canvas.ts';
+import { paintConcrete } from './concrete.ts';
+import { grime } from './masks.ts';
+import { paintPlanks } from './planks.ts';
+import { paintPlates } from './plates.ts';
+import { paintSlate } from './slate.ts';
+import { paintFlat, paintGlass, paintNoise } from './surface.ts';
+import type { StripRecipe } from './types.ts';
+
+export function paintStrip(c: Canvas, r: StripRecipe, seed: number): void {
+  switch (r.kind) {
+    case 'bond':
+      paintBond(c, r, seed);
+      break;
+    case 'planks':
+      paintPlanks(c, r, seed);
+      break;
+    case 'plates':
+      paintPlates(c, r, seed);
+      break;
+    case 'slate':
+      paintSlate(c, r, seed);
+      break;
+    case 'concrete':
+      paintConcrete(c, r, seed);
+      break;
+    case 'glass':
+      paintGlass(c, r, seed);
+      return;
+    case 'noise':
+      paintNoise(c, r, seed);
+      break;
+    case 'flat':
+      paintFlat(c, r);
+      return;
+  }
+  grime(c, param(r.params, 'grime', 0), seed + 101);
+}

package/src/material/paint/surface.ts

@@ -0,0 +1,60 @@
+// The simple kinds: 'noise' (a quiet painted/plain surface: soft tone and roughness mottling,
+// faint relief), 'flat' (constant) and 'glass' (near-white, very smooth, faint ripples, smudges,
+// grime toward the bottom edge).
+// params (noise): tone 0.93 · mottle 0.03 · relief 0.0002 · size 0.3
+// params (glass): ripple 0.0002 · smudge 0.08 · grime 0.4
+
+import { type Canvas, noiseAt, param } from './canvas.ts';
+import { grime } from './masks.ts';
+import type { StripRecipe } from './types.ts';
+
+export function paintFlat(c: Canvas, r: StripRecipe): void {
+  c.tone.fill(param(r.params, 'tone', 1));
+  c.rough.fill(r.roughness);
+  c.metal.fill(r.metalness ?? 0);
+  c.height.fill(0);
+}
+
+export function paintNoise(c: Canvas, r: StripRecipe, seed: number): void {
+  const tone = param(r.params, 'tone', 0.93);
+  const mottle = param(r.params, 'mottle', 0.03);
+  const relief = param(r.params, 'relief', 0.0002);
+  const size = param(r.params, 'size', 0.3);
+  const pu = c.metresU / c.w;
+  const pv = c.metresV / c.h;
+  const metal = r.metalness ?? 0;
+  for (let y = 0; y < c.h; y++) {
+    const ym = (y + 0.5) * pv;
+    for (let x = 0; x < c.w; x++) {
+      const xm = (x + 0.5) * pu;
+      const big = noiseAt(c, xm, ym, size, size, seed, 4);
+      const fine = noiseAt(c, xm, ym, 0.01, 0.01, seed + 1, 2);
+      const i = y * c.w + x;
+      c.tone[i] = tone + mottle * big;
+      c.rough[i] = r.roughness + 0.06 * big + 0.03 * fine;
+      c.metal[i] = metal;
+      c.height[i] = relief * (big + 0.3 * fine);
+    }
+  }
+}
+
+export function paintGlass(c: Canvas, r: StripRecipe, seed: number): void {
+  const ripple = param(r.params, 'ripple', 0.0002);
+  const smudge = param(r.params, 'smudge', 0.08);
+  const pu = c.metresU / c.w;
+  const pv = c.metresV / c.h;
+  for (let y = 0; y < c.h; y++) {
+    const ym = (y + 0.5) * pv;
+    for (let x = 0; x < c.w; x++) {
+      const xm = (x + 0.5) * pu;
+      const wave = noiseAt(c, xm, ym, 0.15, 0.4, seed, 3);
+      const smear = noiseAt(c, xm, ym, 0.08, 0.08, seed + 1, 4);
+      const i = y * c.w + x;
+      c.tone[i] = 0.92 + 0.02 * wave;
+      c.rough[i] = r.roughness + smudge * Math.max(0, smear);
+      c.metal[i] = 0;
+      c.height[i] = ripple * wave;
+    }
+  }
+  grime(c, param(r.params, 'grime', 0.4), seed + 9);
+}

package/src/material/paint/types.ts

@@ -0,0 +1,51 @@
+// The generator's public data contract (re-exported by generator.ts): what a sheet recipe says
+// and what the painter returns.
+
+import type { CellId, StripId } from '../trim-sheet.ts';
+
+export interface PaintedSheet {
+  readonly size: number;
+  /** RGBA8, sRGB. Near-greyscale: hue comes from vertex colour multiplied over it. */
+  readonly albedo: Uint8Array;
+  /** RGBA8, tangent-space (glTF / OpenGL, +Y toward decreasing V). */
+  readonly normal: Uint8Array;
+  /** R = occlusion, G = roughness, B = metalness. */
+  readonly orm: Uint8Array;
+}
+
+export type StripKind =
+  | 'bond'
+  | 'planks'
+  | 'plates'
+  | 'noise'
+  | 'flat'
+  | 'slate'
+  | 'concrete'
+  | 'glass';
+
+export interface StripRecipe {
+  readonly kind: StripKind;
+  /**
+   * World metres the strip's V span represents (its U span is always `stripRect().metres`).
+   * Pick the typical face height the strip is stretched over; texels are anisotropic if needed.
+   */
+  readonly scaleMetres: number;
+  readonly roughness: number;
+  readonly metalness?: number;
+  /** Brick/plank courses, rivet pitch, etc. — read per kind (see each painter's header). */
+  readonly params?: Readonly<Record<string, number>>;
+}
+
+/** A cell stamped from PNG bytes (8-bit grey/RGB/RGBA, non-interlaced), e.g. a kubeez.com decal. */
+export interface CellImage {
+  readonly image: Uint8Array;
+}
+
+export interface SheetRecipe {
+  readonly seed: number;
+  readonly size?: 512 | 1024 | 2048;
+  /** Missing strips fall back to `DEFAULT_SHEET`'s recipe for that strip. */
+  readonly strips: Readonly<Partial<Record<StripId, StripRecipe>>>;
+  /** Cells painted from code, or stamped from a supplied image (e.g. a kubeez.com decal). */
+  readonly cells?: Readonly<Partial<Record<CellId, StripRecipe | CellImage>>>;
+}

package/src/material/paint/validate.ts

@@ -0,0 +1,58 @@
+// Recipe validation: every bad input throws T3D_RECIPE_INVALID with the fix, before any painting.
+
+import { Ts23dError } from '../../core/index.ts';
+import { CELLS, STRIPS } from '../trim-sheet.ts';
+import type { CellImage, SheetRecipe, StripKind, StripRecipe } from './types.ts';
+
+const KINDS: readonly StripKind[] = [
+  'bond',
+  'planks',
+  'plates',
+  'noise',
+  'flat',
+  'slate',
+  'concrete',
+  'glass',
+];
+const SIZES = [512, 1024, 2048];
+
+function fail(cause: string, fix: string): never {
+  throw new Ts23dError('T3D_RECIPE_INVALID', { cause: `sheet recipe: ${cause}`, fix });
+}
+
+const unit = (v: number): boolean => Number.isFinite(v) && v >= 0 && v <= 1;
+
+export function validateStrip(where: string, r: StripRecipe): void {
+  if (!KINDS.includes(r.kind))
+    fail(`${where}.kind '${r.kind}' is unknown`, `use one of ${KINDS.join(' | ')}`);
+  if (!(Number.isFinite(r.scaleMetres) && r.scaleMetres > 0))
+    fail(
+      `${where}.scaleMetres is ${r.scaleMetres}`,
+      'set the metres the strip V span represents, > 0 (e.g. 0.6 for brick)',
+    );
+  if (!unit(r.roughness)) fail(`${where}.roughness is ${r.roughness}`, 'roughness is 0..1');
+  if (r.metalness !== undefined && !unit(r.metalness))
+    fail(`${where}.metalness is ${r.metalness}`, 'metalness is 0..1');
+  for (const [k, v] of Object.entries(r.params ?? {}))
+    if (!Number.isFinite(v)) fail(`${where}.params.${k} is ${v}`, 'params are finite numbers');
+}
+
+export function validateSheet(recipe: SheetRecipe): void {
+  if (!Number.isInteger(recipe.seed)) fail(`seed ${recipe.seed}`, 'seed is an integer');
+  if (recipe.size !== undefined && !SIZES.includes(recipe.size))
+    fail(`size ${recipe.size}`, 'size is 512, 1024 or 2048');
+  for (const [id, r] of Object.entries(recipe.strips)) {
+    if (!(STRIPS as readonly string[]).includes(id))
+      fail(`strip '${id}' is not in the layout`, `strips are ${STRIPS.join(', ')}`);
+    if (r) validateStrip(`strips.${id}`, r);
+  }
+  for (const [id, e] of Object.entries(recipe.cells ?? {})) {
+    if (!(CELLS as readonly string[]).includes(id))
+      fail(`cell '${id}' is not in the layout`, `cells are ${CELLS.join(', ')}`);
+    if (!e) continue;
+    if ('image' in e) {
+      if (!((e as CellImage).image instanceof Uint8Array))
+        fail(`cells.${id}.image is not bytes`, 'pass PNG file bytes as a Uint8Array');
+    } else validateStrip(`cells.${id}`, e);
+  }
+}

package/src/material/palette.ts

@@ -0,0 +1,43 @@
+// Colour lives in vertex colour (linear RGB), multiplied over the greyscale trim sheet: a palette
+// swap is a recipe edit, never a new texture.
+
+import type { Vec3 } from '../core/index.ts';
+
+export type Palette = Readonly<Record<string, Vec3>>;
+
+/** sRGB hex → linear RGB, the space glTF vertex colours are in. */
+export function hex(value: string): Vec3 {
+  const n = Number.parseInt(value.replace('#', ''), 16);
+  const lin = (c: number): number => {
+    const s = c / 255;
+    return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return [lin((n >> 16) & 255), lin((n >> 8) & 255), lin(n & 255)];
+}
+
+export function definePalette(entries: Readonly<Record<string, string>>): Palette {
+  return Object.fromEntries(Object.entries(entries).map(([k, v]) => [k, hex(v)]));
+}
+
+/** Era/region palettes ship as data; recipes extend them with object spread. */
+export const palettes = {
+  victorianRail: definePalette({
+    paint: '#2f4a3a',
+    trim: '#b08d57',
+    iron: '#2b2b2e',
+    brass: '#c9a24a',
+    red: '#7a2a22',
+  }),
+  artDeco: definePalette({
+    limestone: '#d8cfbd',
+    steel: '#9aa3ad',
+    glass: '#4a6a80',
+    bronze: '#8a6a3c',
+  }),
+  modernGlass: definePalette({
+    glass: '#6f8fa8',
+    aluminium: '#c4c9cf',
+    concrete: '#a7a39b',
+  }),
+  harbour: definePalette({ hull: '#1f2f45', deck: '#8a6f4e', white: '#e8e6df', red: '#a1302a' }),
+} as const;

package/src/material/shader-godot.ts

@@ -0,0 +1,77 @@
+// The Godot 4 emitter behind `godotShaderSource`: prints a spatial .gdshader with the same uniforms
+// as the three.js module. Values come pre-validated from shader.ts.
+
+import type { ShaderParams } from './shader.ts';
+import type { UvRect } from './trim-sheet.ts';
+
+const f = (n: number): string => (Number.isInteger(n) ? `${n}.0` : `${+n.toFixed(6)}`);
+const rect = (r: UvRect): string =>
+  `in_rect(UV, vec4(${f(r.u0)}, ${f(r.v0)}, ${f(r.u1)}, ${f(r.v1)}))`;
+
+export function godotSource(p: ShaderParams): string {
+  const modes = ['blend_mix', 'depth_draw_opaque', p.cutout ? 'cull_disabled' : 'cull_back'];
+  const weight = p.windAttribute
+    ? 'CUSTOM0.x /* import _WIND into CUSTOM0 (glTF import: custom attribute mapping) */'
+    : 'smoothstep(0.0, wind_height, VERTEX.z)';
+  return `// Generated by @developerz.ai/ts23d godotShaderSource(). A starting point your project owns:
+// assign it to a ShaderMaterial and set albedo_tex / normal_tex / orm_tex from the GLB's
+// ts23d_* material (or the shared trim_sheet_{albedo,normal,orm}.png). Godot 4.x.
+shader_type spatial;
+render_mode ${modes.join(', ')};
+
+uniform sampler2D albedo_tex : source_color, filter_linear_mipmap, repeat_enable;
+uniform sampler2D normal_tex : hint_normal, filter_linear_mipmap, repeat_enable;
+uniform sampler2D orm_tex : hint_default_white, filter_linear_mipmap, repeat_enable;
+
+uniform float night : hint_range(0.0, 1.0) = 0.0;
+uniform float wind_strength = ${f(p.windStrength)};
+uniform float wind_height = ${f(p.windHeight)};
+uniform float wind_hz = ${f(p.windHz)};
+uniform vec3 glow_color : source_color = vec3(${f(p.glow[0])}, ${f(p.glow[1])}, ${f(p.glow[2])});
+uniform float glow_ratio : hint_range(0.0, 1.0) = ${f(p.glowRatio)};
+uniform float glow_intensity = ${f(p.glowIntensity)};
+uniform float wear : hint_range(0.0, 1.0) = ${f(p.wear)};
+uniform float grime_height = ${f(p.grimeHeight)};
+
+varying vec3 world_pos;
+
+float in_rect(vec2 uv, vec4 r) {
+	float u = fract(uv.x);
+	return step(r.x, u) * step(u, r.z) * step(r.y, uv.y) * step(uv.y, r.w);
+}
+
+float hash13(vec3 p) {
+	p = fract(p * 0.1031);
+	p += dot(p, p.zyx + 31.32);
+	return fract((p.x + p.y) * p.z);
+}
+
+void vertex() {
+	// Wind sway: mesh-local Z is the authored up axis; sway in local XY.
+	float weight = ${weight};
+	float phase = VERTEX.x * 0.7 + VERTEX.y * 0.45;
+	float sway = sin(TIME * wind_hz * 6.2832 + phase) * wind_strength * weight * 0.1;
+	VERTEX.xy += vec2(sway, sway * 0.6);
+	world_pos = (MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz;
+}
+
+void fragment() {
+	vec4 base = texture(albedo_tex, UV);
+	vec3 orm = texture(orm_tex, UV).rgb;
+	float ground = 1.0 - smoothstep(0.0, grime_height, world_pos.y);
+	float grime = clamp(wear * max((1.0 - orm.r) * 1.5, ground), 0.0, 1.0);
+	ALBEDO = base.rgb * COLOR.rgb * (1.0 - grime * 0.45);
+	AO = orm.r;
+	ROUGHNESS = clamp(orm.g + grime * 0.2, 0.0, 1.0);
+	METALLIC = orm.b * (1.0 - grime);
+	NORMAL_MAP = texture(normal_tex, UV).rgb;
+${p.cutout ? '\tALPHA = base.a;\n\tALPHA_SCISSOR_THRESHOLD = 0.5;\n' : p.blend ? '\tALPHA = base.a * 0.6;\n' : ''}
+	// Window glow: dark panes in window cells, or the glass strip; 1.5 m world slots, glow_ratio lit.
+	float luma = dot(base.rgb, vec3(0.2126, 0.7152, 0.0722));
+	float panes = (${p.glowRects.map(rect).join(' + ')}) * step(luma, 0.3);
+	float mask = max(panes, ${rect(p.glassRect)});
+	float lit = step(hash13(floor(world_pos / 1.5)), glow_ratio);
+	EMISSION = glow_color * mask * lit * night * glow_intensity;
+}
+`;
+}

package/src/material/shader-three.ts

@@ -0,0 +1,103 @@
+// The three.js TSL emitter behind `threeMaterialSource`: prints a self-contained TypeScript module
+// for three r18x (`three/webgpu` + `three/tsl`). Values come pre-validated from shader.ts.
+
+import type { ShaderParams } from './shader.ts';
+import type { UvRect } from './trim-sheet.ts';
+
+const f = (n: number): string => (Number.isInteger(n) ? `${n}.0` : `${+n.toFixed(6)}`);
+
+const rectNode = (r: UvRect): string => `inRect(${f(r.u0)}, ${f(r.v0)}, ${f(r.u1)}, ${f(r.v1)})`;
+
+export function threeSource(p: ShaderParams): string {
+  const weight = p.windAttribute
+    ? "attribute('_wind', 'float')"
+    : 'smoothstep(float(0), uWindHeight, positionLocal.z)';
+  const glowCells = p.glowRects.map(rectNode).join('.add(') + ')'.repeat(p.glowRects.length - 1);
+  return `// Generated by @developerz.ai/ts23d threeMaterialSource(). A starting point your project owns:
+// edit freely. Needs three r18x (WebGPURenderer + TSL). ts23d itself has no three dependency.
+//
+// Usage: const gltf = await loader.loadAsync('tank.glb'); upgradeTrimMaterials(gltf.scene);
+//        trim.uniforms.night.value = 1; // at dusk
+
+import { DoubleSide, type Material, type Mesh, MeshStandardMaterial, MeshStandardNodeMaterial, type Object3D, type Texture } from 'three/webgpu';
+import { attribute, color, float, floor, fract, hash, max, normalMap, positionLocal, positionWorld, sin, smoothstep, step, texture, time, uniform, uv, vec3, vertexColor } from 'three/tsl';
+
+export interface TrimMaps {
+  readonly albedo: Texture;
+  readonly normal: Texture | null;
+  readonly orm: Texture | null;
+}
+
+/** Shared uniforms: one set drives every trim material, so a scene-wide night switch is one write. */
+export const uniforms = {
+  night: uniform(0),
+  windStrength: uniform(${f(p.windStrength)}),
+  windHeight: uniform(${f(p.windHeight)}),
+  windHz: uniform(${f(p.windHz)}),
+  glowColor: uniform(color(${f(p.glow[0])}, ${f(p.glow[1])}, ${f(p.glow[2])})),
+  glowRatio: uniform(${f(p.glowRatio)}),
+  glowIntensity: uniform(${f(p.glowIntensity)}),
+  wear: uniform(${f(p.wear)}),
+  grimeHeight: uniform(${f(p.grimeHeight)}),
+};
+
+/** 1 inside a trim-sheet UV rect (U wraps: strips tile along U). */
+function inRect(u0: number, v0: number, u1: number, v1: number) {
+  const t = uv();
+  const u = fract(t.x);
+  return step(u0, u).mul(step(u, u1)).mul(step(v0, t.y)).mul(step(t.y, v1));
+}
+
+export function createTrimMaterial(maps: TrimMaps, cutout = ${p.cutout}): MeshStandardNodeMaterial {
+  const { night, windStrength: uWindStrength, windHeight: uWindHeight, windHz, glowColor, glowRatio, glowIntensity, wear, grimeHeight } = uniforms;
+  const m = new MeshStandardNodeMaterial();
+  const base = texture(maps.albedo, uv());
+  const orm = maps.orm ? texture(maps.orm, uv()) : vec3(1, 0.8, 0);
+  const tint = vertexColor();
+
+  // Wear / grime: cavities (low AO) and the first metres above the ground get darker and rougher.
+  const ground = float(1).sub(smoothstep(float(0), grimeHeight, positionWorld.y));
+  const grime = wear.mul(max(float(1).sub(orm.x).mul(1.5), ground)).clamp(0, 1);
+  m.colorNode = base.rgb.mul(tint.rgb).mul(float(1).sub(grime.mul(0.45)));
+  m.roughnessNode = orm.y.add(grime.mul(0.2)).clamp(0, 1);
+  m.metalnessNode = orm.z.mul(float(1).sub(grime));
+  m.aoNode = orm.x;
+  if (maps.normal) m.normalNode = normalMap(texture(maps.normal, uv()));
+  if (cutout) {
+    m.opacityNode = base.a;
+    m.alphaTest = 0.5;
+    m.side = DoubleSide;
+  }
+
+  // Wind sway (authored Z-up, so sway in local XY), phase-shifted across the crown.
+  const windWeight = ${weight};
+  const phase = positionLocal.x.mul(0.7).add(positionLocal.y.mul(0.45));
+  const sway = sin(time.mul(windHz).mul(6.2832).add(phase)).mul(uWindStrength).mul(windWeight).mul(0.1);
+  m.positionNode = positionLocal.add(vec3(sway, sway.mul(0.6), 0));
+
+  // Window glow: dark pane texels in window cells, or the glass strip; a world-space hash lights
+  // \`glowRatio\` of the 1.5 m window slots; scaled by \`night\`.
+  const luma = base.r.mul(0.2126).add(base.g.mul(0.7152)).add(base.b.mul(0.0722));
+  const panes = ${glowCells}.mul(step(luma, 0.3));
+  const mask = max(panes, ${rectNode(p.glassRect)});
+  const slot = floor(positionWorld.div(1.5));
+  const lit = step(hash(slot.x.mul(73).add(slot.y.mul(157)).add(slot.z.mul(311))), glowRatio);
+  m.emissiveNode = glowColor.mul(mask).mul(lit).mul(night).mul(glowIntensity);
+  return m;
+}
+
+/** Replace every ts23d_* material under \`root\` with the node material, reusing the GLB's maps. */
+export function upgradeTrimMaterials(root: Object3D): void {
+  const cache = new Map<Material, MeshStandardNodeMaterial>();
+  root.traverse((o) => {
+    const mesh = o as Mesh;
+    const old = mesh.isMesh ? mesh.material : null;
+    if (!(old instanceof MeshStandardMaterial) || !old.name.startsWith('ts23d') || !old.map) return;
+    const next = cache.get(old) ?? createTrimMaterial({ albedo: old.map, normal: old.normalMap, orm: old.roughnessMap }, old.alphaTest > 0);
+    next.name = old.name;
+    cache.set(old, next);
+    mesh.material = next;
+  });
+}
+`;
+}