[MooaToon] 2화 . 설치와 빌드: 소스코드에서 나만의 툰 엔진 만들기

UNREAL ENGINE

[MooaToon] 2화 . 설치와 빌드: 소스코드에서 나만의 툰 엔진 만들기

jplee 2026. 9. 3. 21:58

어제 협력사인 제이커브이엔트에 들렀다가 오늘 길에 1화를 쓰기 시작했죠. 오늘은 협력할 여러 결정지 중에서 어떤 것 부터 할까! 정도가 좀 정리가 되었습니다. 와이프와 저녁식사 후 또 업무를 시작하기 전에 짧게 2화 글을 남겨봅니다.

들어가며

1화에서는 MooaToon이 어떤 엔진인지 대략 살펴봤습니다. 다시 짧게 정리하면, MooaToon은 마켓플레이스에서 구입해 프로젝트에 추가하는 셰이더 에셋이 아닙니다. 언리얼 엔진 5 소스를 포크하고 렌더링 파이프라인을 직접 수정한 커스텀 엔진입니다.

그래서 설치 방법도 일반적인 UE5와 다릅니다. 에픽게임즈 런처에서 버전을 고르고 설치 버튼을 누르는 것으로 끝나지 않습니다. 엔진 소스를 내려받고, 빌드에 필요한 프로그램을 갖춘 다음, 내 PC에서 직접 컴파일해야 합니다.

처음 소스 빌드를 해보는 분에게는 이 과정이 꽤 부담스럽게 보일 수 있습니다. 하지만 막상 나눠놓고 보면 해야 할 일은 정해져 있기 때문에 처음 한 두번의 고통?을 감수 하면 누구에게나 같은 시간분해자인건 마찬가지입니다.

Git과 Visual Studio를 설치하고, 계정을 연동하고, 소스를 받은 뒤 빌드하는 순서입니다. 어려운 코드를 작성할 필요는 없습니다. 다만 설치 용량이 크고 시간이 오래 걸리며, 중간 설정 하나가 빠지면 엉뚱한 곳에서 오류가 나는 편입니다.

언리얼 엔진 소스코드 빌드를 관리하는 저장소는 최소 1테라를 비워두길 추천 드립니다. 언리얼 엔진 6.0 소스 풀빌드의 경우 최소 2테라 저장공간을 비워두는 것이 좋습니다. ( 2026년 9월 ue6-main 기준 )

이번 글에서는 자동 설치와 수동 설치를 모두 다룹니다. 처음이라면 자동 설치 툴을 권하고, 이후 엔진 소스를 직접 수정할 생각이라면 수동 설치 과정도 한 번 읽어두는 편이 좋습니다.

MooaToon 공식 저장소에 공개된 렌더링 데모. 설치가 끝나면 샘플 프로젝트에서 이런 툰 렌더링 기능들을 직접 확인할 수 있습니다.

설치 순서

전체 순서는 다음과 같습니다.

개발 환경 준비 — Git, GitHub·Epic Games 계정 연동, Visual Studio 2022
소스 내려받기 — 설치 툴을 사용하거나 저장소를 직접 클론
엔진 빌드 — UE5 솔루션을 생성하고 컴파일
첫 실행 확인 — 샘플 프로젝트와 샘플 레벨 확인
업데이트 준비 — 수정 파일 백업과 클린 스크립트 사용 시 주의점

처음부터 하나씩 보겠습니다.

다운로드·계정 링크 모음

MooaToon 엔진과 프로젝트 브랜치는 비공개 저장소에 있으므로 Epic Games–GitHub 연동을 완료한 계정으로 로그인해야 열립니다. 연동 전에는 정상 링크도 404로 표시됩니다.

0단계. 개발 환경 세팅

설치 중에 만나는 오류는 의외로 엔진 소스보다 개발 환경에서 생기는 경우가 많습니다. 특히 Visual Studio 워크로드나 Windows SDK가 빠져 있으면 실제 빌드 단계에 들어가서야 문제가 드러납니다. 먼저 필요한 프로그램부터 정확히 갖춰두는 편이 낫습니다.

0-1. Git 설치

Git은 원래 소스코드의 변경 이력을 관리하는 도구입니다. 이번 설치에서는 우선 GitHub에 있는 엔진 소스를 내려받는 데 사용한다고 이해하면 충분합니다.

