2026-6-22 TIL

언리얼 C++ 새 모듈(Test) 생성 및 등록

오늘 배운 내용

오늘은 언리얼 C++ 프로젝트에서 새로운 모듈인 Test 모듈을 직접 생성하고, 빌드 대상에 등록하는 과정을 정리했다.

새 모듈은 언리얼 에디터 안에서 만드는 것이 아니라 프로젝트 폴더의 Source 폴더 안에서 직접 생성해야 한다.
즉, Content 폴더가 아니라 Source/Test 경로에 모듈 폴더와 필수 파일을 만들어야 한다.

---

1. 새 모듈(Test) 생성 위치

새 모듈은 프로젝트 폴더 안의 Source 폴더에 만든다.

예시 구조는 다음과 같다.

프로젝트폴더/
├─ Source/
│  ├─ 프로젝트명/
│  │  ├─ 프로젝트명.Build.cs
│  │  ├─ 프로젝트명.h
│  │  └─ 프로젝트명.cpp
│  │
│  └─ Test/
│     ├─ Test.Build.cs
│     ├─ Test.h
│     └─ Test.cpp

여기서 새로 만든 부분은 다음과 같다.

Source/Test

그리고 그 안에 필요한 파일은 다음과 같다.

Test.Build.cs
Test.h
Test.cpp

---

2. Test.Build.cs 작성

Test.Build.cs는 Test 모듈의 빌드 설정 파일이다.

이 파일에는 해당 모듈이 어떤 언리얼 모듈에 의존하는지 작성한다.

using UnrealBuildTool;

public class Test : ModuleRules
{
    public Test(ReadOnlyTargetRules Target) : base(Target)
    {
        PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;

        PublicDependencyModuleNames.AddRange(new string[]
        {
            "Core",
            "CoreUObject",
            "Engine"
        });

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

여기서 PublicDependencyModuleNames는 헤더 파일과 cpp 파일 모두에서 사용할 수 있는 의존성 모듈이고,
PrivateDependencyModuleNames는 cpp 파일 내부에서만 사용하는 의존성 모듈이다.

---

3. Public Dependency와 Private Dependency 차이

오늘 정리한 핵심은 다음과 같다.

Public Dependency
→ 헤더(.h)와 소스(.cpp) 모두에서 사용하는 모듈

Private Dependency
→ 소스(.cpp) 파일에서만 사용하는 모듈

예를 들어 어떤 클래스를 .h 파일에서 상속받거나 멤버 변수로 사용한다면 해당 모듈은 PublicDependencyModuleNames에 넣는 것이 맞다.

반대로 .cpp 파일 안에서만 잠깐 사용하는 기능이라면 PrivateDependencyModuleNames에 넣으면 된다.

---

4. Test.h 작성

Test.h 파일은 새 모듈의 기본 헤더 파일이다.

#pragma once

#include "CoreMinimal.h"

CoreMinimal.h는 언리얼 C++에서 기본적으로 자주 사용하는 타입과 기능을 포함하는 헤더이다.

---

5. Test.cpp 작성

Test.cpp 파일에는 모듈을 언리얼에 등록하는 코드를 작성한다.

#include "Test.h"
#include "Modules/ModuleManager.h"

IMPLEMENT_MODULE(FDefaultModuleImpl, Test);

여기서 핵심은 IMPLEMENT_MODULE이다.

IMPLEMENT_MODULE(FDefaultModuleImpl, Test);

이 코드는 Test라는 모듈을 언리얼 엔진의 모듈 시스템에 등록하는 역할을 한다.

즉, 파일만 만든다고 모듈이 자동으로 인식되는 것이 아니라,
IMPLEMENT_MODULE을 통해 이 모듈이 실제 언리얼 모듈이라는 것을 알려줘야 한다.

---

6. Target.cs에 Test 모듈 등록

새 모듈을 만들었다면 컴파일 대상에도 등록해야 한다.

수정해야 하는 파일은 보통 Source 폴더 바로 아래에 있다.

Source/프로젝트명.Target.cs
Source/프로젝트명Editor.Target.cs

두 파일 모두에서 ExtraModuleNames에 "Test"를 추가해야 한다.

예를 들어 기존 코드가 다음과 같다면,

ExtraModuleNames.AddRange(new string[] { "프로젝트명" });

아래처럼 수정한다.

ExtraModuleNames.AddRange(new string[] { "프로젝트명", "Test" });

또는 기존 코드가 이렇게 되어 있다면,

ExtraModuleNames.Add("프로젝트명");

아래처럼 한 줄을 추가한다.

ExtraModuleNames.Add("프로젝트명");
ExtraModuleNames.Add("Test");

이 작업은 Test 모듈도 실제 빌드 과정에 포함시키기 위한 설정이다.

---

7. .uproject 파일에 Test 모듈 등록

Target.cs에 등록하는 것과 별개로 .uproject 파일에도 모듈 정보를 추가해야 한다.

.uproject 파일은 프로젝트 폴더 가장 바깥에 있다.

예시는 다음과 같다.

"Modules": [
    {
        "Name": "프로젝트명",
        "Type": "Runtime",
        "LoadingPhase": "Default"
    },
    {
        "Name": "Test",
        "Type": "Runtime",
        "LoadingPhase": "PreDefault"
    }
]

여기서 "Name": "Test"는 새로 만든 모듈 이름이다.

"Type": "Runtime"은 게임 실행 중에도 사용할 수 있는 런타임 모듈이라는 뜻이다.

"LoadingPhase": "PreDefault"는 기본 로딩 시점보다 조금 더 먼저 모듈을 로드하겠다는 의미이다.

---

8. Generate Visual Studio project files 실행

모듈 생성과 등록이 끝났다면 프로젝트 파일을 다시 생성해야 한다.

순서는 다음과 같다.

1. 언리얼 에디터 종료
2. .uproject 파일 우클릭
3. Generate Visual Studio project files 실행
4. Visual Studio에서 프로젝트 열기
5. 빌드 실행

이 과정을 해야 Visual Studio 솔루션에 새로 만든 Test 모듈이 반영된다.

---

핵심 요약

오늘 배운 핵심은 새 모듈은 단순히 파일만 만든다고 끝나는 것이 아니라는 점이다.

Source/Test 폴더에 Test.Build.cs, Test.h, Test.cpp를 만든 뒤,
Target.cs와 .uproject 파일에도 모듈을 등록해야 한다.

전체 흐름은 다음과 같다.

1. Source 폴더 안에 Test 폴더 생성
2. Test.Build.cs 작성
3. Test.h 작성
4. Test.cpp 작성
5. IMPLEMENT_MODULE로 모듈 등록
6. Target.cs의 ExtraModuleNames에 Test 추가
7. .uproject의 Modules 리스트에 Test 추가
8. Generate Visual Studio project files 실행
9. Visual Studio에서 빌드

---

느낀 점

처음에는 새 모듈을 언리얼 에디터에서 만드는 줄 알았지만, 실제로는 프로젝트 폴더의 Source 안에서 직접 파일과 폴더를 만들어야 한다는 점을 알게 되었다.

또한 모듈 파일을 만드는 것만으로는 부족하고, Target.cs와 .uproject에 등록해야 실제 컴파일 과정에 포함된다는 것도 이해했다.

오늘 정리한 내용을 기준으로 보면 언리얼 C++ 모듈 생성 흐름은 다음 한 문장으로 정리할 수 있다.

모듈 파일 생성 → 빌드 설정 작성 → 모듈 매크로 등록 → Target.cs 등록 → .uproject 등록 → 프로젝트 파일 재생성 → 빌드