Unreal 엔진 빌드 프로세스

1. VS C++ 솔루션 구조 이해하기

언리얼 프로젝트 폴더에서 솔루션 파일을 클릭해 VS를 실행한 후, 프로젝트 폴더 구조를 파악해 보자.

 

이렇게 프로젝트 폴더들이 계층적으로 표시되는데, 실제 Windows 탐색기에서 보았던 프로젝트 폴더 구조와는 조금 다를 수 있다. VS는 빌드와 관리를 용이하게 하기 위해 디스크의 실제 폴더 구조와는 별개로 가상 폴더 구조를 생성하기 때문이다. 따라서 Windows 탐색기의 실제 폴더 구조와 1:1로 대응되지 않을 수 있음을 유의해야 한다. 빌드 규칙이나 엔진 소스 파일은 가상 폴더 구조에서 위치가 다르게 보이더라도, 실제로는 엔진 설치 폴더와 프로젝트 폴더에 그대로 존재한다.

 

1 - 1. 솔루션 구조 내 주요 폴더

Engine 

• 언리얼 엔진 자체 소스 코드와 리소스가 담긴 곳이다.
• 에디터 작동, 엔진 코어 관련 코드가 포함되어 있지만 초급 단계에서는 거의 수정할 일이 없다.

 

Games (중요)

• 우리가 만든 프로젝트 코드가 모두 들어있다.
• 내부에는 Source, Config, .uproject 파일 등이 있으며, C++로 작성하는 게임 로직을 이 폴더에서 가장 많이 다루게 된다.

 

Programs

• 엔진 동작에 필요한 유틸리티 프로그램이나 서버 모듈이 담겨 있다.
• 초급 단계에서는 거의 볼 일이 없다.

 

Rules

• 엔진과 게임 등 각 모듈의 빌드 규칙을 정의해 놓은 파일들이 모여 있다.
• 모듈 의존성, 플러그인 활성화 여부, 빌드 대상 등을 제어한다.

 

Visualizers

• VS에서 디버깅 시 언리얼 엔진 관련 자료구조를 보기 좋게 표시하기 위한 설정 파일이 들어 있다.

 

1 - 2. 프로젝트 루트 폴더 (Games/프로젝트명)

 

Game 폴더를 열어보면 우리가 만든 프로젝트 이름이 보인다. 이 폴더가 "프로젝트 루트"이며, 게임 개발에 필요한 모든 리소스와 설정 파일이 이곳에 모여 있다.

 

1 - 3. 프로젝트 루트 폴더 주요 구성 요소

 

Config

.ini 파일을 통해 에디터와 게임의 초기 상태를 지정한다.

• DefaultEditor.ini: 에디터 환경 설정 (뷰포트, UI 등)
• DefaultEngine.ini: 엔진 전반 설정 (렌더링, 네트워킹 등)
• DefaultGame.ini: 게임 플레이 관련 설정 (게임 모드, 플레이어 컨트롤러 클래스 등)
• DefaultInput.ini: 키보드/마우스/패드 등의 기본 입력 바인딩 

 

 

Source

실제 C++ 소스 코드(.cpp, .h)가 들어 있다. 최초 프로젝트 생성 시에는 프로젝트명.cpp, 프로젝트명.h 등 최소 파일만 있지만 새 클래스를 만들수록 점차 늘어난다.

 

빌드 설정 관련 주요 파일도 포함된다.

• 프로젝트명.Build.cs: 해당 프로젝트에 필요한 모듈, 라이브러리, 종속성 등을 정의한다.
• 프로젝트명.Target.cs, 프로젝트명Editor.Target.cs: 각각 게임 실행용 , 에디터용 빌드 방식을 정의한다.

 

 

프로젝트명.uproject

언리얼 에디터에서 이 파일을 열면 프로젝트를 직접 실행할 수 있다. 에디터는 이 파일을 통해  "어떤 콘텐츠와 설정을 불러올지"를 판단한다.

 

---

2. VS C++ 빌드 설정 이해하기

C++ 코드를 수정했다면, 이를 컴파일 + 링크 해 동적 라이브러리(DLL)로 만들어야 한다. 그렇게 생성된 DLL이 언리얼 에디터에서 로드되어, 새로 작성한 로직 (함수, 클래스)등이 게임이나 에디터 내에서 즉시 반영된다.

 

