3D engine that AI agents drive
Add the streaming addon: loader plugins, distance loading, byte budget with LRU eviction and LOD hysteresis (part of #776)
Nguyen Xuan An06cefab04fe3
diff --git a/README.md b/README.mdindex e29c7598..a6c49b51 100644--- a/README.md+++ b/README.md@@ -139,6 +139,7 @@ Each addon is a separate import, so a page loads only what it uses.| Vehicles | `67js/addons/vehicle` | [Wheeled vehicles on a path](https://67js.codepawl.com/vehicle.md) || Physics | `67js/addons/physics` | [Rapier contacts and joints](docs/physics.md) recorded into a timeline || Live games | `67js/addons/runtime` | [Game loop](docs/runtime.md) with fixed or variable steps and pluggable systems |+| Live games | `67js/addons/streaming` | [Streaming](docs/streaming.md): loader plugins, distance and request loading, a byte budget with LRU eviction and LOD with hysteresis || Live games | `67js/addons/input` | [Input](docs/input.md): keyboard, mouse, gamepad and custom sources mapped to named actions and axes || Live games | `67js/addons/animation-graph` | [Animation graph](docs/animation-graph.md): states, 1D and 2D blend spaces, parameter transitions with crossfades and masked layers for any rig || Live games | `67js/addons/player` | [Player](docs/player.md): character controller, follow, first-person and top-down camera rigs, swappable at runtime |diff --git a/changes/776.md b/changes/776.mdnew file mode 100644index 00000000..a5528e2f--- /dev/null+++ b/changes/776.md@@ -0,0 +1 @@+- `67js/addons/streaming` adds `createStreaming`, a runtime system that loads assets on demand by distance from a focus point or by game request, with a loader plugin registry (GLB first), a byte budget with least-recently-used eviction, level of detail switching with hysteresis and a loading state game code can read (part of #776)diff --git a/docs/streaming.md b/docs/streaming.mdnew file mode 100644index 00000000..c8a187c5--- /dev/null+++ b/docs/streaming.md@@ -0,0 +1,57 @@+# Streaming: load and free assets while a game plays++`67js/addons/streaming` is a [runtime](runtime.md) system. It loads assets when the player gets near or the game asks, keeps the bytes in use under a budget, frees the least recently used far assets and swaps detail levels. It loads only when imported and adds no dependency. The GLB loader imports the glTF parser on first use.++```js+import { createRuntime } from '67js/addons/runtime';+import { createStreaming } from '67js/addons/streaming';++const streaming = createStreaming({+ budgetBytes: 256 * 1024 * 1024,+ focus: () => player.position,+ assets: [+ { id: 'town', format: 'glb', position: [0, 0, 0], loadDistance: 150,+ levels: [{ source: '/town-high.glb', estimatedBytes: 12e6, maximumDistance: 60 },+ { source: '/town-low.glb', estimatedBytes: 2e6 }] },+ ],+});+const runtime = createRuntime(renderer, { systems: [input, physics, streaming] });+```++## What decides a load++- **Distance.** An asset is wanted once the focus is within `loadDistance` of its `position`, and stays wanted until the focus is `loadDistance * (1 + hysteresis)` away.+- **Request.** `request(id)` wants an asset wherever the focus is, and `release(id)` lets it go. A requested asset is never evicted.+- Loads start in order of distance, nearest first, then by id. At most `maximumConcurrentLoads` (default 2, up to 16) run at once. The order is a function of the focus path only, so a scripted walk streams the same way every run.++## Memory budget++`budgetBytes` caps loaded bytes plus the `estimatedBytes` of loads in flight. Before a load starts, assets nobody wants are freed, least recently used first, until it fits. 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`.++## Detail levels++`levels` runs from the finest to the coarsest. Each level except the last has a `maximumDistance`. A level coarsens once the distance passes its end by `hysteresis` (default 0.1, a fraction) and refines once the distance is short of the finer level's end by the same fraction, so a focus standing on a boundary does not reload back and forth. When the wanted level is loaded, the other levels of that asset are freed. Until then `getAsset` returns the level still resident, so nothing disappears. `selectDetailLevel(maximumDistances, distance, currentLevel, hysteresis)` is the same rule as a function.++## Loader plugins++```js+streaming.registerLoader('terrain-tile', {+ async load({ id, source, level, signal }) {+ const bytes = await (await fetch(source, { signal })).arrayBuffer();+ return { asset: decodeTile(bytes), bytes: bytes.byteLength };+ },+ dispose(asset) { asset.free(); },+});+```++A loader is `{ load(request), dispose(asset) }`. `load` returns `{ asset, bytes }` and gets an `AbortSignal` that fires when the system is disposed. The format name is lowercase letters, digits and hyphens, and each can be registered once (`createStreaming({ loaders: { 'terrain-tile': loader } })` does the same). `glb` is registered by default through `createGlbLoader({ options, fetchBytes })`; `options` go to `parseGltf`, so its limits and decoders apply. Splats, point clouds, audio and compressed textures are loaders of their own.++## 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.++## Limits++At most 4096 assets, 8 levels per asset and 32 loaders. `budgetBytes` is at least 1. Bad input throws an error that says what to pass instead.++Not in this slice: loading in a worker, culling for instanced groups and a measured frame budget on a laptop (#776).diff --git a/package.json b/package.jsonindex 2767290b..bd24b210 100644--- a/package.json+++ b/package.json@@ -42,6 +42,7 @@"docs/modeling.md","docs/physics.md","docs/runtime.md",+ "docs/streaming.md","docs/input.md","docs/animation-graph.md","docs/player.md",@@ -121,6 +122,7 @@"./addons/texture-update": "./build/texture-update.js","./addons/cloth": "./build/cloth.js","./addons/runtime": "./build/runtime.js",+ "./addons/streaming": "./build/streaming.js","./addons/input": "./build/input.js","./addons/animation-graph": "./build/animation-graph.js","./addons/player": "./build/player.js",diff --git a/scripts/prepare-release.mjs b/scripts/prepare-release.mjsindex 6256aa22..2328c902 100644--- a/scripts/prepare-release.mjs+++ b/scripts/prepare-release.mjs@@ -53,7 +53,7 @@ const sourceDocuments = ['vehicle.md','vegetation.md', 'terrain.md', 'grass.md', 'clutter.md', 'light-bake.md', 'path-tracer.md', 'gaussian-splats.md','camera-path.md', 'lighting.md', 'volumetric.md', 'film-physics.md',- 'runtime.md', 'input.md', 'player.md', 'animation-graph.md', 'surface-attachment.md', 'agent-scene.md', 'mcp.md', 'agent-look.md', 'agent-asset.md', 'agent-render-jobs.md', 'agent-motion.md', 'agent-character-motion.md', 'agent-review.md',+ 'runtime.md', 'streaming.md', 'input.md', 'player.md', 'animation-graph.md', 'surface-attachment.md', 'agent-scene.md', 'mcp.md', 'agent-look.md', 'agent-asset.md', 'agent-render-jobs.md', 'agent-motion.md', 'agent-character-motion.md', 'agent-review.md',];for (const name of sourceDocuments) {await copyFile(resolve(root, 'docs', name), resolve(root, 'public', name));diff --git a/src/streaming.js b/src/streaming.jsnew file mode 100644index 00000000..53f6d93c--- /dev/null+++ b/src/streaming.js@@ -0,0 +1,379 @@+// Live asset streaming: a runtime system that loads, swaps and frees assets while a game plays.+// Assets are requested by distance from a focus point or by an explicit game request, held under a byte budget with+// least-recently-used eviction, and switched between detail levels with hysteresis. Formats load through plugins, so GLB+// is only the first loader. Everything is decided inside update() from the focus, a counter and sorted ids, never from+// wall time, so the same walk streams in the same order. Loaders are async; update() only starts them. See docs/streaming.md.++export const STREAMING_LIMITS = Object.freeze({+ maximumAssets: 4096,+ maximumLevels: 8,+ maximumLoaders: 32,+ maximumConcurrentLoads: 16,+ defaultConcurrentLoads: 2,+ maximumBudgetBytes: 2 ** 40,+ defaultHysteresis: 0.1,+ maximumHysteresis: 1,+ eventHistory: 256,+});++export const STREAMING_STATES = Object.freeze(['idle', 'pending', 'loaded', 'evicted', 'failed']);++function describe(value) {+ return value === null ? 'null' : typeof value;+}++function compareText(first, second) {+ if (first === second) return 0;+ return first < second ? -1 : 1;+}++function boundedNumber(value, label, minimum, maximum) {+ if (!Number.isFinite(value) || value < minimum || value > maximum) {+ throw new RangeError(`${label} must be a number from ${minimum} to ${maximum}, got ${String(value)}.`);+ }+ return value;+}++function validatePoint(point, label) {+ if (!Array.isArray(point) && !ArrayBuffer.isView(point)) {+ throw new TypeError(`${label} must be a point like [x, y, z], got ${describe(point)}.`);+ }+ if (point.length !== 3 || !Array.prototype.every.call(point, Number.isFinite)) {+ throw new RangeError(`${label} must be three finite numbers [x, y, z].`);+ }+ return [point[0], point[1], point[2]];+}++/**+ * Pick a detail level for a distance, with hysteresis. `maximumDistances[i]` is where level i ends; the last level has no end.+ * A level only coarsens once the distance passes its end by `hysteresis` (a fraction), and only refines once the distance falls+ * short of the finer level's end by the same fraction, so a focus standing on a boundary never flaps.+ */+export function selectDetailLevel(maximumDistances, distance, currentLevel = 0, hysteresis = STREAMING_LIMITS.defaultHysteresis) {+ let level = Math.min(Math.max(currentLevel, 0), maximumDistances.length);+ while (level < maximumDistances.length && distance > maximumDistances[level] * (1 + hysteresis)) level += 1;+ while (level > 0 && distance < maximumDistances[level - 1] * (1 - hysteresis)) level -= 1;+ return level;+}++/** The GLB loader. It imports the glTF parser on first use, so a game that streams nothing pays nothing. Pass `options` for parseGltf limits and decoders, or `fetchBytes(source, signal)` to read bytes elsewhere. */+export function createGlbLoader({ options = {}, fetchBytes } = {}) {+ return {+ async load({ source, signal }) {+ const { parseGltf } = await import('./gltf.js');+ const bytes = fetchBytes ? await fetchBytes(source, signal) : await fetchArrayBuffer(source, signal);+ const asset = await parseGltf(bytes, { baseUrl: baseUrlOf(source), ...options });+ return { asset, bytes: bytes.byteLength };+ },+ dispose(asset) {+ asset.dispose();+ },+ };+}++async function fetchArrayBuffer(source, signal) {+ const response = await fetch(source, { signal });+ if (!response.ok) throw new Error(`Fetching ${source} failed with status ${response.status}.`);+ return response.arrayBuffer();+}++function baseUrlOf(source) {+ return /^https?:/.test(source) ? new URL('.', source).href : '';+}++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)}.`);+ }+ if (loader === null || typeof loader !== 'object' || typeof loader.load !== 'function') {+ throw new TypeError(`Loader "${format}" must be an object { load(request) => Promise<{ asset, bytes }>, dispose(asset) }, got ${describe(loader)}.`);+ }+ if (loader.dispose !== undefined && typeof loader.dispose !== 'function') {+ throw new TypeError(`Loader "${format}" dispose must be a function or left out.`);+ }+}++function validateDefinition(definition, loaders, hysteresis) {+ if (definition === null || typeof definition !== 'object') {+ throw new TypeError(`A streamed asset must be an object { id, format, source, position, loadDistance, estimatedBytes }, got ${describe(definition)}.`);+ }+ const { id, format } = definition;+ if (typeof id !== 'string' || id === '') throw new TypeError('A streamed asset needs a unique id string.');+ if (!loaders.has(format)) {+ const known = [...loaders.keys()].sort().join(', ') || 'none';+ throw new RangeError(`Streamed asset "${id}" uses format "${String(format)}" with no loader. Register one with registerLoader first; registered: ${known}.`);+ }+ const position = validatePoint(definition.position ?? [0, 0, 0], `Streamed asset "${id}" position`);+ const loadDistance = definition.loadDistance === undefined ? Infinity : boundedNumber(definition.loadDistance, `Streamed asset "${id}" loadDistance`, 0, Infinity);+ const levelInputs = definition.levels ?? [{ source: definition.source, estimatedBytes: definition.estimatedBytes }];+ if (!Array.isArray(levelInputs) || levelInputs.length < 1 || levelInputs.length > STREAMING_LIMITS.maximumLevels) {+ throw new RangeError(`Streamed asset "${id}" levels must be an array of 1 to ${STREAMING_LIMITS.maximumLevels} { source, estimatedBytes, maximumDistance }.`);+ }+ const levels = levelInputs.map((level, index) => {+ if (typeof level?.source !== 'string' || level.source === '') {+ throw new TypeError(`Streamed asset "${id}" level ${index} needs a source string (a URL).`);+ }+ const estimatedBytes = boundedNumber(level.estimatedBytes, `Streamed asset "${id}" level ${index} estimatedBytes`, 1, STREAMING_LIMITS.maximumBudgetBytes);+ const isLast = index === levelInputs.length - 1;+ const maximumDistance = isLast ? Infinity : boundedNumber(level.maximumDistance, `Streamed asset "${id}" level ${index} maximumDistance`, 0, Infinity);+ return { source: level.source, estimatedBytes: Math.ceil(estimatedBytes), maximumDistance };+ });+ for (let index = 1; index < levels.length - 1; index += 1) {+ if (levels[index].maximumDistance <= levels[index - 1].maximumDistance) {+ throw new RangeError(`Streamed asset "${id}" level maximumDistance values must increase from the finest level to the coarsest.`);+ }+ }+ return { id, format, position, loadDistance, unloadDistance: loadDistance * (1 + hysteresis), levels };+}++export function createStreaming(options = {}) {+ if (options === null || typeof options !== 'object') throw new TypeError('createStreaming options must be an object or left out.');+ const budgetBytes = Math.floor(boundedNumber(options.budgetBytes, 'createStreaming budgetBytes', 1, STREAMING_LIMITS.maximumBudgetBytes));+ const hysteresis = boundedNumber(options.hysteresis ?? STREAMING_LIMITS.defaultHysteresis, 'createStreaming hysteresis', 0, STREAMING_LIMITS.maximumHysteresis);+ const maximumConcurrentLoads = boundedNumber(options.maximumConcurrentLoads ?? STREAMING_LIMITS.defaultConcurrentLoads, 'createStreaming maximumConcurrentLoads', 1, STREAMING_LIMITS.maximumConcurrentLoads);+ if (options.focus !== undefined && typeof options.focus !== 'function') {+ throw new TypeError('createStreaming focus must be a function () => [x, y, z], or left out and set with setFocus.');+ }+ if (options.onEvent !== undefined && typeof options.onEvent !== 'function') {+ throw new TypeError('createStreaming onEvent must be a function (event) or left out.');+ }++ const loaders = new Map();+ const records = new Map();+ const events = [];+ let focusPoint = [0, 0, 0];+ let tick = 0;+ let activeLoads = 0;+ let disposed = false;++ function emit(type, id, level, extra = {}) {+ const event = { type, id, level, tick, ...extra };+ events.push(event);+ if (events.length > STREAMING_LIMITS.eventHistory) events.shift();+ options.onEvent?.(event);+ }++ function registerLoader(format, loader) {+ validateLoader(format, loader);+ if (loaders.has(format)) throw new RangeError(`A loader for "${format}" is already registered. Use another format name.`);+ if (loaders.size >= STREAMING_LIMITS.maximumLoaders) throw new RangeError(`At most ${STREAMING_LIMITS.maximumLoaders} loaders can be registered.`);+ loaders.set(format, loader);+ }++ function addAsset(definition) {+ if (disposed) throw new Error('The streaming system was disposed.');+ const asset = validateDefinition(definition, loaders, hysteresis);+ if (records.has(asset.id)) throw new RangeError(`A streamed asset named "${asset.id}" already exists. Pass another id.`);+ if (records.size >= STREAMING_LIMITS.maximumAssets) throw new RangeError(`At most ${STREAMING_LIMITS.maximumAssets} streamed assets can be defined.`);+ records.set(asset.id, { ...asset, wanted: false, requested: false, level: 0, resident: new Map(), pendingLevels: new Map(), lastUsed: 0, state: 'idle', failure: null });+ }++ const recordFor = id => {+ const record = records.get(id);+ if (!record) throw new RangeError(`No streamed asset named "${String(id)}". Add it with addAsset first.`);+ return record;+ };++ function bytesInUse() {+ let total = 0;+ for (const record of records.values()) {+ for (const resident of record.resident.values()) total += resident.bytes;+ for (const pending of record.pendingLevels.values()) total += pending.reservedBytes;+ }+ return total;+ }++ function evictable() {+ const candidates = [];+ for (const record of records.values()) {+ if (record.wanted || record.requested) continue;+ for (const [level, resident] of record.resident) candidates.push({ record, level, resident });+ }+ return candidates.sort((first, second) => first.record.lastUsed - second.record.lastUsed || compareText(first.record.id, second.record.id) || first.level - second.level);+ }++ function evict({ record, level, resident }, reason) {+ loaders.get(record.format).dispose?.(resident.asset);+ record.resident.delete(level);+ if (record.resident.size === 0 && record.pendingLevels.size === 0) record.state = 'evicted';+ emit('evict', record.id, level, { reason, bytes: resident.bytes });+ }++ /** Free least recently used assets nobody wants until `neededBytes` fit. Returns whether they fit. */+ function makeRoom(neededBytes) {+ let used = bytesInUse();+ if (used + neededBytes <= budgetBytes) return true;+ for (const candidate of evictable()) {+ used -= candidate.resident.bytes;+ evict(candidate, 'budget');+ if (used + neededBytes <= budgetBytes) return true;+ }+ return false;+ }++ function startLoad(record, level) {+ const loader = loaders.get(record.format);+ const levelDefinition = record.levels[level];+ const controller = new AbortController();+ const pending = { reservedBytes: levelDefinition.estimatedBytes, controller };+ record.pendingLevels.set(level, pending);+ record.state = 'pending';+ activeLoads += 1;+ emit('load-start', record.id, level);+ 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));+ }++ function finishLoad(record, level, pending, loader, result) {+ activeLoads -= 1;+ record.pendingLevels.delete(level);+ const bytes = Number.isFinite(result?.bytes) && result.bytes >= 0 ? Math.ceil(result.bytes) : pending.reservedBytes;+ if (disposed || pending.controller.signal.aborted) {+ loader.dispose?.(result?.asset);+ return;+ }+ record.resident.set(level, { asset: result.asset, bytes });+ record.state = 'loaded';+ record.lastUsed = tick;+ emit('loaded', record.id, level, { bytes });+ if (bytesInUse() > budgetBytes) makeRoom(0);+ retireOtherLevels(record);+ }++ function failLoad(record, level, pending, error) {+ activeLoads -= 1;+ record.pendingLevels.delete(level);+ if (disposed || pending.controller.signal.aborted) return;+ record.state = record.resident.size > 0 ? 'loaded' : 'failed';+ record.failure = error instanceof Error ? error.message : String(error);+ record.requested = false;+ record.wanted = false;+ emit('failed', record.id, level, { message: record.failure });+ }++ /** Once the level the focus needs is resident, the other levels of that asset are no longer shown, so they go. */+ function retireOtherLevels(record) {+ if (!record.resident.has(record.level)) return;+ for (const [level, resident] of [...record.resident]) {+ if (level !== record.level) evict({ record, level, resident }, 'level-switch');+ }+ }++ function distanceTo(record) {+ return Math.hypot(record.position[0] - focusPoint[0], record.position[1] - focusPoint[1], record.position[2] - focusPoint[2]);+ }++ function updateWanted(record, distance) {+ if (record.wanted) {+ if (distance > record.unloadDistance) record.wanted = false;+ } else if (distance <= record.loadDistance) {+ record.wanted = true;+ }+ }++ function update() {+ if (disposed) return;+ tick += 1;+ if (options.focus) focusPoint = validatePoint(options.focus(), 'createStreaming focus()');+ const wantedLoads = [];+ for (const record of records.values()) {+ if (record.state === 'failed') continue;+ const distance = distanceTo(record);+ updateWanted(record, distance);+ if (!record.wanted && !record.requested) continue;+ record.level = selectDetailLevel(record.levels.slice(0, -1).map(level => level.maximumDistance), distance, record.level, hysteresis);+ record.lastUsed = tick;+ if (!record.resident.has(record.level) && !record.pendingLevels.has(record.level)) wantedLoads.push({ record, distance });+ else retireOtherLevels(record);+ }+ wantedLoads.sort((first, second) => first.distance - second.distance || compareText(first.record.id, second.record.id));+ for (const { record } of wantedLoads) {+ if (activeLoads >= maximumConcurrentLoads) break;+ const needed = record.levels[record.level].estimatedBytes;+ if (makeRoom(needed)) startLoad(record, record.level);+ }+ }++ function request(id) {+ const record = recordFor(id);+ if (record.state === 'failed') {+ record.state = record.resident.size > 0 ? 'loaded' : 'idle';+ record.failure = null;+ }+ record.requested = true;+ }++ function release(id) {+ recordFor(id).requested = false;+ }++ function setFocus(point) {+ focusPoint = validatePoint(point, 'setFocus point');+ }++ function getState(id) {+ const record = recordFor(id);+ const resident = record.resident.get(record.level) ?? [...record.resident.values()][0];+ return { state: record.state, level: record.level, bytes: resident?.bytes ?? 0, failure: record.failure };+ }++ /** The loaded asset to draw: the wanted level when it is loaded, else any level still resident, else null. Reading it counts as a use. */+ function getAsset(id) {+ const record = recordFor(id);+ const entry = record.resident.get(record.level) ?? [...record.resident.entries()].sort(([first], [second]) => first - second)[0]?.[1];+ if (!entry) return null;+ record.lastUsed = tick;+ return entry.asset;+ }++ /** Resolves once no load is in flight and update() would start none more; for tests and loading screens. */+ async function settled() {+ for (let round = 0; round < STREAMING_LIMITS.maximumAssets * STREAMING_LIMITS.maximumLevels; round += 1) {+ await new Promise(resolve => setTimeout(resolve, 0));+ if (activeLoads === 0) return;+ }+ throw new Error('Streaming did not settle; a loader never resolved.');+ }++ function dispose() {+ if (disposed) return;+ disposed = true;+ for (const record of records.values()) {+ for (const pending of record.pendingLevels.values()) pending.controller.abort();+ for (const [level, resident] of [...record.resident]) {+ loaders.get(record.format).dispose?.(resident.asset);+ record.resident.delete(level);+ }+ record.state = 'evicted';+ }+ }++ const stats = () => {+ const counts = Object.fromEntries(STREAMING_STATES.map(state => [state, 0]));+ for (const record of records.values()) counts[record.state] += 1;+ return { ...counts, bytesInUse: bytesInUse(), budgetBytes, activeLoads, assets: records.size };+ };++ for (const [format, loader] of Object.entries(options.loaders ?? {})) registerLoader(format, loader);+ if (!loaders.has('glb')) registerLoader('glb', createGlbLoader());+ for (const definition of options.assets ?? []) addAsset(definition);++ return {+ name: options.name ?? 'streaming',+ update,+ dispose,+ registerLoader,+ addAsset,+ request,+ release,+ setFocus,+ getState,+ getAsset,+ settled,+ get stats() { return stats(); },+ get events() { return events.slice(); },+ get loaders() { return [...loaders.keys()].sort(); },+ };+}diff --git a/tests/streaming.test.js b/tests/streaming.test.jsnew file mode 100644index 00000000..d33494da--- /dev/null+++ b/tests/streaming.test.js@@ -0,0 +1,182 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { createRuntime } from '../src/runtime.js';+import { createGlbLoader, createStreaming, selectDetailLevel } from '../src/streaming.js';++function fakeLoader() {+ const log = [];+ const disposed = [];+ return {+ log,+ disposed,+ async load({ id, level, source }) {+ log.push(`${id}#${level}`);+ return { asset: { id, level, source }, bytes: 100 };+ },+ dispose(asset) {+ disposed.push(`${asset.id}#${asset.level}`);+ },+ };+}++function tileDefinition(id, x, overrides = {}) {+ return { id, format: 'tile', source: `${id}.bin`, position: [x, 0, 0], loadDistance: 15, estimatedBytes: 100, ...overrides };+}++async function walkTo(streaming, point) {+ streaming.setFocus(point);+ streaming.update();+ await streaming.settled();+}++test('evicts the least recently used far asset to stay under the byte budget', async () => {+ const loader = fakeLoader();+ const streaming = createStreaming({ budgetBytes: 250, loaders: { tile: loader } });+ for (const [id, x] of [['a', 0], ['b', 100], ['c', 200]]) streaming.addAsset(tileDefinition(id, x));++ await walkTo(streaming, [0, 0, 0]);+ await walkTo(streaming, [100, 0, 0]);+ assert.equal(streaming.stats.bytesInUse, 200);+ await walkTo(streaming, [200, 0, 0]);++ assert.deepEqual(loader.disposed, ['a#0']);+ assert.equal(streaming.getState('a').state, 'evicted');+ assert.equal(streaming.getState('b').state, 'loaded');+ assert.equal(streaming.getState('c').state, 'loaded');+ assert.ok(streaming.stats.bytesInUse <= 250);+ assert.equal(streaming.getAsset('a'), null);+});++test('never evicts an asset the focus still wants', async () => {+ const streaming = createStreaming({ budgetBytes: 150, loaders: { tile: fakeLoader() } });+ streaming.addAsset(tileDefinition('near', 0));+ streaming.addAsset(tileDefinition('also-near', 5));+ await walkTo(streaming, [2, 0, 0]);+ assert.equal(streaming.getState('near').state, 'loaded');+ assert.equal(streaming.getState('also-near').state, 'idle');+ assert.equal(streaming.stats.bytesInUse, 100);+});++test('a pinned request survives budget pressure until it is released', async () => {+ const streaming = createStreaming({ budgetBytes: 100, loaders: { tile: fakeLoader() } });+ streaming.addAsset(tileDefinition('boss', 500, { loadDistance: 1 }));+ streaming.addAsset(tileDefinition('door', 0));+ streaming.request('boss');+ await walkTo(streaming, [500, 0, 0]);+ await walkTo(streaming, [0, 0, 0]);+ assert.equal(streaming.getState('boss').state, 'loaded');+ assert.equal(streaming.getState('door').state, 'idle');+ streaming.release('boss');+ await walkTo(streaming, [0, 0, 0]);+ assert.equal(streaming.getState('boss').state, 'evicted');+ assert.equal(streaming.getState('door').state, 'loaded');+});++test('hysteresis keeps a level while the distance wobbles around a boundary', () => {+ const ends = [50];+ let level = 0;+ const seen = [];+ for (const distance of [48, 51, 49, 52, 54, 50.5, 47, 46, 44.9, 51, 56]) {+ level = selectDetailLevel(ends, distance, level, 0.1);+ seen.push(level);+ }+ assert.deepEqual(seen, [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]);+ assert.equal(selectDetailLevel(ends, 46, 1, 0.1), 1);+ assert.equal(selectDetailLevel(ends, 44, 1, 0.1), 0);+ assert.equal(selectDetailLevel([10, 20, 30], 100, 0, 0), 3);+});++test('a streamed asset switches level once and does not reload while it wobbles at the boundary', async () => {+ const loader = fakeLoader();+ const streaming = createStreaming({ budgetBytes: 1000, loaders: { tile: loader } });+ streaming.addAsset({+ id: 'tree', format: 'tile', position: [0, 0, 0], loadDistance: 200,+ levels: [{ source: 'tree-high', estimatedBytes: 100, maximumDistance: 50 }, { source: 'tree-low', estimatedBytes: 20 }],+ });+ for (const distance of [40, 51, 49, 52, 55, 48, 45]) await walkTo(streaming, [distance, 0, 0]);+ assert.deepEqual(loader.log, ['tree#0']);+ for (const distance of [56, 49, 54]) await walkTo(streaming, [distance, 0, 0]);+ assert.deepEqual(loader.log, ['tree#0', 'tree#1']);+ assert.deepEqual(loader.disposed, ['tree#0']);+ assert.equal(streaming.getState('tree').level, 1);+ assert.equal(streaming.getAsset('tree').level, 1);+});++test('loader plugins register by format and reject bad input with a fix', () => {+ const streaming = createStreaming({ budgetBytes: 1000 });+ assert.deepEqual(streaming.loaders, ['glb']);+ streaming.registerLoader('splat-cloud', fakeLoader());+ assert.deepEqual(streaming.loaders, ['glb', 'splat-cloud']);+ assert.throws(() => streaming.registerLoader('glb', fakeLoader()), /already registered/);+ assert.throws(() => streaming.registerLoader('Bad Name', fakeLoader()), /lowercase name/);+ assert.throws(() => streaming.registerLoader('x', { load: 1 }), /must be an object/);+ assert.throws(() => streaming.registerLoader('y', { load() {}, dispose: 3 }), /dispose must be a function/);+ assert.throws(() => streaming.addAsset({ id: 'a', format: 'ktx', source: 'a', estimatedBytes: 1 }), /no loader.*registered: glb, splat-cloud/);+ assert.throws(() => createStreaming({}), /budgetBytes/);+ assert.throws(() => createStreaming({ budgetBytes: 10, maximumConcurrentLoads: 99 }), /maximumConcurrentLoads/);+ streaming.addAsset({ id: 'a', format: 'glb', source: 'a.glb', estimatedBytes: 10 });+ assert.throws(() => streaming.addAsset({ id: 'a', format: 'glb', source: 'a.glb', estimatedBytes: 10 }), /already exists/);+ assert.throws(() => streaming.addAsset({ id: 'b', format: 'glb', source: 'b.glb' }), /estimatedBytes/);+ assert.throws(() => streaming.addAsset({ id: 'b', format: 'glb', source: 'b.glb', estimatedBytes: 1, position: [0, 0] }), /three finite numbers/);+ assert.throws(() => streaming.request('missing'), /No streamed asset named "missing"/);+ assert.throws(() => streaming.setFocus('here'), /\[x, y, z\]/);+});++test('the GLB loader passes its bytes to the glTF parser', async () => {+ const loader = createGlbLoader({ fetchBytes: async () => new ArrayBuffer(64) });+ await assert.rejects(loader.load({ source: 'x.glb' }), /glTF|GLB|JSON|binary|header/i);+ assert.equal(typeof loader.dispose, 'function');+});++test('a failed load is reported in the state and can be requested again', async () => {+ let attempts = 0;+ const loader = {+ async load() {+ attempts += 1;+ if (attempts === 1) throw new Error('404 for broken.bin');+ return { asset: {}, bytes: 10 };+ },+ };+ const streaming = createStreaming({ budgetBytes: 100, loaders: { tile: loader } });+ streaming.addAsset(tileDefinition('broken', 0));+ await walkTo(streaming, [0, 0, 0]);+ assert.equal(streaming.getState('broken').state, 'failed');+ assert.match(streaming.getState('broken').failure, /404/);+ streaming.request('broken');+ await walkTo(streaming, [0, 0, 0]);+ assert.equal(streaming.getState('broken').state, 'loaded');+});++test('a scripted walk across a grid of tiles streams in the same order every run', async () => {+ async function run() {+ const loader = fakeLoader();+ const streaming = createStreaming({ budgetBytes: 450, loaders: { tile: loader }, maximumConcurrentLoads: 3 });+ for (let row = 0; row < 4; row += 1) {+ for (let column = 0; column < 4; column += 1) {+ streaming.addAsset(tileDefinition(`tile-${row}-${column}`, 0, { position: [column * 100, 0, row * 100], loadDistance: 120 }));+ }+ }+ for (let step = 0; step <= 6; step += 1) await walkTo(streaming, [step * 50, 0, step * 40]);+ assert.ok(streaming.stats.bytesInUse <= 450);+ return { order: loader.log, evicted: loader.disposed, events: streaming.events.map(event => `${event.type}:${event.id}`) };+ }+ const first = await run();+ const second = await run();+ assert.deepEqual(first, second);+ assert.deepEqual(first.order.slice(0, 3), ['tile-0-0#0', 'tile-0-1#0', 'tile-1-0#0']);+ assert.ok(first.evicted.length > 0);+});++test('runs as a runtime system and disposes what it holds', async () => {+ const loader = fakeLoader();+ const streaming = createStreaming({ budgetBytes: 500, loaders: { tile: loader }, focus: () => [0, 0, 0] });+ streaming.addAsset(tileDefinition('home', 0));+ const runtime = createRuntime({ render() {} }, { mode: 'variable', systems: [streaming], scheduler: { request: () => 1, cancel() {} }, clock: () => 0 });+ runtime.start();+ runtime.step(16);+ await streaming.settled();+ assert.equal(streaming.getState('home').state, 'loaded');+ runtime.dispose();+ assert.deepEqual(loader.disposed, ['home#0']);+ assert.throws(() => streaming.addAsset(tileDefinition('late', 0)), /disposed/);+});diff --git a/vite.lib.config.js b/vite.lib.config.jsindex 0bb2c083..0d20585c 100644--- a/vite.lib.config.js+++ b/vite.lib.config.js@@ -109,6 +109,7 @@ export default defineConfig({input: 'src/input.js','animation-graph': 'src/animation-graph.js',player: 'src/player.js',+ streaming: 'src/streaming.js','update-part-vertices':'src/update-part-vertices.js','replace-textured-parts': 'src/replace-textured-parts.js',// Page of the MCP preview. It imports the engine chunks above instead of bundling its own copy.