Unreal) UPROPERTY

언리얼 엔진으로 게임을 개발하다 보면, 단순히 C++ 문법만으로는 해결할 수 없는 영역들이 등장한다.

예를 들어, 변수 하나를 블루프린트에서 접근하거나, 에디터 상에서 조정 가능한 값으로 만들고 싶을 때가 있다.

이럴 때 사용하는 것이 바로 언리얼의 UPROPERTY 매크로다.

리플렉션(Reflection) 이란?

먼저 리플렉션이란 코드가 실행 중에 자신을 들여다보고 조작할 수 있는 능력을 말한다.

보통 C++은 정적인 언어라, 변수 이름이나 타입 정보를 런타임에 직접 알 수 없다.

하지만 언리얼 엔진은 이 한계를 극복하기 위해 자체적인 리플렉션 시스템을 갖추고 있다.

언리얼의 UCLASS, UPROPERTY, UFUNCTION 같은 매크로들이 이 시스템과 연동되는 핵심 요소다.

언리얼이 리플렉션 정보를 갖고 있으면 다음과 같은 일들이 가능해진다:

• 에디터에서 변수 자동 노출
• 블루프린트에서 변수/함수 접근
• 저장/로드(직렬화) 자동 처리
• 런타임에 변수 이름으로 값 검색
• 가비지 컬렉션(GC) 추적 대상 등록

즉, UPROPERTY는 단순히 변수 선언을 넘어, 언리얼에게 “이 변수 좀 관리해줘”라고 알리는 도장 같은 것이다.

UPROPERTY 란?

UPROPERTY는 언리얼 엔진의 리플렉션 시스템에 해당 변수를 등록하기 위한 매크로이다.

이 매크로를 붙여야 언리얼의 가비지 컬렉션(GC), 에디터 노출, 블루프린트 연동, 저장/로드 등 다양한 기능이 활성화된다.

즉, 언리얼의 내부 시스템에서 해당 변수를 추적하고 관리할 수 있게 만들어주는 일종의 “등록 마크” 역할을 한다고 보면 된다.

언제 사용해야 하나?

• 블루프린트에서 접근하거나 조정하고 싶을 때
• 언리얼 에디터에서 값을 수정하고 싶을 때
• 해당 변수를 저장하거나 로드할 필요가 있을 때
• UObject, UActorComponent, USoundCue, UMaterialInstance 등 언리얼 객체 포인터를 사용할 때

대표적인 속성들

가시성(Visibility)

속성	설명
VisibleAnywhere	어디서든 읽기만 가능
EditAnywhere	어디서든 읽고 쓰기 가능
EditDefaultsOnly	클래스 디폴트에서만 편집 가능
EditInstanceOnly	인스턴스에서만 편집 가능
Transient	저장 안 됨. 런타임 전용

블루프린트 관련

속성	설명
BlueprintReadOnly	블루프린트에서 읽기 전용
BlueprintReadWrite	블루프린트에서 읽고 쓰기 가능

기타

속성	설명
Category="카테고리명"	에디터의 디테일 패널에서 카테고리 정리
meta=(AllowPrivateAccess="true")	private 변수지만 블루프린트/에디터에서 노출되도록 허용

사용 예제

UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category=Camera, meta=(AllowPrivateAccess="true"))
UCameraComponent* FirstPersonCameraComponent;

위 코드는 1인칭 캐릭터의 카메라 컴포넌트를 정의한 것으로,

• 에디터에서 볼 수 있고 (읽기 전용),
• 블루프린트에서도 접근 가능하며,
• Camera라는 카테고리 아래 정리된다.

안 쓰면 어떤 문제가 생기나?

언리얼에서 UObject 기반 포인터를 UPROPERTY 없이 선언하면, 언리얼의 GC(가비지 컬렉션)가 추적하지 못해 런타임 크래시나 메모리 누수가 발생할 수 있다.

또한 블루프린트와의 연동도 불가능하고, 저장/로드, 에디터 노출 등 언리얼 특유의 강력한 기능들을 사용할 수 없게 된다.

마무리

UPROPERTY는 단순한 문법 요소를 넘어 언리얼 개발자의 작업 흐름을 안전하고 편리하게 만들어주는 필수 도구이다.

처음에는 복잡해 보일 수 있지만, 이를 잘 활용하는 것이 곧 언리얼의 진짜 힘을 끌어내는 열쇠가 된다.