1) 다운로드

Git for Windows 공식 다운로드 페이지에서 설치 파일을 받습니다. 일반적인 64비트 Windows PC라면 64-bit Git for Windows Setup을 선택하면 됩니다. 이 페이지의 Click here to download를 누르면 현재 최신 x64 설치 파일이 내려받아집니다.

2) 설치

설치 화면에 옵션이 많이 나오지만 대부분 기본값을 사용해도 됩니다. 아래 항목 정도만 확인하면 됩니다.

Select Components: 기본 체크 상태 유지
Choosing the default editor: 기본값을 사용해도 되고, Vim이 낯설다면 Notepad로 변경
Adjusting your PATH environment: Git from the command line and also from 3rd-party software 유지
SSH, HTTPS, 줄바꿈 관련 설정: 특별한 이유가 없다면 기본값 유지

PATH 설정은 바꾸지 않는 것이 좋습니다. MooaToon 설치 툴을 비롯한 다른 프로그램이 명령줄의 Git을 찾을 때 이 설정을 사용합니다.

3) 설치 확인

Win + R을 누르고 cmd를 입력해 명령 프롬프트를 연 다음 아래 명령을 실행합니다.

git --version

git version 2.xx.x.windows.x처럼 버전이 표시되면 설치된 것입니다. Git을 찾을 수 없다는 메시지가 나오면 명령 프롬프트를 새로 열거나 Windows를 재부팅한 뒤 다시 확인합니다. 그래도 인식되지 않으면 Git 설치 과정의 PATH 옵션을 확인해보세요.

뒤에서 설명할 설치 툴의 _1_1_Install_Git.bat을 사용하면 Git을 자동으로 설치할 수 있습니다. 자동 설치를 이용할 분은 이 과정을 직접 진행하지 않아도 됩니다.

0-2. GitHub와 Epic Games 계정 연동

언리얼 엔진 소스는 GitHub의 비공개 저장소에 있습니다. GitHub 계정만 만든다고 바로 접근할 수 있는 것은 아니고, Epic Games 계정과 연결해야 합니다.

진행 순서는 다음과 같습니다.

GitHub 가입 페이지에서 계정을 만들고 이메일 인증을 완료합니다.
Epic Games 계정이 없다면 Epic Games 가입 페이지에서 먼저 만듭니다.
Epic Games 연결된 계정 페이지에서 GitHub 항목의 연결(Link)을 선택합니다.
GitHub로 도착한 Epic Games 조직 초대를 수락합니다. 전체 과정은 Unreal Engine on GitHub 공식 안내에서도 확인할 수 있습니다.

마지막 초대 수락까지 끝나야 저장소가 보입니다. 저장소 주소로 들어갔는데 404가 나온다면 링크부터 의심하기 쉽지만, 대부분 계정 연동이 끝나지 않았거나 조직 초대를 수락하지 않은 경우입니다.

0-3. Visual Studio 2022 설치

UE5 소스를 실행 가능한 엔진으로 만들려면 C++ 컴파일 환경이 필요합니다. 여기서는 Visual Studio 2022 Community 버전을 사용합니다. Community 버전으로 충분합니다.

Visual Studio 2022 Community 설치 파일을 누르면 Microsoft의 공식 부트스트래퍼가 바로 내려받아집니다. 전체 제품과 이전 버전은 Visual Studio 다운로드 페이지에서 확인할 수 있습니다.

Visual Studio는 설치할 때 어떤 개발 환경을 구성할지 직접 선택해야 합니다. 프로그램만 설치하고 워크로드를 빼먹으면 UE5를 빌드할 수 없습니다.

다음 워크로드를 선택합니다.

C++를 사용한 데스크톱 개발(Desktop development with C++)
C++를 사용한 게임 개발(Game development with C++)
.NET 데스크톱 개발(.NET desktop development)

Visual Studio Installer의 워크로드 선택 화면

Visual Studio Installer의 워크로드 선택 화면. 이미 설치한 뒤에도 수정(Modify) 메뉴에서 같은 화면을 다시 열 수 있습니다. 이미지: Microsoft Learn.

그리고 개별 구성 요소(Individual components) 탭에서 아래 항목이 포함되어 있는지 확인합니다.

