@looop-games/cli 0.1.19 → 0.1.21

package/CHANGELOG.md

@@ -14,6 +14,45 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.21] - 2026-07-30
+
+### Added
+
+- **`looop model bake` resolves a pivot for the model.** `<model>.bake.json`
+  may declare `"pivot": "origin"` (default) | `"center"` | `"feet"` |
+  `[x, y, z]` — the model-space point that lands on your entity's
+  `body.(x,y,z)`. The bake resolves it against the bind-pose bounding box,
+  writes it into the skeleton artifact, and measures the broadphase radius
+  about it (a sphere centred on the pivot but measured from the origin could
+  silently reject true edge hits). Every model re-bakes once on your next
+  `looop dev`/`test`/`publish` to pick up the new artifact format; without a
+  `pivot` entry nothing changes in how it plays. Opting into a non-origin
+  pivot needs an engine that reads it (0.1.35+) — run `npx looop update`
+  first, or the room will place the model by its origin while the broadphase
+  is measured about the pivot.
+
+## [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,14 +28,23 @@
 // ── 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
+//     "pivot": "center"               // where body.(x,y,z) sits in the model:
+//   }                                 // "origin" (default) | "center" | "feet" | [x,y,z]
 // 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
 // bone-attached proxy shapes, pointed at triangles). Patterns match bone
 // 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 +58,16 @@
 
 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.
+// v3: skeletons carry a resolved `pivot`, and the broadphase radius is
+// measured about it instead of the model origin.
+export const BAKE_VERSION = 3;
 
 // ── pure helpers (unit-tested without a browser) ─────────────────────────────
 
@@ -95,6 +109,24 @@ export function boneZonesFromConfig(boneNames, zonesConfig) {
   return { names, byBone };
 }
 
+// Resolve the config's `pivot` — the model-space point that lands ON the
+// entity's body.(x,y,z) — against the bind-pose bounding box. There is no
+// universal right anchor (a flyer wants its centre, a walker its feet, a turret
+// its base), so it's a per-model choice; "origin" reproduces the GLB's own
+// origin and is the default. The resolved vector is written into the skeleton
+// artifact; the runtime composes it into PLACEMENT only, never the inverse
+// bind, so skinning is unaffected.
+export function resolvePivot(pivotCfg, bbox) {
+  if (pivotCfg == null || pivotCfg === 'origin') return [0, 0, 0];
+  const mid = (a) => (bbox.min[a] + bbox.max[a]) / 2;
+  if (pivotCfg === 'center') return [mid(0), mid(1), mid(2)];
+  if (pivotCfg === 'feet') return [mid(0), bbox.min[1], mid(2)];
+  if (Array.isArray(pivotCfg) && pivotCfg.length === 3 && pivotCfg.every((n) => Number.isFinite(n))) {
+    return [pivotCfg[0], pivotCfg[1], pivotCfg[2]];
+  }
+  throw new Error(`"pivot" must be "origin", "center", "feet", or [x, y, z] — got ${JSON.stringify(pivotCfg)}`);
+}
+
 // The dominant bone of a triangle: the bone with the highest summed skin weight
 // across its three vertices. `acc` is scratch sized to the bone count.
 export function dominantBone(skinIndex, skinWeight, influences, index, tri, acc) {
@@ -112,13 +144,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 +162,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 +191,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).
@@ -320,18 +499,44 @@ async function bakeInPage(page, cfg) {
       clips[anim.name] = { duration: anim.duration, tracks };
     }
 
+    // ── pivot: where body.(x,y,z) sits in the model ──────────────────────────
+    // Resolved against the bind-pose bbox of the extracted positions. Mirrors
+    // resolvePivot — this copy runs in-page, because the broadphase radius
+    // below must be measured about the pivot: the runtime centres its sphere on
+    // body, and body IS the pivot point, so a radius measured about the origin
+    // could undersize the sphere and silently reject true edge hits.
+    const bbox = { min: [Infinity, Infinity, Infinity], max: [-Infinity, -Infinity, -Infinity] };
+    for (let i = 0; i < V * 3; i += 3) {
+      for (let a = 0; a < 3; a++) {
+        const c = position[i + a];
+        if (c < bbox.min[a]) bbox.min[a] = c;
+        if (c > bbox.max[a]) bbox.max[a] = c;
+      }
+    }
+    let pivot;
+    {
+      const p = config.pivot;
+      const mid = (a) => (bbox.min[a] + bbox.max[a]) / 2;
+      if (p == null || p === 'origin') pivot = [0, 0, 0];
+      else if (p === 'center') pivot = [mid(0), mid(1), mid(2)];
+      else if (p === 'feet') pivot = [mid(0), bbox.min[1], mid(2)];
+      else if (Array.isArray(p) && p.length === 3 && p.every((n) => Number.isFinite(n))) pivot = [p[0], p[1], p[2]];
+      else return { error: `"pivot" must be "origin", "center", "feet", or [x, y, z] — got ${JSON.stringify(p)}` };
+    }
+
     // ── broadphase radius: worst case across rest + every baked clip ─────────
     // The sphere exists to REJECT cheaply, so it must never reject a true hit:
     // measure every pose the clips can produce, then carry 3% slack (a ray
     // grazing an extremity is near-tangent, and float error then discards a hit
-    // that visibly connects).
+    // that visibly connects). Distances are about the pivot — the sphere's
+    // runtime centre.
     let radius = 0;
     const measure = () => {
       scene.updateMatrixWorld(true);
       sk.skeleton.update?.();
       for (let i = 0; i < V; i++) {
         sk.getVertexPosition(i, v3);
-        const d = Math.hypot(v3.x, v3.y, v3.z);
+        const d = Math.hypot(v3.x - pivot[0], v3.y - pivot[1], v3.z - pivot[2]);
         if (d > radius) radius = d;
       }
     };
@@ -376,6 +581,7 @@ async function bakeInPage(page, cfg) {
     return {
       notes,
       root: { t: [rp.x, rp.y, rp.z], r: [rq.x, rq.y, rq.z, rq.w], s: [rs.x, rs.y, rs.z] },
+      pivot,
       bones: outBones,
       clips,
       mesh: {
@@ -404,19 +610,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 +684,118 @@ 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 },
+      pivot: baked.pivot,
+      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.21",
   "description": "Looop game development CLI — dev server, login, and publishing for standalone Looop games.",
   "type": "module",
   "license": "Apache-2.0",