패키징 및 빌드 설정

배포 전 점검을 끝냈다면, 이제 실제 실행 파일을 만드는 단계로 넘어갑니다.

이번 절의 핵심은 패키징(Packaging)과 빌드 설정입니다.

개발 환경에서 실행되던 프로젝트를 PC, 모바일, 콘솔 같은 대상 플랫폼에서 독립 실행 가능한 형태로 변환하는 과정이며, 이때 선택한 옵션이 파일 크기, 로딩 속도, 성능, 보안 수준에 직접 영향을 줍니다.

여기서는 목표 플랫폼에 맞는 빌드 설정을 고르는 기준과 적용 절차를 다룹니다.

기준을 명확히 잡고 패키징하면 릴리스 품질을 안정적으로 유지할 수 있습니다.

로그로 오류를 제거한다
Development · 진단 누락된 참조와 기능 회귀를 재현하고 원인을 찾는 내부 검증 빌드입니다.
최종 조건으로 다시 만든다
Shipping · 배포 최적화와 디버그 제한이 달라지므로 같은 커밋도 별도 빌드가 필요합니다.
독립 실행을 통과시킨다
Clean machine · 승인 에디터가 없는 환경에서 시작 맵, 저장, 전환, 필수 런타임을 확인합니다.

패키징 및 빌드의 이해

패키징은 언리얼 엔진 프로젝트를 플레이어가 설치하고 실행할 수 있는 최종 게임 파일(예: .exe 파일, .apk 파일)로 변환하는 일련의 과정입니다.

이 과정에는 쿠킹(Cooking), 링크(Linking), 패키징(Packaging) 등의 단계가 포함됩니다.

쿠킹 (Cooking): 개발 환경에서 사용하는 에셋(메시, 텍스처, 머티리얼, 블루프린트 등)을 특정 플랫폼에서 가장 효율적으로 로드하고 사용할 수 있는 형태로 변환하는 과정입니다. 이 단계에서 불필요한 데이터가 제거되거나 압축됩니다.
링크 (Linking): 엔진 코드, 게임 코드, 외부 라이브러리 등을 하나로 묶어 실행 가능한 바이너리 파일을 생성합니다.
패키징 (Packaging): 쿠킹된 콘텐츠와 링크된 바이너리 파일을 하나의 패키지(예: .pak 파일, 설치 프로그램)로 묶는 과정입니다.

아래 다이어그램은 쿠킹, 링크, 패키징이 서로 어떤 순서로 이어지고 각 단계에서 무엇을 확인해야 하는지 요약합니다.

1
플랫폼용 에셋으로 변환
cooking 메시, 텍스처, 머티리얼, 블루프린트를 대상 플랫폼에서 읽기 좋은 형태로 바꿉니다. ✓ 맵 목록 누락 확인 ✓ 깨진 참조와 리다이렉터 정리
2
실행 가능한 바이너리 생성
linking 엔진 코드, 게임 코드, 외부 라이브러리를 묶어 실행 파일을 만듭니다. ✓ C++ 컴파일 오류 확인 ✓ 빌드 타겟 선택 검토
3
배포 가능한 묶음으로 정리
packaging 쿠킹된 콘텐츠과 실행 파일을 Pak, 설치 파일, 앱 패키지 형태로 구성합니다. ✓ Use Pak File과 암호화 검토 ✓ 플랫폼 서명 정보 확인

패키징 설정 핵심 항목

파일(File) > 프로젝트 패키징(Package Project) > 설정(Settings...) 또는 편집(Edit) > 프로젝트 세팅(Project Settings) > 프로젝트(Project) > 패키징(Packaging) 메뉴에서 패키징 관련 설정을 조정할 수 있습니다.

빌드 구성 (Build Configuration)

가장 중요한 설정 중 하나로, 최종 빌드의 목적과 포함될 디버그 정보 수준을 결정합니다.

