UE5

[UE] UnrealEngine 빌드 과정과 Module 추가방법

CGNY 2025. 5. 30. 15:56

우선 unreal engine이 어떤 요소들로 이루어져있는지 부터 알아보자.

ue는 module, plugin, project로 구성이 되어있으며 ue에서 코드 구조를 조직화하고 확장하는데 필수적인 구성요소들로 이루어져있다.

 

Module이란

module은 에디터 툴, 런타임 기능, 라이브러리 등과 같은 기능을 담당하는 코드의 패키지이다. 

좀더 쉡게말하면 하나의 DLL처럼 동작하며, 코드 파일들을 하나의 단위로 묶어주는 역할을 한다.

각 module은 .cpp, .h를 함께 갖고있으며, 이 둘을 하나의 최소실행 단위로 생각할 수 있다.

 

module은 프로젝트, 플러그인과 같은 다른 요소에 종속적이다. 즉, 모듈은 단독적으로 동작할 수 없으며, 다른 plugin 또는 project와 함께 동작하도록 설계되어야 한다는 것이다.

 

왜 ue에서는 모듈이라는 것을 사용할때 아래 3가지의 장점이 있기 때문에 사용한다고 한다.

1. 코드 분리와 캡슐화 : 모듈을 사용하면 코드를 적절하게 분리하여 함수 기능을 캡슐화하고 코드 내부를 숨길 수있다.

2. 효율적인 컴파일 : 각 모듈은 별도의 컴파일 유닛으로 처리되므로, 변경된 모듈만 컴파일 하여 대규모 프로젝틔 빌드 시간을 단축시킨다. -> 빠른 개발속도를 얻을 수 있다.

3. 불필요한 코드 제외 : 모듈을 컴파일하는 동안 프로젝트에 사용하지 않는 모듈을 안전하게 제외할 수 있으며, 이는 불필요한 리소스 사용을 방지한다.

 

Plugin이란

언리얼 엔진의 플러그인은 개발자가 에디터 안에서 쉽게 켜고 끌 수 있는 코드와 데이터 모음을 의미한다.

엔진의 확장성과 커스터마이징을 지원하는 핵심 개념중 하나이다.

플러그인은 실험적 기능을 테스트하고, 새로운 기능을 추가하고, 엔진을 확장하는데 사용된다.

 

확장은 다양한 영역에서 이루어질 수 있는데 예를 들어 게임 로직, 에디터 툴, 그래픽 처리, 네트워킹, 데이터 처리등에서 가능하다.

이런 실험적인 기능은 먼저 외부 플러그인으로 구현되고, 충분한 검증을 거친 후 내부 모듈로 이동하는 방법을 사용한다.

 

플러그인은 여러개의 모듈로 구성할 수 있다. 모듈은 플러그인의 내부 로직을 구성하며 여러개의 플러그인을 참조할 수 있어서 엔진을 보다 강력하게 확장하는데 유리하다. uplugin파일을 통해 엔진은 pluging을 인식하고 관리힌다.

 

 

Project란

언리얼 엔진의 프로젝트는 게임을 이루는 모든 핵심 내용, 코드, 컨텐츠를 포함하는 독립적인 unit으로 볼 수 있다.

.cpp, .h로만 구성할 수 없고 여러개의 모듈과 플러그인으로 구성된다.

.uproject파일을 통해 프로젝트의 설정과 설명을 포함한다. .uproject파일은 프로젝트의 메타 데이터를 정의하고, 버젼, 의존성, 모듈, 플러그인 등의 중요한 정보를 포함한다. 이런 정보들을 통해 unreal engine은 프로젝트를 인식하고 관리할 수 있다.

 

아래 그림을 보고 이해를 돕도록 하자.

unreal engine이라는 것은 최소 하나 이상의 모듈과 플러그인으로 구성되고, 플러그인은 여러 모듈의 집합쯤이라 볼 수 있다.

 

 

실제로 .uproject를 열어서 보면 아래와 같이 Modules : 로 json형태로 모듈이 등록되어 있다.

 

UnrealEngine 컴파일 과정

우선 C++프로젝트의 경우 컴파일 과정은 '전처리 - 컴파일 - 어셈블리 과정 - 링킹 - 실행파일 생성' 정도라 볼 수 있다.

ue의 경우 '전처리 - UBT & UHT - 컴파일 과정(cpp처리) - 어셈블리 과정 - 언리얼 module - DLL 생성' 순이다.

아래에 단계적으로 설명을 하겠다.

 

1. 프로젝트 설정 및 초기화

프로젝트 폴더 안에는 .uproject파일이 존재하며, 프로젝트의 메타데이터와 모듈 정보를 담고있다.

언리얼 엔진의 실행기(UBT)는 .uproject파일을 읽어 어떤 모듈이 필요한지 파악한다. (빌드해야하는지 파악)

 

