@volter/blender-engine 0.1.8 → 0.1.10

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

@@ -0,0 +1,115 @@
+/**
+ * BLENDER'S SOLID SHADING, as Blender computes it: `get_world_lighting` from
+ * `draw/engines/workbench/shaders/workbench_world_light_lib.glsl`, transcribed line for line,
+ * over the four studio lights of the factory `Default` (`SOLID_LIGHTS`, read back from Blender
+ * 5.2's preferences with their specular colours) and no ambient (`light_ambient` is zero).
+ *
+ * Per light: a wrapped diffuse term, `(N·L + wrap) / (1 + wrap)²`; a normalized Blinn specular
+ * whose gloss the wrap softens, blended toward a wrapped "environment" term by `wrap²`; a
+ * Fresnel lift of the specular colour (`brdf_approx`); and energy conservation that takes the
+ * specular's grey level off the diffuse. The surface is the material's VIEWPORT DISPLAY
+ * (`Material.diffuse_color`, `roughness`, `metallic`), which is what Solid's MATERIAL colour type
+ * reads — never its node graph.
+ *
+ * WHY A FUNCTION AND NOT A LIGHT RIG: three's lambert and BRDF cannot express the wrap, the
+ * coupled specular or the per-light specular colour, so the four lights plus one fitted gain
+ * could match the default view's three faces only by absorbing the difference, and missed a
+ * face square to the view by 18 levels (143 against Blender's 161). This function, evaluated
+ * offline for that face, gives 161.
+ *
+ * Built on `MeshLambertMaterial` so skinning, morphs and the view-space normal come with it;
+ * only the final colour is replaced. Blender uses a fast reciprocal (`fast_rcp`); this uses the
+ * exact one.
+ */
+import * as THREE from 'three';
+import { SOLID_LIGHTS } from './blender-runtime-lighting';
+
+/** What Blender's Solid reads off a material. */
+export interface ViewportDisplay {
+  readonly color: readonly [number, number, number, number];
+  readonly roughness: number;
+  readonly metallic: number;
+}
+
+/** For a surface with no material: the factory cube's material's display, read back from Blender
+ *  5.2 (grey 0.8, roughness 0.5, metallic 0). Blender's own default surface was not measured. */
+export const DEFAULT_VIEWPORT_DISPLAY: ViewportDisplay = { color: [0.8, 0.8, 0.8, 1], roughness: 0.5, metallic: 0 };
+
+const WORKBENCH_GLSL = /* glsl */ `
+uniform vec3 wbDir[4];
+uniform vec3 wbDiffuse[4];
+uniform vec3 wbSpecular[4];
+uniform vec4 wbWrap;
+uniform float wbRoughness;
+uniform float wbMetallic;
+
+vec4 wbWrapped(vec4 NL, vec4 w) {
+  vec4 w1 = w + 1.0;
+  return clamp((NL + w) / (w1 * w1), 0.0, 1.0);
+}
+
+vec3 volterWorkbenchLighting(vec3 baseColor, vec3 N, vec3 I) {
+  vec3 diffuseColor = mix(baseColor, vec3(0.0), wbMetallic);
+  vec3 specularColor = mix(vec3(0.05), baseColor, wbMetallic);
+  vec3 R = -reflect(I, N);
+  vec4 wrapNL = vec4(dot(wbDir[0], R), dot(wbDir[1], R), dot(wbDir[2], R), dot(wbDir[3], R));
+  vec4 specAngle = clamp(vec4(
+    dot(normalize(wbDir[0] + I), N), dot(normalize(wbDir[1] + I), N),
+    dot(normalize(wbDir[2] + I), N), dot(normalize(wbDir[3] + I), N)), 0.0, 1.0);
+  vec4 specNL = clamp(vec4(dot(wbDir[0], N), dot(wbDir[1], N), dot(wbDir[2], N), dot(wbDir[3], N)), 0.0, 1.0);
+  vec4 gloss = vec4(1.0 - wbRoughness) * (1.0 - wbWrap);
+  vec4 shininess = exp2(10.0 * gloss + 1.0);
+  vec4 specLight = pow(specAngle, shininess) * specNL * (shininess * 0.125 + 1.0);
+  vec4 envW = mix(wbWrap, vec4(1.0), wbRoughness);
+  vec4 specEnv = wbWrapped(wrapNL, envW);
+  specLight = mix(specLight, specEnv, wbWrap * wbWrap);
+  vec3 specularLight = specLight.x * wbSpecular[0] + specLight.y * wbSpecular[1] +
+    specLight.z * wbSpecular[2] + specLight.w * wbSpecular[3];
+  float NV = clamp(dot(N, I), 0.0, 1.0);
+  float fresnel = exp2(-8.35 * NV) * (1.0 - wbRoughness);
+  specularColor = mix(specularColor, vec3(1.0), fresnel);
+  specularLight *= specularColor;
+  vec4 diffNL = vec4(dot(wbDir[0], N), dot(wbDir[1], N), dot(wbDir[2], N), dot(wbDir[3], N));
+  vec4 diffLight = wbWrapped(diffNL, wbWrap);
+  vec3 diffuseLight = diffLight.x * wbDiffuse[0] + diffLight.y * wbDiffuse[1] +
+    diffLight.z * wbDiffuse[2] + diffLight.w * wbDiffuse[3];
+  float specEnergy = dot(specularColor, vec3(0.33333));
+  diffuseLight *= diffuseColor * (1.0 - specEnergy);
+  return diffuseLight + specularLight;
+}
+`;
+
+const vec3s = (pick: (light: (typeof SOLID_LIGHTS)[number]) => readonly number[]) =>
+  SOLID_LIGHTS.map((light) => {
+    const [x = 0, y = 0, z = 0] = pick(light);
+    return new THREE.Vector3(x, y, z);
+  });
+const LIGHT_DIRECTIONS = vec3s((light) => light.direction).map((v) => v.normalize());
+const LIGHT_DIFFUSE = vec3s((light) => light.diffuse);
+const LIGHT_SPECULAR = vec3s((light) => light.specular);
+const LIGHT_WRAP = new THREE.Vector4(...SOLID_LIGHTS.map((light) => light.smooth));
+
+/** One Solid-shaded surface: Blender's function over this viewport display. */
+export function workbenchMaterial(display: ViewportDisplay, side: THREE.Side): THREE.MeshLambertMaterial {
+  const [r, g, b] = display.color;
+  const material = new THREE.MeshLambertMaterial({ side });
+  material.color.setRGB(r, g, b, THREE.LinearSRGBColorSpace);
+  material.name = 'volter:blender-solid';
+  material.onBeforeCompile = (shader) => {
+    shader.uniforms['wbDir'] = { value: LIGHT_DIRECTIONS };
+    shader.uniforms['wbDiffuse'] = { value: LIGHT_DIFFUSE };
+    shader.uniforms['wbSpecular'] = { value: LIGHT_SPECULAR };
+    shader.uniforms['wbWrap'] = { value: LIGHT_WRAP };
+    shader.uniforms['wbRoughness'] = { value: display.roughness };
+    shader.uniforms['wbMetallic'] = { value: display.metallic };
+    shader.fragmentShader = shader.fragmentShader
+      .replace('void main() {', `${WORKBENCH_GLSL}\nvoid main() {`)
+      .replace(
+        '#include <opaque_fragment>',
+        // The view direction toward the eye, as Blender's `I`: constant in an orthographic view.
+        'outgoingLight = volterWorkbenchLighting(diffuseColor.rgb, normal, isOrthographic ? vec3(0.0, 0.0, 1.0) : normalize(vViewPosition));\n#include <opaque_fragment>',
+      );
+  };
+  material.customProgramCacheKey = () => 'volter-blender-workbench';
+  return material;
+}

