@homie-rocks/studio 0.21.0 → 0.23.0

package/lib/optimise.mjs

@@ -0,0 +1,380 @@
+/**
+ * MAKING A MODEL PHONE-SIZED, AND MEASURING IT (free, on this computer).
+ *
+ *   optimiseModel(input, { out, triangles, texture, height })   a raw .glb (a provider's, a pack's, the person's own)
+ *       becomes one shipped .glb: flat colours into one palette picture, one draw call where it can, the pivot at the
+ *       bottom centre, scaled to its size in metres, welded and simplified to its triangle budget (meshoptimizer),
+ *       pictures resized and re-encoded as WebP (sharp), meshopt geometry, nothing unused. Raw files are never
+ *       changed; the result says what each step did, before and after.
+ *   inspectModel(input)                       triangles, vertices, draw calls, materials, pictures and their GPU memory,
+ *       bones and clips, the bounding box in metres, the Khronos glTF-Validator's errors, and the file's own safety
+ *       check (assets/safety.mjs).
+ *   albedoOf(input)                           the model's dominant surface colours (k-means over its base-colour
+ *       pictures and flat colours, weighted by how much of it they cover): the palette-drift check reads them.
+ *
+ * The tools are @gltf-transform (MIT), meshoptimizer (MIT), the Khronos glTF-Validator (Apache-2.0) and sharp
+ * (Apache-2.0), all dependencies of @homie-rocks/studio, loaded only when a model command runs. Draco and KTX2 inputs
+ * are refused here (ask for a plain .glb); KTX2 output needs KTX-Software's toktx and is not offered in phase 1: WebP
+ * is the house default.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { LIMITS, checkGlb, readGlb } from '../assets/safety.mjs';
+import { dominant } from './colour.mjs';
+
+let tools = null;
+
+/** The glTF toolchain, loaded once: { core, ext, fn, mo, sharp, io, validator }. */
+export async function modelTools() {
+  if (tools) return tools;
+  let core; let ext; let fn; let mo;
+  try {
+    [core, ext, fn, mo] = await Promise.all([import('@gltf-transform/core'), import('@gltf-transform/extensions'), import('@gltf-transform/functions'), import('meshoptimizer')]);
+  } catch (error) {
+    throw new Error(`the model tools are not installed here (${error.message.split('\n')[0]}): run npm install in the studio, then this again`);
+  }
+  await Promise.all([mo.MeshoptEncoder.ready, mo.MeshoptDecoder.ready, mo.MeshoptSimplifier.ready]);
+  let sharp = null;
+  try { sharp = (await import('sharp')).default; } catch { sharp = null; }
+  let validator = null;
+  try { const v = await import('gltf-validator'); validator = v.default ?? v; } catch { validator = null; }
+  // Quiet: the steps report what they did in the result, never on the console.
+  const logger = new core.Logger(core.Logger.Verbosity.ERROR);
+  const io = new core.NodeIO().setLogger(logger).registerExtensions(ext.ALL_EXTENSIONS).registerDependencies({ 'meshopt.decoder': mo.MeshoptDecoder, 'meshopt.encoder': mo.MeshoptEncoder });
+  tools = { core, ext, fn, mo, sharp, io, validator, logger };
+  return tools;
+}
+
+const bytesOf = (input) => (input instanceof Uint8Array ? input : readFileSync(input));
+
+/**
+ * A model on disk whose pictures or buffers sit beside it (a pack's .glb naming "Textures/colormap.png", a .gltf
+ * with its .bin): its relative files are read from its own folder only (never "..", never an address, each within
+ * the import cap), and the result is one self-contained GLB. Anything else is refused as an external URI.
+ */
+async function readLocal(path, limits) {
+  const { io } = await modelTools();
+  const raw = readFileSync(path);
+  let json;
+  if (raw.subarray(0, 4).toString('latin1') === 'glTF') json = readGlb(raw, { maxJson: limits.json }).json;
+  else { try { json = JSON.parse(raw.toString('utf8')); } catch { throw new Error('not a glTF file (.glb or .gltf)'); } }
+  const dir = dirname(resolve(path));
+  const uris = [...(json.buffers ?? []), ...(json.images ?? [])].map((x) => x?.uri).filter((u) => typeof u === 'string' && !/^data:/i.test(u));
+  let total = raw.byteLength;
+  for (const u of uris) {
+    const rel = decodeURIComponent(u);
+    if (/^[a-z][a-z0-9+.-]*:/i.test(rel) || rel.startsWith('/') || rel.split(/[\\/]/).includes('..')) throw new Error(`refused: it loads ${u.slice(0, 60)} from an address or outside its folder (an external URI)`);
+    const abs = resolve(dir, rel);
+    if (!existsSync(abs)) throw new Error(`it names ${rel}, which is not beside it`);
+    total += statSync(abs).size;
+    if (total > limits.bytes) throw new Error(`it and its files are over ${Math.round(limits.bytes / 1024 / 1024)} MB`);
+  }
+  const doc = await io.read(path);
+  const { fn, logger } = await modelTools();
+  doc.setLogger(logger);
+  await doc.transform(fn.unpartition());
+  const bytes = await io.writeBinary(doc);
+  const safe = checkGlb(bytes, limits);
+  if (!safe.ok) throw new Error(`refused: ${safe.problems.slice(0, 4).join('; ')}`);
+  return { doc, safe, bytes };
+}
+
+/** Bytes of a model from a path (resolving its own sibling files) or from bytes: a self-contained GLB. */
+export async function selfContained(input, limits = LIMITS.import) {
+  if (input instanceof Uint8Array) return input;
+  const bytes = readFileSync(input);
+  if (checkGlb(bytes, limits).ok) return bytes;
+  return (await readLocal(input, limits)).bytes;
+}
+export const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const round = (n, d = 3) => +Number(n).toFixed(d);
+
+/** A Document from bytes, refusing what this pipeline cannot read (Draco, KTX2) in plain words. */
+async function readDoc(bytes, limits = LIMITS.import) {
+  const safe = checkGlb(bytes, limits);
+  if (!safe.ok) throw new Error(`refused: ${safe.problems.slice(0, 4).join('; ')}`);
+  const req = safe.info.extensions.required;
+  if (req.includes('KHR_draco_mesh_compression')) throw new Error('Draco-compressed geometry: export it again as a plain .glb (meshopt is applied here)');
+  if (req.includes('KHR_texture_basisu')) throw new Error('KTX2 pictures: export it again with PNG, JPEG or WebP pictures');
+  const { io } = await modelTools();
+  const doc = await io.readBinary(bytes);
+  doc.setLogger(tools.logger);
+  return { doc, safe };
+}
+
+/** Counts and sizes of a Document (what `assets check` holds against the budgets). */
+export async function measureDoc(doc) {
+  const { fn } = await modelTools();
+  const root = doc.getRoot();
+  let triangles = 0; let vertices = 0; let drawCalls = 0;
+  const scene = root.getDefaultScene() ?? root.listScenes()[0];
+  const seenMaterials = new Set();
+  if (scene) {
+    scene.traverse((node) => {
+      const mesh = node.getMesh();
+      if (!mesh) return;
+      const inst = node.getExtension('EXT_mesh_gpu_instancing');
+      const n = inst ? (inst.listAttributes()[0]?.getCount() ?? 1) : 1;
+      for (const prim of mesh.listPrimitives()) {
+        const idx = prim.getIndices();
+        const pos = prim.getAttribute('POSITION');
+        const c = idx ? idx.getCount() : (pos?.getCount() ?? 0);
+        const mode = prim.getMode();
+        triangles += (mode === 4 ? Math.floor(c / 3) : mode === 5 || mode === 6 ? Math.max(0, c - 2) : 0) * n;
+        vertices += (pos?.getCount() ?? 0) * n;
+        drawCalls += inst ? 1 : n;
+        if (prim.getMaterial()) seenMaterials.add(prim.getMaterial());
+      }
+    });
+  }
+  const textures = root.listTextures().map((t) => {
+    const px = t.getSize();
+    const slots = fn.listTextureSlots(t);
+    return { name: t.getName() || t.getURI() || '', mimeType: t.getMimeType(), px: px ? [px[0], px[1]] : null, bytes: t.getImage()?.byteLength ?? 0, gpuBytes: px ? Math.round(px[0] * px[1] * 4 * (4 / 3)) : 0, slots };
+  });
+  let box = null;
+  if (scene) {
+    const b = fn.getBounds(scene);
+    if (Number.isFinite(b.min[0]) && Number.isFinite(b.max[0])) box = { min: b.min.map((v) => round(v)), max: b.max.map((v) => round(v)), size: b.max.map((v, i) => round(v - b.min[i])) };
+  }
+  const skins = root.listSkins();
+  return {
+    triangles, vertices, drawCalls,
+    materials: seenMaterials.size,
+    textures,
+    textureGpuBytes: textures.reduce((s, t) => s + t.gpuBytes, 0),
+    maxTexturePx: textures.reduce((m, t) => Math.max(m, ...(t.px ?? [0])), 0),
+    bones: skins.reduce((m, s) => Math.max(m, s.listJoints().length), 0),
+    skins: skins.length,
+    clips: root.listAnimations().map((a) => a.getName() || 'clip'),
+    box,
+    heightM: box ? box.size[1] : null,
+    // Where the pivot is: the bottom centre is (0, min.y = 0, 0) with the footprint around x = z = 0.
+    pivot: box ? { bottom: Math.abs(box.min[1]) < 0.01 * Math.max(0.01, box.size[1]), centred: Math.abs((box.min[0] + box.max[0]) / 2) < 0.05 * Math.max(0.01, box.size[0]) && Math.abs((box.min[2] + box.max[2]) / 2) < 0.05 * Math.max(0.01, box.size[2]) } : null,
+  };
+}
+
+/** The Khronos glTF-Validator's verdict: { errors, warnings, messages: [first few] } (null when it is not installed). */
+export async function validateModel(bytes) {
+  const { validator } = await modelTools();
+  if (!validator?.validateBytes) return null;
+  try {
+    const report = await validator.validateBytes(new Uint8Array(bytes), { maxIssues: 50, externalResourceFunction: (uri) => Promise.reject(new Error(`external resource ${uri} refused`)) });
+    const msgs = (report.issues?.messages ?? []).filter((m) => m.severity <= 1).slice(0, 8).map((m) => `${m.severity === 0 ? 'error' : 'warning'} ${m.code}${m.pointer ? ` at ${m.pointer}` : ''}: ${m.message}`);
+    return { errors: report.issues?.numErrors ?? 0, warnings: report.issues?.numWarnings ?? 0, messages: msgs };
+  } catch (error) { return { errors: 1, warnings: 0, messages: [`the validator could not read it: ${error.message}`] }; }
+}
+
+/** inspectModel(path | bytes): the safety check, the validator and the measurements of one .glb. */
+export async function inspectModel(input, { limits = LIMITS.game, resolveLocal = false } = {}) {
+  const bytes = resolveLocal ? await selfContained(input, LIMITS.import) : bytesOf(input);
+  const safe = checkGlb(bytes, limits);
+  const base = { bytes: bytes.byteLength, sha256: sha256(bytes), safe };
+  if (!safe.ok) return { ...base, ok: false, measured: null, validator: null };
+  let doc;
+  try { ({ doc } = await readDoc(bytes, LIMITS.import)); } catch (error) { return { ...base, ok: false, measured: null, validator: null, why: error.message }; }
+  const measured = await measureDoc(doc);
+  const validator = await validateModel(bytes);
+  return { ...base, ok: !validator || validator.errors === 0, measured, validator };
+}
+
+/**
+ * The dominant colours of a model's surface: [{ hex, share }]. Each triangle (up to 4,000, spread evenly) counts by its
+ * area in metres: its colour is its material's base colour times the base-colour picture at the triangle's middle
+ * (its UVs), so unused corners of a texture atlas never count.
+ */
+export async function albedoOf(input, { k = 5 } = {}) {
+  const bytes = await selfContained(input, LIMITS.import);
+  const { doc } = await readDoc(bytes, LIMITS.import);
+  const { sharp } = await modelTools();
+  const pictures = new Map();
+  const pictureOf = async (tex) => {
+    if (!tex || !sharp) return null;
+    if (pictures.has(tex)) return pictures.get(tex);
+    let pic = null;
+    try { const r = await sharp(Buffer.from(tex.getImage())).resize(256, 256, { fit: 'fill' }).removeAlpha().raw().toBuffer({ resolveWithObject: true }); pic = { w: r.info.width, h: r.info.height, data: r.data }; } catch { pic = null; }
+    pictures.set(tex, pic);
+    return pic;
+  };
+  const samples = [];
+  const scene = doc.getRoot().getDefaultScene() ?? doc.getRoot().listScenes()[0];
+  const prims = [];
+  scene?.traverse((node) => { const mesh = node.getMesh(); if (mesh) for (const p of mesh.listPrimitives()) if (p.getMode() === 4) prims.push({ p, m: node.getWorldMatrix() }); });
+  const totalTris = prims.reduce((n, { p }) => n + Math.floor((p.getIndices()?.getCount() ?? p.getAttribute('POSITION')?.getCount() ?? 0) / 3), 0) || 1;
+  const step = Math.max(1, Math.floor(totalTris / 4000));
+  for (const { p, m } of prims) {
+    const mat = p.getMaterial();
+    const f = mat ? mat.getBaseColorFactor() : [1, 1, 1, 1];
+    const pic = await pictureOf(mat?.getBaseColorTexture());
+    const pos = p.getAttribute('POSITION'); const uv = p.getAttribute('TEXCOORD_0'); const idx = p.getIndices();
+    if (!pos) continue;
+    const n = Math.floor((idx ? idx.getCount() : pos.getCount()) / 3);
+    const at = (i) => (idx ? idx.getScalar(i) : i);
+    const a = [0, 0, 0]; const b = [0, 0, 0]; const c = [0, 0, 0];
+    for (let t = 0; t < n; t += step) {
+      const i0 = at(t * 3); const i1 = at(t * 3 + 1); const i2 = at(t * 3 + 2);
+      pos.getElement(i0, a); pos.getElement(i1, b); pos.getElement(i2, c);
+      const ux = b[0] - a[0]; const uy = b[1] - a[1]; const uz = b[2] - a[2]; const vx = c[0] - a[0]; const vy = c[1] - a[1]; const vz = c[2] - a[2];
+      const scale = Math.cbrt(Math.abs(m[0] * (m[5] * m[10] - m[6] * m[9]) - m[1] * (m[4] * m[10] - m[6] * m[8]) + m[2] * (m[4] * m[9] - m[5] * m[8]))) || 1;
+      const area = 0.5 * Math.hypot(uy * vz - uz * vy, uz * vx - ux * vz, ux * vy - uy * vx) * scale * scale;
+      if (!(area > 0)) continue;
+      let rgb = [f[0], f[1], f[2]].map((v) => linearToSrgb255(v));
+      if (pic && uv) {
+        const t0 = uv.getElement(i0, []); const t1 = uv.getElement(i1, []); const t2 = uv.getElement(i2, []);
+        const u = (t0[0] + t1[0] + t2[0]) / 3; const v = (t0[1] + t1[1] + t2[1]) / 3;
+        const x = Math.min(pic.w - 1, Math.max(0, Math.floor((u - Math.floor(u)) * pic.w))); const y = Math.min(pic.h - 1, Math.max(0, Math.floor((v - Math.floor(v)) * pic.h)));
+        const o = (y * pic.w + x) * 3;
+        rgb = [pic.data[o], pic.data[o + 1], pic.data[o + 2]].map((tx, ch) => linearToSrgb255(srgbToLinear01(tx) * f[ch]));
+      }
+      samples.push({ rgb, w: area * step });
+    }
+  }
+  return dominant(samples, k);
+}
+const srgbToLinear01 = (v) => { const c = v / 255; return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; };
+const linearToSrgb255 = (v) => { const c = Math.max(0, Math.min(1, v)); return Math.round(255 * (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055)); };
+
+/**
+ * One raw model into one shipped model. Options:
+ *   out        where to write the .glb (else only the bytes come back)
+ *   triangles  the triangle budget (a prop 1,500; a signature prop 5,000; a hero 8,000); 0: keep them
+ *   texture    the largest picture side in pixels (512 for a prop, 1,024 for a hero)
+ *   height     the asset's height in metres (it is scaled to it); null keeps its size
+ *   quality    WebP quality for colour pictures (normal maps get more)
+ *   rigged     keep the node tree and every primitive apart (skins and clips), even when it has none
+ *   metal      keep metalness (a `pbr` game that lights with a reflection map); otherwise every material is drawn
+ *              non-metal, because metal with nothing to reflect is black on a phone (a provider's textured prop
+ *              usually says metallic 1 and leaves the rest to its texture)
+ * Returns { ok, glb (the bytes), bytes (their count), sha256, out, before, after, ops, warnings }.
+ */
+export async function optimiseModel(input, { out = null, triangles = 1500, texture = 512, height = null, quality = 82, rigged = false, metal = false, log = () => {} } = {}) {
+  const t = await modelTools();
+  const { fn, mo, sharp, io } = t;
+  const raw = await selfContained(input, LIMITS.import);
+  const { doc } = await readDoc(raw, LIMITS.import);
+  const before = await measureDoc(doc);
+  const ops = [];
+  const warnings = [];
+  const hasRig = rigged || before.skins > 0 || before.clips.length > 0;
+
+  await doc.transform(fn.dedup(), fn.prune());
+  // Metal draws black without a reflection map, and a phone game has none: a flat colour exported as fully rough metal
+  // (common in packs) is always plastic; with `metal` false (every style but pbr) so is everything else.
+  let unmetal = 0;
+  for (const m of doc.getRoot().listMaterials()) {
+    const roughFlat = m.getMetallicFactor() >= 0.9 && m.getRoughnessFactor() >= 0.9 && !m.getMetallicRoughnessTexture();
+    if (m.getMetallicFactor() > 0 && (roughFlat || !metal)) { m.setMetallicFactor(0); unmetal += 1; }
+  }
+  if (unmetal) ops.push(`metal -> 0 on ${unmetal} material${unmetal === 1 ? '' : 's'} (nothing to reflect on a phone)`);
+  // Flat colours into one small palette picture, then one draw call per material where nothing moves on its own.
+  if (!hasRig) {
+    const flats = doc.getRoot().listMaterials().filter((m) => !m.getBaseColorTexture()).length;
+    if (flats >= 2) { await doc.transform(fn.palette({ min: 2 })); ops.push(`palette (${flats} flat colours into one picture)`); }
+    await doc.transform(fn.flatten(), fn.join());
+    ops.push('flatten, join');
+  }
+  await doc.transform(fn.weld());
+  ops.push('weld');
+
+  // Scale to the card's height, then the pivot to the bottom centre (+Y up).
+  const scene = doc.getRoot().getDefaultScene() ?? doc.getRoot().listScenes()[0];
+  if (height && before.heightM) {
+    const s = height / before.heightM;
+    if (Math.abs(s - 1) > 0.001) {
+      const wrap = doc.createNode('homie-scale').setScale([s, s, s]);
+      for (const child of scene.listChildren()) { scene.removeChild(child); wrap.addChild(child); }
+      scene.addChild(wrap);
+      if (!hasRig) await doc.transform(fn.flatten());
+      ops.push(`scale ${round(s, 4)} (to ${height} m)`);
+    }
+  }
+  await doc.transform(fn.center({ pivot: 'below' }));
+  ops.push('center bottom');
+
+  // Simplify to the triangle budget, loosening the error until it fits (a closed silhouette first).
+  let now = (await measureDoc(doc)).triangles;
+  if (triangles > 0 && now > triangles) {
+    for (const error of [0.002, 0.006, 0.015, 0.03, 0.06, 0.12]) {
+      now = (await measureDoc(doc)).triangles;
+      if (now <= triangles) break;
+      const ratio = Math.max(0.005, Math.min(1, (triangles / now) * 0.97));
+      await doc.transform(fn.simplify({ simplifier: mo.MeshoptSimplifier, ratio, error }));
+    }
+    now = (await measureDoc(doc)).triangles;
+    ops.push(`simplify ${round(now / Math.max(1, before.triangles), 3)} (${before.triangles} to ${now} triangles)`);
+    if (now > triangles) warnings.push(`still ${now} triangles after simplifying (its budget is ${triangles}): the shape resists; a lower-poly source, or a looser budget with a reason`);
+  }
+  if (hasRig) { await doc.transform(fn.resample()); ops.push('resample clips'); }
+
+  // Pictures: no side over `texture`, WebP; normal maps at a higher quality.
+  const textured = doc.getRoot().listTextures().length;
+  if (textured) {
+    if (sharp) {
+      // A palette picture (flat colours, a few pixels a colour) is lossless: lossy WebP bleeds one colour into the next.
+      await doc.transform(fn.textureCompress({ encoder: sharp, targetFormat: 'webp', lossless: true, pattern: /^Palette/ }));
+      await doc.transform(fn.textureCompress({ encoder: sharp, targetFormat: 'webp', resize: [texture, texture], quality, pattern: /^(?!Palette)/, slots: /^(?!normalTexture).*$/ }));
+      await doc.transform(fn.textureCompress({ encoder: sharp, targetFormat: 'webp', resize: [texture, texture], quality: Math.min(95, quality + 10), pattern: /^(?!Palette)/, slots: /^normalTexture$/ }));
+      ops.push(`resize ${texture}`, 'webp');
+    } else warnings.push('sharp is not installed: the pictures were left as they were (npm install in the studio)');
+  }
+  if (hasRig) {
+    // A skinned model keeps float positions: quantizing would move its scale into the inverse bind matrices, and every
+    // measurement of the shipped file (its height, its box) would then be wrong. Meshopt's filters still compress it.
+    await doc.transform(fn.prune(), fn.unpartition(), fn.reorder({ encoder: mo.MeshoptEncoder }));
+    doc.createExtension(t.ext.EXTMeshoptCompression).setRequired(true).setEncoderOptions({ method: t.ext.EXTMeshoptCompression.EncoderMethod.FILTER });
+    // The filters store normals and rotations as normalized integers, which glTF allows only with this extension.
+    doc.createExtension(t.ext.KHRMeshQuantization).setRequired(true);
+  } else await doc.transform(fn.prune(), fn.unpartition(), fn.meshopt({ encoder: mo.MeshoptEncoder, level: 'medium' }));
+  ops.push(hasRig ? 'meshopt (filters, float positions)' : 'meshopt', 'prune');
+
+  const after = await measureDoc(doc);
+  const bytes = await io.writeBinary(doc);
+  const safe = checkGlb(bytes, LIMITS.game);
+  if (!safe.ok) warnings.push(...safe.problems.map((p) => `the result: ${p}`));
+  if (out) { mkdirSync(dirname(out), { recursive: true }); writeFileSync(out, bytes); }
+  log(`optimised: ${before.triangles} -> ${after.triangles} triangles, ${Math.round(raw.byteLength / 1024)} -> ${Math.round(bytes.byteLength / 1024)} KB`);
+  return { ok: safe.ok, out, glb: bytes, bytes: bytes.byteLength, sha256: sha256(bytes), rawBytes: raw.byteLength, rawSha256: sha256(raw), before, after, ops, warnings, tool: `@gltf-transform/functions ${await toolVersion()}` };
+}
+
+let version = null;
+async function toolVersion() {
+  if (version) return version;
+  // The package's exports map hides its package.json: resolve its entry, then read the package.json above it.
+  try {
+    const { createRequire } = await import('node:module');
+    const entry = createRequire(import.meta.url).resolve('@gltf-transform/functions');
+    const m = /^(.*[\\/]@gltf-transform[\\/]functions)[\\/]/.exec(entry);
+    version = JSON.parse(readFileSync(`${m[1]}/package.json`, 'utf8')).version;
+  } catch { version = 'unknown'; }
+  return version;
+}
+
+/**
+ * A grey box .glb of `size` metres (x, y, z), its pivot at the bottom centre: what a remix gets in place of an asset
+ * it may not carry, and what a refused model is drawn as.
+ */
+export async function placeholderGlb(size = [0.5, 0.5, 0.5], { name = 'placeholder', colour = [0.54, 0.56, 0.6, 1] } = {}) {
+  const { core, io } = await modelTools();
+  const doc = new core.Document();
+  const buffer = doc.createBuffer();
+  const [x, y, z] = size.map((v) => Math.max(0.01, Number(v) || 0.5));
+  const X = x / 2; const Z = z / 2;
+  // 24 vertices (flat normals per face), 12 triangles.
+  const faces = [
+    [[1, 0, 0], [[X, 0, -Z], [X, y, -Z], [X, y, Z], [X, 0, Z]]], [[-1, 0, 0], [[-X, 0, Z], [-X, y, Z], [-X, y, -Z], [-X, 0, -Z]]],
+    [[0, 1, 0], [[-X, y, -Z], [-X, y, Z], [X, y, Z], [X, y, -Z]]], [[0, -1, 0], [[-X, 0, Z], [-X, 0, -Z], [X, 0, -Z], [X, 0, Z]]],
+    [[0, 0, 1], [[-X, 0, Z], [X, 0, Z], [X, y, Z], [-X, y, Z]]], [[0, 0, -1], [[X, 0, -Z], [-X, 0, -Z], [-X, y, -Z], [X, y, -Z]]],
+  ];
+  const pos = []; const nor = []; const idx = [];
+  faces.forEach(([n, quad], f) => { for (const p of quad) { pos.push(...p); nor.push(...n); } const b = f * 4; idx.push(b, b + 1, b + 2, b, b + 2, b + 3); });
+  const prim = doc.createPrimitive()
+    .setAttribute('POSITION', doc.createAccessor().setType('VEC3').setArray(new Float32Array(pos)).setBuffer(buffer))
+    .setAttribute('NORMAL', doc.createAccessor().setType('VEC3').setArray(new Float32Array(nor)).setBuffer(buffer))
+    .setIndices(doc.createAccessor().setType('SCALAR').setArray(new Uint16Array(idx)).setBuffer(buffer))
+    .setMaterial(doc.createMaterial(name).setBaseColorFactor(colour).setRoughnessFactor(0.9).setMetallicFactor(0));
+  const mesh = doc.createMesh(name).addPrimitive(prim);
+  doc.createScene(name).addChild(doc.createNode(name).setMesh(mesh));
+  return io.writeBinary(doc);
+}
+

