@looop-games/cli 0.1.20 → 0.1.21

package/CHANGELOG.md

@@ -14,6 +14,23 @@ 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

package/lib/model-bake.mjs

@@ -29,8 +29,9 @@
 //   {
 //     "zones": { "head": ["Head", "Neck*"], "arm": ["*_Arm*"] },
 //     "clips": ["fly", "idle"],       // subset to bake; default = all
-//     "generate": "drifter-gen.mjs"   // generator script, relative to the GLB
-//   }
+//     "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
@@ -64,7 +65,9 @@ import { pathToFileURL } from 'node:url';
 // meaning — it participates in the staleness hash, so old artifacts re-bake.
 // v2: the staleness hash gained the generator-script component, and skeletons
 // may carry generated additive clips.
-export const BAKE_VERSION = 2;
+// 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) ─────────────────────────────
 
@@ -106,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) {
@@ -478,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;
       }
     };
@@ -534,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: {
@@ -638,6 +686,7 @@ export async function bakeModel(glbPath, { dir = process.cwd(), log = console.lo
 
     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,
     };

package/package.json

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