UE5 Blueprint & C++ 연동

Unreal Engine에서 C++와 Blueprint는 긴밀하게 연동됩니다. 엔진 매크로(UFUNCTION, UPROPERTY, UCLASS)를 올바르게 사용하면 C++의 성능과 Blueprint의 유연성을 동시에 활용할 수 있습니다.

UFUNCTION 지정자

BlueprintCallable

Blueprint에서 호출 가능한 C++ 함수를 노출합니다.

UCLASS()
class AMyActor : public AActor
{
    GENERATED_BODY()

public:
    // Blueprint에서 호출 가능
    UFUNCTION(BlueprintCallable, Category="Combat")
    void TakeDamage(float Amount);

    // Pure Function — 실행 핀 없음 (값 반환만)
    UFUNCTION(BlueprintCallable, BlueprintPure, Category="Stats")
    float GetHealthPercent() const;

    // 월드 컨텍스트 자동 바인딩 (static 함수용)
    UFUNCTION(BlueprintCallable, Category="Utils",
              meta=(WorldContext="WorldContextObject"))
    static AMyActor* SpawnMyActor(UObject* WorldContextObject, FVector Location);
};

BlueprintImplementableEvent

C++에서 선언하고 Blueprint에서만 구현하는 이벤트입니다. C++ 바디 없이 선언만 합니다.

// C++ — 선언만 (구현 없음)
UFUNCTION(BlueprintImplementableEvent, Category="Events")
void OnEnemySpotted(AActor* Enemy);

// 호출은 C++에서 가능
void AMyAI::DetectEnemy(AActor* Enemy)
{
    OnEnemySpotted(Enemy); // Blueprint가 구현한 이벤트 호출
}

BlueprintNativeEvent

C++ 기본 구현을 제공하고 Blueprint에서 오버라이드 가능하게 합니다.

// 헤더 — 선언 (함수명 그대로)
UFUNCTION(BlueprintNativeEvent, Category="Combat")
float CalculateDamage(float BaseDamage);

// .cpp — 기본 구현 (_Implementation 접미사)
float AMyCharacter::CalculateDamage_Implementation(float BaseDamage)
{
    return BaseDamage * DamageMultiplier;
}

Blueprint에서 오버라이드하지 않으면 _Implementation이 호출됩니다.

UPROPERTY 지정자

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Stats")
float MaxHealth = 100.f;

UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category="Stats")
float MoveSpeed = 600.f;

UPROPERTY(VisibleAnywhere, BlueprintReadOnly)
UStaticMeshComponent* MeshComp;

지정자	에디터 편집	Blueprint 접근
`EditAnywhere`	인스턴스·CDO 모두	—
`EditDefaultsOnly`	CDO만	—
`EditInstanceOnly`	인스턴스만	—
`BlueprintReadWrite`	—	읽기+쓰기
`BlueprintReadOnly`	—	읽기만
`VisibleAnywhere`	읽기 전용 표시	—

Blueprint Interface (C++ 정의)

인터페이스를 C++로 정의하면 Blueprint와 C++ 모두에서 구현할 수 있습니다.

// 인터페이스 선언
UINTERFACE(MinimalAPI, Blueprintable)
class UInteractable : public UInterface
{
    GENERATED_BODY()
};

class IInteractable
{
    GENERATED_BODY()

public:
    // Blueprint에서 구현 가능
    UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="Interaction")
    void Interact(AActor* Interactor);
};

// C++에서 구현
UCLASS()
class AChest : public AActor, public IInteractable
{
    GENERATED_BODY()

public:
    virtual void Interact_Implementation(AActor* Interactor) override;
};

void AChest::Interact_Implementation(AActor* Interactor)
{
    OpenChest();
}

// 인터페이스 호출 — C++에서
if (Actor->Implements<UInteractable>())
{
    IInteractable::Execute_Interact(Actor, this);
}

Dispatch — C++에서 Blueprint 이벤트 바인딩

// 헤더 — Delegate 선언
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnHealthChanged, float, NewHealth);

UCLASS()
class AMyCharacter : public ACharacter
{
    GENERATED_BODY()

public:
    UPROPERTY(BlueprintAssignable, Category="Events")
    FOnHealthChanged OnHealthChanged;

    void SetHealth(float NewHealth)
    {
        Health = NewHealth;
        OnHealthChanged.Broadcast(Health); // Blueprint에서 바인딩한 이벤트 호출
    }

private:
    float Health = 100.f;
};

Blueprint에서 OnHealthChanged 이벤트 노드에 UI 업데이트 로직을 연결할 수 있습니다.

실무 패턴 정리

상황	권장 방식
성능 중요 로직	C++ 구현, `BlueprintCallable`로 노출
레벨 디자이너 커스텀	`BlueprintImplementableEvent`
기본값 제공 + 오버라이드 허용	`BlueprintNativeEvent`
시스템 간 결합 제거	`DECLARE_DYNAMIC_MULTICAST_DELEGATE`
컴포넌트 간 통신	Blueprint Interface (C++ 정의)