Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.json
index 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.mjs
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.js
index 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.