World Streaming getting started

This chapter gets a partitioned world streaming with the shortest path: enable the Gem, declare a world, bake, add a streaming source, and verify in play mode.

Prerequisites

• The WorldStreaming Gem is enabled in your project (Project Manager or project.json).
• Asset Processor is running so bake products can compile.
• For large-coordinate playtests, pair with double-precision rendering.

Enable the Gem and runtime

1. Enable WorldStreaming in Project Manager (or add it to project.json).
2. Runtime streaming is off by default, even when the Gem is enabled. Turn it on in the project Settings Registry:

{
 "WorldStreaming": {
 "Enabled": true
 }
}

Optionally set DefaultManifest so the world loads automatically at startup (step 4 below). Full defaults ship in Gems/WorldStreaming/Registry/WorldStreaming.setreg; override only what you need. See Configuration and debugging.

Minimal loop (six steps)

1 Declare a partitioned world
 → 2 Place content
 → 3 Bake
 → 4 Configure runtime entry
 → 5 Add a streaming source
 → 6 Play and verify

1. Declare a partitioned world

A world definition has two parts:

• A WorldConfig entity on the level root (WorldStreamingConfigComponent): grids, Content Layers, HLOD layers, worldGuid / cellIdSalt.
• A sibling .wsworld descriptor: the bake aggregation source list.

Common ways to create one:

Details: Authoring.

2. Place content

• Ordinary entities need no extra component: bake assigns them to the default grid cell by world position.
• For finer control, add WorldStreamingMemberComponent (AlwaysLoaded, target grid, Content Layer, exclude-from-HLOD, and more).

3. Bake

In Tools → World Streaming, click Bake World Streaming: save dirty shards → validate the descriptor → Asset Processor incrementally produces cell Spawnables and the .wsmanifest.

Regional or per-grid bake options are covered in Baking.

4. Configure runtime entry

Set the Manifest path so the runtime can load the world:

{
 "WorldStreaming": {
 "Enabled": true,
 "DefaultManifest": "levels/mybigworld/mybigworld.wsmanifest"
 }
}

Or load from code:

#include <WorldStreaming/IWorldStreamingSystem.h>

auto* wp = WorldStreaming::WorldStreamingInterface::Get();
wp->LoadWorld(manifestAssetId);

5. Add a streaming source

Add a World Streaming Streaming Source component to the player or camera entity (category “World Streaming”). Defaults: Load Radius 256 m, Activate Radius 128 m.

Without at least one enabled source (component, script, or provider), cells stay Unloaded.

6. Play and verify

ws_dumpStats
ws_drawRuntimeHash3D true
ws_imguiPanel true

Expect non-zero Loaded / Activated cell counts near the source, and green (Activated) / amber (Loaded) cells in the hash overlay. More diagnostics: Configuration and debugging.

Cell state machine (must know)

Unloaded → Loading → Loaded → Activating → Activated
 ↑ |
 └── Deactivating ←───────────┘
Loaded → Unloading → Unloaded
load failure → Failed (exponential backoff retry)

• Loaded: resident in memory, not simulating or rendering (warmup).
• Activated: active for simulation and rendering.
• Load Radius drives the Loaded ring; Activate Radius drives the Activated ring. Unload / deactivate use hysteresis and cooldown to avoid boundary thrashing.

Full semantics: Core concepts and Runtime streaming.

Root Spawnable relationship

Startup uses a light Root Spawnable + Manifest + cell Spawnables model: the level root keeps resident config only; world content streams through the Manifest. Do not pack the same content into both Root and cells—enable ws_blockOnRootDoubleInstance to catch double instantiation during bring-up.

Sample content

Automated test levels (not a shipping sample, but useful references):

• AutomatedTesting/Levels/WorldStreaming/WorldStreaming_Streaming/
• AutomatedTesting/Levels/WorldStreaming_AutoShard/

Next steps

• Core concepts: glossary-level model of cells, grids, and sources.
• Authoring: partition view, focus loading, editor shards, migration.
• Runtime streaming: streaming-source fields and budgets.