2 - 1. 빌드 구성 및 플랫폼 확인

 

VS 상단 툴바에는 빌드 구성 (Configuration)과 플랫폼(Platform)을 선택하는 드롭다운이 있다.

• 왼쪽 - 빌드 구성
• 오른쪽 - 플랫폼

 

2 - 2. 빌드 구성 종류

 

DebugGame

• 게임 로직만 디버그 정보를 포함하고 엔진은 최적화된 상태로 빌드한다.
• 에디터가 아닌 독립 실행 파일 환경에서 디버깅이 가능하다.

 

DebugGameEditor

• 에디터 환경에서 게임 로직을 디버그하기 편한 설정이다.
• 에디터 플레이 중 C++ 로직을 추적하거나 브레이크 포인트를 걸어볼 수 있다.

 

Development

• 디버그 정보를 최소화해 실행 속도를 높인 개발용 빌드이다.
• 독립 실행 파일 환경 테스트/개발 단계에서 주로 쓰인다.

 

Development Edtior

• 에디터에서도 개발/테스트를 원활히 할 수 있도록 구성된 빌드 모드이다.
• Live Coding 사용 시나리오와 궁합이 좋고, 초/중급자들이 자주 사용한다.

 

Shipping

• 최종 사용자에게 배포할 때 사용하는 릴리스 빌드이다.
• 디버그 정보를 제공하고, 성능 최적화가 극대화된다.

 

2 - 3. 플랫폼

기본적으로 Win64가 선택되어 있으며, 이는 Windows 64 비트 환경을 의미한다. 모바일(Android, iOS), 콘솔 (PS, Xbox)로 빌드하려면 해당 플랫폼용 SDK를 추가로 설치해야 한다.

---

3. VS에서 C++ 빌드하기

언리얼 C++ 프로젝트는 전체 솔루션 빌드와 부분 빌드로 나누어 빌드할 수 있다.

 

3 - 1. 전체 솔루션 빌드

 

 

• VS 메뉴에서 빌드 -> 솔루션 빌드 (단축키 Ctrl + Shift + B)
• 엔진, 유틸리티, 게임 등 모든 모듈을 통째로 빌드한다.
• 첫 빌드나 엔진 소스를 수정했을 때, 또는 엔진 전체 파일이 필요한 경우에 사용한다.
• 프로젝트 규모가 크면 시간이 오래 걸릴 수 있다.

 

3 - 2. 부분 빌드

 

• Solution Explorer에서 프로젝트를 우클릭, Build 선택.
• 엔진이나 다른 모듈을 제외하고, 게임 프로젝트 코드만 빠르게 빌드한다.
• 일반적으로 C++ 로직만 수정했다면 이 방법을 쓰는 것이 효율적이다.

3 - 3. 빌드 전후 체크 포인트

빌드 시작 전

• 언리얼 에디터는 가급적 종료하고 빌드하는 편이 안전하다.
• 에디터가 실행 중이면 수정된 DLL을 교체하지 못해 빌드 에러가 발생할 수 있다.

 

빌드 진행

 

• VS 하단 Output 창에서 빌드 메시지를 모니터링한다.
• Output 창 우측 상단을 빌드 전용으로 변경한다. 그래야만 빌드 문제만을 우선적으로 확인할 수 있다.
• 첫 빌드는 엔진 모듈까지 모두 새로 컴파일하므로 오래 걸릴 수 있지만, 이후에는 변경된 소스만 컴파일해서 빌드 시간이 크게 단축된다.
• 경고나 에러가 뜨면 Error List 창에서 구체적인 원인을 확인할 수 있다.

 

빌드 결과

 

• Build completed 메시지가 나오면 정상 빌드된 것이다. (전과 비교해 수정된 사항이 없어서 빌드가 빨리 끝난 것 같다.)

 

 

• 빌드 후, 프로젝트 폴더의 Binaries/Win64 폴더 내에 UnrealEditor-프로젝트명.dll 등이 새로 생성된다.
• 그 후 언리얼 에디터를 실행하면 이 DLL을 로드해 수정된 로직이 적용된다.

