데브 지노 - 지노윈의 개발 스토리

Unreal Engine 에셋 매니저(Asset Manager)의 번들(Bundle) 기능

지노윈 — Fri, 2 Jan 2026 18:14:35 +0900

비동기 로딩이 진행되는 동안 사용자에게 진행 상황을 보여주는 로딩 화면(UI) 구현과 에셋을 그룹 단위로 관리하는 에셋 매니저(Asset Manager)의 번들(Bundle) 기능에 대해 설명해 드릴게요.

비동기 로딩과 UI 연동 (진척도 표시)

비동기 로딩을 요청하면 TSharedPtr<FStreamableHandle>이라는 핸들을 반환받습니다. 이 핸들을 통해 현재 로딩이 얼마나 진행되었는지 확인할 수 있습니다.

[C++ 예시: 진척도 확인]

// 1. 로드 요청 시 핸들을 보관합니다.
TSharedPtr<FStreamableHandle> LoadHandle;

void AMyGameMode::StartLoading(TArray<FSoftObjectPath> AssetsToLoad)
{
    FStreamableManager& Loader = UAssetManager::GetStreamableManager();
    
    // 핸들을 저장하여 상태를 추적합니다.
    LoadHandle = Loader.RequestAsyncLoad(AssetsToLoad, FStreamableDelegate::CreateUObject(this, &AMyGameMode::OnLoadFinished));
}

void AMyGameMode::Tick(float DeltaTime)
{
    if (LoadHandle.IsValid() && LoadHandle->IsLoadingInProgress())
    {
        // 2. 0.0 ~ 1.0 사이의 진행률을 가져와 UI(ProgressBar)에 전달합니다.
        float Progress = LoadHandle->GetProgress();
        MyLoadingWidget->UpdateProgressBar(Progress);
    }
}

에셋 매니저와 번들(Bundles) 활용

번들은 에셋들을 특정 상황(예: "Lobby", "InGame", "BossFight")에 맞춰 그룹화하는 기능입니다. 데이터 테이블 내의 TSoftObjectPtr에 번들 이름을 지정해두면, 에셋 매니저가 한 번에 해당 그룹을 로드하거나 해제할 수 있습니다.

[설계 방법]

Primary Data Asset 사용: UPrimaryDataAsset을 상속받은 클래스를 만들고, 에셋 매니저에 등록합니다.
번들 태그 지정: UPROPERTY 메타데이터에 AssetBundles를 추가합니다.

UCLASS()
class UMyItemAsset : public UPrimaryDataAsset
{
    GENERATED_BODY()

public:
    // 이 메쉬는 'Visual'이라는 번들 이름을 가집니다.
    UPROPERTY(EditAnywhere, BlueprintReadWrite, AssetRegistrySearchable, meta = (AssetBundles = "Visual"))
    TSoftObjectPtr<UStaticMesh> ItemMesh;
};

번들 단위 로드: 에셋 매니저의 LoadPrimaryAsset 함수를 호출할 때, 로드하고 싶은 번들 리스트(Visual)를 넘겨주면 해당 그룹의 소프트 포인터들만 한꺼번에 로드됩니다.

실무 로딩 화면 시퀀스

일반적으로 다음과 같은 순서로 로직을 구성합니다.

UI 생성: 로딩 바가 있는 위젯을 화면에 띄웁니다.
로드 요청: 에셋 매니저에게 필요한 에셋(또는 번들) 로드를 요청하고 핸들을 받습니다.
상태 체크: Tick이나 Timer를 통해 핸들의 GetProgress()를 UI에 동기화합니다.
완료 콜백: 로드가 완료되면 핸들의 Delegate가 실행되고, 로딩 UI를 제거한 뒤 게임을 시작합니다.

주의할 점: 메모리 누수 방지

비동기 로드 핸들(FStreamableHandle)은 로드가 끝난 후에도 핸들을 명시적으로 해제(Release)하지 않으면 메모리에 해당 에셋들을 계속 붙잡고 있을 수 있습니다. TSharedPtr인 핸들이 유효 범위를 벗어나거나 수동으로 CancelHandle()을 호출하여 관리해야 합니다.

Unreal Engine의 Data Table과 TSoftObjectPtr 활용한 응

지노윈 — Fri, 2 Jan 2026 14:07:58 +0900

