@volter/blender-engine 0.1.64 → 0.1.66

package/browser/runtime.ts

@@ -118,6 +118,9 @@ export interface BlenderCallMetrics {
   readonly maxCallMs: number | null;
   /** Operation and load boundary owning the longest request; no payload data. */
   readonly maxCallLabel?: string | null;
+  /** Current cooperative phase and count of settled wire requests; sampled, not pushed per unit. */
+  readonly currentPhase?: string | null;
+  readonly completedCalls?: number;
   /** Calls whose duration passed 5s, counting outstanding ones already past it. */
   readonly callsOver5s: number;
   /** The same at 30s — a call this side of it is slow, past it is a wedge. */
@@ -168,7 +171,7 @@ export class BlenderRuntime {
   readonly #callLabels = new Map<number, string>();
   #loadBoundary = "engine-start";
   #maxCompletedLabel: string | null = null;
-  readonly #callWork = new Map<number, () => void>();
+  readonly #operationWork = new Set<() => void>();
   #lastCallMs: number | null = null;
   #maxCompletedMs = 0;
   #completedOver5s = 0;
@@ -499,6 +502,7 @@ export class BlenderRuntime {
     for (const id of [...this.#pending.keys()]) this.#settled(id);
     for (const pending of this.#pending.values()) pending.reject(error);
     this.#pending.clear();
+    for (const end of this.#operationWork) end();
   }
 
   /**
@@ -534,6 +538,8 @@ export class BlenderRuntime {
       // different claim from "no call has happened yet".
       maxCallMs: this.#lastCallMs === null && oldest === null ? null : Math.round(max),
       maxCallLabel: maxLabel,
+      currentPhase: this.#acceptedRequests ? this.#loadBoundary : null,
+      completedCalls: this.#completedCalls,
       callsOver5s: over5,
       callsOver30s: over30,
       lastCallWindow: this.#lastCallWindow,
@@ -543,13 +549,12 @@ export class BlenderRuntime {
 
   /** Close a call's window, whether it answered, threw, or was terminated. */
   #settled(id: number): void {
-    this.#callWork.get(id)?.();
-    this.#callWork.delete(id);
     const started = this.#callStarts.get(id);
     if (started === undefined) return;
     this.#callStarts.delete(id);
     const label = this.#callLabels.get(id) ?? null;
     this.#callLabels.delete(id);
+    this.#completedCalls++;
     const elapsed = performance.now() - started;
     this.#lastCallMs = elapsed;
     if (elapsed > this.#maxCompletedMs) { this.#maxCompletedMs = elapsed; this.#maxCompletedLabel = label; }
@@ -559,14 +564,19 @@ export class BlenderRuntime {
       this.#lastCallWindow = { start: started, end: started + elapsed };
   }
 
+  #completedCalls = 0;
   #acceptedRequests = 0;
   #requestTail: Promise<void> = Promise.resolve();
   #request(request: Request, shutdown = false): Promise<unknown> {
     if (this.#terminated || (this.#stopping && !shutdown))
       return Promise.reject(new Error('The Blender session is stopping or terminated'));
     const began = performance.now();
+    let endWork = () => {};
     this.#acceptedRequests++;
     const answer = this.#requestTail.then(async () => {
+      const finishWork = this.#work(`running worker ${request.op}`);
+      endWork = () => { if (this.#operationWork.delete(endWork)) finishWork(); };
+      this.#operationWork.add(endWork);
       this.#loadBoundary = request.op;
       let result = await this.#wireRequest(request) as PullResult<unknown>;
       while (result?.load === 'continue') {
@@ -576,6 +586,7 @@ export class BlenderRuntime {
       return result?.load === 'done' ? result.value : result;
     }).finally(() => {
       this.#acceptedRequests--;
+      endWork();
       const totalMs = Math.round(performance.now() - began);
       try { if (totalMs >= 1000) this.#options.log?.('log', `@@VOLTER-WORK op=${request.op} totalMs=${totalMs}`); } catch { /* diagnostics cannot poison the queue */ }
     });
@@ -592,7 +603,6 @@ export class BlenderRuntime {
       this.#callStarts.set(id, started);
       this.#callLabels.set(id, request.op === "load-next" ? `load-next after ${this.#loadBoundary}` : request.op);
       this.#lastCallWindow = { start: started, end: null };
-      this.#callWork.set(id, this.#work(`waiting for worker ${request.op}`));
       try {
         this.#worker.postMessage({ ...request, id });
       } catch (error) {

package/browser/three/blender-graph-material.ts

@@ -322,8 +322,12 @@ ${compiled.uvs.map(n => `varying vec2 ${uvVarying(n)};`).join('\n')}`;
     '#include <project_vertex>',
     `vBlenderObjectPosition = transformed;
 vBlenderObjectNormal = objectNormal;
-vBlenderWorldPosition = (modelMatrix * vec4(transformed, 1.0)).xyz;
-vBlenderWorldNormal = normalize(transpose(inverse(mat3(modelMatrix))) * objectNormal);
+mat4 blenderWorldMatrix = modelMatrix;
+#ifdef USE_INSTANCING
+blenderWorldMatrix = modelMatrix * instanceMatrix;
+#endif
+vBlenderWorldPosition = (blenderWorldMatrix * vec4(transformed, 1.0)).xyz;
+vBlenderWorldNormal = normalize(transpose(inverse(mat3(blenderWorldMatrix))) * objectNormal);
 vBlenderOrco = blenderOrco;
 ${compiled.attributes.map(n => `${attributeVarying(n)} = ${graphAttributeName(n)};`).join('\n')}
 ${compiled.uvs.map(n => `${uvVarying(n)} = ${attribute(channels[n] ?? 0)};`).join('\n')}

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

@@ -0,0 +1,163 @@
+import * as THREE from 'three';
+
+// Small spatial batches retain frustum rejection without duplicating geometry.
+const BATCH_SIZE = 64;
+type Member = { mesh: THREE.Mesh; layers: number };
+type Batch = { draw: THREE.InstancedMesh; members: Member[] };
+
+function sameMaterials(a: THREE.Material | THREE.Material[], b: THREE.Material | THREE.Material[]): boolean {
+  return Array.isArray(a) && Array.isArray(b)
+    ? a.length === b.length && a.every((material, i) => material === b[i])
+    : a === b;
+}
+
+function shown(object: THREE.Object3D): boolean {
+  for (let node: THREE.Object3D | null = object; node; node = node.parent)
+    if (!node.visible) return false;
+  return true;
+}
+
+/** Three's instance normal transform supports positive, orthogonal scale axes.
+ * Mirrored, singular and sheared placements keep the ordinary Mesh draw. */
+function supported(matrix: THREE.Matrix4): boolean {
+  if (matrix.determinant() <= 0) return false;
+  const e = matrix.elements;
+  const x = Math.hypot(e[0]!, e[1]!, e[2]!);
+  const y = Math.hypot(e[4]!, e[5]!, e[6]!);
+  const z = Math.hypot(e[8]!, e[9]!, e[10]!);
+  const dot = (a: number, b: number) => e[a]! * e[b]! + e[a + 1]! * e[b + 1]! + e[a + 2]! * e[b + 2]!;
+  return Number.isFinite(x + y + z) && Math.min(x, y, z) > 0 &&
+    Math.abs(dot(0, 4)) <= 1e-7 * x * y &&
+    Math.abs(dot(0, 8)) <= 1e-7 * x * z &&
+    Math.abs(dot(4, 8)) <= 1e-7 * y * z;
+}
+
+/** Disposable draws only. The original objects, geometry, material slots and
+ * parent graph remain the authority for hierarchy, bounds, editing and picking.
+ * Layer zero-mask suppresses their ordinary draw; batch raycasts return those
+ * same original objects. Selection passes can still temporarily add their mask
+ * layer to an original. No vertices or authored data are reduced or replaced. */
+export class BlenderRuntimeInstances {
+  private readonly batches: Batch[] = [];
+  private readonly inverse = new THREE.Matrix4();
+  private readonly matrix = new THREE.Matrix4();
+  private readonly box = new THREE.Box3();
+
+  constructor(private readonly root: THREE.Group) {}
+
+  rebuild(objects: Iterable<THREE.Object3D>, enabled: boolean): void {
+    this.clear();
+    if (!enabled) return;
+    const groups = new Map<string, THREE.Mesh[]>();
+    this.inverse.copy(this.root.matrixWorld).invert();
+    for (const object of objects) {
+      const mesh = object as THREE.Mesh;
+      if (!mesh.isMesh || (mesh as THREE.SkinnedMesh).isSkinnedMesh ||
+          (mesh as THREE.InstancedMesh).isInstancedMesh || mesh.morphTargetInfluences ||
+          mesh.layers.mask !== 1) continue;
+      // WebGL2 guarantees sixteen vertex attributes; the instance matrix uses
+      // four. Keep richly attributed meshes on the ordinary path rather than
+      // dropping UV/colour channels or risking a refused shader.
+      if (Object.values(mesh.geometry.attributes).reduce((count, attribute) => count + Math.ceil(attribute.itemSize / 4), 0) > 12) continue;
+      const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+      if (materials.some(m => m.transparent || (m as THREE.MeshPhysicalMaterial).transmission > 0 ||
+          (m as THREE.ShaderMaterial).isShaderMaterial)) continue;
+      this.matrix.multiplyMatrices(this.inverse, mesh.matrixWorld);
+      if (!supported(this.matrix)) continue;
+      const key = `${mesh.geometry.id}:${Array.isArray(mesh.material) ? 'slots' : 'single'}:` +
+        materials.map(m => m.uuid).join(',') + `:${mesh.renderOrder}`;
+      const group = groups.get(key);
+      if (group) group.push(mesh);
+      else groups.set(key, [mesh]);
+    }
+    for (const group of groups.values()) {
+      if (group.length < 2) continue;
+      // Partition along the widest centre axis, recursively. Adjacent authored
+      // names need not be adjacent in space (linked trees span the whole Bridge).
+      const partition = (members: THREE.Mesh[]): void => {
+        if (members.length > BATCH_SIZE) {
+          this.box.makeEmpty();
+          for (const mesh of members) this.box.expandByPoint(new THREE.Vector3().setFromMatrixPosition(mesh.matrixWorld));
+          const size = this.box.getSize(new THREE.Vector3());
+          const axis = size.x >= size.y && size.x >= size.z ? 12 : size.y >= size.z ? 13 : 14;
+          members.sort((a, b) => a.matrixWorld.elements[axis]! - b.matrixWorld.elements[axis]!);
+          const middle = Math.floor(members.length / 2);
+          partition(members.slice(0, middle));
+          partition(members.slice(middle));
+          return;
+        }
+        if (members.length < 2) return;
+        const first = members[0]!;
+        const draw = new THREE.InstancedMesh(first.geometry, first.material, members.length);
+        draw.name = 'Blender repeated geometry';
+        draw.userData['engineInternal'] = true;
+        draw.matrixAutoUpdate = false;
+        draw.renderOrder = first.renderOrder;
+        draw.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+        const batch: Batch = {draw, members: members.map(mesh => ({mesh, layers: mesh.layers.mask}))};
+        // Return the canonical mesh, not the internal batch or an unstable slot.
+        draw.raycast = (raycaster, hits) => {
+          for (const {mesh} of batch.members)
+            if (mesh.layers.mask === 0 && shown(mesh)) mesh.raycast(raycaster, hits);
+        };
+        this.root.add(draw);
+        draw.updateMatrixWorld(true);
+        this.batches.push(batch);
+      };
+      partition(group);
+    }
+    this.sync();
+  }
+
+  /** Called after the root updates its descendants, before Three builds its
+   * render list/uploads attributes. Live gizmo transforms therefore appear on
+   * the very next draw, including parent transforms and visibility changes. */
+  sync(): void {
+    if (!this.batches.length) return;
+    this.inverse.copy(this.root.matrixWorld).invert();
+    for (const {draw, members} of this.batches) {
+      let count = 0;
+      let changed = false;
+      for (const member of members) {
+        const {mesh} = member;
+        this.matrix.multiplyMatrices(this.inverse, mesh.matrixWorld);
+        // A drag can introduce negative scale/shear, or a skin can replace a
+        // mesh between frames. Fall back immediately without touching its data.
+        const compatible = mesh.parent !== null && mesh.geometry === draw.geometry &&
+          sameMaterials(mesh.material, draw.material) && supported(this.matrix);
+        if (!compatible) {
+          mesh.layers.mask |= member.layers;
+          continue;
+        }
+        mesh.layers.mask &= ~member.layers;
+        if (!shown(mesh)) continue;
+        const offset = count * 16;
+        if (this.matrix.elements.some((value, i) => Math.fround(value) !== draw.instanceMatrix.array[offset + i])) {
+          draw.setMatrixAt(count, this.matrix);
+          changed = true;
+        }
+        count++;
+      }
+      changed ||= draw.count !== count || draw.boundingSphere === null;
+      draw.count = count;
+      if (changed) {
+        draw.instanceMatrix.needsUpdate = true;
+        draw.computeBoundingBox();
+        draw.computeBoundingSphere();
+      }
+    }
+  }
+
+  clear(): void {
+    for (const {draw, members} of this.batches) {
+      for (const {mesh, layers} of members) mesh.layers.mask |= layers;
+      draw.removeFromParent();
+      draw.dispose(); // releases instance attributes, never shared geometry/material
+    }
+    this.batches.length = 0;
+  }
+
+  inspect() {
+    return {batches: this.batches.length, instances: this.batches.reduce((count, {draw}) => count + draw.count, 0)};
+  }
+}

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

@@ -42,6 +42,7 @@ import {
   panCameraView,
 } from './blender-runtime-camera-view';
 import { DEFAULT_VIEWPORT_DISPLAY, workbenchMaterial } from './blender-workbench-material';
+import { BlenderRuntimeInstances } from './blender-runtime-instances';
 
 /** A saved `View3DShading.type` as the stage's draw mode: Material Preview is `preview`. */
 const SAVED_SHADING = {
@@ -640,6 +641,7 @@ export interface PhotographRecord {
 
 export class BlenderRuntimeView {
   readonly root = new THREE.Group();
+  private readonly instances = new BlenderRuntimeInstances(this.root);
   private readonly objects = new Map<string, THREE.Object3D>();
   private readonly meshes = new Map<
     string,
@@ -1034,11 +1036,17 @@ export class BlenderRuntimeView {
         for (const child of children) next.add(child);
         parent?.add(next);
         this.objects.set(id, next);
+        this.instances.rebuild(this.objects.values(), !this.rendered);
         return;
       }
   }
 
   constructor() {
+    const updateMatrixWorld = this.root.updateMatrixWorld.bind(this.root);
+    this.root.updateMatrixWorld = (force?: boolean) => {
+      updateMatrixWorld(force);
+      this.instances.sync();
+    };
     this.root.name = 'Model';
     // BLENDER IS Z-UP, THREE IS Y-UP: (x, y, z) -> (x, z, -y). Written as the
     // matrix rather than `rotation.x = -Math.PI / 2`, because that Euler is a
@@ -1212,6 +1220,7 @@ export class BlenderRuntimeView {
       material.dispose();
       this.workbenchMaterials.delete(key);
     }
+    this.instances.rebuild(this.objects.values(), !this.rendered);
   }
 
   private workbenchFor(id: string | null, side: THREE.Side, used: Set<string>): THREE.Material {
@@ -2007,6 +2016,7 @@ export class BlenderRuntimeView {
       active: this.frame?.active,
       mode: this.frame?.mode,
       geometryBuilds: this.geometryBuilds,
+      instancing: this.instances.inspect(),
       objects: [...this.objects].map(([id, object]) => ({
         id,
         name: object.name,
@@ -2224,6 +2234,7 @@ export class BlenderRuntimeView {
   }
 
   private clear() {
+    this.instances.clear();
     for (const entry of this.staged?.meshes.values() ?? []) entry.geometry.dispose();
     this.staged = null;
     for (const light of this.lights.values()) {

package/package.json

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