Level Streaming

Level Streaming — Deep Engineering Guide

Open worlds don't fit in RAM or load in one frame. Level streaming keeps gigabytes on disk and only the needed few hundred MB resident, without the player ever seeing a pop-in or a hitch. This skill covers stream strategies, cell management, async load, dependency closure, transition LOD and the anti-hitch toolkit.

1. The Core Idea

world = partitioned into cells/chunks (geometry+textures+meshes+audio+nav)
player's camera + prediction → determine "in-scope" set
stream: load only in-scope, drop out-of-scope
budget: bytes aligned to disk speed; never stall the frame

Scope is defined by player relevance (distance bands + occlusion), not "whole level".

2. Stream Strategies

Hybrid is the norm: base persistent + spatial cells around it + scripted chunks for set-pieces.

3. Cell Management (The Heart)

• Cell = a pak unit (see asset-pipeline/packing): one load = one bounded read + one manifest entry.
• Cell metadata: AABB, dependencies, resident state, refcount (a cell near a boundary refcounted by 2 cameras/players).
• Residency states: Unloaded → Loading → Resident → (UnloadPending) → Unloaded.

struct Cell { AABB bounds; vector<AssetId> deps; Residency state; int refs; };

4. The Predict-Ahead Rule (Anti-Pop Guarantee)

Load not just the current cell but the predictive set:

inScope = cells that (camera speed projection enters within ~2 s)
        ∪ (radius: camera predicts ahead)
        ∪ (trigger event claims)

Never "load on the frame you're inside" — that's a minimap-swallowed pop. The streaming budget from asset-pipeline throttles you if you request too much («streaming-throttle»).

5. Async Loading (Never On the Frame Thread)

• File reads on IO threads (see platform-abstraction filesystem refs), decompress on workers.
• Main→worker handoff is deferred: the level gets a "Loading" proxy (an occluder shell / low-poly stand-in) until the resident data arrives.
• Never fread on the main thread — the streaming profiler flags any > 8 ms main-thread load.

6. Dependency Closure (The Silent Loader-Breaker)

A cell "needs" materials, meshes, audio, nav (and those need their deps). The streaming system resolves the full transitive closure:

cell → [mesh_a, mat_a, tex_b] → tex_b → [sampler,cdf]

Failure mode: two cells share a dependency, both load it twice (waste + refcount chaos). Solution: a global asset cache with refcounts; cells request assets, the cache dedupes. The closure must be author-authored+safe (the cook generated it, see asset-pipeline).

7. The Anti-Hitch Toolkit

8. Progression & Transitions

• Fade transitions: a region gate fades the world around it (spawn masked) — far less visible than pop.
• LOD-stepping: streamed-in high-res swaps the shell when ready (rare hitch = micro-shell pops, acceptable).
• Hot-reload (asseteditor) works through the same streaming path (see asset-pipeline/hot-reload).

9. Memory & Budget Control

Watch: a resident set that grows under slow movement = an unload bug (the player leaves a region, cell stays).

10. Determinism & Replay

• Streaming must not affect sim determinism: an asset arriving a frame earlier/later must not change outcomes (entity activation is time-invariant; the sim doesn't depend on load timing).
• Level state seeds are baked (the "asset availability" is a config; the sim only reads resident-safe data).

11. References

• references/stream-strategies.md — strategies table, hybrid, authoring, plan
• references/cells-and-residency.md — cell anatomy, residency states, refcounts, radius rules
• references/async-loading.md — IO threads, deferred activation, shell proxies, profiler gates
• references/asset-dependencies.md — closure resolution, global cache, dedupe, cook-generated graphs
• references/hitch-prevention.md — the full toolkit, thresholds, tests, watchdogs
• references/progressive-transitions.md — LOD-stepping, fades, shell→resident swap, editor hot-reload