데이터 테이블(Data Table)과 TSoftObjectPtr을 결합하는 방식은 대규모 RPG나 수집형 게임에서 메모리 효율을 극대화하는 핵심 설계 패턴입니다. 모든 아이템 정보를 담은 데이터 테이블이 메모리에 올라와 있어도, 실제 사용되는 리소스(메쉬, 텍스처)는 필요한 순간에만 로드하기 때문입니다.

구조체(Struct) 정의

먼저 데이터 테이블의 행(Row)이 될 구조체를 정의합니다. 이때 리소스는 반드시 TSoftObjectPtr로 선언합니다.

C++

USTRUCT(BlueprintType)
struct FItemData : public FTableRowBase
{
    GENERATED_BODY()

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FString ItemName;

    // 하드 참조가 아닌 소프트 참조로 선언!
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    TSoftObjectPtr<UStaticMesh> ItemMesh;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    TSoftObjectPtr<UTexture2D> ItemIcon;
};

에셋 관리자(Asset Manager)를 통한 로드 제어

데이터 테이블에서 특정 아이템 정보를 가져와 비동기 로드하는 로직을 구현합니다.

void AMyCharacter::EquipItem(FName ItemRowName)
{
    // 1. 데이터 테이블에서 정보 가져오기
    static const FString ContextString(TEXT("ItemContext"));
    FItemData* Data = ItemDataTable->FindRow<FItemData>(ItemRowName, ContextString);

    if (Data)
    {
        // 2. 이미 로드되어 있는지 확인
        if (Data->ItemMesh.IsValid())
        {
            ApplyItemMesh(Data->ItemMesh.Get());
        }
        else
        {
            // 3. 비동기 로드 요청
            FStreamableManager& Loader = UAssetManager::GetStreamableManager();
            
            // 람다(Lambda)를 사용하면 콜백 함수를 따로 만들지 않아도 되어 편리합니다.
            Loader.RequestAsyncLoad(Data->ItemMesh.ToSoftObjectPath(), 
                FStreamableDelegate::CreateLambda([this, Data]() {
                    if (Data->ItemMesh.IsValid())
                    {
                        ApplyItemMesh(Data->ItemMesh.Get());
                    }
                })
            );
        }
    }
}

이 구조를 사용하면 데이터 테이블 자체는 가벼운 "텍스트/경로 정보"만 들고 있게 됩니다.

실무에서 아주 유용한 "Primary Asset Label" 팁

데이터 테이블에 등록된 수많은 TSoftObjectPtr 에셋들을 나중에 한꺼번에 패키징하거나 관리하기 어려울 때가 있습니다.

Asset Manager 설정: 프로젝트 세팅의 Asset Manager에서 특정 폴더나 데이터 테이블을 등록해두면, 게임 빌드 시 해당 에셋들이 누락되지 않도록 자동으로 관리할 수 있습니다.
번들(Bundles): "InGame", "Menu", "Cinematic" 같은 태그를 붙여, 특정 상황에서 필요한 에셋 뭉치만 한 번에 로드하는 기능도 지원합니다.

요약: 데이터 테이블 활용 전략

데이터 테이블 로드: 게임 시작 시 혹은 필요한 시점에 테이블을 로드합니다 (텍스트 데이터라 매우 가벼움).
리소스 참조: 테이블 내부의 TSoftObjectPtr을 통해 필요한 에셋의 경로만 파악합니다.
지연 로딩: 실제 아이템이 화면에 그려지기 직전에 비동기로 로드합니다.
메모리 해제: 해당 아이템을 더 이상 쓰지 않으면 참조를 해제하여 GC가 수거하게 합니다.

Unreal Engine 비동기 로딩

지노윈 — Fri, 2 Jan 2026 14:03:28 +0900

비동기 로딩은 게임의 끊김(Stuttering)을 방지하는 핵심 기술입니다. TSoftObjectPtr을 실제 프로젝트에서 효과적으로 사용하는 두 가지 핵심 방법(C++와 블루프린트)을 정리해 드릴게요.

1. C++: FStreamableManager를 이용한 비동기 로딩

가장 권장되는 방식입니다. 엔진의 전역 매니저를 사용하여 백그라운드 스레드에서 에셋을 로드하고, 완료되면 콜백 함수를 실행합니다.

[코드 예시]

// Header (.h)
UPROPERTY(EditAnywhere, Category = "Assets")
TSoftObjectPtr<UStaticMesh> SubMeshPtr;

