@homie-rocks/studio 0.30.2 → 0.31.0

package/assets/animate.ts

@@ -49,7 +49,9 @@ const HERO_BUDGET = { triangles: 8000, texturePx: 1024, materials: 2, bytes: 153
 export const ANIM_TUNING = Object.freeze({
   fade: { value: 0.14, min: 0, max: 0.6, step: 0.01, unit: 's', group: 'Motion', note: 'How long one clip takes to blend into the next' },
   walkSpeed: { value: 1.5, min: 0.3, max: 6, step: 0.05, unit: 'm/s', group: 'Motion', note: 'The ground speed the walk clip\'s feet move at (feet slide when this is wrong)' },
-  runSpeed: { value: 4.2, min: 1, max: 12, step: 0.05, unit: 'm/s', group: 'Motion', note: 'The ground speed the run clip\'s feet move at' },
+  // 4.2 m/s suits the starter library's chibi rigs. It is a default, NOT a reading of your rig: a clip retargeted onto
+  // a taller character covers more ground a cycle (`homie-studio anim plan` shows the speed measured on each rig).
+  runSpeed: { value: 4.2, min: 1, max: 12, step: 0.05, unit: 'm/s', group: 'Motion', note: 'The ground speed the run clip\'s feet move at (a default, not measured on your rig: anim plan shows the measured speed)' },
   runFrom: { value: 2.4, min: 0.5, max: 8, step: 0.05, unit: 'm/s', group: 'Motion', note: 'From this speed up, the walk becomes a run' },
   actSpeed: { value: 1.25, min: 0.5, max: 3, step: 0.05, group: 'Motion', note: 'How fast actions (attacks, casts) play: higher is snappier' },
   jumpStretch: { value: 0.16, min: 0, max: 0.5, step: 0.01, group: 'Motion', note: 'How tall and thin the body goes as it leaves the ground' },
@@ -64,8 +66,11 @@ export const ANIM_TUNING = Object.freeze({
 export type AnimTuning = { -readonly [K in keyof typeof ANIM_TUNING]?: number };
 
 export interface CharacterOptions {
-  /** The clip library's address (default: the one the model names, beside it in ./anims/). */
-  anims?: string | null;
+  /**
+   * The clip library's address (default: the one the model names, beside it in ./anims/); null for none; or a list of
+   * addresses when its skeleton has a supplemental library too (the base first).
+   */
+  anims?: string | string[] | null;
   /** Live numbers (lab.tunables(tuning)): any ANIM_TUNING key, read every frame. */
   tune?: AnimTuning;
   /** Bones that swing on springs (default: names with tail, ear, cape, hair, antenna). */
@@ -157,10 +162,15 @@ export async function loadCharacter(models: ModelSource, url: string, opts: Char
   const loaded = await models.load(url, { budget: HERO_BUDGET });
   const info = (loaded.scene.userData?.homie ?? {}) as { anims?: string; family?: string; sockets?: Record<string, string> };
   let clips = loaded.animations ?? [];
-  const animsUrl = opts.anims === null ? null : (opts.anims ?? (info.anims ? new URL(info.anims, new URL(url, typeof location !== 'undefined' ? location.href : 'http://localhost/')).href : null));
-  if (animsUrl) {
-    try { clips = [...(await models.load(animsUrl, { budget: { triangles: 0, bytes: 3 * 1024 * 1024 } })).animations, ...clips]; } catch (error) { if (!clips.length) console.warn(`[animate] ${url}: its clips did not load (${(error as Error).message})`); }
+  // `anims`: the clip library to use instead of the one the model names; null for none; or a LIST, for a skeleton
+  // with a supplemental library beside its own (the base first: where two hold a verb, the earlier one's clip plays).
+  const own = info.anims ? new URL(info.anims, new URL(url, typeof location !== 'undefined' ? location.href : 'http://localhost/')).href : null;
+  const animsUrls = opts.anims === null ? [] : Array.isArray(opts.anims) ? opts.anims : [opts.anims ?? own].filter((u): u is string => Boolean(u));
+  const fromLibraries: AnimationClip[] = [];
+  for (const animsUrl of animsUrls) {
+    try { for (const c of (await models.load(animsUrl, { budget: { triangles: 0, bytes: 3 * 1024 * 1024 } })).animations) if (!fromLibraries.some((x) => x.name === c.name)) fromLibraries.push(c); } catch (error) { if (!clips.length && !fromLibraries.length) console.warn(`[animate] ${url}: its clips did not load (${(error as Error).message})`); }
   }
+  clips = [...fromLibraries, ...clips];
   const model = await models.instance(url, { budget: HERO_BUDGET });
   return createCharacter(model, clips, { ...opts, family: info.family ?? null, sockets: info.sockets ?? {} });
 }

package/assets/assets.ts

@@ -18,7 +18,8 @@
  * runtime (homie.rocks's starter library is copied into the game, never hot-linked). `allowOrigins` opens one on
  * purpose.
  *
- * In development (localhost, or ?debug=1) a model over its budget says so in the console, and `stats()` (also
+ * In development (localhost, or ?debug=1) a model over its budget says so in the console (the budget is a small
+ * prop's unless the game sets its own: game.json `"assets": { "budgets": { "triangles", "bytes" } }`), and `stats()` (also
  * `window.__homieModels`) has the totals the perf skill reads: models, triangles, texture memory and refusals.
  *
  * KTX2 pictures (KHR_texture_basisu) need a transcoder (about 580 KB): pass your own KTX2Loader as `ktx2` when a
@@ -70,7 +71,7 @@ export interface LoadedModel {
 export interface ModelsOptions {
   /** Narrow or widen the file checks (LIMITS.game by default). */
   limits?: Partial<ModelLimits>;
-  /** A per-model budget for the development warnings (the prop tier by default). */
+  /** A per-model budget for the development warnings (over game.json's `assets.budgets`, over the prop tier). */
   budget?: ModelBudget;
   /** A KTX2Loader the game set up (transcoder path, renderer support): only for models with KTX2 pictures. */
   ktx2?: { load?: unknown } | null;
@@ -98,6 +99,16 @@ export interface Models {
 }
 
 const PROP_BUDGET: Required<ModelBudget> = { triangles: 1500, texturePx: 512, materials: 1, bytes: 300 * 1024 };
+/**
+ * The game's own budgets: game.json `"assets": { "budgets": { "triangles": 8000, "bytes": 1500000 } }`, which
+ * `homie-studio build` writes into the bundle as this constant (lib/build.mjs modelBudgetsOf). The defaults above are
+ * a small prop's; a 3D game whose every model is a character or a piece of level sets its own once, there, instead
+ * of reading a warning per model. Any other bundler leaves the name undefined, and the defaults stand.
+ */
+declare const __HOMIE_MODEL_BUDGETS__: ModelBudget | undefined;
+const gameBudget = (): ModelBudget => {
+  try { return typeof __HOMIE_MODEL_BUDGETS__ === 'object' && __HOMIE_MODEL_BUDGETS__ ? __HOMIE_MODEL_BUDGETS__ : {}; } catch { return {}; }
+};
 const devHost = (): boolean => {
   try { return /^(localhost|127\.0\.0\.1|\[::1\])$/.test(location.hostname) || new URLSearchParams(location.search).get('debug') === '1'; } catch { return false; }
 };
@@ -461,7 +472,7 @@ export function createModels(opts: ModelsOptions = {}): Models {
       const key = url;
       let p = cache.get(key);
       if (!p) {
-        p = loadOnce(url, { ...limits, ...(o.limits ?? {}) } as ModelLimits, { ...PROP_BUDGET, ...(opts.budget ?? {}), ...(o.budget ?? {}) });
+        p = loadOnce(url, { ...limits, ...(o.limits ?? {}) } as ModelLimits, { ...PROP_BUDGET, ...gameBudget(), ...(opts.budget ?? {}), ...(o.budget ?? {}) });
         cache.set(key, p);
         p.catch(() => cache.delete(key));
       }

package/assets/render-page.ts

@@ -35,7 +35,7 @@ interface Tokens {
   shape?: { language?: string; bevel?: number };
   proportions?: { heads?: number; heightM?: number };
 }
-interface ModelIn { id: string; glb: string; label?: string; place?: 'hero' | 'prop' | 'dressing'; scale?: number; retint?: boolean; tint?: string; pull?: number; anims?: string; pose?: string; poseAt?: number }
+interface ModelIn { id: string; glb: string; label?: string; place?: 'hero' | 'prop' | 'dressing'; scale?: number; retint?: boolean; tint?: string; pull?: number; anims?: string | string[]; pose?: string; poseAt?: number }
 
 const canvas = document.createElement('canvas');
 document.body.appendChild(canvas);
@@ -51,7 +51,15 @@ async function parse(m: ModelIn): Promise<Group> {
   const gltf = await new Promise<{ scene: Group; animations: AnimationClip[] }>((res, rej) => loader.parse(b64(m.glb), '', res as never, rej));
   gltf.scene.name = m.id;
   // A character with a clip library stands in a pose (idle, a little way in), not in its bind pose.
-  const clips = m.anims ? (await new Promise<{ animations: AnimationClip[] }>((res, rej) => loader.parse(b64(m.anims as string), '', res as never, rej))).animations : gltf.animations;
+  // One clip library, or several (its skeleton's own, then any declared supplemental): a verb's first clip is kept.
+  let clips = gltf.animations;
+  if (m.anims) {
+    clips = [];
+    for (const lib of Array.isArray(m.anims) ? m.anims : [m.anims]) {
+      const more = (await new Promise<{ animations: AnimationClip[] }>((res, rej) => loader.parse(b64(lib), '', res as never, rej))).animations;
+      for (const c of more) if (!clips.some((x) => x.name === c.name)) clips.push(c);
+    }
+  }
   gltf.scene.userData.clips = clips;
   if (clips?.length && (m.anims || m.pose)) {
     const clip = clips.find((c) => c.name === (m.pose ?? 'idle')) ?? clips.find((c) => c.name === 'idle') ?? clips[0];

package/assets/safety.mjs

@@ -87,12 +87,18 @@ export function readGlb(bytes, { maxJson = LIMITS.import.json } = {}) {
  *   { ok, problems: [plain words], warnings: [plain words], info: { bytes, triangles, vertices, meshes, nodes,
  *     materials, images, textures, animations, skins, joints, extensions: { used, required } } }
  * Never throws: a file it cannot read is `ok: false` with the reason.
+ *
+ * The JSDoc types say what the code always took: any limits (numbers, a part of them is enough), and extension names
+ * as strings. Without them a strict TypeScript caller read the frozen defaults as literal types and the empty lists
+ * as never[].
+ * @param {Uint8Array} bytes
+ * @param {Partial<Record<keyof typeof LIMITS.game, number>>} [limits]
  */
 export function checkGlb(bytes, limits = LIMITS.game) {
   const L = { ...LIMITS.game, ...limits };
   const problems = [];
   const warnings = [];
-  const info = { bytes: bytes?.byteLength ?? 0, triangles: 0, vertices: 0, meshes: 0, nodes: 0, materials: 0, images: 0, textures: 0, animations: 0, skins: 0, joints: 0, extensions: { used: [], required: [] } };
+  const info = { bytes: bytes?.byteLength ?? 0, triangles: 0, vertices: 0, meshes: 0, nodes: 0, materials: 0, images: 0, textures: 0, animations: 0, skins: 0, joints: 0, extensions: { used: /** @type {string[]} */ ([]), required: /** @type {string[]} */ ([]) } };
   if (info.bytes > L.bytes) problems.push(`the file is ${size(info.bytes)}, over the ${size(L.bytes)} a model may be here`);
   let glb;
   try { glb = readGlb(bytes, { maxJson: L.json }); } catch (error) { problems.push(error.message); return { ok: false, problems, warnings, info }; }