C++로 Blueprint 클래스 확장

UObject와 AActor 차이를 이해했다면, 이제 언리얼 하이브리드 개발의 핵심으로 넘어갑니다.

이번 절은 C++ 클래스를 블루프린트로 확장하는 방법을 다룹니다.

언리얼은 C++로 기반 구조를 만들고, 블루프린트로 빠르게 기능을 확장하는 방식을 강력하게 지원하며, 이 조합이 실제 개발 효율을 크게 높여 줍니다.

핵심 흐름: C++에서 성능/구조를 고정하고, Blueprint에서 변수·연출을 빠르게 조정해 반복 속도를 높입니다.

C++을 블루프린트로 확장해야 하는 이유

이 질문에 대한 답은 명확합니다.

C++과 블루프린트는 각각의 장단점이 있기 때문입니다.

• C++의 장점
• 성능: 복잡한 연산, 물리 시뮬레이션, AI 로직 등 성능이 중요한 부분에 유리합니다.
• 접근성: 엔진의 깊숙한 부분까지 접근하여 커스터마이징할 수 있습니다.
• 제어: 메모리 관리 등 더 세밀한 제어가 가능합니다.
• 표준화: 대규모 프로젝트에서 코드의 구조와 규칙을 강력하게 강제할 수 있습니다.
• 블루프린트의 장점
• 빠른 프로토타이핑: 시각적인 스크립팅 방식으로 아이디어를 빠르게 구현하고 테스트할 수 있습니다.
• 비개발자 협업: 프로그래밍 지식이 없는 아티스트나 기획자도 게임 로직에 참여할 수 있습니다.
• 쉬운 반복 작업: 간단한 로직 변경이나 데이터 수정에 즉각적으로 대응할 수 있습니다.

이상적인 워크플로는 책임을 분리하는 방식입니다.

성능 민감 구간, 엔진 핵심 경로, 복잡 로직 기반은 C++로 구현하고, 자주 변경되는 게임플레이 디테일이나 디자이너 조정 영역은 블루프린트로 처리합니다.

C++ 클래스를 블루프린트에서 상속해 사용하면 두 방식의 장점을 동시에 취할 수 있습니다.

C++ 클래스 생성 및 기본 구조

첫 번째 C++ 클래스를 생성하며 실습을 시작합니다.

이번에는 간단한 메시를 표시하고 특정 텍스트를 출력하는 액터를 구현합니다.

이제 생성된 파일의 기본 구조를 살펴보겠습니다.

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "Components/StaticMeshComponent.h" // 추가할 컴포넌트를 위해 미리 포함
#include "AMyAwesomeActor.generated.h" // 항상 마지막

UCLASS()
class MYFIRSTCPPPROJECT_API AMyAwesomeActor : public AActor
{
    GENERATED_BODY()

public:
    // Sets default values for this actor's properties
    AMyAwesomeActor();

protected:
    // Called when the game starts or when spawned
    virtual void BeginPlay() override;

public:
    // Called every frame
    virtual void Tick(float DeltaTime) override;

    // StaticMeshComponent를 위한 포인터 선언
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Components")
    UStaticMeshComponent* MyStaticMesh;

    // 블루프린트에서 변경 가능하도록 노출할 속성
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Custom Properties")
    FString WelcomeMessage;

    // 블루프린트에서 호출할 수 있는 함수
    UFUNCTION(BlueprintCallable, Category = "Custom Functions")
    void PrintWelcomeMessage();
};

// AMyAwesomeActor.cpp
#include "AMyAwesomeActor.h"
#include "Components/StaticMeshComponent.h" // StaticMeshComponent를 위해 다시 포함 (보통 헤더에서 미리 함)
#include "Engine/Engine.h" // GEngine->AddOnScreenDebugMessage를 위해 포함

// Sets default values
AMyAwesomeActor::AMyAwesomeActor()
{
    // Set this actor to call Tick() every frame.  You can turn this off to improve performance if you don't need it.
    PrimaryActorTick.bCanEverTick = true;

    // UStaticMeshComponent 생성 및 Root Component로 설정
    MyStaticMesh = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("MyMesh"));
    RootComponent = MyStaticMesh;

    // 변수 기본값 설정
    WelcomeMessage = TEXT("Hello from C++!");
}

// Called when the game starts or when spawned
void AMyAwesomeActor::BeginPlay()
{
    Super::BeginPlay();

    // BeginPlay 시 메시 출력
    PrintWelcomeMessage();
}

