Unreal Engine 5 UPROPERTY

Unreal Engine 5의 UPROPERTY 매크로에 사용할 수 있는 모든 속성값(지정자, Meta Specifiers) 및 그 상세 설명을 정리했습니다. 기본 지정자, 네트워크 및 복제 관련, 고급 관리 지정자 등이 있습니다.

기본 지정자 (Access & Blueprint)

EditAnywhere: 에디터에서 변수의 값을 직접 읽고 쓸 수 있으며, 코드에서도 자유롭게 접근 가능.
EditDefaultsOnly: 클래스 기본값 설정에서만 읽기/쓰기 가능, 인스턴스에서는 변경 불가.
EditInstanceOnly: 인스턴스에서만 편집 가능, 클래스 기본값(아키타입)에서는 변경 불가.
VisibleAnywhere: 에디터에서 읽기 전용으로 표시, 코드에서는 접근 가능.
VisibleInstanceOnly: 인스턴스에서만 읽기 전용 표시, 코드에서 접근 가능.
VisibleDefaultsOnly: 아키타입에서만 읽기 전용 표시, 코드에서 접근 가능.
BlueprintReadOnly: 블루프린트에서 읽기만 가능.
BlueprintReadWrite: 블루프린트에서 읽기/쓰기 모두 가능.

네트워크 및 복제 관련

Replicated: 네트워크(서버→클라이언트)로 값이 복제됨.
ReplicatedUsing=함수명: 복제될 때 지정된 함수가 호출됨.
NotReplicated: 값이 네트워크로 복제되지 않음.
RepRetry: 복제가 실패하면 재시도하도록 지정됨.

고급 관리 지정자

Transient: 일시적 데이터, 저장되지 않고 세션 동안만 유지.
DuplicateTransient: 복제(복사 등)할 때 값이 복제되지 않음.
NonPIEDuplicateTransient: 에디터의 PIE(Play In Editor)에서만 복제되지 않음.
SaveGame: UPROPERTY가 게임 세이브 시스템에서 저장 및 로딩됨.

에디터 관련 Meta Specifiers

Category: 에디터에서 변수를 그룹화하여 관리할 때 사용.
DisplayName: 변수의 에디터 및 블루프린트 표시 이름 지정.
ToolTip: 변수에 대한 설명 툴팁 제공.
ClampMin / ClampMax: 값의 최소/최대 제한 지정.
EditCondition: 특정 조건이 참일 때만 변수 수정 가능, bool 혹은 식 사용.
AdvancedDisplay: 에디터의 ‘Advanced’ 항목 아래에 변수를 숨김 처리.
SimpleDisplay: 기본적으로 Details 패널에 표시됨.
HideAlphaChannel: FColor, FLinearColor에서 Alpha 채널 숨김.
MultiLine: 문자열(FString, FText)에 대해 멀티라인 입력 허용.

기타 주요 지정자

Config: 변수 값이 ini 파일에 저장되어 불러와짐.
GlobalConfig: 베이스 클래스의 ini 파일에서 값을 불러옴.
Interp: 에디터에서 사용자 셋팅값으로 사용 가능.
NonTransactional: 에디터의 되돌리기(Undo/Redo)에 포함되지 않음.
Instanced: 오브젝트 변수에 대해 인스턴스화 및 에디터에서 편집 가능.
BlueprintAssignable: Delegate에 사용. 블루프린트에서 이벤트 할당 가능.
Export: 오브젝트를 Export할 때 함께 Export됨.
AssetRegistrySearchable: 자산 레지스트리에서 검색 대상이 됨.

대표 예시 코드

cpp
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Character Stats", meta=(ClampMin="0.0", ClampMax="100.0"))
float Health;

UPROPERTY(EditAnywhere, Category="Settings", meta=(DisplayName="Player Speed", ToolTip="The speed at which the player moves."))
float PlayerSpeed;

UPROPERTY(EditAnywhere, AdvancedDisplay, Category="Character Stats")
float HiddenInAdvanced;