package/browser/three/release.ts

@@ -9,7 +9,7 @@
  * to the Blender it started:
  *
  *     const { createPresenter, attachPresenter } = await import(url);
- *     const detach = attachPresenter(filesystem, "/tmp/vgai-presenter", createPresenter());
+ *     const detach = attachPresenter(filesystem, "/tmp/volter-presenter", createPresenter());
  *
  * NO HOST BUNDLES THIS. The module is GPL because it is part of the Blender
  * release; a host loads it the way it loads the wasm -- by URL, under a pinned

package/browser/{vgai_three.py → volter_three.py}

@@ -3,7 +3,7 @@
 THE RENDER OVERRIDE IS NOT THE EDITOR'S. `session.py` is the editor tab's
 long-lived session and carries this same override for the session it owns;
 this file is the other delivery of it -- a Blender STARTUP module that ships in
-the pack's resource tree (`scripts/startup/vgai_three.py`), so a bare
+the pack's resource tree (`scripts/startup/volter_three.py`), so a bare
 `blender -b ... -a` on ANY surface renders with three.js too. Blender imports
 every module in `scripts/startup` and calls its `register()`.
 
@@ -56,14 +56,14 @@ import bpy
 # `{offset, length, dtype, count, stride}` in a small JSON frame.
 import _blender_web
 
