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

Unreal Build Tool과 UnrealHeaderTool의 빌드 흐름

난이도심화

예상 시간80분

선수지식1강의 모듈·플러그인 경계

2강. Unreal Build Tool과 UnrealHeaderTool의 빌드 흐름

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

IDE가 헤더를 찾지 못하면 Include 경로만 계속 추가하고, *.generated.h 오류가 나면 Intermediate 파일을 직접 수정하는 경우가 있습니다. 그러나 UBT의 규칙 평가, UHT의 Reflection 생성, 컴파일과 링크는 서로 다른 단계입니다. 첫 실패 단계를 구분하지 않으면 증상만 옮겨 다닙니다.

2. 학습 목표

3. 핵심 개념

UBT는 .Target.cs, .Build.cs, .uproject와 .uplugin을 읽어 현재 Target에 포함할 모듈과 컴파일 환경을 결정합니다. Reflection 매크로가 있는 헤더가 발견되면 UHT가 generated.h와 등록 코드를 생성합니다. 이후 C++ 컴파일러가 각 Translation Unit을 컴파일하고 링커가 모듈 Binary를 만듭니다.

Target 선택
  → Descriptor와 ModuleRules 평가
  → Header Tool 대상 수집
  → UHT Reflection 코드 생성
  → C++ 컴파일
  → 모듈 링크
  → Editor/Game이 Descriptor의 LoadingPhase에 따라 로드

IDE Solution은 탐색 도구입니다. 실제 포함 모듈과 Definition은 UBT 규칙이 결정합니다. Solution에 파일이 보인다고 Target에 링크되는 것은 아닙니다.

4. 단계별 실습

Public/InteractionProfile.h
#pragma once

#include "CoreMinimal.h"
#include "InteractionProfile.generated.h" // Reflection 선언의 마지막 include

USTRUCT(BlueprintType)
struct REUSABLEINTERACTION_API FInteractionProfile
{
    GENERATED_BODY()

    UPROPERTY(EditAnywhere, Category="Interaction", meta=(ClampMin="0.0"))
    float MaxDistance = 350.0f;
};

일부러 generated.h 뒤에 다른 헤더를 Include하거나 UPROPERTY 타입의 선언을 누락해 UHT 오류를 확인합니다. 다음으로 구현한 함수 정의를 CPP에서 제거해 링크 오류를 만듭니다.

로그 특징	실패 단계	첫 확인 위치
Reflection specifier, generated header, unknown reflected type	UHT	UCLASS/USTRUCT와 generated include 순서
Cannot open include file, incomplete type	C++ 컴파일	Build.cs 의존성과 헤더 위치
unresolved external symbol	링크	API 매크로, 함수 정의, 모듈 의존성
module could not be loaded, missing import	로드	Binary, Descriptor Type·LoadingPhase, 선행 모듈

빌드 로그에서 마지막 오류가 아니라 가장 먼저 발생한 의미 있는 오류를 기록합니다. Live Coding이 이전 Binary를 유지할 수 있으므로 모듈 구조와 UHT 선언 변경 뒤에는 Editor를 닫고 전체 Editor Target 빌드를 사용합니다.

5. 코드가 동작하는 이유

GENERATED_BODY는 UHT가 만든 등록·직렬화·Reflection 코드를 클래스나 구조체에 연결합니다. generated.h는 입력 헤더의 선언에 대응하므로 직접 수정해도 다음 생성에서 사라집니다. 원본 Header와 ModuleRules를 고쳐야 빌드 그래프 전체가 재현됩니다.

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

7. 직접 실습

8. 이해 점검 질문 3개

9. 핵심 요약

MINI QUIZ