리플렉션 시스템 (Blueprint 와 C++ 관계, UCLASS, UPROPERTY, UFUNCTION) | [언리얼 엔진 C++ (Unreal Engine C++)]

 

리플렉션 시스템: Blueprint 와 C++ 관계, UCLASS, UPROPERTY, UFUNCTION

 

---

 

Blueprint 와 C++ 관계

 

Blueprint (시각적 스크립팅) 이해

• Blueprint는 언리얼 엔진에서 제공하는 시각적 스크립팅 도구로, 노드 (블록)를 연결하여 게임 로직을 작성합니다.
• 장점
  • Blueprint 그래프를 수정 후, 에디터에서 Play 버튼을 누르면 곧바로 결과를 확인할 수 있습니다. 아이디어를 빠르게 검증하고 반복할 때 큰 장점이 됩니다.
  • “레고 블록”을 쌓듯이 노드를 연결해 로직을 작성하므로, 프로그래밍 언어에 익숙하지 않은 초급자도 쉽게 접근할 수 있습니다.
• 한계점
  • 노드 수가 많아질수록 그래프가 복잡해져, 가독성과 유지보수가 어려워질 수 있습니다.
  • C++과 비교했을 때, Blueprint는 내부적으로 추가 해석 과정을 거칩니다. 따라서 물리 연산이나 AI 같은 높은 성능이 필요한 시스템에서는 병목이 될 수 있습니다.

 

C++ (네이티브 코드 프로그래밍) 이해

• 장점
  • 엔진 코어까지 직접 수정 가능하며, 복잡하고 성능이 중요한 게임 로직을 빠르고 최적화된 방식으로 구현할 수 있습니다.
  • 표준 라이브러리와 외부 라이브러리를 자유롭게 사용할 수 있어, 대규모 프로젝트에 적합합니다.
  • 포인터, 템플릿 같은 C++ 언어적 기능을 통해 메모리와 로직을 정교하게 다룰 수 있습니다.
• 한계점
  • C++ 코드를 수정하면 에디터를 재시작하거나 Live Coding을 다시 컴파일해야 하므로, 반복 작업 시 조금 번거로울 수 있습니다.

 

Blueprint와 C++의 상호보완적 관계

• 실무에서는 Blueprint와 C++를 함께 사용하는 경우가 많습니다. 하나만 사용하는 것보다 각각의 장점을 취하는 하이브리드 워크플로우가 일반적입니다.
  • Blueprint 활용: UI 제작, 간단한 이벤트 처리, 시각적 연출 등 빠른 프로토타이핑과 직관적인 로직 작성에 사용합니다.
  • C++ 활용: 높은 성능이 필요한 게임플레이 로직이나 엔진 레벨의 확장, 복잡한 수학 연산 등에 사용합니다.
• 이렇게 분업하면 개발 속도와 퍼포먼스를 모두 확보하기가 수월해집니다.

 

 

리플렉션 시스템

 

리플렉션 (Reflection)이란?

• 언리얼 엔진의 리플렉션 시스템은 C++ 클래스의 변수 및 함수 정보를 엔진 내부의 메타데이터 형태로 저장하고, 이를 에디터나 블루프린트에서 활용할 수 있게 만들어주는 기술입니다.
  • C++ 클래스에 있는 여러 멤버(변수, 함수 등)를 “Reflectoin (반사)”해, 에디터와 블루프린트에서 직접 설정, 호출이 가능하도록 합니다.
  • 이 덕분에 프로그래머가 만든 C++ 로직의 뼈대를 디자이너나 다른 팀원들이 에디터에서 직관적으로 조정할 수 있습니다.
  • 매개변수를 코드에서만 변경하는 것이 아니라, 에디터에서 바로 조정 (슬라이더나 숫자 입력)하여 반복 테스트를 빠르게 진행할 수 있습니다.
• 리플렉션 시스템을 제대로 이해하고 활용하면, 큰 프로젝트에서도 개발 효율과 협업 효과를 극대화할 수 있습니다.

 