MSVC v143 - VS 2022 C++ x64/x86 빌드 도구
Windows 10 SDK 또는 Windows 11 SDK
.NET Framework 4.6.2 이상 타기팅 팩

이미 Visual Studio 2022를 사용하고 있다면 다시 설치할 필요는 없습니다. 시작 메뉴에서 Visual Studio Installer를 열고, 설치된 버전의 수정(Modify)을 눌러 빠진 워크로드와 구성 요소만 추가하면 됩니다.

_1_2_Install_VisualStudio.bat을 사용하면 Visual Studio와 필요한 워크로드를 자동으로 설치할 수 있습니다. 다만 나중에 빌드 오류가 생겼을 때 확인해야 할 항목은 위 내용과 같습니다.

0-4. 디스크 공간, 빌드 시간, 설치 경로

MooaToon 소스 빌드에서 먼저 확인할 것은 디스크 공간입니다. 엔진 소스만 보면 수십 GB 정도지만, 의존성 파일과 빌드 중간 산출물까지 더해지면 훨씬 커집니다. SSD에 500GB 정도의 여유 공간을 확보한 뒤 시작하는 것을 권합니다.

HDD에서도 빌드는 가능하지만 파일 수가 많아 작업 시간이 크게 늘어납니다. 가능하면 SSD를 사용하세요.

빌드 시간은 PC 사양에 따라 차이가 큽니다. 대략 1~3시간 정도를 예상하면 됩니다. CPU 코어 수와 저장장치 속도에 따라 더 짧아질 수도, 더 길어질 수도 있습니다. 자동 설치 툴을 사용하더라도 컴파일 시간 자체가 없어지는 것은 아닙니다.

설치 경로는 짧게 잡는 편이 안전합니다. 예를 들면 다음과 같습니다.

D:\MooaToon

가능하면 한글과 공백이 들어가지 않은 영문 경로를 권합니다. 모든 도구가 한글 경로에서 문제를 일으키는 것은 아니지만, 소스 빌드 도중 경로 문제를 만나면 원인을 찾기가 번거롭습니다.

1단계. MooaToon 내려받기

설치 방법은 두 가지입니다. 설치 툴을 사용하면 대부분의 과정이 자동으로 진행되고, 수동 설치를 선택하면 저장소와 빌드 구조를 직접 확인할 수 있습니다.

방법 A. 설치 툴 사용

소스 빌드가 처음이라면 이 방법부터 권합니다. 먼저 MooaToon 설치 툴 ZIP을 내려받아 D:\MooaToon처럼 짧은 경로에 압축을 풉니다. 저장소와 최신 변경 내역은 MooaToon 설치 툴 GitHub에서 확인할 수 있습니다. 압축을 푼 뒤 배치 파일을 번호 순서대로 실행하면 됩니다.

_1_1_Install_Git.bat — Git 설치
_1_2_Install_VisualStudio.bat — Visual Studio 2022와 워크로드 설치
_2_0_Install_And_Run_MooaToon.bat — 엔진과 샘플 프로젝트 다운로드, 빌드, 실행

Git이나 Visual Studio가 이미 준비되어 있다면 앞의 설치 단계는 건너뛸 수 있습니다. 세 번째 배치 파일은 엔진과 프로젝트를 받은 뒤 빌드까지 진행하므로 꽤 오래 걸립니다. 실행 중에는 창을 닫지 말고 완료될 때까지 기다립니다.

방법 B. 수동 설치

앞으로 브랜치를 직접 관리하거나 엔진의 C++·셰이더 코드를 수정할 계획이라면 수동 설치 과정을 알아두는 것이 좋습니다.

MooaToon 엔진과 샘플 프로젝트는 MooaToon-Engine 저장소의 서로 다른 브랜치로 관리됩니다.

엔진 소스: 5.x 최신 브랜치
엔진 소스를 zip 압축파일로 받을 경우.
샘플 프로젝트: 5.x_MooaToonProject 브랜치

샘플 프로젝트를 Zip 압축으로 받을 수도 있습니다.

필자는 Fork 를 떠서 사용하도록 하겠다.

