[UE] Unreal Engine Module

'Module'은 독립적으로 실행 가능한 코드 단위로 캡슐화한 것으로 Unreal Engine의 소프트웨어 아키텍처의 기본 구성요소이다. DLL(Dynamic Link Libaray)과  비슷한 개념으로 현 시점 Unreal Engine은 1000개가 넘은 Module로 구성된다.

 

Unreal Engine Document - How to make a gameplay module

---

Module을 사용하는 이유?

Unreal Engine Module은 코드를 정리하고, 프로젝트의 빌드 시간을 단축하고, 시스템 및 코드의

로드 / 언로드 프로세스를 설정할 수 있는 유용한 수단이다. 

 

1. 코드 분리를 통해 기능을 캡슐화하고 코드의 내부 기능을 숨기는 수단을 제공한다.

2. 변경된 Module에 대해서만 컴파일을 진행하여 빌드 시간이 단축된다.

3. 프로젝트에 사용되지 않은 Module은 컴파일에서 제외되어 빌드 시간이 단축 된다.

4. Module의 로드 / 언로드 시기를 제어할 수 있어 프로젝트의 성능 최적화가 가능하다.

5. 특정 조건(플랫폼 등)에 따라 프로젝트의 포함하거나 제외할 수 있다.

 

 

---

Module 생성

모듈을 생성하기 위해서는 C++ 프로젝트로 지정해야 한다.

블루프린트만 사용한 프로젝트로 진행할 경우, Unreal Editor에서 C++ 프로젝트로 변환해야 한다.

Unreal Engine Module을 생성하는 과정은 아래와 같다.

 

1. 디렉토리 구성

모든 Module은 Plugin 또는 Source 디렉토리에 배치되어야 한다.

또한 디렉토리의 이름은 Module의 이름과 같아야 한다.

아래는 Module에 권장되는 폴더 구조의 예시이다.

Source 폴더 내의 모든 하위 디렉토리에 Module을 여러 수준의 깊이로 배치 할 수 있다.

이를 통해 서브디렉토리를 사용하여 Module의 그룹화가 가능하다.

 

- [Project Name]

        - Source

                - [ Project Name ].Target.cs

                - [ Project Name ]Editor.Target.cs

                - [ Primary Modlue Name ] (프로젝트에 기본적으로 포함된 Module)

                        - [ Primary Modlue Name ].Build.cs

                        - Private

                                - [ Primary Modlue Name ].cpp

                        - Public

                                - [ Primary Modlue Name ].h

                        - 게임 모듈에 포함된 기타 C++ 클래스

 

                - [ New Module Name ] -> 새로 생성한 Module

                        - [ New Module Name  ].Build.cs

                        - Private

                                - [ New Module Name  ].cpp

                        - Public

                                - [ New Module Name ].h

 

 

---

2. [ Module Name ].Build.cs 파일에서 종속성 구성

언리얼 빌드 툴(Unreal Build Tool, UBT) 에서 종속성을 확인하기 위해 프로젝트의 디렉토리를 살펴볼 경우

IDE 솔루션 파일을 무시하고 Source 폴더에 있는 Build.cs 파일을 확인한다.

즉, 언리얼 빌드 툴이 Module 을 식별하기 위해서는 Build.cs 파일이 필요하다.

Unreal Engine Document - Module Property

 

Module 의 루트 디렉토리에 [ Module Name ].Build.cs 파일을 생성 후 다음 코드를 추가한다.

빌드 방식 제어, 종속성 구성, 부가 라이브 러리 및 Include 경로 등을 설정할 수 있다.

using UnrealBuildTool;

public class [ New Module Name ] : ModuleRules
{
	public [ New Module Name ](ReadOnlyTargetRules Target) : base(Target)
	{
		PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;

        PublicIncludePaths.AddRange(new string[] { ... });

        PublicDependencyModuleNames.AddRange(new string[] { ... });

		PrivateDependencyModuleNames.AddRange(new string[] { ... });
	}
}

 

생성자의 첫 줄에 PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs 구문은 'IWYU' 관련 내용으로

다음 링크에서 확인할 수 있다. Unreal Engine Document - Include What You Use

 

 

---

3. C++ 에서 모듈 구현

[ Module Name ].Build.cs 파일이 있으면 Unreal Build Tool 이 Module 을 발견할 수 있지만

Unreal Engine 프로젝트에서 로드 및 언로드 하기 위해서는 Module 을 C++ 클래스 형태로 구현해야 한다.

                                               ( C++ 코드에서 사용하기 위해서는 )

 

Module 의 루트 디렉토리에 [ Module Name ].cpp 파일을 생성 후 다음 코드를 추가한다.

IMPLEMENT_PRIMARY_GAME_MODULE 매크로를 사용해서 Module 을 등록한다.

Unreal Engine 에서 C++ 프로젝트를 생성 시 기본적으로 생성되는 Module 을 확인해 보면 .cpp 파일 뿐 아니라

.h 파일도 구현되어 있다. 하지만 대부분의 게임 플레이 Module 은 아래 기본 구현만으로도 모듈을 로드 및 언로드 할 수 있다. Unreal Engine 5.3 Document 에 따르면 .h 굳이 생성하지 않아도 된다고 한다.

 

만약 Module 의 클래스, 생성자, 시작 및 종료 함수를 직접 작성하여 훨씬 디테일한 구현을 생성하고자 한다면

.h 파일을 생성하는 것 같다.

 

또한 C++ 로 구현한 Module 의 이름에는 접미사로 Module 을 붙여주는 것이 규약이다.

ex) [ Module Name ]Module.h   /  [ Module Name ]Module.cpp

#include "Modules/ModuleManager.h"

IMPLEMENT_PRIMARY_GAME_MODULE( FDefaultGameModuleImpl, [ Module Name ], "[Game Name]" );

 

 

---

4. Module 컴파일

프로젝트의 루트 디렉토리에 [ Project Name ].uproject 를 우클릭 한 뒤 Unreal Build Tool 을 실행시켜

IDE 솔루션을 생성한다. Module 의 코드를 및 [ Module Name ].Build.cs 파일을 수정한 경우에도 위 과정을 통해

최신 상태를 유지 시켜 주어야 한다.

 

직접 새 모듈 추가, 모듈 디렉터리 구조 변경, C++ 파일을 이동 또는 이름 바꾸기, 모듈의 종속성 변경 같은 작업을 수행할 때마다 프로젝트 파일을 재생성하여 Visual Studio 솔루션을 업데이트한 뒤 프로젝트를 다시 컴파일해야 한다.

 

 

---

5. 프로젝트에 Module 포함

프로젝트의 루트 디렉토리에  [ Project Name ].uproject 의 모듈에 대한 종속성을 만들어야 한다.

텍스트 에디터에서 [ Project Name ].uproject 를 실행한 뒤 다음 내용을 수정한다.

{
	"FileVersion": 3,
	"EngineAssociation": "5.3",
	"Category": "",
	"Description": "",
	"Modules": [
		{
			"Name": "[ Primary Module ]",
			"Type": "Runtime",
			"LoadingPhase": "Default"
		},
        {
			"Name": "[ New Module ]",
			"Type": "Runtime",
			"LoadingPhase": "Default"
		}
	],
	"Plugins": [
		{
			"Name": "ModelingToolsEditorMode",
			"Enabled": true,
			"TargetAllowList": [
				"Editor"
			]
		}
	]
}