---

 

C++ 클래스 리플렉션에 등록하기

 

C++ 생성시 자동으로 추가되는 리플렉션들

 

#pragma once
#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "Item.generated.h" // 반드시 마지막에 위치해야 합니다.

UCLASS()
class PROTECTNAME_API AItem : public AActor
{
		GENERATED_BODY()
	
public:	
		AItem();
	
protected:
		USceneComponent* SceneRoot;
		UStaticMeshComponent* StaticMeshComp;
	
		float RotationSpeed;
	
		virtual void BeginPlay() override;
		virtual void Tick(float DeltaTime) override;
};

 

• #include "Item.generated.h" (#include "created_file_name.generated.h")
  • 언리얼 엔진이 자동 생성하는 헤더 파일로, 클래스의 리플렉션 및 엔진 통합에 필요한 코드가 들어 있습니다.
  • 반드시 헤더 파일의 가장 마지막 #include 구문 아래에 위치해야 합니다. (다른 #include보다 아래에 오지 않으면 빌드 에러 발생 위험이 있습니다.)
• UCLASS()
  • 해당 클래스를 언리얼 엔진의 리플렉션 시스템에 등록한다는 의미입니다.
  • 이 매크로가 있어야만 블루프린트 등 에디터 차원에서 이 클래스를 인식하고 사용할 수 있습니다.
• GENERATED_BODY()
  • 언리얼의 코드 생성 도구가 사용하는 코드를 삽입하는 역할을 합니다.
  • 클래스 내부에 필요한 리플렉션 정보를 자동으로 생성해 줍니다.

 

UCLASS() 매크로의 주요 지정자

 

UCLASS() 매크로는 클래스를 리플렉션 시스템에 등록하면서, 추가적으로 몇 가지 옵션 (지정자)을 설정할 수 있습니다.

• 기본 동작
  • 만약 UCLASS()에 옵션을 주지 않으면, 블루프린트에서 상속이 가능하고 변수로 참조가 가능한 형태로 등록됩니다.
• 주요 옵션 (필요에 따라 이 지정자들을 조합해 클래스가 어떻게 블루프린트와 상호작용해야 할지 명시할 수 있습니다.)
  • Blueprintable: 블루프린트에서 상속 가능한 클래스로 만듭니다.
  • NotBlueprintable: 블루프린트에서 이 클래스를 상속할 수 없도록 합니다.
  • BlueprintType: 블루프린트에서 변수나 참조로 사용할 수 있게 합니다. 이 옵션만 있으면, 상속은 허용되지 않고 참조만 가능합니다. 

 

Common UCLASS Specifiers

You can pass specifiers inside the macro parenthesis to modify how the engine or Editor treats your class. 

• Blueprintable / BlueprintType: Allows the class to be extended via Blueprints or used as a variable type in the Blueprint graph.
• NotBlueprintable: Prevents Blueprints from inheriting from this class (the default for non-Actor objects).
• Abstract: Tells the engine this class is a template and cannot be instantiated directly in the world.
• EditInlineNew / CollapseCategories: Alters how properties belonging to the class are displayed in the Unreal Editor details panel.
• MinimalAPI: Exports only the bare minimum amount of type information, which speeds up compile times for classes that only need to be cast to from other modules.
• DefaultToInstanced: Allows components or instances of this class to be created and instanced within a Blueprint or Editor panel.

 

UCLASS() == UCLASS( Blueprintable , BlueprintType ) // Default | 블루프린트가 상속 가능하다 

 

C++ 클래스 상속 받은 Blueprint 클래스 생성

 

• Item C++ 클래스로부터 블루프린트 클래스를 상속받아 만들어보겠습니다.
• 콘텐츠 브라우저에서 AItem 클래스를 우클릭합니다.
• Create Blueprint class based on AItem을 선택합니다.

• 저장할 폴더를 지정 (예: Content/Blueprints)하고, 블루프린트 이름을 BP_Item 등으로 정해줍니다.