// Called every frame
void AMyAwesomeActor::Tick(float DeltaTime)
{
    Super::Tick(DeltaTime);

}

void AMyAwesomeActor::PrintWelcomeMessage()
{
    if (GEngine)
    {
        GEngine->AddOnScreenDebugMessage(-1, 5.f, FColor::Green, WelcomeMessage);
    }
    UE_LOG(LogTemp, Warning, TEXT("%s"), *WelcomeMessage);
}

몇 가지 주요 변경사항과 설명을 덧붙이자면:

• UStaticMeshComponent 추가: 액터에 시각적인 형태를 부여하기 위해 UStaticMeshComponent를 추가했습니다. 생성자에서 CreateDefaultSubobject를 사용하여 컴포넌트를 생성하고, RootComponent로 설정하여 액터의 위치와 회전을 결정하는 기준점으로 만들었습니다.
• WelcomeMessage (UPROPERTY): 블루프린트에서 편집 가능하도록 UPROPERTY(EditAnywhere, BlueprintReadWrite)로 선언했습니다. 초기값은 생성자에서 Hello from C++!로 설정했습니다.
• PrintWelcomeMessage (UFUNCTION): 블루프린트에서 호출 가능하도록 UFUNCTION(BlueprintCallable)로 선언했습니다. 이 함수는 화면에 디버그 메시지를 출력하고, 로그에도 기록합니다.
• #include "Engine/Engine.h": GEngine 전역 객체에 접근하여 화면에 메시지를 출력하기 위해 이 헤더를 포함해야 합니다.

C++ 선언이 블루프린트에서 어떻게 보이는지는 매크로와 specifier 조합으로 결정됩니다.

C++ 클래스 컴파일

코드를 수정한 후에는 반드시 컴파일해야 합니다.

언리얼 에디터로 돌아가서 상단의 Compile (컴파일) 버튼을 클릭합니다.

또는 비주얼 스튜디오에서 Ctrl + Shift + B를 눌러 솔루션을 빌드할 수도 있습니다.

성공적으로 컴파일되면, 여러분이 작성한 C++ 코드가 엔진에 반영됩니다.

C++ 클래스 기반으로 블루프린트 클래스 생성

이제 C++ 클래스를 컴파일했으니, 이를 기반으로 블루프린트 클래스를 생성합니다.

블루프린트에서 C++ 속성 및 함수 확인/수정

이제 BP_MyAwesomeActor 블루프린트 클래스를 더블 클릭하여 블루프린트 에디터를 엽니다.

핵심 포인트: C++ 선언, 컴파일(UHT), 블루프린트 반영 확인, 런타임 테스트를 한 루프로 묶어야 노출 누락을 빠르게 잡을 수 있습니다.

레벨에 배치 및 테스트

블루프린트 클래스까지 만들고 내용을 확인했으니, 이제 레벨에 배치하고 테스트해봅시다.

화면 좌측 상단에 블루프린트에서 변경한 WelcomeMessage가 출력되면 정상입니다.

이는 C++로 기본 기능을 구현하고, 블루프린트에서 이를 확장해 데이터를 변경한 결과입니다.

실무에서는 여기서 끝내지 않고, C++ 선언부터 레벨 테스트까지 한 바퀴를 다시 돌며 노출 누락과 기본값 반영 여부를 점검합니다.

작업을 반복할수록 C++과 블루프린트의 책임 경계를 명확히 유지해야 협업과 디버깅 비용이 줄어듭니다.

정리: C++과 블루프린트의 시너지

이 실습을 통해 여러분은 C++ 클래스를 생성하고, UPROPERTY와 UFUNCTION 매크로를 사용하여 속성과 함수를 정의한 다음, 이를 블루프린트에서 상속받아 시각적으로 확장하고 조작하는 과정을 직접 경험했습니다.

언리얼 엔진에서는 성능이 중요한 핵심 로직을 C++로 작성하고, 콘텐츠 조정이나 빠른 반복이 필요한 부분을 블루프린트로 노출하는 식으로 역할을 나눌 수 있습니다.

다음 절에서는 이제 막 만들어본 우리의 C++ 클래스 내에서 BeginPlay, Tick과 같은 액터의 수명 주기 함수들을 활용하여 실제 동작을 구현하는 방법을 더 자세히 알아보겠습니다.

C++ 기본 구현과 Blueprint 조정이 어디서 만나는지 마지막 루프로 확인해 봅니다.