package/lib/remix-assets.mjs

@@ -0,0 +1,84 @@
+/**
+ * A REMIX ARRIVES WITH ITS MODELS. The remix source (source.json) carries text only: the game's code, its
+ * assets/manifest.json and RIGHTS.md. The original site also serves /games/<id>/assets.json (lib/asset-manifest.mjs
+ * servedAssets): each asset's licence, what a remix gets, and for redistributable files their address and SHA-256.
+ *
+ *   include     fetched from the original studio's site, same origin as the source, checked by SHA-256 (and, for a
+ *               model, by the safety rules), written where the original had it
+ *   reference   not carried: a grey placeholder of the recorded size, and the origin named in RIGHTS.md
+ *   none        a grey placeholder of the recorded size and "needs its own licence"
+ *
+ * At most 50 MB in all. Each entry of the remix's manifest records where it came from (`remixOf`), so RIGHTS.md and the
+ * credits carry over; nothing is fetched from anywhere but the original site.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { LIMITS, checkGlb } from '../assets/safety.mjs';
+import { readManifest, syncCredits, writeManifest, writeRights } from './asset-manifest.mjs';
+
+export const REMIX_ASSET_CAP = 50 * 1024 * 1024;
+const SAFE_PATH = /^public\/[A-Za-z0-9._/-]{1,200}$/;
+
+/** `game remix` after the text files are written: the original's assets, or placeholders. */
+export async function fetchRemixAssets(root, id, source, { credit = {}, cap = REMIX_ASSET_CAP, log = () => {} } = {}) {
+  const base = new URL(String(source));
+  const at = new URL(base.pathname.replace(/source\.json$/, 'assets.json'), base);
+  let body = null;
+  try {
+    const res = await fetch(at, { signal: AbortSignal.timeout(20_000) });
+    if (res.ok) body = await res.json();
+  } catch { body = null; }
+  if (body?.kind !== 'homie-game-assets' || !Array.isArray(body.assets)) return { carried: false, why: 'the original serves no assets.json (a game made before 0.22.0, or one with no models)', fetched: [], placeholders: [], bytes: 0 };
+  const gdir = join(root, 'games', id);
+  const manifest = readManifest(root, id);
+  const fetched = []; const placeholders = []; const failed = [];
+  let total = 0;
+  const { placeholderGlb, sha256 } = await import('./optimise.mjs').catch(() => ({}));
+  for (const a of body.assets) {
+    const entry = manifest.assets.find((x) => x.id === a.id);
+    if (!entry) continue;
+    entry.from = { ...(entry.from ?? {}), remixOf: { studio: credit.studio ?? null, game: credit.game ?? null, source: String(base), asset: a.id } };
+    // The original studio owns what it made or generated; this remix does not.
+    if (entry.license?.owner === 'studio') entry.license = { ...entry.license, owner: credit.studio ?? 'the original studio' };
+    const files = (a.files ?? []).filter((f) => SAFE_PATH.test(String(f.path ?? '')) && !String(f.path).split('/').includes('..'));
+    if (a.license?.remix === 'include' && files.length && files.every((f) => f.url && f.sha256)) {
+      let ok = true;
+      for (const f of files) {
+        const url = new URL(String(f.url), at);
+        if (url.origin !== at.origin) { failed.push({ asset: a.id, why: `${f.url} is on another site` }); ok = false; break; }
+        try {
+          const res = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+          if (!res.ok) throw new Error(`answered ${res.status}`);
+          const bytes = Buffer.from(await res.arrayBuffer());
+          total += bytes.byteLength;
+          if (total > cap) throw new Error(`the remix's assets passed ${Math.round(cap / 1024 / 1024)} MB`);
+          const sum = createHash('sha256').update(bytes).digest('hex');
+          if (sum !== f.sha256) throw new Error('its SHA-256 does not match the original\'s record');
+          if (/\.glb$/i.test(f.path)) { const s = checkGlb(bytes, LIMITS.game); if (!s.ok) throw new Error(s.problems[0]); }
+          mkdirSync(dirname(join(gdir, f.path)), { recursive: true });
+          writeFileSync(join(gdir, f.path), bytes);
+        } catch (error) { failed.push({ asset: a.id, file: f.path, why: error.message }); ok = false; break; }
+      }
+      if (ok) { fetched.push({ asset: a.id, files: files.map((f) => f.path) }); continue; }
+    }
+    // Not carried: a grey box of the size it had, so the game still runs, and a plain note.
+    const model = (entry.files ?? []).find((f) => f.role === 'model' && SAFE_PATH.test(String(f.path ?? '')));
+    if (model && placeholderGlb) {
+      const size = a.size ?? entry.measured?.box?.size ?? [0.5, entry.measured?.heightM ?? 0.5, 0.5];
+      const glb = Buffer.from(await placeholderGlb(size, { name: `${a.id}-placeholder` }));
+      mkdirSync(dirname(join(gdir, model.path)), { recursive: true });
+      if (!existsSync(join(gdir, model.path))) writeFileSync(join(gdir, model.path), glb);
+      model.sha256 = sha256(glb);
+      model.bytes = glb.byteLength;
+    }
+    entry.placeholder = true;
+    entry.license = { ...(entry.license ?? {}), remix: 'none', notes: `${a.license?.remix === 'reference' ? `Fetch it from its origin${a.from?.origin ? ` (${a.from.origin})` : ''} under its own licence` : 'Needs its own licence'}: this remix has a grey placeholder of the same size in its place.` };
+    placeholders.push({ asset: a.id, why: a.license?.remix === 'include' ? (failed.find((x) => x.asset === a.id)?.why ?? 'not served') : `its licence (${a.license?.kind ?? 'none'}) does not let a remix carry it` });
+  }
+  writeManifest(root, id, manifest);
+  writeRights(root, id, manifest);
+  syncCredits(root, id, manifest);
+  log(`remix assets: ${fetched.length} carried, ${placeholders.length} placeholder(s)`);
+  return { carried: true, fetched, placeholders, failed, bytes: total };
+}

