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

API 매크로와 모듈 경계를 넘는 클래스 접근

난이도심화

예상 시간80분

선수지식5강의 Public Header 계약

6강. API 매크로와 모듈 경계를 넘는 클래스 접근

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

Public Header가 보이고 컴파일도 일부 통과하지만 소비 모듈 링크에서 unresolved external symbol이 발생합니다. 같은 모듈 안에서는 호출되던 생성자와 함수가 다른 모듈에서만 실패한다면 Header 검색보다 Binary Symbol 노출을 확인해야 합니다.

2. 학습 목표

3. 핵심 개념

UE 모듈이 개별 DLL로 빌드되는 구성에서는 구현 모듈이 Symbol을 Export하고 소비 모듈이 Import해야 합니다. UBT는 모듈 이름에서 REUSABLEINTERACTION_API 같은 매크로를 만들고 빌드 문맥에 따라 플랫폼별 Export/Import 지정으로 바꿉니다.

Public 폴더는 Header를 찾게 하고, PublicDependency는 소비 환경을 전파하며, API 매크로는 Binary Symbol을 연결합니다. 세 조건 중 하나라도 빠지면 다른 종류의 오류가 발생합니다.

4. 단계별 실습

Public/Interaction/InteractionResult.h
#pragma once

#include "CoreMinimal.h"
#include "InteractionResult.generated.h"

USTRUCT(BlueprintType)
struct REUSABLEINTERACTION_API FInteractionResult
{
    GENERATED_BODY()

    UPROPERTY(BlueprintReadOnly)
    TObjectPtr<AActor> Target = nullptr;

    UPROPERTY(BlueprintReadOnly)
    float Distance = 0.0f;

    bool IsValid() const;
};

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

bool FInteractionResult::IsValid() const
{
    return IsValid(Target) && Distance >= 0.0f;
}

소비 모듈에서 FInteractionResult::IsValid를 호출해 링크를 검증합니다. API 매크로를 제거했을 때 Monolithic 구성에서는 우연히 통과할 수 있으므로 Editor Modular 빌드와 실제 소비 모듈을 사용합니다.

MinimalAPI는 Reflection에 필요한 최소 class Symbol만 노출하는 선택입니다. 외부 C++에서 비인라인 멤버 함수를 호출하거나 상속 계약을 제공한다면 필요한 함수 또는 클래스에 명시적인 API 노출이 필요합니다. 단순히 Binary 크기를 줄이기 위해 무분별하게 적용하지 않습니다.

5. 코드가 동작하는 이유

Header 선언은 컴파일러가 함수 시그니처를 알게 하지만 구현 주소를 제공하지 않습니다. 구현 모듈이 내보낸 Symbol과 소비 모듈의 Import가 링커에서 연결돼야 합니다. API 매크로는 UBT가 구성별로 이 차이를 관리하게 합니다.

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

7. 직접 실습

8. 이해 점검 질문 3개

9. 핵심 요약

MINI QUIZ