@volter/editor-blender 0.1.143 → 0.1.144

package/contributions/blender-play-skin.ts

@@ -20,7 +20,9 @@
  * The file's own NLA strips play on the game's clock as scene frames, looping the scene's range as
  * Blender's own playback does. Every
  * clip is baked once per action, the first time it is wanted; until the clips a pose needs are
- * baked, the armature keeps the pose it has.
+ * baked, the armature keeps the pose it has. The clips each character STARTS on are baked before
+ * the game starts (`prepare`), and a bake that could not be read is tried again, so a slow or
+ * failed read at Play's start does not leave a character frozen for the run.
  *
  * THE GAME'S CLOCK DRIVES IT: the runner advances it by each update's `dt`
  * (`@volter/play`'s `play-script.ts`), so pause, step, speed and Restart hold for
@@ -74,6 +76,22 @@ export interface PlayAnimation {
   track(object: THREE.Object3D, name: string, options: PlayTrackOptions | null): Answer;
   constraint(object: THREE.Object3D, bone: string, name: string, options: PlayConstraintOptions): Answer;
   update(dt: number): void;
+  /**
+   * THE LOADING PHASE: bakes every clip a character starts on (its assigned action and its NLA
+   * strips' actions) before the game's first update, so no character stands frozen while Blender
+   * answers. Resolves with what could not be loaded; clips the game asks for later still bake on
+   * first use.
+   */
+  prepare(): Promise<{ readonly failed: readonly string[] }>;
+  /** The starting clips `prepare` is still waiting on Blender for, as `armature / action`. */
+  pending(): readonly string[];
+  /**
+   * THE CLIP LIBRARY, read in the background once the game runs: every action on each armature's
+   * NLA strips, muted tracks included (a game's clip library), most-shared first, one read at a
+   * time and only while no other read is waiting, so a clip the game asks for waits behind at most
+   * one. Without it the first switch to a library clip stood the character still for a read.
+   */
+  prefetch(): void;
   /** What each character is playing now, bottom layer first: the animation editors' live view. */
   live(): readonly LiveArmature[];
   /** The frames an action keys, per bone, for one armature (empty until it was baked). */
@@ -124,7 +142,10 @@ interface Armature {
 }
 
 /** The copy's animation. `bake` reads one action of one armature through the clip door. */
-export function playAnimation(view: BlenderRuntimeView, bake: (armature: string, action: string) => Promise<BlenderActionClip | null>): PlayAnimation {
+/** Reads that outlive one Play: a document's next Play reuses them (see `shared` below). */
+export type PlayClipCache = Map<string, Promise<BlenderActionClip | null>>;
+
+export function playAnimation(view: BlenderRuntimeView, bake: (armature: string, action: string) => Promise<BlenderActionClip | null>, cache: PlayClipCache = new Map()): PlayAnimation {
   const warnings: string[] = [];
   const facts = view.animationFacts();
   const actions = Object.keys(facts.actions);
@@ -141,17 +162,90 @@ export function playAnimation(view: BlenderRuntimeView, bake: (armature: string,
     armature.failed.set(action, why);
     warnings.push(`${armature.rig.armature} / ${action}: ${why}`);
   };
+  /** Reads that failed (Blender busy, the call refused) per clip: tried again up to this many times. */
+  const READ_ATTEMPTS = 3;
+  const attempts = new Map<string, number>();
+  const baking = new Map<string, Promise<void>>();
+  /**
+   * ONE BAKE PER ACTION AND SKELETON. A bake depends on the action, the armature's bones and the
+   * action slot Blender picks for it (`rna_action_clip`), never on the armature otherwise; each
+   * read holds the Blender worker for about 1.5 s. Read per armature, fifteen enemies placed from
+   * one piece baked the same clip fifteen times, and an action the game switched one to waited
+   * behind all of them: measured on Heck Plungers, half the characters still unposed 20 s in with
+   * Blender idle. So armatures with the same bones share a read when the action has at most one
+   * object slot (`objectSlots`, from Blender): with several, which slot plays depends on the
+   * armature, and each armature reads its own.
+   */
+  // KEPT ACROSS PLAYS by the caller (`cache`): keyed by the action's REVISION too, so an action
+  // edited between Plays is read again and an unchanged one is not read twice.
+  const shared = cache;
+  /** A clip whose slot Blender picked for its armature among several: never another armature's answer. */
+  const ownSlot = (clip: BlenderActionClip | null): boolean => !!clip && (clip.objectSlots ?? 2) > 1;
+  const readClip = (armature: Armature, action: string): Promise<BlenderActionClip | null> => {
+    const name = armature.rig.armature;
+    const skeleton = armature.facts.bones.map((bone) => bone.name).sort().join('\u0001');
+    const key = `${facts.actions[action] ?? ''}\u0000${action}\u0000${skeleton}`;
+    const known = shared.get(key);
+    if (known) return known.then((clip) => (ownSlot(clip) && clip!.armature !== name ? bake(name, action) : clip));
+    const read = bake(name, action).then((clip) => {
+      if (ownSlot(clip)) shared.delete(key);
+      return clip;
+    }, (error: unknown) => {
+      shared.delete(key);
+      throw error;
+    });
+    shared.set(key, read);
+    return read;
+  };
   const clipOf = (armature: Armature, action: string): PoseClip | null | undefined => {
     if (armature.clips.has(action)) return armature.clips.get(action);
-    armature.clips.set(action, undefined);
-    void bake(armature.rig.armature, action).then((baked) => {
-      const clip = baked ? poseClip(baked) : null;
-      for (const thing of clip?.unsupported ?? []) warnings.push(`${armature.rig.armature}: ${thing} plays only in Blender, not in a game.${remedy([thing])}`);
-      if (clip) armature.clips.set(action, clip);
-      else fail(armature, action, baked?.reason ?? `it animates none of ${armature.rig.armature}'s bones`);
-    }, (error: unknown) => fail(armature, action, `it could not be read: ${error instanceof Error ? error.message : String(error)}`));
+    void bakeClip(armature, action);
     return undefined;
   };
+  const bakeClip = (armature: Armature, action: string): Promise<void> => {
+    const key = `${armature.rig.armature}\u0000${action}`;
+    const running = baking.get(key);
+    if (running) return running;
+    if (armature.clips.has(action) && armature.clips.get(action) !== undefined) return Promise.resolve();
+    armature.clips.set(action, undefined);
+    const done = readClip(armature, action).then((baked) => {
+      // A clip that cannot be posed is that clip's failure, named like the others; it never
+      // rejects the bake, so the loading phase that awaits it always settles.
+      try {
+        const clip = baked ? poseClip(baked) : null;
+        for (const thing of clip?.unsupported ?? []) warnings.push(`${armature.rig.armature}: ${thing} plays only in Blender, not in a game.${remedy([thing])}`);
+        if (clip) armature.clips.set(action, clip);
+        else fail(armature, action, baked?.reason ?? `it animates none of ${armature.rig.armature}'s bones`);
+      } catch (error) {
+        fail(armature, action, `it could not be posed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }, (error: unknown) => {
+      const tried = (attempts.get(key) ?? 0) + 1;
+      attempts.set(key, tried);
+      const why = `it could not be read: ${error instanceof Error ? error.message : String(error)}`;
+      // A READ THAT FAILED is not the clip's answer: the next pose asks again, up to READ_ATTEMPTS.
+      if (tried < READ_ATTEMPTS && !disposed) armature.clips.delete(action);
+      else fail(armature, action, why);
+    }).finally(() => baking.delete(key));
+    baking.set(key, done);
+    return done;
+  };
+
+  /**
+   * Each armature's assigned action and the strips' actions of the NLA tracks it plays (enabled as
+   * `layersOf` reads them: NLA on, under a solo only the soloed track, else the unmuted ones): the
+   * clips it starts on. A muted track's strips are a clip library, baked when the game asks.
+   */
+  const startingClips = (): { armature: Armature; action: string }[] => [...armatures.values()].flatMap((armature) => {
+    const names = new Set<string>();
+    if (armature.facts.action) names.add(armature.facts.action);
+    const animation = armature.facts.animation;
+    const solo = animation?.tracks.some((track) => track.solo) ?? false;
+    for (const track of animation && animation.useNla ? animation.tracks : [])
+      if (solo ? track.solo : !track.mute)
+        for (const strip of track.strips) if (strip.action) names.add(strip.action);
+    return [...names].filter((name) => name in facts.actions).map((action) => ({ armature, action }));
+  });
 
   for (const rig of view.skeletons.rigs()) {
     const entry = facts.armatures[rig.armature];
@@ -331,6 +425,43 @@ export function playAnimation(view: BlenderRuntimeView, bake: (armature: string,
       armature.constraints.set(key, { ...armature.constraints.get(key), ...options });
       return ok(armature);
     },
+    async prepare() {
+      const wanted = startingClips();
+      for (let round = 0; round < READ_ATTEMPTS && !disposed; round += 1) {
+        const open = wanted.filter(({ armature, action }) => armature.clips.get(action) === undefined);
+        if (open.length === 0) break;
+        await Promise.all(open.map(({ armature, action }) => bakeClip(armature, action)));
+      }
+      const failed = wanted
+        .filter(({ armature, action }) => armature.clips.get(action) == null && armature.failed.has(action) && !/animates none/.test(armature.failed.get(action) ?? ''))
+        .map(({ armature, action }) => `${armature.rig.armature} / ${action}: ${armature.failed.get(action)}`);
+      return { failed };
+    },
+    prefetch() {
+      const users = new Map<string, Armature[]>();
+      for (const armature of armatures.values()) {
+        const names = new Set<string>();
+        if (armature.facts.action) names.add(armature.facts.action);
+        for (const track of armature.facts.animation?.tracks ?? [])
+          for (const strip of track.strips) if (strip.action) names.add(strip.action);
+        for (const action of names) if (action in facts.actions) users.set(action, [...(users.get(action) ?? []), armature]);
+      }
+      const queue = [...users].sort((a, b) => b[1].length - a[1].length)
+        .flatMap(([action, list]) => list.map((armature) => ({ armature, action })));
+      void (async () => {
+        while (!disposed) {
+          if (baking.size > 0) { await Promise.allSettled([...baking.values()]); continue; }
+          const next = queue.find(({ armature, action }) => !armature.clips.has(action));
+          if (!next) return;
+          await bakeClip(next.armature, next.action);
+        }
+      })();
+    },
+    pending() {
+      return startingClips()
+        .filter(({ armature, action }) => armature.clips.get(action) === undefined && !armature.failed.has(action))
+        .map(({ armature, action }) => `${armature.rig.armature} / ${action}`);
+    },
     update(dt) {
       if (disposed) return;
       time += dt;

package/contributions/blender-runtime.document.tsx

@@ -77,7 +77,10 @@ import {
 import { BlenderObjectModeHeader } from './blender-header-menus';
 import { blenderOutlinerAuthoringFor, createBlenderOutlinerAuthoring } from './blender-outliner-authoring';
 import { blenderSkin } from './blender-runtime-skin';
-import { playAnimation, type PlayAnimation } from './blender-play-skin';
+import { playAnimation, type PlayAnimation, type PlayClipCache } from './blender-play-skin';
+
+/** Clip reads per model document, kept across Plays (`PlayClipCache`). */
+const playClipCaches = new Map<string, PlayClipCache>();
 import { areaSplit, subscribeAreaSplit } from '../src/area-split';
 import { noteModelDocument } from '../src/play-mode';
 import { documentPlayExtension, subscribeDocumentPlayExtensions } from '@volter/sdk/kit/document-play-extension';
@@ -912,9 +915,69 @@ function BlenderViewportArea({
       // THE COPY'S CHARACTERS ANIMATE: its view bound their skins from the copied frame, and each
       // armature plays the action the file assigns it until the game sets another
       // (`blender-play-skin.ts`). Nothing is read before the game starts.
-      void view.prepareRendered(stage.rig().drawCamera(), 'render').then(() => {
+      // A LOADING PHASE, said on screen: the game starts only once its stage is drawn and every
+      // character's starting clips are baked (`PlayAnimation.prepare`). Started before them, a
+      // character whose clip Blender had not answered yet stood frozen in its rest pose, and a
+      // clip whose read failed stayed frozen for the whole run. That is the suspected cause of
+      // "sometimes none of the animations work" (a busy Blender was measured to delay the clips).
+      // THE WAIT IS BOUNDED AND SAID: after LOADING_SAY the overlay names the clips still
+      // awaited; at LOADING_LIMIT the game starts without them and the console names them (each
+      // still plays once Blender answers). A thrown `prepare` is named too; the game always starts.
+      const loading = window.document.createElement('div');
+      loading.dataset['testid'] = 'model-play-loading';
+      loading.textContent = 'Loading…';
+      Object.assign(loading.style, {
+        position: 'absolute', inset: '0', display: 'flex', alignItems: 'center', justifyContent: 'center',
+        background: 'rgba(0, 0, 0, 0.35)', color: '#e6e6e6', font: '600 14px system-ui, sans-serif', pointerEvents: 'none',
+      });
+      layers.appendChild(loading);
+      void view.prepareRendered(stage.rig().drawCamera(), 'render').then(async () => {
         if (stopped) return;
-        animation = playAnimation(view, (armature, action) => blenderActionClip({ object: armature, action }));
+        // No session answers null: a read that failed, asked again, not a clip that animates nothing.
+        // A SETUP THAT THROWS still starts the game, without animation and said so; left
+        // outside any catch it left the loading overlay up and the script never ran.
+        let cache = playClipCaches.get(modelId);
+        if (!cache) playClipCaches.set(modelId, cache = new Map());
+        let loaded: PlayAnimation | null = null;
+        try {
+          loaded = playAnimation(view, async (armature, action) => {
+            const clip = await blenderActionClip({ object: armature, action, summary: false });
+            if (clip === null) throw new Error("Blender's session is not started");
+            return clip;
+          }, cache);
+        } catch (error) {
+          editorHost().console.error(`The game's animation could not be set up, so the game starts without it: ${error instanceof Error ? error.message : String(error)}`, 'blender-animation');
+        }
+        animation = loaded;
+        if (!loaded) {
+          loading.remove();
+          if (stopped) return;
+        }
+        if (loaded) {
+          const anim = loaded;
+          const LOADING_SAY = 3_000, LOADING_LIMIT = 20_000;
+          const clips = (names: readonly string[]): string => `${names.length} clip${names.length === 1 ? '' : 's'}`;
+          const say = window.setInterval(() => {
+            const pending = anim.pending();
+            if (pending.length > 0) loading.textContent = `Loading… waiting on Blender for ${clips(pending)}: ${pending.slice(0, 6).join(', ')}${pending.length > 6 ? ` and ${pending.length - 6} more` : ''}`;
+          }, LOADING_SAY);
+          let limit = 0;
+          const outcome = await Promise.race([
+            anim.prepare().then(({ failed }) => ({ failed, waiting: [] as readonly string[] }), (error: unknown) => ({ failed: [`the loading phase failed: ${error instanceof Error ? error.message : String(error)}`], waiting: [] as readonly string[] })),
+            new Promise<{ failed: readonly string[]; waiting: readonly string[] }>((resolve) => {
+              limit = window.setTimeout(() => resolve({ failed: [], waiting: anim.pending() }), LOADING_LIMIT);
+            }),
+          ]);
+          window.clearInterval(say);
+          window.clearTimeout(limit);
+          loading.remove();
+          if (stopped) return;
+          if (outcome.failed.length > 0)
+            editorHost().console.warn(`The game started without ${clips(outcome.failed)} it starts on: ${outcome.failed.join('; ')}`, 'blender-animation');
+          if (outcome.waiting.length > 0)
+            editorHost().console.warn(`The game started after ${LOADING_LIMIT / 1000} s still waiting on Blender for ${clips(outcome.waiting)}; each plays once Blender answers: ${outcome.waiting.join(', ')}`, 'blender-animation');
+          anim.prefetch();
+        }
         setLiveAnimation(animation);
         stopScript = documentPlayExtension('model')?.run({
           ...(animation ? { animation } : {}),
@@ -934,6 +997,7 @@ function BlenderViewportArea({
           },
         }) ?? null;
       }, error => {
+        loading.remove();
         if (stopped) return;
         const failure = `The game's stage could not be prepared for a rendered draw: ${error instanceof Error ? error.message : String(error)}`;
         editorHost().console.error(failure, 'model-play');
@@ -1061,7 +1125,7 @@ function BlenderViewportArea({
     let live = true;
     void blenderSkin.sync(view, {
       clip: (armature) => blenderActionClip({ object: armature }),
-      bake: (armature, action) => blenderActionClip({ object: armature, action }),
+      bake: (armature, action) => blenderActionClip({ object: armature, action, summary: false }),
     }).catch((thrown: unknown) => {
       if (live) editorHost().console.warn(`This file's action could not be read: ${thrown instanceof Error ? thrown.message : String(thrown)}`, 'blender-skin');
     });

package/host/blender-runtime-host.ts

@@ -676,6 +676,8 @@ export async function blenderActionClip(options?: {
   bake?: boolean;
   /** A named action baked against `object`'s armature, assigned or not. */
   action?: string;
+  /** `false` skips the Timeline's summary row, which a reader that only plays the clip never draws. */
+  summary?: boolean;
 }): Promise<BlenderActionClip | null> {
   if (!blenderSessionStarted()) return null;
   return blenderRuntime().actionClip(options);

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/editor-blender",
   "author": "Volter AI, Inc.",
   "license": "AGPL-3.0-only AND GPL-3.0-or-later",
-  "version": "0.1.143",
+  "version": "0.1.144",
   "publishConfig": {
     "access": "public"
   },
@@ -72,15 +72,15 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.32.1",
-    "@volter/blender-engine": "0.1.141",
-    "@volter/editor-threejs": "0.5.204",
+    "@volter/blender-engine": "0.1.142",
+    "@volter/editor-threejs": "0.5.205",
     "zod": "^4.3.6",
     "@fortawesome/free-solid-svg-icons": "^7.2.0"
   },
   "peerDependencies": {
-    "@volter/live": "0.5.204",
-    "@volter/project": "0.5.204",
-    "@volter/sdk": "0.5.204",
+    "@volter/live": "0.5.205",
+    "@volter/project": "0.5.205",
+    "@volter/sdk": "0.5.205",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "three": "^0.180.0",