언리얼엔진 C++ 챕터1 - 5. C++ 클래스와 리플렉션 시스템 활용하기

리플렉션

언리얼 엔진의 리플렉션 시스템은 C++ 클래스의 변수 및 함수 정보를 엔진 내부의 메타데이터 형태로 저장하고, 이를 에디터나 블루프린트에서 활용할 수 있게 만들어주는 기술.

 

 

1. C++클래스를 리플렉션에 등록하기

 

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "Item.generated.h" // 반드시 마지막에 위치해야 합니다.

UCLASS()
class SPARTAPROJECT_API AItem : public AActor
{
		GENERATED_BODY()

 

 

•  #include "Item.generated.h" 
  • 언리얼 엔진이 자동 생성하는 헤더파일, 클래스의 리플렉션 및 엔진 통합에 필요한 코드가 들어 있다.
  • 반드시 헤더 파일의 가장 마지막 #include 구문 아래에 위치해야 한다.
•  UCLASS() 
  • 해당 클래스를 언리얼 엔진의 리플렉션 시스템에 등록한다는 의미.
  • 이 매크로가 있어야만 블루프린트 등 에디터 차원에서 이 클래스를 인식하고 사용할 수 있다.
•  GENERATED_BODY 
  • 언리얼의 코드 생성 도구가 사용하는 코드를 삽입하는 역할을 한다.
  • 클래스 내부에 필요한 리플렉션 정보를 자동으로 생성해준다.

 

1-1. UCLASS() 매크로의 주요 지정자

• UCLASS() 매크로는 클래스를 리플렉션 시스템에 등록하면서, 추가적으로 몇 가지 옵션(지정자)을 설정할 수 있다.
• 기본동작
  • 만약 UCLASS()에 옵션을 주지 않으면, 블루프린트에서 상속이 가능하고 변수로 참조가 가능한 형태로 등록된다.
• 주요 옵션
  •  Blueprintable 
    • 블루프린트에서 상속 가능한 클래스로 만든다.
  •  NotBlueprintable 
    • 블루프린트에서 이 클래스를 상속할 수 없도록 한다.
  •  BlueprintType 
    • 블루프린트에서 변수나 참조로 사용할 수 있게 한다.
    • 이 옵션만 있으면, 상속은 허용되지 않고 참조만 가능하다.
  • 필요에 따라 이 지정자들을 조합해 클래스가 어떻게 블루프린트와 상호작용해야 할지 명시할 수 있다.

 

2. 변수에 리플렉션 적용하기

 

2-1. UPROPERTY() 매크로의 주요 지정자

• UPROPERTY() 에는 여러 지정자를 작성해, 에디터에서의 표시 여부나 Blueprint 접근성, 읽기/쓰기 권한 등을 자세하게 설정할 수 있다. 아래는 자주 쓰이는 대표적인 지정자들이다.

1) 편집 가능 범위 지정자

•  VisibleAnywhere  : 읽기전용으로 표시되며, 수정은 불가능.
•  EditAnywhere  : 클래스 기본값, 인스턴스 모두에서 수정 가능.
•  EditDefaultsOnly  : 클래스 기본값에서만 수정 가능.
•  EditInstanceOnly  : 인스턴스에서만 수정 가능

2) Blueprint 접근성 지정자

•  BlueprintReadWrite  : Blueprint 그래프에서 Getter / Setter로 값을 읽거나 쓸 수 있다.
•  BlueprintReadOnly  : Blueprint 그래프에서 Getter 핀만 노출되어, 읽기만 가능하다.

3) Category 지정자

• Details 패널에서 이 변수는 "Rotation" 범주(폴더) 아래에 표시된다.
• 여러 변수를 비슷한 카테고리에 묶으면, 세부 정보 패널에서 깔끔하게 정리되어 보인다.
• 사용예시 ->  Category = "Item|Componenets"

4) 메타 옵션 지정자

• meta=(ClampMin="0.0") : 에디터에서 변수 입력 시 최소값을 제한할 수 있다.
• meta=(AllowPrivateAccess="true") : 해당 멤버가 private로 선언되어 있어도, 에디터나 Blueprint에서 접근할 수 있도록 허용한다.

만약 UPROPERTY() 만 있고, 추가 지정자를 하나도 주지 않는다면?

• 엔진 리플렉션 시스템에는 등록되지만, 에디터나 Blueprint에 노출되지는 않는다.
• "엔진이 변수의 존재를 알고 있지만, 외부에서는 보이지 않게 숨겨둔 상태"라고 볼 수 있다.
• 리플렉션에 등록만 되어 있어도 가비지 컬렉션(메모리관리)과 직렬화(세이브/로드) 같은 엔진 내부 기능이 작동할 수 있다.

 

3. 함수에 리플렉션 적용하기

:  UFUNCTION() 은 멤버 함수를 등록한다.

 

3-1.  UFUNCTION()  매크로의 주요 지정자

• Blueprint 관련 지정자
  • BlueprintCallable
    • Blueprint 이벤트 그래프(노드)에서 호출(Execute) 가능한 함수로 만든다.
  •  BlueprintPure 
    • Getter 역할만 수핸한다. (Exec 핀 없이 Return Value만 노출)
  •  BlueprintImplementableEvent 
    • 함수의 선언만 C++에 있고, 구현은 블루프린트에서 하도록 한다. C++ 코드에서는 함수 이름만 정의하고, 실제 동작은 Blueprint Event Graph 안에서 이벤트 노드처럼 구현된다.
• 만약  UFUNCTION() 에 지정자를 하나도 쓰지 않았다면?
  •  UPROPERTY() 와 마찬가지로, 함수가 언리얼 리플렉션에 등록되긴 하지만, 특별히 Blueprint에 노출되지는 않는다.
  • "엔진이 함수의 존재는 파악하되, Bluprint에서 직접 호출할 수 없게 숨겨둔 상태"라고 보면 된다.

 

* FVector::ZeroVector : (0,0,0)을 반환한다.