C++와 Unreal Engine으로 3D 게임 개발 1-7

1-7. C++ 클래스와 리플렉션 시스템 활용하기

1. 리플렉션 시스템 이해하기

 

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

장점

• 즉각적인 테스트 가능
• 초급자도 쉽게 접근할 수 있음

단점

• 노드 수가 많아지면 → 그래프가 복잡해짐, 가독성과 유지보수가 어려움
• 내부적으로 추가 해석 과정을 거침
• 물리 연산, AI 등 높은 성능이 필요한 시스템에서는 병목이 될 수 있음

---

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

장점

• 엔진 코어까지 직접 수정 가능
• 복잡하고 성능이 중요한 게임 로직을 빠르고 최적화된 방식으로 구현
• 대규모 프로젝트에 적합
• C++ 언어적 기능을 통해 메모리와 로직을 정교하게 다룰 수 있음

단점

• C++ 코드를 수정하면 에디터를 재시작, Live Coding을 다시 컴파일해야 함 → 반복 작업 시 조금 번거로울 수 있음

---

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

 

실무에서는 Blueprint와 C++를 함께 사용하는 경우가 많음

 

각각의 장점을 취하는 하이브리드 워크플로우

• Blueprint 활용: UI 제작, 간단한 이벤트 처리, 시각적 연출 등 빠른 프로토타이핑과 직관적인 로직 작성에 사용
• C++ 활용: 높은 성능이 필요한 게임플레이 로직이나 엔진 레벨의 확장, 복잡한 수학 연산 등에 사용

---

리플렉션 (Reflection)

• C++ 클래스의 변수 및 함수 정보를 엔진 내부의 메타데이터 형태로 저장하고, 이를 에디터나 블루프린트에서 활용할 수 있게 만들어주는 기술
• C++ 클래스에 있는 여러 멤버(변수, 함수 등)를 Reflectoin (반사) 해, 에디터와 블루프린트에서 직접 설정, 호출이 가능하도록 함
• 매개변수를 코드에서만 변경하는 것이 아니라, 에디터에서 바로 조정 → 반복 테스트를 빠르게 진행
• 큰 프로젝트에서도 개발 효율과 협업 효과를 극대화 가능

---

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

#include "Item.generated.h"

• 반드시 헤더 파일의 가장 마지막 #include 구문 아래에 위치 (빌드 에러 발생 위험)

UCLASS()

• 해당 클래스를 언리얼 엔진의 리플렉션 시스템에 등록한다는 의미
• 해당 매크로가 있어야 블루프린트 등 에디터 차원에서 이 클래스를 인식하고 사용 가능함

GENERATED_BODY()

• 언리얼의 코드 생성 도구가 사용하는 코드를 삽입하는 역할
• 클래스 내부에 필요한 리플렉션 정보를 자동으로 생성

---

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

• 클래스를 리플렉션 시스템에 등록
• 추가적으로 몇 가지 옵션 (지정자)을 설정

옵션을 주지 않는 경우

• 블루프린트에서 상속이 가능하고 변수로 참조가 가능한 형태로 등록

주요 옵션

Blueprintable

• 블루프린트에서 상속 가능한 클래스로 만듦

 NotBlueprintable

• 블루프린트에서 이 클래스를 상속할 수 없도록 함

 BlueprintType

• 블루프린트에서 변수나 참조로 사용할 수 있게 함
• 이 옵션만 있으면, 상속은 허용되지 않고 참조만 가능

---

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

 

BP_Item 블루프린트가 생성 → 기본 부모 클래스는 Item

블루프린트 안에서 C++로 작성된 속성이나 함수를 시각적으로 다룰 수 있음

---

3. 변수에 리플렉션 적용하기

편집 가능 범위 지정자

• VisibleAnywhere : 읽기 전용으로 표시되며, 수정은 불가능 
• EditAnywhere : 클래스 기본값, 인스턴스 모두에서 수정 가능 
• EditDefaultsOnly : 클래스 기본값에서만 수정 가능 
• EditInstanceOnly : 인스턴스에서만 수정 가능

Blueprint 접근성 지정자

• BlueprintReadWrite : Blueprint 그래프에서  Getter/Setter로 값을 읽거나 쓸 수 있음
• BlueprintReadOnly : Blueprint 그래프에서 Getter 핀만 노출되어, 읽기만 가능

 

Item.h

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "Item.generated.h"

UCLASS()
class SPARTAPROJECT_API AItem : public AActor
{
		GENERATED_BODY()
	
public:	
		AItem();
		
protected:
		// 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")
		float RotationSpeed;
	
		virtual void BeginPlay() override;
		virtual void Tick(float DeltaTime) override;
};

 

Item.cpp

#include "Item.h"

AItem::AItem()
{
		SceneRoot = CreateDefaultSubobject<USceneComponent>(TEXT("SceneRoot"));
		SetRootComponent(SceneRoot);
	
		StaticMeshComp = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("StaticMesh"));
		StaticMeshComp->SetupAttachment(SceneRoot);
	
		PrimaryActorTick.bCanEverTick = true;
		RotationSpeed = 90.0f;
}

void AItem::BeginPlay()
{
		Super::BeginPlay();
}

void AItem::Tick(float DeltaTime)
{
		Super::Tick(DeltaTime);
	
		if (!FMath::IsNearlyZero(RotationSpeed))
		{
			AddActorLocalRotation(FRotator(0.0f, RotationSpeed * DeltaTime, 0.0f));
		}
}

 

---

4. 함수에 리플렉션 적용하기

함수 리플렉션

• UPROPERTY() 가 멤버 변수를 리플렉션 시스템에 등록 → UFUNCTION() 은 멤버 함수를 등록
• C++에서 만든 함수를 Blueprint 노드로 노출하고 싶을 때, UFUNCTION() 매크로 사용

---

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

 

Blueprint 관련 지정자

 

BlueprintCallable

• Blueprint 이벤트 그래프(노드)에서 호출 가능한 함수로 만듦

BlueprintPure

• Getter 역할만 수행 (Exec 핀 없이 Return Value만 노출)

BlueprintImplementableEvent

• 함수의 선언만 C++에 있고, 구현은 블루프린트에서 하도록 함
• C++ 코드에서는 함수 이름만 정의하고, 실제 동작은 Blueprint Event Graph 안에서 이벤트 노드처럼 구현

UFUNCTION()에 지정자를 하나도 쓰지 않는 경우

• 함수가 언리얼 리플렉션에 등록되긴함
• Blueprint에 노출되지는 않음

---

Item 클래스 함수 리플렉션 등록

 

Item.h

 

Item.cpp

---

Blueprint에서 함수 노드 사용

• ResetActorPosition → BlueprintCallable로 선언 → 노드로 실행 가능
• GetRotationSpeed → BlueprintPure로 선언 → 단순히 값만 반환하는 Getter 노드로 사용
• OnItemPickedUp → BlueprintImplementableEvent로 선언 → 이벤트 그래프 안에서 구현한 내용을 C++에서OnItemPickedUp() 를 호출함으로써 실행