@volter/blender-engine 0.1.129 → 0.1.130

package/browser/three/blender-object-info-materials.ts

@@ -6,6 +6,7 @@ export interface BlenderObjectInfo {
   readonly color: readonly number[];
   readonly index: number;
   readonly random: number;
+  readonly particle_random?: number;
 }
 type Draw = {source: THREE.MeshPhysicalMaterial; mesh: THREE.Mesh; material: THREE.MeshPhysicalMaterial; version:number};
 
@@ -18,17 +19,24 @@ export class BlenderObjectInfoMaterials {
   private readonly draws=new Map<string,Draw>();
   private readonly sources=new Map<THREE.MeshPhysicalMaterial,string|null>();
   private used=new Set<string>();
+  private readonly particleInputs=new Map<THREE.Mesh,number>();
 
-  begin(): void {this.used.clear();this.sources.clear();}
+  begin(): void {this.used.clear();this.sources.clear();this.particleInputs.clear();}
 
   get(source: THREE.Material, mesh: THREE.Mesh): THREE.Material {
     if (!(source instanceof THREE.MeshPhysicalMaterial)) return source;
     const graph=materialGraph(source);
     this.sources.set(source,graph?.key??null);
-    if (!graph?.objectInfo) return source;
+    if (!graph || (!graph.objectInfo && !graph.particleInfo)) return source;
     const info=mesh.userData['blenderObjectInfo'] as BlenderObjectInfo|undefined;
     if (!info) throw new Error(`Object Info inputs missing for Blender object ${mesh.name}`);
-    const key=`${mesh.uuid}:${source.uuid}`;
+    // Particle Random alone is a draw-uniform value, not a position input.
+    // Identical geometry/values (especially Cycles' default child record) share one
+    // material identity. Object Info still needs each object's model matrix.
+    if (graph.particleInfo && info.particle_random === undefined)
+      throw new Error(`Particle Info Random input missing for Blender object ${mesh.name}`);
+    if (!graph.objectInfo) this.particleInputs.set(mesh,info.particle_random!);
+    const key=`${graph.objectInfo ? mesh.uuid : `particle:${mesh.geometry.uuid}:${info.particle_random}`}:${source.uuid}`;
     this.used.add(key);
     let draw=this.draws.get(key);
     if (!draw) {
@@ -37,6 +45,9 @@ export class BlenderObjectInfoMaterials {
       draw={source,mesh,material,version:source.version};
       this.draws.set(key,draw);
     }
+    // Refresh follows a mesh that still wears this shared input, including
+    // when its former representative was edited or removed.
+    draw.mesh=mesh;
     this.sync(draw,info);
     return draw.material;
   }
@@ -49,7 +60,11 @@ export class BlenderObjectInfoMaterials {
 
   /** A pending authored graph can finish without another native export. */
   needsRemap(): boolean {
-    return [...this.sources].some(([source,key])=>(materialGraph(source)?.key??null)!==key);
+    for (const [source,key] of this.sources)
+      if ((materialGraph(source)?.key??null)!==key) return true;
+    for (const [mesh,value] of this.particleInputs)
+      if ((mesh.userData['blenderObjectInfo'] as BlenderObjectInfo|undefined)?.particle_random!==value) return true;
+    return false;
   }
 
   refresh(): void {
@@ -70,6 +85,6 @@ export class BlenderObjectInfoMaterials {
 
   clear(): void {
     for(const draw of this.draws.values()) draw.material.dispose();
-    this.draws.clear();this.sources.clear();this.used.clear();
+    this.draws.clear();this.sources.clear();this.used.clear();this.particleInputs.clear();
   }
 }

package/browser/three/blender-render-camera.ts

@@ -0,0 +1,22 @@
+import * as THREE from 'three';
+import type {RenderRequest} from '../protocol';
+
+/** Render through the authored camera, including its deliberate clipping.
+ * Navigation's automatically fitted clipping does not describe a render. */
+export function blenderRenderCamera(render: RenderRequest, documentScale = 1): THREE.PerspectiveCamera | THREE.OrthographicCamera {
+  const aspect = render.width / render.height;
+  const near = (render.clipStart ?? .1) * documentScale;
+  const far = (render.clipEnd ?? 2000) * documentScale;
+  const camera = render.orthographic
+    ? new THREE.OrthographicCamera(-render.fov * documentScale * aspect / 2,
+      render.fov * documentScale * aspect / 2, render.fov * documentScale / 2,
+      -render.fov * documentScale / 2, near, far)
+    : new THREE.PerspectiveCamera(render.fov, aspect, near, far);
+  // Blender's shift uses the fitted sensor dimension for BOTH axes.
+  // View offset survives projection updates and capture camera cloning.
+  const fitted = (render.horizontalFit ?? aspect >= 1) ? render.width : render.height;
+  camera.setViewOffset(render.width, render.height,
+    (render.shiftX ?? 0) * fitted, -(render.shiftY ?? 0) * fitted,
+    render.width, render.height);
+  return camera;
+}

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

@@ -47,6 +47,8 @@ import {
   sampleWorldScreen,
   usesWindowCoordinates,
   worldField,
+  worldSolarIrradiance,
+  withoutSolarDiscs,
 } from './world-field-sampler';
 import { type WorldMathOperation, worldMath } from './world-math';
 
@@ -436,6 +438,9 @@ export type WorldExpression =
   | {
       kind: 'sky';
       sky_model?: 'SINGLE_SCATTERING' | 'MULTIPLE_SCATTERING' | undefined;
+      sun_disc?: boolean | undefined;
+      sun_size?: number | undefined;
+      sun_intensity?: number | undefined;
       sun_elevation: number;
       sun_rotation: number;
       altitude: number;
@@ -533,6 +538,9 @@ const worldExpression: z.ZodType<WorldExpression> = z.lazy(() =>
       .object({
         kind: z.literal('sky'),
         sky_model: z.enum(['SINGLE_SCATTERING', 'MULTIPLE_SCATTERING']).optional(),
+        sun_disc: z.boolean().optional(),
+        sun_size: scalar.optional(),
+        sun_intensity: scalar.optional(),
         sun_elevation: scalar,
         sun_rotation: scalar,
         altitude: scalar,
@@ -690,9 +698,18 @@ function worldDataTexture(
   width: number,
   height: number,
 ): THREE.DataTexture {
-  const data = new Uint16Array(width * height * 4);
-  writeScaled(data, samples, strength, width * height);
-  const texture = new THREE.DataTexture(data, width, height, THREE.RGBAFormat, THREE.HalfFloatType);
+  // Solar radiance can exceed half-float's 65504 limit even at native default
+  // intensity. Keep those backgrounds in float32 instead of clipping the field.
+  const fullFloat = samples.some(value => Math.abs(value * strength) > 65504);
+  const data = fullFloat ? new Float32Array(width * height * 4) : new Uint16Array(width * height * 4);
+  if (data instanceof Float32Array) {
+    for (let i = 0; i < width * height; i++) {
+      for (let c = 0; c < 3; c++) data[i * 4 + c] = samples[i * 3 + c]! * strength;
+      data[i * 4 + 3] = 1;
+    }
+  } else writeScaled(data, samples, strength, width * height);
+  const texture = new THREE.DataTexture(data, width, height, THREE.RGBAFormat,
+    fullFloat ? THREE.FloatType : THREE.HalfFloatType);
   texture.mapping = THREE.EquirectangularReflectionMapping;
   texture.colorSpace = THREE.LinearSRGBColorSpace;
   texture.minFilter = THREE.LinearFilter;
@@ -707,6 +724,13 @@ export type WorldData = z.infer<typeof worldSchema>;
  * Constants and linked colors use the same radiometric path. The environment
  * samples the field at 256×128; features below a texel are filtered. */
 export class WorldBackground {
+  readonly solarLights: THREE.DirectionalLight[] = [];
+  private readonly solarDirections = new Map<THREE.DirectionalLight, THREE.Vector3>();
+
+  updateSolarDirections(root: THREE.Object3D): void {
+    for (const [light, direction] of this.solarDirections)
+      light.position.copy(direction).transformDirection(root.matrixWorld);
+  }
   private pending: Promise<void> | null = null;
 
   /** Await this world's preparation, including a failure that settled before
@@ -772,7 +796,7 @@ export class WorldBackground {
     ];
     const missing = skies.filter((parameters) => !hasSkyTexture(parameters));
     if (missing.length === 0) {
-      this.compose(scene, world, expression, camera);
+      this.compose(scene, world, expression, camera, root);
       return;
     }
     const pending = (async () => {
@@ -783,7 +807,7 @@ export class WorldBackground {
       // The world moved on (another apply, or a clear) while the worker ran:
       // composing now would paint a sky nobody asked for over the current one.
       if (this.generation !== generation || this.applied?.scene !== scene) return;
-      this.compose(scene, world, expression, camera);
+      this.compose(scene, world, expression, camera, root);
       presenterChanged();
     })();
     this.pending = pending;
@@ -802,6 +826,7 @@ export class WorldBackground {
     world: WorldData,
     expression: WorldExpression,
     camera?: THREE.Camera,
+    root?: THREE.Object3D,
   ): void {
     this.texture = worldTexture(expression, world.strength, camera);
     if (usesWindowCoordinates(expression)) {
@@ -833,14 +858,37 @@ export class WorldBackground {
     // 0.30 behind a 0.95 backdrop -- and three keeps the two apart, so using
     // the backdrop here would light that scene three times too brightly.
     const { lighting } = world;
-    this.environmentTexture = lighting
-      ? worldTexture(lighting.shader ?? lighting.color, lighting.strength, camera)
+    const lightingExpression = lighting?.shader ?? lighting?.color ?? expression;
+    const solar = worldSolarIrradiance(lightingExpression);
+    this.environmentTexture = lighting || solar.length
+      ? worldTexture(solar.length ? withoutSolarDiscs(lightingExpression) : lightingExpression,
+        lighting?.strength ?? world.strength, camera)
       : null;
     scene.environment = this.environmentTexture ?? this.texture;
+    root?.updateMatrixWorld(true);
+    for (const {direction, irradiance} of solar) {
+      const light = new THREE.DirectionalLight(0xffffff, lighting?.strength ?? world.strength);
+      light.name = 'BlenderWorldSun';
+      light.color.setRGB(irradiance.x, irradiance.y, irradiance.z, THREE.LinearSRGBColorSpace);
+      light.position.copy(direction);
+      if (root) light.position.transformDirection(root.matrixWorld);
+      light.castShadow = true;
+      light.shadow.mapSize.set(2048, 2048);
+      scene.add(light, light.target);
+      this.solarLights.push(light);
+      this.solarDirections.set(light, direction.clone());
+    }
   }
 
   clear(): void {
     this.generation++;
+    for (const light of this.solarLights) {
+      light.removeFromParent();
+      light.target.removeFromParent();
+      light.dispose();
+    }
+    this.solarLights.length = 0;
+    this.solarDirections.clear();
     if (!this.applied) return;
     this.applied.scene.background = this.applied.background;
     this.applied.scene.environment = this.applied.environment;

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

@@ -2,6 +2,7 @@
  * No modeling operations or source builds run here. Stable datablock addresses
  * retain objects/resources; changed meshes replace only their draw geometry.
  */
+import {expandDrawPlacements} from './blender-depsgraph-placements';
 import * as THREE from 'three';
 import { z } from 'zod';
 import { onPresenterChange, presenterChanged } from './blender-presenter-change';
@@ -490,6 +491,13 @@ export const frameSchema = z
     meshes: z.record(z.string(), meshSchema),
     materials: z.record(z.string(), materialSchema),
     images: z.record(z.string(), frameImageSchema).default({}),
+    /** Evaluated draws borrowing geometry/materials from native source rows. */
+    instances: z.array(z.object({
+      id:z.string(),source:z.string(),owner:z.string().nullable(),
+      matrix:z.array(z.tuple([scalar,scalar,scalar,scalar])).length(4),
+      visible:z.boolean(),render_visible:z.boolean(),random:scalar,color:z.tuple([scalar,scalar,scalar,scalar]),
+      shadow_visible:z.boolean().optional(),particle_random:scalar.optional(),
+    }).strict()).optional(),
     objects: z.array(
       z
         .object({
@@ -519,15 +527,19 @@ export const frameSchema = z
           matrix: z.array(z.tuple([scalar, scalar, scalar, scalar])).length(4),
           visible: z.boolean(),
           render_visible: z.boolean().default(true),
+          shadow_visible: z.boolean().default(true),
           selected: z.boolean(),
           parent: z.string().nullable(),
+          instance_owner: z.string().nullable().optional(),
+          viewport_show_self:z.boolean().optional(),
+          render_show_self:z.boolean().optional(),
           /** A manual texture space (`[location, size]`), which Generated
            *  coordinates map through; absent means Blender's automatic one,
            *  the evaluated bounds (`blender-graph-material.ts`'s orco). */
           texspace: z.tuple([z.tuple([scalar, scalar, scalar]), z.tuple([scalar, scalar, scalar])]).optional(),
           default_color: z.string().optional(),
           object_info: z.object({
-            color:z.tuple([scalar,scalar,scalar,scalar]),index:scalar,random:scalar,
+            color:z.tuple([scalar,scalar,scalar,scalar]),index:scalar,random:scalar,particle_random:scalar.optional(),
           }).strict().optional(),
         })
         .strict(),
@@ -701,10 +713,12 @@ export class BlenderRuntimeView {
   private readonly emptyExtrasRoot = new THREE.Group();
   private rendered = false;
   private sceneLights = false;
+  private readonly hiddenSurfaceLayers = new WeakMap<THREE.Object3D,number>();
   private shadowFit: {
     camera: THREE.Camera | undefined;
     cameraMatrix: THREE.Matrix4 | undefined;
     projection: THREE.Matrix4 | undefined;
+    solarLights: THREE.DirectionalLight[];
     objects: Map<THREE.Object3D, { matrix: THREE.Matrix4; visible: boolean }>;
   } | null = null;
   /** The camera the VIEWPORT is held in render lighting through (Blender's Rendered shading),
@@ -723,7 +737,7 @@ export class BlenderRuntimeView {
    *  (`blender-workbench-material.ts`) over their viewport display. */
   private workbench = false;
   private readonly workbenchMaterials = new Map<string, THREE.Material>();
-  private readonly fallback = new THREE.MeshPhysicalMaterial({ color: 0xb9bec6, roughness: 0.72 });
+  private readonly fallback = new THREE.MeshPhysicalMaterial({ color: 0xb9bec6, roughness: 0.72, side: THREE.DoubleSide });
   /** Base Color images, by image name -- ONE texture per image however many
    *  materials read it, and the cache OWNS it: a material points at one and
    *  never disposes it. Held with the size and revision the resident bytes
@@ -1418,6 +1432,9 @@ export class BlenderRuntimeView {
       await lightingReady();
       await Promise.all([...this.textures.values()].map((held) => held.ready));
       await this.world.ready();
+      // The asynchronous sky composition creates solar lights. Fit their
+      // shadows only after they exist, including the first detached capture.
+      this.applyShadows(rendered, camera);
     }
   }
 
@@ -1440,9 +1457,12 @@ export class BlenderRuntimeView {
    */
   private applyShadows(rendered: boolean, camera?: THREE.Camera): void {
     this.root.updateMatrixWorld(true);
+    this.world.updateSolarDirections(this.root);
     const fitted = this.shadowFit;
     if (rendered && fitted && fitted.camera === camera &&
       (!camera || (fitted.cameraMatrix?.equals(camera.matrixWorld) && fitted.projection?.equals(camera.projectionMatrix))) &&
+      fitted.solarLights.length === this.world.solarLights.length &&
+      fitted.solarLights.every((light, index) => light === this.world.solarLights[index]) &&
       fitted.objects.size === this.objects.size &&
       [...this.objects.values()].every(object => {
         const previous = fitted.objects.get(object);
@@ -1452,18 +1472,22 @@ export class BlenderRuntimeView {
       camera,
       cameraMatrix: camera?.matrixWorld.clone(),
       projection: camera?.projectionMatrix.clone(),
+      solarLights: [...this.world.solarLights],
       objects: new Map([...this.objects.values()].map(object =>
         [object, { matrix: object.matrixWorld.clone(), visible: object.visible }])),
     } : null;
     const boxes: THREE.Box3[] = [];
-    for (const object of this.objects.values()) {
+    const casters: THREE.Box3[] = [];
+    const shadowVisibility = new Map(this.frame?.objects.map(row => [row.id, row.shadow_visible]) ?? []);
+    for (const [id, object] of this.objects) {
       const mesh = object as THREE.Mesh;
       if (!mesh.isMesh) continue;
-      mesh.castShadow = rendered;
+      mesh.castShadow = rendered && shadowVisibility.get(id) !== false;
       mesh.receiveShadow = rendered;
       if (rendered && mesh.visible) {
         const bounds = new THREE.Box3().setFromObject(mesh);
         if (!bounds.isEmpty()) boxes.push(bounds);
+        if (!bounds.isEmpty() && mesh.castShadow) casters.push(bounds);
       }
     }
     if (!rendered || !boxes.length) return;
@@ -1477,9 +1501,9 @@ export class BlenderRuntimeView {
     const receivers = frustum
       ? boxes.flatMap((bounds) => visibleShadowReceivers(bounds, frustum))
       : [];
-    for (const light of this.lights.values()) {
+    for (const light of [...this.lights.values(), ...this.world.solarLights]) {
       if ((light as THREE.DirectionalLight).isDirectionalLight && camera)
-        fitModelDirectionalShadow(light as THREE.DirectionalLight, receivers, boxes);
+        fitModelDirectionalShadow(light as THREE.DirectionalLight, receivers, casters);
       else fitShadow(light, sphere.center, sphere.radius);
     }
   }
@@ -1580,11 +1604,26 @@ export class BlenderRuntimeView {
   }
 
   private applyVisibility(): void {
+    // Restore canonical masks before suppressing an instancer's own surface.
+    // Its geometry can be hidden while its placed children remain visible.
+    this.instances.clear();
+    this.transparentInstances.clear();
     const renderVisibility = this.rendered && (this.capturing || this.heldVisibility === 'render');
     for (const obj of this.frame?.objects ?? []) {
       const object = this.objects.get(obj.id);
       const visible = renderVisibility ? obj.render_visible : obj.visible;
       if (object) object.visible = visible;
+      if ((object as THREE.Mesh | undefined)?.isMesh) {
+        const showSelf = (renderVisibility ? obj.render_show_self : obj.viewport_show_self) ?? true;
+        const previous = this.hiddenSurfaceLayers.get(object!);
+        if (!showSelf) {
+          if (previous === undefined) this.hiddenSurfaceLayers.set(object!,object!.layers.mask);
+          object!.layers.mask = 0;
+        } else if (previous !== undefined) {
+          object!.layers.mask = previous;
+          this.hiddenSurfaceLayers.delete(object!);
+        }
+      }
       if (!obj.light) continue;
       const light = this.lights.get(obj.light);
       if (light) light.visible = this.sceneLights && visible;
@@ -1646,7 +1685,7 @@ export class BlenderRuntimeView {
     // the session correct its own tables BEFORE it decides what to ship.
     const held =
       this.frame === null ? null : { session: this.frame.session, revision: this.frame.revision };
-    const next = frameSchema.parse(input);
+    const next = expandDrawPlacements(frameSchema.parse(input));
     const staged = this.staged;
     if (staged && (staged.session !== next.session || staged.revision !== next.revision))
       throw new Error(`Blender frame manifest does not match its staged revision: staged ${JSON.stringify([staged.session, staged.revision])}, manifest ${JSON.stringify([next.session, next.revision])}`);
@@ -1849,7 +1888,9 @@ export class BlenderRuntimeView {
       });
     }
     for (const [id, data] of Object.entries(next.materials)) {
-      const material = this.materials.get(id) ?? new THREE.MeshPhysicalMaterial();
+      // Cycles intersects and shades both faces, including an arcade viewed
+      // from underneath. Three's front-face default drops those surfaces.
+      const material = this.materials.get(id) ?? new THREE.MeshPhysicalMaterial({ side: THREE.DoubleSide });
       material.name = data.name;
       // A LINKED BASE COLOUR REPLACES THE SOCKET'S VALUE, it does not multiply
       // it. Python's `_reduce` fills `color` from the Base Color socket's

package/browser/three/blender-single-scattering-sky.ts

@@ -71,6 +71,26 @@ function spectrumToXyz(spectrum: Float32Array): V {
   return [f(x * 20), f(y * 20), f(z * 20)];
 }
 
+/** SKY_single_scattering_precompute_sun: native spectral radiance at the
+ * bottom and top of the solar disc, before intensity and limb darkening. */
+export function precomputeSingleScatteringSun(p: SkyParameters, angularDiameter: number): [V, V] {
+  const diameter = f(angularDiameter), half = f(diameter / 2);
+  const solidAngle = f(TWO_PI * f(1 - f(Math.cos(half))));
+  if (!(solidAngle > 0) || f(p.sunElevation + half) <= 0) return [[0, 0, 0], [0, 0, 0]];
+  const origin: V = [0, 0, f(EARTH_RADIUS + Math.min(59999, Math.max(1, f(p.altitude))))];
+  const pixel = (elevation: number): V => {
+    const depth = opticalDepth(origin, direction(Math.max(0, elevation), 0));
+    const spectrum = new Float32Array(21);
+    for (let i = 0; i < 21; i++) {
+      const extinction = f(f(f(RAYLEIGH_COEFF[i]! * depth[0]) * f(p.airDensity)) +
+        f(f(f(f(1.11 * MIE_COEFF) * depth[1])) * f(p.aerosolDensity)));
+      spectrum[i] = f(f(IRRADIANCE[i]! * f(Math.exp(-extinction))) / solidAngle);
+    }
+    return spectrumToXyz(spectrum);
+  };
+  return [pixel(f(f(p.sunElevation) - half)), pixel(f(f(p.sunElevation) + half))];
+}
+
 function inscattering(ray: V, sun: V, origin: V, factors: V): V {
   const end = add(origin, scale(ray, atmosphereDistance(origin, ray)));
   const rayLength = length([f(end[0] - origin[0]), f(end[1] - origin[1]), f(end[2] - origin[2])]);

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/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

@@ -686,6 +686,13 @@ async function handle(request: WorkerRequest): Promise<unknown> {
       // 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.130",
   "publishConfig": {
     "access": "public"
   },