package/lib/render3d.mjs

@@ -0,0 +1,81 @@
+/**
+ * STILL PICTURES FROM THE ENGINE (free, on this computer): the style board's swatches, the lineup, the starter
+ * library's thumbnails. assets/render-page.ts (three.js, GLTFLoader with meshopt) is bundled once by esbuild and run
+ * in one headless Chrome on this computer's GPU (SwiftShader where there is none: slow, and fine for stills).
+ *
+ *   await withRenderer(async (r) => {
+ *     const jpg = await r.swatch(tokens, models, { title })      // a data: URL
+ *     const l = await r.lineup(models, tokens)                    // { front, quarter, silhouettes, rows }
+ *     const t = await r.thumb({ id, glb })                        // { image, size }
+ *   });
+ *
+ * Models go in as { id, glb: <base64>, label }. Nothing is fetched but Google Fonts (the swatch's title font).
+ */
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { chromeArgs, findChrome, noChrome } from './chrome.mjs';
+import { PACKAGE_ROOT } from './studio.mjs';
+
+let bundled = null;
+
+/** The render page's script, bundled with three.js from wherever this package's dependencies are installed. */
+export async function renderScript() {
+  if (bundled) return bundled;
+  let esbuild;
+  try { esbuild = await import('esbuild'); } catch { throw new Error('esbuild is not installed (it comes with @homie-rocks/studio: npm install)'); }
+  const res = await (esbuild.default ?? esbuild).build({
+    entryPoints: [join(PACKAGE_ROOT, 'assets', 'render-page.ts')], bundle: true, format: 'iife', target: 'es2022', minify: true, write: false,
+    absWorkingDir: PACKAGE_ROOT, logLevel: 'silent', platform: 'browser',
+  }).catch((error) => { throw new Error(`the render page did not build: ${error.errors?.[0]?.text ?? error.message} (three.js comes with @homie-rocks/studio: npm install)`); });
+  bundled = res.outputFiles[0].text;
+  return bundled;
+}
+
+/** Model bytes as the page takes them. */
+export const modelIn = (id, bytes, extra = {}) => ({ id, glb: Buffer.from(bytes).toString('base64'), ...extra });
+
+/** A data: URL into bytes. */
+export function dataUrlBytes(url) {
+  const m = /^data:([^;,]+);base64,(.*)$/s.exec(String(url));
+  if (!m) throw new Error('not a base64 data: URL');
+  return { type: m[1], bytes: Buffer.from(m[2], 'base64') };
+}
+export function saveDataUrl(url, file) { const { bytes } = dataUrlBytes(url); writeFileSync(file, bytes); return bytes.length; }
+
+/**
+ * Run `fn` with a renderer: { swatch, lineup, thumb, renderer: 'the WebGL renderer name' }. One Chrome for the whole
+ * call, closed after. Throws in plain words when there is no Chrome or no WebGL.
+ */
+export async function withRenderer(fn, { log = () => {} } = {}) {
+  const chrome = findChrome();
+  if (!chrome) throw new Error(noChrome());
+  let puppeteer;
+  try { puppeteer = (await import('puppeteer-core')).default; } catch { throw new Error('puppeteer-core is not installed (it comes with @homie-rocks/studio: npm install)'); }
+  const script = await renderScript();
+  const profile = mkdtempSync(join(tmpdir(), 'homie-render-'));
+  const browser = await puppeteer.launch({ executablePath: chrome, headless: true, userDataDir: profile, timeout: 150_000, protocolTimeout: 300_000, args: [...chromeArgs(), '--no-first-run', '--no-default-browser-check', '--hide-scrollbars'] });
+  try {
+    const page = await browser.newPage();
+    const errors = [];
+    page.on('pageerror', (e) => errors.push(String(e?.message ?? e).slice(0, 300)));
+    await page.setViewport({ width: 1280, height: 720, deviceScaleFactor: 1 });
+    await page.setContent('<!doctype html><html><head><meta charset="utf-8"><style>html,body{margin:0;background:#000}canvas{display:block}</style></head><body></body></html>', { waitUntil: 'load' });
+    await page.addScriptTag({ content: script });
+    const ok = await page.waitForFunction(() => window.homieRender?.ready === true, { timeout: 60_000 }).then(() => true).catch(() => false);
+    if (!ok) throw new Error(`the render page did not start${errors.length ? `: ${errors[0]}` : ''}`);
+    const renderer = await page.evaluate(() => { try { const c = document.createElement('canvas'); const gl = c.getContext('webgl2'); const d = gl?.getExtension('WEBGL_debug_renderer_info'); return gl ? String(d ? gl.getParameter(d.UNMASKED_RENDERER_WEBGL) : gl.getParameter(gl.RENDERER)) : 'no WebGL'; } catch { return null; } });
+    log(`rendering on ${renderer}`);
+    const call = (name, ...args) => page.evaluate((n, a) => window.homieRender[n](...a), name, args).catch((e) => { throw new Error(`${name} failed: ${errors.at(-1) ?? e.message}`); });
+    return await fn({
+      renderer,
+      swatch: (tokens, models = [], opts = {}) => call('swatch', tokens, models, opts),
+      lineup: (models, tokens, opts = {}) => call('lineup', models, tokens, opts),
+      thumb: (model, opts = {}) => call('thumb', model, opts),
+    });
+  } finally {
+    await browser.close().catch(() => {});
+    rmSync(profile, { recursive: true, force: true });
+  }
+}
+

