3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Guard streaming loads and tile field inputs (#2490)
Nguyen Xuan An618440970691
diff --git a/changes/2490.md b/changes/2490.mdnew file mode 100644index 00000000..2438fce3--- /dev/null+++ b/changes/2490.md@@ -0,0 +1 @@+- Streaming fails an asset whose loader resolves with no asset instead of leaving it pending, keeps resident assets when a load can never fit the budget, and createTileField rejects an inverted area or a non-positive tileSize (#2490, #2491, #2492).diff --git a/docs/streaming.md b/docs/streaming.mdindex b9ceecec..039f08aa 100644--- a/docs/streaming.md+++ b/docs/streaming.md@@ -26,7 +26,7 @@ const runtime = createRuntime(renderer, { systems: [input, physics, streaming] }## Memory budget-`budgetBytes` caps loaded bytes plus the `estimatedBytes` of loads in flight. Before a load starts, assets nobody wants are freed until it fits. The order is lowest `priority` first (a number from -100 to 100, default 0, set on the asset), then by `evictionOrder`: `"recency"` (the default, unchanged from before) frees the least recently used first and breaks ties by distance; `"distance"` frees the farthest from the focus first and breaks ties by recency. Last comes the id, so the same walk always frees the same assets. Reading an asset with `getAsset(id)` or keeping it wanted counts as a use. If nothing can be freed, the load waits and update tries again. When a loader reports more bytes than estimated, the system frees unwanted assets to get back under the budget. Wanted and requested assets are never freed, so a budget smaller than what the player needs shows as waiting loads in `stats`.+`budgetBytes` caps loaded bytes plus the `estimatedBytes` of loads in flight. Before a load starts, assets nobody wants are freed until it fits. The order is lowest `priority` first (a number from -100 to 100, default 0, set on the asset), then by `evictionOrder`: `"recency"` (the default, unchanged from before) frees the least recently used first and breaks ties by distance; `"distance"` frees the farthest from the focus first and breaks ties by recency. Last comes the id, so the same walk always frees the same assets. Reading an asset with `getAsset(id)` or keeping it wanted counts as a use. If freeing every unwanted asset would still not make room, nothing is freed and the load waits; update tries again. When a loader reports more bytes than estimated, the system frees unwanted assets to get back under the budget. Wanted and requested assets are never freed, so a budget smaller than what the player needs shows as waiting loads in `stats`.## Detail levels@@ -48,7 +48,7 @@ A loader is `{ load(request), dispose(asset) }`. `load` returns `{ asset, bytes## Reading the state-`getState(id)` returns `{ state, level, bytes, failure }`, with `state` one of `idle`, `pending`, `loaded`, `evicted` or `failed`. A failed asset stays failed until `request(id)` retries it. `stats` has the count of each state plus `bytesInUse`, `budgetBytes`, `activeLoads` and `assets`. `events` is the last 256 events (`load-start`, `loaded`, `evict`, `failed`), each with the update count (`tick`), and `onEvent` receives them as they happen. `settled()` resolves when no load is in flight, for a loading screen.+`getState(id)` returns `{ state, level, bytes, failure }`, with `state` one of `idle`, `pending`, `loaded`, `evicted` or `failed`. A load that rejects, or resolves without an `asset`, fails the asset, and it stays failed until `request(id)` retries it. `stats` has the count of each state plus `bytesInUse`, `budgetBytes`, `activeLoads` and `assets`. `events` is the last 256 events (`load-start`, `loaded`, `evict`, `failed`), each with the update count (`tick`), and `onEvent` receives them as they happen. `settled()` resolves when no load is in flight, for a loading screen.## Limitsdiff --git a/src/streaming.js b/src/streaming.jsindex 242744fc..738186ce 100644--- a/src/streaming.js+++ b/src/streaming.js@@ -141,6 +141,10 @@ export function createWorkerLoader({ createWorker, dispose } = {}) {};}+function hasAsset(result) {+ return result !== null && typeof result === 'object' && result.asset != null;+}+function validateLoader(format, loader) {if (typeof format !== 'string' || !/^[a-z0-9][a-z0-9-]*$/.test(format)) {throw new TypeError(`A loader format must be a lowercase name like "glb" or "terrain-tile", got ${describe(format)} ${String(format)}.`);@@ -280,7 +284,11 @@ export function createStreaming(options = {}) {function makeRoom(neededBytes) {let used = bytesInUse();if (used + neededBytes <= budgetBytes) return true;- for (const candidate of evictable()) {+ const candidates = evictable();+ const reclaimable = candidates.reduce((total, candidate) => total + candidate.resident.bytes, 0);+ // Freeing everything would still not fit the load, so keep what is resident.+ if (neededBytes > 0 && used - reclaimable + neededBytes > budgetBytes) return false;+ for (const candidate of candidates) {used -= candidate.resident.bytes;evict(candidate, 'budget');if (used + neededBytes <= budgetBytes) return true;@@ -300,7 +308,10 @@ export function createStreaming(options = {}) {const request = { id: record.id, format: record.format, source: levelDefinition.source, level, signal: controller.signal };Promise.resolve().then(() => loader.load(request))- .then(result => finishLoad(record, level, pending, loader, result), error => failLoad(record, level, pending, error));+ .then(+ result => (hasAsset(result) ? finishLoad(record, level, pending, loader, result) : failLoad(record, level, pending, new TypeError(`Loader "${record.format}" must resolve { asset, bytes }, got ${describe(result)}.`))),+ error => failLoad(record, level, pending, error),+ );}function finishLoad(record, level, pending, loader, result) {diff --git a/src/tile-field.js b/src/tile-field.jsindex b2c1355b..a4c8891f 100644--- a/src/tile-field.js+++ b/src/tile-field.js@@ -22,6 +22,11 @@ export function tileMatrix(tile) {* A tile keeps `tile.cache` between rebuilds for whatever the caller wants to plan once.*/export function createTileField({ area, tileSize, levels, cullDistance, terrainHeight, buildParts }) {+ const extents = [area?.minX, area?.maxX, area?.minZ, area?.maxZ];+ if (!extents.every(Number.isFinite) || area.maxX <= area.minX || area.maxZ <= area.minZ) {+ throw new TypeError('area needs finite minX < maxX and minZ < maxZ; pass e.g. { minX: 0, maxX: 100, minZ: 0, maxZ: 100 }.');+ }+ if (!Number.isFinite(tileSize) || tileSize <= 0) throw new RangeError('tileSize must be a finite number > 0; pass e.g. 4.');const columns = Math.ceil((area.maxX - area.minX) / tileSize);const rows = Math.ceil((area.maxZ - area.minZ) / tileSize);if (!(columns * rows <= MAXIMUM_TILES)) {diff --git a/tests/streaming-hunt.test.js b/tests/streaming-hunt.test.jsnew file mode 100644index 00000000..27627202--- /dev/null+++ b/tests/streaming-hunt.test.js@@ -0,0 +1,76 @@+// Bug hunt over streaming and tile fields: a loader that answers nothing, a load that cannot fit, and an area that holds no tiles.+import assert from 'node:assert/strict';+import test from 'node:test';+import { createStreaming } from '../src/streaming.js';+import { createTileField } from '../src/tile-field.js';++function tileDefinition(id, x, overrides = {}) {+ return { id, format: 'tile', source: `${id}.bin`, position: [x, 0, 0], loadDistance: 15, estimatedBytes: 100, ...overrides };+}++function countingLoader(bytes = 100) {+ const disposed = [];+ return {+ disposed,+ async load({ id }) {+ return { asset: { id }, bytes };+ },+ dispose(asset) {+ disposed.push(asset.id);+ },+ };+}++test('a loader that resolves with nothing fails the asset instead of leaving it pending', async () => {+ const unhandled = [];+ const record = reason => unhandled.push(reason);+ process.on('unhandledRejection', record);+ try {+ const streaming = createStreaming({ budgetBytes: 1000, loaders: { tile: { load: async () => undefined } } });+ streaming.addAsset(tileDefinition('a', 0));+ streaming.setFocus([0, 0, 0]);+ streaming.update();+ await streaming.settled();+ await new Promise(resolve => setImmediate(resolve));+ assert.deepEqual(unhandled, []);+ assert.equal(streaming.getState('a').state, 'failed');+ assert.match(streaming.getState('a').failure, /asset/);+ assert.equal(streaming.stats.bytesInUse, 0);+ } finally {+ process.off('unhandledRejection', record);+ }+});++test('an asset too large for the budget leaves the resident assets in place', async () => {+ const loader = countingLoader();+ const streaming = createStreaming({ budgetBytes: 250, loaders: { tile: loader } });+ streaming.addAsset(tileDefinition('small', 0));+ streaming.addAsset(tileDefinition('huge', 100, { estimatedBytes: 400 }));+ streaming.setFocus([0, 0, 0]);+ streaming.update();+ await streaming.settled();+ assert.equal(streaming.getState('small').state, 'loaded');++ streaming.setFocus([100, 0, 0]);+ streaming.update();+ await streaming.settled();+ assert.deepEqual(loader.disposed, [], 'nothing was freed for a load that can never fit');+ assert.equal(streaming.getState('small').state, 'loaded');+ assert.equal(streaming.getState('huge').state, 'idle');+});++test('a tile field over an area with no tiles throws and says what to pass', () => {+ const options = { levels: [{ distance: 10 }], cullDistance: 10, terrainHeight: () => 0, buildParts: () => [] };+ const area = { minX: 0, maxX: 100, minZ: 0, maxZ: 100 };+ const rejected = [+ { area: { ...area, maxX: -100 }, tileSize: 10 },+ { area, tileSize: -10 },+ { area, tileSize: 0 },+ { area, tileSize: NaN },+ { area: { ...area, maxZ: 0 }, tileSize: 10 },+ ];+ for (const bad of rejected) {+ assert.throws(() => createTileField({ ...options, ...bad }), /tileSize|area/, JSON.stringify(bad));+ }+ assert.equal(createTileField({ ...options, area, tileSize: 10 }).stats().tiles, 100);+});