@developerz.ai/ts23d 0.1.0 → 0.2.0

package/src/material/paint/validate.ts

@@ -1,7 +1,7 @@
 // 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 { CELLS, STRIPS, stripRow } from '../trim-sheet.ts';
 import type { CellImage, SheetRecipe, StripKind, StripRecipe } from './types.ts';
 
 const KINDS: readonly StripKind[] = [
@@ -13,6 +13,9 @@ const KINDS: readonly StripKind[] = [
   'slate',
   'concrete',
   'glass',
+  'metal',
+  'weave',
+  'leather',
 ];
 const SIZES = [512, 1024, 2048];
 
@@ -33,6 +36,16 @@ export function validateStrip(where: string, r: StripRecipe): void {
   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');
 }
@@ -42,8 +55,11 @@ export function validateSheet(recipe: SheetRecipe): void {
   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 (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 ?? {})) {

package/src/material/palette.ts

@@ -15,6 +15,9 @@ export function hex(value: string): Vec3 {
   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)]));
 }

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;
+}

package/src/material/texture-source.ts

@@ -0,0 +1,86 @@
+// Image-backed strips: a CC0 PBR texture set (Poly Haven, ambientCG or a local file) declared as
+// data — URL + sha256 per map, licence, author page, real-world size. Compile and paint stay
+// offline: bytes come only from a content-addressed cache the caller provides (`provideTextures`,
+// filled by `bun run textures`); a missing map throws T3D_TEXTURE_MISSING with that command.
+
+import { Ts23dError } from '../core/index.ts';
+
+export interface TextureFile {
+  /** Download URL (https) or, for `source: 'file'`, a path relative to the working directory. */
+  readonly url: string;
+  /** Lower-case hex sha256 of the file's bytes: the cache key and the integrity check. */
+  readonly sha256: string;
+}
+
+export interface TextureSource {
+  readonly source: 'polyhaven' | 'ambientcg' | 'file';
+  /** The set's id at the source, e.g. 'wood_planks_grey'. */
+  readonly id: string;
+  /** Only public-domain sets are accepted, so a generated asset never inherits a licence duty. */
+  readonly license: 'CC0-1.0';
+  /** Human page crediting the set (goes into the GLB's XMP credits). */
+  readonly page: string;
+  readonly author?: string;
+  /** Real-world size the image covers, metres (U × V). Poly Haven lists it as `dimensions`. */
+  readonly metres: readonly [number, number];
+  readonly maps: {
+    /** sRGB base colour. */
+    readonly albedo: TextureFile;
+    /** Tangent-space normal, OpenGL convention (+Y up in the image; Poly Haven `nor_gl`). */
+    readonly normal?: TextureFile;
+    /** Packed AO / roughness / metalness (Poly Haven `arm`, glTF ORM order). */
+    readonly arm?: TextureFile;
+  };
+}
+
+/** PNG bytes by sha256. */
+export type TextureCache = ReadonlyMap<string, Uint8Array>;
+
+const SHA = /^[0-9a-f]{64}$/;
+const provided = new Map<string, Uint8Array>();
+
+/** Hand verified texture bytes to the painter (e.g. from `loadTextureCache()` in scripts). */
+export function provideTextures(cache: TextureCache): void {
+  for (const [k, v] of cache) provided.set(k, v);
+}
+
+export function textureBytes(file: TextureFile, where: string): Uint8Array {
+  const hit = provided.get(file.sha256);
+  if (hit) return hit;
+  throw new Ts23dError('T3D_TEXTURE_MISSING', {
+    cause: `${where}: texture ${file.url} (sha256 ${file.sha256.slice(0, 12)}…) is not in the cache`,
+    fix: 'run `bun run textures <module defining the material>` once (downloads + verifies into node_modules/.cache/ts23d/textures), then provideTextures(await loadTextureCache()) before painting',
+  });
+}
+
+export function validateTexture(id: string, t: TextureSource): void {
+  const fail = (cause: string, fix: string): never => {
+    throw new Ts23dError('T3D_MATERIAL_INVALID', { cause: `material '${id}': ${cause}`, fix });
+  };
+  if (!['polyhaven', 'ambientcg', 'file'].includes(t.source))
+    fail(`texture.source '${t.source}'`, "use 'polyhaven', 'ambientcg' or 'file'");
+  if (t.license !== 'CC0-1.0')
+    fail(
+      `texture.license '${t.license}'`,
+      'only CC0-1.0 sets are accepted (Poly Haven and ambientCG are CC0)',
+    );
+  if (!(t.metres.length === 2 && t.metres.every((m) => Number.isFinite(m) && m > 0)))
+    fail(`texture.metres [${t.metres}]`, 'give the real size the image covers, e.g. [1.5, 1.5]');
+  for (const [map, f] of Object.entries(t.maps)) {
+    if (!f) continue;
+    if (!SHA.test(f.sha256))
+      fail(
+        `texture.maps.${map}.sha256 '${f.sha256}'`,
+        'lower-case hex sha256 of the file (sha256sum)',
+      );
+    if (!/\.png$/i.test(f.url))
+      fail(
+        `texture.maps.${map}.url '${f.url}'`,
+        'use the PNG download (8- or 16-bit); JPEG is not decoded',
+      );
+  }
+}
+
+/** One credit line for the GLB's XMP and the docs. */
+export const creditOf = (t: TextureSource): string =>
+  `${t.id}${t.author ? ` by ${t.author}` : ''} (${t.source}, ${t.license}) ${t.page}`;

