@volter/editor-blender 0.1.136 → 0.1.137

package/contributions/blender-runtime-skin.ts

@@ -1,5 +1,5 @@
 /**
- * THE SKIN AND THE CLIP — three.js PLAYS Blender's animation; Blender holds it
+ * THE TIMELINE'S ANIMATION — three.js PLAYS Blender's animation; Blender holds it
  * as DATA (owner rule, 2026-09-20: "we visualize with three.js, not Blender").
  *
  * ## Why this exists at all
@@ -11,11 +11,12 @@
  * times a second under every bpy reader in the session. So the skin travels in the
  * frame itself: the export door ships each Armature-deformed mesh's weights per
  * exported vertex (`bpy_web_export.cc` `write_skin`), the frame names every bone's
- * pose, and the presenter builds the `THREE.SkinnedMesh`es and their skeletons
- * (`blender-runtime-skeleton.ts`). This director only plays the assigned action on
- * those bones with an `AnimationMixer`: every scrub and every played frame costs
- * ZERO calls into Blender, and the clip is baked again exactly when the frame says
- * its action's revision moved.
+ * rest, channels, constraints and pose and each armature's NLA stack, and the presenter
+ * builds the skeletons (`blender-runtime-skeleton.ts`). This director poses EVERY armature
+ * at the scene frame with Blender's own evaluation (`blender-pose.ts`): its NLA tracks and
+ * active action, blended as Blender blends them, and its Damped Track constraints. Every scrub
+ * and every played frame costs ZERO calls into Blender; an action is baked again exactly when
+ * the frame says its revision moved.
  *
  * ## The bind pose is the EXPORT pose, and that is the whole trick
  *
@@ -27,63 +28,60 @@
  * own evaluation of the same skin over the same columns. Nothing has to move
  * Blender's frame, ever.
  *
- * ## What that costs, stated rather than implied
+ * ## The fidelity check, and what is not played
  *
- * While a clip plays, the picture is three.js's skinning of the EXPORT-FRAME
- * mesh. Anything else Blender's depsgraph would do per frame — shape keys, a
- * Displace or Cast or Cloth modifier reading the frame, a driver on geometry —
- * does NOT follow the mixer. The Timeline's status line names any such
- * modifier on the played object rather than showing a confident picture of the
- * wrong thing (`modifiersNotPlayed`). A bone whose pose is a CONSTRAINT's
- * rather than its channels' is named the same way, because the clip is derived
- * from the F-Curves alone.
+ * At Blender's own frame, standing still, the picture IS Blender's pose (the frame's), and the
+ * evaluator's answer for that frame is compared with it bone by bone (`poseDivergence`). A bone
+ * further off than a tenth of a degree is said in the console with what would explain it, so a
+ * difference between this Timeline (and a game, which uses the same evaluator) and Blender is
+ * never silent. What the evaluator does not play — a constraint other than Damped Track, a
+ * driver, non-default parenting — is named once as well. Anything Blender's depsgraph does to
+ * GEOMETRY per frame (shape keys, a Displace or Cloth modifier) does not follow the bones.
  */
 
 import type { BlenderActionClip } from '@volter/blender-engine/browser/rna';
+import type { BlenderArmature } from '@volter/blender-engine/browser/three/blender-runtime-armature';
 import type { BlenderRuntimeView } from '@volter/blender-engine/browser/three/blender-runtime-view';
-import type { StageTransportHandle } from '@volter/editor-sdk/host';
-import * as THREE from 'three';
+import { editorHost, type StageTransportHandle } from '@volter/editor-sdk/host';
 import { blenderRnaSet } from '../host/blender-runtime-host';
+import { actionLayer, ArmaturePose, nlaLayers, poseClip, poseDivergence, type PoseClip, type PoseLayer } from './blender-pose';
 
