[언리얼] UPROPERTY(), UFUNCTION() 리플렉션이란? 메타데이터란?

언리얼 엔진의 리플렉션 기능 이해하기

언리얼 엔진은 강력한 게임 개발 플랫폼으로, 다양한 기능을 제공하여 개발자들이 직관적이면서도 고성능 게임을 만들 수 있도록 지원한다. 그중에서도 리플렉션(Reflection) 기능은 엔진 내부에서 객체의 속성과 메서드를 동적으로 다룰 수 있도록 해주는 핵심 기능 중 하나이다.

리플렉션이란 무엇인가 ?

리플렉션은 코드가 런타임에 객체의 메타데이터를 검사하거나 수정할 수 있도록 하는 프로그래밍 기법이다. 언리얼 엔진에서는 이 기능을 활용하여 객체를 직렬화하거나, 에디터에서 노출하여 사용자가 직접 수정할 수 있도록 한다. 또한 블루프린트와 네트워크 동기화에도 필수적인 역할을 한다.

언리얼 엔진에서의 리플렉션 활용

언리얼 엔진은 C++ 기반으로 작동하지만, 블루프린트와의 상호 운용성을 위해 리플렉션 시스템을 적극 활용한다. 이를 통해 C++에서 정의된 클래스와 속성을 블루프린트 에디터에서 바로 활용할 수 있으며, 이를 가능하게 해주는 주요 매크로가 바로 UCLASS, USTRUCT, UENUM, UFUNCTION, UPROPERTY 등이다.

 

UCLASS 매크로

UCLASS 매크로는 언리얼 엔진의 객체 시스템을 지원하기 위해 클래스 선언부에 사용된다. 이 매크로는 클래스가 엔진에서 인식되고 관리될 수 있도록 한다.

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

위 코드에서 UCLASS() 매크로는 AMyActor 클래스가 엔진의 리플렉션 시스템과 상호작용할 수 있도록 만들어준다. 또한 GENERATED_BODY() 매크로는 클래스 내부에 필요한 메타데이터와 함수 테이블을 자동으로 생성해 준다.

UPROPERTY 매크로

UPROPERTY는 객체의 속성을 엔진 에디터나 블루프린트에서 제어할 수 있도록 하는 매크로이다. 이를 통해 게임 데이터를 직렬화하거나, 네트워크를 통해 동기화할 수 있다.

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Health")
float Health; 

이와 같이 선언하면, 해당 속성은 블루프린트에서도 접근이 가능하며, 에디터에서 값 조정이 가능하다.

UFUNCTION 매크로

UFUNCTION은 C++ 함수를 블루프린트에서 호출할 수 있도록 만든다. 함수가 블루프린트에 노출될 수 있으며, 리플렉션 시스템을 통해 런타임에 호출할 수도 있다.

UFUNCTION(BlueprintCallable, Category = "Damage")
void ApplyDamage(float DamageAmount); 

이 함수는 블루프린트 노드로 나타나며, 다양한 상황에서 호출될 수 있다.

 

컴파일 과정에서의 리플렉션 처리

언리얼 엔진에서 리플렉션 기능을 활용하려면, 컴파일 단계에서 메타데이터를 수집하고 이를 코드로 변환하는 과정이 필요하다. 이 과정은 UHT(Unreal Header Tool) 이 담당하며, 다음과 같은 순서로 진행된다.

1. 코드 분석 및 파싱 : 소스 코드에서 UCLASS, UPROPERTY, UFUNCTION 등과 같은 매크로를 탐지하고 이를 파싱한다.
2. 메타데이터 생성 : 파싱 결과를 기반으로 클래스, 속성, 함수 등의 메타데이터를 생성한다.
3. 자동 코드 생성 : 메타데이터를 사용하여 각 클래스에 대해 별도의 헤더 파일(.generated. h)을 생성한다. 이 파일은 객체 지향 구조를 관리하는 데 필요한 코드와 메타데이터를 포함한다.
4. 컴파일 : 생성된 코드와 기존 소스 코드가 함께 컴파일되어 최종 바이너리가 만들어진다.

이러한 컴파일 과정 덕분에 런타임 시에 클래스 정보를 동적으로 조회할 수 있으며, 에디터에서 속성을 직접 노출하거나 블루프린트에서 접근할 수 있다.

 

---

메타데이터란 ?

**메타데이터(Metadata) * *란 데이터를 설명하는 데이터이다. 쉽게 말해, 데이터에 대한 정보를 담고 있는 데이터라고 할 수 있다.
언리얼 엔진의 리플렉션 시스템에서 메타데이터는 클래스, 속성, 메서드 등에 관한 정보를 의미한다. 이러한 메타데이터를 통해 엔진은 런타임에 객체의 속성이나 메서드 정보를 동적으로 탐색하거나 수정할 수 있다.

 