엔진 브랜치에는 수정된 UE5 본체가 있고, 프로젝트 브랜치에는 샘플 콘텐츠와 설정이 들어 있습니다. 이후 소스를 수정할 때도 이 둘을 구분해야 합니다. 렌더링 파이프라인 자체의 변경은 엔진 쪽에, 콘텐츠와 머티리얼 사용 예시는 프로젝트 쪽에 있습니다.

Git으로 클론하는 방법을 권하지만, 네트워크 문제로 클론이 계속 끊긴다면 위의 ZIP 직접 다운로드 링크를 이용할 수도 있습니다. 다만 ZIP으로 받으면 Git 이력이 없기 때문에 이후 업데이트나 변경 사항 비교가 불편합니다. 저장소가 404로 보인다면 먼저 Epic Games–GitHub 계정 연동 상태를 확인하세요.

저는 현재 브렌치 외의 다른 브렌치는 필요가 없고 히스토리도 많이 필요가 없었기 때문에 아래처럼 Shallow Clone 으로 받았습니다.

2단계. 엔진 빌드

수동으로 소스를 받았다면 UE5의 일반적인 소스 빌드 순서로 진행합니다. MooaToon에서 관리하는 최신 절차는 소스 빌드 공식 안내, UE 공통 절차는 Unreal Engine 소스코드 다운로드·빌드 안내에서 확인할 수 있습니다.

1) Setup.bat 실행

엔진 폴더 최상단의 Setup.bat을 실행합니다. 이 파일은 빌드에 필요한 서드파티 라이브러리와 툴을 내려받습니다. 다운로드 용량이 크기 때문에 네트워크 상태와 남은 디스크 공간을 확인해두세요.

권한 관련 오류가 난다면 관리자 권한으로 다시 실행해봅니다.

2) GenerateProjectFiles.bat 실행

같은 폴더에 있는 GenerateProjectFiles.bat을 실행합니다. 완료되면 Visual Studio에서 열 수 있는 UE5.sln 파일이 생성됩니다.

3) Visual Studio에서 빌드

UE5.sln을 Visual Studio 2022로 엽니다. 상단의 빌드 구성을 다음과 같이 맞춥니다.

솔루션 구성: Development Editor
플랫폼: Win64

솔루션 탐색기에서 UE5 프로젝트를 찾아 우클릭한 뒤 빌드(Build)를 선택합니다. 이제 컴파일이 끝날 때까지 기다립니다.

빌드 중 경고가 많이 표시될 수 있습니다. 중요한 것은 마지막 결과입니다. 빌드가 실패했다면 출력 창의 맨 마지막 오류만 보지 말고, 그보다 앞에서 처음 발생한 오류를 찾는 편이 좋습니다. 뒤에 이어지는 오류는 첫 번째 실패 때문에 연쇄적으로 나온 것일 수 있습니다.

4) 샘플 프로젝트 실행

빌드가 완료되면 MooaToon-Project 폴더의 .uproject 파일을 실행합니다. 엔진 연결을 묻는 창이 나온다면 방금 빌드한 MooaToon 엔진을 지정합니다.

여기서는 InstallBuild 에 대한 것은 다루지 않고 있습니다.

3단계. 첫 실행 확인

에디터가 열리면 샘플 프로젝트부터 확인합니다.

콘텐츠 브라우저에서 다음 폴더로 이동합니다.

Content\MooaToonSamples\Maps

기능별 샘플 레벨을 열어보고 아래 항목이 정상적으로 보이는지 확인합니다.

https://youtu.be/WGOC-0DlZa8?si=mGDYXzE9rdmweg1q

캐릭터의 툰 명암 경계
라이트 방향에 따른 그림자 변화
얼굴 그림자
헤어 하이라이트
그 밖의 MooaToon 전용 표현

샘플 레벨은 단순히 결과를 구경하는 데모라기보다, 각 기능의 구성 방법을 확인하는 예제에 가깝습니다. 이후 연재에서도 계속 참고할 예정이므로 어떤 레벨이 있는지 한 번 훑어보는 것이 좋습니다.

업데이트하기 전에 알아둘 점

MooaToon은 계속 업데이트되고 있고, 이후에는 엔진 소스를 직접 수정할 일도 생깁니다. 원본 저장소가 갱신된 상태에서 내가 수정한 파일이 있으면 충돌이 생길 수 있습니다.