---

4. 언리얼 에디터에서 Live Coding 실행하기

4 - 1. 기존 빌드 흐름 vs Live Coding

기존 방식

1. 에디터 연결 종료 (Shift + F5)
2. C++ 코드 수정
3. VS에서 빌드
4. 에디터 재연결 (F5)
5. 결과 확인

 

Live Coding 활용 시

1. 에디터 연결 종료 안 한 채 C++ 코드 수정
2. Live Coding으로 변경 사항만 컴파일
3. 에디터에 즉시 로직 반영

 

즉, Live Coding을 사용하면 에디터를 일일이 끄고 켜는 번거로움이 줄어든다.

 

4 - 2. Live Coding 제약 사항

간단한 코드 변경

함수 내부 로직, 변수 값 변경, 로그 출력 변경 등은 Live Coding으로 즉시 반영된다.

 

적용이 안 되는 경우

• UCLASS, USTRUCT, UENUM 매크로의 추가/삭제/수정
• 새로운 C++ 클래스(.h, cpp) 생성
• 엔진 코어 영역 수정
• 함수 시그니처(인자, 반환값)나 클래스 상속 구조 변경
• 이 경우에는 전통적인 빌드 프로세스 (에디터 종료 ->  VS 빌드 -> 에디터 재실행)가 필요하다.

 

4 - 3. Live Coding 사용 방법

1. VS 코드에서 코드를 수정한 후, Ctrl + Shift + S로 모든 파일을 저장한다.
2. 에디터 창 하단에 있는 Live Coding 아이콘을 클릭하거나 Ctrl + Alt + F11을 눌러 Live Coding 빌드를 시작한다.
3. 컴파일이 완료되면 Live Coding 창에 Finished 메시지가 뜨고 에디터가 즉시 수정된 로직을 반영한다.

---

5. 빌드 문제 복구하기

5 - 1. 변경 사항 미반영 문제란?

C++ 코드를 수정하고 빌드를 완료하였음에도 불구하고, 언리얼 에디터에서 반영이 안 되는 경우가 있다.

빌드 캐시나 프로젝트 설정 문제, 혹은 파일 경로가 꼬여서 발생할 수 있으며, 아래와 같은 형태로 나타난다.

• 컴파일 대상 누락: VS 혹은 엔진이 수정된 소스를 인식 못 해 빌드 대상에서 누락됨.
• DLL 교체 문제: 빌드가 끝났어도 에디터가 새 DLL을 로드하지 못함
• 캐시 문제: 이전 빌드 결과물이 남아 새 빌드 결과를 덮어씌우지 못함
• 파일 경로 문제: 헤더 파일 경로나 플러그인 설정이 잘못되어 컴파일에 포함되지 않음.

5 - 2. 단계별 해결 가이드

1. 언리얼 에디터와 VS 종료

실행 중인 프로세스들이 빌드 파일을 잠글 수 있으므로, 모두 끄고 새로 시작하는 것이 좋다.

 

2. 프로젝트 폴더에서 Intermediate, DerivedDataCache, Saved 폴더 삭제

이 폴더들은 빌드 캐시 및 임시 데이터를 담고 있다.

삭제 후 다시 빌드하면 새로 생성되어 잘못된 캐시로 인한 오류를 해결할 수 있다.

 

3. .uprojet 파일을 우클릭 -> Generate Visual Studio project files 선택

솔루션 파일과 프로젝트 설정을 재생성하여 누락되었거나 꼬인 구성을 복구한다.

 

4. VS 에서 클린 빌드

새로 생성된 솔루션을 열고

• Build -> Clean Solution으로 기존 빌드 산출물을 정리
• Build -> Build Solution으로 프로젝트 재빌드

에러가 난다면 Output 창과 Error List를 확인해 원인을 파악하고 수정한다.

 

5. 언리얼 에디터 다시 실행

에디터를 다시 실행해 코드 변경 사항이 반영되었는지 확인한다.

여전히 문제가 계속된다면 Saved/Logs 폴더의 로그를 확인해 구체적인 에러를 찾고 엔진 버전이나 프로젝트 설정을 점검해 보자.