1. 핵심 개념
- GameplayTag: 새로 생성 시 리디렉션 정리할 것
- widget
- 언리얼 포인터 사용
- 언리얼에서 순수가상함수는 PURE_VIRTUAL(SomeClass::SomeFunction, return type;);
- UCLASS, UFINCTION, UENUM, UPROPERTY 매크로
- Delegate: Singlecast vs Multicast vs event
2. 상세 내용
2.1. widget
위젯 클래스는 UMG(Unreal Motion Graphics), UMG의 기반인 Slate, CommonUI로 나뉘어 볼 수 있다.
UMG widget
- UUserWidget: 위젯의 최상위 부모 클래스; 디자이너 툴에서 UI 요소 배치 + 로직 작성 시 사용
- UWidget: Button, Image, Text 등 개별적인 UI 컴포넌트들의 기본 클래스
- UPanelWidget: 다른 위젯들을 자식으로 가질 수 있는 컨테이너 클래스
- Canvas Panel, Vertical Box, Horizontal Box, Scroll Box etc
Common UI(플러그인)
- UCommonUserWidget: UUserWidget을 확장한 클래스로, Input 처리 강화
Slate(C++ 하위 레이어)
블루프린트에서 접근 불가능하며, 성능이 중요하거나 에디터 자체 수정 시 사용
- SWidget: Slate 시스템의 최상위 클래스; 기본적으로 위젯은 SWidget를 래핑해서 작동
- SCompoundWidget: 커스텀 Slate 위젯 클래스 만들 때 사용
기타
- UEditorUtilityWidget: 사용자가 직접 에디터 내에 커스텀 툴바나 창 만들 때 사용, 블루프린트로 에디터기능 제어 가능
- UWidgetComponent: 3D 월드 공간에 UI 배치 시 사용(머리 위 체력바 등)
- AHUD: 관리 클래스인데 액터라서 레벨 바뀌면 파괴됨
- UCommonActivatableWidget: CommonUI에서 제공하는 위젯 클래스로 입력과 포커스 관리에 필요한 UI요소를 구현할 때 사용되는 기본 컨테이너 클래스
- Stack: 레이어드 팝업 구현에 사용
- Queue: 연속적인 튜토리얼, 보상 알림
- Switche: 인덱스 전환; 페이지 교체
2.2. 언리얼에서의 포인터
| 방식 | 대상 | 레퍼카운트 | 특징 |
|---|---|---|---|
생 포인터 + UPROPERTY |
UObject | GC 마킹 | 고전적 방식, 실수하면 댕글링 포인터 위험 |
TObjectPtr |
UObject | GC 마킹 | UE5 표준, 멤버 변수용, 디버깅 최적화 |
TWeakObjectPtr |
UObject | 없음 | 자동 null 초기화, 생명주기 영향 X |
TSharedPtr |
일반 C++ | 있음 (RC) | UI 데이터 모델 등 Non-UObject 관리용 |
소유권이 나에게 없을 때: "내 자식"이 아니라 "그냥 아는 사이"인 객체를 가리킬 때 씁니다.
2.3. UCLASS, UFINCTION, UENUM, UPROPERTY 매크로
[!caution] caution
제미나이 pro 모델로 정리함
UCLASS
UCLASS는 C++ 클래스를 언리얼 엔진의 리플렉션 시스템에 등록하여, 가비지 컬렉션(GC)의 보호를 받게 하고 블루프린트와 상호작용할 수 있게 해주는 가장 핵심적인 매크로입니다.
주요 지정자 (Class Specifiers)
UCLASS([주요 지정자 나열], meta = (MetaKey1 = "Value"))
class PROJECT_API UMyClass : public UObject // (또는 AActor, UUserWidget 등)
{
GENERATED_BODY()
};
// 작성 예시 (블루프린트 생성 가능, 특정 카테고리 숨김)
UCLASS(Blueprintable, HideCategories = ("Rendering", "Input"))
class PROJECT_API AMyMonster : public ACharacter
{ ... };| 구분 | 지정자 (Specifier) | 역할 및 특징 |
|---|---|---|
| 블루프린트 | Blueprintable |
에디터에서 이 C++ 클래스를 부모로 하는 블루프린트 클래스를 생성할 수 있게 허용합니다. |
NotBlueprintable |
블루프린트 클래스 생성을 강제로 막습니다. (기본값인 경우가 많음) | |
BlueprintType |
이 클래스를 블루프린트에서 '변수 타입'으로 사용할 수 있게 허용합니다. | |
| 인스턴스화 | Abstract |
추상 클래스로 선언합니다. 에디터 뷰포트에 배치하거나 직접 생성할 수 없으며, 무조건 상속(부모)용으로만 쓰입니다. |
| 에디터 UI | HideCategories = ("A", "B") |
에디터의 디테일 패널에서 특정 카테고리(폴더)를 아예 숨깁니다. (기획자가 건드리면 안 되는 물리 설정 등을 가릴 때 유용) |
ShowCategories = ("A") |
부모 클래스에서 숨겼던 카테고리를 자식 클래스에서 다시 보여줍니다. | |
| 데이터 | Config = Game |
클래스의 특정 UPROPERTY 값을 .ini 파일(설정 파일)에 저장하고 불러올 수 있게 준비합니다. |
주요 메타 데이터 (meta = (...))
| 메타 키 (Meta Key) | 값(Value) 지정 여부 | 역할 및 특징 |
|---|---|---|
BlueprintSpawnableComponent |
(값 없음) | 이 클래스가 UActorComponent를 상속받았을 때, 블루프린트 에디터의 [컴포넌트 추가] 버튼 목록에 뜨게 만들어 줍니다. |
DisplayName |
="이름" |
언리얼 에디터에서 보일 클래스의 별명(표시 이름)을 지정합니다. |
ShortTooltip |
="설명" |
에디터에서 마우스를 올렸을 때 나타나는 짧은 설명말을 추가합니다. |
UFUNCTION
C++
// 1. 기본 구조
UFUNCTION([주요 지정자 나열], Category = "카테고리명", meta = (MetaKey1 = "Value"))
반환타입 함수이름(매개변수);
// 작성 예시 1: 블루프린트에서 호출할 수 있는 일반 함수 (실행 핀 있음)
UFUNCTION(BlueprintCallable, Category = "Player|Combat")
void FireWeapon();
// 작성 예시 2: 값을 반환하기만 하는 순수 함수 (실행 핀 없음, 녹색 노드)
UFUNCTION(BlueprintPure, Category = "Player|Stat")
float GetCurrentHealth() const;블루프린트 관련 주요 지정자 (가장 많이 씀)
C++ 프로그래머와 블루프린트를 사용하는 디자이너/기획자가 협업할 때 핵심이 되는 지정자들입니다.
| 지정자 (Specifier) | 노드 형태 | 역할 및 특징 |
|---|---|---|
BlueprintCallable |
파란색 (실행 핀 O) | 블루프린트에서 이 C++ 함수를 호출(실행)할 수 있게 합니다. |
BlueprintPure |
초록색 (실행 핀 X) | 상태를 변경하지 않고 값만 반환(Get)하는 함수에 씁니다. (예: GetHP(), 수학 계산 함수 등) |
BlueprintImplementableEvent |
빨간색 (이벤트) | C++에서는 껍데기(선언)만 만들고, 실제 구현은 블루프린트에서 하도록 떠넘깁니다. (.cpp 파일에 함수 구현부를 작성하면 컴파일 에러가 납니다.) |
BlueprintNativeEvent |
빨간색 + 파란색 | C++에서 기본 동작을 구현해 두되, 원한다면 블루프린트에서 덮어쓰기(Override)할 수 있게 합니다. |
네트워크 및 기타 지정자
멀티플레이어 게임이나 디버깅을 위해 사용되는 특수 지정자입니다.
| 지정자 (Specifier) | 분야 | 역할 및 특징 |
|---|---|---|
Server |
네트워크 (RPC) | 클라이언트(유저)가 호출하면, 서버에서 실행되는 함수입니다. (주로 공격, 아이템 획득 등 검증이 필요한 행동) |
Client |
네트워크 (RPC) | 서버가 호출하면, 특정 클라이언트의 화면에서만 실행되는 함수입니다. (주로 UI 업데이트, 히트마커 표시 등) |
NetMulticast |
네트워크 (RPC) | 서버가 호출하면, 서버와 연결된 모든 클라이언트에서 동시에 실행됩니다. (주로 폭발 이펙트, 전체 공지 등) |
Exec |
디버깅 | 게임 플레이 중 콘솔창(~ 키)을 열고 함수 이름을 쳐서 직접 실행할 수 있게 합니다. (예: GodMode, AddGold 100) |
주요 메타 데이터 (meta = (...))
블루프린트 에디터에서 노드가 어떻게 보이고 작동할지 세밀하게 제어합니다.
| 메타 키 (Meta Key) | 값(Value) 지정 여부 | 역할 및 특징 |
|---|---|---|
DisplayName |
="이름" |
블루프린트 노드에 표시될 예쁜 이름(별명)을 지정합니다. (예: DisplayName = "무기 발사") |
ToolTip |
="설명" |
노드에 마우스를 올렸을 때 나타나는 설명말을 작성합니다. |
DefaultToSelf |
="매개변수명" |
특정 매개변수의 기본값을 '자기 자신(Self)'으로 자동 연결해 줍니다. |
HidePin |
="매개변수명" |
특정 매개변수의 핀을 블루프린트 노드에서 숨깁니다. |
AdvancedDisplay |
="매개변수명" |
특정 매개변수 핀을 기본적으로 숨기고, 노드 하단의 화살표를 눌러야만 보이게 만듭니다. (복잡한 옵션에 사용) |
UENUM
// 1. UENUM 선언
UENUM([주요 지정자 나열])
enum class EMyEnumName : uint8 // 2. 반드시 enum class 와 uint8 사용 권장
{
// 3. 각 항목 뒤에 UMETA를 붙여 에디터 표시 설정
Value1 UMETA(DisplayName = "첫 번째 값"),
Value2 UMETA(DisplayName = "두 번째 값"),
Value3 UMETA(Hidden)
};주요 지정자 (Enum Specifiers)
| 지정자 (Specifier) | 역할 및 특징 |
|---|---|
BlueprintType |
이 Enum을 블루프린트에서 '변수 타입'으로 생성하고 사용할 수 있게 허용합니다. 사실상 UENUM을 쓸 때 거의 필수적으로 붙이는 지정자입니다. |
UMETA (항목별 메타 데이터)
Enum 내부의 각 값(Value) 뒤에 붙여서 에디터에 어떻게 표시될지 세밀하게 조작합니다.
| 메타 키 (Meta Key) | 값(Value) 지정 여부 | 역할 및 특징 |
|---|---|---|
DisplayName |
="이름" |
블루프린트 드롭다운 메뉴에 보일 예쁜 이름(한글/영문 띄어쓰기 포함)을 지정합니다. |
Hidden |
(값 없음) | 특정 Enum 값을 에디터와 블루프린트 드롭다운 목록에서 숨깁니다. (내부 로직용으로만 쓸 때 사용) |
ToolTip |
="설명" |
해당 Enum 항목에 마우스를 올렸을 때 보이는 설명말을 작성합니다. |
UPROPERTY
C++
UPROPERTY([주요 지정자 나열], Category = "카테고리명", meta = (MetaKey1 = "Value", MetaKey2))
데이터타입 변수명;
// 작성 예시
UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "UI|State", meta = (AllowPrivateAccess = "true"))
EUIState CurrentState;주요 지정자 (Specifiers)
에디터 노출, 블루프린트 권한, 메모리 속성 등을 결정합니다. 쉼표(,)로 구분하여 여러 개를 섞어 쓸 수 있습니다.
디폴트는 블루프린트 에디터 상단 툴바에 Class Defaults로 접근
| 구분 | 지정자 (Specifier) | 역할 및 특징 | 주로 쓰이는 곳 |
|---|---|---|---|
| 에디터 노출 | EditAnywhere |
디폴트(원본) 및 개별 배치된 인스턴스 모두 수정 가능 | 일반적인 수치 조정 (체력, 속도 등) |
EditDefaultsOnly |
클래스 디폴트(원본)에서만 수정 가능 | 공통 세팅 (최대 레벨, 기본 스탯 등) | |
VisibleAnywhere |
디테일 패널에서 보기만 가능 (수정 불가) | 컴포넌트 포인터 (USpringArm 등) |
|
VisibleInstanceOnly |
월드에 배치된 개별 인스턴스에서만 보기 가능 | 런타임 디버깅 데이터 등 | |
| 블루프린트 | BlueprintReadWrite |
블루프린트에서 Get(읽기) / Set(쓰기) 노드 모두 사용 가능 | 동적으로 변하는 데이터 |
BlueprintReadOnly |
블루프린트에서 Get(읽기) 노드만 사용 가능 | 외부 수정으로부터 보호할 데이터 | |
| 메모리/저장 | Transient |
디스크에 저장(Serialize)하지 않음 (런타임 임시 데이터) | UI 애니메이션, 타이머 변수 등 |
SaveGame |
언리얼 세이브 시스템을 통해 파일에 기록될 변수 | 플레이어 진행도, 소지품 등 |
Category (카테고리 분류)
언리얼 에디터의 디테일 패널이나 블루프린트 노드 검색 창에서 변수를 시각적으로 묶어주는 역할을 합니다.
| 파라미터 | 작성 형식 | 역할 및 특징 |
|---|---|---|
| 기본 폴더 | Category = "이름" |
변수를 그룹화할 최상위 폴더명을 지정합니다. |
| 하위 폴더 | Category = "대분류 |
소분류"` |
meta (메타 데이터)
엔진과 에디터의 특수한 동작이나 UI(UMG) 바인딩을 세밀하게 제어합니다. meta = (...) 괄호 안에 작성합니다.
AllowPrivateAccess가 true이면 코드 내에서는 캡슐화가 유지되지만 블루프린트 에디터에는 공개됨
| 메타 키 (Meta Key) | 값(Value) 지정 여부 | 역할 및 특징 |
|---|---|---|
AllowPrivateAccess |
="true" |
C++에서 private/protected인 변수를 블루프린트에 강제 노출하여 캡슐화를 유지합니다. |
BindWidget |
(값 없음) | C++ 변수명과 동일한 이름의 UMG 위젯 에셋을 런타임에 자동 연결합니다. (없으면 에러) |
BindWidgetOptional |
(값 없음) | 위젯을 자동 연결하되, 블루프린트에 위젯이 없어도 에러를 내지 않고 nullptr로 처리합니다. |
BindWidgetAnim |
(값 없음) | C++ 변수명과 동일한 이름의 UMG 타임라인 애니메이션을 자동 연결합니다. |
BindWidgetAnimOptional |
(값 없음) | 애니메이션을 자동 연결하되, 타임라인에 없어도 에러를 무시합니다. |
ClampMin / ClampMax |
="숫자" |
에디터 패널에서 값 입력이나 슬라이더 조작 시, 최소/최대 범위를 강제로 제한합니다. (예: ClampMin="0.0") |
Delegate
- SingleCastDelegate: 1대1 바인딩; 리턴값 존재
- MultiCastDelegate: 1대n 바인딩; 리턴값 없음
- DynamicDelegate: 빌드타임이 아닌 런타임에 바인딩을 가능하게 함
- Event: MultiCastDelegate와 유사하지만 Event를 선언한 클래스만
Broadcast,IsBound,Clear호출이 가능하다.(c#에 event와 delegate와 유사)
3. 질문 및 해결 (Q&A)
4. 관련 문서 (Links)
'내일배움캠프 > TIL' 카테고리의 다른 글
| TIL260513 - Unreal (0) | 2026.05.13 |
|---|---|
| TIL260512 - Unreal (0) | 2026.05.12 |
| TIL260508 - CPP (0) | 2026.05.08 |
| TIL260507 - Quaternion (0) | 2026.05.07 |
| TIL260506 - Quaternion (0) | 2026.05.06 |