Ue World Level Streaming

UE World & Level Streaming

Target engine: UE 5.8. APIs below are verified against the 5.8 headers; older forms are listed under "Deprecated — do not use".

This skill covers how a UWorld is composed and swapped at runtime: World Partition grids, data layers, HLOD, level instances, classic sub-level streaming, streaming volumes, and map travel. Everything here lives in the Engine module (Engine/Source/Runtime/Engine), so Core, CoreUObject and Engine in PublicDependencyModuleNames is all that is needed. The one exception is the Level Streaming Persistence plugin, which adds the LevelStreamingPersistence module.

For end-to-end configurations per game type (open world, hub-and-spoke, procedural, chapter-based, volume-driven, dedicated server), see streaming patterns.

Context

Read .agents/ue-project-context.md if it exists (module names, conventions, enabled plugins, GAS/networking setup). Do not stop if it is missing.

Identify the area from the request and the codebase. Ask only when two plausible readings would produce different code.

Choosing a Streaming Model

World Partition and sub-level streaming are mutually exclusive on the same persistent level. UWorld::IsPartitionedWorld() (Engine/World.h:2968) reports which one is in play; AWorldSettings::GetWorldPartition() (GameFramework/WorldSettings.h:837) returns the partition object (the WorldPartition member is protected).

World Partition Runtime

UWorldPartition (WorldPartition/WorldPartition.h) owns the runtime hash that turns actors into cells. UWorldPartitionSubsystem is the per-world entry point and is a UTickableWorldSubsystem.

#include "WorldPartition/WorldPartition.h"
#include "WorldPartition/WorldPartitionSubsystem.h"

UWorldPartitionSubsystem* Subsystem = GetWorld()->GetSubsystem<UWorldPartitionSubsystem>();
if (Subsystem && Subsystem->IsAllStreamingCompleted())
{
    // Every cell has finished loading, adding to or removing from the world.
}

Subsystem->ForEachWorldPartition([](UWorldPartition* Partition)
{
    return Partition->IsStreamingEnabled(); // return false to stop iterating
});

UWorldPartitionRuntimeCell is the unit the hash produces. Query readiness at an arbitrary point with a query source instead of polling actors:

#include "WorldPartition/WorldPartitionRuntimeCell.h"
#include "WorldPartition/WorldPartitionStreamingSource.h"

TArray<FWorldPartitionStreamingQuerySource> QuerySources;
QuerySources.Emplace(TargetLocation); // FVector

const bool bReady = Subsystem->IsStreamingCompleted(
    EWorldPartitionRuntimeCellState::Activated, QuerySources, /*bExactState=*/false);

EWorldPartitionRuntimeCellState is Unloaded, Loaded, Activated (WorldPartitionRuntimeCell.h:202).

Streaming sources

Any object can drive streaming by implementing IWorldPartitionStreamingSourceProvider (a plain interface struct in WorldPartitionStreamingSource.h) and registering it with the subsystem. For the common "this actor pulls cells in" case, add a UWorldPartitionStreamingSourceComponent instead — it already implements the provider and registers itself.

The two virtuals to override are virtual bool GetStreamingSources(TArray<FWorldPartitionStreamingSource>& StreamingSources) const and virtual const UObject* GetStreamingSourceOwner() const. Register in BeginPlay with UWorldPartitionSubsystem::RegisterStreamingSourceProvider(this) and release in EndPlay with UnregisterStreamingSourceProvider(this). A complete actor implementation is in streaming patterns.

• EStreamingSourceTargetState: Loaded (in memory, not added to the world) or Activated.
• EStreamingSourcePriority: Highest, High, Normal, Low, Lowest, Default (equals Normal).
• TargetGrids plus EStreamingSourceTargetBehavior (Include / Exclude) restrict a source to named runtime grids.
• bBlockOnSlowLoading opts the source into the engine's blocking path when streaming falls behind. Leave it false for cosmetic sources.
• UWorldPartitionSubsystem::GetStreamingSources(const UWorldPartition*, TArray<FWorldPartitionStreamingSource>&) reads back everything currently registered.

Runtime CVars

Data Layers

Actors reference data layers through AActor::DataLayerAssets (TArray<TSoftObjectPtr<UDataLayerAsset>>, GameFramework/Actor.h:1123). UDataLayerAsset is the authored asset, UDataLayerInstance is its per-world instance, and UDataLayerManager is the runtime accessor, reachable from any object inside a partitioned world.

// MyDataLayerController.h
#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "MyDataLayerController.generated.h"

class UDataLayerAsset;

UCLASS()
class MYGAME_API AMyDataLayerController : public AActor
{
    GENERATED_BODY()

public:
    UFUNCTION(BlueprintCallable, Category = "MyGame|Streaming")
    void SetDungeonActive(bool bActive);