• 이제 BP_Item 블루프린트가 생성되었고, 기본 부모 클래스는 Item이 됩니다. 이 블루프린트 안에서 C++로 작성된 속성이나 함수를 시각적으로 다룰 수 있습니다.

 

또한 C++ 안의 UCLASS 에서 옵션을 Default 두면 (즉 막지않으면) Blueprint 안에서 변수로 Class 를 받아올 수 있습니다

 

---

 

변수에 리플렉션 적용하기

 

UPROPERTY() 매크로의 주요 지정자

• UPROPERTY()에는 여러 지정자를 작성해, 에디터에서의 표시 여부나 Blueprint 접근성, 읽기/쓰기 권한 등을 자세하게 설정할 수 있습니다. 아래는 자주 쓰이는 대표적인 지정자들입니다.
• UCLASS() 와 다르게 UPROPERTY() 는 꼭 인자값을 따로 설정해 줘야 한다 (안그러면 아무런 효과가 없음)

1. 편집 가능 범위 지정자
   • VisibleAnywhere: 읽기 전용으로 표시되며, 수정은 불가능
   • EditAnywhere: 클래스 기본값, 인스턴스 모두에서 수정 가능
   • EditDefaultsOnly: 클래스 기본값에서만 수정 가능
   • EditInstanceOnly: 인스턴스에서만 수정 가능
2. Blueprint 접근성 지정자
   • BlueprintReadWrite: Blueprint 그래프에서 Getter/Setter로 값을 읽거나 쓸 수 있습니다.
   • BlueprintReadOnly: Blueprint 그래프에서 Getter 핀만 노출되어, 읽기만 가능합니다.
3. Category 지정자
   • Details 패널에서 이 변수는 “Rotation” 범주(폴더) 아래에 표시됩니다.
   • 여러 변수를 비슷한 카테고리에 묶으면, 세부 정보 패널에서 깔끔하게 정리되어 보입니다.
4. 메타 옵션 지정자
   • meta=(ClampMin="0.0"): 에디터에서 변수 입력 시 최소값을 제한할 수 있습니다.
   • meta=(AllowPrivateAccess="true"): 해당 멤버가 private로 선언되어 있어도, 에디터나 Blueprint에서 접근할 수 있도록 허용합니다.

• 만약 UPROPERTY()만 있고, 추가 지정자를 하나도 주지 않는다면?
  • 엔진 리플렉션 시스템에는 등록되지만, 에디터나 Blueprint에 노출되지는 않습니다.
  • “엔진이 변수의 존재는 알고 있지만, 외부에서는 보이지 않게 숨겨둔 상태”라고 볼 수 있습니다.
  • 리플렉션에 등록만 되어 있어도 가비지 컬렉션(메모리 관리)과 직렬화(세이브/로드) 같은 엔진 내부 기능이 작동할 수 있습니다.

 

C++ 클래스 디폴트 오브젝트는 Class Defaults 를 에디터에서 수정 못하지만, Blueprint로 상속 받은 것은 Class Default 수정 가능하다

 

// Root Scene Component, 에디터에서 볼 수만 있고 수정 불가
UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="Item|Components")
USceneComponent* SceneRoot;	

// Static Mesh, 에디터와 Blueprint에서 수정 가능
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Item|Components")
UStaticMeshComponent* StaticMeshComp;
	
// 회전 속도, 클래스 기본값만 수정 가능
UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category="Item|Properties")

 

위와 같이 UPROPERTY() 지정자를 설정해두면, Blueprint 클래스를 통해 해당 변수들을 에디터 내에서 쉽게 조정할 수 있게 됩니다.

코드 수정 없이 에디터에서 다양한 속성을 즉시 변경하고 테스트할 수 있다는 점이 리플렉션의 큰 장점입니다.

 

---

 

 함수에 리플렉션 적용하기

 

 

함수 리플렉션이란?