void OnMeshLoaded(); // 로드 완료 후 실행될 함수

// Source (.cpp)
void AMyActor::StartAsyncLoad()
{
    if (SubMeshPtr.IsPending())
    {
        // 1. 스트리밍 매니저 가져오기 (보통 GameInstance나 전역으로 관리)
        FStreamableManager& AssetLoader = UAssetManager::GetStreamableManager();
        
        // 2. 비동기 로드 요청
        AssetLoader.RequestAsyncLoad(SubMeshPtr.ToSoftObjectPath(), 
            FStreamableDelegate::CreateUObject(this, &AMyActor::OnMeshLoaded));
    }
}

void AMyActor::OnMeshLoaded()
{
    // 3. 로드가 완료되었으므로 Get()을 통해 실제 포인터를 가져옴
    UStaticMesh* LoadedMesh = SubMeshPtr.Get();
    if (LoadedMesh)
    {
        MyMeshComponent->SetStaticMesh(LoadedMesh);
        UE_LOG(LogTemp, Log, TEXT("Async Load Complete!"));
    }
}

2. 블루프린트: Async Load Asset 노드 사용

C++보다 훨씬 직관적이며, 복잡한 로직이 필요 없는 UI나 간단한 액터 로직에 자주 쓰입니다.

변수 생성: 변수 타입을 원하는 객체(예: Static Mesh)의 Soft Object Reference로 설정합니다.
노드 배치: Async Load Asset 노드를 배치하고 Soft Object Reference를 연결합니다.
완료 처리: Completed 핀이 실행되면, Get Asset 노드를 통해 로드된 객체를 사용합니다.

3. 실무 활용 팁: "언제 로드하고 언제 해제할까?"

TSoftObjectPtr을 효율적으로 쓰기 위한 전략입니다.

인벤토리 시스템: 아이템 데이터 테이블에는 모든 아이콘을 TSoftObjectPtr로 담아둡니다. 인벤토리 창을 열 때만 화면에 보이는 아이콘들을 비동기 로드하고, 창을 닫으면 참조를 해제(null 대입)하여 메모리를 확보합니다.
보스전: 플레이어가 보스 방 근처 트리거에 진입했을 때 보스의 고해상도 메쉬와 이펙트를 로드하기 시작합니다.
참조 해제: TSoftObjectPtr 자체는 스마트 포인터이므로, 이를 소유한 클래스가 파괴되거나 해당 변수에 다른 값을 넣으면 가비지 컬렉터(GC)가 판단하여 메모리에서 해제합니다.

4. 주의사항: "Hard Reference"를 조심하세요!

만약 TSoftObjectPtr 변수를 선언해두고, 코드 어딘가에서 이 변수를 일반 포인터(UStaticMesh*) 변수에 담아버리면, 그 즉시 하드 참조가 되어 비동기 로딩의 이점이 사라집니다. 로드가 끝난 후에도 필요한 짧은 순간에만 지역 변수로 받아 쓰고, 멤버 변수로는 계속 TSoftObjectPtr 상태를 유지하는 것이 좋습니다.

Unreal Engine의 TSoftObjectPtr 이란?

지노윈 — Fri, 2 Jan 2026 14:00:48 +0900

TObjectPtr이 "이미 로드된 객체를 어떻게 가리킬 것인가"에 집중한다면, TSoftObjectPtr은 "아직 로드되지 않은 객체를 어떻게 안전하게 가리키고, 원할 때 로드할 것인가"에 특화된 스마트 포인터입니다.

1. Hard Reference vs Soft Reference

가장 큰 차이는 메모리 로드 타이밍입니다.

Hard Reference (TObjectPtr, UPROPERTY 포인터): A 클래스가 B 에셋을 하드 참조하면, A가 메모리에 로드될 때 B도 반드시 함께 로드됩니다. 이를 "줄줄이 비엔나"처럼 연쇄 로딩이 발생한다고 표현하며, 메모리 낭비의 주범이 됩니다.
Soft Reference (TSoftObjectPtr): A가 B를 소프트 참조하면, A가 로드되어도 B는 로드되지 않습니다. 대신 B가 있는 경로(Path) 문자열만 가지고 있습니다. 실제 객체는 개발자가 코드로 "지금 로드해!"라고 명령할 때만 메모리에 올라옵니다.

2. 주요 특징 및 장점

