@looop-games/cli 0.1.19 → 0.1.20

package/CHANGELOG.md

@@ -14,6 +14,28 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.20] - 2026-07-29
+
+### Added
+
+- **Generator scripts: `looop model bake` can run your code at bake time.**
+  Name a game-committed script in `<model>.bake.json`
+  (`{ "generate": "creature-gen.mjs" }`) and the bake hands it the parsed
+  model. Export `clips(model)` to bake a procedural pose function into
+  additive clips (sampled into delta tracks the engine's layer slots play —
+  see the engine changelog), and/or `zones(model)` to label triangles your
+  own way when bone names can't describe the mesh (one byte per triangle +
+  a name table). The script must be deterministic — the bake refuses
+  `Math.random()`-shaped output — and its text joins the staleness hash, so
+  editing the maths re-bakes automatically, exactly like editing the GLB.
+  The broadphase radius grows to contain every generated pose at weight 1.
+
+### Changed
+
+- Baked artifacts re-bake once after this update (the artifact format version
+  advanced to carry generated clips). No action needed — the next
+  `looop dev`/`test`/`publish` does it.
+
 ## [0.1.19] - 2026-07-22
 
 ### Added

package/lib/model-bake.mjs

@@ -28,7 +28,8 @@
 // ── Optional bake config: <model>.bake.json next to the GLB ──────────────────
 //   {
 //     "zones": { "head": ["Head", "Neck*"], "arm": ["*_Arm*"] },
-//     "clips": ["fly", "idle"]        // subset to bake; default = all
+//     "clips": ["fly", "idle"],       // subset to bake; default = all
+//     "generate": "drifter-gen.mjs"   // generator script, relative to the GLB
 //   }
 // Zones use the dominant-bone rule (a triangle belongs to whichever bone most
 // influences its vertices — the same rule the big engines use to size their
@@ -36,6 +37,13 @@
 // names, `*` is a wildcard. Without config the mesh gets NO zones: hits still land
 // on the exact surface, damage is uniform, and `hitRay` reports `zone: null`.
 //
+// `generate` names a game-committed script that runs AT BAKE TIME with the
+// parsed model and returns data the engine carries: additive clips baked from a
+// procedural pose function (`export clips`) and/or per-triangle zone bytes for
+// meshes bone names can't describe (`export zones`). See the generator-script
+// section below for the exact contract. The script's text participates in the
+// staleness hash, so editing it re-bakes exactly like editing the GLB.
+//
 // ── What a bake rejects, loudly ──────────────────────────────────────────────
 //   - scale tracks in a clip (the runtime rig is uniform-scale; a scaling clip
 //     cannot be reproduced, so it fails the bake instead of silently drifting)
@@ -49,11 +57,14 @@
 
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs';
-import { join, resolve, basename } from 'node:path';
+import { join, resolve, basename, dirname } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 // Version stamped into artifacts. Bump when the bake OUTPUT changes shape or
 // meaning — it participates in the staleness hash, so old artifacts re-bake.
-export const BAKE_VERSION = 1;
+// v2: the staleness hash gained the generator-script component, and skeletons
+// may carry generated additive clips.
+export const BAKE_VERSION = 2;
 
 // ── pure helpers (unit-tested without a browser) ─────────────────────────────
 
@@ -112,13 +123,16 @@ export function sha256(buf) {
   return createHash('sha256').update(buf).digest('hex');
 }
 
