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

플러그인 구조와 .uplugin Descriptor 파일

난이도심화

예상 시간90분

선수지식13강의 Plugin 발견·로드 진단

14강. 플러그인 구조와 .uplugin Descriptor 파일

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

플러그인 폴더는 복사됐지만 Browser에 나타나지 않거나, Runtime과 Editor Module Type이 뒤바뀌어 패키징 대상에 Editor Binary를 요구합니다. .uplugin은 설명 문구만 담는 파일이 아니라 Engine, Editor와 UBT가 Plugin을 발견하고 Module을 선택하는 입력입니다.

2. 학습 목표

3. 핵심 개념

Engine은 Plugin 검색 경로 아래 .uplugin 파일을 찾아 Descriptor를 읽습니다. 코드 Plugin은 Source/<ModuleName>/<ModuleName>.Build.cs와 Modules 항목이 대응해야 합니다. Binaries와 Intermediate는 빌드 산출물이며 Source 배포의 기준 파일이 아닙니다.

ReusableInteraction/
├─ ReusableInteraction.uplugin
├─ Config/DefaultReusableInteraction.ini
├─ Resources/Icon128.png
└─ Source/ReusableInteraction/
   ├─ ReusableInteraction.Build.cs
   ├─ Public/
   └─ Private/

4. 단계별 실습

ReusableInteraction.uplugin
{
  "FileVersion": 3,
  "Version": 1,
  "VersionName": "1.0.0",
  "FriendlyName": "Reusable Interaction",
  "Description": "Project-independent runtime interaction contracts and scanning.",
  "Category": "Gameplay",
  "CreatedBy": "StartBook Learner",
  "CanContainContent": false,
  "IsBetaVersion": true,
  "Installed": false,
  "Modules": [
    {
      "Name": "ReusableInteraction",
      "Type": "Runtime",
      "LoadingPhase": "Default"
    }
  ]
}

DataGuard.uplugin
{
  "FileVersion": 3,
  "Version": 1,
  "VersionName": "1.0.0",
  "FriendlyName": "Data Guard",
  "Description": "Editor-only asset validation and audit tools.",
  "Category": "Editor",
  "CanContainContent": false,
  "IsBetaVersion": true,
  "Installed": false,
  "Modules": [
    {
      "Name": "DataGuardEditor",
      "Type": "Editor",
      "LoadingPhase": "PostEngineInit"
    }
  ]
}

Module Type의 세부 유효 값과 Platform·Target Allow/Deny 필드는 UE 버전의 FModuleDescriptor를 확인합니다. AdditionalDependencies보다 실제 C++ 의존성은 Build.cs에서 선언합니다.

5. 코드가 동작하는 이유

PluginManager는 Descriptor를 발견하고 UBT와 ModuleManager는 현재 Target에 맞는 Modules 항목을 선택합니다. CanContainContent가 true면 Plugin Content Mount가 가능하지만, 에셋을 넣었다는 사실만으로 Cook에 반드시 포함되는 것은 아니므로 참조와 Packaging 규칙을 별도 검증합니다.

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

7. 직접 실습

8. 이해 점검 질문 3개

9. 핵심 요약

MINI QUIZ