@looop-games/cli 0.1.17 → 0.1.19

package/CHANGELOG.md

@@ -14,6 +14,40 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.19] - 2026-07-22
+
+### Added
+
+- **Your 3D models bake themselves.** `looop dev`, `looop test`, and
+  `looop publish` now notice when a GLB your entities reference has changed
+  (or its `<model>.bake.json` zone config has) and quietly regenerate the
+  server-side hit data — `<model>.skeleton.json` + `<model>.mesh.json`,
+  committed next to the model — so the server always shoots at the surface you
+  see. A model that can't bake stops the command with the reason and the fix
+  (a scale-carrying export, an unsupported fifth skin influence, a zone
+  pattern matching no bone), never a silently stale surface. Force a re-bake
+  or debug one with the new **`looop model bake <file.glb>`**. Baking parses
+  your GLB with the browser's own loader in a headless page — the exact code
+  that draws it — so what gets baked is what gets drawn. The loader ships
+  inside the engine, not with the `looop` command, so a game that never
+  touches a 3D model downloads nothing extra. Requires engine 0.1.32 or
+  newer; run `looop update` if your game pins an older one.
+
+## [0.1.18] - 2026-07-15
+
+### Added
+
+- **`looop dev`, `looop test`, and `looop publish` understand entity
+  components.** A game that declares behavior in `components/` folders (the
+  entity system — see `shared/practices/entities.md` in your installed engine)
+  now works across the whole command surface: `dev` bundles your components
+  into the local room server, `test` runs the entity graph lint out of the
+  installed engine before anything else (it runs even when eslint isn't
+  installed in the game), and `publish` bundles them into your game's own
+  multiplayer server — a component game is server-backed automatically,
+  exactly like a primitives game. Requires engine 0.1.27 or newer; run
+  `looop update` if your game pins an older one.
+
 ## [0.1.17] - 2026-07-14
 
 ### Added

package/bin/looop.mjs

@@ -32,6 +32,7 @@ Usage:
   looop lint [--fix]         Check the game against the Looop rules (runs inside 'looop test')
   looop changelog [<v>]      What changed in the engine (default: everything newer than your pin)
   looop update               Move this game to the latest engine release (re-pins looop.engine)
+  looop model bake <glb>     Re-bake a 3D model's server-side hit data now (normally automatic)
   looop publish [--slug <s>]  Publish this game to play.looop.games (--slug for an A/B copy)
   looop feedback             Send the unsent reports under notes/feedback/ to the Looop team
   looop login                Authenticate this machine as your Looop player account
