@homie-rocks/studio 0.24.4 → 0.25.0

package/lib/asset-check.mjs

@@ -5,9 +5,14 @@
  *               glTF-Validator; triangles, materials, picture sizes, bones and bytes against its tier's budget
  *               (the game's cast.tiers decision, else the phone defaults); the pivot at the bottom centre; its height against
  *               the card's; its licence (lib/asset-manifest.mjs); whether a decision it was made under has moved on
+ *   characters  four influences a vertex (three.js reads no more), bones within the tier, its skeleton's clip library
+ *               present, and every verb the game needs (anim.clips) in it
+ *   clips       a skeleton's clip library (kind clip): at most 1 MB (3 MB hard), sampled at no more than 30 a second
  *   the game    shipped models with no record; draw calls, triangles and picture memory summed (each asset times its
  *               `placements`, instanced ones drawn once); the first-play download from the last build (gzip); a
- *               committed binary over 5 MB under games/ (it belongs in R2, never in git)
+ *               committed binary over 5 MB under games/ (it belongs in R2, never in git); skinning on a phone: the
+ *               room's players times the heaviest character's skinned vertices and bones, against SKINNING (beyond it,
+ *               far characters must pose less often: @homie-rocks/studio/animate's crowd())
  *
  * The result also goes to .studio/art/<id>/check.json, which the Studio mod's Art tab and the cards read.
  */
@@ -28,10 +33,15 @@ export const BUDGETS = Object.freeze({
   kit: { triangles: 1000, texturePx: 512, kb: 200, bones: 0, materials: 1 },
   scene: { drawCalls: 100, triangles: 150_000, textureMB: 48, firstPlayMB: 5 },
 });
+/**
+ * Skinning on a phone, every frame (judgment, from the house's 32-player rooms; the perf skill's measured gate decides):
+ * the vertices the GPU skins and the bones the CPU poses. Characters past `crowdFrom` need crowd mode.
+ */
+export const SKINNING = Object.freeze({ vertices: 60_000, bones: 1_200, crowdFrom: 12, clipKB: 1024, clipHardKB: 3072, clipRate: 30 });
 export const HARD_CAPS = Object.freeze({ triangles: { hero: 15000, npc: 6000, prop: 8000, signature: 8000, kit: 3000 }, texturePx: 2048, kb: 5120, bones: 64, materials: 2, scene: { drawCalls: 150, triangles: 250_000, textureMB: 64, firstPlayMB: 8 } });
 const BIG_FILE = 5 * 1024 * 1024;
 
-const tierOf = (a) => (BUDGETS[a.tier] ? a.tier : a.kind === 'character' ? 'hero' : a.kind === 'creature' ? 'npc' : a.kind === 'kit' || a.kind === 'environment' ? 'kit' : 'prop');
+const tierOf = (a) => (a.kind === 'clip' ? 'clip' : BUDGETS[a.tier] ? a.tier : a.kind === 'character' ? 'hero' : a.kind === 'creature' ? 'npc' : a.kind === 'kit' || a.kind === 'environment' ? 'kit' : 'prop');
 
 /** The budgets this game holds itself to: its cast.tiers decision over the phone defaults, never past a hard cap. */
 export function budgetsFor(doc) {
@@ -97,11 +107,16 @@ export async function assetsCheck(root, id, { validate = true, write = true } =
   const rows = [];
   let tris = 0; let draws = 0; let texBytes = 0;
   const seenFiles = new Set();
+  const { verbsFor } = await import('./characters.mjs');
+  const needVerbs = verbsFor(doc);
+  const libs = new Map(manifest.assets.filter((x) => x.kind === 'clip').map((x) => [x.rig?.skeleton, x]));
+  let heaviest = { vertices: 0, bones: 0, id: null };
   for (const a of manifest.assets) {
     const problems = []; const warnings = [];
     const tier = tierOf(a);
     const b = budgets[tier] ?? budgets.prop;
     const n = Math.max(1, Number(a.placements ?? 1) || 1);
+    if (a.kind === 'clip') { rows.push(await clipRow(gdir, a, tools)); continue; }
     const model = (a.files ?? []).find((f) => f.role === 'model');
     let m = null;
     if (model) {
@@ -126,6 +141,19 @@ export async function assetsCheck(root, id, { validate = true, write = true } =
           else if (m.materials > b.materials) warnings.push(`${m.materials} materials (the budget is ${b.materials}: one draw call per material)`);
           if (bytes.byteLength / 1024 > b.kb) problems.push(`${kb(bytes.byteLength)} KB (a ${tier}'s budget is ${b.kb} KB)`);
           if (m.bones > (b.bones || HARD_CAPS.bones)) problems.push(`${m.bones} bones (a ${tier}'s budget is ${b.bones || HARD_CAPS.bones})`);
+          if (m.influences > 4) problems.push(`${m.influences} joints move one vertex (JOINTS_1): three.js reads 4, so the rest are dropped and the mesh tears; export with 4 influences a vertex`);
+          if (m.skinnedVertices > heaviest.vertices) heaviest = { ...heaviest, vertices: m.skinnedVertices, id: a.id };
+          if (m.bones > heaviest.bones) heaviest.bones = m.bones;
+          if (a.rig) {
+            const lib = libs.get(a.rig.skeleton);
+            const animsFile = a.rig.anims ? join(gdir, a.rig.anims) : null;
+            if (!animsFile || !existsSync(animsFile)) problems.push(`its clip library ${a.rig.anims ?? '(none named)'} is missing: homie-studio anim add ${id} ${a.id} --verbs ${needVerbs.join(',')}`);
+            else {
+              const have = lib?.clips?.map((c) => c.verb) ?? a.rig.verbs ?? [];
+              const lacking = needVerbs.filter((v) => !have.includes(v));
+              if (lacking.length) warnings.push(`the game's clips (anim.clips) name ${lacking.join(', ')}, which ${a.id}'s clip library has not: homie-studio anim add ${id} ${a.id} --verbs ${lacking.join(',')}`);
+            }
+          }
           if (m.pivot && !(m.pivot.bottom && m.pivot.centred)) warnings.push('its pivot is not at the bottom centre (assets optimise puts it there)');
           const want = Number(a.heightM ?? a.card?.heightM ?? 0);
           if (want > 0 && m.heightM && Math.abs(m.heightM / want - 1) > 0.1) warnings.push(`${m.heightM} m tall; its card says ${want} m`);
@@ -141,14 +169,23 @@ export async function assetsCheck(root, id, { validate = true, write = true } =
     if (a.route === 'procedural' && a.measured) { tris += (a.measured.tris ?? 0) * n; draws += a.instanced ? (a.measured.drawCalls ?? 1) : (a.measured.drawCalls ?? 1) * n; }
     rows.push({ id: a.id, kind: a.kind, tier, route: a.route, ok: problems.length === 0, problems, warnings, measured: m ? { tris: m.triangles, drawCalls: m.drawCalls, materials: m.materials, maxTexturePx: m.maxTexturePx, textureKB: kb(m.textureGpuBytes), bones: m.bones, heightM: m.heightM, kb: model ? kb(statSync(join(gdir, model.path)).size) : null } : null, budget: b, placements: n });
   }
+  // Skinning on a phone: the room's players, each the heaviest character (the worst case a room can draw).
+  let players = 8;
+  try { players = Math.max(1, Number(JSON.parse(readFileSync(join(gdir, 'game.json'), 'utf8')).players?.max ?? 8) || 8); } catch { players = 8; }
+  const skinning = heaviest.vertices ? { players, character: heaviest.id, vertices: heaviest.vertices * players, bones: heaviest.bones * players, budget: { vertices: SKINNING.vertices, bones: SKINNING.bones } } : null;
   const licence = licenceProblems(root, id, manifest, { public: publicSource(root, id) });
   const stale = doc ? staleAssets(doc, manifest) : [];
   const unrecorded = unrecordedModels(root, id, manifest);
   const bigFiles = bigCommittedFiles(root).filter((f) => f.path.startsWith(`games/${id}/`));
   const firstPlay = firstPlayBytes(root, id);
   const s = budgets.scene;
-  const totals = { assets: manifest.assets.length, triangles: tris, drawCalls: draws, textureMB: +(texBytes / 1024 / 1024).toFixed(1), firstPlayMB: firstPlay ? +(firstPlay.gzip / 1024 / 1024).toFixed(2) : null };
+  const totals = { assets: manifest.assets.length, triangles: tris, drawCalls: draws, textureMB: +(texBytes / 1024 / 1024).toFixed(1), firstPlayMB: firstPlay ? +(firstPlay.gzip / 1024 / 1024).toFixed(2) : null, skinnedVertices: skinning?.vertices ?? 0, bones: skinning?.bones ?? 0 };
   const problems = [];
+  if (skinning && (skinning.vertices > SKINNING.vertices || skinning.bones > SKINNING.bones)) {
+    const crowd = `far characters must pose less often: call crowd(characters, camera) from @homie-rocks/studio/animate every frame (and lighter characters, or fewer, for the rest)`;
+    if (players >= SKINNING.crowdFrom) problems.push(`a room of ${players} skins about ${skinning.vertices.toLocaleString('en-US')} vertices and poses ${skinning.bones.toLocaleString('en-US')} bones a frame on a phone (budget ${SKINNING.vertices.toLocaleString('en-US')} and ${SKINNING.bones.toLocaleString('en-US')}): ${crowd}`);
+    else problems.push(`a room of ${players} skins about ${skinning.vertices.toLocaleString('en-US')} vertices and poses ${skinning.bones.toLocaleString('en-US')} bones a frame (budget ${SKINNING.vertices.toLocaleString('en-US')} and ${SKINNING.bones.toLocaleString('en-US')}): a lighter character (assets optimise --triangles), or ${crowd}`);
+  }
   if (totals.drawCalls > s.drawCalls) problems.push(`about ${totals.drawCalls} draw calls in a scene (the phone budget is ${s.drawCalls}): instance repeated props (placements with instanced: true), or fewer materials`);
   if (totals.triangles > s.triangles) problems.push(`about ${totals.triangles.toLocaleString('en-US')} triangles in a scene (the phone budget is ${s.triangles.toLocaleString('en-US')})`);
   if (totals.textureMB > s.textureMB) problems.push(`${totals.textureMB} MB of picture memory (the phone budget is ${s.textureMB} MB; an iPhone page dies near 100 MB)`);
@@ -156,7 +193,7 @@ export async function assetsCheck(root, id, { validate = true, write = true } =
   for (const l of licence.filter((x) => x.level === 'refuse')) problems.push(`${l.asset}: ${l.problem}${l.fix ? ` (${l.fix})` : ''}`);
   for (const f of bigFiles) problems.push(`${f.path} is ${(f.bytes / 1024 / 1024).toFixed(1)} MB in git: big files go to the studio's R2 (homie-studio storage add, then media move), raw files to art/<slug>/raw/ (git-ignored)`);
   const ok = rows.every((r) => r.ok) && problems.length === 0;
-  const result = { ok, command: 'assets check', game: id, rows, totals, budgets: { ...s, tiers: Object.fromEntries(['hero', 'npc', 'prop', 'signature', 'kit'].map((t) => [t, budgets[t]])) }, licence, stale, unrecorded, bigFiles, firstPlay, problems, at: new Date().toISOString() };
+  const result = { ok, command: 'assets check', game: id, rows, totals, skinning, budgets: { ...s, skinning: SKINNING, tiers: Object.fromEntries(['hero', 'npc', 'prop', 'signature', 'kit'].map((t) => [t, budgets[t]])) }, licence, stale, unrecorded, bigFiles, firstPlay, problems, at: new Date().toISOString() };
   if (write) {
     const dir = join(root, '.studio', 'art', id);
     mkdirSync(dir, { recursive: true });
@@ -165,6 +202,34 @@ export async function assetsCheck(root, id, { validate = true, write = true } =
   return result;
 }
 
+/** A clip library's row: its file there and recorded, its size and sample rate against SKINNING, what it holds. */
+async function clipRow(gdir, a, tools) {
+  const problems = []; const warnings = [];
+  const f = (a.files ?? []).find((x) => x.role === 'clip');
+  let measured = null;
+  if (!f) problems.push('no clip library file recorded');
+  else if (!existsSync(join(gdir, f.path))) problems.push(`${f.path} is missing`);
+  else {
+    const bytes = readFileSync(join(gdir, f.path));
+    const safe = checkGlb(bytes, LIMITS.game);
+    if (!safe.ok) problems.push(...safe.problems.map((p) => `unsafe: ${p}`));
+    const k = Math.round(bytes.byteLength / 1024);
+    if (k > SKINNING.clipHardKB) problems.push(`${k} KB of clips (at most ${SKINNING.clipHardKB} KB): fewer verbs, or resample`);
+    else if (k > SKINNING.clipKB) warnings.push(`${k} KB of clips (the budget is ${SKINNING.clipKB} KB a skeleton)`);
+    if (f.sha256 && tools && tools.sha256(bytes) !== f.sha256) warnings.push('the file changed since it was recorded (its SHA-256 differs)');
+    if (safe.ok && tools) {
+      const ins = await tools.inspectModel(bytes, { limits: LIMITS.game }).catch(() => null);
+      const m = ins?.measured;
+      if (m) {
+        measured = { clips: m.clips.length, verbs: m.clips, kb: k, rate: m.clipRate, seconds: m.clipSeconds, keys: m.clipKeys };
+        if (m.clipRate > SKINNING.clipRate + 0.5) warnings.push(`sampled at about ${m.clipRate} keys a second (30 is plenty: homie-studio anim add bakes at 30)`);
+        if (!m.clips.length) problems.push('it holds no clips');
+      }
+    }
+  }
+  return { id: a.id, kind: 'clip', tier: 'clip', route: a.route, ok: problems.length === 0, problems, warnings, measured: measured ? { tris: 0, drawCalls: 0, materials: 0, maxTexturePx: 0, textureKB: 0, bones: 0, heightM: null, kb: measured.kb, clips: measured.clips, verbs: measured.verbs, rate: measured.rate } : null, budget: { kb: SKINNING.clipKB }, placements: 1 };
+}
+
 /** Whether a game's source is shared (game.json share.source is not false) and it is meant to be public. */
 export function publicSource(root, id) {
   try { const g = JSON.parse(readFileSync(join(root, 'games', id, 'game.json'), 'utf8')); return g.share?.source !== false; } catch { return true; }
@@ -175,13 +240,15 @@ export function checkLines(r) {
   const lines = [`${r.ok ? 'PASS' : 'NOT YET'}: ${r.game}'s ${r.totals.assets} asset${r.totals.assets === 1 ? '' : 's'} against the phone budgets`];
   for (const row of r.rows) {
     const m = row.measured;
-    lines.push(`  ${row.ok ? 'ok  ' : 'FIX '} ${row.id} (${row.kind}, ${row.tier}, ${row.route})${m ? `: ${m.tris} triangles, ${m.drawCalls} draw${m.drawCalls === 1 ? '' : 's'}, ${m.kb} KB, ${m.maxTexturePx ? `${m.maxTexturePx} px pictures` : 'no pictures'}${m.heightM ? `, ${m.heightM} m` : ''}` : ''}`);
+    if (row.kind === 'clip') { lines.push(`  ${row.ok ? 'ok  ' : 'FIX '} ${row.id} (clip library, ${row.route})${m ? `: ${m.clips} clips (${(m.verbs ?? []).join(', ')}), ${m.kb} KB, ${m.rate} keys a second` : ''}`); for (const p of row.problems) lines.push(`        ${p}`); for (const w of row.warnings) lines.push(`        note: ${w}`); continue; }
+    lines.push(`  ${row.ok ? 'ok  ' : 'FIX '} ${row.id} (${row.kind}, ${row.tier}, ${row.route})${m ? `: ${m.tris} triangles, ${m.drawCalls} draw${m.drawCalls === 1 ? '' : 's'}, ${m.kb} KB, ${m.maxTexturePx ? `${m.maxTexturePx} px pictures` : 'no pictures'}${m.heightM ? `, ${m.heightM} m` : ''}${m.bones ? `, ${m.bones} bones` : ''}` : ''}`);
     for (const p of row.problems) lines.push(`        ${p}`);
     for (const w of row.warnings) lines.push(`        note: ${w}`);
   }
   for (const u of r.unrecorded) lines.push(`  FIX  ${u}: shipped with no record (homie-studio assets add ${r.game} --file ${u} --license <kind>)`);
   const s = r.budgets;
   lines.push(`  scene: about ${r.totals.drawCalls} draw calls (budget ${s.drawCalls}), ${r.totals.triangles.toLocaleString('en-US')} triangles (${s.triangles.toLocaleString('en-US')}), ${r.totals.textureMB} MB of picture memory (${s.textureMB} MB)${r.totals.firstPlayMB !== null ? `, ${r.totals.firstPlayMB} MB first play (${s.firstPlayMB} MB)` : ', first play: build first'}`);
+  if (r.skinning) lines.push(`  skinning: a room of ${r.skinning.players} skins about ${r.skinning.vertices.toLocaleString('en-US')} vertices (budget ${r.skinning.budget.vertices.toLocaleString('en-US')}) and poses ${r.skinning.bones.toLocaleString('en-US')} bones (${r.skinning.budget.bones.toLocaleString('en-US')}) a frame on a phone; the heaviest is ${r.skinning.character}`);
   for (const l of r.licence) lines.push(`  ${l.level === 'refuse' ? 'FIX ' : 'note'} licence ${l.asset}: ${l.problem}${l.fix ? ` (${l.fix})` : ''}`);
   for (const st of r.stale) lines.push(`  stale ${st.id}: made under an older ${st.decisions.map((d) => d.id).join(', ')} (homie-studio style blast shows the cost; nothing is remade by itself)`);
   for (const p of r.problems.filter((x) => !/^[a-z0-9-]+: /.test(x))) lines.push(`  FIX  ${p}`);

package/lib/build.mjs

@@ -47,6 +47,7 @@ import { STUDIO_VERSION } from './version.mjs';
 import { licenseOf, remixRow } from '../worker/license.mjs';
 import { SERVER_LIMITS, serverOf } from '../worker/servers.mjs';
 import { chatProblems } from '../worker/chat.mjs';
+import { screenChatProblems } from '../worker/chat-page.mjs';
 import { vocabularyOf } from '../worker/brain.mjs';
 import { shopForBuild } from './shop.mjs';
 import { audienceOf } from '../worker/shop-rules.mjs';
@@ -323,6 +324,8 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
     if (chatBad.length) throw new Error(`games/${g.id}/game.json: ${chatBad.join('; ')}`);
     // A game's own decisions (NETPLAY.md section 20): game.json "decide" is true or false (the Worker answers net.decide only then).
     if (g.decide !== undefined && typeof g.decide !== 'boolean') throw new Error(`games/${g.id}/game.json: "decide" is true (the host may ask the studio's decision model, within the AI brains' day) or false`);
+    // Where chat sits on the screen (game.json "screen": { "chat" }, 0.24.5): a wrong field is the default on the page.
+    for (const p of screenChatProblems(g.screen?.chat)) log(`warning: games/${g.id}/game.json: ${p}; the play page uses the default there`);
     // The game's own source, for other studios to remix (game.json "share": { "source": false } keeps it private).
     if (g.share?.source !== false) writeFileSync(join(out, 'source.json'), `${JSON.stringify(sourceOf(g.dir, g.id, { studio: studio.name ?? null, game: g.name ?? g.id, license: g.license }))}\n`);
     // Its assets' licences, and the address and SHA-256 of each one a remix may carry (`game remix` fetches them).

package/lib/characters.mjs

@@ -0,0 +1,380 @@
+/**
+ * CHARACTERS AND THEIR CLIPS IN A GAME (free, on this computer): a rigged character comes in from the starter library,
+ * the person's files or a provider, and leaves as two files a phone can afford:
+ *
+ *   public/models/<asset>.glb       the character: its joints renamed to the skeleton standard (lib/rig.mjs), helper
+ *                                   bones that move nothing removed, every part and every held thing it keeps merged
+ *                                   into one skinned mesh (one draw call), phone-sized, no clips
+ *   public/anims/<skeleton>.glb     the clip library of its skeleton: one clip per verb the game uses (idle, run, jump,
+ *                                   attack, hit, die, ...), its own where it has them, else RETARGETED from a source
+ *                                   (KayKit's CC0 humanoid clips by default) at build time; every character with that
+ *                                   skeleton shares it
+ *
+ * Both are recorded in assets/manifest.json (the character, kind character or creature; the library, kind clip) with
+ * where every clip came from and its licence, so RIGHTS.md, the remix carry-over and `assets check` see them. The model
+ * names its clip library in its scene's extras (homie.anims), so the game's `loadCharacter(models, url)` finds it.
+ *
+ *   addCharacter(root, game, { item | file, ... })   in, optimised, clips baked, recorded
+ *   bakeClips(root, game, asset, { verbs, from })     more verbs for a character's skeleton (retargeted from a source)
+ *   animPlan(root, game)                              each character: its skeleton, its clips against the verbs the game
+ *                                                     needs (anim.clips), what is missing and where it would come from
+ *   animPreview(root, game, { asset, verbs })         looping previews: each verb as a small animated WebP, and a sheet
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { LIMITS, checkGlb } from '../assets/safety.mjs';
+import { readManifest, recordAsset } from './asset-manifest.mjs';
+import { VERBS, VERB_IDS, bakeLibrary, findClip, rigOf, writeLibrary } from './clips.mjs';
+import { readDecisions } from './decisions.mjs';
+import { FAMILIES, normaliseRig, skeletonOf, socketBone } from './rig.mjs';
+import { GAME_ID } from './studio.mjs';
+
+/** Where humanoid clips come from when a character has none of its own: KayKit's adventurers (CC0, 76 clips). */
+export const CLIP_SOURCES = Object.freeze({
+  humanoid: 'kaykit-adventurers/knight',
+  mini: 'kaykit-adventurers/knight',
+});
+const sha256 = (b) => createHash('sha256').update(b).digest('hex');
+const kb = (n) => Math.round(n / 1024);
+
+/** The game's verbs: its anim.clips decision (words mapped to VERBS), always idle, plus any asked for. */
+export function verbsFor(doc, extra = []) {
+  const want = [...(doc?.decisions?.['anim.clips']?.value ?? ['idle', 'run', 'jump', 'attack', 'hit']), ...extra];
+  const alias = { 'pick-up': 'pickup', pick: 'pickup', kick: 'attack2', aim: 'shoot', boost: 'run', crash: 'hit', walk: 'walk', swing: 'attack', punch: 'attack', bump: 'attack', cheer: 'emote', wave: 'emote', dance: 'emote', victory: 'win' };
+  const out = new Set(['idle']);
+  for (const w of want) { const v = alias[w] ?? w; if (VERB_IDS.includes(v)) out.add(v); }
+  return [...out];
+}
+
+/** The model tools, once. */
+async function tools() { const { modelTools } = await import('./optimise.mjs'); return modelTools(); }
+
+/** A Document from bytes (or a path resolving its sibling pictures). */
+async function docOf(input) {
+  const t = await tools();
+  const { selfContained } = await import('./optimise.mjs');
+  const bytes = await selfContained(input, LIMITS.import);
+  const safe = checkGlb(bytes, LIMITS.import);
+  if (!safe.ok) throw new Error(`refused: ${safe.problems.slice(0, 3).join('; ')}`);
+  const doc = await t.io.readBinary(bytes);
+  doc.setLogger(t.logger);
+  return { doc, bytes };
+}
+
+/** A clip source (a library item id, or a file): its Document renamed to the standard, and its clip names. */
+async function clipSource(from, { lib = null, cache = new Map() } = {}) {
+  if (cache.has(from)) return cache.get(from);
+  let bytes;
+  if (existsSync(resolve(String(from)))) bytes = readFileSync(resolve(String(from)));
+  else {
+    const { fetchItemFile, libraryBase, loadIndex } = await import('./library.mjs');
+    const L = lib ?? libraryBase();
+    const { index } = await loadIndex({ lib: L });
+    const item = index.items.find((x) => x.id === from);
+    if (!item) throw new Error(`no library item "${from}" to take clips from`);
+    if (item.license !== 'cc0') throw new Error(`${from} is not CC0`);
+    ({ bytes } = await fetchItemFile(L, item));
+  }
+  const { doc } = await docOf(bytes);
+  normaliseRig(doc, { merge: false, helpers: false, takeClips: false });
+  const src = { from: String(from), doc, rig: rigOf(doc), names: doc.getRoot().listAnimations().map((a) => a.getName()) };
+  cache.set(from, src);
+  return src;
+}
+
+/**
+ * The clips for `verbs` on `target` (a rig): the character's own where it has one, else from `fallback` (retargeted).
+ * Returns { sources: [{ rig, anim, verb, from }], missing: [verb] }.
+ */
+async function pickSources(own, verbs, fallback, opts) {
+  const sources = []; const missing = [];
+  let fb = null;
+  for (const verb of verbs) {
+    const mine = own ? findClip(own.names, verb) : null;
+    if (mine) { sources.push({ rig: own.rig, anim: own.doc.getRoot().listAnimations().find((a) => a.getName() === mine), verb, from: own.from }); continue; }
+    if (fallback && !fb) { try { fb = await clipSource(fallback, opts); } catch (error) { fb = { error: error.message }; } }
+    const theirs = fb && !fb.error ? findClip(fb.names, verb) : null;
+    if (theirs) sources.push({ rig: fb.rig, anim: fb.doc.getRoot().listAnimations().find((a) => a.getName() === theirs), verb, from: fb.from });
+    else missing.push(verb);
+  }
+  return { sources, missing, fallbackError: fb?.error ?? null };
+}
+
+/** A clip library file's path in a game, for a skeleton. */
+export const animsPath = (skeleton) => `public/anims/${skeleton}.glb`;
+
+/** Read a clip library already in the game (its verbs), or null. */
+async function existingLibrary(gdir, skeleton) {
+  const file = join(gdir, animsPath(skeleton));
+  if (!existsSync(file)) return null;
+  const t = await tools();
+  const doc = await t.io.readBinary(readFileSync(file));
+  doc.setLogger(t.logger);
+  return { doc, verbs: doc.getRoot().listAnimations().map((a) => a.getName()) };
+}
+
+/** Copy the animations of `from` (a baked library Document) into `into` (an existing one), by node name. */
+function appendClips(into, from) {
+  const root = into.getRoot();
+  const buffer = root.listBuffers()[0] ?? into.createBuffer();
+  const nodes = new Map(root.listNodes().map((n) => [n.getName(), n]));
+  for (const a of from.getRoot().listAnimations()) {
+    for (const old of root.listAnimations().filter((x) => x.getName() === a.getName())) old.dispose();
+    const b = into.createAnimation(a.getName()).setExtras(a.getExtras());
+    for (const ch of a.listChannels()) {
+      const node = nodes.get(ch.getTargetNode()?.getName());
+      if (!node) continue;
+      const s = ch.getSampler();
+      const sampler = into.createAnimationSampler()
+        .setInput(into.createAccessor().setType('SCALAR').setArray(s.getInput().getArray().slice()).setBuffer(buffer))
+        .setOutput(into.createAccessor().setType(s.getOutput().getType()).setArray(s.getOutput().getArray().slice()).setBuffer(buffer))
+        .setInterpolation(s.getInterpolation());
+      b.addSampler(sampler).addChannel(into.createAnimationChannel().setTargetNode(node).setTargetPath(ch.getTargetPath()).setSampler(sampler));
+    }
+  }
+  const ex = root.getExtras()?.homie ?? {};
+  root.setExtras({ homie: { ...ex, verbs: root.listAnimations().map((x) => x.getName()) } });
+}
+
+/**
+ * Bake (or extend) a skeleton's clip library in a game and record it. `rig`: the normalised character's rig;
+ * `own`: its own clips (a clip source) or null. Returns { path, skeleton, verbs, clips, missing, bytes, entry }.
+ */
+async function bakeFor(root, game, rig, own, verbs, { from = null, lib = null, cache = new Map(), license = null } = {}) {
+  const gdir = join(root, 'games', game);
+  const skel = rig.skeleton;
+  const fallback = from ?? CLIP_SOURCES[skel.family] ?? null;
+  const existing = await existingLibrary(gdir, skel.id);
+  const todo = verbs.filter((v) => !existing?.verbs.includes(v));
+  const { sources, missing, fallbackError } = await pickSources(own, todo, fallback, { lib, cache });
+  const t = await tools();
+  const rel = animsPath(skel.id);
+  const manifest = readManifest(root, game);
+  const entryId = `anims-${skel.id}`.slice(0, 48);
+  const prev = manifest.assets.find((a) => a.id === entryId);
+  let doc; let clips;
+  if (sources.length || !existing) {
+    ({ doc, clips } = await bakeLibrary(rig, sources, { core: t.core, logger: t.logger }));
+    if (existing) { appendClips(existing.doc, doc); doc = existing.doc; }
+  } else { doc = existing.doc; clips = []; }
+  if (!sources.length && existing) return { path: rel, skeleton: skel.id, verbs: existing.verbs, clips: prev?.clips ?? [], missing, bytes: null, entry: prev ?? null, fallbackError };
+  const out = await writeLibrary(doc, { tools: t });
+  mkdirSync(dirname(join(gdir, rel)), { recursive: true });
+  writeFileSync(join(gdir, rel), out.bytes);
+  const allClips = [...(prev?.clips ?? []).filter((c) => !clips.some((n) => n.verb === c.verb)), ...clips].sort((a, b) => VERB_IDS.indexOf(a.verb) - VERB_IDS.indexOf(b.verb));
+  const froms = [...new Set(allClips.map((c) => c.from).filter(Boolean))];
+  // Clips taken from CC0 sources (KayKit, Kenney) stay CC0 when retargeted; a character's own clips carry its licence.
+  const lic = license && license.kind !== 'cc0' && allClips.some((c) => c.from && !String(c.from).includes('/')) ? license : { kind: 'cc0', spdx: 'CC0-1.0', owner: null, attribution: null, remix: 'include', notes: `Clips from ${froms.join(', ') || 'the character itself'} (CC0), ${allClips.some((c) => c.retargeted) ? 'retargeted onto this skeleton at build time' : 'as they came'}.` };
+  const entry = {
+    id: entryId, kind: 'clip', tier: 'clip', route: allClips.every((c) => !c.from || String(c.from).includes('/')) ? 'library' : 'imported',
+    card: null,
+    from: froms.length ? { library: 'homie-starter', items: froms } : null,
+    files: [{ role: 'clip', path: rel, bytes: out.bytes.length, sha256: sha256(out.bytes) }],
+    rig: { family: skel.family, skeleton: skel.id, fingerprint: skel.fingerprint },
+    clips: allClips,
+    measured: { clips: out.clips, keys: out.keys, kb: kb(out.bytes.length), fps: 30, verbs: allClips.map((c) => c.verb) },
+    license: lic,
+    made: { steps: [{ what: 'clips', tool: 'lib/clips.mjs (retarget and bake)', verbs: allClips.map((c) => `${c.verb}<${c.source}${c.retargeted ? ' (retargeted)' : ''}`) }] },
+    review: { state: 'auto' },
+  };
+  const { entry: e } = recordAsset(root, game, entry);
+  return { path: rel, skeleton: skel.id, verbs: allClips.map((c) => c.verb), clips: allClips, missing, bytes: out.bytes.length, entry: e, fallbackError };
+}
+
+/**
+ * One rigged (or node-animated) character into a game. Options:
+ *   item        a starter-library item id (kaykit-adventurers/knight), or
+ *   file        a .glb on this computer, with license (own, cc0, cc-by-4.0, generated, ...)
+ *   as          the asset id; kind character (default) or creature; card ("Characters/Knight")
+ *   height      metres to scale it to (default: the game's cast.scale character height, else the item's suggestion)
+ *   keep        the held things to keep (a sword, a shield, a hat: names; part swaps); null keeps them all
+ *   verbs       verbs to bake besides the game's anim.clips
+ *   clipsFrom   where clips it lacks come from (a library item or a file); default by its skeleton family
+ *   texture     largest picture side (default 512: a character is a hundred pixels tall on a phone)
+ *   triangles   budget (default: the tier's, a hero 8,000)
+ *   route, steps, raw, concept, owner, attribution, notes: for a generated or imported file (as importModel takes)
+ * Returns { ok, asset, model, anims, skeleton, verbs, missing, before, after, merged, dropped, removedHelpers }.
+ */
+export async function addCharacter(root, game, opts = {}) {
+  if (!GAME_ID.test(String(game ?? ''))) throw new Error(`"${game}" is not a game id`);
+  const gdir = join(root, 'games', game);
+  if (!existsSync(join(gdir, 'game.json')) && !existsSync(join(gdir, 'CODEX.md'))) throw new Error(`no game "${game}"`);
+  const t = await tools();
+  const { optimiseModel, measureDoc } = await import('./optimise.mjs');
+  const decisions = readDecisions(root, game);
+  let bytes; let item = null; let idx = null; let lib = opts.lib ?? null;
+  if (opts.item) {
+    const L = await import('./library.mjs');
+    lib = lib ?? L.libraryBase();
+    idx = opts.index ?? (await L.loadIndex({ lib })).index;
+    item = idx.items.find((x) => x.id === opts.item) ?? idx.items.find((x) => x.item === opts.item);
+    if (!item) throw new Error(`no library item "${opts.item}" (assets find "<words>" --kind character lists them)`);
+    if (item.license !== 'cc0') throw new Error(`${item.id} is not CC0; the starter library holds only CC0`);
+    ({ bytes } = await L.fetchItemFile(lib, item));
+  } else if (opts.file) {
+    const { screenImport } = await import('./asset-import.mjs');
+    screenImport(resolve(root, String(opts.file)));
+    bytes = (await docOf(resolve(root, String(opts.file)))).bytes;
+  } else throw new Error('a library item or a file');
+  const id = String(opts.as ?? item?.item ?? 'character').toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48);
+  const kind = opts.kind === 'creature' || item?.kind === 'creature' ? 'creature' : 'character';
+  const cache = new Map();
+
+  // Its own clips, renamed to the standard (a separate copy: the model itself loses them).
+  const ownDoc = (await docOf(bytes)).doc;
+  const raw = skeletonOf(ownDoc);
+  if (raw.family === 'none') throw new Error(`${item?.id ?? opts.file} has no skeleton and no moving parts: add it as a prop (assets add without a rig), or rig it first (the animate guide)`);
+  normaliseRig(ownDoc, { merge: false, helpers: false, takeClips: false });
+  const own = ownDoc.getRoot().listAnimations().length ? { from: item?.id ?? 'own', doc: ownDoc, rig: rigOf(ownDoc), names: ownDoc.getRoot().listAnimations().map((a) => a.getName()) } : null;
+
+  // The character as shipped: renamed, helpers out, merged, clips out.
+  const { doc } = await docOf(bytes);
+  const rigged = normaliseRig(doc, { keep: opts.keep ?? null, takeClips: true });
+  const rig = rigOf(doc);
+  const verbs = verbsFor(decisions, opts.verbs ?? []);
+  const anims = await bakeFor(root, game, rig, own, verbs, { from: opts.clipsFrom ?? null, lib, cache, license: opts.license ? { kind: opts.license } : null });
+
+  // The model: phone-sized, its clip library named in its scene's extras.
+  const scene = doc.getRoot().getDefaultScene() ?? doc.getRoot().listScenes()[0];
+  scene.setExtras({ ...(scene.getExtras() ?? {}), homie: { kind, skeleton: rig.skeleton.id, family: rig.skeleton.family, anims: `../anims/${rig.skeleton.id}.glb`, sockets: Object.fromEntries(['rightHand', 'leftHand', 'head', 'back'].map((s) => [s, socketBone(rig.nodes.map((n) => n.name), s)]).filter(([, b]) => b)) } });
+  const normalised = await t.io.writeBinary(doc);
+  const castH = Number(decisions?.decisions?.['cast.scale']?.value?.characterHeightM ?? 0);
+  const height = Number(opts.height ?? 0) || castH || Number(item?.suggestM ?? 0) || null;
+  const tri = Number(opts.triangles ?? 0) || (kind === 'creature' ? 3000 : 8000);
+  const r = await optimiseModel(normalised, { height, triangles: tri, texture: Number(opts.texture ?? 512), rigged: true, metal: false });
+  const rel = `public/models/${id}.glb`;
+  mkdirSync(dirname(join(gdir, rel)), { recursive: true });
+  writeFileSync(join(gdir, rel), r.glb);
+  const after = r.after;
+  const files = [{ role: 'model', path: rel, bytes: r.bytes, sha256: r.sha256 }];
+  if (opts.rawPath) files.push({ role: 'raw', path: opts.rawPath, public: false });
+  if (opts.concept) files.push({ role: 'concept', path: String(opts.concept).startsWith('../') ? String(opts.concept) : `../../${String(opts.concept).replace(/^\.\//, '')}`, public: false });
+  const steps = [
+    ...(item ? [{ what: 'library', item: item.id, sha256: item.files?.[0]?.sha256 ?? null }] : []),
+    ...(opts.steps ?? []),
+    { what: 'rig', tool: 'lib/rig.mjs', family: rig.skeleton.family, skeleton: rig.skeleton.id, renamed: rigged.renamed, removedHelpers: rigged.removedHelpers.length, merged: rigged.merged, dropped: rigged.dropped },
+    { what: 'clips', anims: anims.path, verbs: anims.verbs },
+    { what: 'optimise', tool: r.tool, ops: r.ops },
+  ];
+  const license = item
+    ? { kind: 'cc0', spdx: 'CC0-1.0', owner: item.author ?? null, attribution: null, remix: 'include', notes: `From the Homie starter library (${item.pack}); the pack's own licence text: ${idx?.packs?.find((p) => p.id === item.pack)?.licenseFile ?? 'licenses/'}` }
+    : { kind: String(opts.license ?? ''), owner: opts.owner ?? (opts.license === 'generated' || opts.license === 'own' ? 'studio' : null), attribution: opts.attribution ?? null, notes: opts.notes ?? (opts.license === 'generated' ? 'Made through fal on the studio\'s own account (a concept image, then Meshy image-to-3D with its auto-rig); its clips are the starter library\'s CC0 clips retargeted onto its skeleton. fal\'s terms do not assign output ownership expressly (RIGHTS.md).' : null) };
+  const entry = {
+    id, kind, tier: kind === 'creature' ? 'npc' : 'hero', card: opts.card ?? null, route: item ? 'library' : (opts.route === 'generated' ? 'generated' : 'imported'),
+    ...(item ? { from: { library: 'homie-starter', version: idx?.version ?? 'v0', pack: item.pack, packLabel: idx?.packs?.find((p) => p.id === item.pack)?.label ?? item.pack, packUrl: idx?.packs?.find((p) => p.id === item.pack)?.url ?? null, item: item.id, author: item.author ?? null, origin: item.origin ?? null, sha256: item.files?.[0]?.sha256 ?? null, paletteSwap: Boolean(item.paletteSwap) } } : {}),
+    files,
+    rig: { family: rig.skeleton.family, skeleton: rig.skeleton.id, fingerprint: rig.skeleton.fingerprint, skinned: rig.skeleton.skinned, bones: after.bones || rig.skeleton.bones, deform: rig.skeleton.deform, influences: rig.skeleton.influences, anims: anims.path, verbs: anims.verbs, keep: rigged.kept, dropped: rigged.dropped },
+    measured: { tris: after.triangles, materials: after.materials, drawCalls: after.drawCalls, textures: after.textures.map((x) => ({ px: x.px, format: x.mimeType, gpuKB: Math.round(x.gpuBytes / 1024) })), bones: after.bones, clips: anims.verbs.length, heightM: after.heightM, box: after.box, glbKB: kb(r.bytes), animsKB: anims.bytes ? kb(anims.bytes) : null },
+    license,
+    made: { steps },
+    review: { state: 'auto' },
+  };
+  const { entry: e, pinned } = recordAsset(root, game, entry);
+  return { ok: true, command: 'assets add', game, asset: e.id, item: item?.id ?? null, route: e.route, raw: opts.rawPath ?? null, license: e.license.kind, model: rel, anims: anims.path, skeleton: rig.skeleton.id, family: rig.skeleton.family, verbs: anims.verbs, missing: anims.missing, clipsFrom: anims.clips.filter((c) => c.retargeted).map((c) => c.from).filter((v, i, a) => a.indexOf(v) === i), merged: rigged.merged, dropped: rigged.dropped, removedHelpers: rigged.removedHelpers.length, before: { tris: r.before.triangles, kb: kb(r.rawBytes), drawCalls: r.before.drawCalls }, after: { tris: after.triangles, kb: kb(r.bytes), heightM: after.heightM, drawCalls: after.drawCalls, bones: after.bones, animsKB: anims.bytes ? kb(anims.bytes) : null }, pinned, warnings: r.warnings, fallbackError: anims.fallbackError };
+}
+
+/** Whether a library item is a character with a rig or moving parts (assets add sends those here). */
+export const isAnimated = (item) => Boolean(item && (item.rigged || (item.clips ?? []).length >= 1) && ['character', 'creature'].includes(item.kind));
+
+/**
+ * More verbs for a character already in the game: baked into its skeleton's clip library, retargeted from `from`
+ * (a library item or a file; default: its family's clip source). Returns the bake's result.
+ */
+export async function bakeClips(root, game, asset, { verbs = [], from = null, lib = null } = {}) {
+  const m = readManifest(root, game);
+  const a = m.assets.find((x) => x.id === asset);
+  if (!a?.rig) throw new Error(`${asset} is not a rigged character in ${game} (assets add brings one in)`);
+  const t = await tools();
+  const model = a.files.find((f) => f.role === 'model');
+  const doc = await t.io.readBinary(readFileSync(join(root, 'games', game, model.path)));
+  doc.setLogger(t.logger);
+  const rig = rigOf(doc);
+  if (rig.skeleton.id !== a.rig.skeleton) rig.skeleton.id = a.rig.skeleton;
+  const want = verbs.filter((v) => VERB_IDS.includes(v));
+  if (!want.length) throw new Error(`which verbs? ${VERB_IDS.join(', ')}`);
+  let own = null;
+  if (a.from?.item && !from) { try { own = await clipSource(a.from.item, { lib }); } catch { own = null; } }
+  const r = await bakeFor(root, game, rig, own, want, { from, lib });
+  // The character's own record learns its verbs.
+  const fresh = readManifest(root, game);
+  const me = fresh.assets.find((x) => x.id === asset);
+  if (me?.rig) { me.rig.verbs = r.verbs; me.measured = { ...(me.measured ?? {}), clips: r.verbs.length }; const { writeManifest } = await import('./asset-manifest.mjs'); writeManifest(root, game, fresh); }
+  return { ok: true, command: 'anim add', game, asset, skeleton: r.skeleton, anims: r.path, verbs: r.verbs, added: want.filter((v) => r.verbs.includes(v)), missing: r.missing, kb: r.bytes ? kb(r.bytes) : null, why: r.fallbackError };
+}
+
+/** Each character, its skeleton and its clips against the verbs the game needs. */
+export function animPlan(root, game) {
+  const m = readManifest(root, game);
+  const doc = readDecisions(root, game);
+  const need = verbsFor(doc);
+  const libs = new Map(m.assets.filter((a) => a.kind === 'clip').map((a) => [a.rig?.skeleton, a]));
+  const rows = m.assets.filter((a) => (a.kind === 'character' || a.kind === 'creature') && a.rig).map((a) => {
+    const L = libs.get(a.rig.skeleton);
+    const have = L?.clips?.map((c) => c.verb) ?? a.rig.verbs ?? [];
+    return {
+      id: a.id, kind: a.kind, route: a.route, family: a.rig.family, familyLabel: FAMILIES[a.rig.family]?.label ?? a.rig.family, skeleton: a.rig.skeleton, bones: a.rig.bones, anims: a.rig.anims,
+      clips: need.map((v) => { const c = L?.clips?.find((x) => x.verb === v); return { verb: v, note: VERBS[v]?.note ?? '', loop: Boolean(VERBS[v]?.loop), have: have.includes(v), source: c?.source ?? null, from: c?.from ?? null, retargeted: Boolean(c?.retargeted), seconds: c?.duration ?? null }; }),
+      extra: have.filter((v) => !need.includes(v)),
+      missing: need.filter((v) => !have.includes(v)),
+      animsKB: L?.measured?.kb ?? null,
+    };
+  });
+  const unrigged = m.assets.filter((a) => (a.kind === 'character' || a.kind === 'creature') && !a.rig).map((a) => a.id);
+  const d = doc?.decisions ?? {};
+  return {
+    ok: true, command: 'anim plan', game, verbs: need, rows, unrigged,
+    decisions: Object.fromEntries(['anim.style', 'anim.clips', 'anim.source', 'anim.motion', 'anim.blend', 'anim.procedural', 'rig.skeleton', 'rig.source', 'rig.bones', 'game.feel'].map((k) => [k, d[k] ? { label: d[k].label, state: d[k].state } : null])),
+    lab: existsSync(join(root, 'games', game, 'lab.json')) ? JSON.parse(readFileSync(join(root, 'games', game, 'lab.json'), 'utf8')) : null,
+  };
+}
+
+/**
+ * Looping previews: each character's verbs as small animated WebP files (and one sheet a person can read), under the
+ * game's light, in .studio/art/<game>/anim/. Free; one headless Chrome. Returns { rows: [{ id, verbs: [{ verb, file,
+ * frames, seconds }], sheet }] }.
+ */
+export async function animPreview(root, game, { asset = null, verbs = null, size = 144, count = 12, log = () => {} } = {}) {
+  const plan = animPlan(root, game);
+  const rows = plan.rows.filter((r) => !asset || r.id === asset);
+  if (!rows.length) return { ok: false, command: 'anim preview', game, why: asset ? `${asset} is not a rigged character in ${game}` : `${game} has no rigged characters yet (assets add <game> <character item>)` };
+  const m = readManifest(root, game);
+  const gdir = join(root, 'games', game);
+  let tokens = null;
+  try { tokens = JSON.parse(readFileSync(join(gdir, 'style.json'), 'utf8')); } catch { tokens = null; }
+  tokens = tokens?.palette ? tokens : { palette: { bg: '#e9eef2', ink: '#1d2b3a', accent: '#ff8a5b', accent2: '#5cbf8a', danger: '#e2553f', good: '#45b36b', gold: '#ffd25a' } };
+  const dir = join(root, '.studio', 'art', game, 'anim');
+  mkdirSync(dir, { recursive: true });
+  const { withRenderer, modelIn, dataUrlBytes } = await import('./render3d.mjs');
+  let sharp = null;
+  try { sharp = (await import('sharp')).default; } catch { sharp = null; }
+  const out = [];
+  await withRenderer(async (r) => {
+    for (const row of rows) {
+      const a = m.assets.find((x) => x.id === row.id);
+      const model = readFileSync(join(gdir, a.files.find((f) => f.role === 'model').path));
+      const animsFile = join(gdir, row.anims);
+      if (!existsSync(animsFile)) { out.push({ id: row.id, verbs: [], why: `${row.anims} is missing` }); continue; }
+      const want = verbs ?? row.clips.filter((c) => c.have).map((c) => c.verb).concat(row.extra);
+      const res = await r.frames(modelIn(row.id, model, { anims: readFileSync(animsFile).toString('base64') }), tokens, { verbs: want, count, size, sheet: true, loops: want.filter((v) => VERBS[v]?.loop) });
+      const files = [];
+      for (const v of res.verbs) {
+        const file = join(dir, `${row.id}-${v.verb}.webp`);
+        if (sharp) {
+          const frames = v.frames.map((f) => dataUrlBytes(f).bytes);
+          // One animated WebP a verb: the frames at the clip's own pace, looping.
+          const delay = Math.max(40, Math.round((v.duration * 1000) / Math.max(1, frames.length)));
+          await sharp(frames, { join: { animated: true } }).webp({ quality: 70, loop: 0, delay: frames.map(() => delay), effort: 4 }).toFile(file);
+        } else writeFileSync(file.replace(/\.webp$/, '.png'), dataUrlBytes(v.frames[0]).bytes);
+        files.push({ verb: v.verb, file: file.slice(root.length + 1), frames: v.frames.length, seconds: v.duration });
+      }
+      let sheet = null;
+      if (res.sheet) { sheet = join(dir, `${row.id}-sheet.jpg`); writeFileSync(sheet, dataUrlBytes(res.sheet).bytes); sheet = sheet.slice(root.length + 1); }
+      out.push({ id: row.id, verbs: files, sheet, missing: res.missing });
+      log(`${row.id}: ${files.length} preview(s)`);
+    }
+  }, { log });
+  const result = { ok: true, command: 'anim preview', game, rows: out, at: new Date().toISOString() };
+  writeFileSync(join(dir, 'previews.json'), `${JSON.stringify(result, null, 2)}\n`);
+  return result;
+}