1-3. Reflection 시스템 | UE5 GC Deep Dive

SECTION 01

UClass와 타입 시스템

UObject의 타입 정보를 담는 UClass의 구조

UClass 계층 구조

UClass는 모든 UObject 파생 클래스의 타입 정보를 담는 메타 클래스입니다. GC는 UClass의 프로퍼티 정보를 통해 객체 간 참조 관계를 자동으로 추적합니다.

                    클래스 계층
                    UObjectBase
  └── UObjectBaseUtility
       └── UObject
            └── UField (UE4, deprecated in UE5)
                 ├── UStruct
                 │    ├── UClass        ← 클래스 메타데이터
                 │    ├── UScriptStruct  ← USTRUCT 메타데이터
                 │    └── UFunction     ← UFUNCTION 메타데이터
                 └── UEnum             ← UENUM 메타데이터

// UE5에서는 FField 시스템으로 이전
FField
  └── FProperty              ← 프로퍼티 메타데이터 (UProperty 대체)
       ├── FObjectProperty    ← UObject* 참조 추적!
       ├── FObjectPtrProperty ← TObjectPtr 참조 추적
       ├── FWeakObjectProperty ← TWeakObjectPtr
       ├── FSoftObjectProperty ← TSoftObjectPtr
       ├── FArrayProperty     ← TArray 내부 추적
       ├── FMapProperty       ← TMap 내부 추적
       └── FStructProperty    ← 구조체 내부 추적
                

GC와 리플렉션의 핵심 관계

GC는 UPROPERTY()로 마킹된 프로퍼티만 추적합니다. 이는 리플렉션 시스템이 해당 프로퍼티의 FProperty 메타데이터를 생성하기 때문입니다. UPROPERTY가 없는 raw UObject*는 GC가 인식하지 못해 댕글링 포인터의 원인이 됩니다.

SECTION 02

FProperty와 GC 참조 추적

프로퍼티 시스템이 GC 참조를 자동으로 추적하는 원리

FProperty에서 FObjectProperty로

UE5에서 UProperty는 FProperty로 대체되었습니다. FProperty는 UObject가 아니므로 GC 대상이 아니며, 메모리 오버헤드가 줄었습니다. GC는 FObjectProperty 타입의 프로퍼티를 통해 UObject 참조를 추적합니다.

                    C++
                    // GC의 참조 추적 핵심 함수 (간략화)
void UClass::AssembleReferenceTokenStream()
{
    // 클래스의 모든 FProperty를 순회
    for (FProperty* Prop = PropertyLink; Prop; Prop = Prop->PropertyLinkNext)
    {
        // UObject 참조 프로퍼티인지 확인
        if (Prop->ContainsObjectReference())
        {
            // GC 토큰 스트림에 추가
            Prop->EmitReferenceInfo(*this, ReferenceTokenStream);
        }
    }
}

// GC 순회 시 토큰 스트림을 사용하여
// 객체 내부의 모든 UObject* 참조를 빠르게 수집
void ProcessObjectArray(FGCArrayStruct& ArrayStruct)
{
    for (auto& Token : ArrayStruct.ReferenceTokenStream)
    {
        UObject** ObjRef = Token.GetObjectRef(Object);
        if (*ObjRef)
            HandleObjectReference(*ObjRef);  // Reachable 마킹
    }
}
                

참조 토큰 스트림의 구조

토큰 타입	대상 프로퍼티	설명
`GCRT_Object`	`UObject*`	단일 객체 참조
`GCRT_ArrayObject`	`TArray<UObject*>`	배열 내 객체 참조들
`GCRT_ArrayStruct`	`TArray<FMyStruct>`	구조체 배열 내부 참조
`GCRT_ExternalPackage`	외부 패키지	패키지 간 참조
`GCRT_AddReferencedObjects`	커스텀	수동 참조 등록 콜백

SECTION 03

UFunction과 리플렉션 매크로

UCLASS, UPROPERTY, UFUNCTION 매크로의 GC 관련 역할

리플렉션 매크로와 UHT

Unreal Header Tool(UHT)은 리플렉션 매크로를 파싱하여 .generated.h와 .gen.cpp 파일을 생성합니다. 이 파일들에 GC가 사용하는 참조 토큰 스트림 구축 코드가 포함됩니다.

                    C++
                    // 원본 헤더
UCLASS()
class UMyObject : public UObject
{
    GENERATED_BODY()

    UPROPERTY()
    UObject* TrackedRef;      // GC가 추적함!

    UObject* UntrackedRef;     // GC가 모름! 위험!