@@ -87,6 +88,17 @@ try {
     case 'update':
       await update();
       break;
+    case 'model': {
+      // `model` is the accessor for 3D-model tooling; `bake` is its first verb.
+      // Baking is normally automatic (dev/test/publish re-bake changed models);
+      // this is the explicit escape hatch.
+      const [verb, glb] = rest.filter((a) => !a.startsWith('--'));
+      if (verb !== 'bake') throw new Error(`Unknown model command: ${verb ?? '(none)'} — try: looop model bake <file.glb>`);
+      if (!glb) throw new Error('Name the model: looop model bake <file.glb>');
+      const { bakeModel } = await import('../lib/model-bake.mjs');
+      await bakeModel(glb);
+      break;
+    }
     case 'publish':
       await publish({ slug: flag('slug') });
       break;

package/lib/bundle-primitives.mjs

@@ -17,6 +17,7 @@
 // class past the setInterval/park cost boundary. Keeping it external means the
 // worker's room code is always ours.
 import { assertNoOverrideCycle, PRIMITIVES_DIR, SERVER_BARREL, renderBarrel, scanPrimitives } from './primitives.mjs';
+import { scanEntityComponents, renderEntityComponents } from './room-server.mjs';
 import { shadowResolvePlugin } from './shadow-resolve.mjs';
 import { join } from 'node:path';
 
@@ -29,17 +30,19 @@ export const PRIMITIVES_ENTRY = SERVER_BARREL;
 // engine import in the primitives bundle is rewritten to this.
 export const ENGINE_ARTIFACT_MODULE = './rooms-runtime.js';
 
-export async function bundlePrimitives(projectDir, { esbuildImpl } = {}) {
+export async function bundlePrimitives(projectDir, { esbuildImpl, engineSharedDir } = {}) {
   // The barrel is GENERATED, not authored. A creator adds a primitive by adding
-  // a file to `overrides/shared/ui/room/primitives/` — there is no list to keep
-  // in sync, and therefore no way for the list and the folder to disagree.
+  // a file to `overrides/shared/ui/room/primitives/` — and an entity component
+  // by adding a folder under components/ — there is no list to keep in sync,
+  // and therefore no way for the list and the folder to disagree.
   const primitives = scanPrimitives(projectDir); // throws on a reserved index.js
-  if (!primitives.length) {
+  const engineShared = engineSharedDir ?? join(projectDir, 'node_modules/@looop-games/engine/shared');
+  const entityComponents = await scanEntityComponents(projectDir, engineShared); // throws on a malformed component
+  if (!primitives.length && !entityComponents.length) {
     throw new Error(
-      `no server primitives to bundle — ${PRIMITIVES_DIR}/ is empty (this is not a server-backed game)`,
+      `nothing to bundle — ${PRIMITIVES_DIR}/ and components/ are both empty (this is not a server-backed game)`,
     );
   }
-  const engineShared = join(projectDir, 'node_modules/@looop-games/engine/shared');
   assertNoOverrideCycle(primitives, projectDir, engineShared);
 
   const esbuild = esbuildImpl ?? (await import('esbuild'));
@@ -68,7 +71,7 @@ export async function bundlePrimitives(projectDir, { esbuildImpl } = {}) {
     // against the game root so `./overrides/...` means what it says. Same shape
     // the dev room server uses (lib/room-server.mjs) — one contract, two builds.
     stdin: {
-      contents: renderBarrel(primitives),
+      contents: `${renderBarrel(primitives)}\n${renderEntityComponents(entityComponents)}\n`,
       resolveDir: projectDir,
       sourcefile: 'looop-primitives.js',
       loader: 'js',

package/lib/dev.mjs

@@ -53,6 +53,13 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
   // the platform's login-gated registry (no-op when the pinned version is in).
   const engine = await ensureEngine(project.dir, { log });
 
+  // Any 3D model the entity definitions reference re-bakes when its GLB (or
+  // bake config) changed — the server must hit the surface the player sees. A
+  // bake failure stops the stack with the model named rather than serving a
+  // room that shoots at yesterday's shape.
+  const { ensureBaked } = await import('./model-bake.mjs');
+  await ensureBaked({ dir: project.dir, log });
+
   // Which ports, and may we take them? An explicit --port is obeyed as given
   // (takeover included). With no flag we step around anyone else's stack —
   // another lane, another game, an unrelated app — and only ever reclaim our

package/lib/lint.mjs

@@ -57,21 +57,46 @@ async function loadRulesFromEngine(projectDir) {
   return { configs: mod.configs ?? mod.default?.configs ?? null, why: 'ok' };
 }
 
+// The entity graph lint — the SECOND shared step, alongside the eslint rules.
+// Like the rules, the implementation lives in the ENGINE (shared/ui/room/
+// entity/lint-run.mjs), so every gate that checks a game runs the identical
+// pass — there is no second copy to drift. An engine too old to carry it
+// skips — same degradation contract as the rules.
+async function loadEntityLintFromEngine(projectDir) {
+  let engineDir;
+  try {
+    ({ dir: engineDir } = resolveEngine(projectDir));
+  } catch {
+    return null;
+  }
+  const entry = join(engineDir, 'shared', 'ui', 'room', 'entity', 'lint-run.mjs');
+  if (!existsSync(entry)) return null;
+  const mod = await import(pathToFileURL(entry).href);
+  return mod.runEntityLint ?? null;
+}
+
 export async function lintCmd({
   cwd = process.cwd(),
   fix = false,
   log = console.log,
   loadEslint = loadFromProject,
   loadRules = loadRulesFromEngine,
+  loadEntityLint = loadEntityLintFromEngine,
 } = {}) {
   const project = findProject(cwd);
 
+  // The entity graph check runs regardless of the eslint tooling below — a
+  // missing dev tool must never switch off a structural guarantee. It skips
+  // itself silently for games with no entity folders.
+  const runEntity = await loadEntityLint(project.dir);
+  const entity = runEntity ? await runEntity(project.dir, { log }) : { ok: true, skipped: true };
+
   const ESLint = await loadEslint(project.dir);
   if (!ESLint) {
     log('⚠️  looop lint: eslint is not installed in this game — skipping the rule checks.');
     log('   To turn them on (recommended — they catch bugs that silently pass your tests):');
     log('     npm i -D eslint');
-    return { ok: true, skipped: true, errorCount: 0, warningCount: 0 };
+    return { ok: entity.ok, skipped: true, errorCount: 0, warningCount: 0, entity };
   }
 
   const { configs, why } = await loadRules(project.dir);
@@ -87,7 +112,7 @@ export async function lintCmd({
       log('⚠️  looop lint: your engine is older than the Looop rules — skipping.');
       log('   Get an engine that carries them:  looop update');
     }
-    return { ok: true, skipped: true, errorCount: 0, warningCount: 0 };
+    return { ok: entity.ok, skipped: true, errorCount: 0, warningCount: 0, entity };
   }
 
   // A game that ships its own eslint.config.js owns its rules — we do not
@@ -131,10 +156,11 @@ export async function lintCmd({
   }
 
   return {
-    ok: errorCount === 0,
+    ok: errorCount === 0 && entity.ok,
     skipped: false,
     errorCount,
     warningCount,
+    entity,
     files: results.map((r) => relative(project.dir, r.filePath)),
   };
 }

package/lib/model-bake-cli.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// Thin executable wrapper over the model baker. The normal front door is
+// `looop model bake <glb>` (bin/looop.mjs); this file exists so other tooling
+// can exec the same implementation directly. One baker, two entrances.
+import { bakeModel } from './model-bake.mjs';
+
+const glb = process.argv[2];
+if (!glb) {
+  console.error('usage: model-bake <file.glb>   (bakes <file>.skeleton.json + <file>.mesh.json beside it)');
+  process.exit(2);
+}
+try {
+  await bakeModel(glb);
+} catch (err) {
+  console.error(`model bake: ${err.message}`);
+  process.exit(1);
+}

package/lib/model-bake.mjs

@@ -0,0 +1,545 @@
+// model bake — turn a rigged GLB into the artifacts the room needs to hit the
+// model's true animated surface:
+//
+//   <model>.skeleton.json   bones (parent, rest transform) + baked clips — what
+//                           shared/ui/room/lib/rig.js poses
+//   <model>.mesh.json       vertices, skin weights, triangles, per-triangle zone
+//                           bytes, broadphase radius — what skin-hit.js shoots
+//
+// Both are emitted TOGETHER from one read of one loaded model, because they share
+// a bone ordering: the mesh's skin indices are meaningless against a differently
+// ordered skeleton.
+//
+// The GLB is parsed by three.js's own GLTFLoader in a REAL browser (playwright),
+// not by a node-side parser. The browser's loader is the same code that will draw
+// the model at runtime, so whatever it decides about the asset (bone order, node
+// transforms, interleaved buffers) is by construction what the drawn model does.
+// A second parser would be a second opinion, and a second opinion is exactly the
+// drift class this pipeline exists to delete. The page is hermetic: every request
+// (three, the loader, the GLB bytes) is fulfilled from local disk via route
+// interception — no network, no server.
+//
+// Baking is normally AUTOMATIC: dev/test/publish call `ensureBaked()` and re-bake
+// any referenced GLB whose content hash no longer matches the artifact's recorded
+// source hash. `looop model bake <glb>` is the explicit escape hatch (debugging,
+// forcing a re-bake). Artifacts are committed next to the model like any other
+// game file.
+//
+// ── Optional bake config: <model>.bake.json next to the GLB ──────────────────
+//   {
+//     "zones": { "head": ["Head", "Neck*"], "arm": ["*_Arm*"] },
+//     "clips": ["fly", "idle"]        // subset to bake; default = all
+//   }
+// 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`.
+//
+// ── 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)
+//   - >4 skin influences per vertex, non-uniform bone scale, non-unit rotations
+//     (scale left in a matrix — the drifter's 17° bug, caught at bake)
+//   - skin weights outside [0,1] or not summing to ~1 (the fingerprint of reading
+//     interleaved attributes through `.array` instead of the accessors)
+// Root-bone POSITION tracks are stripped by default and reported: the entity's
+// own movement owns where the creature is, and keeping root motion would apply
+// it twice.
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+
+// 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;
+
+// ── pure helpers (unit-tested without a browser) ─────────────────────────────
+
+// Sort bones parent-first and produce old→new remap. rig.js poses in one forward
+// pass, so every parent must precede its children; a GLB does not promise that.
+export function sortBonesParentFirst(raw) {
+  const order = [];
+  const placed = new Set();
+  for (let guard = 0; order.length < raw.length && guard <= raw.length; guard++) {
+    for (let i = 0; i < raw.length; i++) {
+      if (placed.has(i)) continue;
+      if (raw[i].parent < 0 || placed.has(raw[i].parent)) { order.push(i); placed.add(i); }
+    }
+  }
+  if (order.length !== raw.length) throw new Error('skeleton is not a tree (parent cycle)');
+  const remap = new Int32Array(raw.length);
+  order.forEach((old, neu) => { remap[old] = neu; });
+  return { order, remap };
+}
+
+// Bone-name pattern matching for the zones config. `*` matches any run of
+// characters; matching is case-sensitive (bone names are authored identifiers).
+export function matchesPattern(name, pattern) {
+  if (!pattern.includes('*')) return name === pattern;
+  const rx = new RegExp(`^${pattern.split('*').map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`);
+  return rx.test(name);
+}
+
+// Map each bone to a zone byte from the config. Zone 0 is always the implicit
+// "body" (every unmatched bone); config keys become zones 1..n in key order.
+export function boneZonesFromConfig(boneNames, zonesConfig) {
+  const names = ['body', ...Object.keys(zonesConfig)];
+  const byBone = new Uint8Array(boneNames.length);
+  boneNames.forEach((bn, i) => {
+    for (let z = 1; z < names.length; z++) {
+      if (zonesConfig[names[z]].some((p) => matchesPattern(bn, p))) { byBone[i] = z; return; }
+    }
+  });
+  return { names, byBone };
+}
+
+// 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) {
+  acc.fill(0);
+  for (let k = 0; k < 3; k++) {
+    const v = index[tri * 3 + k];
+    for (let j = 0; j < influences; j++) acc[skinIndex[v * influences + j]] += skinWeight[v * influences + j];
+  }
+  let best = 0, bestW = -1;
+  for (let b = 0; b < acc.length; b++) if (acc[b] > bestW) { bestW = acc[b]; best = b; }
+  return best;
+}
+
+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) {
+  return sha256(Buffer.concat([
+    Buffer.from(`bake${BAKE_VERSION}!`),
+    Buffer.from(sha256(glbBytes)),
+    Buffer.from(sha256(Buffer.from(configText ?? ''))),
+  ]));
+}
+
+export function artifactPaths(glbPath) {
+  const stem = glbPath.replace(/\.glb$/i, '');
+  return { skeleton: `${stem}.skeleton.json`, mesh: `${stem}.mesh.json`, config: `${stem}.bake.json` };
+}
+
+// Is the artifact pair current for this GLB + config? (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 have = JSON.parse(readFileSync(skeleton, 'utf8'))?._source?.hash;
+    return have !== want;
+  } catch {
+    return true;   // unreadable artifact = stale artifact
+  }
+}
+
+// ── the in-page bake ─────────────────────────────────────────────────────────
+// Runs inside the browser with three + GLTFLoader importable. Everything it
+// returns is plain JSON (typed arrays as b64).
+
+const PAGE_HTML = `<!doctype html><html><head>
+</head><body><script type="module">
+import { THREE, GLTFLoader } from '/vendor/three-gltf.js';
+window.THREE = THREE; window.GLTFLoader = GLTFLoader; window.__ready = true;
+</script></body></html>`;
+
+// Serialized into the page. `cfg` = { zones, clips } (already parsed).
+async function bakeInPage(page, cfg) {
+  return page.evaluate(async (config) => {
+    const THREE = window.THREE;
+    const notes = [];
+
+    const buf = await (await fetch('/model.glb')).arrayBuffer();
+    const gltf = await new window.GLTFLoader().parseAsync(buf, '/');
+    const scene = gltf.scene;
+    scene.updateMatrixWorld(true);
+
+    // The mesh: the largest SkinnedMesh (a model may carry extras — eyes, teeth).
+    const skinned = [];
+    scene.traverse((o) => { if (o.isSkinnedMesh) skinned.push(o); });
+    if (!skinned.length) return { error: 'no skinned mesh in this GLB — is the model rigged?' };
+    skinned.sort((a, b) => b.geometry.attributes.position.count - a.geometry.attributes.position.count);
+    const sk = skinned[0];
+    if (skinned.length > 1) {
+      notes.push(`model has ${skinned.length} skinned meshes — baked the largest ` +
+        `(${sk.geometry.attributes.position.count} verts); the others are visual-only`);
+    }
+
+    // REST = BIND. skin-hit derives the inverse bind from the rig's rest pose, so
+    // the rest transforms recorded here MUST be the bind pose — not whatever pose
+    // the file happened to save. three's Skeleton.pose() restores exactly that.
+    sk.skeleton.pose();
+    scene.updateMatrixWorld(true);
+
+    const bones = sk.skeleton.bones;
+    const srcIdx = new Map(bones.map((b, i) => [b, i]));
+    const raw = bones.map((b) => ({
+      name: b.name,
+      parent: srcIdx.has(b.parent) ? srcIdx.get(b.parent) : -1,
+      t: [b.position.x, b.position.y, b.position.z],
+      r: [b.quaternion.x, b.quaternion.y, b.quaternion.z, b.quaternion.w],
+      s: [b.scale.x, b.scale.y, b.scale.z],
+    }));
+
+    // Parent-first sort (rig.js poses in one forward pass); remap carried into
+    // skinIndex below. Mirrors sortBonesParentFirst — this copy runs in-page.
+    const order = [];
+    const placed = new Set();
+    for (let guard = 0; order.length < raw.length && guard <= raw.length; guard++) {
+      for (let i = 0; i < raw.length; i++) {
+        if (placed.has(i)) continue;
+        if (raw[i].parent < 0 || placed.has(raw[i].parent)) { order.push(i); placed.add(i); }
+      }
+    }
+    if (order.length !== raw.length) return { error: 'skeleton is not a tree (parent cycle)' };
+    const remap = new Int32Array(raw.length);
+    order.forEach((old, neu) => { remap[old] = neu; });
+    const outBones = order.map((old) => {
+      const b = raw[old];
+      return { name: b.name, parent: b.parent < 0 ? -1 : remap[b.parent], t: b.t, r: b.r, s: b.s };
+    });
+    const boneNames = outBones.map((b) => b.name);
+
+    // Model-space root: from scene origin to the skeleton's parent. The artifact
+    // is baked in the GLB's own space; the GAME places it in the world at runtime
+    // (rig.evaluate's `root`), so the artifact stays game-agnostic.
+    const topBone = bones.find((b) => !srcIdx.has(b.parent)) || bones[0];
+    const rootM = topBone.parent ? topBone.parent.matrixWorld.clone() : new THREE.Matrix4();
+    const rp = new THREE.Vector3(), rq = new THREE.Quaternion(), rs = new THREE.Vector3();
+    rootM.decompose(rp, rq, rs);
+
+    // ── mesh, in scene space at bind pose ────────────────────────────────────
+    const geo = sk.geometry;
+    const V = geo.attributes.position.count;
+    const v3 = new THREE.Vector3();
+    const position = new Float32Array(V * 3);
+    for (let i = 0; i < V; i++) {
+      sk.getVertexPosition(i, v3);           // bind-pose surface (skeleton is posed to bind)
+      position[i * 3] = v3.x; position[i * 3 + 1] = v3.y; position[i * 3 + 2] = v3.z;
+    }
+
+    const si = geo.attributes.skinIndex, sw = geo.attributes.skinWeight;
+    if (geo.attributes.skinIndex1) return { error: 'mesh uses >4 skin influences (skinIndex1) — unsupported' };
+    const inf = si.itemSize;
+    const skinIndex = new Uint16Array(V * inf);
+    const skinWeight = new Float32Array(V * inf);
+    // Through the ACCESSORS, never `.array`: interleaved buffers make `.array`
+    // return neighbouring attributes — silently, with the right length.
+    const get = (attr, i, k) => (k === 0 ? attr.getX(i) : k === 1 ? attr.getY(i) : k === 2 ? attr.getZ(i) : attr.getW(i));
+    for (let v = 0; v < V; v++) {
+      for (let k = 0; k < inf; k++) {
+        skinIndex[v * inf + k] = remap[get(si, v, k)];
+        skinWeight[v * inf + k] = get(sw, v, k);
+      }
+    }
+
+    const idxAttr = geo.index;
+    const index = new Uint32Array(idxAttr ? idxAttr.count : V);
+    if (idxAttr) for (let i = 0; i < idxAttr.count; i++) index[i] = idxAttr.getX(i);
+    else for (let i = 0; i < V; i++) index[i] = i;
+    const T = index.length / 3;
+
+    // ── zones: dominant bone → configured zone, per triangle ─────────────────
+    let zones = null;
+    if (config.zones && Object.keys(config.zones).length) {
+      const names = ['body', ...Object.keys(config.zones)];
+      const match = (name, pattern) => {
+        if (!pattern.includes('*')) return name === pattern;
+        const rx = new RegExp('^' + pattern.split('*').map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$');
+        return rx.test(name);
+      };
+      const byBone = new Uint8Array(outBones.length);
+      const unmatchedPatterns = [];
+      for (let z = 1; z < names.length; z++) {
+        for (const p of config.zones[names[z]]) {
+          if (!boneNames.some((bn) => match(bn, p))) unmatchedPatterns.push(p);
+        }
+      }
+      if (unmatchedPatterns.length) {
+        return { error: `zone patterns match no bone: ${unmatchedPatterns.join(', ')} — bones are: ${boneNames.join(', ')}` };
+      }
+      boneNames.forEach((bn, i) => {
+        for (let z = 1; z < names.length; z++) {
+          if (config.zones[names[z]].some((p) => match(bn, p))) { byBone[i] = z; return; }
+        }
+      });
+      const zoneTri = new Uint8Array(T);
+      const acc = new Float64Array(outBones.length);
+      for (let t = 0; t < T; t++) {
+        acc.fill(0);
+        for (let k = 0; k < 3; k++) {
+          const v = index[t * 3 + k];
+          for (let j = 0; j < inf; j++) acc[skinIndex[v * inf + j]] += skinWeight[v * inf + j];
+        }
+        let best = 0, bestW = -1;
+        for (let b = 0; b < acc.length; b++) if (acc[b] > bestW) { bestW = acc[b]; best = b; }
+        zoneTri[t] = byBone[best];
+      }
+      const counts = {};
+      names.forEach((n) => { counts[n] = 0; });
+      for (let t = 0; t < T; t++) counts[names[zoneTri[t]]]++;
+      zones = { names, zoneTri, counts };
+    }
+
+    // ── clips: every GLB animation, rotation + position tracks ───────────────
+    const wanted = config.clips ?? null;
+    const clips = {};
+    const rootBoneName = outBones.find((b) => b.parent === -1)?.name;
+    for (const anim of gltf.animations ?? []) {
+      if (wanted && !wanted.includes(anim.name)) continue;
+      const tracks = [];
+      for (const tr of anim.tracks) {
+        const m = tr.name.match(/^(.*)\.(quaternion|position|scale)$/);
+        if (!m) { notes.push(`clip "${anim.name}": skipped unrecognised track ${tr.name}`); continue; }
+        const [, nodeName, prop] = m;
+        if (!boneNames.includes(nodeName)) {
+          notes.push(`clip "${anim.name}": track for "${nodeName}" targets a non-bone node — skipped`);
+          continue;
+        }
+        if (prop === 'scale') {
+          return { error: `clip "${anim.name}" has a SCALE track on bone "${nodeName}". The room's rig is uniform-scale ` +
+            `and cannot reproduce it, so the hit surface would drift off the drawn model. Strip scale tracks in your export.` };
+        }
+        if (prop === 'position' && nodeName === rootBoneName) {
+          notes.push(`clip "${anim.name}": stripped root-motion position track on "${nodeName}" — ` +
+            `the entity's own movement carries the creature; keeping it would apply the motion twice`);
+          continue;
+        }
+        const entry = { bone: nodeName, times: Array.from(tr.times) };
+        if (prop === 'quaternion') entry.rot = Array.from(tr.values);
+        else entry.pos = Array.from(tr.values);
+        tracks.push(entry);
+      }
+      clips[anim.name] = { duration: anim.duration, tracks };
+    }
+
+    // ── 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).
+    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);
+        if (d > radius) radius = d;
+      }
+    };
+    measure();                                             // rest pose
+    const mixer = new THREE.AnimationMixer(scene);
+    for (const anim of gltf.animations ?? []) {
+      if (wanted && !wanted.includes(anim.name)) continue;
+      const action = mixer.clipAction(anim);
+      action.play();
+      const STEPS = 24;
+      for (let s = 0; s <= STEPS; s++) {
+        mixer.setTime((anim.duration * s) / STEPS);
+        measure();
+      }
+      action.stop();
+    }
+    sk.skeleton.pose();                                    // back to bind
+    scene.updateMatrixWorld(true);
+    radius *= 1.03;
+
+    // ── weight sanity, while the source is still in hand ─────────────────────
+    let min = Infinity, max = -Infinity, outOfRange = 0, badSums = 0;
+    for (let i = 0; i < skinWeight.length; i++) {
+      const w = skinWeight[i];
+      if (w < min) min = w; if (w > max) max = w;
+      if (w < -1e-4 || w > 1 + 1e-4) outOfRange++;
+    }
+    for (let v = 0; v < V; v++) {
+      let s = 0;
+      for (let k = 0; k < inf; k++) s += skinWeight[v * inf + k];
+      if (Math.abs(s - 1) > 0.02) badSums++;
+    }
+
+    const b64 = (ta) => {
+      const u8 = new Uint8Array(ta.buffer, ta.byteOffset, ta.byteLength);
+      let s = '';
+      const CH = 0x8000;
+      for (let i = 0; i < u8.length; i += CH) s += String.fromCharCode.apply(null, u8.subarray(i, i + CH));
+      return btoa(s);
+    };
+
+    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] },
+      bones: outBones,
+      clips,
+      mesh: {
+        vertexCount: V, triangleCount: T, influences: inf, radius,
+        position: { b64: b64(position) },
+        skinIndex: { b64: b64(skinIndex) },
+        skinWeight: { b64: b64(skinWeight) },
+        index: { b64: b64(index) },
+        ...(zones ? { zones: { names: zones.names, tri: { b64: b64(zones.zoneTri) } } } : {}),
+      },
+      weightCheck: { min, max, outOfRange, badSums },
+      stats: {
+        V, T, inf, radius, bones: outBones.length,
+        clips: Object.keys(clips),
+        ...(zones ? { zoneCounts: zones.counts } : {}),
+      },
+    };
+  }, cfg);
+}
+
+// ── locating the loader bundle (served to the hermetic page) ─────────────────
+// three + GLTFLoader ship VENDORED inside the engine (shared/ui/room/vendor/
+// three-gltf.js, one self-contained ESM file) rather than as a dependency of
+// this CLI — a 2D game must never download three just to own a `looop` binary.
+// The engine is also the right owner of the version pin: the code that DRAWS
+// 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) {
+  const candidates = [
+    // A standalone game: the engine installed under node_modules.
+    join(dir, 'node_modules/@looop-games/engine', VENDOR_REL),
+    // This CLI running from inside the engine repo itself.
+    join(import.meta.dirname, '../../..', VENDOR_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 driver ───────────────────────────────────────────────────────────────
+
+export async function bakeModel(glbPath, { dir = process.cwd(), log = console.log } = {}) {
+  const abs = resolve(glbPath);
+  if (!existsSync(abs)) throw new Error(`no such file: ${glbPath}`);
+  const paths = artifactPaths(abs);
+  const glbBytes = readFileSync(abs);
+  const configText = existsSync(paths.config) ? readFileSync(paths.config, 'utf8') : '';
+  let cfg = {};
+  if (configText) {
+    try { cfg = JSON.parse(configText); } catch (e) {
+      throw new Error(`${basename(paths.config)} is not valid JSON: ${e.message}`);
+    }
+  }
+
+  const { chromium } = await import('playwright');
+  const bundle = threeBundle(dir);
+  const browser = await chromium.launch();
+  try {
+    const page = await browser.newPage();
+    const pageErrors = [];
+    page.on('pageerror', (e) => pageErrors.push(e.message));
+    await page.route('**/*', (route) => {
+      const url = new URL(route.request().url());
+      const p = url.pathname;
+      if (p === '/' || p === '/bake.html') return route.fulfill({ contentType: 'text/html', body: PAGE_HTML });
+      if (p === '/model.glb') return route.fulfill({ contentType: 'model/gltf-binary', body: glbBytes });
+      if (p === '/vendor/three-gltf.js') {
+        return route.fulfill({ contentType: 'text/javascript', body: readFileSync(bundle) });
+      }
+      return route.fulfill({ status: 404, body: 'not baked in' });
+    });
+    await page.goto('http://bake.looop.invalid/bake.html');
+    await page.waitForFunction(() => window.__ready === true, { timeout: 30_000 });
+
+    const baked = await bakeInPage(page, cfg);
+    if (baked.error) {
+      throw new Error(`${baked.error}${pageErrors.length ? `\n(page errors: ${pageErrors.join('; ')})` : ''}`);
+    }
+
+    // ── validate before writing — a bad artifact must never reach the room ───
+    const problems = [];
+    const uni = (s, what) => {
+      const m = Math.max(Math.abs(s[0]), Math.abs(s[1]), Math.abs(s[2])) || 1;
+      if (Math.abs(s[0] - s[1]) / m > 1e-3 || Math.abs(s[0] - s[2]) / m > 1e-3) problems.push(`${what} scale is non-uniform: ${s}`);
+      return (s[0] + s[1] + s[2]) / 3;
+    };
+    const rootS = uni(baked.root.s, 'root');
+    baked.bones.forEach((b, i) => {
+      if (b.parent >= i) problems.push(`bone ${i} ${b.name}: parent ${b.parent} does not precede it`);
+      const L = Math.hypot(...b.r);
+      if (Math.abs(L - 1) > 1e-3) problems.push(`bone ${i} ${b.name}: rotation not unit (${L.toFixed(4)}) — scale left in the matrix`);
+      b.sAvg = uni(b.s, `bone ${i} ${b.name}`);
+    });
+    if (!(baked.mesh.radius > 0)) problems.push('broadphase radius is not positive');
+    const w = baked.weightCheck;
+    if (w.outOfRange > 0) problems.push(`${w.outOfRange} skin weights outside [0,1] (range ${w.min.toFixed(3)}..${w.max.toFixed(3)}) — attributes read wrongly?`);
+    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 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,
+    }, 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(`  clips: ${s.clips.length ? s.clips.join(', ') : '(none in this GLB)'}`);
+    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 };
+  } finally {
+    await browser.close();
+  }
+}
+
+// ── auto-bake: the staleness sweep dev/test/publish run ──────────────────────
+// The game's entity definitions say which models matter: any string field ending
+// in `.glb` inside entities/**/entity.json is a model reference. Model paths are
+// GAME-ROOT-relative — the same string is the presenter's fetch URL (the page
+// sits at the game root) and the room registry key — so they resolve against the
+// game dir here too. Each referenced GLB whose artifacts are missing or stale
+// re-bakes. A bake failure is a real failure — surfaced with the model named,
+// never swallowed: a stale artifact means the server shoots at a shape the
+// player no longer sees.
+
+export function referencedModels(gameDir) {
+  const found = new Set();
+  const scan = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const e of readdirSync(dir)) {
+      const p = join(dir, e);
+      const st = statSync(p);
+      if (st.isDirectory()) { if (e !== 'node_modules') scan(p); continue; }
+      if (!/entity\.json$/.test(e)) continue;
+      const walk = (v) => {
+        if (typeof v === 'string') { if (/\.glb$/i.test(v)) found.add(resolve(gameDir, v)); }
+        else if (Array.isArray(v)) v.forEach(walk);
+        else if (v && typeof v === 'object') Object.values(v).forEach(walk);
+      };
+      try { walk(JSON.parse(readFileSync(p, 'utf8'))); } catch { /* a broken entity.json fails its own gate */ }
+    }
+  };
+  scan(join(gameDir, 'entities'));
+  return [...found].filter(existsSync);
+}
+
+export async function ensureBaked({ dir = process.cwd(), log = console.log } = {}) {
+  const models = referencedModels(dir);
+  const baked = [];
+  for (const glb of models) {
+    if (!isStale(glb)) continue;
+    log(`model ${basename(glb)} changed — re-baking so the server hits the surface you see…`);
+    await bakeModel(glb, { dir, log });
+    baked.push(glb);
+  }
+  return { models, baked };
+}

