2-1. 스트리밍 소스 컴포넌트 | World Partition Deep Dive

01

스트리밍 소스 개념

셀 로딩의 기준점

스트리밍 소스는 World Partition이 어떤 셀을 로드해야 할지 결정하는 기준점입니다. 기본적으로 PlayerController가 스트리밍 소스로 작동합니다.

기본 스트리밍 소스

PlayerController는 IWorldPartitionStreamingSourceProvider를 구현하여 플레이어 위치 기반 스트리밍을 자동으로 수행합니다.

커스텀 스트리밍 소스

텔레포트 프리로딩, 컷신, AI 관리 등 특수 상황에서 추가 스트리밍 소스가 필요합니다.

02

커스텀 스트리밍 소스 액터

UWorldPartitionStreamingSourceComponent 활용

헤더 파일

                    C++ - MyStreamingSourceActor.h
#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "WorldPartition/WorldPartitionStreamingSource.h"
#include "MyStreamingSourceActor.generated.h"

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

public:
    AMyStreamingSourceActor();

    virtual void BeginPlay() override;
    virtual void EndPlay(const EEndPlayReason::Type EndPlayReason) override;

    // 스트리밍 활성화/비활성화
    UFUNCTION(BlueprintCallable, Category = "Streaming")
    void EnableStreaming();

    UFUNCTION(BlueprintCallable, Category = "Streaming")
    void DisableStreaming();

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

protected:
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Streaming")
    TObjectPtr<UWorldPartitionStreamingSourceComponent> StreamingSourceComponent;

    // 커스텀 로딩 범위
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Streaming")
    float CustomLoadingRange = 25600.0f;

    // 타겟 그리드 (선택적)
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Streaming")
    FName TargetGrid;
};
                

구현 파일

                    C++ - MyStreamingSourceActor.cpp
#include "MyStreamingSourceActor.h"
#include "WorldPartition/WorldPartitionSubsystem.h"

AMyStreamingSourceActor::AMyStreamingSourceActor()
{
    PrimaryActorTick.bCanEverTick = false;

    // 스트리밍 소스 컴포넌트 생성
    StreamingSourceComponent = CreateDefaultSubobject<UWorldPartitionStreamingSourceComponent>(
        TEXT("StreamingSourceComponent"));

    // 루트 컴포넌트로 설정
    RootComponent = CreateDefaultSubobject<USceneComponent>(TEXT("RootComponent"));
}

void AMyStreamingSourceActor::BeginPlay()
{
    Super::BeginPlay();

    if (StreamingSourceComponent)
    {
        // 기본적으로 비활성화 상태로 시작
        StreamingSourceComponent->DisableStreamingSource();
    }
}

void AMyStreamingSourceActor::EndPlay(const EEndPlayReason::Type EndPlayReason)
{
    DisableStreaming();
    Super::EndPlay(EndPlayReason);
}

void AMyStreamingSourceActor::EnableStreaming()
{
    if (StreamingSourceComponent)
    {
        StreamingSourceComponent->EnableStreamingSource();
        UE_LOG(LogTemp, Log, TEXT("Streaming source enabled at location: %s"),
               *GetActorLocation().ToString());
    }
}

void AMyStreamingSourceActor::DisableStreaming()
{
    if (StreamingSourceComponent)
    {
        StreamingSourceComponent->DisableStreamingSource();
    }
}

bool AMyStreamingSourceActor::IsStreamingComplete() const
{
    if (StreamingSourceComponent)
    {
        return StreamingSourceComponent->IsStreamingCompleted();
    }
    return true;
}
                

03

스트리밍 소스 활용 예제

실전 사용 시나리오

텔레포트 프리로딩

플레이어 텔레포트 전 타겟 위치를 미리 로드하여 끊김 없는 전환을 구현합니다.

컷신 영역 로딩

컷신 시작 전 관련 영역을 미리 로드하여 부드러운 시네마틱을 보장합니다.

AI 관리

중요 AI 캐릭터 주변 영역을 항상 로드하여 일관된 AI 동작을 유지합니다.

멀티플레이어

다른 플레이어 위치를 스트리밍 소스로 등록하여 해당 영역도 로드합니다.

성능 고려사항

스트리밍 소스가 많아지면 동시에 로드되는 셀 수가 증가합니다. 필요하지 않은 스트리밍 소스는 반드시 비활성화하세요.

04

스트리밍 완료 대기

비동기 로딩 완료 확인

                    C++ - 스트리밍 완료 대기 예제
// 스트리밍 완료를 기다리는 매니저 클래스
void AMyGameManager::WaitForStreaming(FVector TargetLocation, TFunction<void()> OnComplete)
{
    // 타겟 위치에 스트리밍 소스 생성
    if (!PreloadSource)
    {
        FActorSpawnParameters SpawnParams;
        PreloadSource = GetWorld()->SpawnActor<AMyStreamingSourceActor>(
            TargetLocation, FRotator::ZeroRotator, SpawnParams);
    }
    else
    {
        PreloadSource->SetActorLocation(TargetLocation);
    }

    PreloadSource->EnableStreaming();

    // 타이머로 완료 체크
    GetWorldTimerManager().SetTimer(
        StreamingCheckHandle,
        [this, OnComplete]()
        {
            if (PreloadSource && PreloadSource->IsStreamingComplete())
            {
                GetWorldTimerManager().ClearTimer(StreamingCheckHandle);
                OnComplete();
            }
        },
        0.1f,
        true);
}
                

SUMMARY

핵심 요약

PlayerController는 기본 스트리밍 소스로 자동 작동
UWorldPartitionStreamingSourceComponent로 커스텀 스트리밍 소스 구현
EnableStreamingSource/DisableStreamingSource로 활성화 제어
IsStreamingCompleted로 로딩 완료 여부 확인
불필요한 스트리밍 소스는 반드시 비활성화하여 성능 유지

PRACTICE

도전 과제

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

실습 1: StreamingSourceComponent 설정

블루프린트 액터에 UWorldPartitionStreamingSourceComponent를 추가하고, TargetShape(Sphere/Box), TargetGrids, Priority를 설정하세요. 컴포넌트가 스트리밍 소스로 작동하여 주변 셀이 로드되는 것을 확인합니다.

실습 2: 비플레이어 스트리밍 소스 구현

AI 보스 캐릭터에 StreamingSourceComponent를 추가하여, 보스가 이동하는 경로 주변의 셀이 미리 로드되도록 구현하세요. 보스 등장 전 미리 주변 환경을 로드하는 시나리오를 구성합니다.

심화 과제

게임 상황(전투/탐색/컷신)에 따라 스트리밍 소스의 Shape, Range, Priority를 동적으로 조절하는 시스템을 구현하세요. 전투 시 좁은 범위 고우선순위, 탐색 시 넓은 범위 기본 우선순위로 전환합니다.