3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Keep the coplanar search bounded for large grounds with many copies (#2302)
Nguyen Xuan An4da6838b135c
diff --git a/changes/2302.md b/changes/2302.mdnew file mode 100644index 00000000..d8095cfe--- /dev/null+++ b/changes/2302.md@@ -0,0 +1 @@+- A large ground with thousands of instanced copies no longer fails scene_create with "Map maximum size exceeded": the coplanar search makes its grid coarser when it would list over 16 million cells, and a grid still too large names `environment.resolveCoplanar` (#2302)diff --git a/changes/2302.size.md b/changes/2302.size.mdnew file mode 100644index 00000000..ffb60918--- /dev/null+++ b/changes/2302.size.md@@ -0,0 +1 @@+- scene:agent-scene+lazy: the coplanar search grid made coarser instead of throwing on large scenes (+227 bytes gzip: a sampled entry estimate, a retry loop and the error that names resolveCoplanar), so scene_create succeeds for a ground plus thousands of copiesdiff --git a/docs/agent-look.md b/docs/agent-look.mdindex 9467fa59..d7cd68d8 100644--- a/docs/agent-look.md+++ b/docs/agent-look.md@@ -121,7 +121,7 @@ Sky colors use display RGB, matching the renderer's existing environment contrac| `world` | `false` | Boolean world presentation flag. With `true` the setup environment is also the background || `hdri` | absent | A shipped HDRI (`sky-clouds`, `studio-softbox`) or the 64-character ID of a `.hdr` file in `scene_asset_catalog`. It lights, reflects and (with `world: true`) forms the background instead of the setup sky; `environmentIntensity` is its strength and `environmentRotation` turns it about the vertical axis. The setup still gives the key light, so set `keyIntensity: 0` when the HDRI has its own sun. `null` clears. See [Catalog HDRIs and looks](#catalog-hdris-and-looks) || `ground` | on | Absent unless set. `false` removes the preview's automatic floor and contact shadow |-| `resolveCoplanar` | `'offset'` | Flush and near-flush faces, inside one mesh or across parts, are ranked per triangle and drawn with a small depth-only bias, so the face in front wins at every distance and nothing flickers. Geometry never moves. `false` opts out, and `scene_inspect` then lists each pair as a `coplanar-overlap` warning (only pairs closer than the pair's own reach, never more than 50 mm). Parts that set `decal` or `depthLayer` keep their own layer. Where an opaque face covers another on the same plane, or in front of it by at most a thousandth of the shared face (between a millimetre and a centimetre), the covered part is cut out of the drawn copy of the hidden face (the part and its geometry stay as you made them), so a stack of any depth is settled and the path tracer sees one face. What cannot be settled comes back as a `coplanar-overlap` warning with a `reason`: `rank-overflow` (more than 16 faces a wider gap apart), `double-sided-gap`, `unchecked` (past the triangle or pair budget, the part the search stopped at is named) or `collapsed-node` (an axis a millionth of the longest one; a 2 cm slab 400 m wide is a ground, not a collapse) |+| `resolveCoplanar` | `'offset'` | Flush and near-flush faces, inside one mesh or across parts, are ranked per triangle and drawn with a small depth-only bias, so the face in front wins at every distance and nothing flickers. Geometry never moves. `false` opts out, and `scene_inspect` then lists each pair as a `coplanar-overlap` warning (only pairs closer than the pair's own reach, never more than 50 mm). Parts that set `decal` or `depthLayer` keep their own layer. Where an opaque face covers another on the same plane, or in front of it by at most a thousandth of the shared face (between a millimetre and a centimetre), the covered part is cut out of the drawn copy of the hidden face (the part and its geometry stay as you made them), so a stack of any depth is settled and the path tracer sees one face. What cannot be settled comes back as a `coplanar-overlap` warning with a `reason`: `rank-overflow` (more than 16 faces a wider gap apart), `double-sided-gap`, `unchecked` (past the triangle or pair budget, the part the search stopped at is named) or `collapsed-node` (an axis a millionth of the longest one; a 2 cm slab 400 m wide is a ground, not a collapse). A scene of millions of triangles gets a coarser search grid instead of an error; the search only fails, with a message naming this field, when even the coarsest grid is too large || `objectReflections` | on | Absent unless set. Each smooth metal part (`metallic` 0.5 or more, `roughness` 0.6 or less; at most 8 such parts, in a scene with at most 1,024 other 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` || `sky` | absent | Absent unless set. `{ type: 'physical', preset, sunElevation, sunRotation, turbidity, groundAlbedo, aerialPerspective, ozone, sunDisc }`: one time-of-day control. `sunElevation` -90 to 90 degrees (default 45), `sunRotation` degrees clockwise from -Z seen from above (0), `turbidity` 1 to 10 haze (3), `groundAlbedo` 0 to 1 (0.3), `aerialPerspective` 0 to 4 scales the distance haze (1; 0 for none), `ozone` 0 to 10 Chappuis-band absorption (1), `sunDisc` boolean (true; the disc is drawn per pixel at `sunAngularRadius`, 0.5 degrees by default, so it stays a sharp round disc at any zoom, and it is not in the baked sky map). `preset` is `golden-hour` (sun 4 degrees up), `sunset` (1 degree) or `blue-hour` (4 degrees below the horizon), each with the sun turned to rotation 250: it supplies the sun only, fields beside it win, and a preset in a `set-environment` patch starts the sky again from its own sun with the other fields at their defaults. A sun below 14 degrees is fitted to Blender's sky (checked at 2, 6 and 15 degrees, comparison in `docs/golden-hour-comparison.jpg`): a narrow saturated orange band forms along the horizon, the zenith dims and the key warms and strengthens; at 14 degrees and above the sky is unchanged. The sky sets `lightDirection`, `keyColor` (the sun reddens and dims with air mass and sets below the horizon), `skyTop`, `skyBottom`, `fogColor` and `fogDensity`, and replaces the setup's environment map with the sky. A `keyColor`, `fogColor` or `fogDensity` you write beside the sky (in the recipe or in the same `set-environment` patch) wins over the value the sky derives, so a preset fills them only when you leave them out; `lightDirection`, `skyTop` and `skyBottom` always follow the sky. A later patch that changes the sky without naming them goes back to the derived values. `environment` motion tracks can animate `sunElevation`, `sunRotation`, `turbidity`, `groundAlbedo`, `aerialPerspective` and `ozone` for time-of-day arcs. A `set-environment` patch changes the fields it names and keeps the rest; `sky: null` in a patch keeps the last derived values as plain fields. It is an analytic single-scattering approximation (Rayleigh, aerosol and ozone, Kasten-Young air mass), not Blender's Nishita integration: no clouds. Raster first: the path tracer backends read the same environment map and key light, but are not yet checked against it. || `sky` (gradient) | absent | `{ type: 'gradient', stops: [{ at, color }], horizonGlow: { color, width, intensity } }`: a sky whose colours you pick, for a mood that physics would not give (a teal anime sky with a bright cyan band at the horizon). `stops` holds 1 to 8 entries with `at` rising from 0 (horizon) to 1 (zenith, by elevation angle) and `color` as a `#rrggbb` hex in sRGB; below the horizon the first stop continues. `horizonGlow` is optional: `color` as hex, `width` 0.5 to 45 degrees of elevation (the half width of the band, default 6) and `intensity` 0 to 20 (default 1) multiplies the glow colour at the horizon, so 1 shows the colour as given; the band blends toward the glow colour, so it keeps its hue and does not wash to white until the colour itself is bright. The stop and glow colours are compensated for the scene's view transform and the display power, so the frame shows the hex you gave at the horizon, the stops, the zenith and the glow peak (measured within 1 level under `aces` and `neutral`); between stops the colours blend in OKLab, which keeps the lightness and hue steady and bands less than a blend of encoded values. The inverse assumes exposure 1, no look and no post effect, divides by `environmentIntensity`, and is exact for `aces`; `agx` and `neutral` are solved numerically, and a colour they cannot show (a saturated red under `neutral`, pure white under `agx`) lands on the nearest one they can. The scene light and the water reflection read the same compensated radiance, so a gradient lights the scene more strongly than the same hex taken as plain radiance would. The same colours are the background (with `world: true`), the light and reflections of the scene, and the water reflection. It sets `skyTop`, `skyBottom` and `fogColor` from the first and last stop and leaves the sun, the key light and the fog density to the setup and the recipe. A `set-environment` patch with `type: 'gradient'` replaces a physical sky; a patch without `type` edits the gradient in place. Raster first; the path tracer backends read the same map but are not checked against it. |diff --git a/src/flush-search.js b/src/flush-search.jsindex 94eeb3f7..b9c064b2 100644--- a/src/flush-search.js+++ b/src/flush-search.js@@ -25,6 +25,10 @@ const NATIVE_CELL_LIMIT = 64;const GRID_LEVEL_SCALE = 16;const GRID_LEVELS = 2;const CELL_SAMPLES = 4096;+// A JS Map holds at most 2^24 entries and throws a bare RangeError past it. The grid stops listing triangles at this many+// native cells and is built again with cells twice as wide, up to MAXIMUM_GRID_COARSENINGS times.+const MAXIMUM_GRID_ENTRIES = 16_000_000;+const MAXIMUM_GRID_COARSENINGS = 8;// Tags whose vertex shader moves vertices (renderer.js DEFORMING_TAGS): their triangles are not where the geometry says.const DEFORMING_TAGS = new Set(['foliage', 'grass', 'water', 'fire', 'smoke']);@@ -243,6 +247,7 @@ function normalCellsOf(table, id, cells) {}const cellRange = new Int32Array(6);+const estimateNormalCells = [];// The grid cells a triangle's box touches at one level, grown by half the reach so two boxes within the reach share a cell.// Returns how many cells that is.@@ -258,13 +263,35 @@ function cellRangeOf(table, id, cellSize, reach) {return cells;}+// The finest grid level where the triangle spans at most NATIVE_CELL_LIMIT cells.+function nativeLevelOf(table, id, cellSize, reach) {+ let level = 0;+ while (level < GRID_LEVELS && cellRangeOf(table, id, cellSize * GRID_LEVEL_SCALE ** level, reach) > NATIVE_CELL_LIMIT) level++;+ return level;+}++// How many native cell entries buildCells would make, projected from CELL_SAMPLES evenly spaced triangles.+function estimateNativeEntries(table, cellSize, reach) {+ const stride = Math.max(1, Math.floor(table.count / CELL_SAMPLES));+ let sampledEntries = 0;+ let sampled = 0;+ for (let id = 0; id < table.count; id += stride) {+ const level = nativeLevelOf(table, id, cellSize, reach);+ const normalCellCount = normalCellsOf(table, id, estimateNormalCells).length;+ sampledEntries += level === GRID_LEVELS ? normalCellCount : normalCellCount * cellRangeOf(table, id, cellSize * GRID_LEVEL_SCALE ** level, reach);+ sampled++;+ }+ return (sampledEntries / sampled) * table.count;+}+function cellKey(normalCell, level, cellX, cellY, cellZ) {const mixed = Math.imul(cellX, 73856093) ^ Math.imul(cellY, 19349663) ^ Math.imul(cellZ, 83492791) ^ Math.imul(normalCell * GRID_LEVELS + level, 0x9e3779b1);return mixed >>> 0;}// Lists every triangle in the cells of its own level (`natives`), then as a guest in the coarser cells that hold a native.-// The last level is one cell per normal cell, for triangles too large for any grid.+// The last level is one cell per normal cell, for triangles too large for any grid. Returns null when the natives would pass+// MAXIMUM_GRID_ENTRIES, so the caller can try wider cells.function buildCells(table, cellSize, reach) {const levels = Array.from({ length: GRID_LEVELS + 1 }, () => new Map());const nativeLevel = new Uint8Array(table.count);@@ -285,16 +312,18 @@ function buildCells(table, cellSize, reach) {}}};+ let nativeEntries = 0;for (let id = 0; id < table.count; id++) {- let level = 0;- while (level < GRID_LEVELS && cellRangeOf(table, id, cellSize * GRID_LEVEL_SCALE ** level, reach) > NATIVE_CELL_LIMIT) level++;+ const level = nativeLevelOf(table, id, cellSize, reach);nativeLevel[id] = level;const cells = levels[level];visitCells(id, level, key => {+ nativeEntries++;const cell = cells.get(key);if (cell) cell.natives.push(id);else cells.set(key, { natives: [id], guests: [] });});+ if (nativeEntries > MAXIMUM_GRID_ENTRIES) return null;}for (let id = 0; id < table.count; id++) {for (let level = nativeLevel[id] + 1; level <= GRID_LEVELS; level++) {@@ -306,6 +335,18 @@ function buildCells(table, cellSize, reach) {return levels.flatMap(cells => [...cells.values()]);}+// Wider cells list each triangle in fewer of them and leave the pairs found the same. A grid is made wider only when a sample+// of the triangles projects past MAXIMUM_GRID_ENTRIES, or when building it passes that, so every scene that fit keeps its grid.+function buildCoarsenedCells(table, reach) {+ let cellSize = gridCellSize(table, reach);+ for (let coarsening = 0; coarsening <= MAXIMUM_GRID_COARSENINGS; coarsening++, cellSize *= 2) {+ if (estimateNativeEntries(table, cellSize, reach) > MAXIMUM_GRID_ENTRIES) continue;+ const cells = buildCells(table, cellSize, reach);+ if (cells) return cells;+ }+ throw new RangeError(`The coplanar search has ${table.count} triangles in a scene too large to index. Pass environment.resolveCoplanar: false to skip the search, or split the scene into smaller ones.`);+}+const clipFirst = new Float64Array(32);const clipSecond = new Float64Array(32);const sharedCentre = new Float64Array(2);@@ -513,7 +554,7 @@ export function findFlushPairs(parts, { triangleBudget = DEFAULT_TRIANGLE_BUDGET// No pair of parts spans more than the scene, so this is the widest gap any pair is tested with.const reach = nearTolerance(boundsDiagonal(sceneBounds));const testPair = createPairTest(table, entries, reach, pairBudget, testedPairLimit, result);- for (const cell of buildCells(table, gridCellSize(table, reach), reach)) testCell(cell, table, reach, testPair);+ for (const cell of buildCoarsenedCells(table, reach)) testCell(cell, table, reach, testPair);result.pairs.sort((first, second) => first.first - second.first || first.second - second.second);return result;}diff --git a/tests/flush-search-grid-limit.test.js b/tests/flush-search-grid-limit.test.jsnew file mode 100644index 00000000..1551abf7--- /dev/null+++ b/tests/flush-search-grid-limit.test.js@@ -0,0 +1,31 @@+import test from 'node:test';+import assert from 'node:assert/strict';+import { createAgentScene } from '../src/agent-scene.js';+import { loadAllAgentSceneModules } from '../src/agent-scene-modules.js';++// Issue #2302: a 160 m ground widens the search reach, which put about 16 million cell entries of two million small triangles+// into one Map and threw "Map maximum size exceeded" from scene_create.+function scatterNode(id, geometry, seed) {+ return { id, geometry, material: 'red', instances: { scatter: { count: 600, min: [-14, 0.3, -14], max: [14, 4.5, 14] }, seed, yaw: true, scale: [0.5, 1.2] } };+}++function groundWithCopiesRecipe() {+ return {+ format: 'crucible.scene', schemaVersion: 1,+ geometries: [{ id: 'ball', type: 'icoSphere', subdivisions: 2 }, { id: 'gem', type: 'box' }, { id: 'slab', type: 'box' }],+ materials: [{ id: 'red', color: [0.9, 0.3, 0.2], roughness: 0.5 }],+ nodes: [+ { id: 'ground', geometry: 'slab', material: 'red', translation: [0, -0.1, 0], scale: [160, 0.2, 160] },+ scatterNode('balls0', 'ball', 1), scatterNode('balls1', 'gem', 2), scatterNode('balls2', 'ball', 3), scatterNode('balls3', 'gem', 4),+ ],+ camera: { eye: [0, 8, 30], target: [0, 2, 0], fov: 40 },+ environment: { world: true },+ };+}++test('a large ground with 2,400 instanced copies builds with the coplanar search on', { timeout: 120_000 }, async () => {+ const recipe = groundWithCopiesRecipe();+ await loadAllAgentSceneModules();+ const scene = createAgentScene(recipe);+ assert.equal(scene.parts.length, 2401);+});