Ue Packaging And Deployment

Packaging & deployment

Shipping an Unreal project involves three distinct stages that run in sequence: build (compile the game executable), cook (convert assets to the target platform's runtime format), and package (assemble the cooked assets and executable into a distributable build, typically inside pak/IoStore containers). Each stage can fail independently; diagnosing a failure means identifying which stage it belongs to.

When to use this skill

• Producing a runnable build for a platform (automated CI or manual).
• Diagnosing a cook or package failure, or a build that works in PIE but breaks packaged.
• Configuring what content ships: always-cook directories, never-cook exclusions, shader sharing.
• Setting up pak chunking for streaming installs, patching, or DLC.
• Choosing the right build configuration and target for a given deployment scenario.

Build configurations and targets

Target types — defined by *.Target.cs files, one per target:

Source: TargetType enum — Engine/Source/Programs/UnrealBuildTool/Configuration/Rules/TargetRules.cs:21.

Build configurations — controls optimization and what debugging/logging facilities are compiled in:

Source: UnrealTargetConfiguration enum — Engine/Source/Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs:1147.

The packaging UI (EProjectPackagingBuildConfigurations) mirrors these five values as PPBC_Debug … PPBC_Shipping — see ProjectPackagingSettings.h:18.

Key rule: always test the Shipping (or Test) configuration before release. check() macros, most UE_LOG calls, and the console are stripped or limited in Shipping — never put logic inside a check or rely on console state in packaged builds. See ue-logging-and-assertions.

The cook process

Cooking converts editor assets (.uasset, textures, audio) into the target platform's runtime format. The cooker is invoked as a special commandlet mode of UnrealEditor-cmd.

What gets cooked: assets reachable via hard or soft references from the startup map and any "always cook" directories/entries. Unreferenced content is not cooked. This is why a purely string-loaded asset (soft path with no reference) silently disappears unless you declare it via the Asset Manager or DirectoriesToAlwaysCook.

Cook modes:

• By-the-book (CBTB): entire cook runs up front; produces the full set of cooked packages before packaging. Required for final/CI builds.
• Cook on the fly (COTF): a cook server on the host machine serves packages on demand as a connected device requests them. Faster iteration, but not suitable for final builds.

Cook rules (per primary asset, set via Asset Manager or DefaultGame.ini):

• AlwaysCook — include regardless of reference.
• NeverCook — exclude even if referenced (e.g. editor-only test assets).
• Unknown — follow reference graph (default).

Shader code can be shared across materials via bShareMaterialShaderCode in UProjectPackagingSettings — reduces duplication at a small load-time cost.

UAT BuildCookRun — the canonical pipeline

The Unreal Automation Tool (RunUAT.bat / RunUAT.sh) orchestrates the full pipeline via its BuildCookRun command:

Engine/Build/BatchFiles/RunUAT.bat BuildCookRun \
  -project=D:/MyGame/MyGame.uproject \
  -noP4 \
  -platform=Win64 \
  -clientconfig=Shipping \
  -build \
  -cook \
  -allmaps \
  -stage \
  -pak \
  -archive \
  -archivedirectory=D:/Builds/MyGame_Shipping

Each flag maps to a stage: -build compiles the target, -cook runs the cooker, -stage copies to a staging directory, -pak wraps cooked content into .pak/IoStore containers, -archive copies the final build to the output path. Omit any stage to skip it (e.g. skip -build when the executable is already built by a separate CI step).

Add -iostore to enable IoStore container output (.utoc/.ucas) instead of classic .pak-only output. This matches enabling bUseIoStore in Project Settings.

UAT script path (C#): Engine/Source/Programs/AutomationTool/Scripts/BuildCookRun.Automation.cs.

Full BuildCookRun flag reference: references/buildcookrun-and-uat.md.

Pak files and the IoStore container format

After cooking, content is packaged into containers for distribution:

• Classic pak (.pak): a simple archive format; a single monolithic file or one per chunk. Still fully supported; adequate for many projects.
• IoStore (.utoc + .ucas): the modern default. .utoc is the table of contents; .ucas holds the bulk payload. Offers faster I/O via the IoDispatcher because packages are addressed by hash ID rather than path. Enabled via bUseIoStore = true in Project Settings (or -iostore flag to UAT).

Both formats support compression (bCompressed, PackageCompressionFormat) and encryption (configured via the crypto key system, not the deprecated ini flags).

Chunking splits content across multiple pak/IoStore containers for streaming installs, DLC, or patching. Each chunk maps to a numbered .pak / .ucas file (e.g. pakchunk1-Windows.pak). Chunk 0 is the base install; chunks 1+ are downloaded separately. Configure via bGenerateChunks = true and Primary Asset Rules.

Details: references/pak-iostore-and-chunking.md.

ProjectPackagingSettings — what ships

UProjectPackagingSettings (UCLASS(config=Game, defaultconfig)) persists to Config/DefaultGame.ini under section [/Script/UnrealEd.ProjectPackagingSettings]. Key properties (verified in Engine/Source/Developer/DeveloperToolSettings/Classes/Settings/ProjectPackagingSettings.h):

Access in code: GetDefault<UProjectPackagingSettings>() (editor only).

Platforms, Device Profiles, and scalability

Each platform target (Win64, Android, iOS, console) requires its SDK and platform files. Platform-specific packaging overrides live in Config/[Platform]/[Platform]Game.ini.

Device Profiles (DeviceProfiles.ini) set per-platform CVars and scalability groups — the correct way to vary rendering quality per platform. Never hardcode r.* CVars in C++ or Blueprint; use Device Profiles so the cooker and runtime can select them correctly.

A Client/Server split (Game + Server targets built separately) is the standard multiplayer packaging pattern; the server binary runs headless and ships without rendering modules. See ue-networking-and-replication.

Content-on-demand / IoStore On-Demand

The IoStore On-Demand system (Runtime/Experimental/IoStore/OnDemand/) allows a shipped game to fetch content from a CDN at runtime rather than requiring it to be installed upfront. The IOnDemandIoStore interface (IoStoreOnDemand.h) manages requests with statuses Pending / Ok / Cancelled / Error. This is the foundation for streaming installs, live-service content drops, and large-world on-demand streaming beyond what the base chunk system handles.

Shipping vs. development (mind the gap)

Always smoke-test a packaged Shipping build before release — PIE and Development builds mask many of these gaps. Guard editor-only code with #if WITH_EDITOR so it compiles out of runtime targets. See ue-logging-and-assertions for verify vs check.

Gotchas

• Editor-only API in runtime code — cook/link errors; gate with #if WITH_EDITOR.
• Content not reachable — not cooked → missing at runtime. Hard-ref or add to DirectoriesToAlwaysCook. Use the Asset Audit window to inspect chunk assignments.
• Works in PIE, broken packaged — typically editor-only deps, uncooked assets, or absolute file paths.
• check/ensure/UE_LOG used for logic — silently does nothing in Shipping; never put required side-effects inside them.
• Hardcoded r.* CVars — bypass Device Profiles and platform-specific scalability.
• Forgot -iostore flag with IoStore settings — UAT and Project Settings must agree.
• bUseZenStore without bUseIoStore — Zen Store is a no-op unless IoStore is enabled.
• Wrong target cooked — cooking the Editor target instead of Game produces an unrunnable result; confirm the BuildTarget in ProjectPackagingSettings.
• Cook time blowup — enable iterative cooking (-iterate flag to UAT) during iteration; disable for final CI builds to guarantee a clean output.

Version notes

• IoStore as modern default: bUseIoStore defaults to true for new projects as of UE5. Classic .pak-only builds still work. Console platforms often require IoStore.
• Zen Store (bUseZenStore): introduced in UE5, off by default, used by some large first-party titles to centralize cooked data.
• Blueprint nativization is deprecated (removed in UE5, UE_DEPRECATED(5.0, ...)); do not rely on it.

References & source material

Engine source (UE 5.8):

• UProjectPackagingSettings (properties, enums, cook rules) — Engine/Source/Developer/DeveloperToolSettings/Classes/Settings/ProjectPackagingSettings.h:179. EProjectPackagingBuildConfigurations:18, EAssetRegistryWritebackMethod:106, bUseIoStore:250, bGenerateChunks:265, bCompressed:323, DirectoriesToAlwaysCook:568.
• TargetType enum — Engine/Source/Programs/UnrealBuildTool/Configuration/Rules/TargetRules.cs:21.
• UnrealTargetConfiguration enum (Debug…Shipping) — Engine/Source/Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs:1147.
• BuildCookRun UAT command class — Engine/Source/Programs/AutomationTool/Scripts/BuildCookRun.Automation.cs:24.
• IoStore container format (EIoStoreTocVersion, FIoStoreTocHeader) — Engine/Source/Runtime/Core/Internal/IO/IoStore.h:25.
• IoStore On-Demand (IOnDemandIoStore:647, FOnDemandRequest:46) — Engine/Source/Runtime/Experimental/IoStore/OnDemandCore/Public/IO/IoStoreOnDemand.h.
• WITH_EDITOR, WITH_EDITORONLY_DATA preprocessor guards — Engine/Source/Runtime/Core/Public/Misc/Build.h:66.

Official docs (UE 5.8, all fetched and confirmed live):

• Build Configurations Reference — https://dev.epicgames.com/documentation/unreal-engine/build-configurations-reference-for-unreal-engine
• Build Operations: Cook, Package, Deploy, and Run — https://dev.epicgames.com/documentation/unreal-engine/build-operations-cooking-packaging-deploying-and-running-projects-in-unreal-engine
• Cooking and Chunking — https://dev.epicgames.com/documentation/unreal-engine/cooking-content-and-creating-chunks-in-unreal-engine
• Project Launcher Reference — https://dev.epicgames.com/documentation/unreal-engine/using-the-project-launcher-in-unreal-engine
• Patching, Content Delivery, and DLC — https://dev.epicgames.com/documentation/unreal-engine/patching-content-delivery-and-dlc-in-unreal-engine
• Sharing and Releasing Projects — https://dev.epicgames.com/documentation/unreal-engine/sharing-and-releasing-projects-for-unreal-engine

Deep-dive references in this skill:

• references/cook-and-build-configs.md — cook pipeline internals, cook rules, shader sharing, iterative cook, cook commandlet options.
• references/buildcookrun-and-uat.md — full BuildCookRun flag reference, UAT structure, CI patterns.
• references/pak-iostore-and-chunking.md — pak vs IoStore format details, chunk assignment (Asset Manager, Primary Asset Labels, config overrides), compression, encryption.
• references/platform-and-dlc.md — platform targets, Device Profiles, Client/Server split, IoStore On-Demand / content-on-demand, patching.

Related skills: ue-module-and-build-system, ue-asset-management, ue-logging-and-assertions, ue-networking-and-replication, ue-project-structure.