. cpp

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Character")
float Health; 

 

이 속성은 다음과 같은 메타데이터를 가진다 :

• EditAnywhere : 에디터에서 수정 가능
• BlueprintReadWrite : 블루프린트에서 읽기/쓰기 가능
• Category = "Character" : 에디터에서 "Character" 카테고리로 그룹화

---

리플렉션 시스템의 장점

1. 동적 속성 접근 : 런타임에 객체 속성이나 메서드에 접근할 수 있어 직렬화 및 디버깅에 유리하다.
2. 블루프린트와의 강력한 통합 : C++로 작성한 기능을 블루프린트에서 재사용할 수 있어 생산성이 높아진다.
3. 에디터 기능 확장 : 객체 속성을 에디터에서 직접 수정할 수 있어 데이터 관리가 용이하다.
4. 네트워크 지원 : 속성 동기화 및 함수 호출이 가능하여 멀티플레이어 환경에서 유리하다.

리플렉션 시스템의 단점

1. 컴파일 속도 저하 : 메타데이터를 생성하는 과정에서 코드 파싱과 자동 파일 생성이 필요하여 빌드 시간이 길어진다.
2. 코드 복잡성 증가 : 자동 생성 코드와 실제 소스 코드가 분리되어 있어 디버깅이 어려울 수 있다.
3. 메모리 사용 증가 : 메타데이터와 관련된 추가 메모리 사용으로 인해 메모리 효율성이 떨어질 수 있다.
4. 퍼포먼스 문제 : 런타임에 동적으로 속성이나 메서드에 접근할 때 성능 저하가 발생할 수 있다.

리플렉션 시스템은 언리얼 엔진의 강력한 기능 중 하나이지만, 이러한 단점들을 고려하여 성능과 개발 편의성 사이에서 균형을 맞추는 것이 중요하다.

 

리플렉션 시스템을 사용하지 않는 경우

리플렉션 시스템은 동적 속성 접근이나 블루프린트 연동에 유리하지만, 모든 경우에 적합한 것은 아니다. 성능과 메모리 사용을 최적화해야 하는 특정 상황에서는 리플렉션을 사용하지 않는 것이 더 바람직하다. 다음과 같은 경우에는 리플렉션을 사용하지 않는 것이 좋다.

1. 성능이 중요한 실시간 처리 코드 : 런타임에 리플렉션을 통해 메타데이터를 조회하는 과정은 성능 저하를 유발할 수 있다. 특히 프레임당 호출이 빈번한 게임 루프 코드에서는 치명적일 수 있다.
2. 간단한 데이터 구조 : 복잡한 데이터 직렬화가 필요 없는 경우, 단순히 변수나 구조체로 데이터를 관리하는 것이 더 효율적이다.
3. 고정된 기능이나 속성 : 미리 정의된 속성이나 메서드를 사용하여 구조가 고정되어 있는 경우 리플렉션이 불필요하다.
4. 네트워크 최적화 : 네트워크 패킷 전송 시 메타데이터까지 포함하면 데이터 전송량이 증가할 수 있어 직접 직렬화를 구현하는 것이 더 적합하다.
5. 컴파일 시간 최적화 : 빌드 속도가 중요한 프로젝트에서는 리플렉션 시스템으로 인해 발생하는 UHT 단계의 컴파일 지연을 피하고자 매크로 사용을 최소화할 수 있다.

 

결론 및 요약

언리얼 엔진의 리플렉션 시스템은 객체 지향 프로그래밍을 보다 유연하게 다룰 수 있도록 돕는다. 블루프린트와 C++ 코드 간의 상호 운용성을 제공하며, 에디터와 네트워크 동기화에도 필수적이다. 아래 표는 주요 매크로와 그 역할을 요약한 것이다.

매크로	역할	사용 예시
UCLASS	클래스 메타데이터 관리	UCLASS()
UPROPERTY	객체 속성의 직렬화 및 에디터 노출	UPROPERTY(EditAnywhere, BlueprintReadWrite)
UFUNCTION	블루프린트 함수 호출 지원	UFUNCTION(BlueprintCallable)
USTRUCT	구조체를 엔진에서 인식 가능하게 함	USTRUCT(BlueprintType)
UENUM	열거형을 블루프린트와 C++에서 공용으로 사용	UENUM(BlueprintType)

 

이와 같이 언리얼 엔진의 리플렉션 기능을 이해하고 적절히 활용하면, 개발 과정에서 더 효율적이고 유연한 코드 작성이 가능하다.