UPROPERTY(ReplicatedUsing=OnRep_Health)
int32 ReplicatedHealth;

protected:
UPROPERTY(VisibleAnywhere, Category="Character Stats")
int32 ProtectedVariable;

private:
UPROPERTY()
int32 PrivateVariable;

추가적으로 많이 쓰는 Meta Specifiers

ArrayClamp: 배열의 인덱스 값 조절 시 사용.
AllowAbstract/AllowedClasses: 특정 클래스 종류만 에셋 선택기에서 표시.
ExposeOnSpawn: SpawnActor에서 값 노출.
MakeEditWidget: FVector 등 공간에서 편집 위젯 생성.
UIMin/UIMax: 슬라이더 범위 지정.
Multiple: 숫자 값이 특정 값의 배수만 입력되도록 제한.

아래는 Unreal Engine 5에서 사용되는 UPROPERTY 지정자 전체 목록과 각 지정자의 용도입니다.

가시성 및 편집 지정자

지정자	용도 및 설명
EditAnywhere	모든 에디터에서 값 편집 가능.
EditDefaultsOnly	클래스 기본값(아키타입)만 편집 가능, 인스턴스에서는 불가.
EditInstanceOnly	인스턴스에서만 편집 가능, 클래스 기본값에서는 불가.
VisibleAnywhere	에디터에서 읽기 전용 표시, 코드에서는 접근 가능.
VisibleDefaultsOnly	클래스 기본값(아키타입)에서만 읽기 전용 표시, 편집 불가.
VisibleInstanceOnly	인스턴스에서만 읽기 전용 표시.

블루프린트 및 델리게이트 지정자

지정자	용도 및 설명
BlueprintReadWrite	블루프린트에서 값 읽고 쓸 수 있음.
BlueprintReadOnly	블루프린트에서 읽기만 가능.
BlueprintAssignable	멀티캐스트 델리게이트에만 사용, 블루프린트에서 할당 가능.
BlueprintAuthorityOnly	서버 권한만 부여, 클라이언트 블루프린트에서는 접근 불가.
BlueprintCallable	블루프린트에서 함수로 호출 가능(멤버 함수 전용).
BlueprintGetter	Getter 커스텀 함수 연결.
BlueprintSetter	Setter 커스텀 함수 연결.

네트워크 및 복제 지정자

지정자	용도 및 설명
Replicated	네트워크상에서 리플리케이트 가능.
ReplicatedUsing=함수명	값을 복제할 때 지정한 함수가 자동 호출됨.

저장, 일시적 데이터 및 기타 관리

지정자	용도 및 설명
Transient	휘발성, 저장·로드시 값 유지되지 않음.
DuplicateTransient	복제 시 값 복제되지 않음.
NonPIEDuplicateTransient	에디터의 PIE 모드에서만 복제에서 제외됨.
SaveGame	게임 세이브 시 저장됨.
Config	ini 파일 설정값으로 저장 및 불러옴.
GlobalConfig	베이스 클래스의 ini 파일에서 값 불러옴.

에디터 관련 지정자(meta)

지정자	용도 및 설명
Category	에디터에 표시될 카테고리 설정.
DisplayName	표시 이름을 다르게 하기.
ToolTip	툴팁으로 설명 추가.
ClampMin / ClampMax	최소/최대값 제한 및 경고.
EditCondition	특정 조건 만족시만 수정 가능.
AdvancedDisplay	‘Advanced’ 목록으로 숨김.
AllowPrivateAccess	블루프린트에서 private 변수 접근 허용.
MultiLine	멀티라인(FString, FText) 에디터 입력 허용.

기타 지정자

지정자	용도 및 설명
Instanced	오브젝트를 인스턴스화해 편집 가능.
NonTransactional	Undo/Redo 트랜잭션에서 제외.
AssetRegistrySearchable	자산 레지스트리 검색에 사용.
Export	오브젝트 Export 시 같이 Export.

각 지정자는 중첩해서 사용 가능하며, 변수의 성격이나 에디터/블루프린트 노출 상태에 따라 적절히 선택해서 활용합니다.