2. 모듈 설정 파일 분석(Build.cs)

각 모듈에는 ModuleName.Build.cs 파일이 존재한다. (C++ 프로젝트로 생성하면 무조건 존재한다. 블루프린트 프로젝트의 경우 모듈이 없다)

위 Build.cs파일은 UBT에 의해 읽혀서 아래의 내용들을 설정한다.

    - 의존성 모듈(PublicDependencyModuleNames, PrivateDependencyModuleNames)

    - 포함할 헤더 dir

    - PCH

    - 빌드 타입(Editor, Runtime, Develpoer 등)

 

3. UHT실행

UHT는 UCLASS, USTRUCT, UENUM, UPROPERTY, UFUNCTION등의 리플렉션 메크로를 처리한다.

header파일을 분석하여 .generated.h파일을 생성하고 이 파일은 UObject 시스템과 GC, 네트워크 리플리케이션, 블루프린트 등에서 사용된다.

UCLASS()
class MYGAME_API AMyActor : public AActor
{
    GENERATED_BODY() // UHT에 의해 내부 코드를 자동 생성
};

위 클래스를 UHT가 분석하고 해당 결과물을 'Intermediate\Build\Win64\UnrealEditor\Inc\ProjectName\UHT'라는 경로에 저장한다.

실제로 본인이 만든 클래스들에 대한 .generated.h, .cpp파일들이 있다.

 

아래 정의한 클래스는 UHT에 의해 다음과 같은 .generated.h로 만들어진다.

 

4. UBT 컴파일 단계

.Build.cs로 정의된 모듈 단위로 컴파일 계획 설정

사용하는 플랫폼 및 구성(Debug, Develpment, Shipping)에 따라 서부 설정 결정

C++ 컴파일러(cl.exe, clang, gcc 등)에 명령을 전달하여 개별 소스 파일을 컴파일

컴파일된 객체파일(.obj)를 정적라이브러리나 동적라이브러리(DLL)로 생성

 

5. 링킹

엔진 및 프로젝트의 모든 모듈이 컴파일 되면 링커가 모든 개체 파일을 결합하여 최종 실행파일 또는 에디터 바이너리 UE5Editor-MyProj.dll을 생성한다.

 

모듈 추가

unreal engine의 구성 요소와 빌드 과정을 살펴봤으니 모듈을 추가해보도록 하겠다.

엔진은 최소 한개 이상의 모듈과 플러그인으로 구성되어 있고 하나의 모듈은 Build.cs, .h, .cpp파일을 포함한 것이 모듈이라 볼 수 있다.

 

실제 사용할 모듈을 .uproject를 열어서 적어준다. 그리고 이제 모듈을 구성하기 위한 최소 단위에 해당하는 파일들을 생성해준다. 

.Build.cs, .h, .cpp

반드시 Source 및에 위처럼 파일들을 생성해주도록 하자. Visual Studio 상에서 파일과 폴더를 만들면 안되고 

'+새로만들기'를 통해 직접 확장자와 파일이름을 설정해 만들도록 하자.

내가 새롭게 추가할 모듈이름은 TestModule이다. TestModule.Build.cs파일 내부도 notepad로 열어서 위처럼 설정해준다.

 

TestModule..h는 아래처럼 작성해준다.

#pragma once
#include "CoreMinimal.h"
#include "Modules/ModuleManager.h"


class FTestModule : public IModuleInterface
{
public:
	virtual void StartupModule() override
	{

	}

	virtual void ShutdownModule() override
	{

	}
};
#include "TestModule.h"


IMPLEMENT_MODULE(FTestModule, TestModule);

(.cpp 파일에는 반드시 IMPLEMENT_MODULE이라고 설정해야한다. 이미 c++ 프로젝트 생성시 생성된 모듈의 .CPP에

' IMPLEMENT_PRIMARY_GAME_MODULE ' 로 선언이 되어 있을 것인데 IMPLEMENT_PRIMARY_GAME_MODULE는 프로젝트에서 유일하게 존재해야한다.)

 

(이까지하고 .uproject 우클릭 -> generated 머시기 눌러주면 배치파일을 실행하여 프로젝트에 필요한 파일들을 만들어준다.)

 

StartupModule함수는 ue가 실행중 에디터의 실행전 초기화 단계에서 호출되고 모듈의 초기설정 및 필요한 동작을 수행한다. 이 초기화 함수를 통해 모듈은 엔진과의 상호작용을 설정하고 모듈 고유의 동작을 초기화할 수 있다.

실제로 break point가 잡혔고 75%쯤 엔진 초기화 시점인 것을 확인할 수 있다.

 

실제로 모듈이 정상적으로 적용되어 에디터에서 잘 뜨는 것을 확인 할 수 있다.