패키징 및 빌드 설정

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

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

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

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

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

---

패키징 및 빌드의 이해

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

일반적인 패키징 작업은 다음 단계를 구분합니다. 로그에서도 실패한 단계를 먼저 확인합니다.

1. Build: 프로젝트·플러그인의 코드를 컴파일하고 링크해 대상 플랫폼용 바이너리를 만듭니다.
2. Cook: 에셋을 대상 플랫폼에서 읽을 형식으로 변환합니다.
3. Stage: 실행 파일과 쿠킹된 콘텐츠를 별도 스테이징 폴더로 모읍니다.
4. Package: 플랫폼별로 배포할 파일 묶음을 구성합니다. Pak은 콘텐츠 컨테이너이며 실행 파일 자체와는 구분합니다.

Deploy(장치로 전달)와 Run(실행)은 필요할 때 이어지는 별도 작업입니다.

---

패키징 설정 핵심 항목

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

빌드 구성 (Build Configuration)

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

심볼은 Shipping에서도 생성·보관할 수 있습니다. 배포 파일에 포함할지와 내부 심볼 서버에 보관할지를 분리하며, 구성만으로 파일 크기나 실제 성능 순위를 확정하지 않습니다. Debug/Test 등의 가용성은 엔진 소스 빌드·프로젝트·타깃에 따라 다릅니다.

빌드 타겟 (Build Target)

• 프로젝트 세팅 > 프로젝트 > 패키징 또는 파일 > 프로젝트 패키징 메뉴에서 선택할 수 있습니다.
• Game: 일반적인 게임 실행 파일을 빌드합니다. (주로 사용)
• Client: 네트워크 게임에서 클라이언트 전용 실행 파일을 빌드합니다. 해당 Client Target 설정이 필요합니다.
• Server: 네트워크 게임에서 전용 서버 실행 파일을 빌드합니다. 해당 Server Target 설정과 지원되는 엔진 빌드가 필요합니다.

쿠킹 (Cooking) 설정

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

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

패키징 설정

• Use Pak File (Pak 파일 사용)
  • 권장: 쿠킹된 콘텐츠를 하나 이상의 .pak 아카이브로 묶습니다. Io Store가 활성화되면 .utoc/.ucas 사용도 확인합니다.
  • 장점: 파일 관리를 묶어 처리할 수 있습니다. 압축·암호화·서명은 별도 설정이며 실제 크기와 로딩 성능은 측정합니다.
  • 다른 컨테이너도 사용하지 않으면 쿠킹된 파일을 개별 배치합니다. 에디터의 원본 에셋 그대로 배포한다는 뜻은 아닙니다.
• For Distribution (배포용)
  • 앱 스토어 제출 등 플랫폼의 배포 구성을 선택합니다. 압축·암호화·서명 키는 각각 별도로 설정합니다.
  • 대상 플랫폼과 스토어의 제출 지침에 맞춰 적용합니다.
• Encrypt Ini Files / Encrypt Pak Index / Encrypt UAsset Files (Ini 파일 / Pak 인덱스 / UAsset 파일 암호화)
  • 활성화 시, 게임 데이터에 암호화를 적용하여 데이터 추출을 어렵게 합니다. 무결성 검증을 위한 서명과 구분하고 클라이언트 암호화만으로 완전한 보호를 보장하지 않습니다. 보안이 중요한 게임에 유용합니다.
  • 주의: 암호화를 사용하려면 Project Settings > Crypto에서 암호화 키를 설정해야 합니다.

---

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

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

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

---

패키징 실행 및 문제 해결

패키징 실행

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

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

• 쿠킹 실패 (Cook Failed)
  • 원인: 콘텐츠에 오류(잘못된 참조, 누락된 에셋, 컴파일 오류가 있는 블루프린트)가 있는 경우.
  • 해결: 출력 로그를 자세히 확인하여 어떤 에셋 또는 블루프린트에서 오류가 발생했는지 파악하고 수정합니다. Fix Up Redirectors in Folder (콘텐츠 브라우저에서 폴더 우클릭)를 주기적으로 실행하여 리다이렉터(Redirector) 오류를 수정합니다.
• 링킹 실패 (Linking Failed)
  • 원인: 컴파일 단계와 구분해 미해결 심볼, 누락 라이브러리, 모듈 종속성 등을 확인합니다.
  • 해결: 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에서도 재현을 시도하되 Shipping에서만 발생하는 오류는 원래 구성에서 확인합니다.

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

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

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

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

오류 로그는 마지막 실패 요약뿐 아니라 해당 실패를 유발한 앞선 오류를 함께 읽습니다. Stage 실패라면 복사 경로·권한·디스크 공간도 확인하고, 로그와 산출물을 빌드 번호에 연결해 보관합니다.