Large worlds & streaming

A world can be larger than its resident working set#

A large scene cannot keep every high-detail mesh, texture, animation, and physics shape active forever. Streaming keeps the data likely to matter within a bounded memory budget. Visibility is one signal; travel speed, gameplay importance, and pending request age also matter. QubicEngine’s reference world is partitioned into cells with asset dependencies and spatial bounds. WorldStreamer chooses desired cells, AssetStore requests their cooked assets, and Scene activates ready entities at an explicit simulation boundary. Renderer consumes stable ready versions instead of reaching into partially loaded records.

Requests have stages and budgets#

A request moves through file access, decode/import, CPU asset storage, GPU upload, readiness, and residency. These stages have different bottlenecks and completion signals. Streaming diagnostics track bytes and latency per stage so a slow decode does not masquerade as a GPU allocation issue. Low-detail geometry and low-resolution mips can remain resident as fallbacks. A missing fine page should degrade detail rather than break rendering. Physics-critical collision near a player may have higher priority than a distant visual asset; activation policy cannot assume all dependencies have identical urgency.

Coordinate precision#

Floating-point precision becomes less useful as coordinate magnitude grows. The reference design stores broad world positions with higher precision and uses a local origin for rendering/simulation regions. Camera-relative render data subtracts an origin before conversion into GPU-friendly floats. Origin rebasing changes coordinate representations, not the logical identity of entities. Physics state, audio sources, particle caches, motion vectors, and temporal history must follow a documented rebase policy. An unannounced shift can appear as a giant camera/object movement to temporal reconstruction.

A cell is not automatically an entity#

Cells organize residency. Entities retain stable document identities and relationships. Loading a cell resolves references in two phases, similar to scene loading. Cross-cell references must handle a target becoming unavailable without producing stale pointers. WorldStreamer records desired state and ready state separately. A cell being requested is not yet safe to simulate or draw. Conversely, a cell no longer desired may remain retained while earlier frames reference its resources or gameplay holds a dependency.

struct StreamingBudget {
    uint64_t gpuResidentBytes;
    uint64_t stagingBytes;
    uint64_t decodedCpuBytes;
    uint32_t uploadsPerFrame;
};

Selection, LOD, and hysteresis#

Projected detail drives LOD requests. Hysteresis prevents repeated load/evict cycles at a cell border or detail threshold. Prefetch follows likely camera movement, within a budget that leaves room for unexpected requests. Fast travel can use a controlled transition while critical data becomes ready. A virtualized geometry page hierarchy is one form of streaming; ordinary mesh LOD and texture mip residency are simpler forms. They share readiness and retirement ideas but have distinct page tables, compression, and feedback requirements.

Diagnose a streaming hitch#

A frame hitch may be synchronous file access, decode on the main thread, pipeline compilation, a large upload burst, or waiting on a residency dependency. Observe the stage timing before lowering all detail. Visual holes suggest missing fallback or publication before dependencies were ready. Memory growth suggests retained cell references, cache policy, or stuck retirement. Read assets, GPU-driven geometry, and optimization for the contracts that keep streaming bounded.