1-1. UWorldPartition 핵심 클래스 | World Partition Deep Dive

01

UWorldPartition 클래스

월드 파티션 데이터와 스트리밍 정책 관리

UWorldPartition은 World Partition 시스템의 핵심 클래스로, 월드의 파티션 데이터와 스트리밍 정책을 관리합니다.

                    C++ - WorldPartition.h
// Engine/Source/Runtime/Engine/Public/WorldPartition/WorldPartition.h

UCLASS()
class ENGINE_API UWorldPartition : public UObject
{
    GENERATED_BODY()

public:
    // 스트리밍 상태 업데이트 - 매 프레임 호출
    void UpdateStreamingState();

    // 스트리밍 소스 등록/해제
    void RegisterStreamingSourceProvider(IWorldPartitionStreamingSourceProvider* Provider);
    void UnregisterStreamingSourceProvider(IWorldPartitionStreamingSourceProvider* Provider);

    // 스트리밍 완료 확인
    bool IsStreamingCompleted() const;

    // 런타임 해시 접근
    UWorldPartitionRuntimeHash* GetRuntimeHash() const { return RuntimeHash; }

private:
    UPROPERTY()
    TObjectPtr<UWorldPartitionRuntimeHash> RuntimeHash;

    UPROPERTY()
    TObjectPtr<UWorldPartitionStreamingPolicy> StreamingPolicy;
};
                

핵심 멤버 변수

RuntimeHash - 공간 해싱을 통해 스트리밍 셀을 관리
StreamingPolicy - 스트리밍 상태 업데이트 정책 정의
StreamingSourceProviders - 등록된 스트리밍 소스 목록

02

UWorldPartitionSubsystem

월드 레벨에서 World Partition 기능 제공

UWorldPartitionSubsystem은 UTickableWorldSubsystem을 상속받아 월드 레벨에서 World Partition 기능을 제공합니다.

클래스 계층 구조:

UObjectBase
    └── UObjectBaseUtility
        └── UObject
            └── USubsystem
                └── UWorldSubsystem
                    └── UTickableWorldSubsystem
                        └── UWorldPartitionSubsystem

                    C++ - WorldPartitionSubsystem
UCLASS()
class ENGINE_API UWorldPartitionSubsystem : public UTickableWorldSubsystem,
                                            public IStreamingWorldSubsystemInterface
{
    GENERATED_BODY()

public:
    // 서브시스템 접근 헬퍼 함수
    static UWorldPartitionSubsystem* Get(UWorld* World)
    {
        return World ? World->GetSubsystem<UWorldPartitionSubsystem>() : nullptr;
    }

    // 스트리밍 소스 등록
    void RegisterStreamingSourceProvider(IWorldPartitionStreamingSourceProvider* Provider);

    // 스트리밍 완료 확인
    UFUNCTION(BlueprintCallable, Category = "World Partition")
    bool IsStreamingCompleted() const;

    // 모든 셀 로드 여부 확인
    bool IsAllStreamingCompleted() const;

protected:
    virtual void Tick(float DeltaTime) override;
    virtual bool DoesSupportWorldType(EWorldType::Type WorldType) const override;
};
                

서브시스템 사용 예제

                    C++ - 사용 예제
// GameMode나 다른 클래스에서 World Partition Subsystem 접근
void AMyGameMode::CheckStreamingStatus()
{
    if (UWorld* World = GetWorld())
    {
        if (UWorldPartitionSubsystem* WPSubsystem =
            World->GetSubsystem<UWorldPartitionSubsystem>())
        {
            if (WPSubsystem->IsStreamingCompleted())
            {
                UE_LOG(LogTemp, Log, TEXT("All streaming completed!"));
            }
        }
    }
}
                

03

데이터 흐름 개요

에디터/쿡/런타임 단계별 데이터 처리

