3-1. UPROPERTY 심화 | UE5 GC Deep Dive

SECTION 01

UPROPERTY 지정자 총정리

GC에 영향을 미치는 모든 프로퍼티 지정자

GC 관련 지정자

지정자	GC 영향	설명
`UPROPERTY()`	GC 추적	기본 - UObject* 참조를 GC가 추적
`Transient`	추적 유지	직렬화 제외, GC 추적은 유지
`DuplicateTransient`	추적 유지	복제 시 제외, GC 추적 유지
`SkipSerialization`	추적 유지	모든 직렬화 제외, GC 추적 유지
`TextExportTransient`	추적 유지	텍스트 내보내기 제외
`NonPIEDuplicateTransient`	추적 유지	PIE 복제 시에만 복사됨
`Instanced`	소유권 추적	참조가 인스턴스의 소유권을 가짐
`Export`	소유권 추적	Instanced와 동일 (컴포넌트용)

                    C++
                    UCLASS()
class UMyObject : public UObject
{
    GENERATED_BODY()

    // 기본: GC 추적 + 직렬화
    UPROPERTY()
    UObject* StandardRef;

    // GC 추적 O, 직렬화 X (캐시용)
    UPROPERTY(Transient)
    UTexture2D* CachedTexture;

    // 인스턴스 소유 (이 객체가 파괴되면 참조도 파괴)
    UPROPERTY(Instanced)
    UMySubObject* OwnedSubObject;

    // 에디터에서만 유효 (쿠킹 시 제거)
    UPROPERTY(Transient)
    UObject* EditorOnlyCache;
};
                

SECTION 02

Instanced와 소유권 의미론

UPROPERTY(Instanced)가 GC에 미치는 특별한 영향

Instanced 프로퍼티

Instanced 지정자는 해당 참조가 객체의 소유권을 가짐을 의미합니다. 소유 객체가 복제되면 Instanced 서브오브젝트도 함께 복제됩니다. GC 관점에서는 일반 참조와 동일하게 추적되지만, 직렬화와 복제 동작이 다릅니다.

                    C++
                    // Instanced 서브오브젝트 패턴
UCLASS(DefaultToInstanced, EditInlineNew)
class UAbilityData : public UObject
{
    GENERATED_BODY()

    UPROPERTY(EditAnywhere)
    float Damage = 10.f;

    UPROPERTY(EditAnywhere)
    float Cooldown = 1.0f;
};

UCLASS()
class AMyCharacter : public ACharacter
{
    GENERATED_BODY()

    // Instanced: 캐릭터가 소유하는 고유 인스턴스
    UPROPERTY(EditAnywhere, Instanced)
    UAbilityData* PrimaryAbility;

    // Instanced 배열: 각각 고유 인스턴스
    UPROPERTY(EditAnywhere, Instanced)
    TArray<UAbilityData*> Abilities;
};

// 캐릭터가 복제되면 → AbilityData도 자동 복제
// 캐릭터가 GC되면 → AbilityData도 GC 대상
                

DefaultToInstanced와 EditInlineNew

DefaultToInstanced는 이 클래스의 모든 UPROPERTY 참조를 자동으로 Instanced로 만듭니다. EditInlineNew는 에디터에서 인라인으로 새 인스턴스를 생성할 수 있게 합니다. 이 두 지정자를 함께 사용하면 에디터에서 서브오브젝트를 편리하게 관리할 수 있습니다.

SECTION 03

컨테이너 프로퍼티와 GC

TArray, TMap, TSet 내부의 UObject 참조 추적

컨테이너 내부 참조 추적 규칙

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

    // TArray<UObject*> - 모든 요소 GC 추적
    UPROPERTY()
    TArray<AActor*> ActorList;

    // TMap - Key와 Value 모두 추적 가능
    UPROPERTY()
    TMap<FName, UObject*> ObjectMap;

    // TMap<UObject*, UObject*> - 양쪽 모두 추적
    UPROPERTY()
    TMap<UObject*, UObject*> BothSidesTracked;

    // TSet<UObject*> - 모든 요소 추적
    UPROPERTY()
    TSet<UObject*> ObjectSet;

    // 중첩 컨테이너 - 내부까지 추적
    UPROPERTY()
    TArray<FMyStruct> StructArray;
    // FMyStruct 내 UPROPERTY UObject*도 추적됨

    // 위험: UPROPERTY 없는 컨테이너
    TArray<UObject*> DangerousArray;  // GC 미추적!
};
                