package/src/material/trim-sheet.ts

@@ -1,9 +1,15 @@
-// The shared trim sheet: ONE 1024² atlas (albedo + normal + ORM) every asset maps into, so every
+// The shared trim sheet: ONE 2048² atlas (albedo + normal + ORM) every asset maps into, so every
 // asset is one material and one draw call. Strips tile along U; cells are fixed decals.
 // Layout is data here; `paintTrimSheet` (generator.ts) paints it. V grows with world up on
-// box/planar faces. Foliage cells (cutout leaf cards, alpha = leaf mask) sit in their own rows.
+// box/planar faces. V 0–0.875 holds 28 strip rows (64 px each at 2048²): the 8 original strips,
+// 16 physically distinct materials (woods, metals, rubber, canvas, leather, plastic) and 4 slots
+// for project materials (`defineMaterial`). V 0.875–1 holds 128 px cells: decals, then foliage.
 
-export type StripId =
+import { Ts23dError } from '../core/index.ts';
+import { customIndex } from './slots.ts';
+
+/** The original eight strips: greyscale, tinted by vertex colour. */
+export type ClassicStripId =
   | 'plain'
   | 'brick'
   | 'stone'
@@ -12,6 +18,28 @@ export type StripId =
   | 'wood'
   | 'glass'
   | 'concrete';
+/** Material strips with measured colour: use a near-white vertex colour (`NATURAL`) for truth. */
+export type MaterialStripId =
+  | 'oak'
+  | 'pine'
+  | 'wood_weathered'
+  | 'wood_painted'
+  | 'iron_rust'
+  | 'iron_cast'
+  | 'steel_painted'
+  | 'steel_galvanised'
+  | 'brass'
+  | 'copper'
+  | 'aluminium'
+  | 'chrome'
+  | 'rubber'
+  | 'canvas'
+  | 'leather'
+  | 'plastic';
+export type BuiltinStripId = ClassicStripId | MaterialStripId;
+/** A project material's id, as returned by `defineMaterial` (a branded string). */
+export type CustomStripId = string & { readonly __ts23dMaterial: true };
+export type StripId = BuiltinStripId | CustomStripId;
 export type DecalCellId = 'window_sash' | 'door_panel' | 'clock' | 'smokebox' | 'sign' | 'porthole';
 /** Cutout leaf cards: the anchor (twig base) is the cell's bottom-centre, growth toward +V. */
 export type FoliageCellId =
@@ -37,8 +65,10 @@ export interface UvRect {
   readonly metres: number;
 }
 
