2026-06-22 TIL (81일차)
모듈(Module)과 플러그인(Plugin)
1. 모듈(Module): 언리얼 엔진의 최소 조립 단위
언리얼 엔진은 거대한 하나의 통짜 프로그램이 아니라, 수많은 ‘레고 블록(모듈)’들이 조립된 형태입니다. (내부적으로는 각각이 하나의 DLL 파일로 컴파일됩니다.)
왜 이렇게 설계되었을까?
프로젝트가 커질수록 모든 코드를 한 곳에 몰아넣으면 컴파일 속도가 기하급수적으로 느려지고 코드 간의 충돌이 발생합니다. 기능별로 모듈을 쪼개면 수정한 모듈만 독립적으로 컴파일할 수 있어 유지보수와 협업에 압도적으로 유리해집니다.
구현 원리 및 작동 방식
새로운 모듈을 만들기 위해 Source/Test 폴더를 생성하고 다음 파일들을 구성했습니다.
- —.Build.cs: 언리얼의 고유 빌드 시스템(UBT)에게 보내는 ‘부품 명세서’입니다. “이 Test 블록을 컴파일하려면 Core, Engine 같은 엔진 기본 블록이 필요해!”라고 알려줍니다.
- IMPLEMENT_MODULE 매크로 (Test.cpp): 엔진의 심장부(Core)에 “여기 Test라는 모듈이 새로 생겼으니 로드해 줘!”라고 출생신고를 하는 필수 코드입니다. 이게 없으면 폴더가 존재해도 엔진이 무시합니다.
주의점: 대소문자 구분 C++와 언리얼 빌드 툴(UBT)은 대소문자에 매우 민감합니다. 폴더명, 파일명, 코드 내부의 모듈 이름이 한 글자라도 다르면 즉시 빌드 에러가 발생합니다.
2. 본체에 모듈 연결하기: *.Target.cs 와 .uproject
레고 블록(Test 모듈)을 만들었으니, 이제 본체(프로젝트)에 끼워 넣어 엔진과 에디터가 이를 인식하게 만들어야 합니다.
⚙️ 어떻게 작동하나요?
- *.Target.cs 파일: 게임을 최종적으로 패키징(빌드)할 때 어떤 모듈들을 뭉쳐서 하나의 실행 파일(.exe)로 만들지 결정합니다.
ExtraModuleNames에"Test"를 추가하여 우리 모듈을 배포 파일에 포함시킵니다. - .uproject 파일: 프로젝트의 전반적인 ‘설계도’입니다. 언리얼 에디터가 처음 켜질 때 이 JSON 파일을 읽어 들여 “아, 이 프로젝트는 ModuleAndPlugin 모듈뿐만 아니라 Test 모듈도 함께 로드해야 하는구나” 하고 파악합니다. (
LoadingPhase설정을 통해 로드 순서도 제어 가능합니다.)
** 주의점: JSON 문법 지옥**
.uproject는 JSON 포맷입니다. 항목 사이에 쉼표(,)가 반드시 들어가야 하며, 마지막 항목 뒤에는 쉼표가 없어야 합니다. 쉼표 하나만 실수해도 에러가 나며 프로젝트가 열리지 않습니다.
3. 모듈 간 상호작용: 의존성(Dependency) 추가
기본 모듈의 캐릭터 클래스에서 우리가 만든 Test 모듈의 TestActor를 소환(Spawn)해야 했습니다. 하지만 언리얼의 모듈들은 기본적으로 철저히 격리된 공간에 있어서 남의 코드를 마음대로 참조할 수 없습니다.
의존성(Dependency)의 개념
격리된 모듈의 기능을 가져다 쓰려면 통행증이 필요합니다.
ModuleAndPlugin.Build.cs파일의PublicDependencyModuleNames목록에"Test"를 추가합니다.- 이는 컴파일러에게 “우리 기본 모듈이 앞으로 Test 모듈의 코드(헤더 파일)를 참조할 테니 허락해 줘!”라고 선언하는 것입니다. 이 설정이 끝나야
#include "TestActor.h"를 작성했을 때 컴파일 에러가 발생하지 않습니다.
주의점: Generate Visual Studio project files
Build.cs,Target.cs,.uproject같은 시스템 설정 파일을 수정했다면, 반드시 프로젝트 폴더에서 우클릭하여 ‘Generate Visual Studio project files’를 실행해야 합니다. 이 과정을 거쳐야 Visual Studio 솔루션이 새로운 구조를 파악하고 갱신됩니다.
4. 재사용성의 끝판왕: 플러그인(Plugin)
모듈의 개념을 확장하여, 아예 다른 프로젝트에도 손쉽게 이식할 수 있는 임시(Temporary) 플러그인을 만들어 보았습니다.
모듈과 플러그인의 결정적 차이
| 구분 | 모듈 (Module) | 플러그인 (Plugin) |
|---|---|---|
| 구성 요소 | 순수한 소스 코드(C++)의 묶음 | 소스 코드(모듈) + 에셋(Content)의 결합 |
| 종속성 | 특정 프로젝트 안에 강력하게 종속됨 | 프로젝트와 무관하게 독립적으로 작동 |
| 활용도 | 프로젝트 내부의 로직 분리 (네트워크, UI 등) | 마켓플레이스 판매, 타 프로젝트로의 기능 복사/이식 |
어떻게 작동하나요?
- Plugins/Temporary 폴더 구조: 플러그인은 그 자체로 하나의 작은 프로젝트와 같습니다. 코드가 들어가는
Source폴더와 블루프린트, 머티리얼 등이 들어가는Content폴더를 독자적으로 가집니다. - Temporary.uplugin: 플러그인의 명함입니다. 이름, 버전, 어떤 모듈들을 포함하고 있는지 엔진에 알려줍니다.
- 플러그인 폴더를 통째로 복사해서 다른 언리얼 프로젝트의
Plugins폴더에 붙여넣기만 하면, 코딩이나 세팅 없이도 해당 기능과 에셋을 바로 사용할 수 있습니다.
주의점: 엄격한 폴더 뎁스(Depth) 플러그인의 폴더 구조는 매우 엄격합니다. 반드시
Plugins/플러그인이름/Source/모듈이름/순서로 계층이 정확히 맞아야 언리얼 빌드 툴이 정상적으로 소스 코드를 찾고 컴파일할 수 있습니다.