3D engine that AI agents drive
Light the surroundings of sunlit patches in a closed room (part of #462)
Nguyen Xuan An81054d0da860
diff --git a/bench/reference/frame-time.mjs b/bench/reference/frame-time.mjsindex 5cb23d4d..85f6cae3 100644--- a/bench/reference/frame-time.mjs+++ b/bench/reference/frame-time.mjs@@ -1,5 +1,5 @@// Frame time of a reference scene: plain, with the light bake, with reflection probes, and with both.-// node bench/reference/frame-time.mjs [scene-id] [gpu|cpu] [--grand] [--floor-sky=<strength> [--floor-sky-rooms]] [--no-floor-sky]+// node bench/reference/frame-time.mjs [scene-id] [gpu|cpu] [--grand] [--floor-sky=<strength> [--floor-sky-rooms]] [--no-floor-sky] [--sun-bounce=<n>]import { constants, setPriority } from 'node:os';import { chromium } from 'playwright';import { createServer } from 'vite';@@ -20,7 +20,8 @@ const browser = await chromium.launch({ executablePath: CHROME, headless: true,try {const page = await browser.newPage({ viewport: { width: 960, height: 540 } });const floorSkyArgument = process.argv.find(argument => argument.startsWith('--floor-sky='));- const harnessQuery = [process.argv.includes('--grand') ? 'set=grand' : null, floorSkyArgument ? `floorSky=${floorSkyArgument.split('=')[1]}` : null, process.argv.includes('--floor-sky-rooms') ? 'floorSkyRooms=1' : process.argv.includes('--no-floor-sky') ? 'floorSky=0' : null].filter(Boolean).join('&');+ const sunBounceArgument = process.argv.find(argument => argument.startsWith('--sun-bounce='));+ const harnessQuery = [sunBounceArgument ? `sunBounce=${sunBounceArgument.split('=')[1]}` : null, process.argv.includes('--grand') ? 'set=grand' : null, floorSkyArgument ? `floorSky=${floorSkyArgument.split('=')[1]}` : null, process.argv.includes('--floor-sky-rooms') ? 'floorSkyRooms=1' : process.argv.includes('--no-floor-sky') ? 'floorSky=0' : null].filter(Boolean).join('&');await page.goto(`${serverUrl}/bench/reference/harness.html${harnessQuery ? `?${harnessQuery}` : ''}`, { timeout: PAGE_LOAD_TIMEOUT });await page.waitForFunction(() => window.measureReferenceFrameTime, null, { timeout: PAGE_LOAD_TIMEOUT });const results = [];diff --git a/bench/reference/images/brick-flat.jpg b/bench/reference/images/brick-flat.jpgindex 35b7cdb3..b77ffe9a 100644Binary files a/bench/reference/images/brick-flat.jpg and b/bench/reference/images/brick-flat.jpg differdiff --git a/bench/reference/images/brick-graph.jpg b/bench/reference/images/brick-graph.jpgindex f59f17a9..f614efeb 100644Binary files a/bench/reference/images/brick-graph.jpg and b/bench/reference/images/brick-graph.jpg differdiff --git a/bench/reference/images/brick-room.jpg b/bench/reference/images/brick-room.jpgindex d5549211..3635348c 100644Binary files a/bench/reference/images/brick-room.jpg and b/bench/reference/images/brick-room.jpg differdiff --git a/bench/reference/images/brushed-film.jpg b/bench/reference/images/brushed-film.jpgindex 0e977d7f..3e31d9df 100644Binary files a/bench/reference/images/brushed-film.jpg and b/bench/reference/images/brushed-film.jpg differdiff --git a/bench/reference/images/car-paint.jpg b/bench/reference/images/car-paint.jpgindex 4250b7f4..edff813e 100644Binary files a/bench/reference/images/car-paint.jpg and b/bench/reference/images/car-paint.jpg differdiff --git a/bench/reference/images/character.jpg b/bench/reference/images/character.jpgindex 677134d8..480895ae 100644Binary files a/bench/reference/images/character.jpg and b/bench/reference/images/character.jpg differdiff --git a/bench/reference/images/dark-shaft.jpg b/bench/reference/images/dark-shaft.jpgindex 48a9e13b..0f5b2915 100644Binary files a/bench/reference/images/dark-shaft.jpg and b/bench/reference/images/dark-shaft.jpg differdiff --git a/bench/reference/images/fog-room.jpg b/bench/reference/images/fog-room.jpgindex e659f7b3..c1343e64 100644Binary files a/bench/reference/images/fog-room.jpg and b/bench/reference/images/fog-room.jpg differdiff --git a/bench/reference/images/fog-valley.jpg b/bench/reference/images/fog-valley.jpgindex 7d24f4b4..f4d9e9cb 100644Binary files a/bench/reference/images/fog-valley.jpg and b/bench/reference/images/fog-valley.jpg differdiff --git a/bench/reference/images/fog.jpg b/bench/reference/images/fog.jpgindex 312b7d2a..fc583145 100644Binary files a/bench/reference/images/fog.jpg and b/bench/reference/images/fog.jpg differdiff --git a/bench/reference/images/foliage.jpg b/bench/reference/images/foliage.jpgindex 96f97fa3..d279038c 100644Binary files a/bench/reference/images/foliage.jpg and b/bench/reference/images/foliage.jpg differdiff --git a/bench/reference/images/glass.jpg b/bench/reference/images/glass.jpgindex 920dc0f2..412d4a92 100644Binary files a/bench/reference/images/glass.jpg and b/bench/reference/images/glass.jpg differdiff --git a/bench/reference/images/grand-megacity-dusk-a.jpg b/bench/reference/images/grand-megacity-dusk-a.jpgindex e4d5341d..5aac8c25 100644Binary files a/bench/reference/images/grand-megacity-dusk-a.jpg and b/bench/reference/images/grand-megacity-dusk-a.jpg differdiff --git a/bench/reference/images/grand-megacity-dusk-b.jpg b/bench/reference/images/grand-megacity-dusk-b.jpgindex 115a4e61..fdb6e634 100644Binary files a/bench/reference/images/grand-megacity-dusk-b.jpg and b/bench/reference/images/grand-megacity-dusk-b.jpg differdiff --git a/bench/reference/images/grand-megacity-dusk-blue-hour.jpg b/bench/reference/images/grand-megacity-dusk-blue-hour.jpgindex 2a87aa04..fb8bbc7e 100644Binary files a/bench/reference/images/grand-megacity-dusk-blue-hour.jpg and b/bench/reference/images/grand-megacity-dusk-blue-hour.jpg differdiff --git a/bench/reference/images/grand-megacity-dusk-c.jpg b/bench/reference/images/grand-megacity-dusk-c.jpgindex cc448012..3bb6729c 100644Binary files a/bench/reference/images/grand-megacity-dusk-c.jpg and b/bench/reference/images/grand-megacity-dusk-c.jpg differdiff --git a/bench/reference/images/grand-mountain-valley-a.jpg b/bench/reference/images/grand-mountain-valley-a.jpgindex aea20995..e581cd01 100644Binary files a/bench/reference/images/grand-mountain-valley-a.jpg and b/bench/reference/images/grand-mountain-valley-a.jpg differdiff --git a/bench/reference/images/grand-mountain-valley-b.jpg b/bench/reference/images/grand-mountain-valley-b.jpgindex 3cfb2fcf..3c39eca7 100644Binary files a/bench/reference/images/grand-mountain-valley-b.jpg and b/bench/reference/images/grand-mountain-valley-b.jpg differdiff --git a/bench/reference/images/grand-mountain-valley-dawn.jpg b/bench/reference/images/grand-mountain-valley-dawn.jpgindex a3d34eb3..494a2802 100644Binary files a/bench/reference/images/grand-mountain-valley-dawn.jpg and b/bench/reference/images/grand-mountain-valley-dawn.jpg differdiff --git a/bench/reference/images/grand-temple-hall-a.jpg b/bench/reference/images/grand-temple-hall-a.jpgindex a9f1b1fc..d3bfc362 100644Binary files a/bench/reference/images/grand-temple-hall-a.jpg and b/bench/reference/images/grand-temple-hall-a.jpg differdiff --git a/bench/reference/images/grand-temple-hall-b.jpg b/bench/reference/images/grand-temple-hall-b.jpgindex 5f0635b4..9212ba9a 100644Binary files a/bench/reference/images/grand-temple-hall-b.jpg and b/bench/reference/images/grand-temple-hall-b.jpg differdiff --git a/bench/reference/images/grand-temple-hall-c.jpg b/bench/reference/images/grand-temple-hall-c.jpgindex c8221464..da3dd790 100644Binary files a/bench/reference/images/grand-temple-hall-c.jpg and b/bench/reference/images/grand-temple-hall-c.jpg differdiff --git a/bench/reference/images/grand-temple-hall-rose.jpg b/bench/reference/images/grand-temple-hall-rose.jpgindex bd913c14..839ade65 100644Binary files a/bench/reference/images/grand-temple-hall-rose.jpg and b/bench/reference/images/grand-temple-hall-rose.jpg differdiff --git a/bench/reference/images/light-linking.jpg b/bench/reference/images/light-linking.jpgindex 946ed06e..9ea5791f 100644Binary files a/bench/reference/images/light-linking.jpg and b/bench/reference/images/light-linking.jpg differdiff --git a/bench/reference/images/lit-interior.jpg b/bench/reference/images/lit-interior.jpgindex 05f259f5..29ff2549 100644Binary files a/bench/reference/images/lit-interior.jpg and b/bench/reference/images/lit-interior.jpg differdiff --git a/bench/reference/images/long-street.jpg b/bench/reference/images/long-street.jpgindex 5ad15299..ff432e72 100644Binary files a/bench/reference/images/long-street.jpg and b/bench/reference/images/long-street.jpg differdiff --git a/bench/reference/images/material-spheres.jpg b/bench/reference/images/material-spheres.jpgindex 3f875a8c..763ca46b 100644Binary files a/bench/reference/images/material-spheres.jpg and b/bench/reference/images/material-spheres.jpg differdiff --git a/bench/reference/images/megacity-dusk.jpg b/bench/reference/images/megacity-dusk.jpgindex ae150416..cc5e793b 100644Binary files a/bench/reference/images/megacity-dusk.jpg and b/bench/reference/images/megacity-dusk.jpg differdiff --git a/bench/reference/images/metal-room.jpg b/bench/reference/images/metal-room.jpgindex b3bd48c5..ea83c913 100644Binary files a/bench/reference/images/metal-room.jpg and b/bench/reference/images/metal-room.jpg differdiff --git a/bench/reference/images/metal.jpg b/bench/reference/images/metal.jpgindex dd97ebcf..aebb3298 100644Binary files a/bench/reference/images/metal.jpg and b/bench/reference/images/metal.jpg differdiff --git a/bench/reference/images/mountain-valley.jpg b/bench/reference/images/mountain-valley.jpgindex fc12ef8a..e37bcd9c 100644Binary files a/bench/reference/images/mountain-valley.jpg and b/bench/reference/images/mountain-valley.jpg differdiff --git a/bench/reference/images/outdoor-hdri.jpg b/bench/reference/images/outdoor-hdri.jpgindex 72a73e5f..bd1c1246 100644Binary files a/bench/reference/images/outdoor-hdri.jpg and b/bench/reference/images/outdoor-hdri.jpg differdiff --git a/bench/reference/images/spot-area.jpg b/bench/reference/images/spot-area.jpgindex 1eed19f1..e6b2eb42 100644Binary files a/bench/reference/images/spot-area.jpg and b/bench/reference/images/spot-area.jpg differdiff --git a/bench/reference/images/subsurface-off.jpg b/bench/reference/images/subsurface-off.jpgindex de4eb22d..b7bdff11 100644Binary files a/bench/reference/images/subsurface-off.jpg and b/bench/reference/images/subsurface-off.jpg differdiff --git a/bench/reference/images/subsurface.jpg b/bench/reference/images/subsurface.jpgindex c57de75e..66c56f67 100644Binary files a/bench/reference/images/subsurface.jpg and b/bench/reference/images/subsurface.jpg differdiff --git a/bench/reference/images/temple-hall.jpg b/bench/reference/images/temple-hall.jpgindex adf68897..f557abec 100644Binary files a/bench/reference/images/temple-hall.jpg and b/bench/reference/images/temple-hall.jpg differdiff --git a/bench/reference/run.mjs b/bench/reference/run.mjsindex 1c4c19b9..671701cf 100644--- a/bench/reference/run.mjs+++ b/bench/reference/run.mjs@@ -58,6 +58,9 @@ const argumentsGiven = process.argv.slice(2);// Closed rooms lit by a sun get the floor sky trace by default, as in the recipe path; --no-floor-sky draws without it (environment.floorSkyTrace: false).// --floor-sky [<strength>] traces the sky each floor texel sees (src/floor-sky-visibility.js) and scales the world light on floors by it (strength 1 when none follows).const floorSkyFlag = argumentsGiven.indexOf('--floor-sky');+// --sun-bounce <n> sets environment.sunBounce on every scene (0 draws without the sunlit patches' lights; the default is 1).+const sunBounceFlag = argumentsGiven.indexOf('--sun-bounce');+const sunBounceQuery = sunBounceFlag < 0 ? null : `sunBounce=${Number(argumentsGiven[sunBounceFlag + 1])}`;const floorSkyStrength = floorSkyFlag < 0 ? 0 : Number(argumentsGiven[floorSkyFlag + 1]) || 1;const scoreOnly = argumentsGiven.includes('--score-only');const skipBlender = argumentsGiven.includes('--skip-blender') || lookIds !== null;@@ -128,7 +131,7 @@ async function renderBackend(backend, serverUrl, graphics) {page.on('console', message => message.text().includes('GL_') && console.log('PAGE', message.text().slice(0, 200)));// Each scene gets a fresh page, so a large scene leaves no GL state or memory behind for the next one.const openHarness = async () => {- const harnessQuery = [sceneSet ? `set=${sceneSet}` : null, argumentsGiven.includes('--no-water') ? 'water=off' : argumentsGiven.includes('--ssr-water') ? 'water=ssr' : null, argumentsGiven.includes('--no-ground-bounce') ? 'groundBounce=off' : null, floorSkyStrength ? `floorSky=${floorSkyStrength}` : argumentsGiven.includes('--no-floor-sky') ? 'floorSky=0' : null, argumentsGiven.includes('--floor-sky-rooms') ? 'floorSkyRooms=1' : null].filter(Boolean).join('&');+ const harnessQuery = [sceneSet ? `set=${sceneSet}` : null, argumentsGiven.includes('--no-water') ? 'water=off' : argumentsGiven.includes('--ssr-water') ? 'water=ssr' : null, argumentsGiven.includes('--no-ground-bounce') ? 'groundBounce=off' : null, floorSkyStrength ? `floorSky=${floorSkyStrength}` : argumentsGiven.includes('--no-floor-sky') ? 'floorSky=0' : null, argumentsGiven.includes('--floor-sky-rooms') ? 'floorSkyRooms=1' : null, sunBounceQuery].filter(Boolean).join('&');await page.goto(`${serverUrl}/bench/reference/harness.html${harnessQuery ? `?${harnessQuery}` : ''}`, { timeout: PAGE_LOAD_TIMEOUT });await page.waitForFunction(() => window.renderReferenceScene, null, { timeout: PAGE_LOAD_TIMEOUT });};diff --git a/changes/462-sun-bounce.md b/changes/462-sun-bounce.mdnew file mode 100644index 00000000..052bde3f--- /dev/null+++ b/changes/462-sun-bounce.md@@ -0,0 +1 @@+- Light the surroundings of the sunlit patches in a sun-lit closed room (issue #462). A lazily loaded module (`withSunBounce`, loaded with the floor sky trace) finds the patches when the scene is prepared and adds up to 6 unshadowed point lights above them, with flux = sun irradiance x lit area x albedo per channel, so the floor, walls and pillars near a patch get more light than the far end. `environment.sunBounce` is a number of 0 or more (0 off, byte for byte the look before; 1 default; above 1 stronger) in recipes, `set-environment`, the MCP schema and `docs/agent-look.md`; anything else throws a TypeError. Open scenes, rooms with no sun and baked scenes do not change. Ring luminance around the patch moves toward Cycles (`dark-shaft` mean 0.77 to 0.97, `temple-hall` 0.67 to 0.72), FLIP moves by -0.0044 to +0.0022; see `docs/lighting.md`.diff --git a/changes/462-sun-bounce.size.md b/changes/462-sun-bounce.size.mdnew file mode 100644index 00000000..09bc843f--- /dev/null+++ b/changes/462-sun-bounce.size.md@@ -0,0 +1,4 @@+- scene:agent-scene: +54 bytes gzip against #434 (103529 to 103583; +353 against main's 103230) for the `sunBounce` entry in the environment field lists and its number check. Still over its goal of 100000, so the lead decides; no acceptance is written here.+- scene:agent-scene+lazy: +1997 bytes gzip against #434 (367325 to 369322) for the sun bounce module, loaded only by a recipe that names its sun.+- scene:lit-box, scene:gltf-box: no change (0 bytes).+- tool:scene_create: +105 bytes against #434 (67582 to 67687; +224 against main) for the `sunBounce` field and its one-line description, which the schema test needs.diff --git a/docs/agent-look.md b/docs/agent-look.mdindex 055480cb..32feeb55 100644--- a/docs/agent-look.md+++ b/docs/agent-look.md@@ -110,6 +110,7 @@ Sky colors use display RGB, matching the renderer's existing environment contrac| `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` || `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). |+| `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. || `setup` | `daylight` | `daylight`, `overcast`, `sunset` or `studio`. See Lighting setups || `environmentIntensity` | `1` | `0` to `100`. Scales the setup's environment light and reflections || `environmentRotation` | `0` | `-100` to `100` radians around the vertical axis |diff --git a/docs/lighting.md b/docs/lighting.mdindex 4fbdbc34..8684b0cc 100644--- a/docs/lighting.md+++ b/docs/lighting.md@@ -117,7 +117,7 @@ A point light costs about 0.04 to 0.05 ms and an area light about 0.04 ms at thiA closed room lit by point, spot or area lights gets the light its walls bounce without a bake and at no cost per frame. `groundBounceEnvironment(parts, environment)` (`67js/addons/ground-bounce`, the same call that adds the floor's bounce) finds the room with the closed-room ray test, measures the area of the faces that look at the middle of the scene and their mean albedo (colour times texture mean, per channel), and sets `bounce` on the environment map. With lamp flux `F` (point `4 pi I`, spot `2 pi (1 - cos angle) I`, area `pi I`, summed over the lamps inside the room), area `A` and albedo `rho`, the bounce is `0.8 * F / pi * rho / (A * (1 - rho))` in each colour channel, so red walls bounce red light. The renderer adds it to the diffuse light: it is one constant in the first irradiance coefficient, the map's data is shared, and a lamp that changes every frame rebuilds nothing. The 0.8 is fitted: at 1.0 `lit-interior` came out 10 percent brighter than Cycles.-It is left out when the scene has a bake (its light map holds the bounce), a sun (`keyColor` above zero or unset, as in `temple-hall` and `dark-shaft`, which already read lighter than Cycles in their shadows), no map, or `environment.roomBounce` is `false`. It is one average colour for the whole room, with no brighter corner beside a lamp and no colour bleeding next to a wall; a bake gives those, and `scene_inspect` names it (`closed-room-without-bake`, with the `standard` preset) for a closed room lit by lamps only.+It is left out when the scene has a bake (its light map holds the bounce), a sun (`keyColor` above zero or unset; a sun-lit room gets the light of its sunlit patches instead, see "Sunlit patches bounce light into a closed room"), no map, or `environment.roomBounce` is `false`. It is one average colour for the whole room, with no brighter corner beside a lamp and no colour bleeding next to a wall; a bake gives those, and `scene_inspect` names it (`closed-room-without-bake`, with the `standard` preset) for a closed room lit by lamps only.Luminance of the 67js picture over Cycles (linear, whole frame and 20th percentile, `bench/reference/luminance-ratio.py`, GPU renders against the committed Cycles panels):@@ -130,6 +130,27 @@ Luminance of the 67js picture over Cycles (linear, whole frame and 20th percentiThe two `temple-hall` p20 values differ only by the rescaling of the picture (the scene has a sun, so no bounce is added).+## Sunlit patches bounce light into a closed room++A closed room a sun lights gets the light its sunlit patches send on, so the floor, walls and pillars around a patch are lit and the far end of the room is not (`temple-hall`, `dark-shaft`; before this, everything outside the patch was nearly black next to Cycles). `withSunBounce(parts, environment)` (a lazy module that loads with the floor sky trace, `src/sun-bounce.js`) finds the patches once when the scene is prepared: about 20 000 samples of the room's surfaces get a shadow ray to the sun and a fan of 16 rays that must mostly hit something (a roof's outer side is not inside the room), the lit ones are grouped into at most 6 patches by position and facing, and each patch becomes an unshadowed point light one patch radius above it. Its intensity is `0.3 * sunBounce * flux / (2 pi)` per channel, with flux = sun irradiance x lit area x albedo (so a red carpet bounces red). The lights add to the scene's own point lights (16 in all, never more), cost no shader code and one more point light each in every frame. Open scenes, rooms with no sun, baked scenes and `sunBounce: 0` come back unchanged.++`environment.sunBounce` is a number of 0 or more: 0 is off (the look before this change, byte for byte), 1 is the default, above 1 is stronger. The 0.3 is fitted: at 0.6 `dark-shaft` came out brighter than Cycles around its patch (mean 1.19 times) and FLIP got worse by 0.01.++Luminance of the 67js picture over Cycles in the ring around the lit patch (mean and 20th percentile, linear, 480 x 270, patch = Cycles pixels above 0.35 of its 99.5th percentile, ring from 3 to 25 pixels away), and FLIP against Cycles of the whole frame (RTX 3060, `bench/reference`):++| Scene | Ring mean 0 / 1 / 2 | Ring p20 0 / 1 / 2 | FLIP 0 / 1 / 2 |+| --- | --- | --- | --- |+| `temple-hall` | 0.67 / 0.72 / 0.77 | 0.72 / 0.75 / 0.82 | 0.0617 / 0.0633 / 0.0651 |+| `dark-shaft` | 0.77 / 0.97 / 1.19 | 0.56 / 0.83 / 1.05 | 0.0576 / 0.0583 / 0.0676 |+| `temple-hall-a` | 0.37 / 0.40 / 0.44 | 0.58 / 0.64 / 0.69 | 0.1590 / 0.1596 / 0.1601 |+| `temple-hall-b` | 0.53 / 0.61 / 0.69 | 1.29 / 1.38 / 1.47 | 0.1468 / 0.1424 / 0.1402 |+| `temple-hall-c` | 0.97 / 0.98 / 1.00 | 1.09 / 1.12 / 1.14 | 0.1116 / 0.1138 / 0.1170 |+| `long-street` (open) | unchanged | unchanged | 0.1121 / 0.1121 / 0.1121 |++Frame cost (median of 5 plain frames, RTX 3060, machine busy): `temple-hall` 2.205 to 2.385 ms, `dark-shaft` 2.04 to 2.125 ms for `sunBounce` 1 against 0. The patch search runs once when the scene is prepared; its build time on the halls was not measured separately.++FLIP is a little worse at 1 on four of five scenes (by 0.0007 to 0.0022) and better on `temple-hall-b` (by 0.0044): the rooms get lighter near the patch where Cycles does, but the point lights give a rounder pool than Cycles' bounce.+## Sun shadows fill under a low sunA scene with a sun that is not a closed room or a bake gets one more constant diffuse light under a low sun, the same `bounce` colour the room uses, so it costs nothing per frame and changes no shader. Slopes, walls and roofs that face a low sun send its light back into the shadows, and the ground term does not see them (`mountain-valley` has no level ground at all). The fill is `0.4 * albedo * sun colour / pi * (wall - ground)^2`, where `ground` is the sun's vertical share on a level surface, `wall` its horizontal share on a vertical one and `albedo` the floor's (at least 0.2). A high sun gives zero, so the studio scenes and `long-street` are unchanged, and so are `temple-hall` and `dark-shaft`. `environment.outdoorFill: false` turns it off.diff --git a/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.jsindex 50fc261e..84b52b1f 100644--- a/scripts/agent-preview-browser.js+++ b/scripts/agent-preview-browser.js@@ -189,7 +189,7 @@ function syncAutomaticGround(record) {function litEnvironment(parts, environment, hasAutomaticGround) {const lit = groundBounceEnvironment(parts, { ...environment, map: agentEnvironmentMap(environment) }, { automaticAlbedo: hasAutomaticGround ? FLOOR_COLOR : null });// A closed room a sun lights gets the lights of its sunlit patches (src/sun-bounce.js), once a recipe that names a sun has loaded the module.- return agentSceneModuleLoaded('sunBounce') ? agentSceneModule('sunBounce').withSunBounce(parts, lit) : lit;+ return agentSceneModuleLoaded('floorSky') ? agentSceneModule('floorSky').withSunBounce(parts, lit) : lit;}// A renderer takes its cascades at construction, so a change of the count (or of the extent that picks it) rebuilds.diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjsindex 027d8f40..374e3599 100644--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@ -227,7 +227,7 @@ const environment = z.strictObject({lines: lines.nullable().optional(),objectReflections: z.boolean().optional().describe("false turns off reflection probes on smooth metal parts."),floorSkyTrace: z.boolean().optional().describe('false turns off the sky traced into floors of sun-lit closed rooms.'),- sunBounce: z.number().min(0).optional().describe('Light the sunlit patches of a sun-lit closed room bounce on to the room: 0 off, 1 default, above 1 stronger.'),+ sunBounce: z.number().min(0).optional().describe('Sun bounce in a closed room: 0 off, 1 default.'),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.enum(LOOK_NAMES).nullable().optional().describe('Named look preset; null clears.'),diff --git a/src/agent-look.js b/src/agent-look.jsindex e89f7c3e..a9e504f8 100644--- a/src/agent-look.js+++ b/src/agent-look.js@@ -281,7 +281,7 @@ function environmentFrom(input = {}) {}// Scales the light the sunlit patches of a sun-lit closed room bounce on (src/sun-bounce.js); 0 turns it off.if (input.sunBounce !== undefined) {- if (typeof input.sunBounce !== 'number' || !Number.isFinite(input.sunBounce) || input.sunBounce < 0) {+ if (!Number.isFinite(input.sunBounce) || input.sunBounce < 0) {throw new TypeError('environment.sunBounce must be a number of 0 or more.');}environment.sunBounce = input.sunBounce;diff --git a/src/agent-scene-modules.js b/src/agent-scene-modules.jsindex ad84766c..f29f708e 100644--- a/src/agent-scene-modules.js+++ b/src/agent-scene-modules.js@@ -32,7 +32,6 @@ const MODULE_LOADERS = {viewTransform: () => import('./view-transform-shader.js'),coplanar: () => import('./coplanar-overlap.js'),floorSky: () => import('./floor-sky-visibility.js'),- sunBounce: () => import('./sun-bounce.js'),userPass: () => import('./user-pass.js'),materialSnippet: () => import('./material-snippet.js'),};@@ -76,7 +75,6 @@ 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"'],- sunBounce: ['"keyColor"', '"keyIntensity"'],userPass: ['"postPasses"'],materialSnippet: ['"snippet":{'],};diff --git a/src/floor-sky-visibility.js b/src/floor-sky-visibility.jsindex 64a9390f..e83ad08e 100644--- a/src/floor-sky-visibility.js+++ b/src/floor-sky-visibility.js@@ -3,6 +3,9 @@ import { buildWorld, cosineDirection, radicalInverse, sceneScale } from './lightimport { worldBounds } from './probe-trace.js';import { createTracer } from './ray-query.js';+// The sunlit patches' lights (src/sun-bounce.js) load with the floor sky trace: both are for a closed room a sun lights.+export { withSunBounce } from './sun-bounce.js';+// Sky visibility traced from the texels of the floor itself. A floor part is cut into small triangles, every vertex shoots// cosine-weighted rays up into the scene's other parts, and the share that escapes goes into the geometry's `skyVisibility`,// which the shader already multiplies into the light the world gives that surface. A narrow street or a hall then darkensdiff --git a/src/sun-bounce.js b/src/sun-bounce.jsindex ae6b5190..77a49caf 100644--- a/src/sun-bounce.js+++ b/src/sun-bounce.js@@ -14,15 +14,15 @@ import { MAX_POINT_LIGHTS } from './light-limits.js';export const SUN_BOUNCE_PATCH_LIGHTS = 6;export const SUN_BOUNCE_SAMPLES = 20_000;-const ROOM_RAYS = 8;+const ROOM_RAYS = 16;// Share of the room rays that must hit something for a lit sample to count as inside the room (a roof's outer side hits nothing).-const ENCLOSED_SHARE = 0.5;+const ENCLOSED_SHARE = 0.75;const CLUSTER_PASSES = 6;// The light stands this many patch radii above its patch: close enough to light the patch's own surroundings, high enough not to// brighten the patch itself much.const LIFT_IN_RADII = 1;// Fitted against Cycles on the reference halls (docs/lighting.md); environment.sunBounce multiplies it.-export const SUN_BOUNCE_GAIN = 1;+export const SUN_BOUNCE_GAIN = 0.3;const KEY_THRESHOLD = 1e-3;const EXCLUDED_TAGS = new Set(['liquid', 'foam', 'unlit', 'fire', 'smoke']);diff --git a/tests/sun-bounce.test.js b/tests/sun-bounce.test.jsnew file mode 100644index 00000000..54a28cae--- /dev/null+++ b/tests/sun-bounce.test.js@@ -0,0 +1,65 @@+import './support/load-agent-scene-modules.mjs';+import assert from 'node:assert/strict';+import test from 'node:test';+import { createAgentScene } from '../src/agent-scene.js';+import { findSunBounceLights, withSunBounce } from '../src/sun-bounce.js';+import { MAX_POINT_LIGHTS } from '../src/light-limits.js';++// A closed room with a roof opening: the sun reaches a patch of the floor and nothing else.+function roomWithOpening(environment = {}) {+ const block = (id, translation, scale) => ({ id, geometry: 'box', material: 'stone', translation, scale });+ return {+ format: '67js.scene', schemaVersion: 1,+ geometries: [{ id: 'box', type: 'box' }],+ materials: [{ id: 'stone', color: [0.6, 0.5, 0.4], roughness: 0.8 }],+ nodes: [+ block('floor', [0, -0.05, 0], [10, 0.1, 10]),+ block('wall-left', [-5, 2, 0], [0.2, 4, 10]),+ block('wall-right', [5, 2, 0], [0.2, 4, 10]),+ block('wall-front', [0, 2, 5], [10, 4, 0.2]),+ block('wall-back', [0, 2, -5], [10, 4, 0.2]),+ block('roof-left', [-2.9, 4.1, 0], [4.6, 0.2, 10.4]),+ block('roof-right', [2.9, 4.1, 0], [4.6, 0.2, 10.4]),+ ],+ camera: { eye: [0, 1.5, 4], target: [0, 1.5, 0], fov: 60, near: 0.05, far: 40 },+ environment: { keyColor: [3, 3, 3], lightDirection: [0, 1, 0.2], floorSkyTrace: false, ...environment },+ };+}++test('a sun-lit closed room gets point lights at its sunlit patches, above the floor', () => {+ const { parts, environment } = createAgentScene(roomWithOpening());+ const lights = findSunBounceLights(parts, environment);+ assert.ok(lights.length > 0 && lights.length <= 6);+ for (const light of lights) {+ assert.ok(light.position.every((value, axis) => value > [-5, 0, -5][axis] && value < [5, 4, 5][axis]), 'inside the room');+ assert.ok(light.intensity > 0);+ }+});++test('environment.sunBounce scales the lights, and 0 returns the environment unchanged', () => {+ const { parts, environment } = createAgentScene(roomWithOpening());+ const strength = (value) => withSunBounce(parts, { ...environment, sunBounce: value }).pointLights.reduce((total, light) => total + light.intensity, 0);+ assert.ok(strength(2) > 1.99 * strength(1) && strength(2) < 2.01 * strength(1));+ const off = { ...environment, sunBounce: 0 };+ assert.equal(withSunBounce(parts, off), off);+});++test('the lights fit in the point light limit beside the scene lamps', () => {+ const { parts, environment } = createAgentScene(roomWithOpening());+ const lamps = Array.from({ length: MAX_POINT_LIGHTS - 2 }, () => ({ position: [0, 1, 0], color: [1, 1, 1], intensity: 1 }));+ assert.equal(withSunBounce(parts, { ...environment, pointLights: lamps }).pointLights.length, MAX_POINT_LIGHTS);+});++test('open ground and a room with no sun get no lights', () => {+ const { parts, environment } = createAgentScene(roomWithOpening());+ assert.equal(findSunBounceLights(parts.filter(part => part.name === 'floor'), environment).length, 0);+ const dark = { ...environment, keyIntensity: 0 };+ assert.equal(withSunBounce(parts, dark), dark);+});++test('environment.sunBounce that is not a number of 0 or more is refused', () => {+ for (const value of ['strong', true, -1, null]) {+ assert.throws(() => createAgentScene(roomWithOpening({ sunBounce: value })), /sunBounce must be a number/);+ }+ assert.equal(createAgentScene(roomWithOpening({ sunBounce: 2 })).environment.sunBounce, 2);+});