Development (개발)
- 디버그 정보가 포함되어 개발 및 테스트에 용이합니다.
- 최적화 수준이 낮아 파일 크기가 크고 성능이 저하될 수 있습니다.
- 콘솔 명령 및 디버그 기능(예: Stat 명령어)이 활성화됩니다.
Shipping (배포)
- 최종 사용자에게 배포할 때 사용합니다.
- 최고 수준으로 최적화되어 파일 크기가 가장 작고 성능이 가장 좋습니다.
- 디버그 정보가 거의 제거되어 보안성이 높습니다.
- 콘솔 명령 및 디버그 기능이 대부분 비활성화됩니다.
DebugGame (디버그 게임)
- Development와 유사하지만, C++ 코드 디버깅에 필요한 정보가 더 많이 포함됩니다.
- 성능은 Development보다 약간 좋을 수 있습니다.
Debug (디버그)
- 가장 많은 디버그 정보가 포함되어 디버깅에 매우 용이하지만, 파일 크기가 매우 크고 성능이 가장 낮습니다. 일반적으로 사용되지 않습니다.

빌드 타겟 (Build Target)

프로젝트 세팅 > 프로젝트 > 패키징 또는 파일 > 프로젝트 패키징 메뉴에서 선택할 수 있습니다.
Game: 일반적인 게임 실행 파일을 빌드합니다. (주로 사용)
Client: 네트워크 게임에서 클라이언트 전용 실행 파일을 빌드합니다.
Server: 네트워크 게임에서 전용 서버 실행 파일을 빌드합니다.

쿠킹 (Cooking) 설정

쿠킹은 최종 빌드에 포함될 콘텐츠를 효율적으로 만드는 과정입니다.

List of maps to include in a packaged build (패키지 빌드에 포함할 맵 목록):
- 필수 확인 사항: 게임에 사용되는 모든 맵(시작 맵, 플레이 맵, 로딩 맵 등)이 이 목록에 추가되어야 합니다. 누락되면 게임에서 해당 맵을 로드할 수 없습니다.
Cook everything in the project content directory (프로젝트 콘텐츠 디렉토리의 모든 것을 쿠킹):
- 활성화 시, 콘텐츠 폴더 내의 모든 에셋을 빌드에 포함하려고 시도합니다. 간편하지만, 불필요한 에셋이 포함될 수 있어 빌드 크기가 커질 수 있습니다.
- 비활성화 시, 위에 설정된 맵 목록과 맵에서 직접 참조되는 에셋만 쿠킹합니다. 빌드 크기 최적화에 유리하지만, 동적으로 로드되는 에셋이 누락될 수 있으므로 주의해야 합니다.
Generate chunk files (청크 파일 생성)
- 게임 데이터를 여러 개의 청크(.pak 파일)로 분할하여 생성합니다.
- 활용: 대용량 게임에서 특정 청크만 다운로드하거나, 패치를 용이하게 할 때 사용됩니다.
- 설정: Project Settings > Game > Asset Manager에서 Primary Asset Types to Scan과 Chunk IDs를 설정하여 어떤 에셋이 어떤 청크에 포함될지 정의할 수 있습니다. (고급 기능)

패키징 설정

Use Pak File (Pak 파일 사용)
- 권장: 활성화하여 모든 게임 데이터를 .pak 파일이라는 하나의 압축된 아카이브 파일로 묶습니다.
- 장점: 파일 수 감소, 파일 크기 감소, 디스크 I/O 최적화, 로딩 속도 향상, 데이터 암호화 및 무단 변조 방지에 유리합니다.
- 비활성화 시, 모든 에셋이 원본 파일 형태로 배포됩니다.
For Distribution (배포용)
- 활성화 시, 최종 배포를 위한 추가적인 최적화 및 보안 기능이 적용됩니다. (예: 추가적인 데이터 압축, 일부 디버그 정보 제거, 플랫폼별 서명 요구 사항 활성화)
- 특히 모바일 플랫폼에서 앱 스토어에 제출할 때 필수적입니다.
Encrypt Ini Files / Encrypt Pak Index / Encrypt UAsset Files (Ini 파일 / Pak 인덱스 / UAsset 파일 암호화)
- 활성화 시, 게임 데이터에 암호화를 적용하여 데이터 추출 및 변조를 어렵게 합니다. 보안이 중요한 게임에 유용합니다.
- 주의: 암호화를 사용하려면 Project Settings > Crypto에서 암호화 키를 설정해야 합니다.

플랫폼별 패키징 설정 (재강조 및 추가)

