3D engine that AI agents drive
Bake volume report read from the recipe, not the bake cache (#809)
Nguyen Xuan An5b453c56d1ad
diff --git a/changes/809-volume-bake.size.md b/changes/809-volume-bake.size.mdindex 0c990d93..ec280723 100644--- a/changes/809-volume-bake.size.md+++ b/changes/809-volume-bake.size.md@@ -1 +1,3 @@-- scene:agent-scene+lazy: the bake report names the local volumes it leaves out, which an agent otherwise cannot tell from a missing glow (228 bytes gzip).+- scene:agent-scene: the bake report names the local volumes it leaves out, read from the recipe on every call so edits after the bake stay current, which an agent otherwise cannot tell from a missing glow (78 bytes gzip).+- scene:agent-scene+lazy: the same report and the capabilities note that a bake leaves local volumes out (328 bytes gzip).+- goal:agent-scene: the growth is an agent-facing warning (#809), 78 bytes gzip, with no cheaper place: the report is built where the scene reads the bake.diff --git a/docs/light-bake.md b/docs/light-bake.mdindex 5a5aad1a..6a31341c 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 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`.+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), `reused`, and, while the recipe has `environment.localVolumes`, `skippedLocalVolumes` (index, shape, emissive) and `warnings`: the bake leaves volumes out, read from the recipe on every call, so adding or clearing one updates them without a rebake.### Work budgetdiff --git a/src/agent-bake.js b/src/agent-bake.jsindex d08c3d5d..735c2ba7 100644--- a/src/agent-bake.js+++ b/src/agent-bake.js@@ -297,15 +297,22 @@ export function changedPartsOf(bakedParts, snapshots) {* rayWork, seconds, skipped parts with reasons.*/export function bakeAgentParts(parts, worldMatrices, environment, settings, generatedGeometryGenerators = new Map()) {- const baked = traceAgentBake(parts, worldMatrices, environment, settings, generatedGeometryGenerators);- const skippedVolumes = skippedLocalVolumes(environment.localVolumes);+ return traceAgentBake(parts, worldMatrices, environment, settings, generatedGeometryGenerators);+}++/**+ * Local volumes are drawn in the post pass and have no place in a lightmap, so the bake leaves them out. The report names+ * them from the recipe as it is now, outside the bake cache: adding or clearing a volume does not re-trace the bake.+ */+export function withLocalVolumeReport(report, localVolumes) {+ const skippedVolumes = skippedLocalVolumes(localVolumes);+ const { skippedLocalVolumes: staleVolumes, warnings: staleWarnings, ...cleanReport } = report;if (skippedVolumes.length === 0) {- return baked;+ return cleanReport;}- return { ...baked, report: { ...baked.report, skippedLocalVolumes: skippedVolumes, warnings: [localVolumesNotBakedWarning(skippedVolumes)] } };+ return { ...cleanReport, skippedLocalVolumes: skippedVolumes, warnings: [localVolumesNotBakedWarning(skippedVolumes)] };}-// Local volumes are drawn in the post pass and have no place in a lightmap, so the bake leaves them out; the report names them.function skippedLocalVolumes(localVolumes) {return (localVolumes ?? []).map((volume, index) => ({ index, shape: volume.shape, emissive: volume.emissionStrength > 0 && volume.emission.some(channel => channel > 0) }));}diff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.jsindex e46e6ba4..b9470d6f 100644--- a/src/agent-scene-capabilities.js+++ b/src/agent-scene-capabilities.js@@ -270,7 +270,7 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({maxSpotLights: MAX_SPOT_LIGHTS, maxAreaLights: MAX_AREA_LIGHTS,localShadows: Object.freeze({ lights: Object.freeze(['pointLights', 'spotLights']), atlasTiles: 24, pointLightTiles: 6, spotLightTiles: 1, tileSize: 512 }),lightLinking: Object.freeze({ fields: Object.freeze(['environment.keyAffects', 'pointLights[].affects', 'spotLights[].affects', 'areaLights[].affects']), unlisted: 'a light without affects lights every node', unknownNode: 'rejected', bake: 'honoured', pathTracer: 'ignored, named in report.ignored' }),- localVolumes: Object.freeze({ field: 'environment.localVolumes', maximum: 8, shapes: Object.freeze(['box', 'sphere', 'mesh']), fields: 'shape, center, size (box) or radius (sphere) or part + fit bounds|mesh (mesh: the named part, bounds by default; fit mesh needs a closed part and backend cpu), density 0-100 (1), falloff 0-1 (0.5), absorption rgb 0-1 (1,1,1), emission rgb 0-1, emissionStrength 0-1000 (1), noiseAmount 0-1 (0), noiseScale (1), steps 4-32 (16)', note: 'Absorb and emit, no scattering; needs hdr and depth like volumeFog; noise is raster only; path tracer: backend cpu only (gpu and native throw).' }),+ localVolumes: Object.freeze({ field: 'environment.localVolumes', maximum: 8, shapes: Object.freeze(['box', 'sphere', 'mesh']), fields: 'shape, center, size (box) or radius (sphere) or part + fit bounds|mesh (mesh: the named part, bounds by default; fit mesh needs a closed part and backend cpu), density 0-100 (1), falloff 0-1 (0.5), absorption rgb 0-1 (1,1,1), emission rgb 0-1, emissionStrength 0-1000 (1), noiseAmount 0-1 (0), noiseScale (1), steps 4-32 (16)', note: 'Absorb and emit, no scattering; needs hdr and depth like volumeFog; noise is raster only; path tracer: backend cpu only (gpu and native throw); a bake leaves them out, so an emissive volume lights no baked surface (bake report: skippedLocalVolumes, warnings).' }),shadowCascades: Object.freeze({ field: 'environment.shadowCascades', counts: Object.freeze([0, 1, 2, 3, 4]), zero: 'one shadow map', automatic: 'three cascades when shadow.extent is above 40 and the field is unset', maximumDistance: 150, note: 'volume fog and water read the single map' }),lineArt: Object.freeze({ field: 'environment.lines', fields: 'width px 0.25-16 (1.5), color, boundaries, creaseAngle deg (35), depthJump (0.08), toon steps 0-8, polylines [{points [x,y,z] 2-256, color, width, depthTest, closed}] max 64; {} turns on, null clears; material toon 0-8', note: 'docs/line-art.md' }),viewTransform: Object.freeze({diff --git a/src/agent-scene.js b/src/agent-scene.jsindex d4359efd..0fef685e 100644--- a/src/agent-scene.js+++ b/src/agent-scene.js@@ -1516,7 +1516,7 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {// Part identity decides what the next stage reuses, so it compares the parts as built, before any bake.sourceRestParts,parts: restParts, restParts,- bakeReport: lightBakeResult ? { ...lightBakeResult.report, reused: lightBakeResult.reused } : null,+ bakeReport: lightBakeResult ? agentSceneModule('bake').withLocalVolumeReport({ ...lightBakeResult.report, reused: lightBakeResult.reused }, recipe.environment.localVolumes) : null,reflectionReport: reflected ? reflected.report : null,// A renderer holding the deformed cloth parts of the old state needs the rest parts back as a topology change.topologyChanged: Boolean(state && (restParts !== state.restParts || state.parts !== state.restParts)),@@ -1575,7 +1575,7 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {const rebaked = state.recipe.bake?.rebake && agentSceneModule('bake').bakeAtSampledPose(lightBake, state.recipe, pose);if (rebaked) {state.restParts = stageRestParts(state.recipe, state.sourceRestParts, rebaked, pose.graph).restParts;- state.bakeReport = rebaked.report;+ state.bakeReport = agentSceneModule('bake').withLocalVolumeReport(rebaked.report, state.recipe.environment.localVolumes);}}diff --git a/tests/agent-bake.test.js b/tests/agent-bake.test.jsindex cf83f907..a4fc1180 100644--- a/tests/agent-bake.test.js+++ b/tests/agent-bake.test.js@@ -106,3 +106,21 @@ test('a bake names the local volumes it leaves out and a scene without volumes rassert.match(volumed.warnings[0], /localVolumes\[0\] \(sphere, emissive\), environment\.localVolumes\[1\] \(box\)/);assert.equal(volumed.texels, plain.texels);});++test('the volume report follows localVolumes edits made after the bake, without a rebake', () => {+ const scene = createAgentScene(closedRoom());+ assert.equal(scene.inspect().bake.skippedLocalVolumes, undefined);++ const volume = { shape: 'sphere', center: [0, 1, 0], radius: 0.5, emission: [1, 0.6, 0.2] };+ scene.apply([{ type: 'set-environment', environment: { localVolumes: [volume] } }], { expectedRevision: 0 });+ const added = scene.inspect().bake;+ assert.equal(added.reused, true);+ assert.deepEqual(added.skippedLocalVolumes, [{ index: 0, shape: 'sphere', emissive: true }]);+ assert.equal(added.warnings.length, 1);++ scene.apply([{ type: 'set-environment', environment: { localVolumes: [] } }], { expectedRevision: 1 });+ const cleared = scene.inspect().bake;+ assert.equal(cleared.reused, true);+ assert.equal(cleared.skippedLocalVolumes, undefined);+ assert.equal(cleared.warnings, undefined);+});