개요

언리얼 엔진에서 주로 쓰는 UPROPERTY 매크로에 대해서 알아보자

UPROPERTY

C++ 변수 선언 앞에 매크로를 지정할 수 있다. 어떤 변수에 이 매크로를 지정하게 되면 언리얼 엔진의 리플렉션 시스템에 등록되고 다음이 가능해진다

• 에디터에 노출되어 변수의 값을 볼 수 있고 편집이 가능
• 블루프린트 접근 가능
• 네트워크 복제 가능
• 가비지 컬렉션 대상이되어 메모리 자동 관리됨

빌드 시에 UHT이 매크로를 감지해 리플렉션 유형에 추가하게 된다

UPROPERTY([specifier, specifier, ...], [meta(key = value, key = value, ...)])
int32 variable;

Specifier

프로퍼티에 지정자를 통해 엔진과 에디터와 어떻게 상호작용하는지 지정할 수 있다

종류를 살펴보자.

• 에디터 관련
  • EditAnywhere : 에디터 모든 곳에서 수정이 가능
  • EditDefaultsOnly : 블루프린트 클래스 기본값에서만 수정 가능
  • EditInstanceOnly : 레벨에 배치된 인스턴스에서만 수정이 가능
  • EditFixedSize : 동적 배열 전용이며, 에디터에서 배열 길이를 바꾸지 못하도록 한다
  • EditInline : 다른 오브젝트를 참조할 때, 참조된 객체의 내부 속성을 에디터에서 직접 편집할 수 있게 해주는 지정자
    • 원래 이게 없으면 이 오브젝트 설정만 가능하지 내부 편집은 불가능
    • Instanced랑 같이 써야하고 참조 대상 클래스에 UCLASS(EditInlineNew)가 있어야 한다
  • VisibleAnywhere : 에디터에서 읽기만 가능
  • VisibleDefaultsOnly : 아키타입에 대한 프로퍼티 창에서 볼 수만 있음
  • VisibleInstanceOnly : 아키타입이 아닌 인스턴스에 대한 프로퍼티 창에서 볼 수만 있음
  • AdvancedDisplay : 디테일 패널의 Advanced 섹션에 들어간다
    • 
  • Category : 에디터에서 프로퍼티의 카테고리를 지정함. | 연산자를 통해 상위 카테고리 | 하위 카테고리 지정이 가능
  • NoClear : 에디터에서 이 오브젝트 레퍼런스를 none으로 설정하지 못하게 한다
  • NonTransactional : 이 프로퍼티를 변경 시 에디터의 되돌리기/다시하기 히스토리에 포함되지 않는다
• 블루프린트 관련
  • BlueprintReadOnly : 블루프린트에서 읽기만 가능
  • BlueprintReadWrite : 블루프린트에서 읽기 및 쓰기 모두 가능
  • BlueprintAssignable : 멀티캐스트 델리게이트하고만 사용이 가능하다. 프로퍼티를 블루프린트에서 할당할 수 있도록 노출한다
  • BlueprintAuthorityOnly : 이 프로퍼티는 멀티캐스트 델리게이트여야 한다. 블루프린트에서, BlueprintAuthorityOnly 지정자가 붙은 이벤트만 받는다
  • BlueprintCallable : 멀티캐스트 델리게이트 전용이며 프로퍼티를 노출시켜야 블루프린트 코드에서 호출이 가능
• 리플리케이션 관련
  • NotReplicated : 리플리케이션을 생략한다. 서비스 요청 함수의 구조체 멤버와 파라미터에만 적용됨
  • Replicated : 이 프로퍼티는 네트워크를 통해 리플리케이트된다
  • ReplicatedUsing=FunctionName : 프로퍼티가 업데이트될 때 실행되는 콜백 함수를 지정한다
• 그 외
  • AssetRegistrySearchable : 이 프로퍼티와 그 값이, 이것을 멤버 변수로 포함하는 클래스 인스턴스에 대한 애셋 레지스트리에 자동 추가됨을 나타낸다. 구조체 프로퍼티나 파라미터에 사용하는 것은 적합하지 않다
  • Config : 프로퍼티가 환경설정이 가능해짐. 현재 값이 클래스와 연결된 .ini 파일에 저장되며, 생성시 로드된다. 디폴트 프로퍼티에 값을 줄 수 없다
  • GlobalConfig : 위와 비슷하지만 서브클래스에서 덮어쓸 수 없다
  • DuplicateTransient : 이 프로퍼티를 복제할 때 클래스 기본 값으로 리셋시킬지를 나타낸다
  • Localized : 주로 스트링에 사용되며 현지화 값이 있다
  • Transient : 이 프로퍼티는 휘발성이라, 저장 또는 로드되지 않는다. 로드 시간에 0으로 채워짐
  • Instanced : 이 클래스의 인스턴스가 생성될 때, 이를 지정한 프로퍼티의 복사본도 새로 생성된다. 다른 객체가 같은 인스턴스를 참조하는 현상을 막을 수 있다
  • SaveGame : USaveGame을 상속한 클래스에서 저장할 데이터를 명시적으로 나타내는 용도로 사용된다

---

잘 이해가 가지 않는 키워드만 따로 정리해보자

AssetRegistrySearchable

이를 제대로 이해하려면 애셋 레지스트리(Asset Registry)에 대해 알고 있어야 할 것 같다

애셋 레지스트리는 프로젝트 내 모든 애셋의 메타데이터 정보를 관리하는 시스템이다

• 애셋을 로드하지 않고도 이름, 경로, 태그, 커스텀 메타데이터 등의 정보를 조회할 수 있다
• 툴 제작, 에디터 검색, 런타임 애셋 분류 등에 매우 유용함
• FAssetRegistryModule을 통해 코드에서 직접 접근하고 쿼리 가능

아직 직접 프로젝트에서 이를 사용해보지 못해 감이 안와서 자세한 내용은 나중에 다뤄보겠다

meta

매크로에서 프로퍼티나 함수에 추가적인 메타데이터를 제공할 수 있는 옵션이다. 매크로마다 지정자가 다양한데 UPROPERTY에서 사용하는 지정자를 알아보자

• ClampMin="", ClampMax=""
  • 프로퍼티에 입력할 수 있는 최솟값과 최댓값을 지정한다
• BindWidget
  • UMG의 위젯을 C++ 변수와 연결할 때 사용한다. 위젯과 변수 이름이 같아야 함
• BindWidgetOptional
  • 만약 위젯에서 프로퍼티와 같은 이름의 위젯이 없어도 컴파일 에러가 생기지 않음
• BindWidgetAnim
  • UMG 애니메이션을 C++와 연결하고 싶을 때 사용한다
• AllowPrivateAccess = "true/false"
  • private 변수를 블루프린트에서 읽고 싶을 때 사용
• EditCondition = "부울 변수"
  • 부울 변수의 값이 true일 때 프로퍼티를 보거나 수정할 수 있음
• DisplayName = ""
  • 에디터에서 보여지는 변수명
• DisplayThumbnail="true"
  • 프로퍼티가 애셋 타입이며 선택한 애셋의 썸네일을 표시할 때 사용
• DisplayPriority="N"
  • 프로퍼티의 정렬 순서를 결정한다
• ForceInlineRow
  • 프로퍼티를 같은 줄에 표시하고 싶을 때
• Tooltip = ""
  • 변수 설명을 추가한다