Skip to content

3D engine that AI agents drive

Guard streaming loads and tile field inputs (#2490)

Nguyen Xuan An618440970691
diff --git a/changes/2490.md b/changes/2490.md
new file mode 100644
index 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.md
index 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.
## Limits
diff --git a/src/streaming.js b/src/streaming.js
index 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.js
index 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.js
new file mode 100644
index 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);
+});