[Unreal Engine 5] UFUNCTION()와 지정자(Specfier)들

1. 개요

언리얼 엔진의 리플렉션 시스템(Reflection System)이 C++ 함수를 인식하게 만드는 매크로. 이를 통해 C++ 함수를 블루프린트에서 호출하거나, 네트워크로 복제(RPC)하거나, 콘솔 명령어로 실행할 수 있다.

2. 주요 지정자 치트 시트 (Cheat Sheet)

A. 블루프린트 연동 (Blueprint Interaction)

기획자와 아티스트가 블루프린트 그래프에서 함수를 사용할 수 있게 노출함.

B. 에디터 및 디버깅 (Editor & Debug)

C. 네트워크 (Network RPC)

---

3. 핵심 코드 패턴 (Code Patterns)

헤더 파일 (.h)

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

public:
    // 1. 일반적인 액션 함수 (BP에서 호출)
    UFUNCTION(BlueprintCallable, Category = "Combat")
    void Attack();

    // 2. 데이터 조회 함수 (실행 핀 없음, const 필수)
    UFUNCTION(BlueprintPure, Category = "Stats")
    float GetHealth() const;

    // 3. 하이브리드 함수 (C++ 기본 로직 + BP 수정 가능)
    // 주의: Virtual을 쓰지 않음 (내부적으로 처리됨)
    UFUNCTION(BlueprintNativeEvent, Category = "Interaction")
    void Interact();

    // 4. 에디터 테스트용 버튼
    UFUNCTION(CallInEditor, Category = "Debug")
    void DebugFullHeal();
};

소스 파일 (.cpp)

// 1. BlueprintCallable: 일반 함수처럼 구현
void AMyCharacter::Attack()
{
    // 공격 로직
}

// 2. BlueprintPure
float AMyCharacter::GetHealth() const
{
    return Health;
}

// 3. BlueprintNativeEvent: '_Implementation' 접미사 필수!
// 헤더에는 void Interact(); 라고 썼지만, 구현부는 아래와 같음.
void AMyCharacter::Interact_Implementation()
{
    // C++ 기본 상호작용 로직 (BP가 오버라이드 안 하면 이거 실행됨)
    UE_LOG(LogTemp, Log, TEXT("Default C++ Interaction"));
}

// 4. CallInEditor
void AMyCharacter::DebugFullHeal()
{
    Health = MaxHealth;
}

---

4. 주의사항 및 팁

1. 접미사 규칙 (_Implementation):
   • BlueprintNativeEvent와 Server, Client 등의 RPC 함수는 .cpp 파일 구현 시 함수 이름 뒤에 반드시 _Implementation을 붙여야 한다. (엔진이 생성한 generated 코드와 충돌 방지)
2. Category 정리:
   • Category = "MyCategory | Sub" 처럼 파이프(|)를 쓰면 블루프린트 메뉴에서 계층 구조로 깔끔하게 정리된다.
3. const의 중요성:
   • BlueprintPure는 논리적으로 값을 변경하면 안 되므로 C++ 함수 뒤에 const를 붙이는 것이 안전하다.
4. IDE 활용:
   • Rider나 VS에서 헤더 선언 후 Alt + Enter (Generate definition)를 하면 _Implementation이 붙은 올바른 스텁을 자동 생성해 준다.