Unreal Engine 모듈 · 플러그인 개발LESSON 29

Blueprint 노출 API와 C++ 확장 지점 설계

난이도심화

예상 시간135분

선수지식28강의 Runtime 상호작용 Component

29강. Blueprint 노출 API와 C++ 확장 지점 설계

1. 이번 강의에서 해결할 문제

BlueprintReadWrite와 BlueprintCallable을 많이 붙이면 사용하기 쉬워 보이지만, 외부 Blueprint가 내부 상태를 임의로 바꾸며 불변 조건을 깨뜨릴 수 있습니다. 반대로 C++만 허용하면 디자이너가 프롬프트와 효과를 조정하기 어렵습니다. 확장 가능한 지점과 보호해야 할 책임을 구분해야 합니다.

2. 학습 목표

3. 핵심 개념

Blueprint API는 가능한 모든 내부 기능이 아니라 사용자가 수행해도 안전한 계약입니다.

BlueprintPure: 부작용 없는 조회
BlueprintCallable: 검증을 거치는 명령
BlueprintNativeEvent: C++ 기본 구현이 있고 Blueprint가 정책을 확장
Dynamic Multicast Delegate: 상태 변화 사실을 여러 UI·효과 소비자에게 알림

내부 CurrentTarget은 읽을 수 있지만 직접 쓸 수 없게 하고, 변경은 Trace·검증 경로만 거치게 합니다.

4. 단계별 실습

Interface에 C++ 기본 구현을 제공합니다.

Public/Interaction/Interactable.h의 안전한 계약
UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category="Interaction")
bool CanInteract(AActor* InstigatorActor) const;

UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category="Interaction")
FText GetInteractionPrompt(AActor* InstigatorActor) const;

UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category="Interaction")
void Interact(AActor* InstigatorActor);

Private/Interaction/Interactable.cpp
#include "Interaction/Interactable.h"

bool IInteractable::CanInteract_Implementation(
    AActor* InstigatorActor) const
{
    return IsValid(InstigatorActor);
}

FText IInteractable::GetInteractionPrompt_Implementation(
    AActor* InstigatorActor) const
{
    return NSLOCTEXT("ReusableInteraction", "DefaultPrompt", "Interact");
}

void IInteractable::Interact_Implementation(
    AActor* InstigatorActor)
{
}

Component의 Public Header에서는 쓰기 가능한 상태를 공개하지 않습니다.

Public API의 의도
UFUNCTION(BlueprintCallable, Category="Interaction")
bool TryInteract();                    // 명령: 내부에서 다시 검증

UFUNCTION(BlueprintPure, Category="Interaction")
AActor* GetCurrentTarget() const;      // 조회: 외부 변경 불가

UPROPERTY(BlueprintAssignable, Category="Interaction")
FInteractionTargetChanged OnTargetChanged; // 통지: UI는 구독만 함

멀티플레이 확장을 위해 네트워크 전송 자체보다 판정 경계를 먼저 분리합니다.

확장 가능한 C++ 판정 함수
protected:
    virtual bool CanRequestInteraction(
        const AActor* Requester,
        const AActor* Target) const;

    virtual void ExecuteValidatedInteraction(
        AActor* Requester,
        AActor* Target);

소비 프로젝트의 Network Component가 Server RPC를 소유하고 위 검증 함수를 호출할 수 있습니다. 이때 RPC 호출 가능 여부는 Ownership에 영향을 받으며, 서버는 거리·Line of Sight·Target 유효성을 다시 확인합니다. Plugin 기본 과정이 특정 Network Framework를 강제하지 않도록 Core Runtime과 Network Adapter를 분리할 수도 있습니다.

5. 코드가 동작하는 이유

Blueprint는 프롬프트 문구와 구체 상호작용 동작을 쉽게 확장하지만, 대상 검색과 상태 변경은 Component의 C++ 경로를 통과합니다. Delegate는 UI가 Component에 강하게 결합되지 않고 변화에 반응하도록 합니다. 이 구조는 API 표면을 작게 유지해 향후 내부 구현을 바꾸기 쉽게 합니다.

6. 자주 하는 실수와 해결법

7. 직접 실습

8. 이해 점검 질문 3개

9. 핵심 요약

MINI QUIZ