메모리 최적화: 게임 시작 시 모든 무기, 캐릭터, 맵 데이터를 로드할 필요 없이, 플레이어가 해당 아이템을 획득하거나 지역에 진입할 때만 로드할 수 있습니다.
비동기 로딩 지원: 게임이 멈추지 않게 백그라운드에서 에셋을 로드하는 FStreamableManager와 함께 자주 사용됩니다.
안전한 참조: 객체가 메모리에서 해제되었는지 여부를 추적할 수 있어, 댕글링 포인터(Dangling Pointer) 문제를 방지합니다.

3. 실전 사용법 (C++)

TSoftObjectPtr은 일반 포인터처럼 바로 쓸 수 없고, 동기화(Load) 과정이 필요합니다.

// 1. 선언 (헤더 파일)
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Assets")
TSoftObjectPtr<UStaticMesh> MeshPtr;

// 2. 사용 (소스 파일)
// 현재 메모리에 로드되어 있는지 확인
if (MeshPtr.IsPending()) 
{
    // 방법 A: 동기 로드 (잠깐 멈춤 발생 가능)
    UStaticMesh* LoadedMesh = MeshPtr.LoadSynchronous();
}

// 이미 로드되어 있다면 Get()으로 바로 가져올 수 있음
UStaticMesh* Mesh = MeshPtr.Get(); 
if (Mesh)
{
    // 로직 수행
}

4. 언제 사용해야 할까요?

상황	추천하는 포인터
항상 사용되는 필수 컴포넌트 (예: 캐릭터의 Mesh)	TObjectPtr (Hard)
UI 아이콘, 특정 퀘스트에서만 나오는 NPC	TSoftObjectPtr (Soft)
수백 개의 아이템 데이터 시트	TSoftObjectPtr (Soft)
레벨에 배치된 다른 액터 참조	TSoftObjectPtr (Soft)

5. 요약하자면

TSoftObjectPtr은 "주소" 대신 "주소록(경로)"을 들고 있는 것과 같습니다. 주소록만으론 사람(객체)을 직접 만날 수 없지만, 필요할 때 전화를 걸어(Load) 불러낼 수 있는 것과 같은 원리입니다.

블루프린트의 Construction Script(CS) 노드와 SCS

지노윈 — Tue, 30 Dec 2025 14:01:57 +0900

1. SCS vs Construction Script (CS)

구분	SCS (Simple Construction Script)	Construction Script (블루프린트 노드)
정체	컴포넌트 구조의 데이터(설계도)	컴포넌트 생성 후 실행되는 로직(함수)
하는 일	"이 액터는 메쉬 1개, 라이트 1개가 있다"	"메쉬의 색상을 랜덤하게 바꾸고, 라이트 밝기를 조절해라"
실행 시점	액터 생성 직후, 컴포넌트 탄생 단계	SCS가 컴포넌트 조립을 마친 직후
편집 방법	컴포넌트 패널에서 마우스 드래그	그래프 에디터에서 노드 연결

2. 데이터의 흐름 (생성 순서)

액터가 월드에 배치되거나 스폰될 때, 데이터는 다음과 같은 순서로 흐릅니다.

SCS 단계 (정적 구성): 에디터에서 미리 붙여둔 컴포넌트들이 실제 메모리에 할당됩니다.
- 이때 변수들은 CDO에 저장된 기본값을 따릅니다.
변수 주입: Expose on Spawn으로 설정된 변수들이 이 시점에 들어옵니다.
Construction Script 단계 (동적 수정): 이제 막 생성된 컴포넌트들을 노드 로직을 통해 수정합니다.
- 예를 들어, "나의 팀 ID 변수가 1이면 메쉬를 빨간색으로, 2이면 파란색으로 바꿔라" 같은 로직이 여기서 돌아갑니다.

3. 런타임 컴포넌트 추가와의 차이점

게임 도중에 AddComponent 노드로 컴포넌트를 추가하는 것과 SCS의 차이점은 직렬화(Serialization)와 에디터 가시성입니다.

SCS/CS 컴포넌트: 에디터 뷰포트에서 즉시 보이며, 레벨을 저장할 때 해당 컴포넌트의 설정값도 함께 저장됩니다.
런타임 추가 컴포넌트: 게임이 실행된 후에만 존재하며, 에디터 상의 액터 데이터에는 포함되지 않습니다. (휘발성)

실무 팁: 최적화 주의사항

