UE4 다른 모듈의 UInterface 캐스팅에서 LNK1120이 발생할 때

문제가 된 선언#

UInterface를 만들면 실제로는 두 C++ 타입이 생긴다.

• UDefaultAI: Unreal reflection에 등록되는 UObject 쪽 타입
• IDefaultAI: 게임플레이 인터페이스를 선언하는 native C++ 타입

문제가 된 코드는 모듈 API 매크로가 IDefaultAI에만 붙어 있었다.

1
#pragma once
2

3
#include "CoreMinimal.h"
4
#include "UObject/Interface.h"
5
#include "DefaultAI.generated.h"
6

7
UINTERFACE()
8
class UDefaultAI : public UInterface
9
{
10
    GENERATED_BODY()
11
};
12

13
class AI_API IDefaultAI
14
{
15
    GENERATED_BODY()
16

17
public:
18
    virtual class AAIController* GetAIController() const = 0;
19
};

다른 모듈에서 Cast<IDefaultAI>(Object) 같은 reflection 기반 경로를 사용하려면 UDefaultAI::StaticClass()와 그 내부의 GetPrivateStaticClass() 심볼도 필요하다. 그러나 UDefaultAI에는 AI_API가 없었고, modular build의 다른 DLL은 해당 심볼을 가져올 수 없었다.

두 타입 모두 export한다#

UDefaultAI와 IDefaultAI 양쪽에 인터페이스가 정의된 모듈의 API 매크로를 붙인다.

1
#pragma once
2

3
#include "CoreMinimal.h"
4
#include "UObject/Interface.h"
5
#include "DefaultAI.generated.h"
6

7
UINTERFACE()
8
class AI_API UDefaultAI : public UInterface
9
{
10
    GENERATED_BODY()
11
};
12

13
class AI_API IDefaultAI
14
{
15
    GENERATED_BODY()
16

17
public:
18
    virtual class AAIController* GetAIController() const = 0;
19
};

당시 UE4의 모듈 API 매크로는 modular build의 빌드 대상에 따라 바뀌었다.

• 타입을 정의하는 모듈을 빌드할 때: __declspec(dllexport)
• 타입을 사용하는 모듈을 빌드할 때: __declspec(dllimport)
• monolithic build일 때: 빈 매크로

이 때문에 오류는 Editor와 같은 DLL 구성에서만 드러나고, monolithic target에서는 우연히 통과할 수 있다. 특정 빌드에서 통과했다는 사실만으로 export 선언이 올바르다고 판단하면 안 된다.

Build.cs 의존성도 별도로 필요하다#

API 매크로와 모듈 의존성은 서로 대체 관계가 아니다.

1
PublicDependencyModuleNames.AddRange(new[]
2
{
3
    "Core",
4
    "CoreUObject",
5
    "Engine",
6
    "AI",
7
});

• Build.cs는 어떤 모듈의 include·link 환경을 사용할지 정한다.
• AI_API는 그 DLL에서 어떤 클래스와 함수를 외부에 공개할지 정한다.

헤더 경로가 보이는데 GetPrivateStaticClass, vtable 또는 함수 구현에서 unresolved external이 발생한다면 아래 순서로 확인한다.

1. 사용하는 모듈의 Build.cs에 정의 모듈이 들어 있는가?
2. 외부에서 쓰는 클래스·함수에 *_API 매크로가 있는가?
3. UInterface라면 U... 타입과 I... 타입을 모두 확인했는가?
4. 선언과 구현의 함수 signature가 정확히 같은가?
5. Editor DLL build와 packaged monolithic build의 차이에 가려진 문제는 아닌가?

이 사례에서는 3번이 원인이었다. 자동 생성된 코드라도 모듈 경계를 넘는 타입이라면 export 범위를 직접 검토해야 한다.

참고 자료#

• Epic Games: Module API Specifiers — UE 4.27
• Epic Games: Programming Basics — UE 4.27