3D engine that AI agents drive
Add a physical sky driven by the sun (issue #705)
Nguyen Xuan An5c679ce76bb4
diff --git a/changes/705-physical-sky.md b/changes/705-physical-sky.mdnew file mode 100644index 00000000..a5fbbeda--- /dev/null+++ b/changes/705-physical-sky.md@@ -0,0 +1 @@+- `environment.sky: { type: 'physical', sunElevation, sunRotation, turbidity, groundAlbedo, aerialPerspective }` drives the key light direction and colour, the sky map, the background gradient and the distance haze from one sun, so a time of day is one parameter. Recipes without `sky` render byte for byte as before. (#705)diff --git a/changes/705-physical-sky.size.md b/changes/705-physical-sky.size.mdnew file mode 100644index 00000000..2bb0841b--- /dev/null+++ b/changes/705-physical-sky.size.md@@ -0,0 +1 @@+- scene:agent-scene+lazy: the physical sky model, its sky map and the recipe fields load only for a recipe that names environment.sky; the core entry shrank by 20 bytes.diff --git a/docs/agent-look.md b/docs/agent-look.mdindex 2d93bf1c..8e24b55d 100644--- a/docs/agent-look.md+++ b/docs/agent-look.md@@ -123,6 +123,7 @@ Sky colors use display RGB, matching the renderer's existing environment contrac| `ground` | on | Absent unless set. `false` removes the preview's automatic floor and contact shadow || `resolveCoplanar` | off | `'offset'` puts the smaller part of each coplanar pair (see the `coplanar-overlap` warning) on the next depth layer, drawn with a polygon offset; `false` or absent leaves parts as authored. Geometry never moves. Parts that set `decal` or `depthLayer` keep their own || `objectReflections` | on | Absent unless set. Each smooth metal part (`metallic` 0.5 or more, `roughness` 0.6 or less; at most 8 such parts) gets a reflection probe of the scene around it, so a chrome sphere shows the floor and its neighbours. `false` turns it off. Probes are traced at rest, so a part that moves reflects the scene as it started. `scene_inspect` names them in `reflections` |+| `sky` | absent | Absent unless set. `{ type: 'physical', sunElevation, sunRotation, turbidity, groundAlbedo, aerialPerspective }`: one time-of-day control. `sunElevation` -90 to 90 degrees (default 45), `sunRotation` degrees clockwise from -Z seen from above (0), `turbidity` 1 to 10 haze (3), `groundAlbedo` 0 to 1 (0.3), `aerialPerspective` 0 to 4 scales the distance haze (1; 0 for none). The sky sets `lightDirection`, `keyColor` (the sun reddens and dims with air mass and sets below the horizon), `skyTop`, `skyBottom`, `fogColor` and `fogDensity`, and replaces the setup's environment map with the sky, so those fields no longer take your values while a sky is set. A `set-environment` patch changes the fields it names and keeps the rest; `sky: null` in a patch keeps the last derived values as plain fields. It is an analytic single-scattering approximation (Rayleigh and aerosol, Kasten-Young air mass), not Blender's Nishita integration: no ozone, no sun disc, no clouds. Raster first: the path tracer backends read the same environment map and key light, but are not yet checked against it. || `floorSkyTrace` | on | Absent unless set. A closed room a sun lights gets the sky each floor texel sees traced into its floor (`applyFloorSkyVisibility`, strength 0.2), so shadowed floors under a roof or between walls get less world and sky light; it makes the dark end of halls closer to Cycles. Open scenes and rooms lit by lamps alone are left as they are. `false` turns it off; a value that is not a boolean is refused. It loads lazily with a recipe that names its sun (`keyColor` or `keyIntensity`), costs about 1 s of trace when the scene is built and adds triangles to the floor (0.1 to 0.4 ms per frame in the reference halls). || `specularAntiAliasing` | `1` | Absent unless set. `0` to `4`. Widens highlights where the shading normal or normal map detail changes within a pixel (geometric specular anti-aliasing plus a Toksvig term read from the filtered normal map length), so grainy or scanned metal stops sparkling from frame to frame at grazing angles. `0` gives a highlight that follows every texel; above `1` is softer. || `sunBounce` | `1` | Absent unless set. A number of 0 or more. A closed room a sun lights gets a few point lights at its sunlit patches (`withSunBounce`, found when the scene is prepared), so the floor, walls and pillars around a patch are lit by the light it bounces and the far end of the room less. `0` turns it off and gives the look without it; `1` is fitted to Cycles; above `1` is stronger. A value that is not a number of 0 or more is refused. Open scenes and rooms with no sun are left as they are. It loads lazily with the sun, and the lights take up to 6 of the 16 point light slots. |diff --git a/docs/parity.md b/docs/parity.mdindex 8e15b374..8563bf3a 100644--- a/docs/parity.md+++ b/docs/parity.md@@ -192,7 +192,7 @@ To move to a new Blender release, run `node scripts/parity-manual-snapshot.mjs`.| Rendering > Cameras | partial | Perspective, orthographic views, focal length, animated paths, depth of field from depth and camera motion blur, both repeatable per frame. Object motion blur and bokeh shapes are missing. | [camera-path](../tests/camera-path.test.js), [camera](../tests/camera.test.js), [render-passes](../tests/render-passes.test.js) | #54 || Rendering > Lights > Light Objects | partial | One directional light with a shadow, 16 point lights, 8 spot lights and 7 rectangular area lights. Point and spot lights can cast shadows from one 24-tile atlas (a point light takes 6 tiles, a spot light 1). Area lights use a representative point and cast a soft shadow with `castShadow: true`. The directional shadow is a single map, or up to four cascades through `addons/cascaded-shadows` (`shadowCascades` on the renderer and `environment.shadowCascades` in recipes, three by themselves when `shadow.extent` is above 40): scene `long-street` scores 0.1555 against Cycles with one map and 0.1398 with three cascades, for about 0.2 ms more a frame on an RTX 3060 when the camera moves. | [lighting](../tests/lighting.test.js), [cascades](../tests/cascaded-shadows.test.js), `npm run reference` scenes `spot-area` and `long-street` | #52 || Rendering > Lights > Light Linking | partial | `addons/light-linking`: a light's `affects` list (and `environment.keyAffects` for the sun) limits it to the named parts through `applyLightLinks`, as a Blender receiver collection does; the shader skips a light whose bit in the part's mask is clear. Linking changes what a light adds, not what it shadows. The path tracer (issue #215) and the light bake honour it, and recipes reach it through `affects` and `environment.keyAffects` (`lightLinking` in `scene_capabilities`). There is no blocker list. Scene `light-linking` scores 0.0998 against Cycles. | [light-linking](../tests/light-linking.test.js), `npm run reference` scene `light-linking` | #52 |-| Rendering > Lights > World Environment | partial | Recipes pick a named setup (`daylight`, `overcast`, `sunset`, `studio`) that carries a procedural environment map, with opt-in screen-space ambient occlusion. Code can load any HDRI; recipes reach only the named maps, with no URLs or files. No reflections between objects yet. The MCP preview adds an automatic floor with a contact shadow (`environment.ground: false` removes it). Cold-run reference-free score for sitting on a surface, summed over six tasks and 0 to 3 each: 0 before, 6 with the floor and 7 after a lone flat object (a gear) stopped being read as a floor; the front and side cameras see it edge-on, so only the three-quarter view shows it. A blind pairwise Sonnet judge (`default-judge.mjs`, six cold recipes, two cameras, 18 calls) prefers the floor to none 18 of 18 (p 0.0000076) and the darker floor now used (0.22) to the first one (0.6) 18 of 18; its control, one image against itself, picks the first 17 of 18. | [environment](../tests/environment.test.js), [default look](../tests/default-look.test.js) | #53 |+| Rendering > Lights > World Environment | partial | `environment.sky` `{ type: 'physical', sunElevation, sunRotation, turbidity, groundAlbedo, aerialPerspective }` drives the key light, background and distance haze from the sun (an analytic approximation of Blender's sky texture: no ozone, sun disc or clouds; [physical sky](../tests/physical-sky.test.js)). Recipes pick a named setup (`daylight`, `overcast`, `sunset`, `studio`) that carries a procedural environment map, with opt-in screen-space ambient occlusion. Code can load any HDRI; recipes reach only the named maps, with no URLs or files. No reflections between objects yet. The MCP preview adds an automatic floor with a contact shadow (`environment.ground: false` removes it). Cold-run reference-free score for sitting on a surface, summed over six tasks and 0 to 3 each: 0 before, 6 with the floor and 7 after a lone flat object (a gear) stopped being read as a floor; the front and side cameras see it edge-on, so only the three-quarter view shows it. A blind pairwise Sonnet judge (`default-judge.mjs`, six cold recipes, two cameras, 18 calls) prefers the floor to none 18 of 18 (p 0.0000076) and the darker floor now used (0.22) to the first one (0.6) 18 of 18; its control, one image against itself, picks the first 17 of 18. | [environment](../tests/environment.test.js), [default look](../tests/default-look.test.js) | #53, #705 || Rendering > Materials > Components | partial | Surfaces with PBR factors and five maps, a clear coat, transmission with thickness, attenuation and IOR, sheen, and specular weight and tint. Anisotropic highlights and a thin-film iridescence layer, as in the glTF extensions, are compiled in only when a part uses them. Subsurface scattering (the `subsurface` block: weight, radius, scale, color; sun light only in the rasterizer, compiled in only when a part uses it) approximates skin, wax and leaves; the CPU path tracer traces it as a bounded Random Walk (at most 32 scattering events, thin cards as translucency), and so does the GPU tracer. In the `subsurface` reference scene, scored against the Cycles render with subsurface on, the path tracer gets 0.0795 with weight 1 and 0.0875 with weight 0 (64 samples, 28.8 s against 20.7 s; the GPU tracer 0.0795 and 0.0876), the rasterizer 0.1180 and 0.1229. There is no volume material or displacement. | [texture-set](../tests/texture-set.test.js), [material-layers](../tests/material-layers.test.js) | #50, #51 || Rendering > Materials > Assignment | done | A node names one material. | [agent-scene](../tests/agent-scene.test.js) | || Rendering > Materials > Preview | out of scope | Interface for a person. Agents use `scene_look`. | | |diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjsindex 6e657d68..1af9af0b 100644--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@ -284,10 +284,11 @@ const environment = z.strictObject({resolveCoplanar: z.union([z.literal('offset'), z.literal(false)]).optional().describe("'offset' biases the smaller part of each coplanar pair at draw time; false clears."),viewTransform: z.enum(VIEW_TRANSFORM_NAMES).optional().describe('Display transform, for example agx to compare with Blender.'),look: z.union([z.enum([...LOOK_NAMES, ...BUNDLED_CUBE_LOOK_NAMES]), z.string().regex(CATALOG_FILE_ID)]).nullable().optional().describe('Look preset or .cube; scene_capabilities catalogLooks. null clears.'),+ sky: z.record(z.string(), z.unknown()).nullable().optional().describe('Physical sky: {type:"physical", sunElevation, sunRotation, turbidity, groundAlbedo, aerialPerspective}; sets key light, sky and fog. Fields in scene_capabilities physicalSky.'),wind: z.strictObject({ strength: bounded(0, 4).optional(), direction: bounded(-360, 360).optional().describe('Degrees: 0 toward +x, 90 toward +z.') }).optional().describe('Sway of foliage and grass materials; strength defaults to 0.3.'),});// Every tool lists the same short environment; the full schema is served by scene_capabilities topic environment.-const environmentListed = listed('environment', environment, 'Lighting and sky. More fields: hdri, look, viewTransform, keyColor, keyIntensity, fillIntensity, ambientIntensity, daylight, keyAffects, shadowCascades, pointLights, spotLights, areaLights, skyTop, skyBottom, fogColor, fogDensity, volumeFog (density, scatterOctaves, multiScatter, keyTransmittance, surfaceTransmittance and more: scene_capabilities environment), liquid, lines, wind, objectReflections, floorSkyTrace, sunBounce, specularAntiAliasing, resolveCoplanar; see scene_capabilities environment.', coreOf(environment.shape, ['setup', 'world', 'ground', 'lightDirection', 'environmentIntensity']));+const environmentListed = listed('environment', environment, 'Lighting and sky. More fields: sky (physicalSky), hdri, look, viewTransform, keyColor, keyIntensity, fillIntensity, ambientIntensity, daylight, keyAffects, shadowCascades, pointLights, spotLights, areaLights, skyTop, skyBottom, fogColor, fogDensity, volumeFog (density, scatterOctaves, multiScatter, keyTransmittance, surfaceTransmittance and more: scene_capabilities environment), liquid, lines, wind, objectReflections, floorSkyTrace, sunBounce, specularAntiAliasing, resolveCoplanar; see scene_capabilities environment.', coreOf(environment.shape, ['setup', 'world', 'ground', 'lightDirection', 'environmentIntensity']));// Named post steps are checked by the engine and listed in docs/agent-look.md; every tool that takes a recipe repeats this schema.const looseField = z.unknown().optional();const effects = z.strictObject({diff --git a/src/agent-look.js b/src/agent-look.jsindex a651b2a0..89771f3e 100644--- a/src/agent-look.js+++ b/src/agent-look.js@@ -16,7 +16,7 @@ const MAX_LOOK_ARRAY_ENTRIES = Math.max(MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, MAX_Aconst ENVIRONMENT_FIELDS = ['world', 'ground', 'setup', 'hdri', 'environmentIntensity', 'environmentRotation', 'lightDirection', 'keyColor', 'keyIntensity', 'fillIntensity', 'ambientIntensity',- 'daylight', 'pointLights', 'spotLights', 'areaLights', 'skyTop', 'skyBottom', 'fogColor', 'fogDensity', 'volumeFog', 'liquid', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'sunBounce', 'specularAntiAliasing', 'sunAngularRadius', 'lines', 'resolveCoplanar', 'viewTransform', 'look', 'wind',+ 'daylight', 'pointLights', 'spotLights', 'areaLights', 'skyTop', 'skyBottom', 'fogColor', 'fogDensity', 'volumeFog', 'liquid', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'sunBounce', 'specularAntiAliasing', 'sunAngularRadius', 'lines', 'resolveCoplanar', 'viewTransform', 'look', 'wind', 'sky',];const EFFECT_FIELDS = ['exposure', 'saturation', 'contrast', 'temperature', 'vignette', 'grain', 'ambientOcclusion', 'ambientOcclusionRadius', 'bloom', 'depthOfField', 'motionBlur'];const SHADOW_FIELDS = ['target', 'extent', 'distance', 'near', 'far'];@@ -347,6 +347,9 @@ function environmentFrom(input = {}) {knownKeys(input.liquid, Object.keys(LIQUID_OPTICS), 'liquid');environment.liquid = copiedJson(resolveLiquidOptics(copiedJson(input.liquid)));}+ if (input.sky !== undefined && input.sky !== null) {+ agentSceneModule('physicalSky').applyPhysicalSky(input.sky, environment, invalidField);+ }lightShapeSupport.normalize?.(input, environment);updateLightingState(createLightingState(), environment, { world });return environment;@@ -365,6 +368,9 @@ export function environmentPatchWithSetup(patch) {/** The procedural environment map that lights a normalized environment; the same object returns while inputs hold. */export function agentEnvironmentMap(environment) {+ if (environment.sky) {+ return agentSceneModule('physicalSky').createPhysicalSkyMap(environment);+ }if (environment.hdri) {return createCatalogEnvironmentMap(environment.hdri, { intensity: environment.environmentIntensity, rotation: environment.environmentRotation, showBackground: environment.world });}diff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.jsindex 72952b94..9301c232 100644--- a/src/agent-scene-capabilities.js+++ b/src/agent-scene-capabilities.js@@ -161,7 +161,7 @@ export const MESH_MODIFIER_NOTES = Object.freeze({// Vertex colors and groups. Details stay here so the tool schemas stay small.export const MESH_ATTRIBUTE_NOTES = Object.freeze({- vertex_group: 'name (required) sets the weights 0-1 of the vertices of the selected faces; the rest keep theirs (0 in a new group). One of weight (1), field (number expression) or gradient { axis x|y|z, range [low, high], weights [atLow, atHigh] }. Max 32 groups. displace takes group: name and scales each move by the weight; cloth takes pinGroup. Put it after shape edits: a stack node that rebuilds the mesh drops groups.',+ vertex_group: 'name (required) sets the weights 0-1 of the vertices of the selected faces; the rest keep theirs. One of weight (1), field (number expression) or gradient { axis x|y|z, range [low, high], weights [atLow, atHigh] }. Max 32 groups. displace takes group: name (scales each move by the weight); cloth takes pinGroup. Put it after shape edits: a node that rebuilds the mesh drops groups.',vertex_color: 'sets the corner colors (0-1, linear, white until set) of the selected faces. One of color [r, g, b], field (vector expression of the vertex) or gradient { axis, range [low, high], colors [[r,g,b] atLow, [r,g,b] atHigh] }. Drawn, written as COLOR_0 in a GLB, and multiplies the material color.',});@@ -181,8 +181,8 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({geometryTypes: Object.freeze(['box', 'cylinder', 'sphere', 'cone', 'icoSphere', 'torus', 'lathe', 'extrude', 'tube', 'curve', 'text', 'grid', 'plane', 'circle', 'line', 'terrain', 'mesh']),camera: 'eye, target, up, near, far, then fov (vertical degrees) or focalLength (mm, with sensorWidth mm, default 36; not both). projection orthographic with orthoScale (view height in m, default 4). shift [x, y] moves the frame by a fraction of its width and height. fStop (0.7 to 64) turns on depth of field focused on target; 1.4 or lower is full blur, and effects.depthOfField.blur must stay 0. Orthographic and shifted cameras render with the rasterizer, not the path tracer.',terrain: 'One mesh, x and z from -size/2 to size/2, hills about y = 0. size 40 m (1-2000), resolution 64 cells (2-256), seed 1, amplitude 1 m (0-200), holes up to 16 of {center:[x,z],radius} with no surface inside; radius a few cells or more.',- placedAssets: 'Node field asset:{id,materials?,clip?,drive?} turns a group node into a catalog GLB (id from asset_catalog). Its transform places it. materials:[{name,color,metallic,roughness,opacity,emission,emissiveColor}] override source materials by name. clip:{index,start=0,speed=1,loop=true} plays that clip from scene time start on a decoded copy of its own; set-motion tracks move the node and scene time seeks the clip. drive:{path | legs, cruiseSpeed | speed, wheels, lights} drives a car along a path in the placement frame on a decoded copy (fields as motion.drive in an asset recipe, docs/vehicle.md). scene_inspect assets adds wheels, rejectedNames and light signals. At most 512 placements, 16 assets, 16 playing a clip or driving.',- navigation: 'scene_inspect path:{ground,from:[x,z],to:[x,z]} returns a route over the ground node around its holes, steep slopes and the nodes in avoid:[ids] (box footprints), as keyframes [{time,value:[x,y,z]}] for a translation track with interpolation LINEAR. radius 0.3 m keeps the walker off holes and avoided nodes; maxSlope 40 degrees; cellSize defaults to radius; give seconds for the whole walk or speed (1.4 m/s); lift raises y.',+ placedAssets: 'Node field asset:{id,materials?,clip?,drive?} turns a group node into a catalog GLB (id from asset_catalog). materials:[{name,color,metallic,roughness,opacity,emission,emissiveColor}] override source materials by name. clip:{index,start=0,speed=1,loop=true} plays that clip from scene time start. drive:{path | legs, cruiseSpeed | speed, wheels, lights} drives a car along a path in the placement frame (fields as motion.drive, docs/vehicle.md). scene_inspect assets adds wheels, rejectedNames, light signals. At most 512 placements, 16 assets, 16 playing a clip or driving.',+ navigation: 'scene_inspect path:{ground,from:[x,z],to:[x,z]} returns a route over the ground node around holes, steep slopes and the nodes in avoid:[ids], as keyframes [{time,value:[x,y,z]}] for a translation track with interpolation LINEAR. radius 0.3 m keeps the walker off holes and avoided nodes; maxSlope 40 degrees; cellSize defaults to radius; seconds for the whole walk or speed (1.4 m/s); lift raises y.',meshEdits: Object.freeze({ operations: Object.freeze(Object.keys(MESH_EDIT_OPERATIONS)), maxEdits: MAX_MESH_EDITS }),meshStack: Object.freeze({ operations: STACK_OPERATIONS, maxNodes: MAX_STACK_NODES }),meshModifiers: MESH_MODIFIER_NOTES,@@ -230,14 +230,15 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({// (mesh_inspect gives localToWorldScale and localAxesInWorld) on a welded mesh with axis tags and a material tag.importedMeshEdits: Object.freeze({...IMPORTED_MESH_EDIT_LIMITS,- transfer: 'New vertices take skin weights, morph deltas and colours from the nearest original surface point; faces left without UVs read the nearest original UV island. Not supported: mesh_stack, relations, instancing.',- rejects: 'On a skinned or morphed part an edit farther than maxTransferFraction of the part bounds diagonal from the original surface; booleans on open parts (fill_holes first).',+ transfer: 'New vertices take skin weights, morph deltas and colours from the nearest original surface point; faces without UVs read the nearest UV island. Unsupported: mesh_stack, relations, instancing.',+ rejects: 'Skinned or morphed part: an edit farther than maxTransferFraction of the bounds diagonal from the original surface; booleans on open parts (fill_holes first).',}),fixedResources: false, dynamicTopology: true, checkpoints: true, positiveScaleOnly: true,gltfImport: 'Optional extensions and line primitives load with a warning; unlit and punctual lights are read.',authoredLook: true, maxPointLights: MAX_POINT_LIGHTS,catalogLooks: Object.freeze({ hdri: 'environment.hdri', hdris: BUNDLED_ENVIRONMENT_NAMES, cubeLooks: BUNDLED_CUBE_LOOK_NAMES, look: 'environment.look', catalogId: '64-hex ID of a .hdr or .cube in scene_asset_catalog', note: 'environmentIntensity and environmentRotation apply; keyIntensity 0 if the HDRI has a sun' }),- lightingSetups: LIGHTING_SETUP_NAMES, defaultLightingSetup: DEFAULT_LIGHTING_SETUP,+ physicalSky: 'environment.sky {type:physical, sunElevation, sunRotation, turbidity, groundAlbedo, aerialPerspective} drives key, sky, fog',+ lightingSetups: LIGHTING_SETUP_NAMES,defaultLightingSetup: DEFAULT_LIGHTING_SETUP,ambientOcclusion: Object.freeze({ default: DEFAULT_AMBIENT_OCCLUSION, defaultRadius: 0.5, off: 0 }),// Local lights: spot and rectangular area lights. Shadows share one 2048 x 3072 depth atlas of 24 tiles; a shadowed// point light uses 6 tiles and a shadowed spot light 1. Area lights cast no shadow. Recipes reach light linking and cascaded sun shadows through lightLinking and shadowCascades below.@@ -284,12 +285,12 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({cloth: Object.freeze({sheetGeometry: 'grid { segments 1-64 }: unit sheet in XY facing +Z, sized by node scale; any triangle mesh works',defaults: Object.freeze({ stiffness: 0.9, bend: 0.1, density: 0.2, damping: 0.3, friction: 0.3, thickness: 0.01, colliderShape: 'box' }),- notes: 'density kg/m2, damping 1/s, thickness m, wind m/s steady. Pin edges are of the local bounds. Colliders { node, shape ball|box } are fixed fits to geometry bounds and, like sheets, root nodes without a motion track or body. Moving: { attach, shape ball|capsule, radius, offset, to, toOffset } or { armature, radiusFraction, exclude }. Sheet pinGroup names a sheet vertex group whose vertices (weight 0.5 or more) are held. Sheet pinTo { node, weight } rides pinned edges on a node. No self collision.',+ notes: 'density kg/m2, damping 1/s, thickness m, wind m/s steady. Colliders { node, shape ball|box } fit geometry bounds; like sheets they are root nodes without a motion track or body. Moving: { attach, shape ball|capsule, radius, offset, to, toOffset } or { armature, radiusFraction, exclude }. Sheet pinGroup: a vertex group whose vertices (weight 0.5 or more) are held. Sheet pinTo { node, weight } rides pinned edges on a node. No self collision.',limits: Object.freeze({ maxSheets: 8, maxColliders: 16, maxMovingColliders: 64, maxDuration: 10, maxParticles: 5000, framesPerSecond: 60, substeps: 4, iterations: 8 }),}),// Recipe particles: closed-form from seeded launch values, so any time is computed directly and a seek never replays.particles: Object.freeze({- emitter: 'System node keeps its geometry as the particle shape; node transform does not move particles. Fields (defaults): node, seed (1), count (100), rate (per second; omit for a burst at 0), lifetime, speed, size (number or [min, max]; 1, 1, 0.05), direction ([0,1,0]), spread (cone degrees, 30), emitter { shape point|box|sphere|disc, position, halfExtents, radius }, scale constant|shrink|grow, drag (1/s, 0), floor (world y particles land on).',+ emitter: 'System node geometry is the particle shape; its transform does not move them. Fields (defaults): node, seed (1), count (100), rate (per second; omit: burst at 0), lifetime, speed, size (number or [min, max]; 1, 1, 0.05), direction ([0,1,0]), spread (cone degrees, 30), emitter { shape point|box|sphere|disc, position, halfExtents, radius }, scale constant|shrink|grow, drag (1/s, 0), floor (world y they land on).',hair: 'type hair grows strands from a read-only root surface node into node (its own geometry is ignored). Fields (defaults): surface, seed, count, length (m, number or [min, max], 0.1), segments (1-8, 4), width (m, 0.004), droop (0.5), lean (0.2), sway (tip travel m, off), swayRate (Hz, 0.5). Tapering tubes, no UVs.',sectionFields: 'systems, gravity ([0,-9.81,0]), wind (m/s; moves emitter particles only with drag > 0, and sets the hair sway direction), fields (also cloth; wind, turbulence, vortex, drag, magnet: docs/physics.md)',collision: 'colliders [node ids], bounce 0-1 (0.3 with colliders), friction 0-1 (0.5), spin deg/s, color [[r,g,b] birth, [r,g,b] death], alpha [birth, death].',@@ -298,9 +299,9 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({}),// Recipe bake: bounced light written into lightmaps at build time (src/light-bake.js, loaded on demand).bake: Object.freeze({- fields: 'preset, or samples (1-256), bounces (1-8), texelsPerUnit (1-12) over it; irradianceGrid true or 8-48 nodes: a baked grid of bounced diffuse light in place of lightmaps (opt in, static); gridFog true adds the fog (sunlit closed rooms; dark shafts too bright); probes room by default, false for none, or up to 4 {position, radius?}; rebake true bakes each sampled pose (4 kept).',+ fields: 'preset, or samples (1-256), bounces (1-8), texelsPerUnit (1-12) over it; irradianceGrid true or 8-48 nodes: baked bounced diffuse light in place of lightmaps (opt in, static); gridFog true adds the fog (sunlit closed rooms); probes room by default, false for none, or up to 4 {position, radius?}; rebake true bakes each sampled pose (4 kept).',presets: BAKE_PRESETS,- notes: 'Bounced light from point, spot, area and key lights. Reruns when parts, lights, materials or bake change. Skips alpha, skin, morph, hair, cloth (bake.skipped). A preset shrinks to fit (bake.used, bake.reduction); explicit settings fail over maxPathWork or past maxSeconds. No environment map or specular; probes are specular, not in glTF.',+ notes: 'Bounced light from point, spot, area and key lights. Skips alpha, skin, morph, hair, cloth (bake.skipped). A preset shrinks to fit (bake.used, bake.reduction); explicit settings fail over maxPathWork or past maxSeconds. No environment map or specular; probes are specular, not in glTF.',limits: Object.freeze({ maxSeconds: BAKE_MAXIMUM_SECONDS, workerMaxSeconds: BAKE_WORKER_MAXIMUM_SECONDS, maxPathWork: BAKE_EXPLICIT_PATH_WORK_LIMIT, maxPointLights: MAX_POINT_LIGHTS }),}),motionLook: Object.freeze({diff --git a/src/agent-scene-modules.js b/src/agent-scene-modules.jsindex b983b1ad..82d96445 100644--- a/src/agent-scene-modules.js+++ b/src/agent-scene-modules.js@@ -32,6 +32,7 @@ const MODULE_LOADERS = {lineArt: () => import('./line-art.js'),viewTransform: () => import('./view-transform-shader.js'),coplanar: () => import('./coplanar-overlap.js'),+ physicalSky: () => import('./physical-sky.js'),floorSky: () => import('./floor-sky-visibility.js'),userPass: () => import('./user-pass.js'),objectMotionBlur: () => import('./object-motion-blur.js'),@@ -81,6 +82,7 @@ const MODULE_MARKERS = {coplanar: ['"resolveCoplanar"'],// A closed room a sun lights gets the floor sky trace by default. The recipe text can not say whether a room is closed, so a recipe that names its sun loads it and the module skips an open scene.floorSky: ['"keyColor"', '"keyIntensity"'],+ physicalSky: ['"type":"physical"'],userPass: ['"postPasses"'],materialSnippet: ['"snippet":{'],// Only a motionBlur object that sets a non-zero `objects` loads it; the common `"shutter":0` look does not.diff --git a/src/agent-scene.js b/src/agent-scene.jsindex 0570bdf8..d8590b7b 100644--- a/src/agent-scene.js+++ b/src/agent-scene.js@@ -1618,7 +1618,7 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {knownKeys(operation, ['type', lookField], 'operation');const patch = operation[lookField];// Spot and area lights, cascades and sun links are absent from a recipe until it sets them.- const optionalFields = lookField === 'environment' ? ['ground', 'spotLights', 'areaLights', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'sunBounce', 'specularAntiAliasing', 'sunAngularRadius', 'lines', 'resolveCoplanar', 'viewTransform', 'look', 'hdri'] : lookField === 'effects' ? postStepSupport.fields : [];+ const optionalFields = lookField === 'environment' ? ['ground', 'spotLights', 'areaLights', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'sunBounce', 'specularAntiAliasing', 'sunAngularRadius', 'lines', 'resolveCoplanar', 'viewTransform', 'look', 'hdri', 'sky'] : lookField === 'effects' ? postStepSupport.fields : [];knownKeys(patch, [...Object.keys(candidate[lookField]), ...optionalFields], lookField);const nestedField = lookField === 'environment' ? 'volumeFog' : 'bloom';const merged = { ...candidate[lookField], ...(lookField === 'environment' ? environmentPatchWithSetup(patch) : patch) };@@ -1627,6 +1627,7 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {knownKeys(patch[nestedField], nestedKeys, nestedField);merged[nestedField] = { ...candidate[lookField][nestedField], ...patch[nestedField] };}+ if (patch.sky) merged.sky = { ...candidate[lookField].sky, ...patch.sky };candidate[lookField] = merged;continue;}diff --git a/src/physical-sky.js b/src/physical-sky.jsnew file mode 100644index 00000000..13259b9c--- /dev/null+++ b/src/physical-sky.js@@ -0,0 +1,166 @@+import { createEnvironmentMap } from './environment.js';++// environment.sky { type: 'physical' }: a clear-sky model driven by the sun alone. It is an analytic single-scattering+// approximation (Rayleigh and Henyey-Greenstein aerosol, Kasten-Young air mass), not the Nishita integration Blender uses.+// The normalized recipe stores the resolved sun, so the key light, the sky map, the background gradient and the+// aerial perspective of distant geometry always agree.++export const PHYSICAL_SKY_FIELDS = Object.freeze(['type', 'sunElevation', 'sunRotation', 'turbidity', 'groundAlbedo', 'aerialPerspective']);++const DEFAULTS = Object.freeze({ sunElevation: 45, sunRotation: 0, turbidity: 3, groundAlbedo: 0.3, aerialPerspective: 1 });+const LIMITS = Object.freeze({+ sunElevation: [-90, 90, 'degrees above the horizon, such as 15'],+ sunRotation: [-360, 360, 'degrees clockwise from -Z seen from above, such as 120'],+ turbidity: [1, 10, 'haze from 1 (very clear) to 10 (thick haze), such as 3'],+ groundAlbedo: [0, 1, 'a reflectance from 0 to 1, such as 0.3'],+ aerialPerspective: [0, 4, 'a scale from 0 (none) to 4, such as 1'],+});++const MAP_WIDTH = 128;+const MAP_HEIGHT = 64;+// Per-channel (red, green, blue) optical depth of the air at the zenith, and the aerosol depth per unit turbidity.+const RAYLEIGH_DEPTH = [0.04, 0.1, 0.24];+const AEROSOL_DEPTH_PER_TURBIDITY = [0.0125, 0.015, 0.0175];+const SUN_STRENGTH = 3.4;+const SKY_STRENGTH = 2.2;+const MAXIMUM_AIR_MASS = 20;+const AEROSOL_ANISOTROPY = 0.76;++/** Checks and fills the sky fields; `fail` builds the error for a field, a value and what is accepted. */+export function resolvePhysicalSky(input, fail) {+ const unknown = Object.keys(input).filter(key => !PHYSICAL_SKY_FIELDS.includes(key));+ if (unknown.length > 0 || input.type !== 'physical') {+ throw fail('environment.sky', input.type !== 'physical' ? input.type : unknown[0], `type 'physical' with fields ${PHYSICAL_SKY_FIELDS.slice(1).join(', ')}`);+ }+ const resolved = { type: 'physical' };+ for (const [field, [minimum, maximum, example]] of Object.entries(LIMITS)) {+ const value = input[field] ?? DEFAULTS[field];+ if (!Number.isFinite(value) || value < minimum || value > maximum) {+ throw fail(`environment.sky.${field}`, value, `a number from ${minimum} to ${maximum}, ${example}`);+ }+ resolved[field] = value;+ }+ return resolved;+}++function airMass(elevationRadians) {+ const degrees = Math.max(elevationRadians, 0) * 180 / Math.PI;+ return Math.min(MAXIMUM_AIR_MASS, 1 / (Math.sin(Math.max(elevationRadians, 0)) + 0.15 * Math.pow(degrees + 3.885, -1.253)));+}++function opticalDepth(turbidity) {+ return RAYLEIGH_DEPTH.map((rayleigh, channel) => rayleigh + AEROSOL_DEPTH_PER_TURBIDITY[channel] * turbidity);+}++/** The unit direction toward the sun; azimuth turns clockwise seen from above, from -Z. */+export function physicalSunDirection(sky) {+ const elevation = sky.sunElevation * Math.PI / 180;+ const rotation = sky.sunRotation * Math.PI / 180;+ return [Math.cos(elevation) * Math.sin(rotation), Math.sin(elevation), -Math.cos(elevation) * Math.cos(rotation)];+}++function sunColor(sky) {+ const elevation = sky.sunElevation * Math.PI / 180;+ const mass = airMass(elevation);+ const depth = opticalDepth(sky.turbidity);+ // The disc sinks under the horizon over about three degrees.+ const setting = Math.min(1, Math.max(0, (sky.sunElevation + 1) / 3));+ return depth.map(channelDepth => SUN_STRENGTH * Math.exp(-channelDepth * mass) * setting);+}++function skyRadiance(sky, direction, sun) {+ const depth = opticalDepth(sky.turbidity);+ const fullSunMass = airMass(Math.asin(Math.max(-1, Math.min(1, sun[1]))));+ const sunCosine = direction[0] * sun[0] + direction[1] * sun[1] + direction[2] * sun[2];+ const rayleighPhase = 0.75 * (1 + sunCosine * sunCosine);+ const anisotropy = AEROSOL_ANISOTROPY;+ const uncappedAerosolPhase = (1 - anisotropy * anisotropy) / Math.pow(1 + anisotropy * anisotropy - 2 * anisotropy * sunCosine, 1.5) / (4 * Math.PI) * 4;+ const aerosolPhase = Math.min(uncappedAerosolPhase, 2.5);+ const viewMass = airMass(Math.asin(Math.max(0, direction[1])) + 0.02);+ const setting = Math.min(1, Math.max(0, (sky.sunElevation + 6) / 8));+ return depth.map((channelDepth, channel) => {+ const rayleigh = RAYLEIGH_DEPTH[channel];+ const aerosol = AEROSOL_DEPTH_PER_TURBIDITY[channel] * sky.turbidity;+ const scattered = (rayleigh * rayleighPhase + aerosol * aerosolPhase * 1.5) / (rayleigh + aerosol);+ const inScatter = 1 - Math.exp(-channelDepth * viewMass);+ // Light scattered near the sun and low in the sky crossed the whole air mass toward the sun; the rest of the sky saw a short path.+ const nearSun = Math.max(0, sunCosine) ** 2 * (1 - Math.max(0, direction[1]));+ const sunMass = Math.min(4, fullSunMass) * (1 - nearSun) + fullSunMass * nearSun;+ const lightReaching = Math.exp(-channelDepth * sunMass * 0.45);+ return SKY_STRENGTH * scattered * inScatter * lightReaching * setting;+ });+}++function groundRadiance(sky, sunColorValue, zenith, sun) {+ const sunlight = Math.max(sun[1], 0);+ return sunColorValue.map((component, channel) => sky.groundAlbedo * (component * sunlight * 0.3 + zenith[channel] * 0.55));+}++function colorAtZenithAndHorizon(sky) {+ const sun = physicalSunDirection(sky);+ const color = sunColor(sky);+ const sideHorizon = [-sun[2], 0.04, sun[0]];+ const zenith = skyRadiance(sky, [0, 1, 0], sun);+ const toward = skyRadiance(sky, [sun[0], Math.max(0.04, sun[1] * 0.2), sun[2]], sun);+ const across = skyRadiance(sky, sideHorizon, sun);+ const horizon = toward.map((component, channel) => component * 0.7 + across[channel] * 0.3);+ return { sun, color, zenith, horizon };+}++/**+ * The recipe fields the sun and haze imply: key direction and colour, the background gradient and the fog that+ * gives distant geometry its aerial perspective. All stay inside the ranges the environment checks accept.+ */+export function physicalSkyFields(sky) {+ const { sun, color, zenith, horizon } = colorAtZenithAndHorizon(sky);+ // A colour above 1 keeps its hue and scales down to the brightest channel being 1.+ const clamped = vector => vector.map(component => Math.max(0, component / Math.max(1, ...vector)));+ const fields = {+ lightDirection: sun,+ keyColor: color.map(component => Math.round(component * 1000) / 1000),+ skyTop: clamped(zenith),+ skyBottom: clamped(horizon),+ fogColor: clamped(horizon),+ aerialDensity: 0.0025 * sky.turbidity * sky.aerialPerspective,+ };+ return fields;+}++/** A physical sky owns the sun and the haze: its key light, background gradient and aerial perspective replace those fields. */+export function applyPhysicalSky(input, environment, fail) {+ const sky = resolvePhysicalSky(input, fail);+ const { aerialDensity, ...fields } = physicalSkyFields(sky);+ Object.assign(environment, fields, { sky, fogDensity: aerialDensity });+}++const mapsByKey = new Map();+const MAXIMUM_CACHED_MAPS = 8;++function buildMapData(sky) {+ const { sun, color, zenith } = colorAtZenithAndHorizon(sky);+ const data = new Float32Array(MAP_WIDTH * MAP_HEIGHT * 3);+ for (let row = 0; row < MAP_HEIGHT; row++) {+ const polar = ((row + 0.5) / MAP_HEIGHT) * Math.PI;+ for (let column = 0; column < MAP_WIDTH; column++) {+ const azimuth = ((column + 0.5) / MAP_WIDTH - 0.5) * 2 * Math.PI;+ const direction = [Math.sin(polar) * Math.sin(azimuth), Math.cos(polar), -Math.sin(polar) * Math.cos(azimuth)];+ const radiance = direction[1] >= 0+ ? skyRadiance(sky, direction, sun)+ : groundRadiance(sky, color, zenith, sun).map((component, channel) => component + skyRadiance(sky, [direction[0], 0, direction[2]], sun)[channel] * 0.35 * (1 - sky.groundAlbedo));+ data.set(radiance, (row * MAP_WIDTH + column) * 3);+ }+ }+ return data;+}++/** The environment map of a physical sky; the same object returns while sky, strength, rotation and background hold. */+export function createPhysicalSkyMap({ sky, environmentIntensity: intensity, environmentRotation: rotation, world: showBackground }) {+ const key = [...PHYSICAL_SKY_FIELDS.slice(1).map(field => sky[field]), intensity, rotation, showBackground].join('|');+ if (!mapsByKey.has(key)) {+ if (mapsByKey.size >= MAXIMUM_CACHED_MAPS) {+ mapsByKey.clear();+ }+ mapsByKey.set(key, createEnvironmentMap({ width: MAP_WIDTH, height: MAP_HEIGHT, data: buildMapData(sky), intensity, rotation, showBackground }));+ }+ return mapsByKey.get(key);+}diff --git a/tests/physical-sky.test.js b/tests/physical-sky.test.jsnew file mode 100644index 00000000..6fc3645c--- /dev/null+++ b/tests/physical-sky.test.js@@ -0,0 +1,79 @@+import './support/load-agent-scene-modules.mjs';+import test from 'node:test';+import assert from 'node:assert/strict';+import { createAgentScene } from '../src/agent-scene.js';+import { agentSceneModulesNeeded } from '../src/agent-scene-modules.js';+import { agentEnvironmentMap, normalizeAgentLook } from '../src/agent-look.js';++function skyEnvironment(sky, extra = {}) {+ return normalizeAgentLook({ environment: { sky: { type: 'physical', ...sky }, ...extra } }).environment;+}++test('a recipe without a sky keeps the default look and loads no sky code', () => {+ const environment = normalizeAgentLook({}).environment;+ assert.equal(environment.sky, undefined);+ assert.equal(environment.fogDensity, null);+ assert.deepEqual(environment.lightDirection, [-3, 6, 4]);+ assert.ok(!agentSceneModulesNeeded({ environment: { setup: 'sunset' } }).includes('physicalSky'));+ assert.ok(agentSceneModulesNeeded({ environment: { sky: { type: 'physical' } } }).includes('physicalSky'));+});++test('the key light follows the sun elevation and rotation', () => {+ const noon = skyEnvironment({ sunElevation: 60, sunRotation: 0 });+ assert.ok(Math.abs(noon.lightDirection[1] - Math.sin(Math.PI / 3)) < 1e-9);+ assert.ok(noon.lightDirection[2] < 0);+ const east = skyEnvironment({ sunElevation: 0, sunRotation: 90 });+ assert.ok(Math.abs(east.lightDirection[0] - 1) < 1e-9);+});++test('the sun reddens and dims toward the horizon and sets below it', () => {+ const keyAt = elevation => skyEnvironment({ sunElevation: elevation }).keyColor;+ const [high, low, grazing, below] = [60, 15, 2, -5].map(keyAt);+ const redOverBlue = color => color[0] / Math.max(color[2], 1e-6);+ assert.ok(redOverBlue(low) > redOverBlue(high));+ assert.ok(redOverBlue(grazing) > redOverBlue(low));+ assert.ok(high[1] > low[1] && low[1] > grazing[1]);+ assert.deepEqual(below, [0, 0, 0]);+});++test('turbidity thickens the haze and aerial perspective scales it', () => {+ const clear = skyEnvironment({ turbidity: 1 });+ const hazy = skyEnvironment({ turbidity: 8 });+ assert.ok(hazy.fogDensity > clear.fogDensity);+ assert.ok(hazy.keyColor[2] < clear.keyColor[2]);+ assert.equal(skyEnvironment({ aerialPerspective: 0 }).fogDensity, 0);+ assert.ok(skyEnvironment({ aerialPerspective: 2 }).fogDensity > skyEnvironment({ aerialPerspective: 1 }).fogDensity);+ for (const component of [...hazy.fogColor, ...hazy.skyTop, ...hazy.skyBottom]) {+ assert.ok(component >= 0 && component <= 1);+ }+});++test('the sky map is deterministic, finite, cached and follows the ground albedo', () => {+ const environment = skyEnvironment({ sunElevation: 30 });+ const map = agentEnvironmentMap(environment);+ assert.equal(map.kind, 'environment-map');+ assert.ok(map.data.every(Number.isFinite));+ assert.equal(agentEnvironmentMap(skyEnvironment({ sunElevation: 30 })), map);+ const bright = agentEnvironmentMap(skyEnvironment({ sunElevation: 30, groundAlbedo: 0.9 }));+ const sum = values => values.reduce((total, value) => total + value, 0);+ assert.ok(sum(bright.data) > sum(map.data));+ const sunrise = agentEnvironmentMap(skyEnvironment({ sunElevation: 2 }));+ assert.notEqual(sum(sunrise.data).toFixed(3), sum(map.data).toFixed(3));+});++test('a sky field names the value and an accepted example when it is wrong', () => {+ assert.throws(() => skyEnvironment({ sunElevation: 120 }), /environment\.sky\.sunElevation.*120.*-90 to 90/s);+ assert.throws(() => skyEnvironment({ turbidity: 0 }), /environment\.sky\.turbidity/);+ assert.throws(() => skyEnvironment({ dust: 1 }), /environment\.sky/);+ assert.throws(() => normalizeAgentLook({ environment: { sky: { type: 'cloudy' } } }), /physical/);+});++test('set-environment changes one sky field and keeps the others', () => {+ const session = createAgentScene({ format: '67js.scene', schemaVersion: 1, geometries: [], materials: [], nodes: [],+ environment: { sky: { type: 'physical', sunElevation: 60, turbidity: 5 } } });+ session.apply([{ type: 'set-environment', environment: { sky: { sunElevation: 10 } } }], { expectedRevision: 0 });+ const { sky, lightDirection } = session.environment;+ assert.equal(sky.sunElevation, 10);+ assert.equal(sky.turbidity, 5);+ assert.ok(Math.abs(lightDirection[1] - Math.sin(10 * Math.PI / 180)) < 1e-9);+});