    UFUNCTION(BlueprintCallable, Category = "MyGame|Streaming")
    bool IsDungeonActivated() const;

protected:
    UPROPERTY(EditAnywhere, Category = "MyGame|Streaming")
    TObjectPtr<const UDataLayerAsset> DungeonLayer;
};

// MyDataLayerController.cpp
#include "MyDataLayerController.h"
#include "WorldPartition/DataLayer/DataLayerAsset.h"
#include "WorldPartition/DataLayer/DataLayerInstance.h"
#include "WorldPartition/DataLayer/DataLayerManager.h"

void AMyDataLayerController::SetDungeonActive(bool bActive)
{
    UDataLayerManager* Manager = UDataLayerManager::GetDataLayerManager(this);
    if (!Manager || !DungeonLayer)
    {
        return;
    }

    const EDataLayerRuntimeState NewState =
        bActive ? EDataLayerRuntimeState::Activated : EDataLayerRuntimeState::Unloaded;

    Manager->SetDataLayerRuntimeState(DungeonLayer, NewState, /*bInIsRecursive=*/true);
}

bool AMyDataLayerController::IsDungeonActivated() const
{
    UDataLayerManager* Manager = UDataLayerManager::GetDataLayerManager(this);
    if (!Manager || !DungeonLayer)
    {
        return false;
    }

    const UDataLayerInstance* Instance = Manager->GetDataLayerInstanceFromAsset(DungeonLayer);
    return Instance && Manager->GetDataLayerInstanceRuntimeState(Instance) == EDataLayerRuntimeState::Activated;
}

EDataLayerRuntimeState (DataLayerInstance.h:23): Unloaded, Loaded (in memory but not visible — use it to pre-warm), Activated (loaded and visible).

Other manager entry points: SetDataLayerInstanceRuntimeState(const UDataLayerInstance*, EDataLayerRuntimeState, bool bInIsRecursive), GetDataLayerInstanceEffectiveRuntimeState, GetDataLayerInstances(), GetDataLayerInstanceFromName(const FName&), and the BlueprintAssignable delegate OnDataLayerInstanceRuntimeStateChanged. To sweep every instance:

Manager->ForEachDataLayerInstance([](UDataLayerInstance* Instance)
{
    return Instance->IsRuntime(); // return false to stop early
});

Authority: a runtime data layer with no load filter only responds to state changes made on the server, and the resulting state replicates. Client-only layers must be changed on the client, server-only layers on the server. The old world-subsystem accessor still exists as a deprecated shim — see Deprecated — do not use; route everything through UDataLayerManager.

Level Instances

ALevelInstance (LevelInstance/LevelInstanceActor.h) places a .umap as a reusable chunk and implements ILevelInstanceInterface. ULevelInstanceSubsystem is the UWorldSubsystem that tracks them.

#include "Engine/World.h"
#include "LevelInstance/LevelInstanceActor.h"
#include "LevelInstance/LevelInstanceSubsystem.h"

void AMyLevelInstanceDriver::ShowRoom(ALevelInstance* RoomInstance)
{
    if (!RoomInstance)
    {
        return;
    }

    RoomInstance->LoadLevelInstance(); // queued; loads on the subsystem's next streaming update, so IsLoaded() is false this frame

    ULevelInstanceSubsystem* Subsystem = GetWorld()->GetSubsystem<ULevelInstanceSubsystem>();
    if (Subsystem && Subsystem->IsLoaded(RoomInstance))
    {
        Subsystem->ForEachActorInLevelInstance(RoomInstance, [](AActor* LevelActor)
        {
            LevelActor->SetActorTickEnabled(true);
            return true;
        });
    }
}

• ILevelInstanceInterface runtime members: LoadLevelInstance(), UnloadLevelInstance(), IsLoaded(), GetLoadedLevel(), GetLevelStreaming(), GetWorldAsset(), GetLevelInstanceID(), IsInitiallyVisible().
• ULevelInstanceSubsystem runtime members: GetLevelInstance(const FLevelInstanceID&), GetOwningLevelInstance(const ULevel*), RequestLoadLevelInstance(ILevelInstanceInterface*, bool bUpdate), RequestUnloadLevelInstance(ILevelInstanceInterface*), IsLoaded, IsLoading, ForEachActorInLevelInstance, GetLevelInstanceLevel. The editing entry points are WITH_EDITOR only.
• ELevelInstanceRuntimeBehavior (LevelInstanceTypes.h:56) picks how the instance reaches the runtime: Partitioned (actors move into the main partition grid; shown as "Embedded") or LevelStreaming (its own streaming level; shown as "Standalone").
• APackedLevelActor (PackedLevelActor/PackedLevelActor.h) derives from ALevelInstance and bakes its static meshes into instanced-mesh components. It reports ELevelInstanceRuntimeBehavior::None and loads no level at runtime.

