@volter/editor-blender 0.1.133 → 0.1.135

package/contributions/blender-play-skin.ts

@@ -0,0 +1,236 @@
+/**
+ * ANIMATION IN PLAY: the same skin and clips the Timeline plays (`blender-runtime-skin.ts`), bound
+ * to Play's detached copy and driven by the game.
+ *
+ * Play runs a game on a copy of the model (`BlenderRuntimeView.detach`). Until this module the copy
+ * was built without its skins, so every rigged character was a frozen mesh in a game while the same
+ * character played in Movie. Nothing here is a second animation system: the rigs are bound by
+ * `bindRig` and the clips built by `clipTracks`, the Timeline's own code, over the copy's graph.
+ *
+ * WHAT A GAME PLAYS is any action that animates an armature's bones, assigned or not, so a file can
+ * hold a clip library (Idle, Run, Attack, Die side by side) and a game chooses among them by name.
+ * Each armature has its own `THREE.AnimationMixer`; a play crossfades from what played before.
+ *
+ * THE GAME'S CLOCK DRIVES IT: the runner advances the mixers by the `dt` each `update` is handed
+ * (`@volter/editor-model-play`'s `play-script.ts`), so pause, step, speed and Restart hold for
+ * animation exactly as they do for the script. Nothing advances on the page's own time.
+ *
+ * READ ONCE PER PLAY: the rig and every clip are read from the engine when Play starts (`rna_rig`
+ * walks every vertex of every rigged mesh, a clip bakes every bone per frame), never per frame.
+ */
+import type { BlenderActionClip, BlenderRig } from '@volter/blender-engine/browser/rna';
+import * as THREE from 'three';
+import { blenderActionClip, blenderArmatureActions, blenderRig } from '../host/blender-runtime-host';
+import { bindRig, clipTracks, type BoundRig, type SkinPresentation } from './blender-runtime-skin';
+
+/** What Play reads from the engine: the rigs, every armature's action names, and the assigned
+ *  actions baked. Any other action is baked the first time a game sets it (`bake`). */
+export interface PlayClipLibrary {
+  readonly rig: BlenderRig | null;
+  /** Armature name -> the actions that can play on it. */
+  readonly names: ReadonlyMap<string, readonly string[]>;
+  /** Armature name -> the action assigned to it in the file (`animation_data.action`), which it
+   *  plays from the start of a run, as Blender would. */
+  readonly assigned: ReadonlyMap<string, string>;
+  /** Armature name -> its baked clips by action name (the assigned ones at first). */
+  readonly clips: ReadonlyMap<string, ReadonlyMap<string, BlenderActionClip>>;
+  /** Bake one more action for an armature; null, with the reason in `warnings`, when it cannot play. */
+  bake(armature: string, action: string): Promise<BlenderActionClip | null>;
+  readonly warnings: string[];
+}
+
+/** Read the rigs and the assigned clips a game starts with. Empty when the file has no armature. */
+export async function readPlayClipLibrary(): Promise<PlayClipLibrary> {
+  const warnings: string[] = [];
+  const [rig, listing] = await Promise.all([blenderRig(), blenderArmatureActions()]);
+  const names = new Map<string, readonly string[]>();
+  const assigned = new Map<string, string>();
+  const clips = new Map<string, Map<string, BlenderActionClip>>();
+  const bake = async (armature: string, action: string): Promise<BlenderActionClip | null> => {
+    try {
+      const clip = await blenderActionClip({ object: armature, action });
+      if (clip?.reason) warnings.push(`${armature} / ${action}: ${clip.reason}`);
+      if (clip?.tracks.length && clip.clipStart !== undefined && clip.clipEnd !== undefined) return clip;
+    } catch (error) {
+      warnings.push(`${armature} / ${action} could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return null;
+  };
+  await Promise.all((listing?.armatures ?? []).map(async ({ armature, actions, current }) => {
+    names.set(armature, actions);
+    if (!current) return;
+    assigned.set(armature, current);
+    const clip = await bake(armature, current);
+    if (clip) clips.set(armature, new Map([[current, clip]]));
+  }));
+  return { rig, names, assigned, clips, bake, warnings };
+}
+
+export interface PlayAnimateOptions {
+  /** Repeat until something else plays (default true). */
+  readonly loop?: boolean;
+  /** Seconds to crossfade from what this armature played before (default 0.2). */
+  readonly fade?: number;
+  /** Playback rate, 1 is the clip's own speed. */
+  readonly speed?: number;
+  /** Start again from the first frame when this clip is already playing (default false). */
+  readonly restart?: boolean;
+}
+
+/** The game's door to its characters' clips (`ModelPlayContext.animate`). */
+export interface PlayAnimation {
+  /** The clips an object can play: its own armature's, or the armature its rigged mesh is bound to. */
+  clips(object: THREE.Object3D): readonly string[];
+  /** Play a clip on an object's armature; the reason when it cannot. */
+  play(object: THREE.Object3D, clip: string, options?: PlayAnimateOptions): { ok: true; armature: string } | { ok: false; why: string };
+  /** Fade out whatever the object's armature plays. */
+  stop(object: THREE.Object3D, fade?: number): void;
+  /** The clip the object's armature plays now, or null. */
+  playing(object: THREE.Object3D): string | null;
+  /** Advance every mixer by one update's `dt` (the game's clock). */
+  update(dt: number): void;
+  readonly warnings: readonly string[];
+  dispose(): void;
+}
+
+interface Armature {
+  readonly name: string;
+  readonly object: THREE.Object3D;
+  readonly mixer: THREE.AnimationMixer;
+  /** Every action that can play on it, baked or not. */
+  readonly names: readonly string[];
+  readonly bones: ReadonlyMap<string, THREE.Bone>;
+  readonly clips: Map<string, THREE.AnimationClip>;
+  /** Bakes in flight, by action name. */
+  readonly baking: Map<string, Promise<void>>;
+  /** Actions whose bake gave nothing to play: asked once, never re-baked every update. */
+  readonly failed: Set<string>;
+  current: { readonly name: string; readonly action: THREE.AnimationAction } | null;
+  /** The action most recently set, which a bake in flight starts when it lands. */
+  wanted: { readonly name: string; readonly options: PlayAnimateOptions } | null;
+}
+
+/** Bind the library's rigs and clips to Play's copy. */
+export function bindPlayAnimation(presentation: SkinPresentation, library: PlayClipLibrary): PlayAnimation {
+  const warnings = [...library.warnings];
+  const rigs: BoundRig[] = [];
+  for (const rig of library.rig?.rigs ?? []) {
+    if (!rig.object || !rig.armature || !rig.skinIndexBase64 || !rig.skinWeightBase64) {
+      if (rig.reason) warnings.push(rig.reason);
+      continue;
+    }
+    const bound = bindRig(presentation, rig, library.rig!.frame, warnings);
+    if (bound) rigs.push(bound);
+  }
+  const armatures = new Map<string, Armature>();
+  /** A mesh's presented object → the armature its skin is bound to. */
+  const meshArmature = new Map<THREE.Object3D, string>();
+  for (const rig of rigs) meshArmature.set(rig.mesh, rig.armature);
+  const toClip = (action: string, clip: BlenderActionClip, bones: ReadonlyMap<string, THREE.Bone>): THREE.AnimationClip | null => {
+    const tracks = clipTracks(clip, bones, warnings);
+    if (!tracks.length) return null;
+    return new THREE.AnimationClip(action, clip.duration ?? (clip.clipEnd! - clip.clipStart!) / clip.fps, tracks);
+  };
+  for (const [name, actions] of library.names) {
+    const object = presentation.objectForBlenderName(name);
+    if (!object || !actions.length) continue;
+    const bones = new Map<string, THREE.Bone>();
+    for (const rig of rigs) if (rig.armature === name) for (const bone of rig.bones) bones.set(bone.name, bone);
+    if (!bones.size) { warnings.push(`${name} has actions but no skinned mesh is bound to it, so they would move nothing.`); continue; }
+    const clips = new Map<string, THREE.AnimationClip>();
+    for (const [action, clip] of library.clips.get(name) ?? []) {
+      const built = toClip(action, clip, bones);
+      if (built) clips.set(action, built);
+    }
+    armatures.set(name, { name, object, mixer: new THREE.AnimationMixer(object), names: actions, bones, clips, baking: new Map(), failed: new Set(), current: null, wanted: null });
+  }
+  const objectArmature = new Map<THREE.Object3D, Armature>();
+  for (const armature of armatures.values()) objectArmature.set(armature.object, armature);
+  // EACH ARMATURE PLAYS ITS ASSIGNED ACTION from the first update, as Blender's viewport does.
+  for (const armature of armatures.values()) {
+    const name = library.assigned.get(armature.name);
+    const source = name ? armature.clips.get(name) : undefined;
+    if (!name || !source) continue;
+    const action = armature.mixer.clipAction(source);
+    action.setLoop(THREE.LoopRepeat, Number.POSITIVE_INFINITY);
+    action.play();
+    armature.current = { name, action };
+  }
+  /** The armature that animates `object`: itself, the one its skin is bound to, or the nearest
+   *  armature among its ancestors and descendants (a character's root empty holds its armature). */
+  const armatureOf = (object: THREE.Object3D): Armature | null => {
+    const own = objectArmature.get(object) ?? armatures.get(meshArmature.get(object) ?? '');
+    if (own) return own;
+    for (let parent = object.parent; parent; parent = parent.parent) {
+      const found = objectArmature.get(parent);
+      if (found) return found;
+    }
+    let found: Armature | null = null;
+    object.traverse((child) => { if (!found) found = objectArmature.get(child) ?? armatures.get(meshArmature.get(child) ?? '') ?? null; });
+    return found;
+  };
+  let disposed = false;
+  /** Crossfade an armature to a baked action. */
+  const start = (armature: Armature, clip: string, options: PlayAnimateOptions): void => {
+    const source = armature.clips.get(clip)!;
+    const fade = Math.max(0, options.fade ?? 0.2);
+    const action = armature.mixer.clipAction(source);
+    action.setLoop(options.loop === false ? THREE.LoopOnce : THREE.LoopRepeat, Number.POSITIVE_INFINITY);
+    action.clampWhenFinished = options.loop === false;
+    action.setEffectiveTimeScale(options.speed ?? 1);
+    if (armature.current?.name === clip) {
+      if (options.restart) action.reset().play();
+      return;
+    }
+    action.reset().setEffectiveWeight(1).play();
+    if (armature.current && fade > 0) armature.current.action.crossFadeTo(action, fade, false);
+    else armature.current?.action.stop();
+    armature.current = { name: clip, action };
+  };
+  return {
+    warnings,
+    clips: (object) => [...(armatureOf(object)?.names ?? [])],
+    play(object, clip, options = {}) {
+      const armature = armatureOf(object);
+      if (!armature) return { ok: false, why: `${object.name || 'this object'} has no armature with actions` };
+      if (!armature.names.includes(clip)) return { ok: false, why: `${armature.name} has no action "${clip}"; it has ${armature.names.join(', ')}` };
+      if (armature.failed.has(clip)) return { ok: false, why: `${armature.name}'s action "${clip}" has nothing this armature can play (see the console)` };
+      armature.wanted = { name: clip, options };
+      if (!armature.clips.has(clip)) {
+        // FIRST USE: baked now, and started when it lands if it is still the one wanted.
+        if (!armature.baking.has(clip))
+          armature.baking.set(clip, library.bake(armature.name, clip).then((baked) => {
+            armature.baking.delete(clip);
+            const built = baked ? toClip(clip, baked, armature.bones) : null;
+            if (built) armature.clips.set(clip, built);
+            else {
+              armature.failed.add(clip);
+              if (armature.wanted?.name === clip) armature.wanted = null;
+            }
+            if (built && !disposed && armature.wanted?.name === clip) start(armature, clip, armature.wanted.options);
+          }));
+        return { ok: true, armature: armature.name };
+      }
+      start(armature, clip, options);
+      return { ok: true, armature: armature.name };
+    },
+    stop(object, fade = 0.2) {
+      const armature = armatureOf(object);
+      if (armature) armature.wanted = null;
+      if (!armature?.current) return;
+      if (fade > 0) armature.current.action.fadeOut(fade); else armature.current.action.stop();
+      armature.current = null;
+    },
+    // What was last set, so a script that sets the same action every update while it bakes asks once.
+    playing: (object) => {
+      const armature = armatureOf(object);
+      return armature?.wanted?.name ?? armature?.current?.name ?? null;
+    },
+    update(dt) { for (const armature of armatures.values()) armature.mixer.update(dt); },
+    dispose() {
+      disposed = true;
+      for (const armature of armatures.values()) armature.mixer.stopAllAction();
+      for (const rig of rigs) rig.skeleton.dispose();
+    },
+  };
+}

package/contributions/blender-runtime-skin.ts

@@ -84,7 +84,7 @@ export interface SkinPresentation {
   root: THREE.Object3D;
 }
 
-interface BoundRig {
+export interface BoundRig {
   /** The MESH object's Blender name. */
   readonly object: string;
   readonly armature: string;
@@ -103,6 +103,150 @@ function rigSignature(rig: BlenderRigBinding, frame: number): string {
   return [rig.object, rig.mesh, rig.armature, rig.vertexCount, rig.bones.length, frame].join('|');
 }
 
+/**
+ * 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)),
+    );
+  }
+  if (missing.size) warnings.push(`${clip.action} animates ${[...missing].join(', ')}, which this binding has no bone for.`);
+  return tracks;
+}
+
+/**
+ * BIND ONE RIGGED MESH of a presentation: its drawn mesh becomes a `THREE.SkinnedMesh` over a
+ * `Skeleton` built from Blender's bones, in the pose the columns were exported at (so the bind
+ * is an identity there). Shared by the Timeline's director and Play's copy (`blender-play-skin.ts`).
+ */
+export function bindRig(
+  presentation: SkinPresentation,
+  rig: BlenderRigBinding,
+  frame: number,
+  warnings: string[],
+): BoundRig | null {
+  const meshObject = presentation.objectForBlenderName(rig.object ?? '');
+  const armatureObject = presentation.objectForBlenderName(rig.armature ?? '');
+  if (!meshObject || !armatureObject) return null;
+  const source = meshObject as THREE.Mesh;
+  const geometry = source.geometry;
+  if (!geometry) return null;
+  const blenderVertex = geometry.getAttribute('blenderVertex');
+  if (!blenderVertex) {
+    warnings.push(
+      `"${rig.object}" cannot be skinned: its presented geometry carries no \`blenderVertex\` attribute, so a per-Blender-vertex weight cannot be expanded onto its drawn vertices (presented as ${(meshObject as THREE.Object3D).type} with ${Object.keys(geometry.attributes).join(', ') || 'no attributes'}).`,
+    );
+    return null;
+  }
+  if (rig.vertexCount === 0) return null;
+  // THE COLUMNS AND THE BINDING MUST BE THE SAME MESH. `rna_rig` reads the
+  // ORIGINAL mesh's vertices (a deform layer is not geometry, so that is
+  // where the weights live); a generative modifier — Subdivision, Mirror,
+  // Array — makes the EVALUATED mesh the export door ships a different
+  // vertex set, and a skin bound across that mismatch would weight the wrong
+  // vertices. Named, never silently drawn.
+  let highest = 0;
+  for (let i = 0; i < blenderVertex.count; i++)
+    highest = Math.max(highest, blenderVertex.getX(i));
+  if (highest >= rig.vertexCount) {
+    warnings.push(
+      `"${rig.object}" is not skinned here: its presented geometry references Blender vertex ${highest} while the mesh declares ${rig.vertexCount}, which is a generative modifier (Subdivision, Mirror, Array…) between the two. Blender's own viewport shows the evaluated result; this presenter shows the exported columns unskinned.`,
+    );
+    return null;
+  }
+  const skinIndex = uint16Of(rig.skinIndexBase64 ?? '');
+  const skinWeight = float32Of(rig.skinWeightBase64 ?? '');
+  const drawn = blenderVertex.count;
+  const indices = new Uint16Array(drawn * 4);
+  const weights = new Float32Array(drawn * 4);
+  for (let i = 0; i < drawn; i++) {
+    const vertex = blenderVertex.getX(i);
+    for (let k = 0; k < 4; k++) {
+      indices[i * 4 + k] = skinIndex[vertex * 4 + k] ?? 0;
+      weights[i * 4 + k] = skinWeight[vertex * 4 + k] ?? 0;
+    }
+  }
+  geometry.setAttribute('skinIndex', new THREE.Uint16BufferAttribute(indices, 4));
+  geometry.setAttribute('skinWeight', new THREE.Float32BufferAttribute(weights, 4));
+
+  const boneRoot = new THREE.Group();
+  boneRoot.name = `${rig.armature}:bones`;
+  const bones: THREE.Bone[] = [];
+  const armatureSpace = rig.bones.map((bone) => matrixOf(bone.pose));
+  const indexByName = new Map(rig.bones.map((bone, index) => [bone.name, index]));
+  rig.bones.forEach((declared, index) => {
+    const bone = new THREE.Bone();
+    // THE NAME IS BLENDER'S, unsanitized, because a game reads it: the
+    // arena's `Player.tsx` finds its bones by Blender's own names. The CLIP
+    // therefore addresses bones by UUID rather than by name — three's
+    // `PropertyBinding` track-name grammar splits on `.`, and Blender's
+    // `hand.L` is an ordinary bone name.
+    bone.name = declared.name;
+    bones.push(bone);
+    const parentIndex = declared.parent === null ? undefined : indexByName.get(declared.parent);
+    const local =
+      parentIndex === undefined
+        ? armatureSpace[index]!.clone()
+        : armatureSpace[parentIndex]!.clone().invert().multiply(armatureSpace[index]!);
+    local.decompose(bone.position, bone.quaternion, bone.scale);
+    (parentIndex === undefined ? boneRoot : bones[parentIndex]!).add(bone);
+  });
+  armatureObject.add(boneRoot);
+
+  const skinned = new THREE.SkinnedMesh(geometry, source.material);
+  skinned.name = source.name;
+  skinned.matrixAutoUpdate = false;
+  skinned.matrix.copy(source.matrix);
+  skinned.matrix.decompose(skinned.position, skinned.quaternion, skinned.scale);
+  skinned.userData = source.userData;
+  // A SKIN MOVES PAST ITS BIND BOUNDS. three computes a SkinnedMesh's
+  // bounding sphere from the bind pose, so a raised arm at frame 24 is
+  // culled while its bind-pose sphere is off screen — a picture that
+  // vanishes mid-scrub with no error anywhere.
+  skinned.frustumCulled = false;
+  presentation.replacePresentedObject(source, skinned);
+  // THE BIND IS TAKEN AFTER THE GRAPH STANDS, because both halves of it are
+  // WORLD matrices: `Skeleton`'s bone inverses are the bones' `matrixWorld`
+  // at this instant and `bindMatrix` is the mesh's.
+  presentation.root.updateMatrixWorld(true);
+  const skeleton = new THREE.Skeleton(bones);
+  skinned.bind(skeleton, skinned.matrixWorld.clone());
+  if (rig.constrainedBones?.length)
+    warnings.push(
+      `Bone constraints on ${rig.constrainedBones.join(', ')}: the clip is derived from the F-Curves alone, so those bones play their channels rather than Blender's solved pose.`,
+    );
+  if (rig.unmappedGroups?.length)
+    warnings.push(
+      `${rig.object} carries vertex groups no bone is named for (${rig.unmappedGroups.join(', ')}); they weight nothing here, exactly as they deform nothing in Blender.`,
+    );
+  return {
+    object: rig.object ?? '',
+    armature: rig.armature ?? '',
+    mesh: skinned,
+    boneRoot,
+    bones,
+    skeleton,
+    frame,
+    signature: rigSignature(rig, frame),
+  };
+}
+
 /**
  * THE ONE DIRECTOR, module-scoped for the reason `BlenderRuntimeView` itself
  * is (`blender-runtime.document.tsx`): the Python session outlives workspace
@@ -112,6 +256,17 @@ function rigSignature(rig: BlenderRigBinding, frame: number): string {
  */
 export class BlenderSkinDirector {
   #rigs = new Map<string, BoundRig>();
+  /** Rigs that could not be bound, by mesh name, at the signature tried: not retried until the
+   *  rig changes (a generative modifier, no vertex map), so a settle does not re-read and re-warn. */
+  #unbindable = new Map<string, string>();
+
+  /** What could not be bound, keyed by the rig AND what is presented for its mesh: the fix for a
+   *  refusal (removing a generative modifier, showing a hidden object) changes the presentation,
+   *  not the rig, and must be retried. */
+  static #tried(presentation: SkinPresentation, mesh: string, signature: string): string {
+    const object = presentation.objectForBlenderName(mesh) as THREE.Mesh | null;
+    return `${signature}|${object?.uuid ?? 'absent'}|${object?.geometry?.uuid ?? 'none'}`;
+  }
   #mixer: THREE.AnimationMixer | null = null;
   #action: THREE.AnimationAction | null = null;
   #clip: BlenderActionClip | null = null;
@@ -235,6 +390,25 @@ export class BlenderSkinDirector {
   }
 
   /** Blender's scene clock exists even when the scene has no action. */
+  /** Whether a bind would change anything: nothing is bound yet, or a bound mesh is no longer the
+   *  object presented for its name (the presenter replaced it with a new draw). Lets the model
+   *  skip the rig read on the edits that touch no rig. */
+  stale(presentation: SkinPresentation): boolean {
+    // An unbindable rig whose presentation changed since it was tried is worth trying again.
+    for (const [mesh, tried] of this.#unbindable) {
+      const signature = tried.split('|').slice(0, -2).join('|');
+      if (BlenderSkinDirector.#tried(presentation, mesh, signature) !== tried) return true;
+    }
+    if (this.#rigs.size === 0) return this.#unbindable.size === 0;
+    for (const rig of this.#rigs.values()) {
+      if (presentation.objectForBlenderName(rig.object) !== rig.mesh) return true;
+      // A redraw that kept the object but replaced its geometry (a weight or mesh edit with the same
+      // vertex count) leaves the skinned mesh without its skin attributes.
+      if (!rig.mesh.geometry.getAttribute('skinIndex')) return true;
+    }
+    return false;
+  }
+
   get playable(): boolean {
     return this.#clip !== null && this.#transport !== null;
   }
@@ -270,10 +444,38 @@ export class BlenderSkinDirector {
       }
       wanted.add(rig.object);
       const signature = rigSignature(rig, answer.frame);
-      if (this.#rigs.get(rig.object)?.signature === signature) continue;
+      const held = this.#rigs.get(rig.object);
+      // Unchanged only while what it bound is still what is presented, skinned: a redraw that
+      // replaced the object or its geometry (same vertex count, same signature) is bound again.
+      if (held?.signature === signature && presentation.objectForBlenderName(rig.object) === held.mesh
+        && held.mesh.geometry.getAttribute('skinIndex')) continue;
+      const tried = BlenderSkinDirector.#tried(presentation, rig.object, signature);
+      if (this.#unbindable.get(rig.object) === tried) continue;
       const bound = this.#bindOne(presentation, rig, answer.frame, warnings);
+      if (!bound) {
+        this.#unbindable.set(rig.object, tried);
+        if (held) {
+          held.skeleton.dispose();
+          held.boneRoot.removeFromParent();
+          // A skinned mesh still presented with no skeleton would hold its last pose; it draws as
+          // the plain mesh it is again.
+          if (presentation.objectForBlenderName(rig.object) === held.mesh) {
+            const plain = new THREE.Mesh(held.mesh.geometry, held.mesh.material);
+            plain.name = held.mesh.name;
+            plain.matrixAutoUpdate = false;
+            plain.matrix.copy(held.mesh.matrix);
+            plain.matrix.decompose(plain.position, plain.quaternion, plain.scale);
+            plain.userData = held.mesh.userData;
+            presentation.replacePresentedObject(held.mesh, plain);
+          }
+          this.#rigs.delete(rig.object);
+          changed = true;
+        }
+      }
       if (bound) {
-        this.#rigs.get(rig.object)?.skeleton.dispose();
+        this.#unbindable.delete(rig.object);
+        held?.skeleton.dispose();
+        held?.boneRoot.removeFromParent();
         this.#rigs.set(rig.object, bound);
         changed = true;
       }
@@ -318,116 +520,8 @@ export class BlenderSkinDirector {
     this.#publish();
   }
 
-  #bindOne(
-    presentation: SkinPresentation,
-    rig: BlenderRigBinding,
-    frame: number,
-    warnings: string[],
-  ): BoundRig | null {
-    const meshObject = presentation.objectForBlenderName(rig.object ?? '');
-    const armatureObject = presentation.objectForBlenderName(rig.armature ?? '');
-    if (!meshObject || !armatureObject) return null;
-    const source = meshObject as THREE.Mesh;
-    const geometry = source.geometry;
-    if (!geometry) return null;
-    const blenderVertex = geometry.getAttribute('blenderVertex');
-    if (!blenderVertex) {
-      warnings.push(
-        `"${rig.object}" cannot be skinned: its presented geometry carries no \`blenderVertex\` attribute, so a per-Blender-vertex weight cannot be expanded onto its drawn vertices.`,
-      );
-      return null;
-    }
-    if (rig.vertexCount === 0) return null;
-    // THE COLUMNS AND THE BINDING MUST BE THE SAME MESH. `rna_rig` reads the
-    // ORIGINAL mesh's vertices (a deform layer is not geometry, so that is
-    // where the weights live); a generative modifier — Subdivision, Mirror,
-    // Array — makes the EVALUATED mesh the export door ships a different
-    // vertex set, and a skin bound across that mismatch would weight the wrong
-    // vertices. Named, never silently drawn.
-    let highest = 0;
-    for (let i = 0; i < blenderVertex.count; i++)
-      highest = Math.max(highest, blenderVertex.getX(i));
-    if (highest >= rig.vertexCount) {
-      warnings.push(
-        `"${rig.object}" is not skinned here: its presented geometry references Blender vertex ${highest} while the mesh declares ${rig.vertexCount}, which is a generative modifier (Subdivision, Mirror, Array…) between the two. Blender's own viewport shows the evaluated result; this presenter shows the exported columns unskinned.`,
-      );
-      return null;
-    }
-    const skinIndex = uint16Of(rig.skinIndexBase64 ?? '');
-    const skinWeight = float32Of(rig.skinWeightBase64 ?? '');
-    const drawn = blenderVertex.count;
-    const indices = new Uint16Array(drawn * 4);
-    const weights = new Float32Array(drawn * 4);
-    for (let i = 0; i < drawn; i++) {
-      const vertex = blenderVertex.getX(i);
-      for (let k = 0; k < 4; k++) {
-        indices[i * 4 + k] = skinIndex[vertex * 4 + k] ?? 0;
-        weights[i * 4 + k] = skinWeight[vertex * 4 + k] ?? 0;
-      }
-    }
-    geometry.setAttribute('skinIndex', new THREE.Uint16BufferAttribute(indices, 4));
-    geometry.setAttribute('skinWeight', new THREE.Float32BufferAttribute(weights, 4));
-
-    const boneRoot = new THREE.Group();
-    boneRoot.name = `${rig.armature}:bones`;
-    const bones: THREE.Bone[] = [];
-    const armatureSpace = rig.bones.map((bone) => matrixOf(bone.pose));
-    const indexByName = new Map(rig.bones.map((bone, index) => [bone.name, index]));
-    rig.bones.forEach((declared, index) => {
-      const bone = new THREE.Bone();
-      // THE NAME IS BLENDER'S, unsanitized, because a game reads it: the
-      // arena's `Player.tsx` finds its bones by Blender's own names. The CLIP
-      // therefore addresses bones by UUID rather than by name — three's
-      // `PropertyBinding` track-name grammar splits on `.`, and Blender's
-      // `hand.L` is an ordinary bone name.
-      bone.name = declared.name;
-      bones.push(bone);
-      const parentIndex = declared.parent === null ? undefined : indexByName.get(declared.parent);
-      const local =
-        parentIndex === undefined
-          ? armatureSpace[index]!.clone()
-          : armatureSpace[parentIndex]!.clone().invert().multiply(armatureSpace[index]!);
-      local.decompose(bone.position, bone.quaternion, bone.scale);
-      (parentIndex === undefined ? boneRoot : bones[parentIndex]!).add(bone);
-    });
-    armatureObject.add(boneRoot);
-
-    const skinned = new THREE.SkinnedMesh(geometry, source.material);
-    skinned.name = source.name;
-    skinned.matrixAutoUpdate = false;
-    skinned.matrix.copy(source.matrix);
-    skinned.matrix.decompose(skinned.position, skinned.quaternion, skinned.scale);
-    skinned.userData = source.userData;
-    // A SKIN MOVES PAST ITS BIND BOUNDS. three computes a SkinnedMesh's
-    // bounding sphere from the bind pose, so a raised arm at frame 24 is
-    // culled while its bind-pose sphere is off screen — a picture that
-    // vanishes mid-scrub with no error anywhere.
-    skinned.frustumCulled = false;
-    presentation.replacePresentedObject(source, skinned);
-    // THE BIND IS TAKEN AFTER THE GRAPH STANDS, because both halves of it are
-    // WORLD matrices: `Skeleton`'s bone inverses are the bones' `matrixWorld`
-    // at this instant and `bindMatrix` is the mesh's.
-    presentation.root.updateMatrixWorld(true);
-    const skeleton = new THREE.Skeleton(bones);
-    skinned.bind(skeleton, skinned.matrixWorld.clone());
-    if (rig.constrainedBones?.length)
-      warnings.push(
-        `Bone constraints on ${rig.constrainedBones.join(', ')}: the clip is derived from the F-Curves alone, so those bones play their channels rather than Blender's solved pose.`,
-      );
-    if (rig.unmappedGroups?.length)
-      warnings.push(
-        `${rig.object} carries vertex groups no bone is named for (${rig.unmappedGroups.join(', ')}); they weight nothing here, exactly as they deform nothing in Blender.`,
-      );
-    return {
-      object: rig.object ?? '',
-      armature: rig.armature ?? '',
-      mesh: skinned,
-      boneRoot,
-      bones,
-      skeleton,
-      frame,
-      signature: rigSignature(rig, frame),
-    };
+  #bindOne(presentation: SkinPresentation, rig: BlenderRigBinding, frame: number, warnings: string[]): BoundRig | null {
+    return bindRig(presentation, rig, frame, warnings);
   }
 
   #loadClip(presentation: SkinPresentation, clip: BlenderActionClip, warnings: string[]): void {
@@ -440,28 +534,7 @@ export class BlenderSkinDirector {
     const byName = new Map<string, THREE.Bone>();
     for (const rig of this.#rigs.values())
       if (rig.armature === clip.armature) for (const bone of rig.bones) byName.set(bone.name, bone);
-    const tracks: THREE.KeyframeTrack[] = [];
-    const missing = new Set<string>();
-    for (const track of clip.tracks) {
-      const bone = byName.get(track.bone);
-      if (!bone) {
-        missing.add(track.bone);
-        continue;
-      }
-      const times = float32Of(track.timeBase64);
-      const values = float32Of(track.valueBase64);
-      // ADDRESSED BY UUID, not by name — see the bone-naming note above.
-      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)),
-      );
-    }
-    if (missing.size)
-      warnings.push(
-        `${clip.action} animates ${[...missing].join(', ')}, which this binding has no bone for.`,
-      );
+    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);

package/contributions/blender-runtime.document.tsx

@@ -70,10 +70,15 @@ import {
   openModelDocumentBlend,
   modelDocumentMayOpen,
   modelDocumentOwnsPresentation,
+  blenderActionClip,
+  blenderArmatureActions,
+  blenderRig,
+  blenderRnaVersion,
 } from '../host/blender-runtime-host';
 import { BlenderObjectModeHeader } from './blender-header-menus';
 import { blenderOutlinerAuthoringFor, createBlenderOutlinerAuthoring } from './blender-outliner-authoring';
 import { blenderSkin } from './blender-runtime-skin';
+import { bindPlayAnimation, readPlayClipLibrary, type PlayAnimation } from './blender-play-skin';
 import { areaSplit, subscribeAreaSplit } from '../src/area-split';
 import { noteModelDocument } from '../src/play-mode';
 import { documentPlayExtension, subscribeDocumentPlayExtensions } from '@volter/editor-sdk/kit/document-play-extension';
@@ -897,6 +902,7 @@ function BlenderViewportArea({
     let preparing = false;
     let stopScript: (() => void) | null = null;
     let orbit: { enabled: boolean } | null = null;
+    let animation: PlayAnimation | null = null;
     const start = (): void => {
       if (stopScript || preparing || stopped) return;
       const stage = viewportStages().find((one) => one.documentId === documentId);
@@ -904,9 +910,21 @@ function BlenderViewportArea({
       preparing = true;
       orbit = stage.rig().orbit;
       orbit.enabled = false;
-      void view.prepareRendered(stage.rig().drawCamera(), 'render').then(() => {
+      // THE COPY'S CHARACTERS ANIMATE: their skins and every clip they can play, read once for
+      // this run and bound to the copy (`blender-play-skin.ts`). A read that fails costs the game its
+      // animation, said in the console, never the game itself.
+      void Promise.all([
+        view.prepareRendered(stage.rig().drawCamera(), 'render'),
+        readPlayClipLibrary().catch((error: unknown) => {
+          editorHost().console.warn(`The game's animation could not be read: ${error instanceof Error ? error.message : String(error)}`, 'blender-play');
+          return null;
+        }),
+      ]).then(([, library]) => {
         if (stopped) return;
+        animation = library ? bindPlayAnimation(view, library) : null;
+        for (const warning of animation?.warnings ?? []) editorHost().console.warn(warning, 'blender-play');
         stopScript = documentPlayExtension('model')?.run({
+          ...(animation ? { animation } : {}),
           documentId: modelId,
           container: layers,
           ready: () => { if (!stopped) { setPlayReady(true); playReadyRef.current?.(); } },
@@ -964,6 +982,8 @@ function BlenderViewportArea({
       stopPrepareFrames?.();
       window.removeEventListener('keydown', onEscape, true);
       stopScript?.();
+      animation?.dispose();
+      animation = null;
       layers.remove();
       if (orbit) orbit.enabled = true;
     };
@@ -1035,6 +1055,33 @@ function BlenderViewportArea({
       for (const { kind } of groups) stage?.setHelper(kind, null);
     };
   }, [documentId, view]);
+  /**
+   * THE MODEL'S SKINS AND ASSIGNED ACTION, AS BLENDER'S VIEWPORT SHOWS THEM: a rigged object is
+   * presented skinned, whatever editors are open, and plays the action assigned to it. Bound on
+   * every change of the file, a moment after it settles, because `rna_rig` walks every vertex of
+   * every rigged mesh; a file with no armature pays only the cheap listing.
+   */
+  const rnaVersion = useSyncExternalStore(subscribeBlenderRna, blenderRnaVersion, blenderRnaVersion);
+  /** The armatures, their actions and what each is assigned, as last bound: an edit that changes
+   *  none of them and replaced no skinned mesh costs no rig read and no bake. */
+  const boundListing = useRef<string | null>(null);
+  useEffect(() => {
+    if (!documentId || !main) return;
+    let live = true;
+    const timer = setTimeout(() => {
+      void (async () => {
+        const listing = await blenderArmatureActions();
+        if (!live || !listing?.armatures.length) return;
+        const key = JSON.stringify([listing.armatures, listing.scene ?? null]);
+        if (key === boundListing.current && !blenderSkin.stale(view)) return;
+        await blenderSkin.bind(view, { rig: () => blenderRig(), clip: () => blenderActionClip() });
+        boundListing.current = key;
+      })().catch((thrown: unknown) => {
+        if (live) editorHost().console.warn(`This file's rig could not be read: ${thrown instanceof Error ? thrown.message : String(thrown)}`, 'blender-skin');
+      });
+    }, 400);
+    return () => { live = false; clearTimeout(timer); };
+  }, [documentId, main, view, rnaVersion]);
   /**
    * ATTACH THE SKIN TO THIS STAGE'S TRANSPORT.
    *

package/contributions/blender-timeline.document.tsx

@@ -38,7 +38,6 @@
  * you are looking.
  */
 
-import { blenderModelView } from '@volter/blender-engine/browser/three/blender-runtime-view';
 import type { StageTransportHandle } from '@volter/editor-sdk/host';
 import { registerViewVerbs } from '@volter/editor-sdk/views';
 import {
@@ -51,8 +50,6 @@ import {
   useSyncExternalStore,
 } from 'react';
 import {
-  blenderActionClip,
-  blenderRig,
   blenderRnaVersion,
   subscribeBlenderRna,
 } from '../host/blender-runtime-host';
@@ -392,7 +389,7 @@ function BlenderTimeline() {
   // THE FRESHNESS IS THE RNA DOOR'S (ruling 3, 2026-09-19): every write and
   // every presented frame bumps it, which is exactly when a rig or an action
   // can have moved.
-  const rnaVersion = useSyncExternalStore(
+  useSyncExternalStore(
     subscribeBlenderRna,
     blenderRnaVersion,
     blenderRnaVersion,
@@ -404,30 +401,9 @@ function BlenderTimeline() {
   const { transform, size, refusal, onlySelected } = timelineViewState();
   const play = blenderSkin.state();
 
-  // THE BIND LIVES WITH THE TIMELINE, not with every present, and that is a
-  // cost decision stated rather than implied: `rna_rig` walks every vertex of
-  // every rigged mesh and `rna_action_clip` bakes every bone per frame, so
-  // paying for both on each of a session's hundreds of `blender-execute`
-  // presents would be a round trip nobody asked for. A project with no
-  // Timeline open therefore presents exactly as it did before this unit, with
-  // ordinary `THREE.Mesh`es.
-  useEffect(() => {
-    let live = true;
-    void blenderSkin
-      .bind(blenderModelView, {
-        rig: () => blenderRig(),
-        clip: () => blenderActionClip(),
-      })
-      .catch((thrown: unknown) => {
-        if (!live) return;
-        refuseTimelineGesture(
-          `The Timeline could not read this file's rig: ${thrown instanceof Error ? thrown.message : String(thrown)}`,
-        );
-      });
-    return () => {
-      live = false;
-    };
-  }, [rnaVersion]);
+  // The skins and the assigned action are the presented model's (`blender-runtime.document.tsx`
+  // binds them whatever is on screen, as Blender's viewport evaluates whatever editor is open);
+  // the Timeline only shows and drives their clock.
 
   useEffect(() => {
     const element = canvas.current;

package/host/blender-runtime-host.ts

@@ -43,7 +43,7 @@ import type {
   BlenderUvLayout,
 } from '@volter/blender-engine/browser/rna';
 import { createBlenderDisplayTransform, blenderDisplaySettingsForRender } from '@volter/blender-engine/browser/three/blender-display-transform';
-import type { BlenderRuntimeView } from '@volter/blender-engine/browser/three/blender-runtime-view';
+import { BlenderRuntimeView } from '@volter/blender-engine/browser/three/blender-runtime-view';
 import type { EditorCommandResult } from '@volter/editor-sdk/commands';
 import { editorHost } from '@volter/editor-sdk/host';
 import { invokeViewVerb, type ViewVerbContribution } from '@volter/editor-sdk/views';
@@ -677,11 +677,19 @@ export async function blenderRig(options?: { object?: string }): Promise<Blender
 export async function blenderActionClip(options?: {
   object?: string;
   bake?: boolean;
+  /** A named action baked against `object`'s armature, assigned or not. */
+  action?: string;
 }): Promise<BlenderActionClip | null> {
   if (!blenderSessionStarted()) return null;
   return blenderRuntime().actionClip(options);
 }
 
+/** Every armature and the actions that can play on it, for Play's clip library. Never starts the engine. */
+export async function blenderArmatureActions(): Promise<{ armatures: { armature: string; current: string | null; actions: string[]; keys?: string }[]; scene?: { frameCurrent: number; frameStart: number; frameEnd: number; fps: number } } | null> {
+  if (!blenderSessionStarted()) return null;
+  return blenderRuntime().armatureActions();
+}
+
 export async function blenderOutlinerSet(
   path: string,
   column: string,
@@ -821,6 +829,7 @@ function driveNodeView(cmd: { type: string; [key: string]: unknown }): NodeViewS
 }
 
 interface RuntimeView {
+  readonly root: THREE.Group;
   stageFrame(part: { session: string; revision: number; abort?: boolean; mesh?: string; image?: string; piece?: unknown }): void;
   applyFrame(frame: unknown): unknown;
   snapshot(): ReturnType<BlenderRuntimeView['snapshot']>;
@@ -903,6 +912,7 @@ const isRuntimeView = (value: unknown): value is RuntimeView =>
   typeof (value as RuntimeView).applyFrame === 'function' &&
   typeof (value as RuntimeView).stageFrame === 'function' &&
   typeof (value as RuntimeView).snapshot === 'function' &&
+  (value as RuntimeView).root?.isObject3D === true &&
   typeof (value as RuntimeView).captureSnapshot === 'function' &&
   typeof (value as RuntimeView).recordPresentation === 'function' &&
   typeof (value as RuntimeView).recordPhotograph === 'function';
@@ -951,11 +961,20 @@ export function blenderRuntime(): BlenderRuntime {
   captureLifetime = lifetime;
   let photographing = false;
   let streamedFrame: { view: RuntimeView; session: string; revision: number } | null = null;
+  let renderFrame: { view: BlenderRuntimeView; source: RuntimeView; sourceFrame: ReturnType<RuntimeView['snapshot']>; documentId: string; session: string; revision: number } | null = null;
+  const discardRenderFrame = () => {
+    const owned = renderFrame;
+    renderFrame = null;
+    owned?.view.dispose();
+    owned?.view.root.removeFromParent();
+  };
   const discardStreamedFrame = () => {
     const staged = streamedFrame;
     streamedFrame = null;
     if (staged) staged.view.stageFrame({ session: staged.session, revision: staged.revision, abort: true });
+    discardRenderFrame();
   };
+  lifetime.signal.addEventListener('abort', discardStreamedFrame, { once: true });
   runtime = new BlenderRuntime({
     work: beginBlenderWork,
     history: (entries) => {
@@ -997,6 +1016,20 @@ export function blenderRuntime(): BlenderRuntime {
       const view = await runtimeView();
       lifetime.signal.throwIfAborted();
       if (presentationDocumentId() !== documentId) throw new Error('Blender document changed during frame transfer');
+      if (part.evaluation === 'render') {
+        if (!renderFrame) {
+          if (part.mesh !== undefined || part.image !== undefined) throw new Error('Render resource arrived before its frame');
+          const detached = BlenderRuntimeView.forPhotograph();
+          view.root.updateWorldMatrix(true, false);
+          detached.root.matrix.copy(view.root.matrixWorld);
+          renderFrame = { view: detached, source: view, sourceFrame: view.snapshot(), documentId, session: part.session, revision: part.revision };
+        }
+        if (renderFrame.source !== view || renderFrame.sourceFrame !== view.snapshot() || renderFrame.documentId !== documentId || renderFrame.session !== part.session || renderFrame.revision !== part.revision)
+          throw new Error('Blender capture source changed during render transfer');
+        renderFrame.view.stageFrame(part);
+        return;
+      }
+      if (renderFrame) throw new Error('Viewport frame arrived during render transfer');
       if (streamedFrame && streamedFrame.view !== view)
         throw new Error('Blender presenter changed during frame transfer');
       view.stageFrame(part);
@@ -1027,6 +1060,12 @@ export function blenderRuntime(): BlenderRuntime {
         throw new Error('Blender document changed before its frame could be presented');
       if (streamedFrame && streamedFrame.view !== view)
         throw new Error('Blender presenter changed before its frame could be presented');
+      const rendering = capture?.evaluation === 'render' ? renderFrame : null;
+      if (capture?.evaluation === 'render' && !rendering)
+        throw new Error('Render-evaluated frame arrived without its staged resources');
+      if (rendering && (rendering.source !== view || rendering.sourceFrame !== view.snapshot() || rendering.documentId !== documentId))
+        throw new Error('Blender capture source changed before render presentation');
+      const presenter = rendering?.view ?? view;
       // WHAT THE PRESENTER HELD BEFORE THIS FRAME, carried back to the session
       // beside whatever this present produced. The session only has a RECORD of
       // what it sent; this view is the authority on what it actually holds, and
@@ -1036,7 +1075,7 @@ export function blenderRuntime(): BlenderRuntime {
       // all, rather than a wrong `null`.
       const endApply = beginBlenderWork('applying frame to Model');
       const applied = (() => {
-        try { return view.applyFrame(frame) as { held?: unknown } | null | undefined; }
+        try { return presenter.applyFrame(frame) as { held?: unknown } | null | undefined; }
         finally { endApply(); }
       })();
       streamedFrame = null;
@@ -1049,7 +1088,7 @@ export function blenderRuntime(): BlenderRuntime {
       // THE RECORD OF WHAT WAS SUBMITTED, kept only once the frame was taken:
       // a refused frame is not displayed and must not be described as if it
       // were.
-      view.recordPresentation(description);
+      presenter.recordPresentation(description);
       if (!capture) return answer(undefined);
       lastCapture = capture;
       if (!capture.render) return answer(undefined);
@@ -1091,7 +1130,7 @@ export function blenderRuntime(): BlenderRuntime {
           'A Blender render capture must carry the scene camera position, target and up',
         );
       if (photographing) throw new Error('A Blender render capture is already in progress');
-      const snapshot = view.captureSnapshot();
+      const snapshot = rendering ? rendering.view.takeCaptureSnapshot() : view.captureSnapshot();
       photographing = true;
       lifetime.signal.addEventListener('abort', snapshot.dispose, { once: true });
       try {
@@ -1150,6 +1189,7 @@ export function blenderRuntime(): BlenderRuntime {
         photographing = false;
         lifetime.signal.removeEventListener('abort', snapshot.dispose);
         snapshot.dispose();
+        if (rendering && renderFrame === rendering) renderFrame = null;
       }
     },
     // The worker's OWN stdout and stderr, forwarded so a developer can read

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