-/** Base64 → the typed array it holds. The same three lines every payload in
- *  this package decodes with (`blender-uv-geometry.ts`'s `uvBytes`); kept
- *  local because this module is in the presenter's closure and that one is in
- *  the UV view's. */
-function bytesOf(base64: string): Uint8Array {
-  const binary = atob(base64);
-  const out = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
-  return out;
+/** How the director reads the engine: the Timeline's subject (its keys, the scene's range) and
+ *  one action baked for one armature. */
+export interface SkinReader {
+  clip(armature: string): Promise<BlenderActionClip | null>;
+  bake(armature: string, action: string): Promise<BlenderActionClip | null>;
 }
-function float32Of(base64: string): Float32Array {
-  const bytes = bytesOf(base64);
-  return new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 2);
-}
-/**
- * A BLENDER ACTION'S BAKED TRACKS as three.js keyframe tracks over `bones` (by Blender's bone
- * name), addressed by bone UUID because three's track-name grammar splits on `.` and `hand.L`
- * is an ordinary bone name. A track for a bone this binding lacks is named in `warnings`.
- */
-export function clipTracks(clip: BlenderActionClip, bones: ReadonlyMap<string, THREE.Bone>, warnings: string[]): THREE.KeyframeTrack[] {
-  const tracks: THREE.KeyframeTrack[] = [];
-  const missing = new Set<string>();
-  for (const track of clip.tracks) {
-    const bone = bones.get(track.bone);
-    if (!bone) {
-      missing.add(track.bone);
-      continue;
-    }
-    const times = float32Of(track.timeBase64);
-    const values = float32Of(track.valueBase64);
-    const path = `${bone.uuid}.${track.property}`;
-    tracks.push(
-      track.property === 'quaternion'
-        ? new THREE.QuaternionKeyframeTrack(path, Array.from(times), Array.from(values))
-        : new THREE.VectorKeyframeTrack(path, Array.from(times), Array.from(values)),
-    );
+
+/** An armature's layers at a scene frame: its NLA, then its active action over them. */
+export function sceneLayers(armature: BlenderArmature, frame: number,
+  clips: (action: string) => PoseClip | null | undefined): { layers: PoseLayer[]; waiting: boolean; skipped: string[] } {
+  const stack = nlaLayers(armature.animation, frame, clips);
+  const action = armature.action ?? null;
+  if (action) {
+    const clip = clips(action);
+    if (clip === undefined) stack.waiting = true;
+    const layer = clip ? actionLayer(armature.animation, clip, frame, stack.evaluated) : null;
+    if (layer) stack.layers.push(layer);
   }
-  if (missing.size) warnings.push(`${clip.action} animates ${[...missing].join(', ')}, which this binding has no bone for.`);
-  return tracks;
+  return stack;
+}
+
+/** What to do about what plays only in Blender, by kind. */
+export function remedy(unsupported: readonly string[]): string {
+  const out: string[] = [];
+  if (unsupported.some((thing) => thing.includes(' constraint ') || thing.includes('drivers')))
+    out.push('Bake a constraint or driver into the action (Pose ▸ Animation ▸ Bake Action, Visual Keying), or aim with a Damped Track.');
+  if (unsupported.some((thing) => thing.includes('curves on ')))
+    out.push("Key the motion on a bone (the root bone) instead of the armature object, or move the object from the game.");
+  if (unsupported.some((thing) => thing.includes('interpolation') || thing.includes(' modifier')))
+    out.push('Use Bezier, Linear or Constant keys and the Cycles modifier only, or bake the curves (Key ▸ Bake Keyframes).');
+  return out.length ? ` ${out.join(' ')}` : '';
+}
+
+/** True when an armature has anything to evaluate: an action, or NLA strips. */
+export function animated(armature: BlenderArmature): boolean {
+  return !!armature.action || !!armature.animation?.tracks.some((track) => track.strips.length);
 }
 
 /**
@@ -94,15 +92,17 @@ export function clipTracks(clip: BlenderActionClip, bones: ReadonlyMap<string, T
  * copy of the playback state anywhere.
  */
 export class BlenderSkinDirector {
-  /** The presented view whose skeletons the clip plays on (`sync`). */
+  /** The presented view whose skeletons are posed (`sync`). */
   #view: BlenderRuntimeView | null = null;
-  /** The armature the clip plays on, and what the clip was read for: armature, action, the
-   *  action's revision, the scene's clock and frame. Read again only when this changes. */
+  #reader: SkinReader | null = null;
+  /** The Timeline's subject: the armature its keys and header describe, and what its header was
+   *  read for. Read again only when that changes. */
   #armature: string | null = null;
   #clipKey: string | null = null;
-  #mixer: THREE.AnimationMixer | null = null;
-  #action: THREE.AnimationAction | null = null;
   #clip: BlenderActionClip | null = null;
+  /** Each posed armature's evaluator, and every action baked for it, at the revision baked. */
+  #poses = new Map<string, ArmaturePose>();
+  #baked = new Map<string, { revision: number | null; clip: PoseClip | null | undefined }>();
   /** The frame the last SEEK asked for — see {@link frame}. */
   #seeked: number | null = null;
   /** The stage transport this skin is attached to, or null before `attachTo`.
@@ -112,6 +112,8 @@ export class BlenderSkinDirector {
   #listeners = new Set<() => void>();
   #version = 0;
   #warnings: string[] = [];
+  /** What was already said in the console, so each finding is said once. */
+  #said = new Set<string>();
   /** Engine calls this director has made, counted so a walk can prove that a
    *  scrub costs none (the acceptance the owner named). */
   #engineCalls = 0;
@@ -134,9 +136,8 @@ export class BlenderSkinDirector {
     for (const listener of [...this.#listeners]) listener();
   }
 
-  /** The clip's own facts plus the mixer's live time, expressed in BLENDER
-   *  FRAMES — which is the only number the Timeline draws, and the only one a
-   *  person or an agent ever names. */
+  /** The subject's facts plus the playhead, expressed in BLENDER FRAMES — which is the only
+   *  number the Timeline draws, and the only one a person or an agent ever names. */
   state(): {
     frame: number;
     start: number;
@@ -148,9 +149,8 @@ export class BlenderSkinDirector {
     bones: number;
     keyframes: readonly { frame: number; type: string; select: boolean }[];
     /** Every animated object's own columns plus its SELECTION — what the
-     *  summary row's `show_only_selected` filter chooses between. The mixer
-     *  never reads it: what plays is the bound action, filter or no filter,
-     *  exactly as in Blender. */
+     *  summary row's `show_only_selected` filter chooses between. What plays
+     *  is every armature's stack, filter or no filter, exactly as in Blender. */
     summary: readonly {
       object: string;
       action: string;
@@ -165,20 +165,17 @@ export class BlenderSkinDirector {
     engineCalls: number;
     /** BLENDER'S OWN `scene.frame_current`, as the clip door last read it —
      *  which is a different number from `frame` on purpose. `frame` is where
-     *  the person is looking (the mixer's); this is where bpy and the
-     *  Properties rail are. They agree after a pause or a scrub-end, and they
-     *  are deliberately allowed to differ in between. */
+     *  the person is looking; this is where bpy and the Properties rail are.
+     *  They agree after a pause or a scrub-end, and they are deliberately
+     *  allowed to differ in between. */
     blenderFrame: number | null;
   } {
     const clip = this.#clip;
-    const start = clip?.frameStart ?? 1;
-    const end = clip?.frameEnd ?? 250;
-    const fps = clip?.fps ?? 24;
     return {
       frame: this.frame(),
-      start,
-      end,
-      fps,
+      start: clip?.frameStart ?? 1,
+      end: clip?.frameEnd ?? 250,
+      fps: clip?.fps ?? 24,
       action: clip?.action ?? null,
       object: clip?.object ?? null,
       armature: clip?.armature ?? null,
@@ -188,8 +185,7 @@ export class BlenderSkinDirector {
       clipStart: clip?.clipStart ?? null,
       clipEnd: clip?.clipEnd ?? null,
       tracks: clip?.tracks.length ?? 0,
-      // The armature the clip plays on, when the presenter holds its skeleton.
-      bound: this.#armature && this.#view?.skeletons.rig(this.#armature) ? [this.#armature] : [],
+      bound: [...this.#poses.keys()],
       warnings: this.#warnings,
       engineCalls: this.#engineCalls,
       blenderFrame: clip?.frameCurrent ?? null,
@@ -202,25 +198,9 @@ export class BlenderSkinDirector {
     return this.#clip ? this.frame() : null;
   }
 
-  /** The mixer's time as a Blender frame. With no clip the scene's own current
-   *  frame stands, which is Blender's answer for a file with no animation. */
+  /** The frame on screen: the last seek's, else Blender's own. */
   frame(): number {
-    const clip = this.#clip;
-    if (this.#seeked !== null) return this.#seeked;
-    if (!clip || !this.#action || clip.clipStart === undefined) return clip?.frameCurrent ?? 1;
-    // A SEEK'S OWN ANSWER, while one is standing. `LoopRepeat` wraps
-    // `action.time` into `[0, duration)`, so a seek to the LAST frame lands on
-    // `time === duration` and reads back as the FIRST — measured on the first
-    // walk, where `jump-end` answered frame 1 over a frame-48 pose. The
-    // wrapping is right for playback and wrong for a question, so a standing
-    // seek answers with the frame it was given and the play tick clears it.
-    // THE ACTION'S TIME, NOT THE MIXER'S, and the difference is the whole of
-    // looping: `AnimationMixer.time` is monotonic and never wraps, while
-    // `AnimationAction.time` is wrapped into `[0, duration]` by `LoopRepeat`.
-    // Measured on the first walk: two seconds of playback over a 47-frame clip
-    // read as frame 63.5 off the mixer, where the picture was correctly back
-    // near the start.
-    return clip.clipStart + this.#action.time * clip.fps;
+    return this.#seeked ?? this.#clip?.frameCurrent ?? 1;
   }
 
   /** Blender's scene clock exists even when the scene has no action. */
@@ -231,14 +211,15 @@ export class BlenderSkinDirector {
   // ------------------------------------------------------------ the frame
 
   /**
-   * FOLLOW THE PRESENTED FRAME. The armature played is the active object's (itself, or the one its
-   * skin is bound to), else the one armature that has an action. Its assigned action is read
-   * through the clip door when the frame says something about it moved: another armature or
-   * action, the action's revision, the scene's clock, or Blender's own frame. Otherwise this costs
-   * nothing, which is what lets the model call it after every present.
+   * FOLLOW THE PRESENTED FRAME. Every armature the frame names is posed; the Timeline's subject is
+   * the active object's armature (itself, or the one its skin is bound to), else the one armature
+   * that has an action, and its header is read through the clip door when the frame says
+   * something about it moved. Actions are baked once per revision, the first time a frame needs
+   * them. Otherwise this costs nothing, which is what lets the model call it after every present.
    */
-  async sync(view: BlenderRuntimeView, read: { clip(armature: string): Promise<BlenderActionClip | null> }): Promise<void> {
+  async sync(view: BlenderRuntimeView, read: SkinReader): Promise<void> {
     this.#view = view;
+    this.#reader = read;
     const facts = view.animationFacts();
     const names = Object.keys(facts.armatures);
     const active = facts.active;
@@ -246,79 +227,138 @@ export class BlenderSkinDirector {
       : (active ? facts.skinArmature(active) : null)
         ?? (names.filter((name) => facts.armatures[name]!.action).length === 1
           ? names.find((name) => facts.armatures[name]!.action)! : null);
-    const action = armature ? facts.armatures[armature]?.action ?? null : null;
-    const key = JSON.stringify([armature, action, action ? facts.actions[action] ?? null : null, facts.clock, facts.frame,
-      armature ? view.skeletons.rig(armature) !== null : false]);
-    if (key === this.#clipKey && (!armature || this.#rig() === view.skeletons.rig(armature))) return;
-    this.#clipKey = key;
-    if (this.#armature && this.#armature !== armature) view.skeletons.restorePose(this.#armature);
-    this.#armature = armature;
-    this.#boundRig = armature ? view.skeletons.rig(armature) : null;
-    const warnings: string[] = [];
-    let clip: BlenderActionClip | null = null;
-    if (armature) {
-      this.#engineCalls++;
-      clip = await read.clip(armature);
+    // EVERY ARMATURE'S EVALUATOR, over the rig the presenter holds for it now.
+    for (const [name, pose] of [...this.#poses])
+      if (!facts.armatures[name] || view.skeletons.rig(name) !== pose.rig) this.#poses.delete(name);
+    for (const [name, entry] of Object.entries(facts.armatures)) {
+      const rig = view.skeletons.rig(name);
+      if (!rig || !animated(entry)) {
+        this.#poses.delete(name);
+        continue;
+      }
+      let pose = this.#poses.get(name);
+      if (!pose) this.#poses.set(name, pose = new ArmaturePose(rig));
+      pose.facts(entry);
+    }
+    // A BAKE IS GOOD FOR ITS ACTION'S REVISION; a new revision bakes it again when next needed.
+    for (const [key, entry] of [...this.#baked]) {
+      const action = key.slice(key.indexOf('\u0000') + 1);
+      if ((facts.actions[action] ?? null) !== entry.revision) this.#baked.delete(key);
     }
-    const previous = this.#clip;
-    const rangeChanged = clip?.frameStart !== previous?.frameStart ||
-      clip?.frameEnd !== previous?.frameEnd || clip?.fps !== previous?.fps;
-    this.#clip = clip ?? null;
-    if (!clip || clip.scene !== previous?.scene) this.#seeked = null;
-    if (clip?.reason) warnings.push(clip.reason);
-    if (clip) this.#loadClip(clip, warnings);
-    else {
-      this.#mixer?.stopAllAction();
-      this.#mixer = null;
-      this.#action = null;
+    const action = armature ? facts.armatures[armature]?.action ?? null : null;
+    const key = JSON.stringify([armature, action, action ? facts.actions[action] ?? null : null, facts.clock, facts.frame]);
+    if (key !== this.#clipKey) {
+      this.#clipKey = key;
+      this.#armature = armature;
+      let clip: BlenderActionClip | null = null;
+      if (armature) {
+        this.#engineCalls++;
+        clip = await read.clip(armature);
+        if (clip?.action && clip.armature) this.#baked.set(`${clip.armature}\u0000${clip.action}`, { revision: facts.actions[clip.action] ?? null, clip: poseClip(clip) });
+      }
+      const previous = this.#clip;
+      const rangeChanged = clip?.frameStart !== previous?.frameStart ||
+        clip?.frameEnd !== previous?.frameEnd || clip?.fps !== previous?.fps;
+      this.#clip = clip ?? null;
+      if (!clip || clip.scene !== previous?.scene) this.#seeked = null;
+      const activeSubject = this.#transport?.snapshot().activeSubject;
+      if (rangeChanged && activeSubject) this.#transport?.setActiveSubject(activeSubject);
+      const playing = this.#transport?.snapshot().playbackState === 'playing';
+      if (clip && !playing) {
+        this.#seeked = null;
+        if (this.#transport && clip.fps > 0) this.#transport.seek(clip.frameCurrent / clip.fps);
+      }
     }
-    const activeSubject = this.#transport?.snapshot().activeSubject;
-    if (rangeChanged && activeSubject) this.#transport?.setActiveSubject(activeSubject);
+    this.#pose();
+    this.#publish();
+  }
+
+  /** One action of one armature: baked, or being baked now (once), or null when it plays nothing. */
+  #clipOf(armature: string, action: string): PoseClip | null | undefined {
+    const key = `${armature}\u0000${action}`;
+    const held = this.#baked.get(key);
+    if (held) return held.clip;
+    const reader = this.#reader;
+    const revision = this.#view?.animationFacts().actions[action] ?? null;
+    if (!reader) return null;
+    const entry: { revision: number | null; clip: PoseClip | null | undefined } = { revision, clip: undefined };
+    this.#baked.set(key, entry);
+    this.#engineCalls++;
+    void reader.bake(armature, action).then((baked) => {
+      entry.clip = baked ? poseClip(baked) : null;
+      if (this.#baked.get(key) !== entry) return;
+      this.#pose();
+      this.#publish();
+    }, (error: unknown) => {
+      entry.clip = null;
+      this.#say(`bake:${key}`, `${armature} / ${action} could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    return undefined;
+  }
+
+  /**
+   * POSE EVERY ARMATURE AT THE FRAME ON SCREEN. At Blender's own frame, standing still, the bones
+   * take Blender's pose (the frame's, exact) and the evaluator's answer is checked against it;
+   * anywhere else they take the evaluator's.
+   */
+  #pose(): void {
+    const view = this.#view;
+    if (!view) return;
+    const facts = view.animationFacts();
+    const frame = this.frame();
+    // BLENDER'S OWN FRAME is the one the presented pose was evaluated at, not the bookmark: a pause
+    // writes the bookmark first and the frame evaluated there arrives after.
+    const atBlender = frame === facts.frame;
     const playing = this.#transport?.snapshot().playbackState === 'playing';
-    if (clip && !playing) {
-      this.#seek(clip.frameCurrent);
-      if (this.#transport && clip.fps > 0) this.#transport.seek(clip.frameCurrent / clip.fps);
+    const warnings: string[] = this.#clip?.reason ? [this.#clip.reason] : [];
+    const world = { object: (name: string) => view.objectForBlenderName(name) };
+    for (const [name, pose] of this.#poses) {
+      const armature = facts.armatures[name];
+      if (!armature) continue;
+      const unsupported = [...pose.unsupported(), ...this.#clipsOf(name).flatMap((clip) => clip.unsupported)];
+      if (unsupported.length) {
+        const said = `${name} plays ${unsupported.join(', ')} only in Blender, not in the Timeline or a game.${remedy(unsupported)}`;
+        warnings.push(said);
+        this.#say(`unsupported:${name}:${unsupported.join('|')}`, said);
+      }
+      const stack = sceneLayers(armature, frame, (action) => this.#clipOf(name, action));
+      for (const skipped of stack.skipped) this.#say(`skipped:${name}:${skipped}`, `${name}: ${skipped} plays only in Blender, not in the Timeline or a game.`);
+      if (stack.waiting) continue;
+      if (atBlender && !playing) {
+        view.skeletons.restorePose(name);
+        pose.rig.object.updateMatrixWorld(true);
+        this.#check(name, pose, armature, stack.layers, world, unsupported);
+      } else {
+        pose.apply(stack.layers, world);
+      }
     }
     this.#warnings = warnings;
-    this.#publish();
   }
 
-  /** The rig the clip was loaded over: a rebuilt rig (new bones) needs the clip loaded again. */
-  #boundRig: object | null = null;
-  #rig(): object | null {
-    return this.#boundRig;
+  /** The clips baked so far for one armature. */
+  #clipsOf(armature: string): PoseClip[] {
+    const out: PoseClip[] = [];
+    for (const [key, entry] of this.#baked) if (key.startsWith(`${armature}`) && entry.clip) out.push(entry.clip);
+    return out;
   }
 
-  #loadClip(clip: BlenderActionClip, warnings: string[]): void {
-    this.#mixer?.stopAllAction();
-    this.#mixer = null;
-    this.#action = null;
-    if (!clip.tracks.length || clip.clipStart === undefined || clip.clipEnd === undefined) return;
-    const rig = clip.armature ? this.#view?.skeletons.rig(clip.armature) : null;
-    if (!rig) return;
-    const armature = rig.object;
-    const byName = rig.bones;
-    const tracks = clipTracks(clip, byName, warnings);
-    if (!tracks.length) return;
-    const duration = clip.duration ?? (clip.clipEnd - clip.clipStart) / clip.fps;
-    const mixer = new THREE.AnimationMixer(armature);
-    const action = mixer.clipAction(
-      new THREE.AnimationClip(clip.action ?? 'action', duration, tracks),
-    );
-    action.setLoop(THREE.LoopRepeat, Number.POSITIVE_INFINITY);
-    action.play();
-    this.#mixer = mixer;
-    this.#action = action;
-    // THE FRESH MIXER STARTS AT BLENDER'S OWN FRAME, not at zero, and that is
-    // the invariant this whole design rests on: the mesh columns were exported
-    // at `frameCurrent` and the skeleton was bound in that pose, so seeking
-    // anywhere else would make the first picture after a re-bind disagree with
-    // the geometry underneath it. Measured on the first walk: a pause wrote
-    // frame 16, the write presented, the present re-exported the mesh at 16
-    // and re-bound — and `setTime(0)` snapped the playhead back to frame 1
-    // over a frame-16 mesh.
-    this.#seek(clip.frameCurrent);
-    this.#refresh();
+  /** THE FIDELITY CHECK at Blender's own frame: the evaluator's pose against Blender's. */
+  #check(name: string, pose: ArmaturePose, armature: BlenderArmature, layers: readonly PoseLayer[],
+    world: { object(name: string): ReturnType<BlenderRuntimeView['objectForBlenderName']> }, unsupported: readonly string[]): void {
+    const off = poseDivergence(pose.apply(layers, world, false), armature);
+    if (!off) return;
+    const frame = this.#clip?.frameCurrent ?? this.frame();
+    const why = unsupported.length
+      ? `What Blender plays here and the evaluator does not: ${unsupported.join(', ')}.`
+      : 'Nothing the evaluator knows of explains it; this is a defect in the presenter, report it with the file.';
+    this.#say(`divergence:${name}:${frame}:${off.bone}:${Math.round(off.degrees)}`,
+      `${name} at frame ${frame}: bone "${off.bone}" is ${off.degrees.toFixed(1)}° and ${(off.offset * 100).toFixed(1)}% of its length off Blender's own pose, so the Timeline and a game show it differently from Blender. ${why}`);
+  }
+
+  #say(key: string, message: string): void {
+    if (this.#said.has(key)) return;
+    this.#said.add(key);
+    editorHost().console.warn(message, 'blender-animation');
   }
 
   // ------------------------------------------------------------ the playback
@@ -326,25 +366,8 @@ export class BlenderSkinDirector {
   #seek(frame: number): void {
     const clip = this.#clip;
     if (!clip) return;
-    const clamped = Math.min(clip.frameEnd, Math.max(clip.frameStart, frame));
-    this.#seeked = clamped;
-    // An action supplies a pose at this scene time; it does not own whether
-    // the scene clock can move. Empty/static scenes still play and scrub.
-    if (!this.#mixer || clip.clipStart === undefined || clip.clipEnd === undefined) return;
-    // The TIME is nudged inside the clip so the last frame evaluates as the
-    // last frame rather than wrapping to the first; the number REPORTED is the
-    // one asked for (see `frame`).
-    const duration = (clip.clipEnd - clip.clipStart) / clip.fps;
-    this.#mixer.setTime(Math.max(0, Math.min(duration - 1e-4, (clamped - clip.clipStart) / clip.fps)));
-    this.#refresh();
-  }
-
-  /** The bones moved; make the world matrices agree before the stage's next
-   *  render reads them. A `Bone` keeps `matrixAutoUpdate`, so this is a forced
-   *  pass over a handful of nodes rather than a recomposition of the scene. */
-  #refresh(): void {
-    const rig = this.#armature ? this.#view?.skeletons.rig(this.#armature) : null;
-    rig?.object.updateMatrixWorld(true);
+    this.#seeked = Math.min(clip.frameEnd, Math.max(clip.frameStart, frame));
+    this.#pose();
   }
 
   /** The scene's name, for the one address the Timeline writes to. */
@@ -447,12 +470,11 @@ export class BlenderSkinDirector {
 
   dispose(): void {
     this.#detach?.();
-    this.#mixer?.stopAllAction();
-    this.#mixer = null;
-    this.#action = null;
     this.#clip = null;
     this.#seeked = null;
-    if (this.#armature) this.#view?.skeletons.restorePose(this.#armature);
+    for (const name of this.#poses.keys()) this.#view?.skeletons.restorePose(name);
+    this.#poses.clear();
+    this.#baked.clear();
     this.#armature = null;
     this.#clipKey = null;
   }

package/contributions/blender-runtime.document.tsx

@@ -1055,7 +1055,10 @@ function BlenderViewportArea({
   useEffect(() => {
     if (!documentId || !main) return;
     let live = true;
-    void blenderSkin.sync(view, { clip: (armature) => blenderActionClip({ object: armature }) }).catch((thrown: unknown) => {
+    void blenderSkin.sync(view, {
+      clip: (armature) => blenderActionClip({ object: armature }),
+      bake: (armature, action) => blenderActionClip({ object: armature, action }),
+    }).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');
     });
     return () => { live = false; };

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.136",
+  "version": "0.1.137",
   "publishConfig": {
     "access": "public"
   },
@@ -72,15 +72,15 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.32.1",
-    "@volter/blender-engine": "0.1.134",
-    "@volter/editor-threejs": "0.5.197",
+    "@volter/blender-engine": "0.1.135",
+    "@volter/editor-threejs": "0.5.198",
     "zod": "^4.3.6",
     "@fortawesome/free-solid-svg-icons": "^7.2.0"
   },
   "peerDependencies": {
-    "@volter/editor-live": "0.5.197",
-    "@volter/editor-project": "0.5.197",
-    "@volter/editor-sdk": "0.5.197",
+    "@volter/editor-live": "0.5.198",
+    "@volter/editor-project": "0.5.198",
+    "@volter/editor-sdk": "0.5.198",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "three": "^0.180.0",