@developerz.ai/ts23d 0.0.0-stage → 0.2.0

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,48 @@
+// Dispatch a StripRecipe to its painter, then the shared grime pass (`params.grime`, 0..1), then
+// the recipe's own `paint` layer (project materials), checked for finite output. A `texture`
+// recipe paints from its cached CC0 image set instead of a kind (no grime: the photo has its own).
+
+import { paintBond } from './bond.ts';
+import type { Canvas } from './canvas.ts';
+import { param } from './canvas.ts';
+import { paintConcrete } from './concrete.ts';
+import { paintLeather, paintWeave } from './fabric.ts';
+import { paintImageStrip } from './image-strip.ts';
+import { checkFinite, paintKit } from './kit.ts';
+import { grime } from './masks.ts';
+import { paintMetal } from './metal.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 { StripKind, StripRecipe } from './types.ts';
+
+type Painter = (c: Canvas, r: StripRecipe, seed: number) => void;
+
+const PAINTERS: Readonly<Record<StripKind, Painter>> = {
+  bond: paintBond,
+  planks: paintPlanks,
+  plates: paintPlates,
+  slate: paintSlate,
+  concrete: paintConcrete,
+  metal: paintMetal,
+  weave: paintWeave,
+  leather: paintLeather,
+  noise: paintNoise,
+  glass: paintGlass,
+  flat: (c, r) => paintFlat(c, r),
+};
+
+export function paintStrip(c: Canvas, r: StripRecipe, seed: number, where = 'strip'): void {
+  if (r.texture) paintImageStrip(c, r, r.texture, where);
+  else {
+    if (r.albedo || r.albedo2)
+      c.colours = [r.albedo ?? [1, 1, 1], r.albedo2 ?? r.albedo ?? [1, 1, 1]];
+    PAINTERS[r.kind](c, r, seed);
+    if (r.kind !== 'glass' && r.kind !== 'flat') grime(c, param(r.params, 'grime', 0), seed + 101);
+  }
+  if (r.paint) {
+    r.paint(c, paintKit(c, seed + 211));
+    checkFinite(c, where);
+  }
+}

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,94 @@
+// The generator's public data contract (re-exported by generator.ts): what a sheet recipe says
+// and what the painter returns.
+
+import type { Vec3 } from '../../core/index.ts';
+import type { TextureSource } from '../texture-source.ts';
+import type { CellId, StripId } from '../trim-sheet.ts';
+import type { Canvas } from './canvas.ts';
+
+export interface PaintedSheet {
+  readonly size: number;
+  /** RGBA8, sRGB. Classic strips are greyscale (vertex colour carries hue); materials carry colour. */
+  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'
+  | 'metal'
+  | 'weave'
+  | 'leather';
+
+/**
+ * The surface a painter writes, one float per texel per layer, in real metres. Row y grows with
+ * world up (+V); strips wrap along x. Layers: `height` (metres, + is out), `tone` (linear
+ * brightness multiplier), `rough` and `metal` (0–1), `mix` (0 = albedo, 1 = albedo2), `occl`.
+ */
+export type MaterialSurface = Canvas;
+
+/** Helpers handed to a custom painter: seeded, tileable noise and smoothstep, all in metres. */
+export interface PaintKit {
+  readonly seed: number;
+  /** Tileable fBm in [−1, 1] with feature size `sizeU` × `sizeV` metres; `salt` varies it. */
+  noise(
+    xm: number,
+    ym: number,
+    sizeU: number,
+    sizeV: number,
+    salt?: number,
+    octaves?: number,
+  ): number;
+  /** Integer hash in [0, 1). */
+  hash(a: number, b: number, salt?: number): number;
+  smooth(e0: number, e1: number, v: number): number;
+  /** Visit every texel: index into the layers and its centre in metres. */
+  each(fn: (i: number, xm: number, ym: number) => void): void;
+}
+
+/** A project painter: runs after the base `kind`, layering its own pattern over it. */
+export type MaterialPainter = (s: MaterialSurface, kit: PaintKit) => void;
+
+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>>;
+  /** Intrinsic linear albedo; omitted = white (greyscale strip, vertex colour carries hue). */
+  readonly albedo?: Vec3;
+  /** Second linear albedo the painter blends to through `mix` (latewood, rust, bare wood…). */
+  readonly albedo2?: Vec3;
+  /** Extra layer painted after `kind` (see `defineMaterial`). */
+  readonly paint?: MaterialPainter;
+  /** Paint from a cached CC0 texture set instead of `kind` (see texture-source.ts). */
+  readonly texture?: TextureSource;
+}
+
+/** 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,74 @@
+// Recipe validation: every bad input throws T3D_RECIPE_INVALID with the fix, before any painting.
+
+import { Ts23dError } from '../../core/index.ts';
+import { CELLS, STRIPS, stripRow } 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',
+  'metal',
+  'weave',
+  'leather',
+];
+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 key of ['albedo', 'albedo2'] as const) {
+    const a = r[key];
+    if (a !== undefined && !(a.length === 3 && a.every(unit)))
+      fail(
+        `${where}.${key} is [${a}]`,
+        `${key} is linear RGB, three numbers 0..1 (use hex('#rrggbb'))`,
+      );
+  }
+  if (r.paint !== undefined && typeof r.paint !== 'function')
+    fail(`${where}.paint is not a function`, 'paint is (surface, kit) => void');
+  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 (stripRow(id) < 0)
+      fail(
+        `strip '${id}' is not in the layout`,
+        `strips are ${STRIPS.join(', ')} or a defineMaterial() id`,
+      );
+    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,46 @@
+// 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)];
+}
+
+/** Vertex colour for material strips that carry their own colour (oak, brass, rubber…). */
+export const NATURAL: Vec3 = [1, 1, 1];
+
+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;
+  });
+}
+`;
+}

package/src/material/shader.ts

@@ -0,0 +1,100 @@
+// Engine shader sources for the trim-sheet material: per-asset effects that stay on the one shared
+// material — vertex-colour tint, wind sway, night window glow, wear/grime. Both functions return
+// plain source strings (a three.js TSL module, a Godot 4 .gdshader). They are STARTING POINTS an
+// engine project loads and owns, not runtime dependencies: ts23d never imports three or Godot.
+//
+// Shared conventions both sources implement:
+//   tint      albedo.rgb × COLOR_0.rgb (linear), alpha from albedo.a (cutout leaf masks)
+//   ORM       R occlusion · G roughness · B metalness (one texture, as the GLB binds it)
+//   wind      weight from the `_WIND` vertex attribute (three: `_wind`) or, by default, the
+//             mesh-local height (authored Z-up), smoothstep(0, wind.height, z); sway in local XY
+//   glow      emissive on window panes: window_sash/porthole texels darker than luma 0.3, and the
+//             whole glass strip; a world-space 1.5 m hash lights `ratio` of windows; × `night`
+//   wear      darkens + roughens cavities (1 − AO) and the first `grimeHeight` metres of world height
+
+import type { Surface } from '../core/index.ts';
+import { Ts23dError } from '../core/index.ts';
+import { godotSource } from './shader-godot.ts';
+import { threeSource } from './shader-three.ts';
+import { cellRect, stripRect, type UvRect } from './trim-sheet.ts';
+
+export interface ShaderHints {
+  /** Vertex sway for vegetation. Weight from the `_WIND` attribute or mesh-local height. */
+  readonly wind?: {
+    readonly strength: number;
+    readonly source?: 'attribute' | 'height';
+    /** Metres of height at which sway reaches full weight (height source). Default 4. */
+    readonly height?: number;
+    readonly hz?: number;
+  };
+  /** Emissive mask on window cells at night: `ratio` of windows lit. */
+  readonly windowGlow?: {
+    readonly color: string;
+    readonly ratio: number;
+    readonly intensity?: number;
+  };
+  /** Wear/grime mask strength 0..1 and how high ground grime climbs (metres). */
+  readonly wear?: { readonly amount: number; readonly grimeHeight?: number };
+  /** The surface the material is for: 'cutout' adds alpha test + double-sided. */
+  readonly surface?: Surface;
+}
+
+/** Resolved, validated numbers both emitters print. */
+export interface ShaderParams {
+  readonly windStrength: number;
+  readonly windAttribute: boolean;
+  readonly windHeight: number;
+  readonly windHz: number;
+  readonly glow: readonly [number, number, number];
+  readonly glowRatio: number;
+  readonly glowIntensity: number;
+  readonly wear: number;
+  readonly grimeHeight: number;
+  readonly cutout: boolean;
+  readonly blend: boolean;
+  readonly glowRects: readonly UvRect[];
+  readonly glassRect: UvRect;
+}
+
+function fail(cause: string, fix: string): never {
+  throw new Ts23dError('T3D_RECIPE_INVALID', { cause: `shader hints: ${cause}`, fix });
+}
+
+function srgbHex(value: string): [number, number, number] {
+  if (!/^#[0-9a-fA-F]{6}$/.test(value)) fail(`colour '${value}'`, "use '#rrggbb' sRGB hex");
+  const n = Number.parseInt(value.slice(1), 16);
+  return [((n >> 16) & 255) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255];
+}
+
+export function resolveHints(h: ShaderHints): ShaderParams {
+  const unit = (v: number, what: string): number =>
+    Number.isFinite(v) && v >= 0 && v <= 1 ? v : fail(`${what} is ${v}`, `${what} is 0..1`);
+  const pos = (v: number, what: string): number =>
+    Number.isFinite(v) && v > 0 ? v : fail(`${what} is ${v}`, `${what} is a positive number`);
+  const strength = h.wind ? pos(h.wind.strength, 'wind.strength') : 0;
+  return {
+    windStrength: strength,
+    windAttribute: h.wind?.source === 'attribute',
+    windHeight: pos(h.wind?.height ?? 4, 'wind.height'),
+    windHz: pos(h.wind?.hz ?? 0.4, 'wind.hz'),
+    glow: h.windowGlow ? srgbHex(h.windowGlow.color) : [1, 0.75, 0.4],
+    glowRatio: h.windowGlow ? unit(h.windowGlow.ratio, 'windowGlow.ratio') : 0,
+    glowIntensity: pos(h.windowGlow?.intensity ?? 2, 'windowGlow.intensity'),
+    wear: h.wear ? unit(h.wear.amount, 'wear.amount') : 0,
+    grimeHeight: pos(h.wear?.grimeHeight ?? 0.6, 'wear.grimeHeight'),
+    cutout: h.surface === 'cutout',
+    blend: h.surface === 'glass' || h.surface === 'translucent',
+    glowRects: [cellRect('window_sash'), cellRect('porthole')],
+    glassRect: stripRect('glass'),
+  };
+}
+
+/** A three.js (r18x, WebGPU/TSL) TypeScript module: `createTrimMaterial(maps)` + `upgradeTrimMaterials(root)`. */
+export function threeMaterialSource(hints: ShaderHints = {}): string {
+  return threeSource(resolveHints(hints));
+}
+
+/** A Godot 4 spatial shader (.gdshader) with the same features and uniform names. */
+export function godotShaderSource(hints: ShaderHints = {}): string {
+  return godotSource(resolveHints(hints));
+}

package/src/material/slots.ts

@@ -0,0 +1,18 @@
+// The custom-strip slot table: ids registered by `defineMaterial`, in registration order. A leaf
+// module (no imports) so the layout (trim-sheet.ts) and the registry (registry.ts) can both read it.
+
+const custom: string[] = [];
+
+/** Slot index among the custom strips, or −1. */
+export const customIndex = (id: string): number => custom.indexOf(id);
+
+export const customIds = (): readonly string[] => custom;
+
+export function pushCustom(id: string): number {
+  custom.push(id);
+  return custom.length - 1;
+}
+
+export function clearCustom(): void {
+  custom.length = 0;
+}