3D engine that AI agents drive
Move the floor sky default into the recipe path with environment.floorSkyTrace as the opt-out (part of #197)
Nguyen Xuan An02f1149d532c
diff --git a/bench/reference/README.md b/bench/reference/README.mdindex 013f5e95..f4948a1c 100644--- a/bench/reference/README.md+++ b/bench/reference/README.md@@ -1784,7 +1784,7 @@ What would close it is a finer height-to-normal source than a 512 texel map (an## Sky seen from the floor, on by default for sunlit closed rooms (2026-11-04, part of issue #197)-The opt-in trace above helped halls and studio floors and hurt streets, cities and rooms lit by lamps alone. The split is by what lights the scene, not by geometry: the mean traced visibility of the floor did not separate them (`temple-hall` 0.45, `dark-shaft` 0.54, but also `lit-interior` 0.55, `metal-room` 0.49 and `brick-room` 0.26, measured at strength 1). The rule that does separate them: a closed room (the ray test of the ground bounce) that a sun lights. `applyFloorSkyVisibility(parts, { onlyClosedRooms: true })` traces only closed rooms, at `FLOOR_SKY_ROOM_STRENGTH` 0.2, and returns open scenes unchanged (`report.reason` `open scene`); the reference harness calls it for scenes whose `keyColor` is not zero, so lamp-only rooms and every open scene draw as before. `--no-floor-sky` draws without it, `--floor-sky <strength>` sets one. Nothing in core; `report.meanVisibility` is new.+The opt-in trace above helped halls and studio floors and hurt streets, cities and rooms lit by lamps alone. The split is by what lights the scene, not by geometry: the mean traced visibility of the floor did not separate them (`temple-hall` 0.45, `dark-shaft` 0.54, but also `lit-interior` 0.55, `metal-room` 0.49 and `brick-room` 0.26, measured at strength 1). The rule that does separate them: a closed room (the ray test of the ground bounce) that a sun lights. `applyFloorSkyVisibility(parts, { onlyClosedRooms: true })` traces only closed rooms, at `FLOOR_SKY_ROOM_STRENGTH` 0.2, and returns open scenes unchanged (`report.reason` `open scene`). `applyDefaultFloorSky(parts, environment)` adds the sun test and the opt-out, and it is what `createAgentScene` calls for every recipe that names its sun (the module loads lazily, `environment.floorSkyTrace: false` opts out, see `docs/agent-look.md`). The harness calls the same function with the scene's environment and sets nothing of its own, so a recipe and the reference scene get the same frame; `--no-floor-sky` sets the opt-out on every scene, and `--floor-sky <strength>` is an experiment that traces every floor. Nothing in core; `report.meanVisibility` is new.GPU, 960 x 540, FLIP against the stored Cycles arrays, change from a render of main on the same machine (24 scenes and the 9 grand options; a scene not listed changed by less than 0.002, and all open scenes and lamp-only rooms are identical by construction):@@ -1809,6 +1809,6 @@ Box 2, dark end (`shadow-depth.py`, display luminance, 67js before > after / CycThe dark percentiles move toward Cycles in every row but by small steps (p1 by 0.000 to 0.005, p25 by 0.003 to 0.004; `temple-hall` p1 is now within 0.0007 of Cycles). The lit to shadow contrast does not move (at most 0.02 log2 step), as the opt-in section said: a sky term lowers lit and shadowed tiles together. `temple-hall-b` p1 and p5 do not move because its darkest pixels are lit by its lamps, not by the sky. The contrast gap needs a deeper sun shadow, not sky light, and is still open.-Cost, measured on a loaded machine (another heavy job ran beside, so read these as ranges; `frame-time.mjs --plain`, one run each): `temple-hall` 1.83 ms without and 2.23 ms with, `dark-shaft` 2.38 ms without and 2.11 ms with. The trace takes 1.2 s and 0.6 s when the scene is prepared. Size: `entry:floor-sky-visibility` +93 bytes gzip, no other entry changes.+Cost, measured on a loaded machine (another heavy job ran beside, so read these as ranges; `frame-time.mjs --plain`, one run each): `temple-hall` 1.83 ms without and 2.23 ms with, `dark-shaft` 2.38 ms without and 2.11 ms with. The trace takes 1.2 s and 0.6 s when the scene is prepared. Size: `entry:floor-sky-visibility` +202 bytes gzip, `scene:agent-scene` +448 (102996 to 103444, a goal scene, over its goal of 100000), `scene:agent-scene+lazy` +3836, `scene:lit-box` 0.-The full suite (`npm run reference`, then `--grand`, with Blender 5.2.2 and fresh Cycles renders) ran once on this change and reproduced the numbers above (`temple-hall` 0.0617, `dark-shaft` 0.0576). It also moved rows this change does not touch (fresh Cycles renders against a newer main), so `baseline.json`, `grand.json` and the sheet images are left as they were; the rows of `temple-hall`, `dark-shaft` and the three temple options are stale by the changes above until the next refresh.+Rows refreshed: `temple-hall` and `dark-shaft` in `baseline.json` (with their sheet images) and the three temple options in `grand.json`, from a Blender 5.2.2 rerun of just those scenes with the final code. The other rows, and `long-street` and `megacity-dusk-a`, which render identically, are left as they were.diff --git a/bench/reference/harness.js b/bench/reference/harness.jsindex 79a5cb62..8a92ea93 100644--- a/bench/reference/harness.js+++ b/bench/reference/harness.js@@ -18,7 +18,7 @@ import { applyLightLinks } from '/src/light-linking.js';import { applyWaterReflection, attachWaterReflection } from '/src/water-reflection.js';import { attachScreenSpaceWater } from './ssr-water.js';import { groundBounceEnvironment } from '/src/ground-bounce.js';-import { applyFloorSkyVisibility } from '/src/floor-sky-visibility.js';+import { applyDefaultFloorSky, applyFloorSkyVisibility } from '/src/floor-sky-visibility.js';import { installReversedDepth } from '/src/reversed-depth.js';// Water reflection is on the way a recipe gets it: found from the materials, no field. ?water=off draws the scenes without it, ?water=ssr with the screen-space reflection it was compared with.@@ -36,20 +36,19 @@ const REVERSED_DEPTH = new URLSearchParams(location.search).get('reversedDepth')const WATER_REFLECTION = { off: false, ssr: 'ssr' }[new URLSearchParams(location.search).get('water')] ?? 'planar';-// The sky each floor texel sees (src/floor-sky-visibility.js) scales the world light on floors. By default the scenes that are a closed room lit-// by a sun (the temple halls, the shaft) get it at the addon's room strength; lamp-only rooms and open scenes draw without it, because it made them worse.-// ?floorSky=0 draws every scene without it, ?floorSky=<strength> sets the strength, ?floorSkyRooms=1 traces every closed room and open scene alike.+// The scenes draw with the default of the recipe path: a closed room a sun lights gets the floor sky trace (applyDefaultFloorSky, the same call+// createAgentScene makes), and environment.floorSkyTrace: false turns it off. ?floorSky=0 sets that opt-out on every scene. ?floorSky=<strength>+// is an experiment that traces every floor at that strength instead, and ?floorSkyRooms=1 adds the closed rooms to it.const FLOOR_SKY_PARAMETER = new URLSearchParams(location.search).get('floorSky');-const FLOOR_SKY_ROOMS_MODE = new URLSearchParams(location.search).get('floorSkyRooms') ?? (FLOOR_SKY_PARAMETER === null ? 'sun' : null);+const FLOOR_SKY_EXPERIMENT = FLOOR_SKY_PARAMETER !== null && FLOOR_SKY_PARAMETER !== '0';const floorSkyReports = {};function withFloorSky(id, parts, scene) {- if (FLOOR_SKY_PARAMETER === '0') return parts;- const sunlit = (scene?.environment?.keyColor ?? [0, 0, 0]).some(channel => channel > 0);- if (FLOOR_SKY_ROOMS_MODE === 'sun' && !sunlit) return parts;- const strength = FLOOR_SKY_PARAMETER === null ? undefined : Number(FLOOR_SKY_PARAMETER);- const result = applyFloorSkyVisibility(parts, { strength, includeClosedRooms: FLOOR_SKY_ROOMS_MODE === '1', onlyClosedRooms: FLOOR_SKY_ROOMS_MODE === 'sun' });- floorSkyReports[id] = result.report;+ const environment = FLOOR_SKY_PARAMETER === '0' ? { ...scene.environment, floorSkyTrace: false } : scene.environment;+ const result = FLOOR_SKY_EXPERIMENT+ ? applyFloorSkyVisibility(parts, { strength: Number(FLOOR_SKY_PARAMETER), includeClosedRooms: new URLSearchParams(location.search).get('floorSkyRooms') === '1' })+ : applyDefaultFloorSky(parts, environment);+ if (result.report) floorSkyReports[id] = result.report;return result.parts;}diff --git a/bench/reference/run.mjs b/bench/reference/run.mjsindex bfe987dc..1c4c19b9 100644--- a/bench/reference/run.mjs+++ b/bench/reference/run.mjs@@ -55,7 +55,7 @@ const BACKEND_ARGUMENTS = {const argumentsGiven = process.argv.slice(2);// --floor-sky-rooms also traces closed rooms, which are left as they are otherwise.-// Closed rooms lit by a sun get the floor sky trace by default; --no-floor-sky draws without it, --floor-sky-sun is the same as the default.+// 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');const floorSkyStrength = floorSkyFlag < 0 ? 0 : Number(argumentsGiven[floorSkyFlag + 1]) || 1;@@ -114,7 +114,7 @@ const sceneIdsGiven = lookIds ?? (sceneFlag >= 0 ? argumentsGiven[sceneFlag + 1]// The fresh bake.json lands in the work directory and is checked against the committed one (compare-scores.mjs); --update-baseline replaces// the committed bake.json and images/<id>-baked.jpg with it.const bakeScoreRun = bakedSceneIds !== null && !sceneSet && !pathTracerFlag;-const bakeVariantFlags = ['--sky-only', '--bake-preset', '--bake-backend', '--bake-samples', '--bake-density', '--probes', '--ambient', '--ambient-occlusion', '--cascades', '--no-object-probes', '--object-probes', '--no-water', '--ssr-water', '--no-ground-bounce', '--floor-sky', '--floor-sky-rooms', '--floor-sky-sun', '--no-floor-sky'];+const bakeVariantFlags = ['--sky-only', '--bake-preset', '--bake-backend', '--bake-samples', '--bake-density', '--probes', '--ambient', '--ambient-occlusion', '--cascades', '--no-object-probes', '--object-probes', '--no-water', '--ssr-water', '--no-ground-bounce', '--floor-sky', '--floor-sky-rooms', '--no-floor-sky'];const bakeScoreIsBaseline = bakeScoreRun && argumentsGiven.includes('--update-baseline') && !bakeVariantFlags.some(flag => argumentsGiven.includes(flag));const onlyScenes = sceneIdsGiven ?? (bakeScoreRun ? bakedSceneIds : null);const skipCpu = skipCpuFlag || bakeScoreRun || Boolean(viewTransform);@@ -128,7 +128,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' : argumentsGiven.includes('--floor-sky-sun') ? 'floorSkyRooms=sun' : 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].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/197-sun-rooms.md b/changes/197-sun-rooms.mdindex 9a22943f..284cf090 100644--- a/changes/197-sun-rooms.md+++ b/changes/197-sun-rooms.md@@ -1 +1 @@-- Add `onlyClosedRooms` to `applyFloorSkyVisibility` (issue #197) and `report.meanVisibility`. It traces closed rooms only, at the default strength 0.2 (`FLOOR_SKY_ROOM_STRENGTH`), and leaves open scenes alone, where the trace made streets and cities too dark. The reference harness now applies it by default to closed rooms lit by a sun (`temple-hall`, `dark-shaft` and the three grand temple options; lamp-only rooms and open scenes draw as before), `--no-floor-sky` turns it off. FLIP against Cycles: the four hall scenes improve by 0.0023 to 0.0096, `dark-shaft` moves by +0.0017, nothing else changes. The core entry is unchanged. The README has the numbers.+- Turn the floor sky trace (issue #197) on by default in the recipe path for a closed room a sun lights, at strength 0.2: `createAgentScene` calls `applyDefaultFloorSky(parts, environment)` from a lazily loaded module, loaded when the recipe names its sun (`keyColor` or `keyIntensity`). Open scenes and rooms lit by lamps alone are left as they are, because the trace made those worse against Cycles. `environment.floorSkyTrace: false` opts out (documented in `docs/agent-look.md`). `applyFloorSkyVisibility` gains `onlyClosedRooms`, a lower default strength with it, and `report.meanVisibility`. FLIP against Cycles: `temple-hall` -0.0023, the three grand temple options -0.0051 to -0.0096, `dark-shaft` +0.0017, no other scene past 0.002. The README has the numbers.diff --git a/changes/197-sun-rooms.size.md b/changes/197-sun-rooms.size.mdindex 568f4a88..9636b459 100644--- a/changes/197-sun-rooms.size.md+++ b/changes/197-sun-rooms.size.md@@ -1 +1,3 @@-- entry:floor-sky-visibility: +93 bytes gzip (15101 to 15194) for the onlyClosedRooms option, the room strength constant and the mean visibility in the report; core entries unchanged+- entry:floor-sky-visibility: +202 bytes gzip (15101 to 15303) for the onlyClosedRooms option, the room strength, the mean visibility in the report and applyDefaultFloorSky+- scene:agent-scene: +448 bytes gzip (102996 to 103444) for the floorSkyTrace field, the staging call and the lazy module entry that give closed rooms lit by a sun the floor sky trace by default+- scene:agent-scene+lazy: +3836 bytes gzip (351298 to 355134), the same code plus the floor sky module loadeddiff --git a/docs/agent-look.md b/docs/agent-look.mdindex 2070efbd..4085b7db 100644--- a/docs/agent-look.md+++ b/docs/agent-look.md@@ -109,6 +109,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` |+| `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. 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). || `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 3002b0f4..4fbdbc34 100644--- a/docs/lighting.md+++ b/docs/lighting.md@@ -147,7 +147,7 @@ The other 19 reference scenes drew the same pixels (mean, p20 and FLIP identical## Sky seen from the floor-`applyFloorSkyVisibility(parts, { strength, includeClosedRooms, onlyClosedRooms })` (`67js/addons/floor-sky-visibility`) is opt-in and returns `{ parts, report }`. It cuts the floor parts into texels, shoots 64 cosine-weighted rays from each against the other opaque parts and stores the share that escapes as the floor's `skyVisibility`, so the world and sky light on a floor under a roof or between walls is scaled down and open ground is not. Pass the returned parts to the renderer. `strength` 1 uses the traced share, 0.5 keeps half of what it hides. `onlyClosedRooms: true` is the setting that helped: it traces closed rooms only, at strength 0.2 unless you pass one, and leaves open scenes alone. Use it for a room a sun lights through its openings (the reference halls); a room lit by lamps alone and open ground are better without it. A closed room is left alone unless `includeClosedRooms` is `true`, and a scene that is too large (over 200,000 triangles), has no floor or runs past `maxSeconds` (20) comes back unchanged with `report.reason`. It is not on by default: it moves the dark end of halls and studio floors toward Cycles, and makes sunlit streets too dark (`long-street` +0.0135 FLIP at 0.5). The trace takes 0.5 to 1.7 s, and the floor grows to about 66,000 triangles, which adds 0.1 to 0.3 ms per frame in the reference scenes. Numbers: `bench/reference/README.md`, "Sky visibility traced from the floor texels".+`applyFloorSkyVisibility(parts, { strength, includeClosedRooms, onlyClosedRooms })` (`67js/addons/floor-sky-visibility`) is opt-in and returns `{ parts, report }`. It cuts the floor parts into texels, shoots 64 cosine-weighted rays from each against the other opaque parts and stores the share that escapes as the floor's `skyVisibility`, so the world and sky light on a floor under a roof or between walls is scaled down and open ground is not. Pass the returned parts to the renderer. `strength` 1 uses the traced share, 0.5 keeps half of what it hides. `onlyClosedRooms: true` is the setting that helped: it traces closed rooms only, at strength 0.2 unless you pass one, and leaves open scenes alone. Use it for a room a sun lights through its openings (the reference halls); a room lit by lamps alone and open ground are better without it. A closed room is left alone unless `includeClosedRooms` is `true`, and a scene that is too large (over 200,000 triangles), has no floor or runs past `maxSeconds` (20) comes back unchanged with `report.reason`. The recipe path turns it on for closed rooms a sun lights (`environment.floorSkyTrace`, `false` opts out; see agent-look.md) via `applyDefaultFloorSky(parts, environment)`. Every other use is opt-in: on open ground it makes sunlit streets too dark (`long-street` +0.0135 FLIP at 0.5). The trace takes 0.5 to 1.7 s, and the floor grows to about 66,000 triangles, which adds 0.1 to 0.3 ms per frame in the reference scenes. Numbers: `bench/reference/README.md`, "Sky visibility traced from the floor texels".## Local shadowsdiff --git a/src/agent-look.js b/src/agent-look.jsindex 9fbee670..82a70dca 100644--- a/src/agent-look.js+++ b/src/agent-look.js@@ -13,7 +13,7 @@ const MAX_LOOK_ARRAY_ENTRIES = Math.max(MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, MAX_Aconst ENVIRONMENT_FIELDS = ['world', 'ground', 'setup', 'environmentIntensity', 'environmentRotation', 'lightDirection', 'keyColor', 'keyIntensity', 'fillIntensity', 'ambientIntensity',- 'daylight', 'pointLights', 'spotLights', 'areaLights', 'skyTop', 'skyBottom', 'fogColor', 'fogDensity', 'volumeFog', 'liquid', 'shadowCascades', 'keyAffects', 'objectReflections', 'lines', 'resolveCoplanar', 'viewTransform', 'look', 'wind',+ 'daylight', 'pointLights', 'spotLights', 'areaLights', 'skyTop', 'skyBottom', 'fogColor', 'fogDensity', 'volumeFog', 'liquid', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'lines', 'resolveCoplanar', 'viewTransform', 'look', 'wind',];const EFFECT_FIELDS = ['exposure', 'saturation', 'contrast', 'temperature', 'vignette', 'grain', 'ambientOcclusion', 'ambientOcclusionRadius', 'bloom', 'depthOfField', 'motionBlur'];const SHADOW_FIELDS = ['target', 'extent', 'distance', 'near', 'far'];@@ -272,6 +272,12 @@ function environmentFrom(input = {}) {}environment.objectReflections = input.objectReflections;}+ if (input.floorSkyTrace !== undefined) {+ if (typeof input.floorSkyTrace !== 'boolean') {+ throw new TypeError('environment.floorSkyTrace must be a boolean.');+ }+ environment.floorSkyTrace = input.floorSkyTrace;+ }// Outlines and line geometry; null clears them. The module checks the fields and loads on demand.if (input.lines !== undefined && input.lines !== null) {environment.lines = copiedJson(agentSceneModule('lineArt').resolveLineArt(input.lines));diff --git a/src/agent-scene-modules.js b/src/agent-scene-modules.jsindex 800c42d0..49f51ee9 100644--- a/src/agent-scene-modules.js+++ b/src/agent-scene-modules.js@@ -31,6 +31,7 @@ const MODULE_LOADERS = {lineArt: () => import('./line-art.js'),viewTransform: () => import('./view-transform-shader.js'),coplanar: () => import('./coplanar-overlap.js'),+ floorSky: () => import('./floor-sky-visibility.js'),};const loadedModules = {};@@ -70,6 +71,8 @@ const MODULE_MARKERS = {viewTransform: ['"viewTransform":"agx"', '"viewTransform":"neutral"', '"look":"'],// The coplanar-overlap warning in scene_inspect appears only once this is loaded, which loadAllAgentSceneModules does; a recipe with resolveCoplanar needs it.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"'],};/** Whether a recipe, operation list or edit list contains a boolean edit, which needs loadMeshBooleans() first. */diff --git a/src/agent-scene.js b/src/agent-scene.jsindex a3d4f394..fee92dfa 100644--- a/src/agent-scene.js+++ b/src/agent-scene.js@@ -1119,7 +1119,7 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {const sourceRestParts = sameParts ? state.sourceRestParts : Object.freeze(nextParts);const lightBakeResult = stageLightBake(recipe, sourceRestParts, graph);const reflected = stageObjectReflections(recipe, sourceRestParts, lightBakeResult ? lightBakeResult.parts : sourceRestParts, graph);- const restParts = stageCoplanarOffsets(recipe, stageLightLinks(recipe, reflected ? reflected.parts : lightBakeResult ? lightBakeResult.parts : sourceRestParts));+ const restParts = stageCoplanarOffsets(recipe, stageLightLinks(recipe, stageFloorSky(recipe, reflected ? reflected.parts : lightBakeResult ? lightBakeResult.parts : sourceRestParts)));const stagedState = {recipe, geometryRecords, geometries, graph, materialHandles,// Part identity decides what the next stage reuses, so it compares the parts as built, before any bake.@@ -1202,6 +1202,21 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {return objectReflectionCache.result;}+ // A closed room a sun lights gets the sky each floor texel sees (src/floor-sky-visibility.js), unless environment.floorSkyTrace is false. It runs+ // only when that code is loaded, which a recipe that names its sun does; open scenes and lamp-only rooms come back unchanged. The result is kept while the parts are the same objects.+ let floorSkyCache = null;+ function stageFloorSky(recipe, parts) {+ if (recipe.environment.floorSkyTrace === false || !agentSceneModuleLoaded('floorSky')) {+ return parts;+ }+ if (floorSkyCache?.parts === parts && floorSkyCache.environment === recipe.environment) {+ return floorSkyCache.result;+ }+ const result = agentSceneModule('floorSky').applyDefaultFloorSky(parts, recipe.environment).parts;+ floorSkyCache = { parts, environment: recipe.environment, result };+ return result;+ }+// A scene that asks for no bake and looks like a closed room gets one diagnostic naming the bake. The ray test costs a// few milliseconds, so it runs for scene_inspect only and is kept until the scene changes.function isLitByLampsOnly(environment) {@@ -1444,7 +1459,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' ? ['spotLights', 'areaLights', 'shadowCascades', 'keyAffects', 'objectReflections', 'lines', 'resolveCoplanar', 'viewTransform', 'look'] : [];+ const optionalFields = lookField === 'environment' ? ['spotLights', 'areaLights', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'lines', 'resolveCoplanar', 'viewTransform', 'look'] : [];knownKeys(patch, [...Object.keys(candidate[lookField]), ...optionalFields], lookField);const nestedField = lookField === 'environment' ? 'volumeFog' : lookField === 'effects' ? 'bloom' : null;const merged = { ...candidate[lookField], ...(lookField === 'environment' ? environmentPatchWithSetup(patch) : patch) };diff --git a/src/floor-sky-visibility.js b/src/floor-sky-visibility.jsindex e71a1cca..0a20f5cf 100644--- a/src/floor-sky-visibility.js+++ b/src/floor-sky-visibility.js@@ -279,3 +279,19 @@ export function applyFloorSkyVisibility(parts, { raysPerTexel = FLOOR_SKY_RAYS,const meanVisibility = texels ? floors.reduce((total, floor) => total + floor.meanVisibility * floor.texels, 0) / texels : 1;return { parts: Object.freeze(nextParts), report: { floors, texels, meanVisibility, rays: totalRays, seconds: (performance.now() - started) / 1000, reason: null } };}++/** True when the environment has a sun: a key light with a colour and intensity above zero. A recipe that sets neither has the default sun. */+export function environmentHasSun(environment) {+ const keyColor = environment?.keyColor ?? [1, 1, 1];+ return (environment?.keyIntensity ?? 1) * (keyColor[0] + keyColor[1] + keyColor[2]) > 0;+}++/**+ * The default for a scene: a closed room a sun lights gets the sky trace at `FLOOR_SKY_ROOM_STRENGTH`, and every other scene (open ground,+ * a room lit by lamps alone) comes back unchanged, because the trace made those worse against Cycles. `environment.floorSkyTrace: false`+ * turns it off. The recipe path (`createAgentScene`) and the reference harness both call this, so they draw the same frame.+ */+export function applyDefaultFloorSky(parts, environment) {+ if (environment?.floorSkyTrace === false || !environmentHasSun(environment)) return { parts, report: null };+ return applyFloorSkyVisibility(parts, { onlyClosedRooms: true });+}diff --git a/tests/agent-floor-sky-trace.test.js b/tests/agent-floor-sky-trace.test.jsnew file mode 100644index 00000000..1b2d8038--- /dev/null+++ b/tests/agent-floor-sky-trace.test.js@@ -0,0 +1,45 @@+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';++// A closed room: a floor, four walls and a closed roof, lit by a sun.+function room(environment = {}) {+ const wall = (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.5, 0.45, 0.4], roughness: 0.8 }],+ nodes: [+ wall('floor', [0, -0.05, 0], [10, 0.1, 10]),+ wall('wall-left', [-5, 2, 0], [0.2, 4, 10]),+ wall('wall-right', [5, 2, 0], [0.2, 4, 10]),+ wall('wall-front', [0, 2, 5], [10, 4, 0.2]),+ wall('wall-back', [0, 2, -5], [10, 4, 0.2]),+ wall('roof-a', [-2.5, 4.1, 0], [5.2, 0.2, 10.4]),+ wall('roof-b', [2.5, 4.1, 0], [5.2, 0.2, 10.4]),+ ],+ camera: { eye: [0, 1.5, 4], target: [0, 1.5, 0], fov: 60, near: 0.05, far: 40 },+ environment,+ };+}++function floorHasSkyVisibility(scene) {+ return Boolean(scene.parts.find(part => part.name === 'floor').geometry.skyVisibility);+}++test('a closed room lit by a sun gets the floor sky trace by default', () => {+ assert.equal(floorHasSkyVisibility(createAgentScene(room({ keyColor: [3, 3, 3] }))), true);+});++test('environment.floorSkyTrace false turns the trace off, and a non-boolean throws', () => {+ assert.equal(floorHasSkyVisibility(createAgentScene(room({ keyColor: [3, 3, 3], floorSkyTrace: false }))), false);+ assert.throws(() => createAgentScene(room({ floorSkyTrace: 'no' })), /floorSkyTrace must be a boolean/);+});++test('a room with no sun and open ground are left as they were', () => {+ assert.equal(floorHasSkyVisibility(createAgentScene(room({ keyColor: [0, 0, 0] }))), false);+ const open = room({ keyColor: [3, 3, 3] });+ open.nodes = open.nodes.filter(node => node.id === 'floor' || node.id === 'roof-a');+ assert.equal(floorHasSkyVisibility(createAgentScene(open)), false);+});