3D engine that AI agents drive
Bake: allow up to 8 bounces for lightmaps and the irradiance grid (issue #462)
Nguyen Xuan Anec287629a2e2
diff --git a/bench/reference/harness.js b/bench/reference/harness.jsindex 666446f4..28ef3aea 100644--- a/bench/reference/harness.js+++ b/bench/reference/harness.js@@ -176,7 +176,7 @@ function describeScene(id, scene) {// Blender always gets the original parts: the bake is 67js's approximation of what Cycles computes.async function bakeScene(scene, bakeOptions) {if (bakeOptions.preset) {- return bakeScenePreset(scene, bakeOptions.preset, bakeOptions.irradianceGrid);+ return bakeScenePreset(scene, bakeOptions.preset, bakeOptions.irradianceGrid, { bounces: bakeOptions.bounces });}const { bakeLightmapsAsync } = await import('/src/light-bake-gpu.js');const { pointLights, keyColor, lightDirection } = scene.environment;@@ -188,9 +188,9 @@ async function bakeScene(scene, bakeOptions) {// The bake an agent gets from `bake: { preset }`: the same settings and budget fit as a recipe. Probes stay out of it and come// from --probes, as in the other rows.-async function bakeScenePreset(scene, preset, irradianceGrid = false) {+async function bakeScenePreset(scene, preset, irradianceGrid = false, overrides = {}) {const { normalizeAgentBake, bakeAgentParts } = await import('/src/agent-bake.js');- const settings = normalizeAgentBake({ preset, probes: false, ...(irradianceGrid ? { irradianceGrid } : {}) });+ const settings = normalizeAgentBake({ preset, probes: false, ...(overrides.bounces ? { bounces: overrides.bounces } : {}), ...(irradianceGrid ? { irradianceGrid } : {}) });const started = performance.now();let baked;try {diff --git a/bench/reference/run.mjs b/bench/reference/run.mjsindex 836e13a8..278f1f14 100644--- a/bench/reference/run.mjs+++ b/bench/reference/run.mjs@@ -118,7 +118,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 = ['--no-glossy', '--sky-only', '--bake-preset', '--bake-grid', '--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 bakeVariantFlags = ['--no-glossy', '--sky-only', '--bake-preset', '--bake-grid', '--bake-bounces', '--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);@@ -148,7 +148,7 @@ async function renderBackend(backend, serverUrl, graphics) {// Object probes are on by default, as in a recipe, so the baseline scores what a user gets.const objectProbesThisScene = !argumentsGiven.includes('--no-object-probes') && (objectProbeSceneIds === null || objectProbeSceneIds.includes(id));const probes = probesThisScene || (objectProbesThisScene ? 'objects' : false);- const bake = bakesThisScene ? { ...skyOnlyOptions, ...(bakePreset ? { preset: bakePreset } : {}), ...(argumentsGiven.includes('--bake-grid') ? { irradianceGrid: Number(argumentsGiven[argumentsGiven.indexOf('--bake-grid') + 1]) || true } : {}), ...(bakeBackend ? { backend: bakeBackend } : {}), ...(bakeSamples ? { samples: bakeSamples } : {}), ...(bakeDensity ? { texelsPerUnit: bakeDensity } : {}) } : null;+ const bake = bakesThisScene ? { ...skyOnlyOptions, ...(bakePreset ? { preset: bakePreset } : {}), ...(argumentsGiven.includes('--bake-grid') ? { irradianceGrid: Number(argumentsGiven[argumentsGiven.indexOf('--bake-grid') + 1]) || true } : {}), ...(argumentsGiven.includes('--bake-bounces') ? { bounces: Number(argumentsGiven[argumentsGiven.indexOf('--bake-bounces') + 1]) } : {}), ...(bakeBackend ? { backend: bakeBackend } : {}), ...(bakeSamples ? { samples: bakeSamples } : {}), ...(bakeDensity ? { texelsPerUnit: bakeDensity } : {}) } : null;const result = await page.evaluate(([sceneId, shouldDescribe, ambientOcclusion, ambientOcclusionRadius, bakeOptions, cascadeCount, withProbes, ambientScale, selectedViewTransform]) => window.renderReferenceScene(sceneId, { describe: shouldDescribe, ambientOcclusion, ambientOcclusionRadius, bake: bakeOptions, cascades: cascadeCount, probes: withProbes, ambient: ambientScale, viewTransform: selectedViewTransform }), [id, describe, ambientOcclusion, ambientOcclusionRadius, bake, cascades, probes, ambient, viewTransform]);if (result.glError !== 0) throw new Error(`${id} on ${backend} gave WebGL error ${result.glError}.`);graphics[backend] = result.graphics;diff --git a/changes/462-warmth.md b/changes/462-warmth.mdnew file mode 100644index 00000000..22630bb9--- /dev/null+++ b/changes/462-warmth.md@@ -0,0 +1 @@+- Allow `bake.bounces` up to 8 (was 3) for the lightmap bake and the irradiance grid (issue #462). Cycles gathers 8 bounces and the grid stopped at 3, which left sunlit rooms cooler and darker: on a synthetic room with an orange floor and a warm sun, 8 bounces read 28% warmer (R/B) and 30% brighter than 3, and the grid matched its own 3-bounce gather within 2%. On the agent-built reading-corner room with the grid, 8 bounces move R/B from 1.22 to 1.27 (Cycles 1.44) and FLIP against Cycles from 0.4035 to 0.3817. The default stays 3, so no scene changes unless a recipe asks for more. The reference harness gets `--bake-bounces <n>`.diff --git a/docs/light-bake.md b/docs/light-bake.mdindex b3b36c1d..11c99250 100644--- a/docs/light-bake.md+++ b/docs/light-bake.md@@ -28,7 +28,7 @@ const renderer = new Renderer67(canvas, bakedParts, rendererOptions);| `standard` (default) | 128 | 2 | 6 || `fine` | 192 | 2 | 7 |-Ranges are 1 to 256 samples, 1 to 3 bounces and 1 to 12 texels per unit. The bake lights the rest pose with the recipe's point lights and key light (key colour times `keyIntensity`). It runs when the scene builds and again only when a part, its matrix, a light, a material or the bake fields change: camera edits, effects edits, motion seeks and renders reuse the result. A bake that passes its time limit fails the edit and leaves the scene as it was. The limit is 90 s when the bake runs on a worker (the MCP preview does this, so it blocks nothing) and 20 s on the page's own thread when there is no Worker. The preview's call deadline grows by the 90 s for a `scene_create` whose recipe has a `bake` and for a `scene_apply` with `set-bake`; other calls keep 30 s. A `scene_apply` also gets it whenever the active scene already has a bake, because an ordinary edit such as moving a part rebakes. The same recipe gives the same lightmap bytes. `scene_inspect` returns `bake`: the resolved fields, `used` (the samples, bounces and texelsPerUnit that were traced), `reduced`, `texels`, `rayWork`, `seconds` (of the run that made the lightmaps), `bakedParts`, `skipped` (name and reason) and `reused`.+Ranges are 1 to 256 samples, 1 to 8 bounces and 1 to 12 texels per unit. The bake lights the rest pose with the recipe's point lights and key light (key colour times `keyIntensity`). It runs when the scene builds and again only when a part, its matrix, a light, a material or the bake fields change: camera edits, effects edits, motion seeks and renders reuse the result. A bake that passes its time limit fails the edit and leaves the scene as it was. The limit is 90 s when the bake runs on a worker (the MCP preview does this, so it blocks nothing) and 20 s on the page's own thread when there is no Worker. The preview's call deadline grows by the 90 s for a `scene_create` whose recipe has a `bake` and for a `scene_apply` with `set-bake`; other calls keep 30 s. A `scene_apply` also gets it whenever the active scene already has a bake, because an ordinary edit such as moving a part rebakes. The same recipe gives the same lightmap bytes. `scene_inspect` returns `bake`: the resolved fields, `used` (the samples, bounces and texelsPerUnit that were traced), `reduced`, `texels`, `rayWork`, `seconds` (of the run that made the lightmaps), `bakedParts`, `skipped` (name and reason) and `reused`.### Work budgetdiff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.jsindex 5a733093..54cd20a7 100644--- a/src/agent-scene-capabilities.js+++ b/src/agent-scene-capabilities.js@@ -106,7 +106,7 @@ export const BAKE_PRESETS = Object.freeze({// An alias of standard: measured on the five reference rooms, no samples and density mix within the 20 s limit scored better (bench/reference/README.md).fine: Object.freeze({ samples: 128, bounces: 3, texelsPerUnit: 6 }),});-export const BAKE_RANGES = Object.freeze({ samples: [1, 256], bounces: [1, 3], texelsPerUnit: [1, 12] });+export const BAKE_RANGES = Object.freeze({ samples: [1, 256], bounces: [1, 8], texelsPerUnit: [1, 12] });export const BAKE_MAXIMUM_SECONDS = 20;/** The limit when the bake runs on a worker, which does not block the page: a busy machine still finishes a preset. */export const BAKE_WORKER_MAXIMUM_SECONDS = 90;@@ -273,7 +273,7 @@ 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-3), 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); probes room by default, false for none, or up to 4 {position, radius?}. Same recipe, same bytes.',+ 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); probes room by default, false for none, or up to 4 {position, radius?}. Same recipe, same bytes.',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, never refuses (bake.used, bake.reduction); explicit settings fail over maxPathWork or past maxSeconds. No environment map or specular. Probes: specular only, none in glTF.',limits: Object.freeze({ maxSeconds: BAKE_MAXIMUM_SECONDS, workerMaxSeconds: BAKE_WORKER_MAXIMUM_SECONDS, maxPathWork: BAKE_EXPLICIT_PATH_WORK_LIMIT, maxPointLights: MAX_POINT_LIGHTS }),diff --git a/src/irradiance-grid.js b/src/irradiance-grid.jsindex 9c5d44dc..d0eff3d5 100644--- a/src/irradiance-grid.js+++ b/src/irradiance-grid.js@@ -14,7 +14,7 @@ import { worldBounds } from './probe-trace.js';// This module is optional. A scene without `bake.irradianceGrid` never loads it, and the renderer's only link to it is the// material field `irradianceGrid`, which batches parts by grid.-export const IRRADIANCE_GRID_LIMITS = Object.freeze({ resolution: [8, 48], samples: [4, 128], bounces: [1, 3], maxNodes: 65536 });+export const IRRADIANCE_GRID_LIMITS = Object.freeze({ resolution: [8, 48], samples: [4, 128], bounces: [1, 8], maxNodes: 65536 });// `true` picks the cell size itself: at most this many nodes along the longest side and at most AUTO_NODE_BUDGET in all. The// budget keeps the trace inside the bake's time limit (20 s on the page's thread): a closed 68 m hall with 31,768 nodes took// 40 s, the bake was refused and the scene was drawn with no grid at all (temple-hall-b, FLIP 0.1535 against 0.1211 with a grid).diff --git a/src/light-bake.js b/src/light-bake.jsindex 093dda2b..a70224eb 100644--- a/src/light-bake.js+++ b/src/light-bake.js@@ -16,7 +16,7 @@ export const BAKE_LIMITS = Object.freeze({maxResolution: { minimum: 4, maximum: 256, fallback: 128 },texelsPerUnit: { minimum: 0.5, maximum: 64, fallback: 6 },samples: { minimum: 1, maximum: 512, fallback: 128 },- bounces: { minimum: 1, maximum: 4, fallback: 3 },+ bounces: { minimum: 1, maximum: 8, fallback: 3 },maxSeconds: { minimum: 1, maximum: 600, fallback: 60 },});// Total ray work (texels x samples x bounces x rays per hit) a bake may ask for, checked before any ray is traced.diff --git a/tests/agent-bake.test.js b/tests/agent-bake.test.jsindex 5216ef7b..6ab98f59 100644--- a/tests/agent-bake.test.js+++ b/tests/agent-bake.test.js@@ -51,7 +51,7 @@ test('bake presets and fields resolve to plain numbers within their ranges', ()test('bake rejects hostile and out of range fields', () => {const hostile = [{ preset: 'ultra' }, { samples: 0 }, { samples: 257 }, { samples: 1e9 }, { samples: NaN }, { samples: '64' },- { samples: 2.5 }, { bounces: 4 }, { bounces: 1.5 }, { texelsPerUnit: 0.5 }, { texelsPerUnit: 13 },+ { samples: 2.5 }, { bounces: 9 }, { bounces: 1.5 }, { texelsPerUnit: 0.5 }, { texelsPerUnit: 13 },{ maxSeconds: 600 }, { unknown: 1 }, [], 'standard', JSON.parse('{"__proto__":{"samples":1}}'),];for (const input of hostile) {diff --git a/tests/light-bake.test.js b/tests/light-bake.test.jsindex b2e95f6f..aae07142 100644--- a/tests/light-bake.test.js+++ b/tests/light-bake.test.js@@ -142,7 +142,7 @@ test('a part marked as generating its own geometry is skipped', () => {test('options are validated with their bounds', () => {const fallbacks = Object.fromEntries(Object.entries(BAKE_LIMITS).map(([name, limit]) => [name, limit.fallback]));assert.deepEqual(normalizeBakeOptions({}), { ...fallbacks, backend: 'cpu' });- for (const [name, bad] of [['samples', 0], ['samples', 513], ['samples', Number.NaN], ['bounces', 5], ['maxResolution', 3], ['maxResolution', 1e9], ['texelsPerUnit', 0], ['texelsPerUnit', Infinity], ['maxSeconds', 0], ['maxSeconds', '60']]) {+ for (const [name, bad] of [['samples', 0], ['samples', 513], ['samples', Number.NaN], ['bounces', 9], ['maxResolution', 3], ['maxResolution', 1e9], ['texelsPerUnit', 0], ['texelsPerUnit', Infinity], ['maxSeconds', 0], ['maxSeconds', '60']]) {assert.throws(() => normalizeBakeOptions({ [name]: bad }), { name: 'RangeError', message: new RegExp(name) }, `${name} ${bad}`);}for (const bad of [null, [], 'fast', 3]) assert.throws(() => normalizeBakeOptions(bad), TypeError);