[Unreal Engine 5] Module과 Plugin의 차이점

언리얼 엔진 5(UE5)로 프로젝트를 진행하며 커스텀 로그 시스템을 구축하던 중, 코드를 논리적으로 분리하는 단위인 모듈(Module)과 플러그인(Plugin)의 차이점을 명확히 알게 되었다. 이 둘의 구조적 차이와 의존성 설정 방법을 정리해 본다.

1. 개념 및 설계

가장 큰 차이는 포함할 수 있는 요소의 범위와 재사용성에 있다.

• 모듈 (Module):
  • 언리얼 엔진에서 C++ 코드를 컴파일하는 최소 단위.
  • 순수하게 C++ 코드(.h, .cpp, .Build.cs)로만 구성되며 에셋(블루프린트, 머티리얼 등)을 가질 수 없다.
  • 비유하자면 코드가 적힌 '책 한 권'.
• 플러그인 (Plugin):
  • 하나 이상의 모듈과 에디터 에셋(Content)을 하나로 묶어놓은 배포 및 기능의 단위.
  • 다른 프로젝트로 그대로 복사해서 붙여넣기만 해도 독립적으로 작동한다. (.uplugin 파일로 관리)
  • 비유하자면 여러 권의 책(모듈)과 그림 자료(에셋)를 담고 있는 '책장'.

2. 헤더(.h) 및 의존성 관리 (Dependencies)

시스템 간의 결합도를 낮추기 위해 의존성은 철저하게 관리되어야 한다.

• Build.cs 설정: 메인 게임 모듈에서 커스텀 플러그인(예: MySpartaLog)의 기능을 사용하려면, 메인 모듈의 .Build.cs 파일 내 PublicDependencyModuleNames에 해당 플러그인 모듈의 이름을 문자열로 추가해야 한다.
• 순환 참조(Circular Dependency) 주의: 플러그인은 절대 게임 메인 모듈을 참조해서는 안 된다. 플러그인은 다른 프로젝트에서도 쓰일 수 있도록 독립적이어야 하기 때문이다.
• 전방 선언(Forward Declaration): 컴파일 시간을 최적화하기 위해, 헤더 파일(.h)에서 다른 모듈의 클래스를 사용할 때는 #include 대신 class UMyPluginClass; 형태로 전방 선언을 하고, 실제 헤더 포함은 소스 파일(.cpp)에서 진행한다.

3. 소스(.cpp) 및 컴파일 관점 (Implementation)

각 모듈은 컴파일러(UBT)가 진입점을 알 수 있도록 매크로를 통해 구현된다.

• 게임의 메인 모듈은 소스 파일에 IMPLEMENT_PRIMARY_GAME_MODULE 매크로를 사용한다.
• 플러그인 내부의 일반 하위 모듈들은 IMPLEMENT_MODULE 매크로를 사용하여 엔진에 자신을 등록한다.

4. 에디터 설정 및 라이더(Rider) 활용 팁

• .uproject vs .uplugin:
  .uproject 파일의 "Modules" 배열에는 프로젝트의 Source/ 폴더 아래에 있는 메인 모듈들만 명시해야 한다. 플러그인 내부의 모듈을 이곳에 적으면 UnrealBuildTool failed with exit code 0x00000009 (ActionGraphInvalid) 오류가 발생하며 IDE에서 코드가 '제외됨' 처리된다.
• JetBrains Rider 단축키 팁 (Visual Studio 2022 키맵 기준):
  • 다른 모듈의 헤더가 필요할 때 커서를 대고 Alt + Enter (Quick Fix)를 누르면 자동으로 알맞은 모듈의 헤더를 #include 해준다.
  • 전체 심볼 검색 Ctrl + T를 통해 플러그인과 메인 모듈을 넘나들며 클래스를 쉽게 찾을 수 있다.