[Unreal C++] 리플렉션(Reflection) 시스템 완전 정리
🎨 C++과 블루프린트를 잇는 언리얼 리플렉션 시스템 완전 정복
리플렉션(Reflection) 시스템이란?
언리얼 엔진의 리플렉션 시스템(Reflection System) 은
C++ 코드와 언리얼 엔진의 다양한 시스템(에디터, 블루프린트, 직렬화, 네트워킹 등) 간의
상호작용을 가능하게 해주는 핵심 메커니즘이다.
즉, 런타임 또는 컴파일 타임에 객체의 속성과 메서드 정보를 동적으로 접근하고 조작할 수 있도록 도와준다.
이 시스템 덕분에 C++로 작성한 코드가 엔진의 다양한 기능과 유기적으로 연결된다.
리플렉션은 주로 UPROPERTY()와 UFUNCTION() 매크로를 통해 구현되며,
언리얼 헤더 툴(UHT, Unreal Header Tool) 이 이를 분석하여 필요한 리플렉션 코드를 생성한다.
UPROPERTY()
UPROPERTY()는 클래스의 멤버 변수를 언리얼 엔진 내부 시스템에 노출시키는 매크로이다.
즉, 에디터나 블루프린트에서 해당 변수를 조작할 수 있도록 연결해주는 역할을 한다.
주요 기능
- 에디터 노출: 디자이너나 개발자가 에디터에서 직접 값을 수정할 수 있음
- 블루프린트 통합: 블루프린트에서 접근하거나 수정 가능
- 자동 직렬화: 게임 데이터를 저장/불러올 때 자동으로 직렬화되어 저장
- 가비지 컬렉션(GC) 관리:
UPROPERTY로 선언된 포인터는 자동으로 참조 카운트 관리 - 메타데이터 지정:
EditAnywhere,BlueprintReadWrite등으로 편집 및 접근 권한 세부 제어 가능
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Movement")
float MoveSpeed;이 예시는 MoveSpeed 변수를 에디터에서 수정 가능하게 하고,
블루프린트에서도 읽기/쓰기 모두 가능하도록 설정한 예시다.
추가 세부 키워드 (참고: dlemrcnd.tistory.com/96)
변수 공개 & 수정 권한
VisibleDefaultsOnly: 인스펙터 창에서 보기만 가능VisibleInstanceOnly: 월드 배치에서만 보기 가능VisibleAnywhere: 둘 다 보기 가능EditDefaultsOnly: 에디터에서만 수정 가능EditInstanceOnly: 월드 배치에서만 수정 가능EditAnywhere: 둘 다 수정 가능
블루프린트 접근 권한
BlueprintReadOnly: 블루프린트에서 읽기만 가능BlueprintReadWrite: 블루프린트에서 읽기 & 쓰기 가능BlueprintGetter,BlueprintSetter: 특정 함수로 접근/수정 지정 가능
기타 옵션
Category: 디테일 패널의 그룹 이름 지정meta = (AllowPrivateAccess = "true"): private 변수라도 에디터에 노출 가능
UFUNCTION()
UFUNCTION()은 클래스의 멤버 함수를 언리얼 엔진이나 블루프린트에서 사용할 수 있도록 하는 매크로이다.
즉, 블루프린트에서 함수 호출 노드로 노출시키거나, 네트워크 동작에 활용할 수 있게 한다.
주요 기능
- 블루프린트 노출: 블루프린트 내에서 함수 호출 가능
- 네트워크 동작 정의:
Server,Client,NetMulticast등으로 네트워크 함수 지정 - 이벤트 바인딩: 특정 이벤트 발생 시 자동으로 호출되도록 설정 가능
- 메타데이터 제어: 함수의 동작 방식 및 접근성을 세밀하게 조정 가능
UFUNCTION(BlueprintCallable, Category = "Movement")
void MoveForward(float Value);이 예시는 블루프린트에서 MoveForward() 함수를 노드로 호출할 수 있도록 만든 예시이다.
추가 세부 키워드 (참고: dlemrcnd.tistory.com/96)
BlueprintCallable: C++ 함수를 블루프린트에서 사용 가능BlueprintPure: 반환값만 있고 상태 변경이 없는 함수에 적합UPARAM: 참조 인자를 블루프린트에 넘길 때 사용BlueprintImplementableEvent: C++에서 함수 원형만 선언하고, 블루프린트에서 구현BlueprintNativeEvent: C++에서 기본 구현 제공, 블루프린트에서 오버라이드 가능
리플렉션 시스템의 작동 원리
-
개발자가 C++ 코드에
UCLASS,UPROPERTY,UFUNCTION등을 작성한다. -
빌드 시 UHT(Unreal Header Tool) 이 코드를 스캔하고,
클래스와 속성, 함수 정보를 메타데이터 형태로 생성한다. -
엔진은 이 정보를 활용해:
- 에디터 노출
- 블루프린트 연결
- 직렬화 및 네트워킹
을 자동 처리한다.
C++ 코드 작성
↓
UHT가 코드 분석 및 메타데이터 생성
↓
엔진이 런타임에 정보 활용 (에디터, 블루프린트, 네트워킹 등)핵심 요약
| 항목 | 역할 |
|---|---|
UCLASS() | 클래스를 리플렉션 시스템에 등록 |
UPROPERTY() | 변수를 엔진 시스템에 노출 |
UFUNCTION() | 함수를 엔진 및 블루프린트에 노출 |
USTRUCT() | 구조체를 리플렉션 시스템에 등록 |
UENUM() | 열거형(enum)을 블루프린트/에디터에서 사용 가능하게 함 |
정리
UPROPERTY()와 UFUNCTION()은 단순한 코드 장식이 아니라,
언리얼 리플렉션 시스템의 핵심적인 연결 매개체이다.
이를 통해 개발자는 C++로 작성한 코드를 엔진 내부 기능과 자연스럽게 통합시켜
더 유연하고 효율적인 워크플로우를 구축할 수 있다.
📘 한 줄 요약
언리얼 리플렉션 시스템은 C++과 엔진 내부 시스템을 연결하는 "정보 노출 메커니즘"이며,
UPROPERTY()와UFUNCTION()은 그 핵심 도구이다.