package/lib/primitives.mjs

@@ -127,8 +127,19 @@ export function scanPrimitives(projectDir) {
 // other. (They used to disagree: publish looked for `_local/primitives/index.js`
 // while dev looked for a `partykit.json` that nothing ever created, so a
 // creator's primitive ran in production and silently did not run in dev.)
+//
+// TWO trees make a game server-backed: vendored primitives (overrides/) and
+// entity components (components/, or entity-local ones under entities/). The
+// entity half is a cheap folder check, not a scan — a malformed component
+// still makes the game server-backed; the build is where it fails loudly.
 export function isServerBacked(projectDir) {
-  return scanPrimitives(projectDir).length > 0;
+  if (scanPrimitives(projectDir).length > 0) return true;
+  if (existsSync(join(projectDir, 'components'))) return true;
+  const entitiesDir = join(projectDir, 'entities');
+  if (!existsSync(entitiesDir)) return false;
+  return readdirSync(entitiesDir).some((name) => {
+    try { return existsSync(join(entitiesDir, name, 'components')); } catch { return false; }
+  });
 }
 
 // The one cycle shadowing makes possible, caught in the creator's own words.

package/lib/publish.mjs

@@ -18,6 +18,7 @@ import { ensureEngine } from './engine.mjs';
 import { getToken, getApiBase } from './config.mjs';
 import { DEFAULT_API_BASE } from './llm-shim.mjs';
 import { bundlePrimitives } from './bundle-primitives.mjs';
+import { scanEntityComponents } from './room-server.mjs';
 import {
   BROWSER_REGISTRY,
   SERVER_BARREL,
@@ -67,6 +68,14 @@ export async function publish({
 } = {}) {
   const project = findProject(cwd);
 
+  // Published rooms must hit the surface players see: re-bake any referenced
+  // model whose GLB or bake config changed before the game ships. Fails the
+  // publish, loudly, rather than deploying a room that shoots at an old shape.
+  {
+    const { ensureBaked } = await import('./model-bake.mjs');
+    await ensureBaked({ dir: project.dir, log });
+  }
+
   // A publish is GLOBAL, PERMANENT and IRREVERSIBLE — the first one claims the
   // name for this account forever. A lane is a throwaway experiment in a folder
   // named after it, and the slug defaults to the folder name, so a bare publish
@@ -119,13 +128,22 @@ export async function publish({
   // are killing is an override that uploads, serves, and silently never runs.
   assertNoInertOverride({ projectDir: project.dir, engine });
   const serverPrimitives = scanPrimitives(project.dir); // throws on a reserved index.js
-  if (serverPrimitives.length) {
-    const { source, externals } = await bundlePrimitives(project.dir);
+  const entityComponents = await scanEntityComponents(project.dir, engine.sharedDir); // throws on a malformed component
+  if (serverPrimitives.length || entityComponents.length) {
+    const { source, externals } = await bundlePrimitives(project.dir, { engineSharedDir: engine.sharedDir });
     files.set(SERVER_BARREL, Buffer.from(source, 'utf8'));
-    files.set(BROWSER_REGISTRY, Buffer.from(renderBrowserRegistry(serverPrimitives), 'utf8'));
-    const names = serverPrimitives.map((p) => p.type).join(', ');
+    // The browser prediction registry exists for PRIMITIVES only — entity
+    // components' client/shared files ship as ordinary game files, and the
+    // client imports its own manifests directly.
+    if (serverPrimitives.length) {
+      files.set(BROWSER_REGISTRY, Buffer.from(renderBrowserRegistry(serverPrimitives), 'utf8'));
+    }
+    const names = [
+      ...serverPrimitives.map((p) => p.type),
+      ...entityComponents.map((c) => `${c.name} (component)`),
+    ].join(', ');
     log(
-      `Bundled server primitives — ${names} (${(source.length / 1024).toFixed(0)} KB, engine external${externals.length ? `: ${[...new Set(externals)].length} module(s)` : ''}).`,
+      `Bundled server code — ${names} (${(source.length / 1024).toFixed(0)} KB, engine external${externals.length ? `: ${[...new Set(externals)].length} module(s)` : ''}).`,
     );
   }
 

package/lib/room-server.mjs

@@ -23,8 +23,9 @@
 // imports EXTERNAL and rewrites them to the release's pre-bundled
 // `rooms-runtime.js`, because the publish endpoint is a Worker with no bundler.
 // Same seam, two deliveries.)
-import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import {
   assertNoOverrideCycle,
   isServerBacked,
@@ -65,17 +66,76 @@ function engineAliasPlugin(sharedDir) {
   };
 }
 
+// Entity components take the same trip as vendored primitives: scanned from
+// the game tree, bundled, handed to the host — through the sibling
+// `extraEntityComponents()` seam. The room bundle carries each component's
+// MANIFEST (so channel gates are trusted — a world spec arrives from a
+// client and may not define them) and its SIM entry: `server/sim.js` when
+// the component has one, else `shared/sim.js` (predicted sims live in
+// shared/ so the browser can run them too; server/ is for genuinely
+// server-only adjudication and may import shared/ itself).
+//
+// The scan implementation lives in the ENGINE (shared/ui/room/entity/) at
+// the same relative path in the repo and the built artifact. An engine too
+// old to carry it means no entity components exist for that game — skip.
+export async function scanEntityComponents(projectDir, sharedDir) {
+  const scanPath = join(sharedDir, 'ui', 'room', 'entity', 'scan.js');
+  if (!existsSync(scanPath)) return [];
+  const { scanGame } = await import(pathToFileURL(scanPath).href);
+  const { components, errors } = scanGame(projectDir);
+  if (errors.length) {
+    throw new Error(`this game's entity components cannot build a room server:\n  - ${errors.join('\n  - ')}`);
+  }
+  const posix = (p) => relative(projectDir, p).split('\\').join('/');
+  return [...components.values()].map((c) => {
+    const serverSim = join(c.dir, 'server', 'sim.js');
+    const sharedSim = join(c.dir, 'shared', 'sim.js');
+    const code = existsSync(serverSim) ? serverSim : existsSync(sharedSim) ? sharedSim : null;
+    return {
+      name: c.name,
+      manifestRel: posix(c.manifestPath),
+      codeRel: code ? posix(code) : null,
+    };
+  });
+}
+
+export function renderEntityComponents(components) {
+  if (!components.length) return 'export const extraEntityComponents = null;';
+  const lines = [];
+  const manifests = [];
+  const code = [];
+  components.forEach((c, i) => {
+    lines.push(`import entityManifest${i} from './${c.manifestRel}';`);
+    manifests.push(`entityManifest${i}`);
+    if (c.codeRel) {
+      lines.push(`import * as entityCode${i} from './${c.codeRel}';`);
+      code.push(`    '${c.name}': entityCode${i},`);
+    }
+  });
+  return [
+    ...lines,
+    'export const extraEntityComponents = {',
+    `  manifests: [${manifests.join(', ')}],`,
+    '  code: {',
+    ...code,
+    '  },',
+    '};',
+  ].join('\n');
+}
+
 // The room the game actually gets: the engine's room class, subclassed to hand
 // the host the creator's primitives through the `extraPrimitives()` seam the
 // engine already reads (server.js). Identical in shape to what the publish
 // endpoint generates for the per-game Worker — one contract, two builders.
-function renderEntry(primitives) {
+function renderEntry(primitives, entityComponents) {
   return [
     renderBarrel(primitives),
+    renderEntityComponents(entityComponents),
     "import LooopRoom from '/shared/ui/room/server.js';",
     '',
     'export default class GameRoom extends LooopRoom {',
     '  extraPrimitives() { return extraPrimitives; }',
+    '  extraEntityComponents() { return extraEntityComponents; }',
     '}',
     '',
   ].join('\n');
@@ -88,7 +148,8 @@ function renderEntry(primitives) {
 // dev must not quietly serve a room that is missing the creator's code.
 export async function buildDevRoomServer({ projectDir, engine, esbuildImpl }) {
   const primitives = scanPrimitives(projectDir); // throws on a reserved index.js
-  if (!primitives.length) {
+  const entityComponents = await scanEntityComponents(projectDir, engine.sharedDir); // throws on a malformed component
+  if (!primitives.length && !entityComponents.length) {
     // Not server-backed (any more). A PREVIOUS run may have generated a room
     // server and a registry shadow; both must go, or dev keeps mounting a stale
     // `.looop/overrides/shared/.../index.js` that imports a primitive the creator
@@ -109,7 +170,7 @@ export async function buildDevRoomServer({ projectDir, engine, esbuildImpl }) {
     // against the game root, so `./overrides/...` means what it says and no
     // machine-specific absolute path can leak into the output.
     stdin: {
-      contents: renderEntry(primitives),
+      contents: renderEntry(primitives, entityComponents),
       resolveDir: projectDir,
       sourcefile: 'looop-room-server.js',
       loader: 'js',
@@ -156,9 +217,15 @@ export async function buildDevRoomServer({ projectDir, engine, esbuildImpl }) {
   // same in dev (static mount fall-through) and in production (the import map):
   //   /shared/ui/room/primitives/engine.js  → not shadowed → the engine's list
   //   /shared/ui/room/primitives/beacon.js  → shadowed     → the game's primitive
-  const registryDir = join(projectDir, DEV_OVERRIDES_DIR, 'ui/room/primitives');
-  mkdirSync(registryDir, { recursive: true });
-  writeFileSync(join(registryDir, 'index.js'), renderBrowserRegistry(primitives));
+  if (primitives.length) {
+    const registryDir = join(projectDir, DEV_OVERRIDES_DIR, 'ui/room/primitives');
+    mkdirSync(registryDir, { recursive: true });
+    writeFileSync(join(registryDir, 'index.js'), renderBrowserRegistry(primitives));
+  } else {
+    // Entity components alone need no primitive-registry shadow — and a stale
+    // one from a removed primitive must not stay mounted.
+    rmSync(join(projectDir, DEV_OVERRIDES_DIR), { recursive: true, force: true });
+  }
 
   return outDir;
 }

package/lib/test-cmd.mjs

@@ -63,6 +63,14 @@ const SMOKE_PRELOAD = new URL('./smoke-gpu-preload.mjs', import.meta.url).href;
 
 export async function testCmd({ cwd = process.cwd(), log = console.log, devFn = dev, lintFn = lintCmd, runFn = run, patterns = [] } = {}) {
   const project = findProject(cwd);
+
+  // Freshness gate: referenced 3D models re-bake if their GLB or bake config
+  // changed, BEFORE anything runs — a stale artifact means every hit test in
+  // the suite exercises a surface the player no longer sees. A bake failure
+  // fails the gate with the model named.
+  const { ensureBaked } = await import('./model-bake.mjs');
+  await ensureBaked({ dir: project.dir, log });
+
   const all = discoverTestFiles(project.dir);
 
   // Scoped run (`looop test <pattern>…`): keep only files whose path contains a

package/package.json

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