언리얼 리플렉션 시스템

리플렉션

• 런타임에 클래스, 변수, 함수의 타입 정보를 조회하고 조작할 수 있는 시스템
• 일반 C++는 컴파일 후 타입 정보가 사라지지만, 언리얼은 리플렉션으로 런타임에도 타입 정보 유지
• 메타데이터를 통해 "이 변수가 int형이다", "이 함수가 존재한다" 같은 정보를 프로그램 실행 중에 알 수 있음

---

에디터 연동

• 변수를 에디터의 Details 패널에서 보고 수정 가능
• 타입 정보가 있어야 에디터가 적절한 UI 제공 (int면 숫자 입력, bool이면 체크박스 등)
• UPROPERTY가 없으면 에디터에 표시되지 않음

저장/로드 자동화

• 게임 저장 시 "어떤 변수를 저장해야 하는지?" 자동으로 파악
• 리플렉션이 없으면 일일이 수동으로 저장 코드 작성 필요
• 맵 저장 시 액터의 모든 속성을 자동으로 직렬화

블루프린트 연동

• C++ 함수를 블루프린트에서 호출 가능
• C++ 변수를 블루프린트에서 접근 가능
• 블루프린트가 C++ 코드의 존재를 알 수 있는 기반

네트워크 복제

• 서버와 클라이언트 간 어떤 변수를 동기화할지 자동 판단
• UPROPERTY(Replicated)로 표시된 변수만 네트워크로 전송
• 복제 조건(OwnerOnly 등)도 리플렉션 메타데이터로 관리

가비지 컬렉션

• "이 객체가 어떤 다른 객체를 참조하는지?" 자동 추적
• UPROPERTY로 표시된 포인터만 GC가 추적
• 메모리 누수와 댕글링 포인터 방지

---

UPROPERTY

class AMyActor : public AActor
{
    GENERATED_BODY()
    
    // 에디터에서 편집 가능
    UPROPERTY(EditAnywhere)
    int32 Health;
    
    // 블루프린트에서 읽기/쓰기
    UPROPERTY(BlueprintReadWrite)
    float Speed;
    
    // 네트워크 복제
    UPROPERTY(Replicated)
    FVector Position;
};

주요 지정자:

• EditAnywhere: 에디터 어디서든 편집 가능
• EditDefaultsOnly: 블루프린트 기본값만 편집
• EditInstanceOnly: 배치된 인스턴스만 편집
• BlueprintReadWrite: 블루프린트에서 읽기/쓰기
• BlueprintReadOnly: 블루프린트에서 읽기만
• Replicated: 네트워크 복제
• ReplicatedUsing=함수명: 복제 시 OnRep 호출

UFUNCTION

class AMyActor : public AActor
{
    // 블루프린트에서 호출 가능
    UFUNCTION(BlueprintCallable)
    void TakeDamage(float Damage);
    
    // 블루프린트에서 구현 가능 (이벤트)
    UFUNCTION(BlueprintImplementableEvent)
    void OnDeath();
    
    // C++에서 기본 구현 + 블루프린트에서 오버라이드 가능
    UFUNCTION(BlueprintNativeEvent)
    void Attack();
    
    // 서버 RPC
    UFUNCTION(Server, Reliable)
    void ServerFire();
};

주요 지정자:

• BlueprintCallable: 블루프린트에서 호출 가능
• BlueprintPure: 블루프린트에서 순수 함수 (실행 핀 없음)
• BlueprintImplementableEvent: 블루프린트에서만 구현
• BlueprintNativeEvent: C++ 기본 구현 + 블루프린트 오버라이드
• Server/Client/NetMulticast: RPC 타입

UCLASS

UCLASS()
class MYGAME_API AMyActor : public AActor
{
    GENERATED_BODY()
    
public:
    AMyActor();
};

주요 지정자:

• Blueprintable: 블루프린트로 상속 가능
• BlueprintType: 블루프린트 변수 타입으로 사용 가능
• Abstract: 추상 클래스, 인스턴스 생성 불가
• NotBlueprintable: 블루프린트 상속 불가

GENERATED_BODY() 매크로

UCLASS()
class AMyActor : public AActor
{
    GENERATED_BODY()  // 리플렉션 코드 삽입
};

• 이 매크로가 리플렉션 메타데이터 코드를 삽입, 없으면 컴파일 에러

UHT (Unreal Header Tool)

• 컴파일 전에 먼저 실행되는 전처리기
• .h 파일을 스캔해서 UPROPERTY, UFUNCTION 등 매크로 탐색
• 자동으로 .generated.h 파일 생성
• 이 파일에 리플렉션 메타데이터 코드 포함
• 컴파일 시 .generated.h 파일도 함께 컴파일, 메타데이터가 바이너리에 포함됨

---

STL 컨테이너 사용 불가

• std::vector, std::map 같은 STL 컨테이너는 리플렉션 시스템이 인식 불가
• 템플릿이라 런타임 타입 정보 없음
• UHT가 내부 구조를 파악할 수 없음

---

매크로	대상	용도	예시
UPROPERTY	변수	변수 노출	UPROPERTY(EditAnywhere)
UFUNCTION	함수	함수 노출	UFUNCTION(BlueprintCallable)
UCLASS	클래스	클래스 등록	UCLASS()
USTRUCT	구조체	구조체 등록	USTRUCT(BlueprintType)
UENUM	열거형	열거형 노출	UENUM(BlueprintType)
GENERATED_BODY	클래스 내부	리플렉션 코드 삽입	필수 매크로