3D engine that AI agents drive
Report bake-stale when motion moves a baked light, and add bake.rebake (issue #603)
Nguyen Xuan An6b234104ea3d
diff --git a/changes/603-bake-stale.md b/changes/603-bake-stale.mdnew file mode 100644index 00000000..9312f40a--- /dev/null+++ b/changes/603-bake-stale.md@@ -0,0 +1 @@+- `scene_inspect` reports a `bake-stale` warning when motion has moved a light, the sun or a part off the pose a light bake was traced at; a scene without motion or without a bake pays nothing. `bake.rebake: true` traces on every build and silences the warning. Material animation is not checked, see docs/light-bake.md (#603)diff --git a/changes/603-bake-stale.size.md b/changes/603-bake-stale.size.mdnew file mode 100644index 00000000..0d45482a--- /dev/null+++ b/changes/603-bake-stale.size.md@@ -0,0 +1 @@+- scene:agent-scene+lazy: the stale check, the bake key and `bake.rebake` live in the lazy bake chunk, which now imports the motion look code it needs to sample lights; the core bundle shrinks by 7 bytes because the new capability text is paid for by shorter notes.diff --git a/docs/light-bake.md b/docs/light-bake.mdindex ce521c55..bc670bab 100644--- a/docs/light-bake.md+++ b/docs/light-bake.md@@ -148,3 +148,11 @@ Measured 2026-11-04 on a closed 8 m room with one lamp (6 walls, 4,098 to 1,836The CPU gatherer treats every part as a Lambertian surface of its diffuse albedo. The kernel evaluates the tracer's own material: the diffuse part shrinks by the Fresnel share and the specular lobe (a GGX lobe of F0 0.04 at the default `ior`, the colour for a metal) reflects light from the other surfaces towards the texel. With the lobe switched off the two backends agree to 0.6 percent over the room; the 0.1 to 1.9 percent that is left sits on the walls, not on floor and ceiling, does not move with the lamp radius (0.05 or 0.001), and is not isolated. Every other suspect from #412 was ruled out by that diffuse-only room: the first bounce's cosine weighting, emission and sky (neither is present), the bounce count (both follow `bounces` hits), and Russian roulette (starts after the third hit, so it never runs at 3 bounces or fewer). A texel offset or normal that was wrong would show on the diffuse room too, and it does not beyond the residual above.Both are right for their own model. The GPU light is the one a path tracer such as Cycles also sees, which is why it scores nearer to Cycles on `lit-interior` (0.0914 against 0.1129); the CPU light is the diffuse-only reference. Use the CPU backend for a lightmap with no light from specular surfaces, and the GPU backend when rooms hold glossy floors, metal or clear coat. `tests/light-bake-backends.test.js` keeps the diffuse agreement under 1 percent and the GPU's extra light on a glossy room above 1.5 percent.++## When to rebake++The bake is traced at the authored pose and is cached by a key over the bake settings, the lights, the materials and the world matrix of every part. Any recipe edit that changes one of them traces again on the next build, so an edit never leaves a stale bake.++Motion is the exception: a motion track can move a light, the sun or a part after the bake was traced, and the baked light stays where it was. When a bake and motion both exist, `scene_inspect` compares the key at the sampled time with the baked key and reports a `bake-stale` diagnostic when they differ. A scene without motion, or at a time where nothing moved, pays nothing and gets no warning. Material animation is not part of the check.++To fix it, bake a pose that stays put (keep lit lights and parts still, or animate only unlit things), or set `bake.rebake` to `true` with `set-bake`. `rebake` skips the cache so every build traces again, and it silences `bake-stale`. It traces the authored pose, so it does not make baked light follow motion; clear it with `set-bake` without the field once the scene is final.diff --git a/src/agent-bake.js b/src/agent-bake.jsindex 82581504..59ed8f65 100644--- a/src/agent-bake.js+++ b/src/agent-bake.js@@ -1,5 +1,6 @@import { planLightmaps, estimateBake, traceLightmaps } from './light-bake.js';import { runKernel } from './kernel-offload.js';+import { motionEnvironment } from './agent-motion.js';import { normalizeProbeList, traceProbes } from './probe-trace.js';import { placeProbes } from './reflection-probes.js';import { normalizeIrradianceGrid, placeIrradianceGrid, traceIrradianceGrid, withMeanRadiance } from './irradiance-grid.js';@@ -12,7 +13,7 @@ const PRESET_SAMPLES_FLOOR = 16;// Recipe `bake`: bounced light written into lightmaps when the scene builds. This module loads on demand, so scenes// without a bake never download the ray tracer.-const BAKE_FIELDS = ['preset', 'samples', 'bounces', 'texelsPerUnit', 'probes', 'irradianceGrid', 'gridFog'];+const BAKE_FIELDS = ['preset', 'samples', 'bounces', 'texelsPerUnit', 'probes', 'irradianceGrid', 'gridFog', 'rebake'];const BAKED_MATERIAL_FIELDS = ['emission', 'emissiveColor', 'emissiveMap', 'lightMap', 'lightMapScale', 'occlusionMap', 'occlusionStrength'];/** Validates a recipe bake section and returns the plain, resolved form stored in the recipe (null clears it). */@@ -53,6 +54,13 @@ export function normalizeAgentBake(input) {}resolved.gridFog = true;}+ // Not stored when off, so the default bake keeps its bytes.+ if (input.rebake !== undefined && typeof input.rebake !== 'boolean') {+ throw new RangeError('bake.rebake must be a boolean.');+ }+ if (input.rebake === true) {+ resolved.rebake = true;+ }for (const field of ['samples', 'bounces']) {if (!Number.isInteger(resolved[field])) {throw new RangeError(`Bake ${field} must be an integer.`);@@ -61,6 +69,32 @@ export function normalizeAgentBake(input) {return resolved;}+/**+ * The text a bake is cached by: the bake settings (not `rebake`), the lights, materials and the world matrix of every+ * part. The scene stores it when it bakes; a frame whose key differs is lit by a bake that no longer matches.+ */+export function lightBakeKey(recipe, generatedGeometryGenerators, environment, worldMatrices) {+ const { pointLights, spotLights, areaLights, keyColor, keyIntensity, lightDirection, keyAffects } = environment;+ return JSON.stringify([{ ...recipe.bake, rebake: undefined }, [...generatedGeometryGenerators], pointLights, spotLights, areaLights, keyColor, keyIntensity, lightDirection, keyAffects, recipe.materials,+ [...worldMatrices].map(([name, matrix]) => [name, Array.from(matrix)])]);+}++/** The scene_inspect diagnostics for a bake whose inputs, at the sampled pose, differ from the ones it was traced at. */+export function staleBakeProblems(state, generators, bakedKey) {+ const environment = state.movedLook ? motionEnvironment(structuredClone(state.recipe.environment), state.movedLook) : state.recipe.environment;+ const graph = state.poseGraph ?? state.graph;+ const worldMatrices = new Map(state.sourceRestParts.map(part => [part.name, graph.getNode(part.name).worldMatrix]));+ return lightBakeKey(state.recipe, generators, environment, worldMatrices) === bakedKey ? [] : [staleBakeDiagnostic()];+}++function staleBakeDiagnostic() {+ return {+ kind: 'bake-stale', severity: 'warning', target: 'bake',+ message: 'A light, the sun or a part has moved from the pose the bake was traced at, so the baked light no longer matches the frame.',+ fix: 'Bounced light does not follow motion. Bake a pose that stays put, or set bake.rebake true (scene_apply set-bake) to trace again on every build and silence this. Material animation is not checked.',+ };+}+function isPreset(settings) {return Object.values(BAKE_PRESETS).some(preset => Object.keys(preset).every(field => preset[field] === settings[field]));}diff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.jsindex 4f619f87..bce835ec 100644--- a/src/agent-scene-capabilities.js+++ b/src/agent-scene-capabilities.js@@ -170,7 +170,7 @@ export const MESH_SHAPE_KEY_NOTES = Object.freeze({// Organic shaping edits. Details stay here so the tool schemas stay small.export const MESH_SCULPT_NOTES = Object.freeze({- sculpt: 'strokes run in order on the vertices of the selected faces; other vertices stay, so a tag confines them. A stroke has type inflate (along the vertex normal), displace (along direction, needed) or smooth (strength 0 to 1), center and radius, strength in mesh units (negative pushes in). Falloff is smooth to zero at the radius. For bulges, dents and softened forms.',+ sculpt: 'strokes run in order on the vertices of the selected faces; other vertices stay, so a tag confines them. A stroke has type inflate (along the vertex normal), displace (along direction, needed) or smooth (strength 0 to 1), center and radius, strength in mesh units (negative pushes in); falloff is smooth. For bulges, dents and softened forms.',shrinkwrap: 'target is a primitive record placed by translation, rotation and scale. mode nearest (default) moves each selected vertex to the closest point; project moves it along direction (needed) to the first hit. offset (default 0) stands it off along the normal, on the side it came from. maxDistance limits the search; onMiss error (default) or keep. To lay a flat grid sheet onto a curved target as a decal, use enough cells to follow the curve, then solidify.',});@@ -179,8 +179,8 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({geometryTypes: Object.freeze(['box', 'cylinder', 'sphere', 'cone', 'icoSphere', 'torus', 'lathe', 'extrude', 'tube', 'curve', 'text', 'grid', 'plane', 'circle', 'line', 'terrain', 'mesh']),camera: 'eye, target, up, near, far, then fov (vertical degrees) or focalLength (mm, with sensorWidth mm, default 36; not both). projection orthographic with orthoScale (view height in m, default 4). shift [x, y] moves the frame by a fraction of its width and height. fStop (0.7 to 64) turns on depth of field focused on target; 1.4 or lower is full blur, and effects.depthOfField.blur must stay 0. Orthographic and shifted cameras render with the rasterizer, not the path tracer.',terrain: 'One mesh, x and z from -size/2 to size/2, hills about y = 0. size 40 m (1-2000), resolution 64 cells (2-256), seed 1, amplitude 1 m (0-200), holes up to 16 of {center:[x,z],radius} with no surface inside; radius a few cells or more.',- placedAssets: 'Node field asset:{id,materials?,clip?,drive?} turns a group node into a catalog GLB (id from asset_catalog; scene_create_asset is one asset alone). Its transform places it. materials:[{name,color,metallic,roughness,opacity,emission,emissiveColor}] override source materials by name. clip:{index,start=0,speed=1,loop=true} plays that clip from scene time start, on a decoded copy of its own; scene_apply set-motion tracks move the node as usual and scene time seeks the clip. Copies of one asset share geometry and materials and draw as one batch. drive:{path | legs, cruiseSpeed | speed, wheels, lights} drives a car along a path in the placement frame on a decoded copy of its own (fields as motion.drive in an asset recipe, docs/vehicle.md; no tail-light glow). scene_inspect assets adds its wheels, rejectedNames and light signals. At most 512 placements, 16 assets, 16 playing a clip or driving. Render jobs do not draw placed assets yet; scene_look does.',- navigation: 'scene_inspect path:{ground,from:[x,z],to:[x,z]} returns a route over the ground node around its holes, steep slopes and the nodes in avoid:[ids] (box footprints), as keyframes [{time,value:[x,y,z]}] for a node translation track with interpolation LINEAR. radius 0.3 m is how far the walker position stays from holes and avoided nodes; maxSlope 40 degrees; cellSize defaults to radius; give seconds for the whole walk or speed (1.4 m/s); lift raises y, such as half the walker height. Ground and avoided nodes are read at their authored pose. Errors name an unwalkable start or goal, or one that cannot be reached.',+ placedAssets: 'Node field asset:{id,materials?,clip?,drive?} turns a group node into a catalog GLB (id from asset_catalog; scene_create_asset is one asset alone). Its transform places it. materials:[{name,color,metallic,roughness,opacity,emission,emissiveColor}] override source materials by name. clip:{index,start=0,speed=1,loop=true} plays that clip from scene time start, on a decoded copy of its own; scene_apply set-motion tracks move the node as usual and scene time seeks the clip. Copies of one asset share geometry and materials and draw as one batch. drive:{path | legs, cruiseSpeed | speed, wheels, lights} drives a car along a path in the placement frame on a decoded copy of its own (fields as motion.drive in an asset recipe, docs/vehicle.md; no tail-light glow). scene_inspect assets adds its wheels, rejectedNames and light signals. At most 512 placements, 16 assets, 16 playing a clip or driving. Render jobs skip placed assets; scene_look draws them.',+ navigation: 'scene_inspect path:{ground,from:[x,z],to:[x,z]} returns a route over the ground node around its holes, steep slopes and the nodes in avoid:[ids] (box footprints), as keyframes [{time,value:[x,y,z]}] for a node translation track with interpolation LINEAR. radius 0.3 m is how far the walker position stays from holes and avoided nodes; maxSlope 40 degrees; cellSize defaults to radius; give seconds for the whole walk or speed (1.4 m/s); lift raises y, such as half the walker height. Ground and avoided nodes use their authored pose. Errors name an unwalkable start or goal, or one that cannot be reached.',meshEdits: Object.freeze({ operations: Object.freeze(Object.keys(MESH_EDIT_OPERATIONS)), maxEdits: MAX_MESH_EDITS }),meshStack: Object.freeze({ operations: STACK_OPERATIONS, maxNodes: MAX_STACK_NODES }),meshModifiers: MESH_MODIFIER_NOTES,@@ -285,7 +285,7 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({}),// Recipe particles: closed-form from seeded launch values, so any time is computed directly and a seek never replays.particles: Object.freeze({- emitter: 'System node keeps its geometry as the particle shape; node transform does not move particles. Fields (defaults): node, seed (1), count (100), rate (per second; omit for a burst at 0), lifetime, speed, size (each number or [min, max]; 1, 1, 0.05), direction ([0,1,0]), spread (cone degrees, 30), emitter { shape point|box|sphere|disc, position, halfExtents, radius }, scale constant|shrink|grow, drag (1/s, 0), floor (world y particles land on).',+ emitter: 'System node keeps its geometry as the particle shape; node transform does not move particles. Fields (defaults): node, seed (1), count (100), rate (per second; omit for a burst at 0), lifetime, speed, size (number or [min, max]; 1, 1, 0.05), direction ([0,1,0]), spread (cone degrees, 30), emitter { shape point|box|sphere|disc, position, halfExtents, radius }, scale constant|shrink|grow, drag (1/s, 0), floor (world y particles land on).',hair: 'type hair grows strands from a read-only root surface node into node (its own geometry is ignored). Fields (defaults): surface, seed, count, length (m, number or [min, max], 0.1), segments (1-8, 4), width (m, 0.004), droop (0.5), lean (0.2), sway (tip travel m, off), swayRate (Hz, 0.5). Tapering tubes, no UVs.',sectionFields: 'systems, gravity ([0,-9.81,0]), wind (m/s; moves emitter particles only with drag > 0, and sets the hair sway direction), fields (also cloth; wind, turbulence, vortex, drag, magnet: docs/physics.md)',notes: 'Pure function of seed, index and time; raising count keeps earlier ones. No collision but the floor, no bounce, rotation, colour or alpha; no hair collision.',@@ -293,9 +293,9 @@ 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-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); gridFog true adds the fog (sunlit closed rooms; dark shafts too bright); 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); gridFog true adds the fog (sunlit closed rooms; dark shafts too bright); probes room by default, false for none, or up to 4 {position, radius?}; rebake true traces every build, no bake-stale. 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.',+ 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 (bake.used, bake.reduction); explicit settings fail over maxPathWork or past maxSeconds. No environment map or specular. Probes: specular, not in glTF.',limits: Object.freeze({ maxSeconds: BAKE_MAXIMUM_SECONDS, workerMaxSeconds: BAKE_WORKER_MAXIMUM_SECONDS, maxPathWork: BAKE_EXPLICIT_PATH_WORK_LIMIT, maxPointLights: MAX_POINT_LIGHTS }),}),motionLook: Object.freeze({diff --git a/src/agent-scene.js b/src/agent-scene.jsindex 9ee9427c..ace5d369 100644--- a/src/agent-scene.js+++ b/src/agent-scene.js@@ -1336,6 +1336,26 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {return linked;}+ function bakeGenerators(recipe) {+ const generators = new Map();+ for (const system of recipe.particles?.systems ?? []) {+ generators.set(system.node, 'a hair or particle system');+ }+ for (const sheet of recipe.cloth?.sheets ?? []) {+ generators.set(sheet.node, 'a cloth simulation');+ }+ return generators;+ }++ // The bake no longer matches the frame: motion moved a light, the sun or a part off the pose it was traced at.+ // Only a scene with both a bake and motion pays for this check, and bake.rebake turns it off.+ function staleBakeProblems() {+ if (!lightBake || !state.recipe.bake || state.recipe.bake.rebake || !state.motionSampler) {+ return [];+ }+ return agentSceneModule('bake').staleBakeProblems(state, bakeGenerators(state.recipe), lightBake.key);+ }+// A light bake costs seconds of ray tracing: it runs when the parts, the lights, the materials or the bake fields// change, and every other edit, seek or camera move reuses the last result.function stageLightBake(recipe, sourceRestParts, graph) {@@ -1343,18 +1363,9 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {return null;}const worldMatrices = new Map(sourceRestParts.map(part => [part.name, new Float32Array(graph.getNode(part.name).worldMatrix)]));- const { pointLights, keyColor, keyIntensity, lightDirection } = recipe.environment;- const generatedGeometryGenerators = new Map();- for (const system of recipe.particles?.systems ?? []) {- generatedGeometryGenerators.set(system.node, 'a hair or particle system');- }- for (const sheet of recipe.cloth?.sheets ?? []) {- generatedGeometryGenerators.set(sheet.node, 'a cloth simulation');- }- const { spotLights, areaLights } = recipe.environment;- const key = JSON.stringify([recipe.bake, [...generatedGeometryGenerators], pointLights, spotLights, areaLights, keyColor, keyIntensity, lightDirection, recipe.environment.keyAffects, recipe.materials,- [...worldMatrices].map(([name, matrix]) => [name, Array.from(matrix)])]);- if (lightBake?.key === key && lightBake.sourceRestParts === sourceRestParts) {+ const generatedGeometryGenerators = bakeGenerators(recipe);+ const key = agentSceneModule('bake').lightBakeKey(recipe, generatedGeometryGenerators, recipe.environment, worldMatrices);+ if (!recipe.bake.rebake && lightBake?.key === key && lightBake.sourceRestParts === sourceRestParts) {return { ...lightBake, reused: true };}const baked = agentSceneModule('bake').bakeAgentParts(sourceRestParts, worldMatrices, recipe.environment, recipe.bake, generatedGeometryGenerators);@@ -1714,7 +1725,7 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {return result;});const resident = geometryStats(ownedGeometryRecords());- const diagnostics = [...recipeDiagnostics(state.recipe), ...closedRoomProblems(), ...coplanarProblems()];+ const diagnostics = [...recipeDiagnostics(state.recipe), ...closedRoomProblems(), ...staleBakeProblems(), ...coplanarProblems()];return {revision, topologyRevision,...(state.recipe.motion?.ik?.length ? { motionIk: agentSceneModule('motion').compileAgentMotion(state.recipe.motion, state.recipe).sweepIk() } : {}),diff --git a/tests/agent-bake-stale.test.js b/tests/agent-bake-stale.test.jsnew file mode 100644index 00000000..0edd93b3--- /dev/null+++ b/tests/agent-bake-stale.test.js@@ -0,0 +1,48 @@+// A bake traced at the authored pose reports bake-stale when motion has moved a light off it (issue 603).+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 { closedRoom } from './support/agent-bake-rooms.mjs';++const LIGHT_MOVES = { kind: 'light', id: 'point:0', property: 'position', keyframes: [{ time: 0, value: [0, 2, 0] }, { time: 2, value: [1, 2, 0] }] };++function bakedRoom(bakeOverrides = {}) {+ const recipe = closedRoom({ bake: { preset: 'draft', ...bakeOverrides }, motion: { duration: 2, tracks: [LIGHT_MOVES] } });+ recipe.environment.pointLights = [{ position: [0, 2, 0], intensity: 10 }];+ return recipe;+}++const staleDiagnostics = scene => (scene.inspect().diagnostics ?? []).filter(entry => entry.kind === 'bake-stale');++test('moving a light with a motion track after a bake gives a bake-stale warning', () => {+ const scene = createAgentScene(bakedRoom());+ assert.deepEqual(staleDiagnostics(scene), []);+ scene.sampleMotion(0);+ assert.deepEqual(staleDiagnostics(scene), []);+ scene.sampleMotion(2);+ const [warning] = staleDiagnostics(scene);+ assert.equal(warning.severity, 'warning');+ assert.match(warning.fix, /bake\.rebake/);+ scene.sampleMotion(0);+ assert.deepEqual(staleDiagnostics(scene), []);+});++test('an unchanged scene, or one with a bake and no motion, gives no warning', () => {+ const scene = createAgentScene(bakedRoom());+ assert.equal(scene.inspect().bake.reused, false);+ assert.deepEqual(staleDiagnostics(scene), []);+ const { motion, ...withoutMotion } = bakedRoom();+ const unmoved = createAgentScene(withoutMotion);+ assert.deepEqual(staleDiagnostics(unmoved), []);+});++test('bake.rebake turns the warning off and skips the cache on a rebuild', () => {+ const scene = createAgentScene(bakedRoom({ rebake: true }));+ scene.sampleMotion(2);+ assert.deepEqual(staleDiagnostics(scene), []);+ assert.equal(scene.inspect().bake.rebake, true);+ const firstBake = scene.inspect().bake.reused;+ assert.equal(firstBake, false);+ assert.throws(() => createAgentScene(bakedRoom({ rebake: 'yes' })), /rebake must be a boolean/);+});