언리얼 리플렉션 매크로로 프로퍼티 설정하기(UPROPERTY, UFUNCTION)

언리얼 엔진 리플렉션 시스템(UE Reflection System)이란?

C++에서 지원하지 않는 리플렉션 기능을 언리얼 엔진 자체에서 구현한것으로,

매크로 선언을 통해 언리얼 에디터 자체에서 자신의 구조(변수, 함수 등)을 조사하여 에디터 내에 노출하거나 접근 및 수정이 가능하도록 하는 시스템이다.

 

줄이면, C++내 함수 또는 변수에 매크로를 선언하여 언리얼 에디터 내에서 노출 및 편집할 수 있도록 하는 시스템.

사용법

매크로 선언 방법

UPROPERTY, UFUNCTION매크로 사용예시.

UPROPERTY(Specifier1, Specifier2, meta = (MetaTag1 = "Value", MetaTag2 = "Value"))

UPROPERTY매크로는 위의 형태로 이루어지며, 지정된 설정은 바로 아래에 오는 변수 리플렉션에 적용된다.

지정자, 카테고리, 메타값을 정해진값 내에서 원하는대로 서설정이 가능하다.

주요 지정자(Specifier) 종류

UPROPERTY(변수)

Specifier 이름	설명
VisibleAnywhere	에디터에 표시됨(일반적으로 컴포넌트 포인터에 사용)
VisibleDefaultsOnly	클래스 디폴트에서만 보임
VisibleInstanceOnly	인스턴스에서만 변수값을 볼수 있음
EditAnywhere	아키타입(에셋, 클래스 디폴트)과 인스턴스 모두에서 수정 가능
EditDefaultsOnly	아키타입(에셋, 클래스 디폴트)에서만 수정 가능하지만 레벨 인스턴스에서는 편집 불가능
EditInstanceOnly	레벨에 배치된 인스턴스에서만 수정이 가능
BlueprintReadWrite	블루프린트에서 읽기/쓰기 허용 /  Get/Set 노드 모두 사용가능
BlueprintReadOnly	블루프린트에서 읽기만 허용 / Get노드 사용가능
BlueprintAssignable	이벤트 디스패쳐 델리게이트 전용, 델리게이트 이벤트에 변수를 바인딩
BlueprintImplementableEvent	이벤트 함수로 선언하여 블루프린트에서 사용가도록 한다. 선언은 C++에서, 구현은 블루프린트에서 진행되도록 한
BlueprintNativeEvent	이벤트를 C++ 에서 구현하는 방법. 이 경우 이벤트 함수의 이름 끝에는 "_Implementation"가 포함되어야 한다.

Visible~~지정자와 Edit~~~지정자는 수정 가능여부의 차이를 보이며 두가지를 동시에 사용하는것은 불가능하다.
예시로 VisibleAnywhere로 설정하고 EditInstanceOnly로 인스턴스에서만 설정하도록 하는 그런것이 불가능하다는 것이다.

그런상황을 만들고싶다면 메타값을 잘 활용하는 방법이 있다.

 

Blueprint~~ 지정자로 블루프린트에서 읽기 쓰기 여부를 선택 가능하다.

읽기/쓰기 여부 설정이 기본적이며, 이벤트 객체 변수일 경우 BlueprintAssignable를 사용한다

 

UFUNCTION(함수)

Specifier 이름	설명
BlueprintCallable	블루프린트 그래프에서 이 함수를 호출할 수 있는 노드로 나타낸.
BlueprintPure	실행 핀(하얀 화살표)이 없는 노드를 생성합니다. 값을 반환하기만 하고 객체의 상태를 변경하지 않는 함수(Getter 등)에 사용한다.
BlueprintImplementableEvent	C++에서 본체를 작성하지 않고, 블루프린트에서 로직을 구현하도록 한다
BlueprintNativeEvent	C++에서 기본 로직을 구현하고, 블루프린트에서 이를 오버라이드(재정의)할 수 있게 한다. 이 경우 이벤트 함수의 이름 끝에는 "_Implementation"가 포함되어야 한다
Server	클라이언트가 호출하지만 서버에서 실행되는 함수입니다.
Client	서버가 호출하지만 해당 액터를 소유한 클라이언트에서 실행되는 함수입니다.
NetMulticast	서버에서 호출되고 서버 및 연결된 모든 클라이언트에서 실행됩니다.
Reliable	RPC 전송의 신뢰성을 결정합니다. Reliable은 반드시 전송됨을 보장합니다.
Unreliable	RPC 전송의 신뢰성을 결정합니다. Reliable은 반드시 전송됨을 보장합니다.

서버관련은 필자가 사용해보지 않았지만 추가함.

 

카테고리 사용법

카테고리 사용법은 매우 간단하다.

Category="Category1|Category2" 이런식으로 사용이 가능하다.

버티컬 바  '|' 를 이용하여 위처럼 계층 구조를 나타낼 수 있다.

예시로 "Item|Components"가 되면 아래 사진처럼 계층구조가 된다.

왼쪽은 Item|Components, 오른쪽은 디테일 패널에서 Item/Components에서 Static Mesh Comp를 확인할 수 있다.

 

주요 메타 태그(Metadata Sepcifiers)

변수의 세밀한 설정을 담당한다.

주요한 몇가지만 살펴보자면

• AllowPrivateAccess = “true”: private 섹션에 선언된 변수를 블루프린트에 노출할 때 사용합니다.
• ClampMin / ClampMax: 숫자 변수의 입력 범위를 제한합니다.
• UIMin / UIMax: 상세 패널의 슬라이더 범위를 제한합니다 (직접 입력으로 범위 밖 값 입력 가능).
• DisplayName: 에디터에서 변수 이름 대신 보여줄 별칭을 지정합니다.
• EditCondition: 특정 bool 변수가 true일 때만 편집 가능하도록 활성화합니다.
• ToolTip: 에디터에서 변수에 마우스를 올렸을 때 나타나는 설명을 작성합니다.

예로 툴팁을 추가하고 싶다면 

meta = (ToolTip = "툴팁 설명란")

정도로 매크로 파라미터를 추가하고 괄호 내에서 여러개 설정이 가능하다.

 

 

UFUNCTION, UPROPERTY외에도 여러 매크로와 이에 맞는 메타데이터 지정자가 존재하니

자세한 매크로 파라미터값은 아래로

https://dev.epicgames.com/documentation/unreal-engine/metadata-specifiers-in-unreal-engine

Metadata Specifiers in Unreal Engine | Unreal Engine 5.7 Documentation | Epic Developer Community