언리얼 UPROPERTY 필수 메타데이터 정리

언리얼 엔진에서 UPROPERTY()는 C++ 코드와 에디터, 블루프린트 간의 연결을 담당하는 핵심 매크로입니다.
하지만 처음엔 안에 들어가는 다양한 메타데이터들이 생소하게 느껴질 수 있죠.
이 글에서는 자주 쓰이는 지정자 위주로, 실제 사용 우선순위에 따라 정리해드립니다.

1. BlueprintReadWrite / BlueprintReadOnly

UPROPERTY(BlueprintReadOnly)
float MaxHealth;

UPROPERTY(BlueprintReadWrite)
int32 CurrentScore;

블루프린트에서 읽기만 가능하거나, 읽기/쓰기를 모두 허용할지 설정합니다.

2. EditAnywhere / EditDefaultsOnly / VisibleAnywhere

UPROPERTY(EditAnywhere)
float WalkSpeed;

UPROPERTY(EditDefaultsOnly)
UStaticMesh* WeaponMesh;

UPROPERTY(VisibleAnywhere)
FVector LastHitLocation;

디테일 패널에서 수정 가능 여부를 제어합니다.

3. Category

UPROPERTY(EditAnywhere, Category="Movement")
float JumpVelocity;

디테일 패널에서 속성 그룹을 지정할 수 있습니다.

4. meta = (AllowPrivateAccess = "true")

UPROPERTY(EditAnywhere, meta = (AllowPrivateAccess = "true"))
float Speed;

private 변수도 에디터에서 노출되도록 허용합니다.

5. Transient

UPROPERTY(Transient)
int32 RuntimeTempValue;

저장되지 않고 런타임 중에만 유지되는 휘발성 변수로 지정합니다.

6. SaveGame

UPROPERTY(SaveGame)
int32 PlayerLevel;

SaveGame 시스템으로 저장 시 포함될 항목을 지정합니다.

7. ClampMin / ClampMax

UPROPERTY(EditAnywhere, meta = (ClampMin = "0.0", ClampMax = "100.0"))
float Stamina;

입력 가능한 값의 범위를 제한합니다.

8. DisplayName

UPROPERTY(EditAnywhere, meta = (DisplayName = "최대 체력"))
float MaxHealth;

디테일 패널과 블루프린트에서 변수명을 다르게 보여줄 수 있습니다.

💡 UPROPERTY 초보자용 요약표

지정자	설명	사용 예
BlueprintReadOnly	블루프린트에서 읽기만 가능	상태값 등 외부 수정이 필요 없는 변수
BlueprintReadWrite	블루프린트에서 읽고 쓰기 가능	UI에서 조작하는 값
EditAnywhere	모든 디테일 패널에서 수정 가능	디자인 수치 조정용
EditDefaultsOnly	클래스 디폴트 값만 수정 가능	기본 값 설정
VisibleAnywhere	읽기 전용, 수정 불가	디버깅용 표시
Category	속성 그룹 설정	"Movement", "UI", "Combat"
Transient	저장되지 않는 변수	임시값, 캐시
SaveGame	저장 파일에 포함될 변수	레벨, 위치, 경험치 등
ClampMin / ClampMax	입력 제한 범위 설정	0 ~ 100 등 수치형 값
DisplayName	표시될 변수명 변경	"최대 체력" 등 한글 UI 구성

📌 추천 기본 조합 예시

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

🔗 공식 문서

✅ 언리얼 엔진 UPROPERTY 메타데이터 공식 문서