    UPROPERTY()
    TArray<UObject*> TrackedArray;  // 배열 내부도 추적

    UPROPERTY()
    TMap<FName, UObject*> TrackedMap;  // 맵 Value도 추적

    UFUNCTION()
    void MyFunction();  // 함수 파라미터의 UObject*도 GC 고려
};

// UHT가 생성하는 코드 (MyObject.gen.cpp, 간략화)
void UMyObject::StaticRegisterNativesUMyObject()
{
    // 네이티브 함수 등록
}

const UECodeGen_Private::FObjectPropertyParams
    Z_Construct_UClass_UMyObject_Statics::NewProp_TrackedRef = {
        "TrackedRef",
        nullptr,  // RepNotifyFunc
        CPF_None,
        UECodeGen_Private::EPropertyGenFlags::Object,
        // ... offset, class 정보 등
    };
                

UPROPERTY() 없는 UObject* 참조의 위험

UPROPERTY() 매크로가 없는 UObject* 멤버 변수는 리플렉션 정보가 생성되지 않아 GC 토큰 스트림에 포함되지 않습니다. 결과적으로:

참조된 객체가 GC에 의해 수집될 수 있음 (댕글링 포인터)
해당 포인터 사용 시 크래시 발생 가능
디버깅이 매우 어려움 (간헐적 발생)

SECTION 04

USTRUCT와 중첩 참조 추적

구조체 내부의 UObject 참조를 GC가 추적하는 방법

USTRUCT 내부의 참조 추적

USTRUCT로 선언된 구조체 내부에 UPROPERTY로 마킹된 UObject*가 있으면, GC는 구조체를 포함하는 외부 객체의 토큰 스트림에 이를 포함시켜 추적합니다.

                    C++
                    USTRUCT()
struct FMyData
{
    GENERATED_BODY()

    UPROPERTY()
    UObject* InnerRef;  // 구조체 내부 참조도 추적됨

    UPROPERTY()
    TArray<UTexture2D*> Textures;  // 배열 내부도 추적
};

UCLASS()
class UMyContainer : public UObject
{
    GENERATED_BODY()

    UPROPERTY()
    FMyData Data;  // 구조체 자체가 UPROPERTY이면 내부 참조 추적

    UPROPERTY()
    TArray<FMyData> DataArray;  // 배열 내 구조체의 참조도 추적

    FMyData NoTrackData;  // UPROPERTY 없음 → 내부 참조 미추적!
};
                

중첩 추적의 조건

GC가 구조체 내부 참조를 추적하려면 세 가지 조건이 모두 충족되어야 합니다:

구조체가 USTRUCT()로 선언되어야 함
구조체 내부 멤버가 UPROPERTY()로 마킹되어야 함
외부 클래스에서 구조체 변수가 UPROPERTY()로 마킹되어야 함

SUMMARY

핵심 요약

이 강의에서 배운 내용

UClass는 FProperty 목록을 통해 GC 참조 토큰 스트림을 구축합니다
UE5에서 FProperty는 UObject가 아닌 경량 객체로, GC 오버헤드가 줄었습니다
UPROPERTY() 매크로가 없는 UObject* 참조는 GC가 추적하지 못해 댕글링 포인터의 원인이 됩니다
UHT는 리플렉션 매크로를 파싱하여 .gen.cpp에 GC 토큰 스트림 구축 코드를 생성합니다
USTRUCT 내부 참조 추적은 구조체와 멤버 모두 UPROPERTY()가 있어야 동작합니다

PRACTICE

도전 과제

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

실습 1: UPROPERTY 리플렉션으로 참조 탐색

UClass::ForEachProperty를 사용하여 특정 UObject 인스턴스의 모든 UPROPERTY 중 UObject* 타입인 프로퍼티를 찾아 참조 그래프를 출력하세요. FObjectPropertyBase를 활용하여 포인터 값을 읽어보세요.

실습 2: FProperty 메타데이터 분석

커스텀 UObject 클래스에 다양한 UPROPERTY 지정자(EditAnywhere, BlueprintReadWrite, Transient 등)를 적용하고, StaticClass()->PropertyLink를 순회하며 각 FProperty의 PropertyFlags를 분석하세요.

심화 과제: 리플렉션 기반 GC 참조 시각화

FReferenceChainSearch를 활용하여 특정 UObject에 대한 참조 체인을 추적하고, 결과를 구조화된 텍스트로 출력하는 디버그 유틸리티 함수를 작성하세요. obj refs 콘솔 명령어의 결과와 비교해보세요.