┌─────────────────────────────────────────────────────────────────┐
│                        EDITOR TIME                               │
├─────────────────────────────────────────────────────────────────┤
│  Actor Files (.uasset)                                          │
│       ↓                                                          │
│  FWorldPartitionActorDesc (Actor Descriptors)                   │
│       ↓                                                          │
│  UActorDescContainer (Actor Descriptor Containers)              │
│       ↓                                                          │
│  Streaming Generation                                            │
│       ↓                                                          │
│  Grid Cells → Streaming Levels                                   │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                        COOK/PIE TIME                             │
├─────────────────────────────────────────────────────────────────┤
│  Streaming Generation Process:                                   │
│  1. Container Instance 수집                                      │
│  2. Actor 필터링 (에디터 전용 액터 제거)                           │
│  3. 클러스터링 (크기, 그리드 할당, 하드 레퍼런스, Data Layers)      │
│  4. Spatial Hash 적용 → 스트리밍 레벨 구성                        │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                        RUNTIME                                   │
├─────────────────────────────────────────────────────────────────┤
│  Streaming Sources (PlayerController, Custom Components)        │
│       ↓                                                          │
│  UWorldPartitionRuntimeSpatialHash::GetStreamingCells()         │
│       ↓                                                          │
│  UWorldPartitionStreamingPolicy::UpdateStreamingState()         │
│       ↓                                                          │
│  Level Streaming (Load/Unload Streaming Levels)                 │
└─────────────────────────────────────────────────────────────────┘

핵심 포인트

에디터에서는 Actor Descriptor를 통해 액터 메타데이터만 로드하고, 실제 액터는 필요할 때만 로드합니다. 이를 통해 대규모 월드에서도 에디터 성능을 유지할 수 있습니다.

04

IWorldPartitionStreamingSourceProvider

스트리밍 소스 인터페이스

스트리밍 소스로 동작하려면 IWorldPartitionStreamingSourceProvider 인터페이스를 구현해야 합니다. APlayerController는 기본적으로 이 인터페이스를 구현합니다.

                    C++ - 인터페이스 구조
class IWorldPartitionStreamingSourceProvider
{
public:
    // 스트리밍 소스 정보 반환
    virtual bool GetStreamingSource(FWorldPartitionStreamingSource& OutSource) const = 0;

    // 우선순위 반환 (높을수록 먼저 처리)
    virtual int32 GetPriority() const { return 0; }

    // 활성화 여부
    virtual bool IsStreamingSourceEnabled() const { return true; }
};
                

기본 스트리밍 소스

APlayerController가 기본 스트리밍 소스로 작동하며, 플레이어 위치 기반으로 셀을 로드합니다.

커스텀 스트리밍 소스

텔레포트 프리로딩, 컷신, AI 등 특수 상황에서 추가 스트리밍 소스를 등록할 수 있습니다.

SUMMARY

핵심 요약

UWorldPartition은 파티션 데이터와 스트리밍 정책을 관리하는 핵심 클래스
UWorldPartitionSubsystem은 월드 레벨에서 API를 제공하고 매 프레임 Tick 처리
에디터에서는 Actor Descriptor로 메타데이터만 로드하여 성능 유지
런타임에서는 스트리밍 소스 위치 기반으로 셀을 동적 로드/언로드
IWorldPartitionStreamingSourceProvider를 구현하여 커스텀 스트리밍 소스 생성 가능

PRACTICE

도전 과제

배운 내용을 직접 실습해보세요

실습 1: UWorldPartitionSubsystem 접근 실습

GameMode에서 UWorldPartitionSubsystem을 가져와 IsStreamingCompleted()를 호출하고, 결과를 HUD에 표시하는 코드를 작성하세요. GetWorld()->GetSubsystem 패턴을 익힙니다.

실습 2: 스트리밍 소스 등록 실습

IWorldPartitionStreamingSourceProvider를 구현하는 커스텀 Actor 클래스를 만들고, GetStreamingSource()에서 특정 위치를 반환하도록 설정하세요. 등록 후 해당 위치 주변의 셀이 로드되는 것을 확인합니다.

심화 과제

런타임에 UWorldPartition의 상태(활성 셀 수, 로딩 중인 셀, 등록된 스트리밍 소스 목록)를 실시간으로 표시하는 디버그 HUD를 구현하세요. ImGui 또는 UMG 오버레이를 활용합니다.