-ROOT = os.environ.get("VGAI_PRESENTER_ROOT", "/tmp/vgai-presenter")
+ROOT = os.environ.get("VOLTER_PRESENTER_ROOT", "/tmp/volter-presenter")
 ASK = os.path.join(ROOT, "ask")
 REPLY = os.path.join(ROOT, "reply")
 # WHERE THE EXPORT DOOR LEAVES THE ARENA. The host cannot reach this program's
 # linear memory, so the arena crosses as a file -- the door writes it when
 # `buffer_path` is set, and the host reads it beside the ask.
 EXPORT_BUFFER_PATH = os.environ.get(
-    "VGAI_EXPORT_BUFFER_PATH", os.path.join(ROOT, "arena.bin")
+    "VOLTER_EXPORT_BUFFER_PATH", os.path.join(ROOT, "arena.bin")
 )
 # THE FRAME'S IDENTITY IS A PAIR, `(session, revision)`, and the presenter
 # refuses a revision that went backwards under a name it already holds. One
@@ -78,7 +78,7 @@ EXPORT_BUFFER_PATH = os.environ.get(
 # 2026-09-20 in the substrate tab; the first run on a freshly loaded page
 # always worked, which is what hid it). The start time is what makes the name
 # this process's own.
-SESSION = "vgai-three:%d-%d" % (os.getpid(), time.time_ns())
+SESSION = "volter-three:%d-%d" % (os.getpid(), time.time_ns())
 HELLO_TIMEOUT_SECONDS = 2.0
 POLL_SECONDS = 0.002
 
@@ -115,14 +115,14 @@ def warn(what):
         return
     _WARNED.add(what)
     _WARNINGS.append(what)
-    _say("@@VGAI-WARN " + what)
+    _say("@@VOLTER-WARN " + what)
 
 
 def _drop(path):
     try:
         os.unlink(path)
     except OSError as error:
-        _say("@@VGAI-WARN vgai_three could not remove its own %s: %r" % (path, error))
+        _say("@@VOLTER-WARN volter_three could not remove its own %s: %r" % (path, error))
 
 
 def _prepare_directories():
@@ -130,7 +130,7 @@ def _prepare_directories():
         try:
             os.makedirs(directory, exist_ok=True)
         except OSError as error:
-            _say("@@VGAI-ERROR vgai_three cannot create %s: %r" % (directory, error))
+            _say("@@VOLTER-ERROR volter_three cannot create %s: %r" % (directory, error))
         try:
             os.chmod(directory, 0o777)
         except OSError:
@@ -371,7 +371,7 @@ def _assert_photographed_from(reported, position, target, up):
             )
 
 
-class VgaiRenderEngine(bpy.types.RenderEngine):
+class VolterRenderEngine(bpy.types.RenderEngine):
     """The scene's renderer, so `write_still`, `save_render` and Render Result
     behave as Blender's own.
 
@@ -381,7 +381,7 @@ class VgaiRenderEngine(bpy.types.RenderEngine):
     starts a path trace nobody asked for.
     """
 
-    bl_idname = "VGAI_THREE"
+    bl_idname = "VOLTER_THREE"
     bl_label = "three.js"
     bl_use_preview = False
 
@@ -471,7 +471,7 @@ def _register_engine():
         ("BLENDER_WORKBENCH", "Workbench"),
     ):
         existing = _engine_class(identifier)
-        if existing is not None and issubclass(existing, VgaiRenderEngine):
+        if existing is not None and issubclass(existing, VolterRenderEngine):
             made.append(identifier)
             continue
         if existing is not None:
@@ -482,8 +482,8 @@ def _register_engine():
             else:
                 _release_from_owning_addon(existing)
         engine = type(
-            "Vgai" + identifier.title().replace("_", ""),
-            (VgaiRenderEngine,),
+            "Volter" + identifier.title().replace("_", ""),
+            (VolterRenderEngine,),
             {"bl_idname": identifier, "bl_label": label, "bl_use_preview": False},
         )
         try:
@@ -496,17 +496,17 @@ def _register_engine():
             # keeps `BLENDER_EEVEE` and `BLENDER_WORKBENCH`: a fact about the
             # build, not a warning on every boot.
             unavailable.append(identifier)
-    # `VGAI_THREE` is the engine under its own name, registered ONCE: this runs
+    # `VOLTER_THREE` is the engine under its own name, registered ONCE: this runs
     # again after every file load (the ids have to be retaken), and Blender
     # refuses a class it already holds -- which is not a capability anyone
     # lost, so it is not a warning.
-    if _engine_class(VgaiRenderEngine.bl_idname) is None:
+    if _engine_class(VolterRenderEngine.bl_idname) is None:
         try:
-            bpy.utils.register_class(VgaiRenderEngine)
+            bpy.utils.register_class(VolterRenderEngine)
         except Exception as error:  # noqa: BLE001
             warn("could not register the three.js engine: %s" % error)
-    if _engine_class(VgaiRenderEngine.bl_idname) is not None:
-        made.append(VgaiRenderEngine.bl_idname)
+    if _engine_class(VolterRenderEngine.bl_idname) is not None:
+        made.append(VolterRenderEngine.bl_idname)
     return made, unavailable
 
 
@@ -518,7 +518,7 @@ def _adopt():
     _register_engine()
     for scene in bpy.data.scenes:
         try:
-            scene.render.engine = "VGAI_THREE"
+            scene.render.engine = "VOLTER_THREE"
         except (TypeError, AttributeError) as error:
             warn("scene %s kept its own render engine: %s" % (scene.name, error))
 
@@ -536,7 +536,7 @@ def register():
     _prepare_directories()
     if ask({"op": "hello"}, timeout=HELLO_TIMEOUT_SECONDS) is None:
         _say(
-            "vgai: rendering with Cycles — no presenter answered at %s within 2 s"
+            "volter: rendering with Cycles — no presenter answered at %s within 2 s"
             % ROOT
         )
         return

package/browser/worker.ts

@@ -27,7 +27,7 @@
  * picks up BETWEEN calls, never mid-call), and carries the bytes to the
  * project through `/__editor/blender-document` BEFORE acknowledging the edit.
  *
- * WHY THE CARRY IS NOT THE MIRROR'S JOB (`vgai blender-mcp`, class Mirror):
+ * WHY THE CARRY IS NOT THE MIRROR'S JOB (`volter blender-mcp`, class Mirror):
  * the Mirror is pull-based and runs only after an `execute_blender_code`, so
  * a document saved after the LAST call of a modeling session
  * would never leave the worker — which is exactly the state this closes
@@ -172,7 +172,7 @@ async function saveDocument(): Promise<void> {
     throw new Error(`The Blender document ${relative} was not written to the project: ${describeThrown(error)}`);
   }
   setDocumentDirty(false);
-  log('log', `@@VGAI-DOCUMENT ${JSON.stringify({ path: relative, bytes: bytes.length })}`);
+  log('log', `@@VOLTER-DOCUMENT ${JSON.stringify({ path: relative, bytes: bytes.length })}`);
 }
 
 async function startBlender(project: string, document?: string): Promise<unknown> {
@@ -286,7 +286,7 @@ async function start(project: string, document?: string): Promise<unknown> {
     throw new Error(
       'Headless Blender is not served by this editor, so there is no modeling engine: ' +
         `${served.missing.join('; ')}. The engine is Blender compiled to WebAssembly ` +
-        '(packages/blender-engine/wasm, or the directory VGAI_BLENDER_WASM_DIR names); nothing stands in for it.',
+        '(packages/blender-engine/wasm, or the directory VOLTER_BLENDER_WASM_DIR names); nothing stands in for it.',
     );
   projectRoot = project;
   return startBlender(project, document);

package/package.json

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