자주 하는 실수: 로컬 컨테이너

함수 로컬 변수로 선언된 TArray<UObject*>는 UPROPERTY가 아니므로 GC가 추적하지 않습니다. 만약 해당 함수 실행 중 GC가 발생하면(비동기 콜백 등), 컨테이너 내의 객체가 수집될 수 있습니다. 장시간 유지되는 로컬 컨테이너에는 FGCObject를 사용하거나, 멤버 변수로 승격시켜야 합니다.

SECTION 04

UPROPERTY 메타데이터와 GC 최적화

프로퍼티 메타데이터가 GC 효율에 미치는 영향

GC 토큰 스트림 최적화

UPROPERTY의 타입에 따라 GC 토큰 스트림의 크기와 복잡도가 달라집니다. UObject 참조가 없는 프로퍼티는 토큰 스트림에 포함되지 않으므로 GC 성능에 영향을 주지 않습니다.

                    C++
                    UCLASS()
class UHeavyObject : public UObject
{
    GENERATED_BODY()

    // GC 토큰 없음 (값 타입)
    UPROPERTY()
    int32 Health;           // 토큰 스트림 미포함

    UPROPERTY()
    FString Name;            // 토큰 스트림 미포함

    UPROPERTY()
    FVector Location;        // 토큰 스트림 미포함

    // GC 토큰 생성 (참조 타입)
    UPROPERTY()
    UObject* Ref1;           // GCRT_Object 토큰 1개

    UPROPERTY()
    TArray<UObject*> Refs;  // GCRT_ArrayObject 토큰 1개

    UPROPERTY()
    TMap<FName, UObject*> Map; // GCRT_Map 토큰
};

// 이 클래스의 GC 토큰 스트림 = 3개 토큰
// → GC가 이 객체를 처리할 때 3번만 검사
                

GC 효율 팁

UObject 참조를 많이 가진 클래스는 GC 비용이 높습니다. 대량의 참조를 관리해야 한다면:

참조를 구조체로 묶어 관리 (토큰 수 감소)
필요 시 TWeakObjectPtr 사용 (GC 추적 불필요)
가능하면 TSoftObjectPtr로 전환 (지연 로딩)

SUMMARY

핵심 요약

이 강의에서 배운 내용

Transient, SkipSerialization 등은 직렬화만 제어하며 GC 추적에는 영향 없습니다
Instanced 지정자는 소유권을 부여하여 복제와 직렬화 동작을 변경합니다
TArray, TMap, TSet의 UPROPERTY 컨테이너 내 UObject* 참조는 자동 추적됩니다
UPROPERTY가 없는 로컬 TArray<UObject*>는 GC가 추적하지 못해 위험합니다
값 타입 프로퍼티는 GC 토큰 스트림에 포함되지 않아 GC 비용이 없습니다

PRACTICE

도전 과제

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

실습 1: UPROPERTY 지정자별 GC 동작 테스트

하나의 UObject에 UPROPERTY(), UPROPERTY(Transient), raw pointer(UPROPERTY 없음), TObjectPtr 프로퍼티를 각각 만들고, 참조 대상 객체의 GC 수집 여부를 테스트하세요. UPROPERTY 없는 raw pointer가 dangling 되는 상황을 재현하세요.

실습 2: TObjectPtr vs raw UObject* 마이그레이션

기존 코드에서 UObject* raw pointer를 사용하는 클래스를 TObjectPtr로 마이그레이션하세요. Access Tracking과 Lazy Load 동작의 차이를 디버그 로그로 확인하고, 마이그레이션 전후 동작이 동일한지 검증하세요.

심화 과제: UPROPERTY 메모리 레이아웃 분석

FProperty::GetOffset_ForInternal()을 사용하여 클래스 내 UPROPERTY들의 메모리 레이아웃을 분석하세요. 프로퍼티 순서, 패딩, 오프셋을 시각화하고, GC가 토큰 스트림으로 참조를 스캔하는 과정을 이해하는 문서를 작성하세요.