Build Config
목적별 구성 선택
Cook
필요 에셋 변환
Package
실행 파일 구성
Smoke Test
실행과 로그 확인
Development
디버깅과 로그가 필요한 내부 검증 단계에 적합합니다.
Shipping
최종 배포용으로 최적화와 불필요한 디버그 정보를 줄입니다.
Cook by the Book
대상 플랫폼에 맞춰 에셋을 미리 변환해 패키징 안정성을 높입니다.
Platform Profile
해상도, 입력, 압축, 권한 설정을 플랫폼별로 분리해 확인합니다.
실패가 자주 나는 지점
누락된 맵과 에셋 참조를 먼저 확인합니다. 플러그인과 SDK 버전이 대상 플랫폼 요구사항과 맞는지 점검합니다. 패키징 성공 뒤에도 첫 실행, 저장, 네트워크, 종료 흐름을 확인합니다.
출시 전 기준
Maps 필수 맵 포함 SDK 플랫폼 버전 Logs 치명 오류 없음 Input 기기별 조작

각 대상 플랫폼에 따라 추가적인 설정이 필요합니다.

Windows
- Project Settings > Platforms > Windows
- Target RHI: 사용할 렌더링 API (DirectX 11, DirectX 12, Vulkan 등). 기본적으로 모든 지원 API를 포함하지만, 특정 API만 포함하여 빌드 크기를 줄일 수 있습니다.
- Packaging 섹션에서 런타임에 필요한 Prerequisites (예: Visual C++ Redistributable)를 설치 프로그램에 포함할지 여부를 설정할 수 있습니다.
Android
- Project Settings > Platforms > Android
- APK Packaging
  - Build Configuration: Shipping
  - Package for Google Play: Google Play Store 배포 시 활성화 (AAB 파일 생성).
  - ETC2 / DXT / ASTC 등 Texture Compression Format 선택: 디바이스 호환성 및 파일 크기에 큰 영향을 미칩니다. 모든 디바이스를 지원하려면 여러 포맷을 포함해야 할 수 있습니다.
  - Architectures to Package: ARM64 활성화.
- Signing: Android SDK 설치 시 생성된 Keystore 파일을 사용하여 앱 서명 정보를 설정해야 합니다. (이름, 별칭, 비밀번호 등)
iOS
- Project Settings > Platforms > iOS
- Bundle Identifier, Version Number, Build Number 설정.
- Signing: Apple Developer 계정에서 발급받은 Certificate 및 Provisioning Profile을 설정해야 합니다.
- Supported Orientations: 세로/가로 모드 지원 여부.
콘솔: 각 콘솔 제조사(Sony, Microsoft, Nintendo)의 개발자 프로그램에 등록하고, 해당 SDK가 설치된 환경에서 언리얼 엔진의 전용 빌드 파이프라인을 사용해야 합니다. 설정은 콘솔별로 다릅니다.

패키징 실행 및 문제 해결

1
Build
컴파일 오류, 모듈 누락, 플러그인 의존성 오류를 먼저 확인합니다. C++/Plugin
2
Cook
에셋 로드 실패, 머티리얼 컴파일, 플랫폼 미지원 리소스를 추적합니다. Asset
3
Stage
파일 복사, 경로 길이, 권한 문제로 패키지 폴더 구성이 실패하는지 봅니다. File system
4
Package
압축, 서명, 배포 포맷 생성 단계에서 발생한 오류를 따로 읽습니다. Distribution
5
로그 보존
성공/실패 로그를 빌드 번호와 묶어 비교 가능하게 남깁니다.
6
변경 단위
설정, 에셋, 코드 변경을 한 번에 섞어 재시도하지 않습니다.
7
자동화
동일 명령으로 로컬과 CI에서 같은 패키지를 만들 수 있어야 합니다.

패키징 실행

파일(File) > 프로젝트 패키징(Package Project) > [대상 플랫폼]을 선택합니다.
패키징이 시작되고 출력 로그(Output Log) 창에서 진행 상황을 확인할 수 있습니다.
성공적으로 완료되면 지정된 출력 폴더에 실행 가능한 게임 파일이 생성됩니다.

일반적인 패키징 오류 및 해결책