Construction Script는 에디터에서 액터를 살짝만 움직여도 매 프레임 재실행됩니다.

따라서 CS 노드 안에 무거운 계산이나 복잡한 루프를 넣으면 에디터가 매우 버벅이게 됩니다.
반면 SCS는 단순히 "데이터"를 나열한 것이므로 성능 부하가 거의 없습니다. 가능하면 시각적인 구조는 SCS(컴포넌트 패널)에서 잡는 것이 좋습니다.

Unreal Engine SCS(Simple Construction Script)

지노윈 — Tue, 30 Dec 2025 13:59:32 +0900

언리얼 엔진에서 SCS(Simple Construction Script)는 우리가 블루프린트 에디터의 '컴포넌트(Components)' 패널에서 컴포넌트를 추가하고, 계층 구조를 잡고, 설정을 변경하는 모든 시각적 작업을 코드로 관리하는 시스템입니다.

쉽게 말해, "블루프린트에서 마우스로 컴포넌트를 조립한 내역을 담고 있는 청사진"이라고 정의할 수 있습니다.

1. SCS의 핵심 역할

우리가 블루프린트 에디터에서 StaticMesh를 추가하고 SceneComponent 아래에 배치하면, 엔진 내부적으로는 다음과 같은 일이 일어납니다.

계층 구조 저장: 어떤 컴포넌트가 부모이고 자식인지에 대한 정보를 저장합니다.
프로퍼티 기록: 컴포넌트의 위치(Transform), 할당된 메쉬, 라이트 강도 등의 수정 사항을 기록합니다.
인스턴스화: 게임이 실행되거나 액터가 월드에 배치될 때, SCS에 기록된 정보를 바탕으로 실제 컴포넌트 객체들을 생성하고 부착합니다.

2. SCS와 C++의 관계

SCS는 주로 블루프린트에서 추가된 컴포넌트를 다룹니다. C++ 코드와 비교하면 이해가 빠릅니다.

C++ 방식: CreateDefaultSubobject<T>()를 호출하여 생성자에서 직접 컴포넌트를 만듭니다. 이 정보는 앞서 배운 CDO에 포함됩니다.
SCS 방식: 블루프린트 에디터에서 'Add Component' 버튼으로 추가합니다. 이 정보는 SCS라는 데이터 구조에 저장되었다가, 액터가 생성될 때 실행됩니다.

[!NOTE] 만약 C++ 클래스를 상속받은 블루프린트를 만들면, 해당 액터는 **[C++에서 만든 CDO의 컴포넌트] + [블루프린트 SCS에서 추가한 컴포넌트]**가 합쳐진 형태가 됩니다.

3. 액터 생성 시 동작 순서

액터가 생성될 때 컴포넌트들이 조립되는 과정은 대략 다음과 같습니다.

C++ 생성자 호출: C++에 정의된 기본 컴포넌트들이 먼저 생성됩니다.
SCS 실행: 블루프린트에서 추가한 컴포넌트들이 생성되고 계층 구조에 따라 부착(Attach)됩니다.
Construction Script 실행: 사용자가 블루프린트의 Construction Script 그래프에 짠 로직이 실행되며 최종 세팅을 마칩니다.

4. 왜 SCS라고 부르나요?

Simple: 복잡한 프로그래밍 없이 시각적인 도구로 구성할 수 있다는 의미입니다.
Construction: 액터가 "건설(생성)"되는 과정에서 필요한 설계도라는 의미입니다.
Script: 명령문처럼 차례대로 컴포넌트를 생성하고 설정하는 절차를 담고 있기 때문입니다.

요약하자면

SCS는 블루프린트 에디터에서 우리가 조립한 컴포넌트들의 설계도 정보이며, 이를 통해 엔진은 액터가 생성될 때마다 매번 똑같은 구조의 컴포넌트들을 자동으로 생성하고 붙여줄 수 있습니다.

Unreal Engine CDO 사용 방법

지노윈 — Tue, 30 Dec 2025 13:18:49 +0900

1. 코드에서 CDO에 접근하는 방법

실행 시간에 특정 클래스의 기본값을 가져오고 싶을 때, 액터를 스폰(SpawnActor)하지 않고도 아래의 함수들을 사용하여 CDO에 접근할 수 있습니다.

GetDefault<T>() 사용 (가장 권장됨)

템플릿 기반으로 작성되어 가독성이 좋고 안전합니다.

