@volter/blender-engine 0.1.129 → 0.1.131

package/browser/three/blender-sky.ts

@@ -15,7 +15,7 @@
  * `Linear CIE-XYZ D65`.
  */
 import * as THREE from 'three';
-import {precomputeSingleScatteringSky} from './blender-single-scattering-sky';
+import {precomputeSingleScatteringSky, precomputeSingleScatteringSun} from './blender-single-scattering-sky';
 
 const M_PI_2_F = 1.5707963267948966;
 const M_2PI_F = 6.2831853071795864;
@@ -104,6 +104,9 @@ const aerosolDensity = (h: number): number =>
 export interface SkyParameters {
   /** Omitted in older frames, whose only supported model was multiple scattering. */
   model?: 'SINGLE_SCATTERING' | 'MULTIPLE_SCATTERING';
+  sunDisc?: boolean | undefined;
+  sunSize?: number | undefined;
+  sunIntensity?: number | undefined;
   sunElevation: number;
   sunRotation: number;
   altitude: number;
@@ -399,6 +402,14 @@ export function primeSkyTexture(p: SkyParameters, pixels: Float32Array): void {
   }
 }
 
+/** Cycles' Z-up solar direction: rotation zero points along +Y. */
+export function skySunDirection(p: Pick<SkyParameters, 'sunElevation' | 'sunRotation'>): THREE.Vector3 {
+  // sky_radiance_nishita uses spherical_to_direction(elevation - PI/2,
+  // (2PI - rotation) - PI/2), after SkyTextureNode::simplify_settings.
+  return new THREE.Vector3(Math.cos(p.sunElevation) * Math.sin(p.sunRotation),
+    Math.cos(p.sunElevation) * Math.cos(p.sunRotation), Math.sin(p.sunElevation));
+}
+
 /**
  * One Sky Texture node as a field over directions, in Blender's Z-up frame.
  *
@@ -422,6 +433,12 @@ export function skyField(p: SkyParameters): (direction: THREE.Vector3) => THREE.
     primeSkyTexture(p, pixels);
   }
   const colour = new THREE.Vector3();
+  const diameter = p.sunSize ?? 0;
+  const solar = p.model === 'SINGLE_SCATTERING' && p.sunDisc && diameter > 0
+    ? precomputeSingleScatteringSun(p, diameter) : null;
+  const sun = skySunDirection(p);
+  const earthAngle = -Math.acos(6360000 / (6360000 + Math.min(59999, Math.max(1, p.altitude))));
+  const cross = new THREE.Vector3();
   return (direction) => {
     const horizontal = Math.hypot(direction.x, direction.y);
     const dirElevation = Math.atan2(direction.z, horizontal);
@@ -456,6 +473,14 @@ export function skyField(p: SkyParameters): (direction: THREE.Vector3) => THREE.
       );
       xyz[i] = mix(top, bottom, ty);
     }
+    if (solar && dirElevation > earthAngle) {
+      const angle = Math.atan2(cross.crossVectors(direction, sun).length(), direction.dot(sun));
+      if (angle < diameter / 2) {
+        const limb = 1 - .6 * (1 - Math.sqrt(Math.max(0, 1 - (angle / (diameter / 2)) ** 2)));
+        const t = (dirElevation - p.sunElevation) / diameter + .5;
+        for (let i = 0; i < 3; i++) xyz[i]! += mix(solar[0][i]!, solar[1][i]!, t) * (p.sunIntensity ?? 1) * limb;
+      }
+    }
     return colour.set(
       XYZ_TO_RGB[0]![0]! * xyz[0]! + XYZ_TO_RGB[0]![1]! * xyz[1]! + XYZ_TO_RGB[0]![2]! * xyz[2]!,
       XYZ_TO_RGB[1]![0]! * xyz[0]! + XYZ_TO_RGB[1]![1]! * xyz[1]! + XYZ_TO_RGB[1]![2]! * xyz[2]!,

package/browser/three/blender-world-visibility.ts

@@ -0,0 +1,264 @@
+/** Directional world-light visibility. One shared depth atlas replaces repeated
+ * per-pixel triangle traversal. Geometry/placements are derived draw resources;
+ * Blender data and the visible canvas are never changed. This is finite
+ * directional quadrature, not indirect light transport. */
+import * as THREE from 'three';
+
+const SAMPLE_COUNT=16, TILES=4, TILE_SIZE=512;
+type Segment={mesh:THREE.Mesh; geometry:THREE.BufferGeometry; position:THREE.BufferAttribute|THREE.InterleavedBufferAttribute;
+ index:THREE.BufferAttribute|null; positionVersion:number; indexVersion:number; start:number; count:number;
+ offset:number; matrix:THREE.Matrix4; shown:boolean; bounds:THREE.Box3; dynamic:boolean};
+const version=(attribute:THREE.BufferAttribute|THREE.InterleavedBufferAttribute)=>
+ 'isInterleavedBufferAttribute' in attribute ? attribute.data.version : attribute.version;
+function shown(mesh:THREE.Mesh):boolean {
+ if(!mesh.castShadow || !mesh.layers.isEnabled(0))return false;
+ for(let parent:THREE.Object3D|null=mesh;parent;parent=parent.parent)if(!parent.visible)return false;
+ return true;
+}
+
+export class BlenderWorldVisibility {
+ readonly uniforms={
+  blenderWorldVisibilityEnabled:{value:false},
+  blenderWorldDepth:{value:null as THREE.Texture|null},
+  blenderWorldDynamicDepth:{value:null as THREE.Texture|null},
+  blenderWorldHasDynamicDepth:{value:false},
+  blenderWorldRadiance:{value:null as THREE.Texture|null},
+  blenderWorldDirections:{value:Array.from({length:SAMPLE_COUNT},(_,i)=>{
+   const z=1-2*(i+.5)/SAMPLE_COUNT,angle=i*2.399963229728653;
+   return new THREE.Vector3(Math.sqrt(1-z*z)*Math.cos(angle),z,Math.sqrt(1-z*z)*Math.sin(angle));
+  })},
+  blenderWorldMatrices:{value:Array.from({length:SAMPLE_COUNT},()=>new THREE.Matrix4())},
+  blenderWorldToNative:{value:new THREE.Matrix3()},
+  blenderWorldRayOffset:{value:1e-5},
+ };
+ private target:THREE.WebGLRenderTarget|null=null;
+ private dynamicTarget:THREE.WebGLRenderTarget|null=null;
+ private readonly dynamicScene=new THREE.Scene();
+ private readonly dynamicMeshes=new Map<THREE.Mesh,THREE.Mesh>();
+ private readonly scene=new THREE.Scene();
+ private readonly geometry=new THREE.BufferGeometry();
+ private readonly material=new THREE.MeshDepthMaterial({side:THREE.DoubleSide});
+ private readonly mesh=new THREE.Mesh(this.geometry,this.material);
+ private readonly camera=new THREE.OrthographicCamera();
+ private segments:Segment[]=[];
+ private dirty=true;
+ private staticDirty=true;
+ private dynamicDirty=false;
+ private fittedBounds=new THREE.Box3();
+ private passes=0;
+ private staticPasses=0;
+ private dynamicPasses=0;
+ constructor(){this.mesh.frustumCulled=false;this.scene.add(this.mesh);}
+
+ sync(objects:Iterable<THREE.Object3D>,world:THREE.Texture|null,root:THREE.Object3D,enabled:boolean):void {
+  this.uniforms.blenderWorldVisibilityEnabled.value=enabled && world!==null;
+  this.uniforms.blenderWorldRadiance.value=world;
+  this.uniforms.blenderWorldToNative.value.setFromMatrix4(root.matrixWorld).invert();
+  if(!enabled || !world)return;
+  const meshes=[...objects].filter((object):object is THREE.Mesh=>(object as THREE.Mesh).isMesh===true &&
+   !!(object as THREE.Mesh).geometry.getAttribute('position'));
+  const layoutChanged=meshes.length!==this.segments.length || meshes.some((mesh,i)=>{
+   const previous=this.segments[i],geometry=mesh.geometry;
+   return !previous || previous.mesh!==mesh || previous.geometry!==geometry ||
+    previous.position!==geometry.getAttribute('position') || previous.index!==geometry.index ||
+    previous.start!==geometry.drawRange.start || previous.count!==Math.min(geometry.drawRange.count,
+     (geometry.index?.count ?? geometry.getAttribute('position').count)-geometry.drawRange.start);
+  });
+  if(layoutChanged) {
+   for(const mesh of this.dynamicMeshes.values()){mesh.removeFromParent();mesh.geometry.dispose();}
+   this.dynamicMeshes.clear();this.dynamicDirty=true;this.fittedBounds.makeEmpty();
+   let offset=0;
+   this.segments=meshes.map(mesh=>{
+    const geometry=mesh.geometry,position=geometry.getAttribute('position'),index=geometry.index;
+    const start=geometry.drawRange.start,count=Math.max(0,Math.min(geometry.drawRange.count,(index?.count??position.count)-start));
+    const segment={mesh,geometry,position,index,positionVersion:-1,indexVersion:-1,start,count,
+     offset,matrix:new THREE.Matrix4(),shown:!shown(mesh),bounds:new THREE.Box3(),dynamic:false};
+    offset+=count;return segment;
+   });
+   this.geometry.setAttribute('position',new THREE.BufferAttribute(new Float32Array(offset*3),3));
+   this.dirty=true;this.staticDirty=true;
+  }
+  const attribute=this.geometry.getAttribute('position') as THREE.BufferAttribute|undefined;
+  if(!attribute)return;
+  const point=new THREE.Vector3();
+  for(const segment of this.segments) {
+   const visible=shown(segment.mesh),pv=version(segment.position),iv=segment.index?.version??0;
+   if(segment.shown===visible && segment.matrix.equals(segment.mesh.matrixWorld) &&
+      segment.positionVersion===pv && segment.indexVersion===iv)continue;
+   // Once an object moves/deforms, keep it in the small dynamic atlas. Its
+   // later poses must never redraw every static triangle in the environment.
+   if(!segment.dynamic && segment.positionVersion>=0 &&
+     (!segment.matrix.equals(segment.mesh.matrixWorld) || segment.positionVersion!==pv || segment.indexVersion!==iv)) {
+    const geometry=new THREE.BufferGeometry();
+    geometry.setAttribute('position',new THREE.BufferAttribute(new Float32Array(segment.count*3),3));
+    const mesh=new THREE.Mesh(geometry,this.material);mesh.frustumCulled=false;
+    this.dynamicScene.add(mesh);this.dynamicMeshes.set(segment.mesh,mesh);segment.dynamic=true;
+    (attribute.array as Float32Array).fill(0,segment.offset*3,(segment.offset+segment.count)*3);
+    attribute.addUpdateRange(segment.offset*3,segment.count*3);attribute.needsUpdate=true;this.staticDirty=true;
+   }
+   const dynamicMesh=this.dynamicMeshes.get(segment.mesh);
+   const written=(dynamicMesh?.geometry.getAttribute('position')??attribute) as THREE.BufferAttribute;
+   if(dynamicMesh)dynamicMesh.visible=visible;
+   segment.bounds.makeEmpty();
+   for(let i=0;i<segment.count;i++) {
+    if(visible) {
+     const vertex=segment.index?.getX(segment.start+i) ?? segment.start+i;
+     point.fromBufferAttribute(segment.position,vertex).applyMatrix4(segment.mesh.matrixWorld);
+     segment.bounds.expandByPoint(point);
+    } else point.set(0,0,0); // Degenerate the hidden range without changing its layout.
+    written.setXYZ(dynamicMesh?i:segment.offset+i,point.x,point.y,point.z);
+   }
+   written.addUpdateRange(dynamicMesh?0:segment.offset*3,segment.count*3);written.needsUpdate=true;
+   if(dynamicMesh)this.dynamicDirty=true;else this.staticDirty=true;
+   segment.shown=visible;segment.matrix.copy(segment.mesh.matrixWorld);
+   segment.positionVersion=pv;segment.indexVersion=iv;this.dirty=true;
+  }
+ }
+
+ /** Draw the atlas only when a caster changes. All directional samples share
+  * one texture sampler and one merged depth draw, retaining offscreen casters. */
+ prepare(renderer:THREE.WebGLRenderer):void {
+  if(!this.uniforms.blenderWorldVisibilityEnabled.value || !this.dirty)return;
+  if(!this.target) {
+   const size=TILES*TILE_SIZE;
+   this.target=new THREE.WebGLRenderTarget(size,size,{depthBuffer:true,stencilBuffer:false});
+   this.target.depthTexture=new THREE.DepthTexture(size,size,THREE.UnsignedIntType);
+   this.target.depthTexture.minFilter=this.target.depthTexture.magFilter=THREE.NearestFilter;
+   this.uniforms.blenderWorldDepth.value=this.target.depthTexture;
+  }
+  if(this.dynamicMeshes.size && !this.dynamicTarget) {
+   const size=TILES*TILE_SIZE;
+   this.dynamicTarget=new THREE.WebGLRenderTarget(size,size,{depthBuffer:true,stencilBuffer:false});
+   this.dynamicTarget.depthTexture=new THREE.DepthTexture(size,size,THREE.UnsignedIntType);
+   this.dynamicTarget.depthTexture.minFilter=this.dynamicTarget.depthTexture.magFilter=THREE.NearestFilter;
+   this.uniforms.blenderWorldDynamicDepth.value=this.dynamicTarget.depthTexture;
+  }
+  this.uniforms.blenderWorldHasDynamicDepth.value=this.dynamicMeshes.size>0;
+  const bounds=this.segments.reduce((all,segment)=>all.union(segment.bounds),new THREE.Box3());
+  if(this.fittedBounds.isEmpty() || !this.fittedBounds.containsBox(bounds)) {
+   this.fittedBounds.union(bounds);this.staticDirty=true;
+  }
+  const sphere=this.fittedBounds.getBoundingSphere(new THREE.Sphere());
+  this.mesh.visible=(this.geometry.getAttribute('position')?.count??0)>0;
+  const radius=Math.max(sphere.radius,1e-3),distance=radius*2+1;
+  this.uniforms.blenderWorldRayOffset.value=radius*1e-5;
+  this.camera.left=-radius;this.camera.right=radius;this.camera.top=radius;this.camera.bottom=-radius;
+  this.camera.near=.001;this.camera.far=distance+radius*2;
+  this.camera.updateProjectionMatrix();
+  const target=renderer.getRenderTarget(),autoClear=renderer.autoClear,shadowMap=renderer.shadowMap.enabled;
+  try {
+   renderer.autoClear=false;renderer.shadowMap.enabled=false;
+   const targets:[THREE.WebGLRenderTarget,THREE.Scene,boolean][]=[[this.target,this.scene,this.staticDirty]];
+   if(this.dynamicTarget)targets.push([this.dynamicTarget,this.dynamicScene,this.dynamicDirty||this.staticDirty]);
+   for(const [target,,draw] of targets)if(draw) {
+    target.viewport.set(0,0,TILES*TILE_SIZE,TILES*TILE_SIZE);target.scissorTest=false;
+    renderer.setRenderTarget(target);renderer.clear(true,true,false);
+   }
+   for(let i=0;i<SAMPLE_COUNT;i++) {
+    const direction=this.uniforms.blenderWorldDirections.value[i]!;
+    this.camera.position.copy(sphere.center).addScaledVector(direction,distance);
+    this.camera.up.set(0,1,0);this.camera.lookAt(sphere.center);this.camera.updateMatrixWorld(true);
+    this.uniforms.blenderWorldMatrices.value[i]!.multiplyMatrices(this.camera.projectionMatrix,this.camera.matrixWorldInverse);
+    const x=(i%TILES)*TILE_SIZE,y=Math.floor(i/TILES)*TILE_SIZE;
+    // Render-target viewports use device pixels. Renderer.setViewport uses
+    // logical pixels even offscreen, so a HiDPI view would overlap the tiles.
+    for(const [target,scene,draw] of targets)if(draw) {
+     target.viewport.set(x,y,TILE_SIZE,TILE_SIZE);target.scissor.set(x,y,TILE_SIZE,TILE_SIZE);target.scissorTest=true;
+     renderer.setRenderTarget(target);renderer.render(scene,this.camera);
+    }
+   }
+   if(this.staticDirty){this.passes+=SAMPLE_COUNT;this.staticPasses+=SAMPLE_COUNT;}
+   if(this.dynamicTarget && (this.dynamicDirty||this.staticDirty)){this.passes+=SAMPLE_COUNT;this.dynamicPasses+=SAMPLE_COUNT;}
+   this.dirty=false;this.staticDirty=false;this.dynamicDirty=false;
+  } finally {
+   renderer.setRenderTarget(target);renderer.autoClear=autoClear;renderer.shadowMap.enabled=shadowMap;
+  }
+ }
+ diagnostics(){return {enabled:this.uniforms.blenderWorldVisibilityEnabled.value,world:!!this.uniforms.blenderWorldRadiance.value,
+  depth:!!this.uniforms.blenderWorldDepth.value,passes:this.passes,staticPasses:this.staticPasses,dynamicPasses:this.dynamicPasses,
+  dynamicObjects:this.dynamicMeshes.size,vertices:this.geometry.getAttribute('position')?.count??0,
+  casters:this.segments.filter(segment=>segment.shown).length,dirty:this.dirty};}
+ dispose():void {
+  this.uniforms.blenderWorldVisibilityEnabled.value=false;
+  this.target?.dispose();this.target=null;this.uniforms.blenderWorldDepth.value=null;
+  this.dynamicTarget?.dispose();this.dynamicTarget=null;this.uniforms.blenderWorldDynamicDepth.value=null;
+  this.uniforms.blenderWorldHasDynamicDepth.value=false;
+  for(const mesh of this.dynamicMeshes.values()){mesh.removeFromParent();mesh.geometry.dispose();}this.dynamicMeshes.clear();
+  this.geometry.dispose();this.material.dispose();this.segments=[];
+  this.geometry.deleteAttribute('position');this.dirty=true;this.staticDirty=true;this.dynamicDirty=false;this.fittedBounds.makeEmpty();
+ }
+}
+
+const bindings=new WeakMap<THREE.Material,BlenderWorldVisibility>();
+const compiled=new WeakMap<THREE.Material,Set<THREE.WebGLProgramParametersWithUniforms['uniforms']>>();
+const inactive=new BlenderWorldVisibility();
+export function bindWorldVisibility(material:THREE.Material,visibility:BlenderWorldVisibility):void {
+ if(bindings.get(material)===visibility)return;
+ bindings.set(material,visibility);
+ for(const uniforms of compiled.get(material)??[])Object.assign(uniforms,visibility.uniforms);
+}
+export function copyWorldVisibility(source:THREE.Material,target:THREE.Material):void {
+ const visibility=bindings.get(source);if(visibility)bindWorldVisibility(target,visibility);
+}
+export function worldVisibilityUniforms(material:THREE.Material,uniforms:THREE.WebGLProgramParametersWithUniforms['uniforms']):void {
+ let held=compiled.get(material);if(!held){held=new Set();compiled.set(material,held);}held.add(uniforms);
+ Object.assign(uniforms,(bindings.get(material)??inactive).uniforms);
+}
+
+export const worldVisibilityShader=/* glsl */`
+varying vec3 blenderWorldPosition;
+uniform bool blenderWorldVisibilityEnabled;
+uniform sampler2D blenderWorldDepth, blenderWorldDynamicDepth, blenderWorldRadiance;
+uniform bool blenderWorldHasDynamicDepth;
+uniform vec3 blenderWorldDirections[16];
+uniform mat4 blenderWorldMatrices[16];
+uniform mat3 blenderWorldToNative;
+uniform float blenderWorldRayOffset;
+float blenderWorldVisible(int i, vec3 position, vec3 worldDx, vec3 worldDy) {
+ vec4 clip=blenderWorldMatrices[i]*vec4(position,1.);
+ vec3 point=clip.xyz/clip.w*.5+.5;
+ if(any(lessThan(point,vec3(0.))) || any(greaterThan(point,vec3(1.))))return 1.;
+ vec2 tile=vec2(float(i%4),float(i/4));
+ vec2 samplePoint=clamp((floor(point.xy*512.)+.5)/512.,vec2(.5/512.),vec2(1.-.5/512.));
+ vec2 uv=(tile+samplePoint)/4.;
+ float depth=texture2D(blenderWorldDepth,uv).x;
+ if(blenderWorldHasDynamicDepth)depth=min(depth,texture2D(blenderWorldDynamicDepth,uv).x);
+ // Compare the receiver plane AT THE DEPTH TEXEL, not at its nearby fragment.
+ // A fixed depth bias falsely shadows an unoccluded tilted plane; increasing
+ // that bias leaks through thin walls. Derivatives retain its actual slope.
+ vec3 dx=(blenderWorldMatrices[i]*vec4(worldDx,0.)).xyz*.5;
+ vec3 dy=(blenderWorldMatrices[i]*vec4(worldDy,0.)).xyz*.5;
+ float determinant=dx.x*dy.y-dx.y*dy.x;
+ vec2 gradient=abs(determinant)>1e-12 ? vec2(dx.z*dy.y-dy.z*dx.y,dy.z*dx.x-dx.z*dy.x)/determinant : vec2(0.);
+ float receiverDepth=point.z+dot(gradient,samplePoint-point.xy);
+ return receiverDepth<=depth+1e-6 ? 1. : 0.;
+}
+vec3 blenderWorldIrradiance(vec3 normal, vec3 fallbackIrradiance) {
+ if(!blenderWorldVisibilityEnabled)return fallbackIrradiance;
+ vec3 n=inverseTransformDirection(normal,viewMatrix),sum=vec3(0.);
+ float weights=0.;vec3 origin=blenderWorldPosition+n*blenderWorldRayOffset;
+ vec3 worldDx=dFdx(blenderWorldPosition),worldDy=dFdy(blenderWorldPosition);
+ for(int i=0;i<16;i++) {
+  vec3 direction=blenderWorldDirections[i];float weight=max(0.,dot(n,direction));weights+=weight;
+  if(weight>0. && blenderWorldVisible(i,origin,worldDx,worldDy)>0.) {
+   vec3 nativeDirection=normalize(blenderWorldToNative*direction);
+   vec2 uv=vec2(atan(-nativeDirection.y,nativeDirection.x)/6.28318530718+.5,
+    asin(clamp(nativeDirection.z,-1.,1.))/3.14159265359+.5);
+   sum+=texture2D(blenderWorldRadiance,uv).rgb*weight;
+  }
+ }
+ return sum*(3.14159265359/max(weights,1e-8));
+}
+float blenderWorldReflectionVisibility(vec3 viewDirection,vec3 normal,float roughness) {
+ if(!blenderWorldVisibilityEnabled)return 1.;
+ vec3 n=inverseTransformDirection(normal,viewMatrix),r=inverseTransformDirection(reflect(-viewDirection,normal),viewMatrix);
+ vec3 origin=blenderWorldPosition+n*blenderWorldRayOffset;
+ vec3 worldDx=dFdx(blenderWorldPosition),worldDy=dFdy(blenderWorldPosition);
+ float sum=0.,weights=0.;
+ for(int i=0;i<16;i++) {
+  float weight=pow(max(0.,dot(r,blenderWorldDirections[i])),mix(64.,1.,roughness));
+  weights+=weight;sum+=weight*blenderWorldVisible(i,origin,worldDx,worldDy);
+ }
+ return sum/max(weights,1e-8);
+}
+`;