• 지금까지 살펴본 것은 멤버 변수를 리플렉션 시스템에 노출하는 방법이었습니다. 이와 비슷하게, 함수 또한 블루프린트에서 직접 호출할 수 있도록 등록할 수 있습니다. 이렇게 하면, 복잡한 C++ 로직을 Blueprint에서 간단한 노드로 불러와 제어할 수 있으므로 작업 효율이 높아집니다.
  • UPROPERTY()가 멤버 변수를 리플렉션 시스템에 등록한다면,
  • UFUNCTION()은 멤버 함수를 등록합니다.
• C++에서 만든 함수를 Blueprint 노드로 노출하고 싶을 때, UFUNCTION() 매크로를 사용합니다.

 

UFUNCTION() 매크로의 주요 지정자

• Blueprint 관련 지정자
  • BlueprintCallable: Blueprint 이벤트 그래프(노드)에서 호출(Execute) 가능한 함수로 만듭니다.
  • BlueprintPure: Getter 역할만 수행합니다. (Exec 핀 없이 Return Value만 노출)
  • BlueprintImplementableEvent: 함수의 선언만 C++에 있고, 구현은 블루프린트에서 하도록 합니다. C++ 코드에서는 함수 이름만 정의하고, 실제 동작은 Blueprint Event Graph 안에서 이벤트 노드처럼 구현됩니다.
    • C++ 내에서 정의하면 안됨
  • BlueprintNativeEvent:  C++ 기본 구현 가능 + 블루프린트에서 오버라이드 가능

• 예시로는 GetHealth() 같은 값 반환 함수는 BlueprintPure
• UseItem() 같은 행동 함수는 BlueprintCallable이 자주 어울려요.

 

• 만약 UFUNCTION()에 지정자를 하나도 쓰지 않았다면?
  • UPROPERTY()와 마찬가지로, 함수가 언리얼 리플렉션에 등록되긴 하지만, 특별히 Blueprint에 노출되지는 않습니다.
  • “엔진이 함수의 존재는 파악하되, Blueprint에서 직접 호출할 수 없게 숨겨둔 상태”라고 보면 됩니다.

 

 

Blueprint에서 함수 노드 사용

 

이제 블루프린트 (BP_Item)의 Event Graph 창에서 우클릭한 뒤, 함수 이름을 검색하면 아래와 같이 노드가 노출됩니다.

 

• ResetActorPosition → BlueprintCallable로 선언했으므로, 노드로 실행(Exec)할 수 있습니다.
• GetRotationSpeed → BlueprintPure로 선언했으므로, 단순히 값만 반환하는 Getter 노드로 사용됩니다.
• OnItemPickedUp → BlueprintImplementableEvent로 선언했으므로, 이벤트 그래프 안에서 구현한 내용을 C++에서 OnItemPickedUp()를 호출함으로써 실행할 수 있습니다.

 

블루프린트에서 이벤트처럼 구현한 OnItemPickedUp()은 C++에선 함수 이름만 존재하고 실제 코드는 없습니다. 대신, Blueprint에서 이벤트 그래프를 통해 시각적 로직으로 구현해두면, C++에서 OnItemPickedUp()를 부르는 순간 그 이벤트가 실행됩니다.

---

 

리플렉션 시스템 = Blueprint 와 C++ 의 연결

 

추천

 

UE 공식 문서

UFUNCTION 지정자 문서: https://dev.epicgames.com/documentation/en-us/unreal-engine/ufunctions-in-unreal-engine

UFunctions in Unreal Engine | Unreal Engine 5.7 Documentation | Epic Developer Community

 

언리얼 리플렉션 시스템 개요: https://dev.epicgames.com/documentation/en-us/unreal-engine/reflection-system-in-unreal-engine

Reflection System in Unreal Engine | Unreal Engine 5.7 Documentation | Epic Developer Community

 

UPROPERTY 지정자 문서: https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-uproperties

Unreal Engine UProperties | Unreal Engine 5.7 Documentation | Epic Developer Community

 

 

[페이지] Unreal Engine | 언리얼 엔진