// AMyWeapon 클래스의 CDO에서 기본 데미지 값을 가져오기
AMyWeapon* DefaultWeapon = GetDefault<AMyWeapon>();
float Damage = DefaultWeapon->BaseDamage;

// 클래스 변수(UClass*)가 있을 때
UClass* WeaponClass = AMyWeapon::StaticClass();
const AMyWeapon* DefaultObj = GetDefault<AMyWeapon>(WeaponClass);

GetDefaultObject() 사용

UClass 포인터를 가지고 있을 때 유용하며, UObject 타입을 반환하므로 형변환이 필요합니다.

UClass* MyClass = AMyActor::StaticClass();
AMyActor* CDO = MyClass->GetDefaultObject<AMyActor>();

2. 생성자(Constructor)와 CDO의 관계

언리얼 엔진에서 생성자는 주로 CDO를 설정하기 위해 실행됩니다. 우리가 생성자 내부에 작성하는 코드들은 사실상 "이 클래스의 마스터 복사본(CDO)은 이렇게 생겨야 한다"라고 정의하는 과정입니다.

생성자에서 주로 하는 일

컴포넌트 생성: CreateDefaultSubobject를 사용하여 기본 컴포넌트 구조를 잡습니다.
기본값 할당: 변수의 초기값을 설정합니다.
에셋 레퍼런스 지정: FObjectFinder 등을 통해 기본 메쉬나 텍스처를 연결합니다.

AMyCharacter::AMyCharacter()
{
    // CDO에 포함될 기본 컴포넌트 생성
    MeshComponent = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("VisualMesh"));
    
    // CDO의 기본 변수값 설정
    MoveSpeed = 600.0f;
    bCanDoubleJump = false;
}

3. CDO 사용 시 주의할 점 (심화)

런타임 수정 금지

앞서 말씀드렸듯 CDO는 전역 마스터입니다. 만약 게임 도중에 GetDefault<AMyCharacter>()->MoveSpeed = 1000.0f; 처럼 값을 수정하면, 그 이후에 생성되는 모든 캐릭터의 기본 이동 속도가 1000으로 고정됩니다. (이것은 의도치 않은 버그의 원인이 됩니다.)

가비지 컬렉션 (GC)

CDO는 엔진이 켜져 있는 동안 절대 파괴되지 않습니다. 따라서 CDO가 참조하고 있는 에셋(메쉬, 텍스처 등)들도 게임 내내 메모리에 상주하게 됩니다. 생성자에서 너무 무거운 에셋을 너무 많이 참조하지 않도록 주의해야 하는 이유입니다.

로직 실행 자제

생성자는 엔진 초기화 단계(에디터 로딩 중 포함)에서 실행되므로, 월드에 접근하거나(GetWorld()), 다른 액터를 참조하는 등의 동적인 로직은 절대 생성자에 넣으면 안 됩니다. 그런 로직은 BeginPlay()에서 처리해야 합니다.

Unreal Engine CDO 사용 이유

지노윈 — Tue, 30 Dec 2025 13:14:50 +0900

언리얼 엔진에서 CDO(Class Default Object)는 클래스당 딱 하나씩 존재하는 '원본 마스터 객체'입니다. 엔진이 초기화될 때 각 클래스의 생성자를 호출하여 이 객체를 메모리에 미리 만들어 둡니다.

단순히 "기본값 저장소" 이상의 의미를 갖는데, CDO를 사용하는 핵심적인 이유 4가지는 다음과 같습니다.

1. 메모리와 성능 최적화 (Template Role)

새로운 액터나 오브젝트를 스폰할 때, 맨땅에서 모든 변수를 초기화하는 것은 비효율적입니다.

동작 방식: 엔진은 CDO라는 완성된 '복사본'을 미리 가지고 있다가, 새로운 인스턴스가 생성되면 CDO의 메모리 상태를 그대로 복사(Serialization)해서 넘겨줍니다.
이점: 복잡한 생성 로직을 매번 실행할 필요 없이 메모리 복사만으로 빠르게 객체를 생성할 수 있습니다.

2. 변수 기본값의 기준점 (Default values)

에디터의 디테일 패널(Details Panel)에서 우측의 '노란색 화살표(Reset to Default)' 버튼을 본 적이 있으실 겁니다.

