Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Streaming crossing: validate --speed, add a crossing deadline, check the tile under the player, size the budget from a measured peak (#776)

Nguyen Xuan An1dd3e0d72342
diff --git a/bench/streaming-crossing/harness.js b/bench/streaming-crossing/harness.js
index e68d58e0..c2e44f45 100644
--- a/bench/streaming-crossing/harness.js
+++ b/bench/streaming-crossing/harness.js
@@ -10,6 +10,7 @@ const MARKER_MATERIAL = { color: [0.95, 0.75, 0.2], metallic: 0, roughness: 0.5,
const IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
const WARMUP_FRAMES = 60;
const LONG_TASK_MILLISECONDS = 50;
+const CROSSING_DEADLINE_MARGIN_SECONDS = 120;
const SHEET_COLUMNS = 4;
const SHEET_ROWS = 2;
const SHEET_FRAME_WIDTH = 480;
@@ -174,7 +175,14 @@ async function runCrossing(options = {}) {
const startedAt = performance.now();
runtime.start();
- while (!player.state.finished) await new Promise(resolve => setTimeout(resolve, 100));
+ const deadlineSeconds = player.total / settings.playerSpeed + CROSSING_DEADLINE_MARGIN_SECONDS;
+ while (!player.state.finished) {
+ if ((performance.now() - startedAt) / 1000 > deadlineSeconds) {
+ runtime.stop();
+ throw new Error(`The crossing did not finish within ${deadlineSeconds.toFixed(0)} s (path ${player.total.toFixed(0)} units at ${settings.playerSpeed} units per second plus ${CROSSING_DEADLINE_MARGIN_SECONDS} s); it reached ${player.state.distance.toFixed(0)} units after ${frames} frames. Pass a higher --speed or check that frames are being drawn.`);
+ }
+ await new Promise(resolve => setTimeout(resolve, 100));
+ }
const crossingSeconds = (performance.now() - startedAt) / 1000;
runtime.stop();
observer.disconnect();
diff --git a/bench/streaming-crossing/run.mjs b/bench/streaming-crossing/run.mjs
index a9898200..65dad4ac 100644
--- a/bench/streaming-crossing/run.mjs
+++ b/bench/streaming-crossing/run.mjs
@@ -6,6 +6,7 @@ import { constants, setPriority } from 'node:os';
import { resolve } from 'node:path';
import { chromium } from 'playwright';
import { createServer } from 'vite';
+import { requirePlayerSpeed } from './world.js';
setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);
const CHROME = process.env.CHROME_PATH ?? 'C:/Program Files/Google/Chrome/Application/chrome.exe';
@@ -17,7 +18,9 @@ function flagValue(name, fallback) {
const useCpu = flags.includes('--cpu');
const outputFolder = resolve(flagValue('--out', 'artifacts/776'));
const label = flagValue('--label', useCpu ? 'swiftshader' : 'gpu');
-const speed = Number(flagValue('--speed', 30));
+const speedText = flagValue('--speed', '30');
+const speed = speedText === undefined || speedText.trim() === '' ? Number.NaN : Number(speedText);
+requirePlayerSpeed(speed, '--speed (units per second, for example 30)');
const withSheet = !flags.includes('--no-sheet');
const browserArguments = ['--enable-webgl', '--ignore-gpu-blocklist', '--disable-renderer-backgrounding', '--enable-precise-memory-info'];
diff --git a/bench/streaming-crossing/world.js b/bench/streaming-crossing/world.js
index 48858698..9e276a06 100644
--- a/bench/streaming-crossing/world.js
+++ b/bench/streaming-crossing/world.js
@@ -10,12 +10,19 @@ export const CROSSING_DEFAULTS = Object.freeze({
levelResolutions: Object.freeze([96, 48, 24]),
levelDistances: Object.freeze([30, 70]),
loadDistance: 120,
- budgetBytes: 16 * 1024 * 1024,
+ budgetBytes: 20 * 1024 * 1024,
playerSpeed: 30,
eyeHeight: 2,
});
-export const CROSSING_LIMITS = Object.freeze({ maximumTilesPerSide: 64, maximumResolution: 256 });
+export const CROSSING_LIMITS = Object.freeze({ maximumTilesPerSide: 64, maximumResolution: 256, maximumPlayerSpeed: 1000 });
+
+/** Checks a player speed in world units per second; the crossing never ends for zero, a negative number or NaN. */
+export function requirePlayerSpeed(speed, label) {
+ if (!Number.isFinite(speed) || speed <= 0 || speed > CROSSING_LIMITS.maximumPlayerSpeed) {
+ throw new RangeError(`${label} must be a number above 0 and at most ${CROSSING_LIMITS.maximumPlayerSpeed} world units per second, got ${String(speed)}.`);
+ }
+}
const heightFunctions = new Map();
@@ -123,6 +130,7 @@ export function createCrossingWorld(options = {}) {
requireInteger(settings.seed, 'createCrossingWorld seed', 0, 2 ** 31 - 1);
requireInteger(settings.tilesPerSide, 'createCrossingWorld tilesPerSide', 2, CROSSING_LIMITS.maximumTilesPerSide);
if (!Number.isFinite(settings.tileSize) || settings.tileSize <= 0) throw new RangeError('createCrossingWorld tileSize must be a positive number of world units.');
+ requirePlayerSpeed(settings.playerSpeed, 'createCrossingWorld playerSpeed');
for (const resolution of settings.levelResolutions) requireInteger(resolution, 'createCrossingWorld levelResolutions entry', 1, CROSSING_LIMITS.maximumResolution);
if (settings.levelDistances.length !== settings.levelResolutions.length - 1) {
throw new RangeError('createCrossingWorld levelDistances needs one distance fewer than levelResolutions: the last level has no end.');
diff --git a/docs/streaming.md b/docs/streaming.md
index c39c3b65..6a323399 100644
--- a/docs/streaming.md
+++ b/docs/streaming.md
@@ -56,8 +56,8 @@ At most 4096 assets, 8 levels per asset and 32 loaders. `budgetBytes` is at leas
## Crossing a large world
-`npm run benchmark:streaming` crosses a seeded world of 576 terrain tiles (480 by 480 units, three detail levels, tiles built in workers with `createWorkerLoader`) on a scripted path through the runtime, in headless Chrome. It records frame time, long tasks over 50 ms, `replaceParts` time and resident bytes for the whole crossing, and writes `crossing-<label>.json` and a contact sheet to `--out`. `--cpu` uses SwiftShader and `--speed` sets the player speed. The world and its generator are in `bench/streaming-crossing/world.js`. `tests/streaming-crossing.test.js` runs the same crossing in Node and asserts that bytes in use never pass the budget (the budget does force evictions), that no loader starts inside a frame and that the player's tile is always resident.
+`npm run benchmark:streaming` crosses a seeded world of 576 terrain tiles (480 by 480 units, three detail levels, tiles built in workers with `createWorkerLoader`) on a scripted path through the runtime, in headless Chrome. It records frame time, long tasks over 50 ms, `replaceParts` time and resident bytes for the whole crossing, and writes `crossing-<label>.json` and a contact sheet to `--out`. `--cpu` uses SwiftShader and `--speed` sets the player speed in world units per second (above 0, at most 1000; anything else stops with a message before a browser starts). The run fails with a message if the crossing takes more than the path length over the speed plus 120 s. The world and its generator are in `bench/streaming-crossing/world.js`. `tests/streaming-crossing.test.js` runs the same crossing in Node and asserts that bytes in use never pass the budget (the budget does force evictions), that no loader starts inside a frame and that on every frame after the loading screen the tile under the player (found by column and row, as the benchmark does) is resident.
-Pick a budget above what the focus wants at once: the tiles inside `loadDistance`, each at its level. A budget below that leaves loads waiting and the ground missing under the player; `stats.pending` and the events show it. The benchmark world wants about 11 MB at once and runs on a 16 MiB budget, 6 percent of the 257 MB the whole world takes at its finest level. A renderer that draws the resident tiles should call `replaceParts(parts, { retainedUnchanged: true })` when the resident set changes, so batches that did not change are not synced again.
+Pick a budget above what the focus wants at once: the tiles inside `loadDistance`, each at its level. A budget below that leaves loads waiting and the ground missing under the player; `stats.pending` and the events show it. Measured on the benchmark world with a budget too large to bind: the crossing holds at most 16,098,432 bytes (15.35 MiB) in use at once, counting in-flight reservations and both levels of a tile during a level switch. The default is 20 MiB, about 30 percent above that peak; three GPU crossings at 16 or 20 MiB peaked at 15.8 to 16.2 MB with 0 frames without ground. A budget that sits just above the peak leaves little room for load timing to shift which tiles are resident, so keep headroom. A renderer that draws the resident tiles should call `replaceParts(parts, { retainedUnchanged: true })` when the resident set changes, so batches that did not change are not synced again.
Not yet: culling for instanced groups, and a run on a mid laptop (#776).
diff --git a/tests/streaming-crossing.test.js b/tests/streaming-crossing.test.js
index 59ef4b9d..8cebe13e 100644
--- a/tests/streaming-crossing.test.js
+++ b/tests/streaming-crossing.test.js
@@ -1,8 +1,10 @@
import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
import test from 'node:test';
import { createRuntime } from '../src/runtime.js';
import { createStreaming } from '../src/streaming.js';
-import { createCrossingWorld, createPathPlayer, estimatedTileBytes, generateTile, parseTileSource, tileBytes } from '../bench/streaming-crossing/world.js';
+import { createCrossingWorld, createPathPlayer, estimatedTileBytes, generateTile, parseTileSource, requirePlayerSpeed, tileBytes, tileId } from '../bench/streaming-crossing/world.js';
const FRAME_SECONDS = 1 / 30;
@@ -63,6 +65,18 @@ test('bad world input says what to pass', () => {
assert.throws(() => createCrossingWorld({ seed: 1.5 }), /seed must be a whole number/);
assert.throws(() => generateTile({ seed: 1, column: 0, row: 0, tilesPerSide: 4, tileSize: 20, resolution: 0 }), /resolution must be a whole number/);
assert.throws(() => parseTileSource('mesh:1:2:3:4'), /Tile source must look like/);
+ for (const speed of [0, -5, Number.NaN, Number.POSITIVE_INFINITY, 5000, '30']) {
+ assert.throws(() => createCrossingWorld({ playerSpeed: speed }), /playerSpeed must be a number above 0/);
+ assert.throws(() => requirePlayerSpeed(speed, '--speed'), /--speed must be a number above 0 and at most 1000/);
+ }
+});
+
+test('the benchmark rejects a bad --speed before it starts a browser', () => {
+ for (const value of [['--speed'], ['--speed', 'fast'], ['--speed', '0'], ['--speed', '--cpu']]) {
+ const run = spawnSync(process.execPath, [fileURLToPath(new URL('../bench/streaming-crossing/run.mjs', import.meta.url)), ...value], { encoding: 'utf8', timeout: 60000 });
+ assert.notEqual(run.status, 0, `${value.join(' ')} was accepted`);
+ assert.match(run.stderr, /--speed .*must be a number above 0 and at most 1000/);
+ }
});
test('crossing the world through the runtime stays under the byte budget and never loads inside a frame', async () => {
@@ -80,10 +94,19 @@ test('crossing the world through the runtime stays under the byte budget and nev
scheduler: { request: () => 1, cancel() {} },
clock: () => 0,
});
+ // Like the benchmark's loading screen: play starts after the tiles around the start are in, so every frame is checked.
+ for (let round = 0; round < 200; round += 1) {
+ const eventsBefore = streaming.events.length;
+ streaming.update();
+ await streaming.settled();
+ if (streaming.stats.activeLoads === 0 && streaming.events.length === eventsBefore) break;
+ }
runtime.start();
+ const half = world.settings.tilesPerSide / 2;
+ const tileIndexUnder = coordinate => Math.min(world.settings.tilesPerSide - 1, Math.max(0, Math.floor(coordinate / world.settings.tileSize + half)));
let peakBytes = 0;
- let framesWithoutNearbyGround = 0;
+ let framesWithoutGround = 0;
let frames = 0;
while (!player.state.finished) {
frameState.insideFrame = true;
@@ -93,10 +116,8 @@ test('crossing the world through the runtime stays under the byte budget and nev
peakBytes = Math.max(peakBytes, streaming.stats.bytesInUse);
assert.ok(streaming.stats.bytesInUse <= budgetBytes, `frame ${frames}: ${streaming.stats.bytesInUse} bytes in use exceeds the budget of ${budgetBytes}`);
await new Promise(resolve => setImmediate(resolve));
- if (frames > 30) {
- const nearby = world.assets.filter(asset => Math.hypot(asset.position[0] - player.state.position[0], asset.position[2] - player.state.position[2]) < world.settings.tileSize);
- if (!nearby.some(asset => streaming.getAsset(asset.id) !== null)) framesWithoutNearbyGround += 1;
- }
+ const tileUnderPlayer = tileId(tileIndexUnder(player.state.position[0]), tileIndexUnder(player.state.position[2]));
+ if (streaming.getAsset(tileUnderPlayer) === null) framesWithoutGround += 1;
}
await streaming.settled();
@@ -106,7 +127,7 @@ test('crossing the world through the runtime stays under the byte budget and nev
assert.equal(loader.disposed, (evictionReasons.budget ?? 0) + (evictionReasons['level-switch'] ?? 0));
assert.ok(peakBytes <= budgetBytes);
assert.ok(peakBytes > budgetBytes * 0.3, `peak ${peakBytes} bytes says the budget was never close`);
- assert.equal(framesWithoutNearbyGround, 0, 'the player stood on ground that had not streamed in');
+ assert.equal(framesWithoutGround, 0, 'the tile under the player had not streamed in');
assert.equal(streaming.stats.failed, 0);
runtime.dispose();
});