쿠킹 실패 (Cook Failed)
- 원인: 콘텐츠에 오류(잘못된 참조, 누락된 에셋, 컴파일 오류가 있는 블루프린트)가 있는 경우.
- 해결: 출력 로그를 자세히 확인하여 어떤 에셋 또는 블루프린트에서 오류가 발생했는지 파악하고 수정합니다. Fix Up Redirectors in Folder (콘텐츠 브라우저에서 폴더 우클릭)를 주기적으로 실행하여 리다이렉터(Redirector) 오류를 수정합니다.
링킹 실패 (Linking Failed)
- 원인: C++ 코드에 컴파일 오류가 있거나, 종속성 문제가 있는 경우.
- 해결: Visual Studio에서 C++ 프로젝트를 빌드하여 오류를 먼저 해결합니다.
서명 실패 (Signing Failed) (주로 모바일)
- 원인: Android Keystore 정보가 잘못되었거나, iOS 인증서/프로비저닝 프로파일이 만료되었거나 잘못 설정된 경우.
- 해결: 플랫폼별 서명 설정(Project Settings > Platforms > Android/iOS)을 다시 확인하고, 유효한 서명 정보를 사용합니다.
맵 누락 (Map Not Found)
- 원인: Project Settings > Packaging > List of maps to include in a packaged build에 필요한 맵이 포함되지 않은 경우.
- 해결: 해당 맵을 목록에 추가합니다.
크래시 (Crash) 발생
- 원인: 패키징된 빌드 실행 중 크래시가 발생하면, 디버그 정보가 거의 없으므로 Shipping 빌드 대신 Development 또는 DebugGame 빌드로 패키징하여 문제를 재현하고 디버거를 붙여 원인을 파 찾습니다.

배포 직전 검증 순서 (성능/안정성)

Development 빌드에서 기능 회귀를 먼저 제거합니다.
동일 커밋으로 Shipping 빌드를 만들고 로딩 시간/FPS/메모리를 측정합니다.
인증/로그인/세이브 같은 상태 저장 기능이 패키징 후에도 동일하게 동작하는지 확인합니다.
패치 업데이트를 고려해 빌드 산출물 버전과 맵 포함 목록을 다시 점검합니다.
배포 후보 빌드는 클린 환경(새 PC/새 계정)에서 최종 검증합니다.

아래 다이어그램은 패키징 성공 이후에도 릴리스 후보를 통과시키기 위해 확인해야 하는 실행 환경, 콘텐츠 포함, 플랫폼 서명, 회귀 테스트 기준을 한눈에 묶은 것입니다.

새 환경 첫 실행
clean run 개발 PC 캐시나 에디터 설정에 의존하지 않는지 확인합니다. ✓ 새 계정 또는 새 PC에서 실행 ✓ 필수 런타임 설치 여부 확인
맵과 에셋 포함
content 시작 맵, 로딩 맵, 동적 로드 에셋이 빠지지 않았는지 봅니다. ✓ 필수 맵 목록 검수 ✓ 패키징 로그의 누락 참조 확인
플랫폼 요구사항
platform 서명, 권한, SDK, 압축 포맷이 제출 대상과 맞아야 합니다. ✓ Android/iOS 서명 정보 ✓ 압축 포맷과 아키텍처
핵심 기능 회귀
regression 저장, 로그인, 네트워크, 옵션 변경처럼 상태가 남는 기능을 재확인합니다. ✓ Shipping 빌드 전용 오류 확인 ✓ FPS, 메모리, 로딩 시간 기록

패키징/배포 오류 점검 체크리스트

Cook Failed의 원인 에셋을 로그 기준으로 정확히 특정했는가?
플랫폼 서명(Android/iOS) 만료/권한 문제를 사전 점검했는가?
포함 맵 목록 누락으로 실행 불가 맵이 생기지 않았는가?
Shipping 빌드에서만 재현되는 크래시를 별도로 테스트했는가?
배포 산출물(실행 파일, DLC/패치 파일, 버전 문서) 정합성을 검수했는가?

패키징 및 빌드 설정은 목표 플랫폼에 맞는 재현 가능한 빌드를 만드는 과정입니다.

빌드 구성, 쿠킹 설정, 플랫폼별 패키징 설정, 테스트 절차를 함께 관리해야 합니다.

패키징 오류는 메시지 종류에 따라 원인 위치가 달라지므로, 아래처럼 먼저 분기해 점검하면 좋습니다.

에셋 경로
Cook Failed 누락 참조, Redirector, 손상된 에셋을 먼저 확인합니다.
키와 인증서
Signing Failed 플랫폼별 서명 파일, 비밀번호, 프로비저닝을 맞춥니다.
포함 맵 목록
맵 누락 실행 시작 맵과 이동 가능한 맵이 패키지에 들어갔는지 봅니다.
재현 빌드
Shipping Crash Development 빌드로 다시 만들어 콜스택과 로그를 확보합니다.

이 페이지의 목차