Sub-Level Streaming

ULevelStreaming state

ELevelStreamingState (Engine/LevelStreaming.h:110) is Removed, Unloaded, FailedToLoad, Loading, LoadedNotVisible, MakingVisible, LoadedVisible, MakingInvisible. Read it with GetLevelStreamingState(). The requested side is ELevelStreamingTargetState (Unloaded, UnloadedAndRemoved, LoadedNotVisible, LoadedVisible).

#include "Engine/LevelStreaming.h"
#include "Kismet/GameplayStatics.h"

ULevelStreaming* Streaming = UGameplayStatics::GetStreamingLevel(this, FName("/Game/Levels/L_Zone_A"));
if (Streaming)
{
    Streaming->SetShouldBeLoaded(true);
    Streaming->SetShouldBeVisible(true);

    const bool bReady = Streaming->IsLevelLoaded() && Streaming->IsLevelVisible();
    ULevel* Loaded = Streaming->GetLoadedLevel();
}

Four BlueprintAssignable delegates, all with no parameters: OnLevelLoaded, OnLevelUnloaded, OnLevelShown, OnLevelHidden. Bind with AddDynamic to a no-argument UFUNCTION().

Use SetIsRequestingUnloadAndRemoval(true) to drop the streaming level object entirely. Never mutate UWorld::StreamingLevels directly — use AddStreamingLevel, AddStreamingLevels, RemoveStreamingLevel, RemoveStreamingLevels and UpdateStreamingLevelShouldBeConsidered (Engine/World.h:1073-1109), which maintain StreamingLevelsToConsider.

Latent load and unload

UGameplayStatics::LoadStreamLevel(const UObject* WorldContextObject, FName LevelName, bool bMakeVisibleAfterLoad, bool bShouldBlockOnLoad, FLatentActionInfo LatentInfo) and UnloadStreamLevel(const UObject* WorldContextObject, FName LevelName, FLatentActionInfo LatentInfo, bool bShouldBlockOnUnload) resume through FLatentActionInfo::ExecutionFunction, which is resolved by name through the reflection system. The callback therefore has to be a UFUNCTION() declared inside a class body in a header.

// MyStreamingActor.h
#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "MyStreamingActor.generated.h"

UCLASS()
class MYGAME_API AMyStreamingActor : public AActor
{
    GENERATED_BODY()

public:
    void StreamInRoom(FName LevelName);
    void StreamOutRoom(FName LevelName);

    // UFUNCTION on the declaration is mandatory: FLatentActionInfo::ExecutionFunction
    // is looked up by name on CallbackTarget's UClass.
    UFUNCTION()
    void OnRoomLoaded();

    UFUNCTION()
    void OnRoomUnloaded();

protected:
    bool bRoomReady = false;
};

// MyStreamingActor.cpp
#include "MyStreamingActor.h"
#include "Engine/LatentActionManager.h"
#include "Kismet/GameplayStatics.h"

void AMyStreamingActor::StreamInRoom(FName LevelName)
{
    FLatentActionInfo LatentInfo;
    LatentInfo.CallbackTarget = this;
    LatentInfo.ExecutionFunction = FName("OnRoomLoaded");
    LatentInfo.Linkage = 0;
    LatentInfo.UUID = 1; // unique per pending latent action on this object

    UGameplayStatics::LoadStreamLevel(this, LevelName,
        /*bMakeVisibleAfterLoad=*/true, /*bShouldBlockOnLoad=*/false, LatentInfo);
}

void AMyStreamingActor::StreamOutRoom(FName LevelName)
{
    FLatentActionInfo LatentInfo;
    LatentInfo.CallbackTarget = this;
    LatentInfo.ExecutionFunction = FName("OnRoomUnloaded");
    LatentInfo.Linkage = 0;
    LatentInfo.UUID = 2;

    UGameplayStatics::UnloadStreamLevel(this, LevelName, LatentInfo, /*bShouldBlockOnUnload=*/false);
}

void AMyStreamingActor::OnRoomLoaded()
{
    bRoomReady = true;
}

void AMyStreamingActor::OnRoomUnloaded()
{
    bRoomReady = false;
}

LoadStreamLevelBySoftObjectPtr and UnloadStreamLevelBySoftObjectPtr take a TSoftObjectPtr<UWorld> in place of the FName and are the packaging-safe form. UGameplayStatics::FlushLevelStreaming(const UObject*) blocks until pending work completes; UWorld::FlushLevelStreaming(EFlushLevelStreamingType) gives finer control (None, Full, Visibility).

Runtime level instancing

ULevelStreamingDynamic loads one package repeatedly at different transforms. Prefer the params-struct overload, because the by-name overload cannot express a full FTransform.

