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

Unreal 프로젝트의 Target, Module, Plugin 구조 읽기

난이도심화

예상 시간75분

선수지식2강의 UBT·UHT 빌드 단계

3강. Unreal 프로젝트의 Target, Module, Plugin 구조 읽기

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

새 모듈 폴더와 Build.cs를 만들었는데 빌드되지 않거나, Editor 모듈이 Game Target에도 포함됩니다. Plugin Browser에서는 보이지만 Binary가 없어 활성화에 실패하기도 합니다. 파일 존재, Target 포함, Descriptor 로드와 의존성 연결을 한 트리에서 읽어야 합니다.

2. 학습 목표

3. 핵심 개념

Target은 Editor, Game, Client, Server 같은 최종 빌드 제품과 Configuration을 정합니다. Module은 Target에 포함되는 C++ 코드 단위입니다. Project Descriptor는 프로젝트 모듈과 활성 플러그인을, Plugin Descriptor는 플러그인의 모듈 Type·LoadingPhase와 Content 여부를 선언합니다.

ArchitectureLab/
├─ ArchitectureLab.uproject
├─ Source/
│  ├─ ArchitectureLab.Target.cs
│  ├─ ArchitectureLabEditor.Target.cs
│  ├─ ArchitectureLab/ArchitectureLab.Build.cs
│  └─ GameplaySupport/GameplaySupport.Build.cs
└─ Plugins/
   ├─ ReusableInteraction/ReusableInteraction.uplugin
   │  └─ Source/ReusableInteraction/ReusableInteraction.Build.cs
   └─ DataGuard/DataGuard.uplugin
      └─ Source/DataGuardEditor/DataGuardEditor.Build.cs

4. 단계별 실습

ArchitectureLabEditor.Target.cs
using UnrealBuildTool;
using System.Collections.Generic;

public class ArchitectureLabEditorTarget : TargetRules
{
    public ArchitectureLabEditorTarget(TargetInfo Target) : base(Target)
    {
        Type = TargetType.Editor;
        DefaultBuildSettings = BuildSettingsVersion.Latest;
        IncludeOrderVersion = EngineIncludeOrderVersion.Latest;
        ExtraModuleNames.AddRange(new[] { "ArchitectureLab", "GameplaySupport" });
    }
}

ArchitectureLab.uproject
{
  "FileVersion": 3,
  "Modules": [
    { "Name": "ArchitectureLab", "Type": "Runtime", "LoadingPhase": "Default" },
    { "Name": "GameplaySupport", "Type": "Runtime", "LoadingPhase": "Default" }
  ],
  "Plugins": [
    { "Name": "ReusableInteraction", "Enabled": true },
    { "Name": "DataGuard", "Enabled": true }
  ]
}

Plugin 모듈은 .uplugin의 Modules 목록과 일치하는 이름의 Source 디렉터리·Build.cs가 필요합니다. 프로젝트 모듈은 .uproject와 Target 의존성 체인에서 포함 여부를 확인합니다. Editor 전용 모듈을 Game Target의 ExtraModuleNames에 넣지 않습니다.

5. 코드가 동작하는 이유

UBT는 선택한 Target에서 시작해 Descriptor와 ModuleRules의 의존성 그래프를 구성합니다. Plugin Source가 있어도 해당 Plugin이 비활성화됐거나 모듈이 현재 Target Type과 맞지 않으면 빌드·로드 대상이 아닙니다. 반대로 Runtime Type은 Editor와 Game 모두에서 필요할 수 있습니다.

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

7. 직접 실습

8. 이해 점검 질문 3개

9. 핵심 요약

MINI QUIZ