-// The staleness key an artifact records: GLB bytes + bake config + bake version.
-// If any of the three changes, the artifact is stale and auto-bake re-runs.
-export function sourceHash(glbBytes, configText) {
+// The staleness key an artifact records: GLB bytes + bake config + generator
+// script + bake version. If any of the four changes, the artifact is stale and
+// auto-bake re-runs — editing the generator's wing maths re-bakes exactly like
+// editing the GLB does.
+export function sourceHash(glbBytes, configText, generatorText = '') {
   return sha256(Buffer.concat([
     Buffer.from(`bake${BAKE_VERSION}!`),
     Buffer.from(sha256(glbBytes)),
     Buffer.from(sha256(Buffer.from(configText ?? ''))),
+    Buffer.from(sha256(Buffer.from(generatorText ?? ''))),
   ]));
 }
 
@@ -127,12 +141,28 @@ export function artifactPaths(glbPath) {
   return { skeleton: `${stem}.skeleton.json`, mesh: `${stem}.mesh.json`, config: `${stem}.bake.json` };
 }
 
-// Is the artifact pair current for this GLB + config? (Missing → stale.)
+// The generator script's current text, resolved from the bake config — '' when
+// the config names none. A named-but-missing script reads as null so staleness
+// can answer "stale" and the bake itself can fail with the real error.
+function generatorText(glbPath, configText) {
+  if (!configText) return '';
+  let gen;
+  try { gen = JSON.parse(configText)?.generate; } catch { return ''; }   // bad JSON fails in bakeModel with the real message
+  if (!gen) return '';
+  const p = resolve(dirname(glbPath), gen);
+  if (!existsSync(p)) return null;
+  return readFileSync(p, 'utf8');
+}
+
+// Is the artifact pair current for this GLB + config + generator? (Missing → stale.)
 export function isStale(glbPath) {
   const { skeleton, mesh, config } = artifactPaths(glbPath);
   if (!existsSync(skeleton) || !existsSync(mesh)) return true;
   try {
-    const want = sourceHash(readFileSync(glbPath), existsSync(config) ? readFileSync(config, 'utf8') : '');
+    const configText = existsSync(config) ? readFileSync(config, 'utf8') : '';
+    const genText = generatorText(glbPath, configText);
+    if (genText === null) return true;   // config names a script that is gone
+    const want = sourceHash(readFileSync(glbPath), configText, genText);
     const have = JSON.parse(readFileSync(skeleton, 'utf8'))?._source?.hash;
     return have !== want;
   } catch {
@@ -140,6 +170,134 @@ export function isStale(glbPath) {
   }
 }
 
+// ── generator scripts: game code runs at bake time, the engine ships data ────
+// bake.json may name a game-committed script: { "generate": "drifter-gen.mjs" }
+// (path relative to the GLB). The script receives the parsed model and returns
+// DATA — additive clip samples and/or per-triangle zone bytes. The engine
+// validates and carries what it returns; it learns no geometric language and
+// runs no game code after the bake. Two exports, both optional, each either the
+// value or a function of the model:
+//
+//   export function clips(model) {
+//     return { beat: { duration: 1, additive: true, keys: 64, sample: (t) => ({
+//       WingL: { rot: [x, y, z, w] },        // delta from rest, unit quaternion
+//       Chest: { pos: [x, y, z] },           // delta from rest, model units
+//     }) } };
+//   }
+//   export function zones(model) {
+//     return { names: ['body', 'wing'], tri: bytes };   // one byte per triangle
+//   }
+//
+// `model` = { bones, clips, mesh: { vertexCount, triangleCount, influences,
+// position, skinIndex, skinWeight, index } } — everything the bake read from
+// the GLB, typed arrays decoded.
+//
+// sample(t) must be DETERMINISTIC (no Math.random(), no Date.now()): the tracks
+// it produces are replicated pose truth, and a re-bake must reproduce them
+// byte-identically or the staleness hash lies.
+
+// Sample each generated clip definition into baked additive tracks.
+export function buildGeneratedClips(defs, boneNames, existingClipNames = []) {
+  const known = new Set(boneNames);
+  const existing = new Set(existingClipNames);
+  const clips = {};
+  for (const [name, def] of Object.entries(defs ?? {})) {
+    if (existing.has(name)) {
+      throw new Error(`generated clip "${name}" collides with a clip already in the GLB — rename one of them`);
+    }
+    if (def?.additive !== true) {
+      throw new Error(`generated clip "${name}" must declare additive: true — generated clips are deltas layered over the base pose; base clips come from the GLB`);
+    }
+    if (typeof def.sample !== 'function') {
+      throw new Error(`generated clip "${name}": "sample" must be a function of time`);
+    }
+    const duration = def.duration ?? 0;
+    // Key times are INCLUSIVE of the end (0..duration), so a looping clip
+    // interpolates across the seam instead of stepping at the wrap.
+    const keys = duration > 0 ? Math.max(2, Math.round(def.keys ?? 64)) : 0;
+    const times = duration > 0
+      ? Array.from({ length: keys + 1 }, (_, k) => (k / keys) * duration)
+      : [0];
+
+    // Determinism probe: the cheapest check that catches the whole class of
+    // Math.random()/Date.now() mistakes before they become flickering re-bakes.
+    if (JSON.stringify(def.sample(times[0])) !== JSON.stringify(def.sample(times[0]))) {
+      throw new Error(`generated clip "${name}": sample(t) is not deterministic — identical t must return identical output (no Math.random(), no Date.now()); these tracks are replicated pose truth and a re-bake must reproduce them exactly`);
+    }
+
+    let shape = null;                 // bone -> { rot: bool, pos: bool }, fixed by the first sample
+    const acc = new Map();            // bone -> { times, rot[], pos[] }
+    for (const t of times) {
+      const frame = def.sample(t) ?? {};
+      const frameBones = Object.keys(frame);
+      if (shape === null) {
+        shape = new Map();
+        for (const bn of frameBones) {
+          if (!known.has(bn)) {
+            throw new Error(`generated clip "${name}": sample() returned bone "${bn}" — the skeleton has no such bone. Bones are: ${boneNames.join(', ')}`);
+          }
+          shape.set(bn, { rot: !!frame[bn]?.rot, pos: !!frame[bn]?.pos });
+        }
+        if (!shape.size) throw new Error(`generated clip "${name}": sample() returned no bones`);
+      } else if (frameBones.length !== shape.size || !frameBones.every((bn) => shape.has(bn))) {
+        throw new Error(`generated clip "${name}": sample() must return the same bones (with the same rot/pos properties) at every time — t=${t} differs from t=${times[0]}`);
+      }
+      for (const [bn, spec] of shape) {
+        const v = frame[bn];
+        if (!!v?.rot !== spec.rot || !!v?.pos !== spec.pos) {
+          throw new Error(`generated clip "${name}": sample() must return the same bones (with the same rot/pos properties) at every time — bone "${bn}" at t=${t} differs`);
+        }
+        let entry = acc.get(bn);
+        if (!entry) { entry = { times: [], rot: spec.rot ? [] : null, pos: spec.pos ? [] : null }; acc.set(bn, entry); }
+        entry.times.push(t);
+        if (spec.rot) {
+          const q = v.rot;
+          const L = Math.hypot(q[0], q[1], q[2], q[3]);
+          if (!(L > 0) || Math.abs(L - 1) > 1e-3) {
+            throw new Error(`generated clip "${name}", bone "${bn}" at t=${t}: rotation is not unit length (${L.toFixed(4)}) — normalize your quaternions`);
+          }
+          entry.rot.push(q[0] / L, q[1] / L, q[2] / L, q[3] / L);
+        }
+        if (spec.pos) entry.pos.push(v.pos[0], v.pos[1], v.pos[2]);
+      }
+    }
+    clips[name] = {
+      duration,
+      additive: true,
+      tracks: [...acc.entries()].map(([bone, e]) => ({
+        bone, times: e.times,
+        ...(e.rot ? { rot: e.rot } : {}),
+        ...(e.pos ? { pos: e.pos } : {}),
+      })),
+    };
+  }
+  return clips;
+}
+
+// Validate a zone generator's return: bring-your-own-bytes, checked hard.
+export function validateGeneratedZones(z, triangleCount) {
+  if (!z || !Array.isArray(z.names) || z.names.length === 0 || !z.names.every((n) => typeof n === 'string')) {
+    throw new Error('zone generator: "names" must be a non-empty array of zone name strings (index 0 is the default zone)');
+  }
+  if (z.names.length > 256) {
+    throw new Error(`zone generator: at most 256 zone names (got ${z.names.length}) — zones are stored one byte per triangle`);
+  }
+  const tri = z.tri;
+  const len = tri?.length ?? -1;
+  if (len !== triangleCount) {
+    throw new Error(`zone generator: "tri" must carry one byte per triangle — the mesh has ${triangleCount} triangles, got ${len}`);
+  }
+  const out = new Uint8Array(triangleCount);
+  for (let i = 0; i < triangleCount; i++) {
+    const v = tri[i];
+    if (!Number.isInteger(v) || v < 0 || v >= z.names.length) {
+      throw new Error(`zone generator: zone byte ${v} at triangle ${i} is out of range — must be an integer 0..${z.names.length - 1}`);
+    }
+    out[i] = v;
+  }
+  return { names: [...z.names], tri: out };
+}
+
 // ── the in-page bake ─────────────────────────────────────────────────────────
 // Runs inside the browser with three + GLTFLoader importable. Everything it
 // returns is plain JSON (typed arrays as b64).
@@ -404,19 +562,19 @@ async function bakeInPage(page, cfg) {
 // models lives there, so the loader that bakes and the loader that draws move
 // together, on engine releases. The bake never touches the network.
 const VENDOR_REL = 'shared/ui/room/vendor/three-gltf.js';
-function threeBundle(dir) {
+function engineFile(dir, rel) {
   const candidates = [
     // A standalone game: the engine installed under node_modules.
-    join(dir, 'node_modules/@looop-games/engine', VENDOR_REL),
+    join(dir, 'node_modules/@looop-games/engine', rel),
     // This CLI running from inside the engine repo itself.
-    join(import.meta.dirname, '../../..', VENDOR_REL),
+    join(import.meta.dirname, '../../..', rel),
   ];
   for (const c of candidates) if (existsSync(c)) return c;
   throw new Error(
-    'the installed engine does not include the model loader '
-    + `(${VENDOR_REL}) — run \`npx looop update\` to get a newer engine`,
+    `the installed engine does not include ${rel} — run \`npx looop update\` to get a newer engine`,
   );
 }
+const threeBundle = (dir) => engineFile(dir, VENDOR_REL);
 
 // ── the driver ───────────────────────────────────────────────────────────────
 
@@ -478,21 +636,117 @@ export async function bakeModel(glbPath, { dir = process.cwd(), log = console.lo
     if (w.badSums > 0) problems.push(`${w.badSums} vertices whose weights do not sum to ~1`);
     if (problems.length) throw new Error(`BAKE INVALID:\n  ${problems.join('\n  ')}`);
 
-    const source = { hash: sourceHash(glbBytes, configText), glb: basename(abs), bakeVersion: BAKE_VERSION };
+    const skeletonJson = {
+      root: { t: baked.root.t, r: baked.root.r, s: rootS },
+      bones: baked.bones.map((b) => ({ name: b.name, parent: b.parent, t: b.t, r: b.r, s: b.sAvg })),
+      clips: baked.clips,
+    };
+
+    // ── the generator script, if the config names one ────────────────────────
+    let genText = '';
+    let generatedNames = [];
+    let genZones = null;
+    if (cfg.generate) {
+      const scriptPath = resolve(dirname(abs), cfg.generate);
+      if (!existsSync(scriptPath)) {
+        throw new Error(`${basename(paths.config)} names generate: "${cfg.generate}" but ${scriptPath} does not exist`);
+      }
+      genText = readFileSync(scriptPath, 'utf8');
+      // The hash query re-imports a changed script within one process (node
+      // caches module URLs forever; ensureBaked may bake twice in one run).
+      const mod = await import(`${pathToFileURL(scriptPath).href}?v=${sha256(Buffer.from(genText)).slice(0, 12)}`);
+      if (!mod.clips && !mod.zones) {
+        throw new Error(`generator ${cfg.generate} exports neither clips nor zones — nothing to generate`);
+      }
+      const fromB64 = (Ctor, entry) => {
+        const buf = Buffer.from(entry.b64, 'base64');
+        return new Ctor(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
+      };
+      const model = {
+        bones: skeletonJson.bones,
+        clips: baked.clips,
+        mesh: {
+          vertexCount: baked.mesh.vertexCount,
+          triangleCount: baked.mesh.triangleCount,
+          influences: baked.mesh.influences,
+          position: fromB64(Float32Array, baked.mesh.position),
+          skinIndex: fromB64(Uint16Array, baked.mesh.skinIndex),
+          skinWeight: fromB64(Float32Array, baked.mesh.skinWeight),
+          index: fromB64(Uint32Array, baked.mesh.index),
+        },
+      };
+      const boneNames = skeletonJson.bones.map((b) => b.name);
+      if (mod.clips) {
+        const defs = typeof mod.clips === 'function' ? mod.clips(model) : mod.clips;
+        const generated = buildGeneratedClips(defs, boneNames, Object.keys(baked.clips));
+        generatedNames = Object.keys(generated);
+        Object.assign(skeletonJson.clips, generated);
+
+        // The broadphase sphere must contain every pose the LAYERS can reach —
+        // the in-page measure only saw the GLB's own clips. Skin the mesh
+        // through each generated clip alone at weight 1 and add each clip's
+        // worst vertex displacement to the radius. A sum over clips is
+        // deliberately conservative (layers combine): an oversized sphere only
+        // costs broadphase efficiency, an undersized one silently discards
+        // true hits on a flared wing. Weights are expected in [0, 1].
+        const rigLib = await import(pathToFileURL(engineFile(dir, 'shared/ui/room/lib/rig.js')).href);
+        const skinLib = await import(pathToFileURL(engineFile(dir, 'shared/ui/room/lib/skin-hit.js')).href);
+        const rig = rigLib.createRig(skeletonJson);
+        const root = { t: skeletonJson.root.t, r: skeletonJson.root.r, s: skeletonJson.root.s };
+        const skinned = skinLib.createSkinnedMesh({
+          vertexCount: model.mesh.vertexCount, influences: model.mesh.influences,
+          position: model.mesh.position, skinIndex: model.mesh.skinIndex,
+          skinWeight: model.mesh.skinWeight, index: model.mesh.index,
+          invBind: skinLib.restInvBind(rig, root),
+        });
+        const rest = Float32Array.from(skinLib.skin(skinned, rigLib.evaluate(rig, { root })));
+        let inflate = 0;
+        for (const name of generatedNames) {
+          const clip = skeletonJson.clips[name];
+          const STEPS = clip.duration > 0 ? 24 : 1;
+          let worst = 0;
+          for (let s = 0; s <= STEPS; s++) {
+            const t = clip.duration > 0 ? (clip.duration * s) / STEPS : 0;
+            const sample = rigLib.sampleAdditive(rig, name, t, 1);
+            const posed = skinLib.skin(skinned, rigLib.evaluate(rig, { ...sample, root }));
+            for (let v = 0; v < model.mesh.vertexCount * 3; v += 3) {
+              const d = Math.hypot(posed[v] - rest[v], posed[v + 1] - rest[v + 1], posed[v + 2] - rest[v + 2]);
+              if (d > worst) worst = d;
+            }
+          }
+          inflate += worst;
+        }
+        if (inflate > 0) baked.mesh.radius = (baked.mesh.radius + inflate) * 1.03;
+      }
+      if (mod.zones) {
+        if (cfg.zones && Object.keys(cfg.zones).length) {
+          throw new Error(`${basename(paths.config)} has BOTH a "zones" bone-name map and a generator exporting zones() — pick one strategy per model`);
+        }
+        const raw = typeof mod.zones === 'function' ? mod.zones(model) : mod.zones;
+        genZones = validateGeneratedZones(raw, baked.mesh.triangleCount);
+        const b64 = Buffer.from(genZones.tri).toString('base64');
+        baked.mesh.zones = { names: genZones.names, tri: { b64 } };
+        const counts = {};
+        genZones.names.forEach((n) => { counts[n] = 0; });
+        for (const z of genZones.tri) counts[genZones.names[z]]++;
+        baked.stats.zoneCounts = counts;
+      }
+    }
+
+    const source = { hash: sourceHash(glbBytes, configText, genText), glb: basename(abs), bakeVersion: BAKE_VERSION };
     const note = 'GENERATED by the Looop model baker — do not hand-edit; edit the GLB or its .bake.json and re-bake.';
     writeFileSync(paths.skeleton, JSON.stringify({
       _generated: note,
       _source: source,
-      root: { t: baked.root.t, r: baked.root.r, s: rootS },
-      bones: baked.bones.map((b) => ({ name: b.name, parent: b.parent, t: b.t, r: b.r, s: b.sAvg })),
-      clips: baked.clips,
+      ...skeletonJson,
     }, null, 1) + '\n');
     writeFileSync(paths.mesh, JSON.stringify({ _generated: note, _source: source, ...baked.mesh }) + '\n');
 
     const s = baked.stats;
     log(`baked ${basename(abs)} → ${basename(paths.skeleton)} + ${basename(paths.mesh)}`);
-    log(`  bones ${s.bones}   vertices ${s.V}   triangles ${s.T}   radius ${s.radius.toFixed(3)}`);
+    log(`  bones ${s.bones}   vertices ${s.V}   triangles ${s.T}   radius ${baked.mesh.radius.toFixed(3)}`);
     log(`  clips: ${s.clips.length ? s.clips.join(', ') : '(none in this GLB)'}`);
+    if (generatedNames.length) log(`  generated additive clips: ${generatedNames.join(', ')}`);
     if (s.zoneCounts) log(`  zones: ${Object.entries(s.zoneCounts).map(([k, v]) => `${k} ${v}`).join('  ')}`);
     for (const n of baked.notes) log(`  note: ${n}`);
     return { paths, stats: s, notes: baked.notes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@looop-games/cli",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "Looop game development CLI — dev server, login, and publishing for standalone Looop games.",
   "type": "module",
   "license": "Apache-2.0",