package/browser/three/world-field-sampler.ts

@@ -18,7 +18,7 @@ import { gradientTexture } from './blender-gradient-texture';
 // Type-only, so this module keeps NO runtime edge back to the contribution
 // that uses it -- which is what lets a worker import it alone.
 import type { WorldExpression } from './blender-runtime-lighting';
-import { type SkyParameters, skyField } from './blender-sky';
+import { type SkyParameters, skyField, skySunDirection } from './blender-sky';
 import { worldMath } from './world-math';
 
 export function worldField(
@@ -101,6 +101,9 @@ export function worldField(
     // rebuilding it per direction would be a 65,536-pixel job per texel.
     const field = skyField({
       ...(expression.sky_model === undefined ? {} : {model: expression.sky_model}),
+      ...(expression.sun_disc === undefined ? {} : {sunDisc: expression.sun_disc}),
+      ...(expression.sun_size === undefined ? {} : {sunSize: expression.sun_size}),
+      ...(expression.sun_intensity === undefined ? {} : {sunIntensity: expression.sun_intensity}),
       sunElevation: expression.sun_elevation,
       sunRotation: expression.sun_rotation,
       altitude: expression.altitude,
@@ -255,6 +258,9 @@ export function collectSkyParameters(expression: WorldExpression): SkyParameters
       case 'sky':
         found.push({
           ...(node.sky_model === undefined ? {} : {model: node.sky_model}),
+          ...(node.sun_disc === undefined ? {} : {sunDisc: node.sun_disc}),
+          ...(node.sun_size === undefined ? {} : {sunSize: node.sun_size}),
+          ...(node.sun_intensity === undefined ? {} : {sunIntensity: node.sun_intensity}),
           sunElevation: node.sun_elevation,
           sunRotation: node.sun_rotation,
           altitude: node.altitude,
@@ -298,6 +304,57 @@ export function collectSkyParameters(expression: WorldExpression): SkyParameters
   return found;
 }
 
+/** Keep the broad sky in IBL and integrate its small bright disc separately.
+ * A 256-wide environment map cannot resolve a one-degree sun reliably, and
+ * IBL has no geometric shadow visibility. A directional shadow light carries
+ * the disc's integrated irradiance; it is an angular-size approximation,
+ * rather than a replacement for Cycles' finite-disc path sampling. */
+export function withoutSolarDiscs(expression: WorldExpression): WorldExpression {
+  return JSON.parse(JSON.stringify(expression), (_key, value) =>
+    value?.kind === 'sky' && value.sky_model === 'SINGLE_SCATTERING'
+      ? {...value, sun_disc: false} : value) as WorldExpression;
+}
+
+export function worldSolarIrradiance(expression: WorldExpression): {direction: THREE.Vector3; irradiance: THREE.Vector3}[] {
+  const suns = collectSkyParameters(expression).filter(p => p.model === 'SINGLE_SCATTERING' &&
+    p.sunDisc && (p.sunSize ?? 0) > 0 && (p.sunIntensity ?? 1) > 0);
+  if (!suns.length) return [];
+  // Window-dependent world shaders need ray origins as well as directions;
+  // there is no position-independent directional light for that field.
+  if (usesWindowCoordinates(expression)) return [];
+  const diffuse = worldField(withoutSolarDiscs(expression));
+  const unique = [...new Map(suns.map(p => [JSON.stringify([p.sunElevation, p.sunRotation, p.sunSize]), p])).values()];
+  return unique.map(p => {
+    // Other discs must not be counted again when they overlap this one's
+    // integration domain. Equal domains are one group, including mixed nodes.
+    const complete = worldField(JSON.parse(JSON.stringify(expression), (_key, value) =>
+      value?.kind === 'sky' && value.sky_model === 'SINGLE_SCATTERING' &&
+      (value.sun_elevation !== p.sunElevation || value.sun_rotation !== p.sunRotation || value.sun_size !== p.sunSize)
+        ? {...value,sun_disc:false} : value) as WorldExpression);
+    const direction = skySunDirection(p);
+    const u = new THREE.Vector3().crossVectors(direction, Math.abs(direction.z) < .9
+      ? new THREE.Vector3(0, 0, 1) : new THREE.Vector3(0, 1, 0)).normalize();
+    const v = new THREE.Vector3().crossVectors(direction, u);
+    const irradiance = new THREE.Vector3(), ray = new THREE.Vector3(), delta = new THREE.Vector3();
+    const solidAngle = 2 * Math.PI * (1 - Math.cos(p.sunSize! / 2));
+    const radial = 32, azimuthal = 32;
+    for (let i = 0; i < radial; i++) {
+      const cos = 1 - (i + .5) / radial * (1 - Math.cos(p.sunSize! / 2));
+      const sin = Math.sqrt(1 - cos * cos);
+      for (let j = 0; j < azimuthal; j++) {
+        const phi = (j + .5) / azimuthal * 2 * Math.PI;
+        ray.copy(direction).multiplyScalar(cos).addScaledVector(u, sin * Math.cos(phi)).addScaledVector(v, sin * Math.sin(phi));
+        const all = complete(ray);
+        if (typeof all === 'number') delta.setScalar(all); else delta.copy(all);
+        const base = diffuse(ray);
+        if (typeof base === 'number') delta.addScalar(-base); else delta.sub(base);
+        irradiance.addScaledVector(delta, cos * solidAngle / (radial * azimuthal));
+      }
+    }
+    return {direction, irradiance};
+  });
+}
+
 /** Whether this expression depends on the camera's normalized image coordinates. */
 export function usesWindowCoordinates(expression: WorldExpression): boolean {
   if (typeof expression === 'number' || Array.isArray(expression)) return false;

package/browser/volter_three.py

@@ -225,7 +225,11 @@ def _export():
         "known": {},
         "buffer_path": EXPORT_BUFFER_PATH,
     }
-    frame = json.loads(_blender_web.export_frame(json.dumps(options)))
+    # The native door reads UTF-8 and does not decode `\\uXXXX` escapes (it
+    # drops the backslash), so the request goes unescaped, as session.py's door
+    # calls send theirs: a non-ASCII presenter root in `buffer_path` would
+    # otherwise reach the door misspelled.
+    frame = json.loads(_blender_web.export_frame(json.dumps(options, ensure_ascii=False)))
     error = frame.get("error")
     if error:
         raise RuntimeError("Blender export door: %s" % error)

package/browser/worker.ts

@@ -577,6 +577,43 @@ async function stageProjectFiles(files_: BlenderFiles, project: string): Promise
   return failed;
 }
 
+/** What `session.py::follow_open_file` says after a script changed the file Blender holds. */
+type FollowedDocument =
+  | { moved: true; from: string; document: string }
+  | { moved: false; from: string; outside: string };
+
+/**
+ * THE DOCUMENT FOLLOWS BLENDER'S SAVE AS, and the script's caller is told in its own answer.
+ *
+ * A move retargets the session's saves here (the save this call ends with lands the new file
+ * in the project, which is where the editor's Model tab for it opens from) and tells the tab,
+ * whose runtime handle holds the same path. A file outside the project is refused: the editor
+ * has no document there, so the session keeps its own and keeps saving to it, and says so
+ * naming both files, since the script believes it is now working in the other one.
+ */
+function followDocument(followed: FollowedDocument | undefined): string {
+  if (!followed) return '';
+  if (!followed.moved) {
+    const line = `Blender now has ${followed.outside} open, which is outside the project, so the editor cannot ` +
+      `follow it there: this session's document stays ${followed.from}, and the model keeps saving to ` +
+      `${followed.from}. To move the model to another file, save it inside the project (src/models/<name>.blend).`;
+    log('warn', line);
+    return `\n\n${line}`;
+  }
+  if (!isDocumentPath(followed.document)) {
+    // The session checks the same shape, so this is a broken promise, not a refusal to explain.
+    throw new Error(`Blender moved its document to ${JSON.stringify(followed.document)}, which is not a project .blend path`);
+  }
+  documentPath = followed.document;
+  // Even a present that failed must not leave the new file only in the engine's filesystem.
+  setDocumentDirty(true);
+  post({ op: 'document-moved', from: followed.from, document: followed.document });
+  const line = `Blender now has ${followed.document} open (this code saved or opened it), so the editor follows it: ` +
+    `the model saves to ${followed.document} from now on, and ${followed.from} keeps what it last saved.`;
+  log('log', `@@VOLTER-DOCUMENT-MOVED ${JSON.stringify({ from: followed.from, document: followed.document })}`);
+  return `\n\n${line}`;
+}
+
 /** The failures `stageProjectFiles` answered, as one paragraph a script's caller can read. */
 function stagingNote(failed: readonly string[]): string {
   return failed.length === 0 ? '' :
@@ -678,14 +715,22 @@ async function handle(request: WorkerRequest): Promise<unknown> {
         const note = stagingNote(await stageProjectFiles(files, projectRoot));
         const answer = await ask({ op: 'execute', code: request.code, history: request.history ?? true,
           label: request.label ?? 'Blender Python' }) as {
-          error?: string; result: string;
+          error?: string; result: string; document?: FollowedDocument;
         };
-        return (answer.error ? `Error executing code: ${answer.error}` : `Code executed successfully: ${answer.result}`) + note;
+        return (answer.error ? `Error executing code: ${answer.error}` : `Code executed successfully: ${answer.result}`) +
+          note + followDocument(answer.document);
       }
     case 'present':
       // Straight through to `session.py`'s own `present` op — the worker adds
       // nothing, and a capture-less present answers `{ presented, revision }`.
       return pullWork('present', () => ask({ op: 'present' }));
+    case 'native-preview':
+      return ask({ op: 'native-preview', width: request.width, height: request.height,
+        samples: request.samples, ...(request.camera === undefined ? {} : { camera: request.camera }) });
+    case 'list-files-snapshot': {
+      const document = await ask({ op: 'document-info' });
+      return { entries: await listSessionFiles(files, request.path), document };
+    }
     case 'scene-info':
       return session.sceneInfo();
     case 'object-info':

package/package.json

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

package/wasm/BUNDLE.json

@@ -1,9 +1,9 @@
 {
   "blender": "5.2.0 LTS",
-  "source": "9fdd05db03bf0e4aa1028607be3e113be7f98d01",
+  "source": "434072350c0577eb155068d5a1b62bb45daf19f9",
   "upstream": "fbe6228777e7d9afefcd61a413844e790ae75db7",
   "sourceRepository": "https://github.com/volter-ai/blender",
-  "sourceRecipe": "https://github.com/volter-ai/blender/blob/9fdd05db03bf0e4aa1028607be3e113be7f98d01/build_files/emscripten/RELEASE.md",
+  "sourceRecipe": "https://github.com/volter-ai/blender/blob/434072350c0577eb155068d5a1b62bb45daf19f9/build_files/emscripten/RELEASE.md",
   "factoryEngine": "BLENDER_EEVEE",
   "files": {
     "blender_browser.js": "raw",
@@ -13,38 +13,38 @@
   "rawFiles": {
     "blender_browser.js": {
       "bytes": 408423,
-      "sha256": "0c63c29e7d4b1ba1fce4e94057778b0757767b25ea4f6f01d329e99351568f30"
+      "sha256": "d818e8d746bc62ebf810206ac564d2dc75dc645b3121f4a3919d13ecef11e419"
     },
     "blender_browser.wasm": {
-      "bytes": 86337036,
-      "sha256": "9d8cb5bd0dbb34fa7f04858fb6bc831195d0b06e8b82bb26889f3c6d807a9588"
+      "bytes": 86344416,
+      "sha256": "f5b988d30a9f29708254bc84600f7b88d9c9eb41af904b84c9f398d5c41595e4"
     },
     "blender_browser.data": {
-      "bytes": 52698568,
-      "sha256": "bf86b5ca29b86a9d7e1185d8b3eba5bd5101eff9eeef47d36884fbe69b9a2cb7"
+      "bytes": 52699590,
+      "sha256": "89cfee5131d8a7c7361b1f8d249fb08a81b14102963ae161e1146eabab56e558"
     }
   },
   "shippedFiles": {
     "blender_browser.js": {
       "bytes": 408423,
-      "sha256": "0c63c29e7d4b1ba1fce4e94057778b0757767b25ea4f6f01d329e99351568f30"
+      "sha256": "d818e8d746bc62ebf810206ac564d2dc75dc645b3121f4a3919d13ecef11e419"
     },
     "blender_browser.wasm.br": {
-      "bytes": 18604996,
-      "sha256": "782c1f8519851e8b901d5309d239429ecd07c4ed374adaf117214f9ac22f84c9"
+      "bytes": 18611942,
+      "sha256": "b415a2fce0f2d2f796a2a3362b38420df063866898cc04c61d4604c5caf13e0d"
     },
     "blender_browser.data.br": {
-      "bytes": 8056563,
-      "sha256": "1d63c1250e2ab9538df36d7d07338396b271577c49227508ae7530f7bde2ee4a"
+      "bytes": 8056485,
+      "sha256": "899d53d55f730eb12602b23c9f78e034e45e244380719d310ee11098725911d8"
     },
     "DEPENDENCY-LICENSES.txt": {
       "bytes": 241352,
       "sha256": "4085e9336266cf66f061d4d5c962a5929cc96d5732c746b5c13ea05cd104a75b"
     }
   },
-  "note": "Stoneguard c7/c14/c15 engine. Emscripten 6.0.5, Release -O3 objects and -O2 link. Portable native arm64 matrix reciprocal plus fused generic OpenSubdiv stencil and patch accumulation; bodice four-stage comparison 28/28 arrays exact. Full-scene comparison and memory scope recorded in provenance/stoneguard-memory.json. Historical battery absent; no full-battery or hosted acceptance claim.",
+  "note": "Stoneguard c7/c14/c15 engine. Emscripten 6.0.5, Release -O3 objects and -O2 link. Portable native arm64 matrix reciprocal plus fused generic OpenSubdiv stencil and patch accumulation; bodice four-stage comparison 28/28 arrays exact. Full-scene comparison and memory scope recorded in provenance/stoneguard-memory.json. Historical battery absent; no full-battery or hosted acceptance claim. Rebuilt from the public instance-source commit with the same Emscripten 6.0.5, Release -O3 objects and -O2 link. All 6287 drawable Lone Monk placements resolve to 26 native source objects and 24 deferred mesh resources. Live raster rendering still differs from native Cycles; no full-scene visual parity claim. Rebuilt from the public evaluated-geometry identity commit with the same Emscripten 6.0.5 Release recipe. Distinct Array/Mirror/deformation outputs no longer borrow another object’s geometry. Native linked-input sharing and every deferred probe vertex are checked independently. Live raster illumination remains unoccluded environment lighting and differs substantially from native Cycles; no visual parity claim.",
   "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 existing session registers Python render engines under CYCLES, BLENDER_EEVEE and BLENDER_WORKBENCH; the headless build permits built-in IDs to be shadowed.",
-  "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.",
+  "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.",
   "preloadedPayload": "releasePreloadedFileData releases the JS preload buffer after session ready. The measured working payload exclusions are retained."
 }