@volter/editor-blender 0.1.134 → 0.1.136

package/contributions/blender-outliner-authoring.ts

@@ -1280,7 +1280,11 @@ export function blenderOutlinerAuthoringFor(
       // is the other end of the same seam `hierarchy.node` already normalizes.
       // An id that resolves to no row is DROPPED rather than stored: a row id
       // is this provider's whole currency and a foreign one is not a selection.
-      selected = ids.map(rowIdFor).filter((id): id is string => id !== null);
+      // The WRITE below still names a presented object that has no row yet.
+      // One row lookup per id: `rowIdForObject` scans the object rows, and a marquee over a
+      // large scene passes every object it covers.
+      const rowIds = ids.map(rowIdFor);
+      selected = rowIds.filter((id): id is string => id !== null);
       publishPresentation();
       // AND IT WRITES BLENDER'S (see {@link writeBlenderSelection}). The
       // subject is the OWNING OBJECT of each selected row, which is Blender's
@@ -1294,14 +1298,37 @@ export function blenderOutlinerAuthoringFor(
       // its object selection, and a person who clicked one and saw the
       // Properties rail keep the last object deserves the sentence.
       const table = rows();
+      const view = presented();
       const names: string[] = [];
       const ownerless: string[] = [];
-      for (const id of selected) {
-        const row = table.get(id);
-        const name = row?.object;
-        if (name === undefined) ownerless.push(row?.name ?? id);
+      const unnamed: string[] = [];
+      ids.forEach((id, index) => {
+        const rowId = rowIds[index]!;
+        if (rowId !== null) {
+          const row = table.get(rowId);
+          const name = row?.object;
+          if (name === undefined) ownerless.push(row?.name ?? rowId);
+          else if (!names.includes(name)) names.push(name);
+          return;
+        }
+        // A PRESENTED OBJECT PAST THE TREE'S PAGE IS STILL BLENDER'S. `rna_outliner`
+        // answers the first `_OUTLINER_PAGE` rows of every child list, so in a larger
+        // scene the viewport picks objects that have no row yet (Canyon Comet: 1,146 rows
+        // under its one collection, 64 answered, all six karts among the rest). The view
+        // names the object by identity; the tree read for the frame this write presents
+        // keeps the selection's rows (`page_tree`), and `syncFromEngine` takes the row up.
+        const object = threeObject(defaultAdapter.hierarchy, id);
+        const name = object === null ? null : (view?.blenderObjectName(object) ?? null);
+        if (name === null) unnamed.push(id);
         else if (!names.includes(name)) names.push(name);
-      }
+      });
+      // Said, not swallowed: a picked object the view can't name is a selection Blender never gets.
+      if (unnamed.length > 0)
+        editorHost().console.warn(
+          `No Blender object answers to ${unnamed.join(', ')}, so Blender's selection leaves ` +
+            `${unnamed.length === 1 ? 'it' : 'them'} out.`,
+          'blender-outliner',
+        );
       if (ownerless.length > 0)
         editorHost().console.warn(
           `${ownerless.join(', ')} ${ownerless.length === 1 ? 'is' : 'are'} not an object, so ` +

package/contributions/blender-play-mixer.ts

@@ -0,0 +1,256 @@
+/**
+ * A CHARACTER'S ANIMATION IN A GAME: layered, weighted actions on one armature's bones, and a
+ * look-at for targets only the game knows.
+ *
+ * LAYERS: the base layer plays on every bone; a named layer plays on the bones from one bone down
+ * (`from: 'spine_01'`: the upper body), and takes those bones from the base. So legs can run while
+ * the upper body aims. A layer holds any number of actions at weights (`blend`); setting one action
+ * is a blend of that one, crossfaded (`set`).
+ *
+ * LOOK-AT: turns one bone so its axis points at a point, after the actions, by a weight and within
+ * an angle. The axis is the bone's FORWARD unless given: the direction in the bone that pointed the
+ * way the character faces (Blender's convention, the armature's -Y) in the pose the file was in. A
+ * bone's own Y runs along it, out of the top of a head, so it is not what "look" means. It is the game's, not Blender's: Blender's own IK and constraints are what an action was
+ * authored with; this aims at what exists only while the game runs (an aim target, the player).
+ *
+ * Everything advances on the game's clock (`update(dt)`).
+ */
+import * as THREE from 'three';
+
+export interface LayerOptions {
+  /** The layer: `base` (default) or a name of the game's choosing. */
+  readonly layer?: string;
+  /** For a layer other than `base`: the bone it plays from, with every bone below it. */
+  readonly from?: string;
+  /** Seconds for weights to reach what was set (default 0.2 for `set`, 0 for `blend`). */
+  readonly fade?: number;
+  /** Repeat (default true); `false` plays once and holds the last frame. */
+  readonly loop?: boolean;
+  /** Playback rate, 1 is the action's own. */
+  readonly speed?: number;
+  /** Start again from the first frame when this action already plays on the layer. */
+  readonly restart?: boolean;
+}
+
+export interface LookAtOptions {
+  /** How far toward the target, 0 to 1 (default 1). */
+  readonly weight?: number;
+  /** The bone's local axis that should point at the target: `forward` (default, see the header)
+   *  or one of the bone's own axes (`y` is a Blender bone's length). */
+  readonly axis?: 'forward' | 'x' | 'y' | 'z' | '-x' | '-y' | '-z';
+  /** The most it turns away from the animated pose, in degrees (default 75). */
+  readonly limit?: number;
+}
+
+interface Entry {
+  readonly name: string;
+  action: THREE.AnimationAction | null;
+  weight: number;
+  target: number;
+  rate: number;
+  loop: boolean;
+  speed: number;
+}
+
+interface Layer {
+  readonly name: string;
+  from: string | null;
+  /** The bones it plays on, by uuid; null for the base (everything other layers do not hold). */
+  bones: Set<string> | null;
+  readonly entries: Map<string, Entry>;
+}
+
+const AXES: Record<Exclude<NonNullable<LookAtOptions['axis']>, 'forward'>, THREE.Vector3> = {
+  x: new THREE.Vector3(1, 0, 0), y: new THREE.Vector3(0, 1, 0), z: new THREE.Vector3(0, 0, 1),
+  '-x': new THREE.Vector3(-1, 0, 0), '-y': new THREE.Vector3(0, -1, 0), '-z': new THREE.Vector3(0, 0, -1),
+};
+
+export class LayeredMixer {
+  readonly #mixer: THREE.AnimationMixer;
+  readonly #layers = new Map<string, Layer>();
+  readonly #masked = new Map<string, THREE.AnimationClip>();
+  readonly #looks = new Map<string, { bone: THREE.Bone; target: THREE.Vector3 | THREE.Object3D; options: LookAtOptions }>();
+  /** Each bone's forward in its own space, from the pose the file was in (before any action). */
+  readonly #forward = new Map<string, THREE.Vector3>();
+
+  /** `clipFor` answers an action's full clip, or null while it is not available yet (a bake in
+   *  flight); the mixer asks again on later updates. */
+  constructor(
+    readonly root: THREE.Object3D,
+    readonly bones: ReadonlyMap<string, THREE.Bone>,
+    private readonly clipFor: (action: string) => THREE.AnimationClip | null,
+  ) {
+    this.#mixer = new THREE.AnimationMixer(root);
+    // The character faces the armature's -Y, as in Blender; each bone's forward is that direction
+    // in the bone's frame at the pose the file was in.
+    root.updateWorldMatrix(true, true);
+    const rootWorld = root.getWorldQuaternion(new THREE.Quaternion());
+    const facing = new THREE.Vector3(0, -1, 0).applyQuaternion(rootWorld);
+    for (const [name, bone] of bones) {
+      const boneWorld = bone.getWorldQuaternion(new THREE.Quaternion());
+      this.#forward.set(name, facing.clone().applyQuaternion(boneWorld.invert()).normalize());
+    }
+    this.#layers.set('base', { name: 'base', from: null, bones: null, entries: new Map() });
+  }
+
+  /** Play one action on a layer, crossfading the layer's others out. */
+  set(action: string, options: LayerOptions = {}): string | null {
+    const layer = this.#layer(options);
+    if (typeof layer === 'string') return layer;
+    const held = layer.entries.get(action);
+    if (held && options.restart) held.action?.reset();
+    this.#weigh(layer, { [action]: 1 }, options.fade ?? 0.2, options);
+    return null;
+  }
+
+  /** Set a layer's actions at weights; an action left out fades to nothing. */
+  blend(weights: Readonly<Record<string, number>>, options: LayerOptions = {}): string | null {
+    const layer = this.#layer(options);
+    if (typeof layer === 'string') return layer;
+    this.#weigh(layer, weights, options.fade ?? 0, options);
+    return null;
+  }
+
+  /** Fade out what a layer plays (the base: everything the character plays). */
+  stop(options: LayerOptions = {}): void {
+    const layer = this.#layers.get(options.layer ?? 'base');
+    if (layer) this.#weigh(layer, {}, options.fade ?? 0.2, options);
+  }
+
+  /** The action that weighs most on a layer, as set (what a script asked for), or null. */
+  playing(layer = 'base'): string | null {
+    let best: Entry | null = null;
+    for (const entry of this.#layers.get(layer)?.entries.values() ?? []) if (entry.target > 0 && (!best || entry.target > best.target)) best = entry;
+    return best?.name ?? null;
+  }
+
+  /** Turn `bone` toward `target` (world point or object) every update until set to null. */
+  lookAt(bone: string, target: THREE.Vector3 | THREE.Object3D | null, options: LookAtOptions = {}): string | null {
+    if (target === null) { this.#looks.delete(bone); return null; }
+    const found = this.bones.get(bone);
+    if (!found) return `no bone "${bone}"`;
+    this.#looks.set(bone, { bone: found, target, options: { ...options, axis: options.axis ?? 'forward' } });
+    return null;
+  }
+
+  update(dt: number): void {
+    for (const layer of this.#layers.values()) {
+      for (const [name, entry] of [...layer.entries]) {
+        if (!entry.action) entry.action = this.#action(layer, name, entry);
+        entry.weight = entry.rate <= 0 ? entry.target
+          : entry.weight < entry.target ? Math.min(entry.target, entry.weight + dt * entry.rate)
+          : Math.max(entry.target, entry.weight - dt * entry.rate);
+        if (entry.action) entry.action.setEffectiveWeight(entry.weight);
+        if (entry.weight === 0 && entry.target === 0) {
+          entry.action?.stop();
+          layer.entries.delete(name);
+        }
+      }
+    }
+    this.#mixer.update(dt);
+    for (const look of this.#looks.values()) this.#turn(look.bone, look.target, look.options);
+  }
+
+  dispose(): void {
+    this.#mixer.stopAllAction();
+    this.#looks.clear();
+  }
+
+  // ---------------------------------------------------------------- internals
+
+  #layer(options: LayerOptions): Layer | string {
+    const name = options.layer ?? 'base';
+    if (name === 'base') return this.#layers.get('base')!;
+    let layer = this.#layers.get(name);
+    if (!layer || (options.from !== undefined && options.from !== layer.from)) {
+      if (!options.from) return `layer "${name}" needs the bone it plays from (\`from\`)`;
+      const root = this.bones.get(options.from);
+      if (!root) return `no bone "${options.from}" for layer "${name}"`;
+      const bones = new Set<string>();
+      root.traverse((child) => { if ((child as THREE.Bone).isBone) bones.add(child.uuid); });
+      if (layer) for (const entry of layer.entries.values()) entry.action?.stop();
+      layer = { name, from: options.from, bones, entries: layer?.entries ?? new Map() };
+      for (const entry of layer.entries.values()) entry.action = null;
+      this.#layers.set(name, layer);
+      // The base gives up these bones: its actions are rebuilt over what it still holds.
+      for (const entry of this.#layers.get('base')!.entries.values()) { entry.action?.stop(); entry.action = null; }
+    }
+    return layer;
+  }
+
+  #weigh(layer: Layer, weights: Readonly<Record<string, number>>, fade: number, options: LayerOptions): void {
+    const rate = fade > 0 ? 1 / fade : 0;
+    for (const entry of layer.entries.values()) { entry.target = 0; entry.rate = rate; }
+    for (const [name, raw] of Object.entries(weights)) {
+      const target = Math.max(0, Math.min(1, raw));
+      const entry = layer.entries.get(name) ?? { name, action: null, weight: 0, target: 0, rate, loop: true, speed: 1 };
+      entry.target = target;
+      entry.rate = rate;
+      entry.loop = options.loop ?? entry.loop;
+      entry.speed = options.speed ?? entry.speed;
+      if (entry.action) this.#configure(entry.action, entry);
+      layer.entries.set(name, entry);
+    }
+  }
+
+  /** The action of `name` on `layer`: its clip limited to the layer's bones. */
+  #action(layer: Layer, name: string, entry: Entry): THREE.AnimationAction | null {
+    const full = this.clipFor(name);
+    if (!full) return null;
+    const allowed = layer.bones ?? this.#baseBones();
+    const key = `${name}\u0000${layer.name}\u0000${allowed.size}`;
+    let clip = this.#masked.get(key);
+    if (!clip) {
+      const tracks = full.tracks.filter((track) => allowed.has(track.name.slice(0, track.name.indexOf('.'))));
+      clip = new THREE.AnimationClip(`${name}@${layer.name}`, full.duration, tracks);
+      this.#masked.set(key, clip);
+    }
+    const action = this.#mixer.clipAction(clip);
+    this.#configure(action, entry);
+    action.setEffectiveWeight(entry.weight);
+    action.play();
+    return action;
+  }
+
+  #configure(action: THREE.AnimationAction, entry: Entry): void {
+    action.setLoop(entry.loop ? THREE.LoopRepeat : THREE.LoopOnce, Number.POSITIVE_INFINITY);
+    action.clampWhenFinished = !entry.loop;
+    action.setEffectiveTimeScale(entry.speed);
+  }
+
+  /** Every bone no named layer holds. */
+  #baseBones(): Set<string> {
+    const taken = new Set<string>();
+    for (const layer of this.#layers.values()) for (const uuid of layer.bones ?? []) taken.add(uuid);
+    const bones = new Set<string>();
+    for (const bone of this.bones.values()) if (!taken.has(bone.uuid)) bones.add(bone.uuid);
+    return bones;
+  }
+
+  #turn(bone: THREE.Bone, target: THREE.Vector3 | THREE.Object3D, options: LookAtOptions): void {
+    const weight = Math.max(0, Math.min(1, options.weight ?? 1));
+    if (weight === 0) return;
+    bone.updateWorldMatrix(true, false);
+    // A script's Vector3 may come from its own copy of three, so it is recognised by its flag.
+    const at = (target as THREE.Vector3).isVector3 ? new THREE.Vector3().copy(target as THREE.Vector3) : (target as THREE.Object3D).getWorldPosition(new THREE.Vector3());
+    const position = new THREE.Vector3();
+    const world = new THREE.Quaternion();
+    bone.matrixWorld.decompose(position, world, new THREE.Vector3());
+    const desired = at.sub(position);
+    if (desired.lengthSq() < 1e-10) return;
+    desired.normalize();
+    const axis = options.axis ?? 'forward';
+    const local = axis === 'forward' ? this.#forward.get(bone.name) ?? AXES.y : AXES[axis];
+    const current = local.clone().applyQuaternion(world).normalize();
+    const turn = new THREE.Quaternion().setFromUnitVectors(current, desired);
+    const limit = THREE.MathUtils.degToRad(options.limit ?? 75);
+    const angle = 2 * Math.acos(Math.min(1, Math.abs(turn.w)));
+    const amount = angle > limit ? (limit / angle) * weight : weight;
+    const applied = new THREE.Quaternion().slerp(turn, amount);
+    const next = applied.multiply(world);
+    const parent = new THREE.Quaternion();
+    bone.parent?.getWorldQuaternion(parent);
+    bone.quaternion.copy(parent.invert().multiply(next));
+    bone.updateMatrixWorld(true);
+  }
+}

package/contributions/blender-play-skin.ts

@@ -0,0 +1,168 @@
+/**
+ * ANIMATION IN A GAME: actions played on the skeletons of the game's copy of the model.
+ *
+ * The copy binds its own skins (`BlenderRuntimeView.detach` keeps each skinned mesh's weights and
+ * the frame's armatures, and its view's `skeletons` builds and binds them exactly as the editing
+ * view does), so nothing here binds or reads a rig. What a game plays is Blender's: each armature
+ * starts on the action the file assigns it (`animation_data.action`), and a script sets another by
+ * name (`play.setAction`), as Blender's own assignment does. Any action in the file may be set; one
+ * that animates none of an armature's bones refuses, with the reason, once.
+ *
+ * A CLIP IS BAKED ONCE PER ACTION, through the clip door, the first time it is wanted. The copy's
+ * frame is the frame it was detached from, so its revisions hold for the run. Until a bake lands
+ * the armature keeps what it showed before (at first, the pose Blender exported).
+ *
+ * LAYERS, BLENDS AND LOOK-AT: each armature has a layered mixer (`blender-play-mixer.ts`), so a
+ * game plays actions on parts of a body, at weights, and turns a bone toward what only it knows.
+ *
+ * THE GAME'S CLOCK DRIVES IT: the runner advances the mixers by each update's `dt`
+ * (`@volter/editor-model-play`'s `play-script.ts`), so pause, step, speed and Restart hold for
+ * animation exactly as they do for the script.
+ */
+import type { BlenderActionClip } from '@volter/blender-engine/browser/rna';
+import type { BlenderRuntimeView } from '@volter/blender-engine/browser/three/blender-runtime-view';
+import type { ArmatureRig } from '@volter/blender-engine/browser/three/blender-runtime-skeleton';
+import * as THREE from 'three';
+import { clipTracks } from './blender-runtime-skin';
+import { LayeredMixer, type LayerOptions, type LookAtOptions } from './blender-play-mixer';
+
+export type PlayAnimateOptions = LayerOptions;
+
+type Answer = { ok: true; armature: string } | { ok: false; why: string };
+
+/** The game's door to its characters' actions (`ModelPlayContext.setAction`, `blend`, `lookAt`). */
+export interface PlayAnimation {
+  /** The actions in the file, which an object's armature may be set to play. */
+  clips(object: THREE.Object3D): readonly string[];
+  /** Play one action on a layer of an object's armature; the reason when it cannot. */
+  play(object: THREE.Object3D, clip: string, options?: PlayAnimateOptions): Answer;
+  /** Set a layer's actions at weights. */
+  blend(object: THREE.Object3D, weights: Readonly<Record<string, number>>, options?: PlayAnimateOptions): Answer;
+  /** Fade out what a layer plays. */
+  stop(object: THREE.Object3D, fade?: number, layer?: string): void;
+  /** The action that weighs most on a layer, as last set, or null. */
+  playing(object: THREE.Object3D, layer?: string): string | null;
+  /** Turn one of an object's bones toward a point (or object) every update, until `null`. */
+  lookAt(object: THREE.Object3D, bone: string, target: THREE.Vector3 | THREE.Object3D | null, options?: LookAtOptions): Answer;
+  update(dt: number): void;
+  readonly warnings: readonly string[];
+  dispose(): void;
+}
+
+interface Armature {
+  readonly rig: ArmatureRig;
+  readonly mixer: LayeredMixer;
+  readonly clips: Map<string, THREE.AnimationClip>;
+  readonly baking: Set<string>;
+  /** Actions with nothing this armature can play: asked once, never re-baked every update. */
+  readonly failed: Map<string, string>;
+}
+
+/** 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 {
+  const warnings: string[] = [];
+  const facts = view.animationFacts();
+  const actions = Object.keys(facts.actions);
+  const armatures = new Map<string, Armature>();
+  let disposed = false;
+
+  const refuse = (armature: Armature, clip: string, why: string): void => {
+    armature.failed.set(clip, why);
+    warnings.push(`${armature.rig.armature} / ${clip}: ${why}`);
+  };
+
+  /** The clip the mixer asks for: baked, or baked now (once) and given on a later update. */
+  const clipFor = (armature: Armature, clip: string): THREE.AnimationClip | null => {
+    const held = armature.clips.get(clip);
+    if (held || disposed || armature.failed.has(clip) || armature.baking.has(clip)) return held ?? null;
+    armature.baking.add(clip);
+    void bake(armature.rig.armature, clip).then((baked) => {
+      armature.baking.delete(clip);
+      const tracks = baked && baked.clipStart !== undefined && baked.clipEnd !== undefined
+        ? clipTracks(baked, armature.rig.bones, warnings) : [];
+      if (!baked || !tracks.length) {
+        refuse(armature, clip, baked?.reason ?? `it animates none of ${armature.rig.armature}'s bones`);
+        return;
+      }
+      const duration = baked.duration ?? (baked.clipEnd! - baked.clipStart!) / baked.fps;
+      armature.clips.set(clip, new THREE.AnimationClip(clip, duration, tracks));
+    }, (error: unknown) => {
+      armature.baking.delete(clip);
+      refuse(armature, clip, `it could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    return null;
+  };
+
+  for (const rig of view.skeletons.rigs()) {
+    const armature: Armature = {
+      rig, clips: new Map(), baking: new Set(), failed: new Map(),
+      mixer: new LayeredMixer(rig.object, rig.bones, (clip) => clipFor(armature, clip)),
+    };
+    armatures.set(rig.armature, armature);
+  }
+
+  // EACH ARMATURE STARTS ON ITS ASSIGNED ACTION, as Blender's viewport plays it.
+  for (const armature of armatures.values()) {
+    const assigned = facts.armatures[armature.rig.armature]?.action;
+    if (assigned) armature.mixer.set(assigned, { fade: 0 });
+  }
+
+  /** The armature that animates `object`: its own, the one its skin is bound to, or the nearest
+   *  armature among its ancestors and descendants (a character's root holds its armature). */
+  const own = (candidate: THREE.Object3D): Armature | null => {
+    for (const armature of armatures.values()) if (armature.rig.object === candidate) return armature;
+    const skin = (candidate as THREE.Mesh).geometry?.userData['blenderSkin'] as { armature: string } | undefined;
+    return skin ? armatures.get(skin.armature) ?? null : null;
+  };
+  const armatureOf = (object: THREE.Object3D): Armature | null => {
+    for (let at: THREE.Object3D | null = object; at; at = at.parent) {
+      const found = own(at);
+      if (found) return found;
+    }
+    let found: Armature | null = null;
+    object.traverse((child) => { if (!found) found = own(child); });
+    return found;
+  };
+
+  /** The armature, after checking every action named is one it can play. */
+  const resolve = (object: THREE.Object3D, clips: readonly string[]): Armature | { why: string } => {
+    const armature = armatureOf(object);
+    if (!armature) return { why: `${object.name || 'this object'} has no armature` };
+    for (const clip of clips) {
+      if (!(clip in facts.actions)) return { why: `the file has no action "${clip}"` };
+      const failed = armature.failed.get(clip);
+      if (failed) return { why: failed };
+    }
+    return armature;
+  };
+  const answer = (armature: Armature, refused: string | null): Answer =>
+    refused ? { ok: false, why: refused } : { ok: true, armature: armature.rig.armature };
+
+  return {
+    warnings,
+    clips: (object) => (armatureOf(object) ? actions : []),
+    play(object, clip, options = {}) {
+      const armature = resolve(object, [clip]);
+      return 'why' in armature ? { ok: false, why: armature.why } : answer(armature, armature.mixer.set(clip, options));
+    },
+    blend(object, weights, options = {}) {
+      const armature = resolve(object, Object.keys(weights));
+      return 'why' in armature ? { ok: false, why: armature.why } : answer(armature, armature.mixer.blend(weights, options));
+    },
+    stop(object, fade = 0.2, layer) {
+      armatureOf(object)?.mixer.stop({ fade, ...(layer ? { layer } : {}) });
+    },
+    // What was last set, so a script setting the same action every update while it bakes asks once.
+    playing: (object, layer) => armatureOf(object)?.mixer.playing(layer) ?? null,
+    lookAt(object, bone, target, options = {}) {
+      const armature = armatureOf(object);
+      if (!armature) return { ok: false, why: `${object.name || 'this object'} has no armature` };
+      return answer(armature, armature.mixer.lookAt(bone, target, options));
+    },
+    update(dt) { for (const armature of armatures.values()) armature.mixer.update(dt); },
+    dispose() {
+      disposed = true;
+      for (const armature of armatures.values()) armature.mixer.dispose();
+    },
+  };
+}

package/contributions/blender-runtime-skin.ts

@@ -8,11 +8,14 @@
  * it and re-exports the mesh columns. That is the wrong architecture: it puts
  * a WASM depsgraph evaluation and a full geometry round trip between the
  * person's pointer and the picture, and it moves `scene.frame_current` sixty
- * times a second under every bpy reader in the session. So instead the tab
- * reads the rig ONCE (`session.py`'s `rna_rig`) and the action ONCE
- * (`rna_action_clip`), builds a real `THREE.SkinnedMesh` + `Skeleton` +
- * `AnimationMixer`, and every scrub and every played frame after that costs
- * ZERO calls into Blender.
+ * 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.
  *
  * ## The bind pose is the EXPORT pose, and that is the whole trick
  *
@@ -36,11 +39,8 @@
  * from the F-Curves alone.
  */
 
-import type {
-  BlenderActionClip,
-  BlenderRig,
-  BlenderRigBinding,
-} from '@volter/blender-engine/browser/rna';
+import type { BlenderActionClip } from '@volter/blender-engine/browser/rna';
+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 { blenderRnaSet } from '../host/blender-runtime-host';
@@ -59,48 +59,31 @@ function float32Of(base64: string): Float32Array {
   const bytes = bytesOf(base64);
   return new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 2);
 }
-function uint16Of(base64: string): Uint16Array {
-  const bytes = bytesOf(base64);
-  return new Uint16Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 1);
-}
-
-/** A row-major four-row matrix, as every matrix in the RNA doors crosses —
- *  `THREE.Matrix4.set` takes its arguments row-major too, so this is a spread
- *  and not a transpose. */
-function matrixOf(rows: readonly (readonly [number, number, number, number])[]): THREE.Matrix4 {
-  return new THREE.Matrix4().set(...(rows.flat() as unknown as Parameters<THREE.Matrix4['set']>));
-}
-
-/** What the presenter needs of the view to swap a Mesh for a SkinnedMesh and
- *  to hang bones off an armature. Deliberately three methods and not the view:
- *  this module has no business knowing about frames, materials or overlays. */
-export interface SkinPresentation {
-  /** The presented `Object3D` for a Blender object NAME, or null. */
-  objectForBlenderName(name: string): THREE.Object3D | null;
-  /** Put `next` where `previous` was — same parent, same place in the object
-   *  table — so the next frame's reuse check finds it. */
-  replacePresentedObject(previous: THREE.Object3D, next: THREE.Object3D): void;
-  /** The presented root, for the one forced `updateMatrixWorld` a bind needs. */
-  root: THREE.Object3D;
-}
-
-interface BoundRig {
-  /** The MESH object's Blender name. */
-  readonly object: string;
-  readonly armature: string;
-  readonly mesh: THREE.SkinnedMesh;
-  readonly boneRoot: THREE.Group;
-  readonly bones: readonly THREE.Bone[];
-  readonly skeleton: THREE.Skeleton;
-  /** `scene.frame_current` the binding was read at. */
-  readonly frame: number;
-  /** The identity a re-read is compared against: rebuilding a skeleton on
-   *  every present would throw away the mixer's time sixty times a minute. */
-  readonly signature: string;
-}
-
-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;
 }
 
 /**
@@ -111,7 +94,12 @@ function rigSignature(rig: BlenderRigBinding, frame: number): string {
  * copy of the playback state anywhere.
  */
 export class BlenderSkinDirector {
-  #rigs = new Map<string, BoundRig>();
+  /** The presented view whose skeletons the clip plays on (`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. */
+  #armature: string | null = null;
+  #clipKey: string | null = null;
   #mixer: THREE.AnimationMixer | null = null;
   #action: THREE.AnimationAction | null = null;
   #clip: BlenderActionClip | null = null;
@@ -194,13 +182,14 @@ export class BlenderSkinDirector {
       action: clip?.action ?? null,
       object: clip?.object ?? null,
       armature: clip?.armature ?? null,
-      bones: [...this.#rigs.values()].reduce((sum, rig) => sum + rig.bones.length, 0),
+      bones: this.#armature ? this.#view?.skeletons.rig(this.#armature)?.bones.size ?? 0 : 0,
       keyframes: clip?.keyframes ?? [],
       summary: clip?.summary ?? [],
       clipStart: clip?.clipStart ?? null,
       clipEnd: clip?.clipEnd ?? null,
       tracks: clip?.tracks.length ?? 0,
-      bound: [...this.#rigs.keys()],
+      // The armature the clip plays on, when the presenter holds its skeleton.
+      bound: this.#armature && this.#view?.skeletons.rig(this.#armature) ? [this.#armature] : [],
       warnings: this.#warnings,
       engineCalls: this.#engineCalls,
       blenderFrame: clip?.frameCurrent ?? null,
@@ -239,229 +228,77 @@ export class BlenderSkinDirector {
     return this.#clip !== null && this.#transport !== null;
   }
 
-  // ------------------------------------------------------------ the binding
+  // ------------------------------------------------------------ the frame
 
   /**
-   * Bind every rigged mesh the frame carries, and load the active action.
-   *
-   * IDEMPOTENT BY SIGNATURE: a rig whose mesh, armature, vertex count, bone
-   * count and export frame are unchanged is left exactly as it is, mixer time
-   * included. That is what lets the presenter call this after EVERY frame
-   * without the picture jumping back to the bind pose each time something
-   * unrelated moved.
+   * 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.
    */
-  async bind(
-    presentation: SkinPresentation,
-    read: {
-      rig(): Promise<BlenderRig | null>;
-      clip(): Promise<BlenderActionClip | null>;
-    },
-  ): Promise<void> {
-    this.#engineCalls++;
-    const answer = await read.rig();
-    if (!answer) return;
+  async sync(view: BlenderRuntimeView, read: { clip(armature: string): Promise<BlenderActionClip | null> }): Promise<void> {
+    this.#view = view;
+    const facts = view.animationFacts();
+    const names = Object.keys(facts.armatures);
+    const active = facts.active;
+    const armature = active && facts.armatures[active] ? active
+      : (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[] = [];
-    const wanted = new Set<string>();
-    let changed = false;
-    for (const rig of answer.rigs) {
-      if (!rig.object || !rig.armature || !rig.skinIndexBase64 || !rig.skinWeightBase64) {
-        if (rig.reason) warnings.push(rig.reason);
-        continue;
-      }
-      wanted.add(rig.object);
-      const signature = rigSignature(rig, answer.frame);
-      if (this.#rigs.get(rig.object)?.signature === signature) continue;
-      const bound = this.#bindOne(presentation, rig, answer.frame, warnings);
-      if (bound) {
-        this.#rigs.get(rig.object)?.skeleton.dispose();
-        this.#rigs.set(rig.object, bound);
-        changed = true;
-      }
+    let clip: BlenderActionClip | null = null;
+    if (armature) {
+      this.#engineCalls++;
+      clip = await read.clip(armature);
     }
-    for (const [name, rig] of [...this.#rigs])
-      if (!wanted.has(name)) {
-        rig.skeleton.dispose();
-        rig.boneRoot.removeFromParent();
-        this.#rigs.delete(name);
-        changed = true;
-      }
-    this.#engineCalls++;
-    const clip = await read.clip();
     const previous = this.#clip;
     const rangeChanged = clip?.frameStart !== previous?.frameStart ||
       clip?.frameEnd !== previous?.frameEnd || clip?.fps !== previous?.fps;
-    const movedAction =
-      clip?.action !== previous?.action ||
-      clip?.tracks.length !== previous?.tracks.length ||
-      clip?.clipStart !== previous?.clipStart ||
-      clip?.clipEnd !== previous?.clipEnd;
     this.#clip = clip ?? null;
     if (!clip || clip.scene !== previous?.scene) this.#seeked = null;
     if (clip?.reason) warnings.push(clip.reason);
-    if (clip && (movedAction || changed)) this.#loadClip(presentation, clip, warnings);
-    // The subject can attach before the asynchronous scene read arrives.
-    // Refresh its clock range through the transport's own subject door.
+    if (clip) this.#loadClip(clip, warnings);
+    else {
+      this.#mixer?.stopAllAction();
+      this.#mixer = null;
+      this.#action = null;
+    }
     const activeSubject = this.#transport?.snapshot().activeSubject;
     if (rangeChanged && activeSubject) this.#transport?.setActiveSubject(activeSubject);
-    // BLENDER'S OWN FRAME RE-SYNCS THE PLAYHEAD. An agent that set
-    // `scene.frame_current` in bpy has said where it wants to be, and a
-    // present is how we hear about it; while the transport is PLAYING it would
-    // be the Timeline arguing with itself, so it is honoured only at rest.
     const playing = this.#transport?.snapshot().playbackState === 'playing';
-    if (clip && !playing && (rangeChanged || previous?.frameCurrent !== clip.frameCurrent)) {
+    if (clip && !playing) {
       this.#seek(clip.frameCurrent);
-      // THE BOOKMARK READ, once per bind: the file says where it was left, and
-      // the transport is what everything else now asks.
       if (this.#transport && clip.fps > 0) this.#transport.seek(clip.frameCurrent / clip.fps);
     }
     this.#warnings = warnings;
     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),
-    };
+  /** 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;
   }
 
-  #loadClip(presentation: SkinPresentation, clip: BlenderActionClip, warnings: string[]): void {
+  #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 armature = clip.armature ? presentation.objectForBlenderName(clip.armature) : null;
-    if (!armature) return;
-    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 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);
@@ -506,10 +343,8 @@ export class BlenderSkinDirector {
    *  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 {
-    for (const rig of this.#rigs.values()) {
-      rig.boneRoot.updateMatrixWorld(true);
-      rig.skeleton.update();
-    }
+    const rig = this.#armature ? this.#view?.skeletons.rig(this.#armature) : null;
+    rig?.object.updateMatrixWorld(true);
   }
 
   /** The scene's name, for the one address the Timeline writes to. */
@@ -617,11 +452,9 @@ export class BlenderSkinDirector {
     this.#action = null;
     this.#clip = null;
     this.#seeked = null;
-    for (const rig of this.#rigs.values()) {
-      rig.skeleton.dispose();
-      rig.boneRoot.removeFromParent();
-    }
-    this.#rigs.clear();
+    if (this.#armature) this.#view?.skeletons.restorePose(this.#armature);
+    this.#armature = null;
+    this.#clipKey = null;
   }
 }
 

package/contributions/blender-runtime.document.tsx

@@ -70,10 +70,13 @@ import {
   openModelDocumentBlend,
   modelDocumentMayOpen,
   modelDocumentOwnsPresentation,
+  blenderActionClip,
+  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 { playAnimation, 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 +900,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 +908,14 @@ function BlenderViewportArea({
       preparing = true;
       orbit = stage.rig().orbit;
       orbit.enabled = false;
+      // 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(() => {
         if (stopped) return;
+        animation = playAnimation(view, (armature, action) => blenderActionClip({ object: armature, action }));
         stopScript = documentPlayExtension('model')?.run({
+          ...(animation ? { animation } : {}),
           documentId: modelId,
           container: layers,
           ready: () => { if (!stopped) { setPlayReady(true); playReadyRef.current?.(); } },
@@ -964,6 +973,8 @@ function BlenderViewportArea({
       stopPrepareFrames?.();
       window.removeEventListener('keydown', onEscape, true);
       stopScript?.();
+      animation?.dispose();
+      animation = null;
       layers.remove();
       if (orbit) orbit.enabled = true;
     };
@@ -1035,6 +1046,20 @@ function BlenderViewportArea({
       for (const { kind } of groups) stage?.setHelper(kind, null);
     };
   }, [documentId, view]);
+  /**
+   * THE ASSIGNED ACTION ON THE PRESENTED SKELETONS. The skins themselves come with every frame (the
+   * presenter binds them, `blender-runtime-skeleton.ts`); after each present the director follows
+   * the frame, and reads a clip only when the frame says its action, revision or clock moved.
+   */
+  const rnaVersion = useSyncExternalStore(subscribeBlenderRna, blenderRnaVersion, blenderRnaVersion);
+  useEffect(() => {
+    if (!documentId || !main) return;
+    let live = true;
+    void blenderSkin.sync(view, { clip: (armature) => blenderActionClip({ object: armature }) }).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; };
+  }, [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/contributions/blender.command.ts

@@ -93,7 +93,6 @@ export const commands: CommandContribution['commands'] = {
   // and the ONE write the Timeline makes (`scene.frame_current`, once on
   // pause and at scrub-end) goes through `blender-rna-set`, which already
   // exists and already presents.
-  'blender-rig': verb('none', 60_000),
   'blender-action-clip': verb('none', 120_000),
   // THE NODE VIEW'S OWN ACTIONS as a session verb — the keyboard ruling's
   // `volter.*`-command-per-action pattern, and the only way the drawer's view

package/host/blender-runtime-host.ts

@@ -36,7 +36,6 @@ import type {
   BlenderNodeTree,
   BlenderOutlinerTree,
   BlenderOutlinerWrite,
-  BlenderRig,
   BlenderRnaContext,
   BlenderRnaView,
   BlenderRnaWrite,
@@ -661,15 +660,6 @@ export async function blenderUvLayout(options?: {
   return blenderRuntime().uvLayout(options);
 }
 
-/** THE RIG DOOR, in-page — one mesh's skin binding, which the presenter turns
- *  into a `THREE.SkinnedMesh` (`../contributions/blender-runtime-skin.ts`).
- *  WE VISUALIZE WITH THREE.JS, NOT BLENDER (owner rule, 2026-09-20): this is
- *  called once per rig, never per played frame. Same rule as the doors above:
- *  it never starts the engine. */
-export async function blenderRig(options?: { object?: string }): Promise<BlenderRig | null> {
-  if (!blenderSessionStarted()) return null;
-  return blenderRuntime().rig(options);
-}
 
 /** THE CLIP DOOR, in-page — one action as three.js keyframe tracks plus the
  *  scene's frame range and the Timeline's summary columns. Called when the
@@ -677,11 +667,14 @@ 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);
 }
 
+
 export async function blenderOutlinerSet(
   path: string,
   column: string,
@@ -1448,18 +1441,8 @@ export async function handleBlenderCommand(cmd: {
             }),
           },
         };
-      // THE RIG AND CLIP DOORS on the wire, beside the UV one: the skin
-      // binding and the action as three.js tracks, so a `cyclotron eval` reads
-      // exactly what the presenter bound and what the Timeline plays.
-      case 'blender-rig':
-        return {
-          ok: true,
-          data: {
-            result: await session.rig({
-              ...(typeof cmd['object'] === 'string' ? { object: cmd['object'] } : {}),
-            }),
-          },
-        };
+      // THE CLIP DOOR on the wire, beside the UV one: an action as three.js tracks, so a
+      // `cyclotron eval` reads exactly what the Timeline and a game play.
       case 'blender-action-clip':
         return {
           ok: true,

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