기준점: 사용자가 수정한 값이 "기본값과 다른지" 판단할 때, 그 비교 대상이 바로 CDO입니다.
직렬화 최적화: 게임을 저장하거나 네트워크로 데이터를 보낼 때, 기본값(CDO 값)과 다른 변수만 골라서 저장/전송하면 되므로 데이터 크기를 획기적으로 줄일 수 있습니다.

3. 데이터 기반 프로그래밍 (Data-Driven Access)

객체를 실제로 월드에 배치(Spawn)하지 않고도, 그 클래스가 어떤 정보를 가지고 있는지 미리 알아야 할 때 사용합니다.

예시: 인벤토리 UI에서 아이템 아이콘을 표시해야 한다고 가정해 봅시다. 아이템 액터를 월드에 스폰하지 않고도, 아이템 클래스의 CDO에 접근하여 ItemIcon 변수값만 읽어올 수 있습니다.

코드 예시:

// 액터를 생성하지 않고 클래스 정보만으로 기본값 접근
AMyWeapon* DefaultWeapon = GetDefault<AMyWeapon>(MyWeaponClass);
float Power = DefaultWeapon->BaseDamage;

4. 리플렉션 및 에디터 통합

언리얼 엔진의 강력한 리플렉션(UProperty 등) 시스템은 CDO를 기반으로 작동합니다. 엔진은 CDO를 검사하여 이 클래스가 어떤 컴포넌트를 기본으로 가지는지, 어떤 기본 에셋을 참조하는지를 파악하고 이를 에디터 UI에 노출합니다.

주의사항: CDO는 '불변'이어야 합니다

CDO는 해당 클래스의 모든 인스턴스가 공유하는 원본입니다.

만약 런타임 중에 CDO의 값을 수정해버리면, 이후에 생성되는 해당 클래스의 모든 객체들이 바뀐 값을 가지고 태어나는 대참사가 발생할 수 있습니다.
따라서 CDO는 값을 읽기 전용(Read-only)으로 사용하는 것이 원칙입니다.

요약하자면

CDO는 클래스의 '설계도'와 '실제 객체' 사이의 가교 역할을 하며, "빠른 생성, 기본값 관리, 효율적인 데이터 접근"을 위해 존재합니다.

unreal engine assertion들 check, ensure, verify 등등...

지노윈 — Tue, 30 Dec 2025 11:38:52 +0900

1. check(조건)

가장 강력하고 엄격한 어설션입니다.

동작: 조건이 거짓이면 게임을 즉시 중단(Crash)시키고 로그를 남깁니다.
특징: Shipping 빌드(배포판)에서는 코드 자체가 삭제됩니다. 즉, 개발 단계에서만 동작하며 릴리즈된 게임의 성능에는 영향을 주지 않습니다.

사용 예시: "이 포인터는 여기서 절대 null일 수 없다"고 확신할 때 사용합니다.

check(MeshComponent != nullptr);
MeshComponent->SetVisibility(true); // 만약 null이었다면 위에서 이미 멈췄을 것

2. ensure(조건)

조금 더 유연한 어설션입니다.

동작: 조건이 거짓이면 콜스택(Call Stack)을 로그에 출력하지만, 게임은 멈추지 않고 계속 실행됩니다. (에디터에서는 한 번만 멈추고 디버거를 띄워줍니다.)
특징: check와 마찬가지로 Shipping 빌드에서는 제거됩니다.
사용 예시: "문제가 있긴 하지만, 당장 크래시를 낼 정도는 아닐 때" 또는 "문제를 인지만 하고 실행은 계속하고 싶을 때" 사용합니다. if문과 조합해서 자주 씁니다.
```
if (ensure(WeaponActor != nullptr))
{
    WeaponActor->Fire();
}
```

3. verify(조건)

check와 거의 동일하지만, 한 가지 결정적인 차이가 있습니다.

동작: 조건이 거짓이면 **즉시 중단(Crash)**됩니다.
특징: Shipping 빌드에서도 코드가 삭제되지 않고 실행됩니다. 단, Shipping 빌드에서는 "조건 검사"는 수행하지만 "실패 시 크래시" 기능은 비활성화됩니다.
사용 예시: 조건식 안에 실제 로직(함수 호출)이 포함되어 있을 때 사용합니다. check를 쓰면 릴리즈 시 함수 호출 자체가 사라져버리지만, verify는 함수를 실행해 줍니다.
```
// Shipping 빌드에서도 OpenDoor()는 실행되어야 함
verify(OpenDoor() == true); 
```

