언리얼엔진5 C++로 정복하기(18) UPROPERTY, UFUNCTION 매크로/GC 정리

일단.. C++로 코드를 짜다보면 헤더파일에 변수들에 UPROPERTY, 함수들에 UFUNCTION이 굉장히 많이 붙는다.
 
이참에 한번 알아보고 정리해보자 하고 생각해서 정리를 해본다.
 
1. UPROPERTY 기본 구조

 
옵션: 리플렉션, 에디터/블루프린트 접근 제어 등이 있고
meta: 에디터 UI, 블루프린트 표시 방식 제어 등이 있다.
 
2. UPROPERTY 옵션 정리

@Edit 계열

 
EditAnyWhere : 에디터 어디서든 수정 가능
EditDefaultOnly : BP 기본값에서만 수정 가능 (인스턴스 불가)
EditInstanceOnly : 레벨에 배치된 인스턴스에서만 수정 가능

@Visible 계열

 
VisibleAnywhere: 어디서나 보이지만 수정 불가
VisibleDefaultsOnly: BP 기본값에서만 보임
VisibleInstanceOnly: 인스턴스에서만 보임
 
컴포넌트 포인터는 거의 Visible만 사용 예(USkeletalMeshCompoennt*)

@Blueprint 접근 제어

 
BlueprintReadOnly:  BP에서 읽기만 가능
BlueprintReadWrite:  BP에서 읽기/쓰기 가능
 
상태값(HP, IsDead 등) ->  ReadOnly
설정값(Speed, Damage) -> ReadWrite

@Category (정리용)

| : |로 하위카테고리 생성 (에디터 디테일 패널에서 폴더처럼 정리된다)

@Replication 관련

Replicated: 단순 동기화
ReplicatedUsing: 값 변경 시 함수 호출
OnRep: UI 갱신 및 이펙트 트리

@저장 관련

SaveGame: 세이브 시스템에 저장하고 싶을 때
Config, GlobalConfig: INI 설정 파일로 빼고 싶을 때
Transient: 저장/로드 대상 아님 (런타임 임시값)
 
3. 가비지 컬렉션 GC
 

@GC 관련 설명

GC에 대해 알아보자.
언리얼엔진은 자체 GC(가비지 컬렉션)를 사용한다.
UObject / AActor 는 new / delete로 관리를 안한다.
엔진이 누가 이 객체를 참조 중인지를 추적해서 아무도 안 쓰면 자동으로 지운다.
그래서 엔진은 이 포인터가 UPROPERTY로 등록되어 있나? 하고 돼있으면 살아있는 참조라고 생각한다.
 
여기서 AActor* TargetActor와 TObjectPtr<AActor> TargetActor의 차이점을 알아보자
 
3-1  AActor* TargetActor
 
의미: C++의 일반 포인터
UPROPERTY가 붙어 있으므로 GC가 추적이 가능하며 에디터/블루프린트/복제 시스템에 참여가 가능하다.
장점: 문법이 단순하며 UE4부터 쓰던 방식이다.
단점: 정적 분석(컴파일 타임 검증)이 약하고
미래 GC/메모리 시스템 변화에 취약하다.
 
3-2  TObjectPtr<T> TargetActor
 
TObjectPtr<T> 는 이 포인터는 UObject 계열이다를 타입 자체로 명확하게 표시하는 래퍼이다.
엔진에서 이건 UObject 참조라고 정확히 판단하며 GC/에디터/복제 다 정확히 처리해도 된다고 이해한다.
 
실제 사용법은 둘다 거의 동일하지만 엔진 내부에서는 포인터 접근시 체크하고, 로딩/언로드/리디렉션 처리와 메모리 이동 대비가 더 좋다. UE5에서는 TObjectPtr을 더 선호한다.
https://dev.epicgames.com/documentation/ko-kr/unreal-engine/unreal-engine-5-migration-guide?application_version=5.0

새로운 기능 | 언리얼 엔진 5.7 문서 | Epic Developer Community

--언리얼엔진5 공식문서--
 

@Delegates, AdvancedDisplay

 
만약 BlueprintAssignable을 쓸려면 Dynamic_Multicast_Delegate 여야한다. 
BlueprintAssignable: BP에서 이벤트 바인딩 가능(버튼처럼)(디테일 패널에 +버튼 생김)
AdvancedDisplay: Detail 패널에서 Advanced에 숨김
 
4. meta

@meta

ClampMin / ClampMax: 값 자체를 강제로 제한(초과 범위 입력시에 잘려들어감)
UIMin / UIMax: 슬라이더로 제한 (직접 입력은 가능)
EditCondition / EditConditionHides: EditCondition일때 bisDead가 true일때만 편집가능
EditConditionHides는 false면 아예 숨겨버림

@meta#2

DisplayName, ToolTip: 표시이름 설명 및 가독성
ExposeOnSpawn: 블루프린트에서 SpawnActor 할때 바로 꽂아서 생성이 가능하다.
MultiLine: 여러 줄 입력할때 사용
AllowedClasses: 에디터에서 파일/에셋을 고르기 편하게 (특정 클래스만 선택되게 제한)
MakeEditWidget: fvector 같은 값을 월드에서 핸들로 수정이 가능하게
TitleProperty: 배열이 길어질 때 어떤 요소인지 표시를 해준다.
AllowPrivateAccess: private도 블루프린트에 노출이 가능하게 해준다.
 
5. UFUNCTION
*함수를 블루프린트 노드로 만들거나 네트워크 RPC로 만들거나 에디터에서 버튼으로 실행할지 결장할때 많이 사용한다.

@블루프린트에서도 호출 가능한 함수

BlueprintCallable: BP에서 실행 노드로 호출 가능
BlueprintPure: 실행 핀이 없는 값 가져오기 전용 (Getter), 상태 변경 금지!
BlueprintImplementableEvent: C++에서는 구현없이 선언만, BP에서 이벤트 그래프로 구현
BlueprintNativeEvent: C++에서도 기본 구현도 가능하고 BP에서 오버라이드 가능
 
6. 네트워크 RPC

@Server, Client, NetMulticast RPC

Server: 클라이언트가 서버에게 요청할 때
Client: 서버가 특정 클라이언트에게만 요청할 때
NetMulticast: 서버가 모두에게 브로드 캐스트
Reliable / Unreliable: Reliable : 반드시 전달해야함, Unreliable: 가끔 누락되도 된다!
 

@UFUNCTION meta

CallInEditor: 에디터에서 버튼처럼 실행 (Details 패널에 버튼이 생긴다)
BlueprintCallable, Category...meta=(DisplayName)...: 노드 표시 이름 및 카테고리
ExpandEnumAsExecs: BP에서 Switch처럼 편해짐(실행핀으로 enum을 쪼갬)
AutoCreateRefTerm: 참조 파라미터를 BP에서 편하게 한다.
 
더 추가할 것이 있다면 댓글로 부탁드리겠습니다.