@volter/blender-engine 0.1.129 → 0.1.131

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

@@ -26,7 +26,7 @@ interface Binding {
   channels: Record<string, number>;
   borrowedFrom?: Binding;
   borrowedSource?: THREE.MeshPhysicalMaterial;
-  objectInfoUniforms?: {color: THREE.IUniform<THREE.Vector4>; indexRandom: THREE.IUniform<THREE.Vector2>};
+  objectInfoUniforms?: {color: THREE.IUniform<THREE.Vector4>; indexRandom: THREE.IUniform<THREE.Vector2>; particleRandom: THREE.IUniform<number>};
   palette?: {indices: Int32Array; sources: readonly THREE.MeshPhysicalMaterial[]};
 }
 const bindings = new WeakMap<THREE.MeshPhysicalMaterial, Binding>();
@@ -46,7 +46,7 @@ function compatiblePaletteGraphs(sources: readonly THREE.MeshPhysicalMaterial[])
   if (sources.length !== 2 || sources.some(source => pendings.has(source))) return null;
   const graphs = sources.map(source => bindings.get(source)?.compiled);
   const graph = graphs[0];
-  if (!graph || graph.objectInfo || failed.has(graph.key) || graphs.some(other => !other || other.key !== graph.key ||
+  if (!graph || graph.objectInfo || graph.particleInfo || failed.has(graph.key) || graphs.some(other => !other || other.key !== graph.key ||
       other.declarations !== graph.declarations || other.library !== graph.library ||
       JSON.stringify([other.uvs, other.attributes, other.outputs]) !== JSON.stringify([graph.uvs, graph.attributes, graph.outputs]))) return null;
   // Leave room for the physical material's environment and lighting samplers.
@@ -186,17 +186,20 @@ export function borrowGraphDrawBinding(source: THREE.MeshPhysicalMaterial, targe
  * belong to ONE object. A distinct material identity makes Three upload them
  * when it switches between objects sharing an authored material. */
 export function bindGraphObjectInfo(material: THREE.MeshPhysicalMaterial,
-  info: {color: readonly number[]; index: number; random: number}): void {
+  info: {color: readonly number[]; index: number; random: number; particle_random?: number}): void {
   const binding=bindings.get(material);
-  if (!binding?.compiled.objectInfo) return;
+  if (!binding || (!binding.compiled.objectInfo && !binding.compiled.particleInfo)) return;
+  if (binding.compiled.particleInfo && info.particle_random === undefined)
+    throw new Error('Particle Info Random input missing for Blender object');
   const values=binding.objectInfoUniforms ??= {
-    color:{value:new THREE.Vector4()}, indexRandom:{value:new THREE.Vector2()},
+    color:{value:new THREE.Vector4()}, indexRandom:{value:new THREE.Vector2()}, particleRandom:{value:0},
   };
   if (binding.uniforms['blenderObjectColor']!==values.color) {
-    binding.uniforms={...binding.uniforms,blenderObjectColor:values.color,blenderObjectIndexRandom:values.indexRandom};
+    binding.uniforms={...binding.uniforms,blenderObjectColor:values.color,blenderObjectIndexRandom:values.indexRandom, blenderParticleRandom:values.particleRandom};
   }
   values.color.value.fromArray(info.color);
   values.indexRandom.value.set(info.index,info.random);
+  if (info.particle_random !== undefined) values.particleRandom.value=info.particle_random;
 }
 
 /** A binding's values: uniforms, ramp tables and textures. */

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

@@ -49,7 +49,7 @@ export const GRAPH_NODE_TYPES = [
   'ShaderNodeGamma', 'ShaderNodeRGBToBW', 'ShaderNodeSeparateColor', 'ShaderNodeCombineColor',
   'ShaderNodeVectorRotate', 'ShaderNodeFresnel', 'ShaderNodeLayerWeight', 'ShaderNodeBump',
   'ShaderNodeNormalMap', 'ShaderNodeNewGeometry', 'ShaderNodeVertexColor', 'ShaderNodeAttribute',
-  'ShaderNodeRGBCurve', 'ShaderNodeVectorCurve', 'ShaderNodeFloatCurve', 'ShaderNodeObjectInfo',
+  'ShaderNodeRGBCurve', 'ShaderNodeVectorCurve', 'ShaderNodeFloatCurve', 'ShaderNodeObjectInfo', 'ShaderNodeParticleInfo',
 ] as const;
 
 const nodeSchema = z.object({
@@ -145,6 +145,7 @@ export interface CompiledGraph {
   readonly attributes: readonly string[];
   /** Requires a draw identity with this object's native inputs. */
   readonly objectInfo: boolean;
+  readonly particleInfo: boolean;
   /** Which surface inputs the graph drives, each a GLSL global of `type`. */
   readonly outputs: Readonly<Record<string, {readonly global: string; readonly type: GpuType}>>;
   readonly surface: MaterialGraph['surface'];
@@ -433,6 +434,8 @@ class Compiler {
     const [key, index] = source.link;
     const node = this.graph.nodes[key];
     if (!node) throw new Error(`The graph links to ${key}, which it does not carry`);
+    if (node.type === 'ShaderNodeParticleInfo' && node.outputs[index]?.id !== 'Random')
+      throw new Error(`Particle Info output ${node.outputs[index]?.id ?? index} is not compiled by the presenter`);
     const outputs = this.node(key, node);
     const output = outputs[index];
     if (!output) throw new Error(`${key} has no output ${index}`);
@@ -489,6 +492,12 @@ class Compiler {
         body.push(`${outputs[0]!.name} = ${this.uniform(type, prop<number | number[]>(node, 'value'))};`);
         break;
       }
+      case 'ShaderNodeParticleInfo': {
+        // Cycles uses the originating particle's index hash, not Object Info
+        // Random. The exporter refuses other outputs until their data travels.
+        body.push(`${outputs[1]!.name} = blenderParticleRandom;`);
+        break;
+      }
       case 'ShaderNodeObjectInfo': {
         // node_shader_gpu_object_info / node_object_info. Location is the
         // object's origin, never the current fragment's world position.
@@ -959,6 +968,8 @@ class Compiler {
     const program = [
       ...(Object.values(this.graph.nodes).some(n=>n.type==='ShaderNodeObjectInfo')
         ? ['uniform vec4 blenderObjectColor;', 'uniform vec2 blenderObjectIndexRandom;'] : []),
+      ...(Object.values(this.graph.nodes).some(n=>n.type==='ShaderNodeParticleInfo')
+        ? ['uniform float blenderParticleRandom;'] : []),
       ...[...this.s.uniformTypes].map(([n, t]) => `uniform ${t} ${n};`),
       ...this.images.map(i => i.tiled
         ? `uniform highp sampler2DArray ${i.uniform};\nuniform highp sampler2D ${i.uniform}Map;`
@@ -980,6 +991,7 @@ class Compiler {
       uvs: [...this.s.uvs],
       attributes: [...this.s.attributes],
       objectInfo: Object.values(this.graph.nodes).some(n=>n.type==='ShaderNodeObjectInfo'),
+      particleInfo: Object.values(this.graph.nodes).some(n=>n.type==='ShaderNodeParticleInfo'),
       outputs,
       surface: this.graph.surface,
       closure: closure !== undefined,

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-physical-material.ts

@@ -7,6 +7,7 @@ import {z} from 'zod';
 import {applyGraphShader, bindGraphDraw, bindPaletteGraph, borrowGraphDrawBinding, graphProgramKey, graphUvChannels, setGraphViewport} from './blender-graph-material';
 import type {CompiledGraph} from './blender-node-graph';
 import {bindNamedUvChannels} from './blender-texture-samplers';
+import {copyWorldVisibility,worldVisibilityShader,worldVisibilityUniforms} from './blender-world-visibility';
 
 const scalar = z.number().finite();
 const color = z.tuple([scalar, scalar, scalar]);
@@ -55,6 +56,7 @@ function graphShadow(material: THREE.MeshPhysicalMaterial): THREE.MeshPhysicalMa
   // which `copy` replaces with the material's own (it leaves hooks alone).
   applyPhysicalMaterial(shadow);
   shadow.copy(material);
+  copyWorldVisibility(material,shadow);
   const values = uniforms.get(shadow)!;
   if (held) {
     values.blenderCoatIor.value = held.blenderCoatIor.value;
@@ -149,6 +151,7 @@ export function syncPhysicalDrawMaterial(source: THREE.Material, target?: THREE.
     return null;
   }
   copy.copy(source);
+  copyWorldVisibility(source,copy);
   const held = uniforms.get(source)!;
   const values = uniforms.get(copy)!;
   values.blenderCoatIor.value = held.blenderCoatIor.value;
@@ -192,7 +195,7 @@ export function applyPhysicalMaterial(material: THREE.MeshPhysicalMaterial, inpu
       blenderWorldExtinction: {value: new THREE.Vector3()}};
     uniforms.set(material, values);
     const held = values;
-    material.customProgramCacheKey = () => `blender-principled-physical-v5${graphProgramKey(material)}`;
+    material.customProgramCacheKey = () => `blender-principled-physical-v6${graphProgramKey(material)}`;
     material.onBeforeRender = (renderer, scene, camera, geometry, object) => {
       bindNamedUvChannels(material, geometry);
       bindGraphDraw(material, geometry, renderer, scene, camera, object, graphShadow);
@@ -210,6 +213,12 @@ export function applyPhysicalMaterial(material: THREE.MeshPhysicalMaterial, inpu
         .map(i => (i <= 3 ? `#ifndef USE_UV${i}\nattribute vec2 uv${i};\n#endif` : `attribute vec2 uv${i};`))
         .join('\n') + '\n' + shader.vertexShader;
       Object.assign(shader.uniforms, held);
+      worldVisibilityUniforms(material,shader.uniforms);
+      shader.vertexShader='varying vec3 blenderWorldPosition;\n'+shader.vertexShader;
+      shader.vertexShader=shader.vertexShader.replace('#include <worldpos_vertex>',
+        '#include <worldpos_vertex>\n#if defined(USE_ENVMAP) || defined(USE_SHADOWMAP) || defined(USE_TRANSMISSION)\nblenderWorldPosition=worldPosition.xyz;\n#else\nblenderWorldPosition=(modelMatrix*vec4(transformed,1.)).xyz;\n#endif');
+      shader.fragmentShader=shader.fragmentShader.replace('#include <envmap_physical_pars_fragment>',
+        '#include <envmap_physical_pars_fragment>\n'+worldVisibilityShader);
       shader.fragmentShader = `uniform float blenderCoatIor;
         uniform vec3 blenderWorldExtinction;
         vec3 blenderInfiniteTransmission() { return vec3(
@@ -255,6 +264,10 @@ export function applyPhysicalMaterial(material: THREE.MeshPhysicalMaterial, inpu
           'rectAreaLight = rectAreaLights[ i ]; rectAreaLight.color *= exp(-blenderWorldExtinction * length(rectAreaLight.position-geometryPosition));')
         .replace('getAmbientLightIrradiance( ambientLightColor )', 'getAmbientLightIrradiance( ambientLightColor ) * blenderInfiniteTransmission()');
       const environment = THREE.ShaderChunk.lights_fragment_maps
+        .replace('getIBLIrradiance( geometryNormal )',
+          'blenderWorldIrradiance( geometryNormal, getIBLIrradiance( geometryNormal ) )')
+        .replaceAll(/(getIBL(?:Radiance|AnisotropyRadiance)\([^;]+\))/g,
+          '$1 * blenderWorldReflectionVisibility(geometryViewDir,geometryNormal,material.roughness)')
         .replaceAll(/(getIBL(?:Irradiance|Radiance|AnisotropyRadiance)\([^;]+\))/g, '$1 * blenderInfiniteTransmission()');
       shader.fragmentShader = shader.fragmentShader.replace('#include <lights_physical_fragment>', physical)
         .replace('#include <lights_fragment_begin>', lighting)

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,14 @@ 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 {
+  lightingTexture():THREE.Texture|null {return this.environmentTexture??this.texture;}
+  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 +797,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 +808,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 +827,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 +859,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-shadows.ts

@@ -58,6 +58,11 @@ export function fitModelDirectionalShadow(
   casters: THREE.Box3[],
 ): void {
   if (!light.castShadow || !receivers.length) return;
+  // A detached photograph fits before its first render. Newly composed suns
+  // and their targets have not yet passed through Scene.updateMatrixWorld;
+  // fitting in those stale axes produces a different map on the first draw.
+  light.updateWorldMatrix(true, false);
+  light.target.updateWorldMatrix(true, false);
   light.shadow.updateMatrices(light);
   const camera = light.shadow.camera;
   const view = camera.matrixWorldInverse;

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';
@@ -25,6 +26,7 @@ import {
   worldSchema,
 } from './blender-runtime-lighting';
 import { fitModelDirectionalShadow, visibleShadowReceivers } from './blender-runtime-shadows';
+import {BlenderWorldVisibility,bindWorldVisibility} from './blender-world-visibility';
 import { volumeMesh, volumeSchema } from './blender-runtime-volume';
 import { applyPhysicalMaterial, applyWorldExtinction, physicalMaterialSchema } from './blender-physical-material';
 import { prepareGraphGeometry, setMaterialGraph } from './blender-graph-material';
@@ -490,6 +492,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 +528,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(),
@@ -669,6 +682,7 @@ export class BlenderRuntimeView {
   private readonly lights = new Map<string, THREE.Light>();
   private readonly lighting = new ViewportLighting();
   private readonly world = new WorldBackground();
+  private readonly worldVisibility=new BlenderWorldVisibility();
   /**
    * THE INSPECTION OVERLAYS (I4). They are NOT children of {@link root}, and
    * that is the whole design: an overlay is EDITOR FURNITURE, so its
@@ -701,10 +715,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 +739,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
@@ -1319,6 +1335,13 @@ export class BlenderRuntimeView {
       // objects. Fit shadows for that draw, rather than the camera's pose
       // when Rendered shading was first entered. Captures use this path too.
       if (this.rendered) this.applyShadows(true, camera);
+      this.worldVisibility.sync(this.objects.values(),this.world.lightingTexture(),this.root,this.rendered);
+      for(const material of [...this.materials.values(),this.fallback])bindWorldVisibility(material,this.worldVisibility);
+      for(const object of this.objects.values()) {
+        const mesh=object as THREE.Mesh;if(!mesh.isMesh)continue;
+        for(const material of Array.isArray(mesh.material)?mesh.material:[mesh.material])bindWorldVisibility(material,this.worldVisibility);
+      }
+      if(options?.renderer)this.worldVisibility.prepare(options.renderer);
       const opaqueDone = performance.now();
       const motion = this.motionGeometry.prepare(camera, !this.rendered && (this.mode ?? this.frame?.mode) === 'OBJECT' &&
         options?.interactive === true, options?.height ?? 0);
@@ -1418,6 +1441,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 +1466,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 +1481,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 +1510,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 +1613,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 +1694,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 +1897,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
@@ -2181,7 +2231,7 @@ export class BlenderRuntimeView {
   }
 
   drawStatistics() {
-    return {enabled: this.drawBatching, preparation: {...this.drawPreparation}, materialRanges: this.materialRanges.inspect(), opaque: this.instances.inspect(), transparent: this.transparentInstances.inspect(), motion: this.motionGeometry.inspect()};
+    return {enabled: this.drawBatching, preparation: {...this.drawPreparation}, worldVisibility:this.worldVisibility.diagnostics(), materialRanges: this.materialRanges.inspect(), opaque: this.instances.inspect(), transparent: this.transparentInstances.inspect(), motion: this.motionGeometry.inspect()};
   }
 
   snapshot() {
@@ -2363,6 +2413,10 @@ export class BlenderRuntimeView {
         if (disposed) throw new Error('Blender capture snapshot is disposed');
         return detached.setRendered(true, camera);
       },
+      prepareDraw:(renderer:THREE.WebGLRenderer,camera:THREE.Camera)=>{
+        if(disposed)throw new Error('Blender capture snapshot is disposed');
+        return detached.prepareDraw(camera,{interactive:false,height:renderer.domElement.height,renderer});
+      },
       dispose,
     };
   }
@@ -2411,6 +2465,7 @@ export class BlenderRuntimeView {
   }
 
   private clear() {
+    this.worldVisibility.dispose();
     this.objectInfoMaterials.clear();
     this.materialRanges.clear();
     this.motionGeometry.clear();

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])]);