@volter/blender-engine 0.1.132 → 0.1.134

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

@@ -8,6 +8,7 @@ import { z } from 'zod';
 import { onPresenterChange, presenterChanged } from './blender-presenter-change';
 import { bytesFromBase64 } from './blender-base64';
 import { ArmatureOverlay, armatureSchema } 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),
@@ -147,6 +180,9 @@ const drawArraysSchema = z
         })
         .strict(),
     ),
+    /** 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();
@@ -222,6 +258,7 @@ const columnAttributeSchema = z
   .strict();
 const exportedMeshSchema = z
   .object({
+    skin: frameSkinSchema.optional(),
     columns: columnsSchema,
     attributes: z.array(columnAttributeSchema),
     activeUv: z.string().nullable(),
@@ -565,6 +602,11 @@ 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(),
     /** The active object's active vertex group, per vertex
      *  (`blender-runtime-weights.ts`); null when nothing is painted. */
     weights: weightsSchema.nullable().default(null),
@@ -661,8 +703,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);
@@ -1059,6 +1117,35 @@ 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;
+    active: string | null;
+    actions: Readonly<Record<string, number>>;
+    armatures: Readonly<Record<string, { action: string | null }>>;
+    skinArmature(object: string): string | null;
+  } {
+    const frame = this.frame;
+    return {
+      frame: frame?.frame ?? 0,
+      clock: frame?.clock ?? null,
+      active: frame?.active ?? null,
+      actions: frame?.actions ?? {},
+      armatures: Object.fromEntries(Object.entries(frame?.armatures ?? {}).map(([name, armature]) => [name, { action: armature.action ?? null }])),
+      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);
@@ -1669,9 +1756,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));
@@ -1789,7 +1878,7 @@ export class BlenderRuntimeView {
         prepared.set(id, {
           signature,
           geometry: exported
-            ? geometryFromDrawArrays(
+            ? withFrameSkin(geometryFromDrawArrays(
                 drawArraysFromColumns(
                   {
                     ...data.columns,
@@ -1799,9 +1888,9 @@ export class BlenderRuntimeView {
                   },
                   signature,
                 ),
-              )
+              ), data.skin)
             : drawn
-              ? geometryFromDrawArrays(data)
+              ? withDrawnSkin(geometryFromDrawArrays(data), data.skin)
               : drawRuntimeGeometry(data),
         });
       }
@@ -2178,6 +2267,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
@@ -2248,13 +2357,14 @@ export class BlenderRuntimeView {
   /** Everything this view holds, as ONE self-contained frame another view can be built from:
    *  every mesh's resident geometry and every resident image, with no reference to what a
    *  receiver already holds. */
-  private fullFrame(): Frame {
+  private fullFrame(options: { sourceVertices?: boolean } = {}): Frame {
     const source = this.frame;
     if (!source) throw new Error('Blender capture requires a presented frame');
     // 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);
@@ -2290,6 +2400,20 @@ export class BlenderRuntimeView {
           count: group.count,
           materialIndex: group.materialIndex ?? 0,
         })),
+        // A COPY THAT PLAYS keeps the draw's vertex map: Play binds skins over it (a Blender
+        // vertex's weights expand onto its drawn vertices through it), where a render snapshot
+        // needs none.
+        ...(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)
@@ -2368,7 +2492,7 @@ export class BlenderRuntimeView {
    */
   detach(): { readonly view: BlenderRuntimeView; dispose(): void } {
     const detached = new BlenderRuntimeView();
-    if (this.frame) detached.applyFrame(this.fullFrame());
+    if (this.frame) detached.applyFrame(this.fullFrame({ sourceVertices: true }));
     let disposed = false;
     return {
       view: detached,
@@ -2499,6 +2623,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,16 +796,12 @@ 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',
         ...(request.object === undefined ? {} : { object: request.object }),
         ...(request.bake === undefined ? {} : { bake: request.bake }),
+        ...(request.action === undefined ? {} : { action: request.action }),
       });
     case 'outliner-set':
       return ask({

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/blender-engine",
   "author": "Volter AI, Inc.",
   "license": "GPL-3.0-or-later",
-  "version": "0.1.132",
+  "version": "0.1.134",
   "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) and each armature's assigned action (actions).",
   "preloadedPayload": "releasePreloadedFileData releases the JS preload buffer after session ready. The measured working payload exclusions are retained."
 }