-const STRIP_H = 1 / 16;
-const strips: readonly StripId[] = [
+/** Strip rows in the atlas: built-ins first, then `CUSTOM_STRIP_SLOTS` project materials. */
+export const STRIP_ROWS = 28;
+const STRIP_H = 1 / 32;
+const classic: readonly ClassicStripId[] = [
   'plain',
   'brick',
   'stone',
@@ -48,6 +78,26 @@ const strips: readonly StripId[] = [
   'glass',
   'concrete',
 ];
+const material: readonly MaterialStripId[] = [
+  'oak',
+  'pine',
+  'wood_weathered',
+  'wood_painted',
+  'iron_rust',
+  'iron_cast',
+  'steel_painted',
+  'steel_galvanised',
+  'brass',
+  'copper',
+  'aluminium',
+  'chrome',
+  'rubber',
+  'canvas',
+  'leather',
+  'plastic',
+];
+const strips: readonly BuiltinStripId[] = [...classic, ...material];
+export const CUSTOM_STRIP_SLOTS = STRIP_ROWS - strips.length;
 const decals: readonly DecalCellId[] = [
   'window_sash',
   'door_panel',
@@ -70,30 +120,46 @@ const foliage: readonly FoliageCellId[] = [
   'foliage_needles',
 ];
 const cells: readonly CellId[] = [...decals, ...foliage];
-/** Decals fill row 0 of the cell region (V 0.5); foliage starts on row 1 (V 0.625). */
+/** Cells are 1/16 of the sheet, 16 per row from V 0.875: decals at 0–5, foliage from slot 8. */
+const CELL = 1 / 16;
+const CELL_V0 = STRIP_ROWS * STRIP_H;
 const FOLIAGE_SLOT = 8;
 const slotOf = (id: CellId): number => {
   const d = decals.indexOf(id as DecalCellId);
   return d >= 0 ? d : FOLIAGE_SLOT + foliage.indexOf(id as FoliageCellId);
 };
 
-export const TRIM_SHEET_SIZE = 1024;
+export const TRIM_SHEET_SIZE = 2048;
+
+/** Atlas row of a strip id, or −1 when it is neither built in nor defined. */
+export function stripRow(id: string): number {
+  const b = strips.indexOf(id as BuiltinStripId);
+  if (b >= 0) return b;
+  const c = customIndex(id);
+  return c >= 0 ? strips.length + c : -1;
+}
 
 export function stripRect(id: StripId): UvRect {
-  const i = strips.indexOf(id);
+  const i = stripRow(id);
+  if (i < 0)
+    throw new Ts23dError('T3D_MATERIAL_UNKNOWN', {
+      cause: `strip '${id}' is neither built in nor defined`,
+      fix: `use a built-in strip (${strips.join(', ')}) or register it first with defineMaterial({ id: '${id}', ... })`,
+    });
   return { u0: 0, v0: i * STRIP_H, u1: 1, v1: (i + 1) * STRIP_H, metres: 2 };
 }
 
-/** Cells sit in the lower half (V ≥ 0.5), 8 per row: decals on row 0, foliage from row 1. */
 export function cellRect(id: CellId): UvRect {
   const i = slotOf(id);
-  const size = 1 / 8;
-  const u0 = (i % 8) * size;
-  const v0 = 0.5 + Math.floor(i / 8) * size;
-  return { u0, v0, u1: u0 + size, v1: v0 + size, metres: 1 };
+  const u0 = (i % 16) * CELL;
+  const v0 = CELL_V0 + Math.floor(i / 16) * CELL;
+  return { u0, v0, u1: u0 + CELL, v1: v0 + CELL, metres: 1 };
 }
 
+/** Every built-in strip, classic first. */
 export const STRIPS = strips;
+export const CLASSIC_STRIPS = classic;
+export const MATERIAL_STRIPS = material;
 export const CELLS = cells;
 export const DECAL_CELLS = decals;
 export const FOLIAGE_CELLS = foliage;

package/src/render/beauty.ts

@@ -29,7 +29,7 @@ export interface BeautyOptions {
   readonly fovDeg?: number;
   /** Samples per pixel edge (1–4). Default 2 (4 samples per pixel). */
   readonly supersample?: number;
-  /** The painted trim sheet; default paints `DEFAULT_SHEET` at 512² once per process. */
+  /** The painted trim sheet; default paints `DEFAULT_SHEET` at 1024² once per process. */
   readonly sheet?: PaintedSheet;
   /** Zoom into the default framing: window centre (0–1, 0–1) of the full shot and a zoom ≥ 1. */
   readonly window?: { readonly x: number; readonly y: number; readonly zoom: number };
@@ -51,7 +51,7 @@ export interface BeautyRender {
 let defaultSheet: PaintedSheet | undefined;
 const sheetOf = (o: BeautyOptions): PaintedSheet => {
   if (o.sheet) return o.sheet;
-  defaultSheet ??= paintTrimSheet({ ...DEFAULT_SHEET, size: 512 });
+  defaultSheet ??= paintTrimSheet({ ...DEFAULT_SHEET, size: 1024 });
   return defaultSheet;
 };
 

package/src/render/lighting.ts

@@ -48,6 +48,32 @@ export function studioRig(cameraAzDeg: number): Rig {
   };
 }
 
+const HORIZON: V3 = [0.82, 0.8, 0.76];
+const ZENITH: V3 = [0.3, 0.34, 0.44];
+const FLOOR: V3 = [0.3, 0.28, 0.26];
+const BAND = 0.12;
+
+/**
+ * The studio environment a reflection sees, channel `k`, along a reflection vector with up
+ * component `rz`: a bright cyclorama horizon fading to a cooler zenith, a dark band where the
+ * floor meets the wall, the lit floor below. Roughness pre-blurs it toward its mean, so polished
+ * metal shows the horizon line and rough metal a soft gradient — what makes metal read as metal.
+ */
+export function envRadiance(rz: number, rough: number, k: number): number {
+  const h = HORIZON[k] ?? 0;
+  const sharp =
+    rz >= 0
+      ? h + ((ZENITH[k] ?? 0) - h) * Math.sqrt(rz)
+      : rz > -0.3
+        ? h * BAND + ((FLOOR[k] ?? 0) - h * BAND) * Math.min(1, -rz / 0.3) ** 0.5
+        : (FLOOR[k] ?? 0);
+  const blurred = 0.5 * h + 0.25 * (ZENITH[k] ?? 0) + 0.25 * (FLOOR[k] ?? 0);
+  // Above the horizon the blur keeps a little of the up/down split so rough metal still shades.
+  const tilt = 1 + 0.25 * Math.max(-1, Math.min(1, rz * 2));
+  const t = Math.min(1, rough * 1.6);
+  return sharp + (blurred * tilt - sharp) * t;
+}
+
 /** Poisson-ish disc of 12 taps (texel offsets), radius ~1.6, rotated four ways for dithering. */
 const DISC: readonly (readonly [number, number])[] = [
   [-0.94, -0.4],

package/src/render/shade.ts

@@ -1,11 +1,12 @@
 // Per-pixel shading of the visibility buffer: reconstruct position, normal, UV and vertex colour
 // from (triangle, barycentrics), perturb by the trim sheet's normal map, then light it — key sun
 // with a PCF shadow, sky/bounce hemisphere × multi-direction AO × the sheet's baked occlusion,
-// and a roughness-driven specular (normalised Blinn–Phong + Schlick Fresnel).
+// a roughness-driven sun specular (normalised Blinn–Phong + Schlick Fresnel) and a studio
+// environment reflection (envRadiance) per texel from the sheet's ORM, so metal reads as metal.
 
 import type { PerspectiveCamera } from './camera.ts';
 import { type DepthMap, openness, visibility } from './depth-map.ts';
-import type { Rig } from './lighting.ts';
+import { envRadiance, type Rig } from './lighting.ts';
 import type { Scene } from './scene.ts';
 import { type SheetTextures, sample } from './texture.ts';
 
@@ -184,7 +185,10 @@ export function shadeSample(
   const shin = Math.min(2048, 2 / (rough * rough * rough * rough) - 2);
   const lobe = ((shin + 8) / 25.13) * ndh ** shin;
   const fr = (1 - vdh) ** 5;
-  const fe = (1 - ndv) ** 5 * (1 - rough) * (1 - rough);
+  const fv = (1 - ndv) ** 5;
+  // Image-based term: the studio seen along the reflection, occluded like the sky (+ cavity AO).
+  const rz = 2 * ndv * n2 - vz;
+  const specOcc = open * (0.4 + 0.6 * occ);
   const ch = [ar, ag, ab];
   for (let k = 0; k < 3; k++) {
     const al = ch[k] ?? 0;
@@ -192,8 +196,9 @@ export function shadeSample(
     const sky = (r.bounce[k] ?? 0) * (1 - hemi) + (r.sky[k] ?? 0) * hemi;
     const diffuse = al * dk * ((r.sunColor[k] ?? 0) * lit + sky * amb);
     const spec = (f0 + (1 - f0) * fr) * lobe * lit * (r.sunColor[k] ?? 0) * 0.8;
-    const env =
-      (f0 + (1 - f0) * fe) * (r.sky[k] ?? 0) * open * (glass ? 2.5 : 0.3 + 0.7 * (1 - rough));
+    const env = glass
+      ? (f0 + (1 - f0) * fv * (1 - rough) * (1 - rough)) * (r.sky[k] ?? 0) * open * 2.5
+      : (f0 + (Math.max(1 - rough, f0) - f0) * fv) * envRadiance(rz, rough, k) * specOcc;
     out[k] = (diffuse + spec + env) * r.exposure;
   }
 }