MooaToon은 _3_X_Clean_MooaToon 계열 스크립트로 클린과 업데이트 작업을 지원합니다. 스크립트의 최신 버전과 변경 내용은 MooaToon 설치 툴 저장소에서 확인할 수 있습니다. 이 스크립트를 실행하기 전에는 직접 수정한 파일을 별도로 백업해두세요. 클린 과정에서 로컬 변경 사항이 사라질 수 있습니다.

처음에는 거창한 관리 체계까지 만들 필요는 없습니다. 어떤 파일을 왜 수정했는지 메모해두고, 변경한 파일을 따로 복사해두는 것부터 시작해도 됩니다. Git을 사용할 수 있다면 작업 단위로 커밋해두는 방법이 가장 편합니다.

자주 생기는 문제

저장소에 들어가면 404가 나온다

Epic Games 연결된 계정 페이지에서 GitHub 계정이 연결되어 있는지 확인하고, GitHub로 받은 Epic Games 조직 초대를 수락했는지 확인합니다. 문제가 계속되면 공식 연동 안내를 따라 연결을 해제한 뒤 다시 연동해봅니다.

git --version을 실행해도 Git을 찾지 못한다

명령 프롬프트를 새로 열거나 Windows를 재부팅한 뒤 다시 확인합니다. 계속 인식되지 않으면 Git을 재설치하면서 PATH 옵션을 확인합니다.

Setup.bat 실행 중 실패한다

네트워크 연결과 디스크 여유 공간을 먼저 확인합니다. 권한 오류로 보이면 관리자 권한으로 다시 실행합니다.

컴파일러 또는 SDK 관련 오류가 나온다

Visual Studio Installer에서 C++ 워크로드, MSVC v143 빌드 도구, Windows SDK가 설치되어 있는지 확인합니다.

빌드 도중 디스크 공간이 부족해졌다

중간 산출물을 정리하고 충분한 공간을 확보한 뒤 다시 빌드해야 합니다. 시작하기 전에 SSD 여유 공간을 넉넉히 잡는 이유가 이것입니다.

경로와 관련된 정체불명의 오류가 난다

설치 경로에 한글이나 공백이 들어갔는지 확인합니다. 가능하면 D:\MooaToon처럼 짧은 영문 경로로 옮겨 다시 진행합니다.

마무리

이번 글에서는 MooaToon을 빌드하기 위한 개발 환경부터 첫 실행까지 정리했습니다. 과정이 길어 보이지만 실제 순서는 단순합니다. Git과 계정 연동을 준비하고, Visual Studio에 필요한 워크로드를 설치한 뒤, 엔진과 프로젝트를 받아 빌드하면 됩니다.

소스 빌드는 첫 시도가 가장 번거롭습니다. 한 번 환경을 제대로 만들어두면 이후에는 같은 과정을 처음부터 반복할 일이 많지 않습니다. 그리고 직접 빌드한 엔진이 정상적으로 실행되는 것을 확인했다면, MooaToon을 살펴볼 준비는 끝난 셈입니다.

전체 연재 순서는 다음과 같습니다.

MooaToon이란 무엇인가
설치와 빌드: 소스코드에서 엔진 만들기 ← 지금 이 글
엔진 구조 해부: 어떤 파일이 어디에 있는가
기본 사용법: 캐릭터에 툰 셰이딩 입히기
고급 사용법: 얼굴 셰도우, 림라이트, 헤어 하이라이트
커스터마이징 입문: 머티리얼 에디터에서 시작하기
커스터마이징 심화: 엔진 소스(C++/셰이더) 수정하기
실전 프로젝트: 나만의 툰 렌더링 파이프라인 완성

다음 3화에서는 MooaToon-Engine과 MooaToon-Project의 폴더와 파일 구조를 살펴보겠습니다. 파일 수가 워낙 많기 때문에 전부 설명하기보다는, 실제로 툰 렌더링과 관련된 코드가 어디에 있고 어떤 기준으로 찾아가면 되는지부터 정리할 생각입니다.

본 포스트는 MooaToon 공식 홈페이지(mooatoon.com) 및 GitHub 저장소(JasonMa0012/MooaToon)의 공개 정보를 바탕으로 글쓴이가 내용을 재구성하고 추가했습니다.

저작자표시 비영리 변경금지 (새창열림)