한눈에 비교하기

매크로	실패 시 결과	Shipping 빌드 포함 여부	용도
check	즉시 중단 (Crash)	제거됨	치명적인 오류 확인 (개발용)
ensure	로그 출력 후 계속 실행	제거됨	경고 및 비치명적 오류 확인
verify	즉시 중단 (Crash)	표현식은 유지됨	반환값이 있는 로직 확인

4. 기타 유용한 변형들

checkNoEntry(): 절대 도달해서는 안 되는 코드 경로에 둡니다. (예: switch문의 default 케이스)
checkf(조건, L"메시지"): 실패했을 때 사용자 정의 메시지를 로그에 함께 출력합니다. (check, ensure, verify 모두 뒤에 f를 붙인 버전이 존재합니다.)
unimplemented(): 아직 구현되지 않은 함수임을 표시하며, 호출 시 크래시를 발생시킵니다.

TObjectPtr를 사용하는 이유

지노윈 — Tue, 30 Dec 2025 11:04:51 +0900

언리얼 엔진 5(UE5)에서 도입된 TObjectPtr은 기존의 Raw Pointer(C++ 기본 포인터, 예: UObject*)를 대체하기 위해 설계된 엔진 전용 스마트 포인터 시스템입니다.

단순히 주소를 가리키는 것을 넘어, 에디터 환경과 메모리 관리 효율을 위해 도입되었습니다. 주요 사용 이유 4가지는 다음과 같습니다.

1. 지연 로딩 (Lazy Loading) 및 성능 최적화

가장 큰 기술적 이유는 에디터 빌드에서 오브젝트를 실제로 필요할 때까지 로드하지 않기 위해서입니다.

Raw Pointer: 포인터 변수가 선언되어 있으면 해당 오브젝트를 즉시 메모리에 올려야 할 때가 많습니다.
TObjectPtr: 에디터 환경에서 해당 객체가 실제로 접근(Access)되기 전까지는 로딩을 지연시키거나, 경로 정보만 가지고 있을 수 있습니다. 이는 특히 대규모 프로젝트에서 에디터 로딩 속도를 획기적으로 줄여줍니다.

2. 엔진 시스템과의 긴밀한 통합 (Access Tracking)

TObjectPtr은 단순한 주소값이 아니라 객체 접근을 추적할 수 있는 래퍼(Wrapper)입니다.

디버깅 및 통계: 어떤 오브젝트가 얼마나 자주 참조되는지, 언제 로드되는지 엔진이 모니터링하기 쉬워집니다.
가비지 컬렉션(GC): 엔진의 가비지 컬렉터가 객체를 더 효율적으로 식별하고 관리할 수 있도록 돕습니다.

3. 에디터에서의 안전성 및 유연성

에디터에서 블루프린트나 에셋을 수정할 때, TObjectPtr은 Optional하게 동작할 수 있는 구조를 제공합니다. 에셋의 주소가 바뀌거나 재로드되는 상황에서도 Raw Pointer보다 훨씬 유연하게 대응합니다.

4. 최신 표준 및 가시성 (Modernization)

UE5부터 엔진 소스 코드 전반에 적용되었으며, 프로그래머에게 이 변수가 "언리얼 오브젝트(UObject)를 가리키고 있으며, 엔진에 의해 관리되고 있음"을 명확히 알려줍니다.

핵심 차이점 요약

특징	*Raw Pointer (UObject)**	TObjectPtr<T>
권장 버전	UE4 이하	UE5 이상 필수 권장
로딩 방식	즉시 로딩 위주	에디터에서 지연 로딩 지원
안전성	수동 관리 요소 많음	엔진 시스템(GC, 에디터) 최적화
런타임 오버헤드	없음	거의 없음 (릴리즈 빌드에선 Raw Pointer로 컴파일됨)

[IMPORTANT]

실제 게임 배포(Shipping) 빌드에서는 TObjectPtr이 내부적으로 Raw Pointer와 동일하게 컴파일되도록 설계되어 있습니다. 따라서 런타임 성능 저하 없이 개발 단계의 이점만 챙길 수 있습니다.

사용 예시 (C++)

UPROPERTY(EditAnywhere, Category = "MyCategory")
TObjectPtr<UStaticMeshComponent> MeshComponent;

UPROPERTY(EditAnywhere, Category = "MyCategory")
TObjectPtr<UTexture2D> BackgroundTexture;