3D engine that AI agents drive
Keep the floor sky default in the lazy module, one conditional call in core (part of #197)
Nguyen Xuan An38edf745d67a
diff --git a/bench/reference/README.md b/bench/reference/README.mdindex e020b20f..018b9b74 100644--- a/bench/reference/README.md+++ b/bench/reference/README.md@@ -1809,7 +1809,7 @@ 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` +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.+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` +285 bytes gzip, `scene:agent-scene` +375 (102996 to 103371, a goal scene, over its goal of 100000), `scene:agent-scene+lazy` +3846, `scene:lit-box` 0.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/changes/197-sun-rooms.md b/changes/197-sun-rooms.mdindex 284cf090..047f2202 100644--- a/changes/197-sun-rooms.md+++ b/changes/197-sun-rooms.md@@ -1 +1 @@-- 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.+- 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, any other value leaves it on (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 9636b459..47b2275a 100644--- a/changes/197-sun-rooms.size.md+++ b/changes/197-sun-rooms.size.md@@ -1,3 +1,3 @@-- 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 loaded+- entry:floor-sky-visibility: +285 bytes gzip (15101 to 15386) for the onlyClosedRooms option, the room strength, the mean visibility in the report, applyDefaultFloorSky and the recipe stage with its cache+- scene:agent-scene: +375 bytes gzip (102996 to 103371) for the floorSkyTrace field, one conditional call into the lazy module and the module entry with its markers; the sun and closed-room tests live in the lazy chunk+- scene:agent-scene+lazy: +3846 bytes gzip (352062 to 355908), the same code plus the floor sky module loadeddiff --git a/src/agent-look.js b/src/agent-look.jsindex 82a70dca..5ecab5bd 100644--- a/src/agent-look.js+++ b/src/agent-look.js@@ -272,10 +272,8 @@ function environmentFrom(input = {}) {}environment.objectReflections = input.objectReflections;}+ // Only `false` opts out of the floor sky trace (src/floor-sky-visibility.js); any other value leaves it on.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.diff --git a/src/agent-scene.js b/src/agent-scene.jsindex fee92dfa..7540e352 100644--- a/src/agent-scene.js+++ b/src/agent-scene.js@@ -1202,19 +1202,9 @@ 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;+ // A closed room a sun lights gets the sky each floor texel sees; the lazy module decides, keeps its result and honours environment.floorSkyTrace.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;+ return agentSceneModuleLoaded('floorSky') ? agentSceneModule('floorSky').stageFloorSky(recipe.environment, parts) : parts;}// A scene that asks for no bake and looks like a closed room gets one diagnostic naming the bake. The ray test costs adiff --git a/src/floor-sky-visibility.js b/src/floor-sky-visibility.jsindex 0a20f5cf..64a9390f 100644--- a/src/floor-sky-visibility.js+++ b/src/floor-sky-visibility.js@@ -291,7 +291,21 @@ export function environmentHasSun(environment) {* 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) {+export function applyDefaultFloorSky(parts, environment, options = {}) {if (environment?.floorSkyTrace === false || !environmentHasSun(environment)) return { parts, report: null };- return applyFloorSkyVisibility(parts, { onlyClosedRooms: true });+ return applyFloorSkyVisibility(parts, { onlyClosedRooms: true, ...options });+}++const defaultResults = new WeakMap();++/** The recipe path's call: the default for these parts and this environment, kept until either is replaced. */+export function stageFloorSky(environment, parts) {+ if (environment.floorSkyTrace === false) return parts;+ let byEnvironment = defaultResults.get(parts);+ if (!byEnvironment) {+ byEnvironment = new WeakMap();+ defaultResults.set(parts, byEnvironment);+ }+ if (!byEnvironment.has(environment)) byEnvironment.set(environment, applyDefaultFloorSky(parts, environment).parts);+ return byEnvironment.get(environment);}diff --git a/tests/agent-floor-sky-trace.test.js b/tests/agent-floor-sky-trace.test.jsindex 1b2d8038..9b71db1c 100644--- a/tests/agent-floor-sky-trace.test.js+++ b/tests/agent-floor-sky-trace.test.js@@ -2,6 +2,7 @@ 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 { applyDefaultFloorSky } from '../src/floor-sky-visibility.js';// A closed room: a floor, four walls and a closed roof, lit by a sun.function room(environment = {}) {@@ -28,13 +29,16 @@ function floorHasSkyVisibility(scene) {return Boolean(scene.parts.find(part => part.name === 'floor').geometry.skyVisibility);}+// The recipe path runs the same call with the default texel count, which takes seconds; the test keeps the trace small.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);+ const { parts } = createAgentScene(room({ keyColor: [3, 3, 3], floorSkyTrace: false }));+ const result = applyDefaultFloorSky(parts, { keyColor: [3, 3, 3] }, { maximumTexels: 400 });+ assert.equal(result.report.reason, null);+ assert.ok(result.parts.find(part => part.name === 'floor').geometry.skyVisibility);});-test('environment.floorSkyTrace false turns the trace off, and a non-boolean throws', () => {+test('environment.floorSkyTrace false turns the trace off', () => {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', () => {