package/lib/scaffold.mjs

@@ -28,6 +28,7 @@ import { STATS_MIGRATION, STATS_MIGRATION_FILE } from '../worker/stats.mjs';
 import { PLAYERS_MIGRATION, PLAYERS_MIGRATION_FILE } from '../worker/players.mjs';
 import { OFFICE_MIGRATION, OFFICE_MIGRATION_FILE } from '../worker/office-schema.mjs';
 import { SERVERS_MIGRATION, SERVERS_MIGRATION_FILE } from '../worker/servers.mjs';
+import { CHAT_MIGRATION, CHAT_MIGRATION_FILE } from '../worker/chat-store.mjs';
 import { themeFile } from './site.mjs';
 
 export const COMPAT_DATE = '2026-06-01';
@@ -106,6 +107,7 @@ directory lists its games; homie.rocks does not host them.
 | --- | --- |
 | \`games/<id>/\` | One game: \`game.json\` (id, name, blurb, players, round length), \`index.html\`, \`src/main.ts\`; and, when it has them, \`tunables.json\` (the numbers that shape how it feels: the Game Lab's sliders, kept values written back) and \`lab.json\` (the Game Lab's takes). |
 | \`music/\`, \`videos/\` | Songs, scores, loops; trailers, music videos, cutscenes. \`manifest.json\` lists each one (\`node_modules/@homie-rocks/studio/media/MEDIA.md\`); a published entry gets a page at \`/music/<slug>/\` or \`/videos/<slug>/\`. Without storage the site serves each file itself (up to 25 MiB). Once the studio has storage (see below), its big media (over 1 MiB, or left out of git) lives in its own R2: every deploy uploads it, checks it by SHA-256 and serves it from R2 at the same address. Large files never go into git. The Homie plugin's \`music\` and \`video\` skills make them. |
+| \`games/<id>/assets/\` | Every model and texture a game ships, with where it came from and its licence (\`manifest.json\`), and \`RIGHTS.md\` in plain words; \`games/<id>/codex/decisions.json\` (private, like the codex) is its look as decisions, and \`style.json\` the palette, fonts, light and camera the game draws with. \`art/<slug>/\` holds art jobs (concepts, receipts; \`raw/\` is git-ignored). |
 | \`posts/\` | The studio's news and drops: one markdown file each (\`posts/2026-09-30-we-are-live.md\`: \`title:\`, \`date:\`, \`summary:\`, and \`game:\` / \`song:\` / \`video:\` to link one). They are the site's Posts, with Atom and JSON feeds. |
 | \`site/\` | The studio's site: its look (\`theme.json\`), and anything of its own that wins over the generated pages (\`site/README.md\`); the Worker (\`src/worker.mjs\`) and its D1 migrations. |
 | \`wrangler.jsonc\` | The Worker's Cloudflare config (the Worker, D1, the Table and Lobby Durable Objects, and \`previews\` for branch Previews), at the root, where Cloudflare's Workers Builds reads it. A studio made before 0.10.0 keeps it in \`site/\` and deploys from a computer; every command finds either. |
@@ -264,6 +266,26 @@ studio's pinned copy, never a registry lookup of the bare name.
   Cloudflare, Chrome, ffmpeg, GitHub, ElevenLabs, fal), what each unlocks, and the exact fix. Optional ones never
   block anything.
 
+## Art direction and models
+
+- **A game's look is a set of decisions** (\`games/<id>/codex/decisions.json\`, drawn in the codex's Art direction
+  tab): render style, palette, shape, proportions, materials, light, camera, fonts, effects; the cast, its library
+  family, scale and phone budgets. \`npx --no-install homie-studio style init <id> --prompt "<the person's words>"\`
+  picks every one automatically with a why. The person can steer one ("warmer"), lock one, or explore three
+  directions drawn by the game engine itself (\`style board <id>\`, free). The first asset built on a decision pins
+  it; a locked one changes only with the person's yes after \`style blast\` shows what goes stale and what remaking
+  it would cost. Nothing is ever remade by itself. The Homie plugin's \`style\` skill has the rest.
+- **Models come free first**: the engine, then Homie's CC0 starter library (\`assets find "<words>"\`, then
+  \`assets add <id> <item>\`, copied in, never hot-linked), then the person's own files (\`assets add <id> --file …
+  --license …\`), then generated props on the person's own fal account under a budget with receipts (the plugin's
+  \`models\` skill). Every model is checked (no external URIs, no oversized files), made phone-sized and recorded
+  with its licence; \`RIGHTS.md\` and the credits page follow. \`assets check <id>\` holds a game to the phone
+  budgets; \`assets lineup <id>\` shows everything at true scale. A three.js game loads models through
+  \`@homie-rocks/studio/assets\` (\`createModels\`); \`game new <id> --from gem-rush-3d\` starts one.
+- **Licences**: a public game ships only assets whose licence allows it (CC0, CC BY with credit, the studio's own,
+  generated); \`publish\` refuses an asset with no licence record. A remix gets each redistributable model,
+  checked by SHA-256, and a grey placeholder for the rest.
+
 ## Running live games (the back office)
 
 - The owner runs the studio's live games from \`/_studio/office\` (\`npx --no-install homie-studio office link\` gives
@@ -485,6 +507,11 @@ music/**/*.flac
 videos/**/*.mp4
 videos/**/*.mov
 videos/**/*.webm
+# 3D: raw provider output, high-poly sources and Blender files stay on this computer (or the studio's R2): never shipped, never committed. The phone-sized model in games/<id>/public/models/ is committed.
+art/**/raw/
+*.blend
+*.blend1
+*.fbx
 `;
 
 /** Every file a new studio gets, relative to its folder. */
