gamedev-skills/awesome-gamedev-agent-skills / skills/unreal/unreal-packaging
unreal-packaging
VerifiedPackages and ships Unreal Engine 5 (UE 5.8) projects: Shipping builds, cooking, pak/IoStore and RunUAT BuildCookRun with UAT and cook log reading. Use for a packaged game with a black screen, a map missing in the build, "BUILD FAILED" or an AutomationTool exit code. Not for store uploads (`steam-publish`, `itch-publish`) or gameplay compile errors (`unreal-cpp-gameplay`).
Unreal Packaging & Cooking
Turn a UE5 project into a build that starts on the right map and runs on a machine without the editor, and make that build reproducible from a command line. Targets UE 5.8.
When to use
- Producing a test or release build; choosing Development, Test or Shipping; setting the launch map and which content gets cooked.
- Scripting builds for CI with
RunUAT BuildCookRun, or reading why one failed. - Understanding where cooked and staged output goes, including the Zen store.
When not to use: store submission and depots → steam-publish / itch-publish.
Gameplay C++ compile errors → unreal-cpp-gameplay. Building the engine from source is out of
scope.
Workflow
-
Read the project and engine.
EngineAssociationin the.uprojectis a version such as5.8for a Launcher engine and a GUID (or empty) for a source build; console platforms need a source build. Check that the platform SDK on the build machine meets the engine's minimum (see Version notes). -
Set what loads and what cooks. Project Settings → Maps & Modes → Game Default Map (stored as
GameDefaultMapinConfig/DefaultEngine.ini). Maps that are only opened by name at runtime must be listed in Packaging → "List of maps to include in a packaged build" or cooked with-map=; assets loaded only by path need "Additional Asset Directories to Cook". -
Validate content:
UnrealEditor-Cmd <Project>.uproject -run=DataValidation -unattendedand fix every error before cooking. -
Build with UAT (default), even when the user packages from the editor, because the command line is reproducible:
# From Engine/Build/BatchFiles (RunUAT.bat on Windows, RunUAT.sh on macOS and Linux) RunUAT BuildCookRun -project="<abs path>/MyGame.uproject" -noP4 \ -platform=Win64 -clientconfig=Development \ -build -cook -stage -pak -archive -archivedirectory="<abs path>/Builds" \ -utf8outputSwap
-clientconfig=Shippingfor release. Cook a subset with-map=Start+Level01. The editor path (Platforms → Windows → Package Project) and Project Launcher profiles run the same steps; a Launcher profile prints its full UAT command line in the Output Log. -
Read the logs on failure. UAT prints the path of its log (
Log.txt) and of the cook log (Cook-*.txt). Search them forError:; the first error is usually the cause and the rest follow from it. Launcher engines on Windows write them under%APPDATA%\Unreal Engine\AutomationTool\Logs\<engine path>, source builds underEngine/Programs/AutomationTool/Saved/Logs. -
Run the packaged build (see Verify). A finished cook proves the content converted, not that the game starts.
Verify
Say which of these you ran and quote the lines that prove it.
- UAT result: the run ends with
BUILD SUCCESSFULand exit code 0, and the archive directory contains the executable plus.pak/.utoc/.ucasfiles under<Project>/Content/Paks. - Smoke-run a Development build from the archive with a log file:
<archive>/Windows/MyGame.exe -log -unattended -windowed -ResX=1280 -ResY=720 -abslog="<dir>/smoke.log"(on a machine without a GPU, add-nullrhi). Let it reach the first map, close it, then check the log for the expectedLoadMap(/Game/...)line and for anyFatal error,Error:or missing-asset warnings. - Shipping builds strip logging, so smoke-test the same content as Development or Test first, then ask the user to launch the Shipping build and report whether it reaches the main menu and can quit from the game's own menu.
- Optional: if the project has automation tests, run them on the packaged Development
build or in the editor as in
unreal-cpp-gameplaybefore shipping.
Gotchas
- Black screen or empty level in the build: Game Default Map is unset, or that map (or a map it opens by name) wasn't cooked.
- Asset exists in the editor, missing in the build: nothing hard-references it, so the cooker skipped it. Add its directory to cook, or reference it from a cooked asset.
Saved/Cooked/<Platform>has no.uassetfiles: in 5.8 Zen Server is the cooked output store by default, so that folder holds only a smallue.projectstoremarker. Ship the staged or archived folder, built with-pak. Staging to loose files without-pakproduces a build that streams content from your Zen server and is not distributable.- Zen server starts and stops on every CI step: for team and CI machines Epic recommends
LimitProcessLifetime=falseunder[Zen.AutoLaunch]inDefaultEngine.ini; make sure the build agent tolerates the long-runningzenserverprocess. - Shipping-only bug with no log: Shipping strips
UE_LOGand the console. Reproduce in a Test build, which keeps some tooling with Shipping-like optimizations. - No way to quit a Shipping build: the console
quitcommand isn't there. The game needs its own exit option. - Platform SDK errors early in the build: the installed Visual Studio, Windows SDK or Xcode is older than the engine minimum, or a console platform is used with a Launcher engine.
- First cook takes very long: shaders and every asset cook from scratch; later cooks are incremental. A slow first cook is not a hang; watch the cook log grow.
- Expecting Blueprint Nativization: it was removed in UE5. Profile and move hot logic to C++ instead.
References
- Epic docs: Packaging Your Project, Build operations: cooking, packaging, deploying, Zenserver as Cooked Output Store, Unreal Automation Tool overview.
Related skills
steam-publish/itch-publish: uploading the archived build.unreal-cpp-gameplay: compile errors and automation tests.performance-optimization: profiling the packaged build.
Version notes
Last verified: 2026-11-11.
- Current release: UE 5.8 (5.8.4 hotfix, October 2026); UE 5.9 is in Preview and adds an experimental WebAssembly target with WebGPU rendering.
- UE 5.8 Windows: Visual Studio 2022 17.14 or newer (2026 recommended), MSVC 14.38 minimum (14.50 recommended), Windows SDK 10.0.22621.0 minimum (10.0.26100.0 default). macOS: Xcode 15.2 minimum (15.4 or newer recommended). Linux: clang 20.1.8. Other platforms: see the release notes' Platform SDK Upgrades table.
- UE 5.8 adds experimental Windows on Arm game builds:
-clientarchitecture=arm64, orarm64+x64for side-by-side executables. The editor itself does not run on Arm64 in 5.8. - UE 5.8 makes Zen Server the default cooked output store; projects that had the Zen store turned off keep it off.
- Sources: UE 5.8 release notes, UE 5.9 Preview release notes, 5.8.4 hotfix announcement.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |