@volter/blender-engine 0.1.133 → 0.1.135

package/browser/three/blender-runtime-armature.ts

@@ -33,6 +33,7 @@ import { LineSegmentsGeometry } from 'three/addons/lines/LineSegmentsGeometry.js
 import { z } from 'zod';
 
 const scalar = z.number().finite();
+const matrixSchema = z.array(z.tuple([scalar, scalar, scalar, scalar])).length(4);
 
 /** ONE BONE, as `session.py`'s `_armature_bones` answers it. */
 export const boneSchema = z
@@ -49,9 +50,76 @@ export const boneSchema = z
     select: z.boolean(),
     active: z.boolean(),
     lockedWeight: z.boolean(),
+    /** `Bone.matrix_local`, the rest matrix in the armature's space. */
+    rest: matrixSchema.optional(),
+    /** The channels' own values: what a channel no action animates keeps. */
+    channels: z.object({
+      mode: z.string(),
+      location: z.array(scalar).length(3),
+      rotation_quaternion: z.array(scalar).length(4),
+      rotation_euler: z.array(scalar).length(3),
+      rotation_axis_angle: z.array(scalar).length(4),
+      scale: z.array(scalar).length(3),
+    }).strict().optional(),
+    /** Parenting flags that are not Blender's default, by name. */
+    inherit: z.array(z.string()).optional(),
+    /** The bone's constraint stack, in order. */
+    constraints: z.array(z.object({
+      name: z.string(),
+      type: z.string(),
+      enabled: z.boolean(),
+      influence: scalar,
+      target: z.string().optional(),
+      subtarget: z.string().optional(),
+      trackAxis: z.string().optional(),
+      headTail: scalar.optional(),
+    }).strict()).optional(),
   })
   .strict();
 
+/** One NLA strip, as `session.py`'s `_armature_animation` answers it. */
+export const nlaStripSchema = z.object({
+  name: z.string(),
+  type: z.string(),
+  action: z.string().nullable(),
+  start: scalar,
+  end: scalar,
+  actionStart: scalar,
+  actionEnd: scalar,
+  scale: scalar,
+  repeat: scalar,
+  influence: scalar,
+  animatedInfluence: z.boolean(),
+  /** The keyed influence's F-Curve, when `animatedInfluence`. */
+  influenceCurve: z.object({
+    extrapolation: z.string(),
+    interpolation: z.array(z.number()),
+    keysBase64: z.string(),
+    cycles: z.tuple([z.number(), z.number(), z.number(), z.number()]).optional(),
+    unsupported: z.array(z.string()).optional(),
+  }).strict().optional(),
+  animatedTime: z.boolean(),
+  blendIn: scalar,
+  blendOut: scalar,
+  blendType: z.string(),
+  extrapolation: z.string(),
+  reversed: z.boolean(),
+  mute: z.boolean(),
+}).strict();
+
+/** An armature's animation stack: NLA tracks bottom to top, then the active action over them. */
+export const armatureAnimationSchema = z.object({
+  useNla: z.boolean(),
+  influence: scalar,
+  blendType: z.string(),
+  extrapolation: z.string(),
+  /** The NLA is in tweak mode (`use_tweak_mode`), which the presenter does not play. */
+  tweak: z.boolean().optional(),
+  tracks: z.array(z.object({ name: z.string(), mute: z.boolean(), solo: z.boolean(), strips: z.array(nlaStripSchema) }).strict()),
+  /** Bones whose channels a driver sets. */
+  drivers: z.array(z.string()).optional(),
+}).strict();
+
 export const armatureSchema = z
   .object({
     object: z.string(),
@@ -61,10 +129,16 @@ export const armatureSchema = z
     showInFront: z.boolean(),
     mode: z.string(),
     bones: z.array(boneSchema),
+    /** `animation_data.action`, the action it plays (`session.py` `_armatures`). */
+    action: z.string().nullable().optional(),
+    animation: armatureAnimationSchema.optional(),
   })
   .strict();
 
 export type BlenderArmature = z.infer<typeof armatureSchema>;
+export type BlenderArmatureBone = z.infer<typeof boneSchema>;
+export type BlenderArmatureAnimation = z.infer<typeof armatureAnimationSchema>;
+export type BlenderNlaStrip = z.infer<typeof nlaStripSchema>;
 type Bone = z.infer<typeof boneSchema>;
 
 /**

package/browser/three/blender-runtime-skeleton.ts

@@ -0,0 +1,206 @@
+/**
+ * THE SKELETONS A FRAME DESCRIBES, and the skinned meshes bound to them.
+ *
+ * WHERE THE SKIN COMES FROM: the export door itself (`bpy_web_export.cc`, `write_skin`). Every mesh
+ * an Armature modifier deforms arrives with a `skin` block: the armature's name, the mesh's vertex
+ * group names and, per EXPORTED vertex, its four strongest groups and their normalized weights. The
+ * frame's `armatures` already name every bone with its parent and its pose matrix
+ * (`PoseBone.matrix`, armature space). So one frame holds everything a skin needs, from one
+ * evaluation, and nothing here reads the engine or guesses whether what it holds is stale: a weight
+ * edit, a modifier added or removed, a new pose, each re-exports the mesh under a new revision (the
+ * door's skin digest moves it) and the skin is rebuilt with the geometry.
+ *
+ * THE BIND IS THE EXPORTED POSE. The exported vertices are already deformed, at the pose the frame
+ * names, so each bone's inverse is that pose's inverse: at Blender's own pose the skinning is an
+ * identity and the picture is exactly the one Blender evaluated. A clip played on the bones
+ * (`AnimationMixer` over `rig().bones`) moves the mesh from there. The inverses come from the
+ * frame's matrices, never from the bones' current transforms, so a bind taken while a clip is
+ * playing is still right.
+ *
+ * AN UNWEIGHTED VERTEX stays where it is, as in Blender: the door gives it the index one past the
+ * groups with weight 1, and that index is a bone at the armature's origin that never moves. A group
+ * no bone is named for weights nothing (it is that same still bone), as it deforms nothing in Blender.
+ */
+import * as THREE from 'three';
+import type { BlenderArmature } from './blender-runtime-armature';
+
+/** The `skin` block of an exported mesh, as the door writes it (typed arrays by the worker). */
+export interface FrameSkin {
+  readonly armature: string;
+  readonly groups: readonly string[];
+  readonly columns: { readonly joints: Uint16Array; readonly weights: Float32Array };
+}
+
+export interface ArmatureRig {
+  /** The armature this rig belongs to, by Blender object name. */
+  readonly armature: string;
+  /** The armature's presented object, which the bones hang under. */
+  readonly object: THREE.Object3D;
+  /** Every bone by Blender's own bone name (unsanitized: a game finds them by those names). */
+  readonly bones: ReadonlyMap<string, THREE.Bone>;
+  /** The action the file assigns this armature (`animation_data.action`), if any. */
+  readonly action: string | null;
+}
+
+interface Rig extends ArmatureRig {
+  readonly root: THREE.Group;
+  readonly still: THREE.Bone;
+  /** Bone names and parents: a change rebuilds the bones. */
+  readonly structure: string;
+  /** The pose matrices last applied, armature space, by bone name. */
+  pose: Map<string, THREE.Matrix4>;
+  poseKey: string;
+  action: string | null;
+}
+
+const matrixOf = (rows: readonly (readonly number[])[]): THREE.Matrix4 =>
+  new THREE.Matrix4().set(...(rows.flat() as Parameters<THREE.Matrix4['set']>));
+
+/** Expand an exported mesh's per-vertex skin onto its DRAWN vertices (`blenderVertex`, the draw's
+ *  map back to Blender's vertices), as the geometry's `skinIndex` and `skinWeight`. */
+export function skinGeometry(geometry: THREE.BufferGeometry, skin: FrameSkin): void {
+  const source = geometry.getAttribute('blenderVertex');
+  if (!source) throw new Error(`A skinned mesh of ${skin.armature} was drawn without its vertex map`);
+  const drawn = source.count;
+  const indices = new Uint16Array(drawn * 4);
+  const weights = new Float32Array(drawn * 4);
+  for (let i = 0; i < drawn; i++) {
+    const vertex = source.getX(i);
+    indices.set(skin.columns.joints.subarray(vertex * 4, vertex * 4 + 4), i * 4);
+    weights.set(skin.columns.weights.subarray(vertex * 4, vertex * 4 + 4), i * 4);
+  }
+  geometry.setAttribute('skinIndex', new THREE.Uint16BufferAttribute(indices, 4));
+  geometry.setAttribute('skinWeight', new THREE.Float32BufferAttribute(weights, 4));
+  geometry.userData['blenderSkin'] = { armature: skin.armature, groups: [...skin.groups] };
+}
+
+export class RuntimeSkeletons {
+  #rigs = new Map<string, Rig>();
+
+  /** The rig of one armature, or null when the frame names none by that name. */
+  rig(armature: string): ArmatureRig | null {
+    return this.#rigs.get(armature) ?? null;
+  }
+
+  rigs(): readonly ArmatureRig[] {
+    return [...this.#rigs.values()];
+  }
+
+  /**
+   * Bring the rigs to this frame: build an armature's bones when it is new or its bones changed,
+   * and pose them as Blender posed them WHEN THAT POSE CHANGED, so a clip a reader is playing is
+   * not reset by a frame that says nothing new about the pose.
+   */
+  apply(armatures: Readonly<Record<string, BlenderArmature>>,
+    objectFor: (name: string) => THREE.Object3D | null): void {
+    for (const [name, rig] of [...this.#rigs]) {
+      const armature = armatures[name];
+      const object = objectFor(name);
+      if (!armature || !object || object !== rig.object) {
+        rig.root.removeFromParent();
+        this.#rigs.delete(name);
+      }
+    }
+    for (const [name, armature] of Object.entries(armatures)) {
+      const object = objectFor(name);
+      if (!object) continue;
+      const structure = armature.bones.map((bone) => `${bone.name}\u0000${bone.parent ?? ''}`).join('\u0001');
+      let rig = this.#rigs.get(name);
+      if (rig && rig.structure !== structure) {
+        rig.root.removeFromParent();
+        rig = undefined;
+      }
+      if (!rig) {
+        const root = new THREE.Group();
+        root.name = `${name}:bones`;
+        const still = new THREE.Bone();
+        still.name = `${name}:still`;
+        root.add(still);
+        const bones = new Map<string, THREE.Bone>();
+        for (const declared of armature.bones) {
+          const bone = new THREE.Bone();
+          bone.name = declared.name;
+          bones.set(declared.name, bone);
+        }
+        for (const declared of armature.bones) {
+          const parent = declared.parent === null ? undefined : bones.get(declared.parent);
+          (parent ?? root).add(bones.get(declared.name)!);
+        }
+        object.add(root);
+        rig = { armature: name, object, root, still, bones, structure, pose: new Map(), poseKey: '', action: null };
+        this.#rigs.set(name, rig);
+      }
+      rig.action = armature.action ?? null;
+      const poseKey = armature.bones.map((bone) => bone.matrix.flat().join(',')).join(';');
+      if (poseKey !== rig.poseKey) {
+        rig.poseKey = poseKey;
+        rig.pose = new Map(armature.bones.map((bone) => [bone.name, matrixOf(bone.matrix)]));
+        RuntimeSkeletons.#pose(rig, armature);
+      }
+    }
+  }
+
+  /** Set every bone's local transform from the frame's armature-space pose matrices. */
+  static #pose(rig: Rig, armature: BlenderArmature): void {
+    for (const declared of armature.bones) {
+      const own = rig.pose.get(declared.name)!;
+      const parent = declared.parent === null ? undefined : rig.pose.get(declared.parent);
+      const local = parent ? parent.clone().invert().multiply(own) : own.clone();
+      const bone = rig.bones.get(declared.name)!;
+      local.decompose(bone.position, bone.quaternion, bone.scale);
+    }
+  }
+
+  /** Put Blender's pose back on an armature's bones, after a reader that played a clip lets go. */
+  restorePose(armature: string): void {
+    const rig = this.#rigs.get(armature);
+    if (!rig) return;
+    for (const [name, own] of rig.pose) {
+      const bone = rig.bones.get(name)!;
+      const parentBone = bone.parent instanceof THREE.Bone && bone.parent !== rig.still ? bone.parent : null;
+      const parent = parentBone ? rig.pose.get(parentBone.name) : undefined;
+      const local = parent ? parent.clone().invert().multiply(own) : own.clone();
+      local.decompose(bone.position, bone.quaternion, bone.scale);
+    }
+  }
+
+  /**
+   * A mesh object's skinned form: a `THREE.SkinnedMesh` over its geometry, bound to its armature's
+   * rig at the pose the frame was exported in. Null when its geometry carries no skin or its
+   * armature is not in the frame (it then draws as the plain, exported mesh: Blender's own pose).
+   * The world matrices must be current (`root.updateMatrixWorld(true)`) before this is called.
+   */
+  bind(mesh: THREE.SkinnedMesh | THREE.Mesh): THREE.SkinnedMesh | null {
+    const skin = mesh.geometry.userData['blenderSkin'] as { armature: string; groups: string[] } | undefined;
+    const rig = skin ? this.#rigs.get(skin.armature) : undefined;
+    if (!skin || !rig) return null;
+    const skinned = (mesh as THREE.SkinnedMesh).isSkinnedMesh ? mesh as THREE.SkinnedMesh
+      : new THREE.SkinnedMesh(mesh.geometry, mesh.material);
+    if (skinned !== mesh) {
+      skinned.name = mesh.name;
+      skinned.matrixAutoUpdate = mesh.matrixAutoUpdate;
+      skinned.matrix.copy(mesh.matrix);
+      skinned.matrix.decompose(skinned.position, skinned.quaternion, skinned.scale);
+      skinned.userData = mesh.userData;
+      // A skin moves past its bind bounds: three computes them from the bind pose.
+      skinned.frustumCulled = false;
+    }
+    const armatureWorld = rig.object.matrixWorld;
+    const bones = [...skin.groups.map((group) => rig.bones.get(group) ?? rig.still), rig.still];
+    const inverses = bones.map((bone) => {
+      const pose = bone === rig.still ? undefined : rig.pose.get(bone.name);
+      const world = pose ? armatureWorld.clone().multiply(pose) : armatureWorld.clone();
+      return world.invert();
+    });
+    mesh.updateWorldMatrix(true, false);
+    // A re-export rebinds the same mesh: its old skeleton's bone texture goes with it.
+    (skinned.skeleton as THREE.Skeleton | undefined)?.dispose();
+    skinned.bind(new THREE.Skeleton(bones, inverses), mesh.matrixWorld.clone());
+    return skinned;
+  }
+
+  dispose(): void {
+    for (const rig of this.#rigs.values()) rig.root.removeFromParent();
+    this.#rigs.clear();
+  }
+}

package/browser/three/blender-runtime-view.ts

@@ -7,7 +7,8 @@ import * as THREE from 'three';
 import { z } from 'zod';
 import { onPresenterChange, presenterChanged } from './blender-presenter-change';
 import { bytesFromBase64 } from './blender-base64';
-import { ArmatureOverlay, armatureSchema } from './blender-runtime-armature';
+import { ArmatureOverlay, armatureSchema, type BlenderArmature } from './blender-runtime-armature';
+import { type FrameSkin, RuntimeSkeletons, skinGeometry } from './blender-runtime-skeleton';
 import { UNKNOWN_GEOMETRY, UNKNOWN_IMAGE } from './blender-runtime-frame';
 import {
   drawArraysFromColumns,
@@ -129,6 +130,38 @@ const attributeSchema = z.discriminatedUnion('type', [
   z.object({ ...attributeFields, type: z.literal('BOOLEAN'), data: z.array(z.boolean()) }).strict(),
   z.object({ ...attributeFields, type: z.literal('STRING'), data: z.array(z.string()) }).strict(),
 ]);
+/** The door's skin block (`bpy_web_export.cc` `write_skin`): per EXPORTED vertex, four deform
+ *  groups and their weights, for the armature that deforms the mesh. */
+const frameSkinSchema = z
+  .object({
+    armature: z.string(),
+    groups: z.array(z.string()),
+    columns: z.object({ joints: z.instanceof(Uint16Array), weights: z.instanceof(Float32Array) }).strict(),
+  })
+  .strict();
+/** The same skin per DRAWN vertex, as a copy of a presented frame carries it (`fullFrame`). */
+const drawnSkinSchema = z
+  .object({
+    armature: z.string(),
+    groups: z.array(z.string()),
+    index: z.instanceof(Uint16Array),
+    weight: z.instanceof(Float32Array),
+  })
+  .strict();
+/** An exported mesh's geometry with its skin laid over its drawn vertices (`skinGeometry`). */
+function withFrameSkin(geometry: THREE.BufferGeometry, skin: FrameSkin | undefined): THREE.BufferGeometry {
+  if (skin) skinGeometry(geometry, skin);
+  return geometry;
+}
+/** A drawn mesh's geometry with the per-drawn-vertex skin a copy carried (`fullFrame`). */
+function withDrawnSkin(geometry: THREE.BufferGeometry,
+  skin: { armature: string; groups: string[]; index: Uint16Array; weight: Float32Array } | undefined): THREE.BufferGeometry {
+  if (!skin) return geometry;
+  geometry.setAttribute('skinIndex', new THREE.Uint16BufferAttribute(skin.index, 4));
+  geometry.setAttribute('skinWeight', new THREE.Float32BufferAttribute(skin.weight, 4));
+  geometry.userData['blenderSkin'] = { armature: skin.armature, groups: [...skin.groups] };
+  return geometry;
+}
 const drawArraysSchema = z
   .object({
     positions: z.instanceof(Float32Array),
@@ -149,6 +182,7 @@ const drawArraysSchema = z
     ),
     /** The draw's vertex map (`DrawArrays.sourceVertex`), kept by a copy that plays (skins bind over it). */
     sourceVertex: z.instanceof(Uint32Array).optional(),
+    skin: drawnSkinSchema.optional(),
     hash: z.string(),
   })
   .strict();
@@ -224,6 +258,7 @@ const columnAttributeSchema = z
   .strict();
 const exportedMeshSchema = z
   .object({
+    skin: frameSkinSchema.optional(),
     columns: columnsSchema,
     attributes: z.array(columnAttributeSchema),
     activeUv: z.string().nullable(),
@@ -567,6 +602,13 @@ export const frameSchema = z
      * `show_in_front`. `blender-runtime-armature.ts` is the drawing.
      */
     armatures: z.record(z.string(), armatureSchema).default({}),
+    /** Every action and its revision (`bpy_web_export.cc`): a clip is baked again exactly when its
+     *  action's revision moves. */
+    actions: z.record(z.string(), z.number().int().nonnegative()).default({}),
+    /** The scene's frame range and rate (`session.py`), beside `frame`. */
+    clock: z.object({ start: z.number().int(), end: z.number().int(), fps: z.number().finite().positive() }).strict().optional(),
+    /** Actions with no user and no fake user, which the next save drops. */
+    unkeptActions: z.array(z.string()).default([]),
     /** The active object's active vertex group, per vertex
      *  (`blender-runtime-weights.ts`); null when nothing is painted. */
     weights: weightsSchema.nullable().default(null),
@@ -663,8 +705,24 @@ export interface PhotographRecord {
   render: { width: number; height: number; fov: number; orthographic: boolean };
 }
 
+/** A skinned mesh as the plain mesh it is again (its geometry kept), when its skin went away. */
+function plainMesh(skinned: THREE.Mesh): THREE.Mesh {
+  const plain = new THREE.Mesh(skinned.geometry, skinned.material);
+  plain.name = skinned.name;
+  plain.matrixAutoUpdate = skinned.matrixAutoUpdate;
+  plain.matrix.copy(skinned.matrix);
+  plain.matrix.decompose(plain.position, plain.quaternion, plain.scale);
+  plain.userData = skinned.userData;
+  return plain;
+}
+
 export class BlenderRuntimeView {
   readonly root = new THREE.Group();
+  /** Every armature's bones as the frame poses them, and the skins bound to them
+   *  (`blender-runtime-skeleton.ts`). A reader plays clips on `skeletons.rig(name).bones`. */
+  readonly skeletons = new RuntimeSkeletons();
+  /** The geometry and rig each skinned mesh was bound with, so it is bound again only when either changes. */
+  private skinBinds = new WeakMap<THREE.Object3D, { geometry: THREE.BufferGeometry; rig: object }>();
   private readonly instances = new BlenderRuntimeInstances(this.root);
   private readonly materialRanges = new BlenderMaterialRanges();
   private readonly transparentInstances = new BlenderTransparentInstances(this.root);
@@ -1061,6 +1119,40 @@ export class BlenderRuntimeView {
    *  needs it — its rows come from the engine by name, and every one that our
    *  viewport can select has to find its way back to a three object through
    *  the frame's own table, never through `object.name`. */
+  /**
+   * WHAT THE LAST FRAME SAYS ABOUT ANIMATION, for a reader that plays clips on `skeletons`: the
+   * scene's current frame and clock, every action's revision, each armature's assigned action, the
+   * active object, and which armature a mesh object's skin is bound to. Read off the frame the view
+   * holds, never the engine.
+   */
+  animationFacts(): {
+    frame: number;
+    clock: { start: number; end: number; fps: number } | null;
+    /** Actions the next save drops: no user and no fake user. */
+    unkept: readonly string[];
+    active: string | null;
+    actions: Readonly<Record<string, number>>;
+    /** Each armature as the frame describes it: bones (rest, channels, constraints, Blender's own
+     *  pose), its action and its NLA stack. */
+    armatures: Readonly<Record<string, BlenderArmature>>;
+    skinArmature(object: string): string | null;
+  } {
+    const frame = this.frame;
+    return {
+      frame: frame?.frame ?? 0,
+      clock: frame?.clock ?? null,
+      unkept: frame?.unkeptActions ?? [],
+      active: frame?.active ?? null,
+      actions: frame?.actions ?? {},
+      armatures: frame?.armatures ?? {},
+      skinArmature: (name) => {
+        const object = this.objectForBlenderName(name) as THREE.Mesh | null;
+        const skin = object?.geometry?.userData['blenderSkin'] as { armature: string } | undefined;
+        return skin?.armature ?? null;
+      },
+    };
+  }
+
   objectForBlenderName(name: string): THREE.Object3D | null {
     const entry = this.frame?.objects.find((o) => o.name === name);
     return entry === undefined ? null : (this.objects.get(entry.id) ?? null);
@@ -1671,9 +1763,11 @@ export class BlenderRuntimeView {
       const data = exportedMeshSchema.parse(part.piece);
       if (staged.meshes.has(part.mesh)) throw new Error('Duplicate Blender mesh piece');
       const signature = `revision:${data.revision}`;
-      staged.meshes.set(part.mesh, { signature, geometry: geometryFromDrawArrays(drawArraysFromColumns({
+      const geometry = geometryFromDrawArrays(drawArraysFromColumns({
         ...data.columns, attributes: data.attributes as never, activeUv: data.activeUv, renderUv: data.renderUv,
-      }, signature)) });
+      }, signature));
+      if (data.skin) skinGeometry(geometry, data.skin);
+      staged.meshes.set(part.mesh, { signature, geometry });
     } else if (part.image !== undefined) {
       if (staged.images.has(part.image)) throw new Error('Duplicate Blender image piece');
       staged.images.set(part.image, frameImageSchema.parse(part.piece));
@@ -1791,7 +1885,7 @@ export class BlenderRuntimeView {
         prepared.set(id, {
           signature,
           geometry: exported
-            ? geometryFromDrawArrays(
+            ? withFrameSkin(geometryFromDrawArrays(
                 drawArraysFromColumns(
                   {
                     ...data.columns,
@@ -1801,9 +1895,9 @@ export class BlenderRuntimeView {
                   },
                   signature,
                 ),
-              )
+              ), data.skin)
             : drawn
-              ? geometryFromDrawArrays(data)
+              ? withDrawnSkin(geometryFromDrawArrays(data), data.skin)
               : drawRuntimeGeometry(data),
         });
       }
@@ -2180,6 +2274,26 @@ export class BlenderRuntimeView {
         this.lights.delete(id);
       }
     this.root.updateMatrixWorld(true);
+    // THE SKINS, once the graph stands (a bind reads world matrices): every armature's bones as
+    // Blender posed them, and every mesh whose exported geometry carries a skin bound to them. A
+    // mesh is bound again only when its geometry or its rig was rebuilt; one whose geometry lost
+    // its skin draws as the plain mesh it is.
+    const named = new Map(next.objects.map((obj) => [obj.name, this.objects.get(obj.id) ?? null]));
+    this.skeletons.apply(next.armatures, (name) => named.get(name) ?? null);
+    for (const obj of next.objects) {
+      if (obj.mesh === null || obj.volume) continue;
+      const object = this.objects.get(obj.id) as THREE.Mesh | undefined;
+      if (!object?.isMesh) continue;
+      const skin = object.geometry.userData['blenderSkin'] as { armature: string } | undefined;
+      const rig = skin ? this.skeletons.rig(skin.armature) : null;
+      const held = this.skinBinds.get(object);
+      if (rig && held?.geometry === object.geometry && held.rig === rig) continue;
+      const bound = rig ? this.skeletons.bind(object) : null;
+      const replacement = bound ?? ((object as THREE.SkinnedMesh).isSkinnedMesh ? plainMesh(object) : null);
+      if (replacement && replacement !== object) this.replacePresentedObject(object, replacement);
+      if (bound && rig) this.skinBinds.set(bound, { geometry: bound.geometry, rig });
+    }
+    this.root.updateMatrixWorld(true);
     // Keep the frame's identity and object table, not its geometry payloads:
     // a presented mesh is already resident as its BufferGeometry, and the
     // nested number arrays it arrived as cost ~15x their JSON (the blower's
@@ -2256,7 +2370,8 @@ export class BlenderRuntimeView {
     // Inspection overlays are not render content. In particular weight-paint
     // overlays reference source vertices, which the evaluated draw no longer
     // needs and a render snapshot deliberately does not copy.
-    const frame: Frame = structuredClone({ ...source, images: {}, armatures: {}, weights: null });
+    // A copy that plays keeps the armatures its skins bind to; a render snapshot draws no bones.
+    const frame: Frame = structuredClone({ ...source, images: {}, armatures: options.sourceVertices ? source.armatures : {}, weights: null });
     for (const [id, { signature, geometry }] of this.meshes) {
       const attribute = (name: string): Float32Array<ArrayBuffer> | null => {
         const value = geometry.getAttribute(name);
@@ -2298,6 +2413,14 @@ export class BlenderRuntimeView {
         ...(options.sourceVertices && geometry.getAttribute('blenderVertex')
           ? { sourceVertex: new Uint32Array((geometry.getAttribute('blenderVertex') as THREE.BufferAttribute).array) }
           : {}),
+        // A COPY THAT PLAYS keeps its skin too, per drawn vertex, so its own skeletons bind it.
+        ...(options.sourceVertices && geometry.userData['blenderSkin'] && geometry.getAttribute('skinIndex')
+          ? { skin: {
+              ...(geometry.userData['blenderSkin'] as { armature: string; groups: string[] }),
+              index: new Uint16Array((geometry.getAttribute('skinIndex') as THREE.BufferAttribute).array),
+              weight: new Float32Array((geometry.getAttribute('skinWeight') as THREE.BufferAttribute).array),
+            } }
+          : {}),
       };
     }
     for (const [id, { signature }] of this.volumes)
@@ -2507,6 +2630,8 @@ export class BlenderRuntimeView {
   }
 
   private clear() {
+    this.skeletons.dispose();
+    this.skinBinds = new WeakMap();
     this.worldVisibility.dispose();
     this.objectInfoMaterials.clear();
     this.materialRanges.clear();

package/browser/worker.ts

@@ -796,11 +796,6 @@ async function handle(request: WorkerRequest): Promise<unknown> {
     // reason is a measured defect: I4's Collection tab simply did not stand
     // because `collection` crossed `runtime.ts` and `session.py` and never
     // this switch, with no error anywhere.
-    case 'rig':
-      return pullWork('rig', () => ask({
-        op: 'rig',
-        ...(request.object === undefined ? {} : { object: request.object }),
-      }));
     case 'action-clip':
       return ask({
         op: 'action-clip',
@@ -808,8 +803,6 @@ async function handle(request: WorkerRequest): Promise<unknown> {
         ...(request.bake === undefined ? {} : { bake: request.bake }),
         ...(request.action === undefined ? {} : { action: request.action }),
       });
-    case 'armature-actions':
-      return ask({ op: 'armature-actions' });
     case 'outliner-set':
       return ask({
         op: 'outliner-set',

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/blender-engine",
   "author": "Volter AI, Inc.",
   "license": "GPL-3.0-or-later",
-  "version": "0.1.133",
+  "version": "0.1.135",
   "publishConfig": {
     "access": "public"
   },

package/wasm/BUNDLE.json

@@ -1,9 +1,9 @@
 {
   "blender": "5.2.0 LTS",
-  "source": "5a3cb1250fc1fd7df59e3ff823949c06e52d9422",
+  "source": "49cb2710c66715ba61fbf65cc1cc818b1f49d73a",
   "upstream": "fbe6228777e7d9afefcd61a413844e790ae75db7",
   "sourceRepository": "https://github.com/volter-ai/blender",
-  "sourceRecipe": "https://github.com/volter-ai/blender/blob/5a3cb1250fc1fd7df59e3ff823949c06e52d9422/build_files/emscripten/RELEASE.md",
+  "sourceRecipe": "https://github.com/volter-ai/blender/blob/49cb2710c66715ba61fbf65cc1cc818b1f49d73a/build_files/emscripten/RELEASE.md",
   "factoryEngine": "BLENDER_EEVEE",
   "files": {
     "blender_browser.js": "raw",
@@ -12,12 +12,12 @@
   },
   "rawFiles": {
     "blender_browser.js": {
-      "bytes": 408423,
-      "sha256": "d818e8d746bc62ebf810206ac564d2dc75dc645b3121f4a3919d13ecef11e419"
+      "bytes": 408218,
+      "sha256": "bcdbcb3ff18110c095b5170d70a0d0f0b33687f86c14c8bc10c979d613ed11c7"
     },
     "blender_browser.wasm": {
-      "bytes": 86351436,
-      "sha256": "d4c3a8002cb1686f3c5299e28bcbb356934bbe910f2485b2572032b115cf67bd"
+      "bytes": 86366810,
+      "sha256": "56752d31e837d314eb489ffb031915e003ec9fade944657690ae097ed7c1e947"
     },
     "blender_browser.data": {
       "bytes": 52699590,
@@ -26,12 +26,12 @@
   },
   "shippedFiles": {
     "blender_browser.js": {
-      "bytes": 408423,
-      "sha256": "d818e8d746bc62ebf810206ac564d2dc75dc645b3121f4a3919d13ecef11e419"
+      "bytes": 408218,
+      "sha256": "bcdbcb3ff18110c095b5170d70a0d0f0b33687f86c14c8bc10c979d613ed11c7"
     },
     "blender_browser.wasm.br": {
-      "bytes": 18605311,
-      "sha256": "97e3bc2c772e9fd6da5a3e28086c1ee1dfd62b35ebdeb127a413b4bd5904031f"
+      "bytes": 18248590,
+      "sha256": "54cb053de1d77030ba19345eaca38d16d1971bbb50f3de6624709f8b2f97f4e9"
     },
     "blender_browser.data.br": {
       "bytes": 8056485,
@@ -45,6 +45,6 @@
   "note": "Emscripten 6.0.5, Release -O3 objects and -O2 link, retained public build recipe and dependency licenses. Scoped render-evaluated export preserves render-only geometry and render-specific modifier results without replacing the viewport export state. Prior geometry identity and memory fixes remain. Full-scene Three versus Cycles rendering parity remains incomplete.",
   "callTrampoline": "CPython 3.13.13 is compiled with PY_CALL_TRAMPOLINE for Blender CPython slot arity casts. This applies to CPython dispatch, not arbitrary indirect calls.",
   "engineIds": "The session preserves the compiled native CYCLES engine. VOLTER_THREE selects the explicit raster presenter; BLENDER_EEVEE and BLENDER_WORKBENCH remain presentation engines.",
-  "exportDoor": "The source-owned bpy_web_export.cc exports Principled physical inputs, normal images, eight named UV layers and evaluated corner normals, and takes graph_materials/graph_images/graph_generated (a graph-drawn shader mix reduced to the one Principled BSDF it reaches, graph images at the door revisions with every UDIM tile, orco for deformed meshes whose graph reads Generated coordinates). A frame can defer its changed meshes and pictures (defer) for the caller to pull one at a time (export_mesh, export_image), each call freeing the previous one's columns and a picture it decoded; an undo step keeps the revisions when Blender kept the depsgraph (session_undo); Blender's CPU subdivision descriptor is released once a mesh is read; the memory door reports malloc in-use and free. Datablock revisions are keyed by session_uid. writefile.cc writes one copy of the document per save in the browser build. CPU evaluators adopt stencil tables without cloning; browser subdivision descriptors are released immediately after CPU tessellation/deformation. Native evaluated corner triangles accompany corner normals. Consumed local conversion stencils are released before later UV channels are constructed. Caller-thread file-read, evaluated-object and subdivision checkpoints provide backpressure for resumable startup. Shared geometry revisions advance once per frame. Existing synchronous export remains available. Optional instance_sources exports stable evaluated collection and particle source meshes, including excluded library meshes and converted curves. Frame-local instance_geometry tokens verify Python placement metadata against the exported geometry and are consumed before presentation. Geometry resource identity preserves implicit input storage only for unmodified geometry and separates evaluated modifier/deformation outputs. Object and mesh resource keys have independent namespaces. Scoped begin_render_export/end_render_export reads the render engine depsgraph and isolates viewport revision, undo, deferred resource and image watcher state. Geometry resource identity preserves implicit input storage only for unmodified geometry and separates evaluated modifier/deformation outputs. Object and mesh resource keys have independent namespaces.",
+  "exportDoor": "The source-owned bpy_web_export.cc exports Principled physical inputs, normal images, eight named UV layers and evaluated corner normals, and takes graph_materials/graph_images/graph_generated (a graph-drawn shader mix reduced to the one Principled BSDF it reaches, graph images at the door revisions with every UDIM tile, orco for deformed meshes whose graph reads Generated coordinates). A frame can defer its changed meshes and pictures (defer) for the caller to pull one at a time (export_mesh, export_image), each call freeing the previous one's columns and a picture it decoded; an undo step keeps the revisions when Blender kept the depsgraph (session_undo); Blender's CPU subdivision descriptor is released once a mesh is read; the memory door reports malloc in-use and free. Datablock revisions are keyed by session_uid. writefile.cc writes one copy of the document per save in the browser build. CPU evaluators adopt stencil tables without cloning; browser subdivision descriptors are released immediately after CPU tessellation/deformation. Native evaluated corner triangles accompany corner normals. Consumed local conversion stencils are released before later UV channels are constructed. Caller-thread file-read, evaluated-object and subdivision checkpoints provide backpressure for resumable startup. Shared geometry revisions advance once per frame. Existing synchronous export remains available. Optional instance_sources exports stable evaluated collection and particle source meshes, including excluded library meshes and converted curves. Frame-local instance_geometry tokens verify Python placement metadata against the exported geometry and are consumed before presentation. Geometry resource identity preserves implicit input storage only for unmodified geometry and separates evaluated modifier/deformation outputs. Object and mesh resource keys have independent namespaces. Scoped begin_render_export/end_render_export reads the render engine depsgraph and isolates viewport revision, undo, deferred resource and image watcher state. Geometry resource identity preserves implicit input storage only for unmodified geometry and separates evaluated modifier/deformation outputs. Object and mesh resource keys have independent namespaces. A frame ships each armature-deformed mesh's skin with its geometry (write_skin: four joints and weights per drawn vertex by the armature's deform bones, keyed by skin_digest so it is re-sent only when the binding changes), every action in the file with its revision (actions), and each armature's assigned action.",
   "preloadedPayload": "releasePreloadedFileData releases the JS preload buffer after session ready. The measured working payload exclusions are retained."
 }