@@ -545,6 +572,7 @@ export { default, Table, Lobby } from '@homie-rocks/studio/worker';
     [`site/migrations/${PLAYERS_MIGRATION_FILE}`]: PLAYERS_MIGRATION,
     [`site/migrations/${OFFICE_MIGRATION_FILE}`]: OFFICE_MIGRATION,
     [`site/migrations/${SERVERS_MIGRATION_FILE}`]: SERVERS_MIGRATION,
+    [`site/migrations/${CHAT_MIGRATION_FILE}`]: CHAT_MIGRATION,
     'wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2, layout: 'root' }),
     '.claude/skills/.gitkeep': '',
   };
@@ -637,13 +665,22 @@ export function ensureServersMigration(root) {
 }
 
 /** Every migration the template owns that this studio lacks, added: the files written (deploy and dev say so). */
+/** A studio made before 0.23.0 has no room chat tables: the owner's chat rules and players' reports. */
+function ensureChatMigration(root) {
+  const file = join(root, 'site', 'migrations', CHAT_MIGRATION_FILE);
+  if (existsSync(file)) return null;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, CHAT_MIGRATION);
+  return `site/migrations/${CHAT_MIGRATION_FILE}`;
+}
+
 export function ensureMigrations(root) {
-  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root)].filter(Boolean);
+  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root)].filter(Boolean);
 }
 
 /** What a migration file the template added is for, in a few words (deploy and dev say it). */
 export function migrationWord(file) {
-  return /players/.test(file) ? 'player accounts and cloud saves' : /servers/.test(file) ? 'servers and agent seats: room pools with their own rules, AI passes' : /office/.test(file) ? 'the back office: launch states, invites, the owner\'s controls' : 'the studio\'s own stats: counts, never tracks';
+  return /players/.test(file) ? 'player accounts and cloud saves' : /chat/.test(file) ? 'room chat: the owner\'s chat rules and players\' reports (never the chat itself)' : /servers/.test(file) ? 'servers and agent seats: room pools with their own rules, AI passes' : /office/.test(file) ? 'the back office: launch states, invites, the owner\'s controls' : 'the studio\'s own stats: counts, never tracks';
 }
 
 /**