/unreal-packaging

name: unreal-packaging
description: >
  Packages 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

1. **Read the project and engine.** `EngineAssociation` in the `.uproject` is a version such as `5.8` for 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). 2. **Set what loads and what cooks.** Project Settings → Maps & Modes → **Game Default Map** (stored as `GameDefaultMap` in `Config/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". 3. **Validate content:** `UnrealEditor-Cmd <Project>.uproject -run=DataValidation -unattended` and fix every error before cooking. 4. **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" \
     -utf8output

Swap `-clientconfig=Shipping` for 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. 5. **Read the logs on failure.** UAT prints the path of its log (`Log.txt`) and of the cook log (`Cook-*.txt`). Search them for `Error:`; 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 under `Engine/Programs/AutomationTool/Saved/Logs`. 6. **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.

1. **UAT result:** the run ends with `BUILD SUCCESSFUL` and exit code 0, and the archive directory contains the executable plus `.pak`/`.utoc`/`.ucas` files under `<Project>/Content/Paks`. 2. **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 expected `LoadMap(/Game/...)` line and for any `Fatal error`, `Error:` or missing-asset warnings. 3. **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. 4. **Optional:** if the project has automation tests, run them on the packaged Development build or in the editor as in `unreal-cpp-gameplay` before 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 `.uasset` files:** in 5.8 Zen Server is the cooked

output store by default, so that folder holds only a small `ue.projectstore` marker. Ship the staged or archived folder, built with `-pak`. Staging to loose files without `-pak` produces 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=false` under `[Zen.AutoLaunch]` in `DefaultEngine.ini`; make sure the build agent tolerates the long-running `zenserver` process.

• **Shipping-only bug with no log:** Shipping strips `UE_LOG` and the console. Reproduce in a

Test build, which keeps some tooling with Shipping-like optimizations.

• **No way to quit a Shipping build:** the console `quit` command 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](https://dev.e