#include "Engine/LevelStreamingDynamic.h"
#include "Engine/World.h"

ULevelStreamingDynamic* AMyDungeonGenerator::SpawnRoom(const FTransform& RoomTransform, const FString& InstanceName)
{
    ULevelStreamingDynamic::FLoadLevelInstanceParams Params(
        GetWorld(), TEXT("/Game/Levels/L_Room_Corridor"), RoomTransform);

    Params.OptionalLevelNameOverride = &InstanceName; // identical on server and clients
    Params.bInitiallyVisible = true;

    bool bSuccess = false;
    ULevelStreamingDynamic* Level = ULevelStreamingDynamic::LoadLevelInstance(Params, bSuccess);
    return bSuccess ? Level : nullptr;
}

Tear an instance down with SetShouldBeVisible(false), SetShouldBeLoaded(false), then SetIsRequestingUnloadAndRemoval(true). A generator that tracks its instances and binds OnLevelShown is in streaming patterns.

FLoadLevelInstanceParams members: World, LongPackageName, LevelTransform, OptionalLevelNameOverride (const FString*), OptionalLevelStreamingClass, bLoadAsTempPackage, bInitiallyVisible, bAllowReuseExitingLevelStreaming, EditorPathOwner, LevelStreamingCreatedCallback.

The Blueprint-exposed overloads are LoadLevelInstance(UObject* WorldContextObject, FString LevelName, FVector Location, FRotator Rotation, bool& bOutSuccess, const FString& OptionalLevelNameOverride, TSubclassOf<ULevelStreamingDynamic> OptionalLevelStreamingClass, bool bLoadAsTempPackage) and LoadLevelInstanceBySoftObjectPtr, which takes a TSoftObjectPtr<UWorld> in place of LevelName and the same tail parameters; a C++-only BySoftObjectPtr overload takes an FTransform (Engine/LevelStreamingDynamic.h:94).

Streaming volumes

ALevelStreamingVolume drives sub-levels from camera position. EStreamingVolumeUsage values: SVB_Loading, SVB_LoadingAndVisibility, SVB_VisibilityBlockingOnLoad, SVB_BlockingOnLoad, SVB_LoadingNotVisible. Set StreamingUsage on the volume; StreamingLevelNames lists what it affects and a streaming level's EditorStreamingVolumes array is the editor-side link. Set ULevelStreaming::bDisableDistanceStreaming = true to take a level off volume control, and MinTimeBetweenVolumeUnloadRequests to damp flicker at volume boundaries. Streaming volumes do nothing in a partitioned world.

Level Travel

Seamless travel

1. Set bUseSeamlessTravel = true in the GameMode constructor. It is already a UPROPERTY on AGameModeBase (GameModeBase.h:579) — do not redeclare it.
2. Set a transition map. Without one the engine transitions through an empty dummy world (World.cpp:8367). In PIE, seamless travel falls back to hard travel unless net.AllowPIESeamlessTravel=1 (GameModeBase.cpp:506).

[/Script/EngineSettings.GameMapsSettings]
TransitionMap=/Game/Maps/L_Transition.L_Transition

3. Override the persistence hooks. Signatures are verbatim from GameFramework/GameModeBase.h:239-268:

// MyGameMode.cpp
void AMyGameMode::GetSeamlessTravelActorList(bool bToTransition, TArray<AActor*>& ActorList)
{
    Super::GetSeamlessTravelActorList(bToTransition, ActorList);

    if (MyPersistentManager)
    {
        ActorList.Add(MyPersistentManager); // called for both legs (to transition, then to destination); add on both
    }
}

void AMyGameMode::PostSeamlessTravel()
{
    Super::PostSeamlessTravel();
}

void AMyGameMode::HandleSeamlessTravelPlayer(AController*& C)
{
    Super::HandleSeamlessTravelPlayer(C);
}

APlayerController::GetSeamlessTravelActorList(bool bToEntry, TArray<AActor*>& ActorList) is the client-side counterpart. APlayerController::SeamlessTravelTo(APlayerController* NewPC) / SeamlessTravelFrom(APlayerController* OldPC) and APlayerState::SeamlessTravelTo(APlayerState* NewPlayerState) copy per-player state onto the new objects. UWorld::IsInSeamlessTravel() and UWorld::SetSeamlessTravelMidpointPause(bool bNowPaused) control the midpoint; UWorld::OnSeamlessTravelStart and UWorld::OnSeamlessTravelTransition are static multicast delegates for observers.

Replication behaviour across travel (channel teardown, actor re-creation, net relevancy) belongs to ue-networking-replication; UNetDriver::NotifyActorLevelUnloaded(AActor*) is the hook it uses when a streamed level goes away.