Skip to content

Package a build

Programmer · 1–2 h (mostly waiting) · No code (editor menus; one optional command line)

Result: a Windows build of your game that boots to the title screen, starts a new game in your map, and has every menu working, checked in the packaged build rather than only in the editor.

Before you start

What packaging does here

The project is Lyra with XenoCore added, so it packages as Lyra does: the LyraGame target, Development configuration by default, compressed into pak files. The editor-only XenoCoreEditor module is left out automatically.

Two XenoCore specifics shape the packaging settings. The Apply step of Install and first launch writes both into your project's Config/DefaultGame.ini. If you are not sure it ran, use Tools › XenoCore › Apply XenoCore Project Settings; it changes nothing that is already set:

  • Some assets are found by path, not by reference. The shop, trade, arts, save, quest and loot screens and the dialogue anchor are loaded by a fixed path from C++. The cooker can't see those paths, so the project cooks /XenoCore/UserInterface and /XenoCore/Characters/NPC in full (Additional Asset Directories to Cook in the packaging settings). Keep them there.
  • Maps reached only by a setting must be listed. The new-game map and any map a save file names are soft references. The shipped list is L_XenoCore_FrontEnd, L_XenoCore_GaurPlain (where New Game starts) and L_XenoCore_Gym. List every map you ship.

Steps

1. Check the packaging settings

Open Project Settings › Project › Packaging:

  1. Build Configuration: Development while testing; Shipping for release.
  2. List of maps to include in a packaged build: your title map (Maps/L_XenoCore_FrontEnd unless you replaced it) and every playable map. The shipped list is the front end, L_XenoCore_GaurPlain and L_XenoCore_Gym; remove the sample maps once yours replace them.
  3. Additional Asset Directories to Cook: keep /XenoCore/UserInterface and /XenoCore/Characters/NPC. Add any folder of yours whose assets are loaded only by path.
  4. Directories to Never Cook: add your own test or scratch folders.
  5. For Distribution: tick for the build you release.

Fails silently: a map left off the list

The packaged title screen works, and New Game or Load goes nowhere, because the map was never cooked. The editor never shows this; only a packaged build does.

Fails silently: shipped content that uses a never-cooked asset

Anything that references an asset in a Directories to Never Cook folder works in the editor and arrives in the build with that asset missing (a silent level, a default material). Before packaging, open the Reference Viewer on the test assets you have used, or keep your own test content out of shipped folders altogether.

2. Check which plugins ship

Your Lyra project still carries Lyra's own sample game features (ShooterCore, ShooterMaps, ShooterExplorer, TopDownArena and others), and they cook unless you turn them off. XenoCore.uplugin declares every plugin XenoCore's content needs (Niagara, Niagara UI Renderer, Water, DataRegistry, Metasound and VRM4U among them), so they stay on whatever you disable. See Compatibility for the list.

  1. Open Edit › Plugins, filter by Enabled.
  2. Disable what your game doesn't use. Re-open the editor and play-test after each change.

VRM4U is needed at runtime

The sample party is VRoid characters, and their materials, spring bones and facial expressions use the VRM4U plugin in the game, not only at import. Keep it enabled while any VRoid character ships. It compiles from source with the rest of the project; its assimp library is in Plugins/VRM4U/ThirdParty/assimp, and a packaged build links it.

3. Set the version

Set Project Settings › Project › Description › Project Version. XenoCore draws this version in the bottom-right corner of every screen, including in packaged builds, so a bug report can name the build.

4. Package

From the editor: Platforms › Windows › Package Project, and choose an output folder.

For programmers: the same from the command line

Unreal Automation Tool runs the whole package without the editor:

"<Engine>\Engine\Build\BatchFiles\RunUAT.bat" BuildCookRun -project="<project folder>\Lyra.uproject" -noP4 -target=LyraGame -platform=Win64 -clientconfig=Development -build -cook -stage -pak -iostore -archive -archivedirectory="<output folder>" -unattended

Fails silently: the exit code can say success

Build.bat and some automation steps can return exit code 0 after a failed step. Don't trust the exit code or a "finished" message. Read the end of the log for BUILD SUCCESSFUL (or Result: Succeeded from Build.bat) and search it for Error:.

5. Test the packaged build, not the editor

Run the .exe from the output folder and go through the whole path:

  1. The boot screens play, then the title screen.
  2. New Game loads your map, with your party.
  3. Open every menu screen: Items, Equipment, Arts, Party, Quests, Save.
  4. Talk to an NPC, open a shop and a trade, open a chest after a fight.
  5. Save, quit to title, Continue.

Anything that works in the editor and not here is almost always a missing cooked asset.

Test it

The packaged game completes step 5 with nothing missing, and its log (<output folder>/Windows/Lyra/Saved/Logs/Lyra.log) has no LoadErrors or "failed to load" lines for your assets.

If it doesn't work

A menu or popup never opens in the build

It is loaded by path and its folder is not cooked. Add the folder to Additional Asset Directories to Cook, or move the asset back where XenoCore expects it.

The build fails on a plugin you don't use

Disable that plugin in Edit › Plugins rather than fixing it. Do not disable one that XenoCore.uplugin lists; XenoCore's content will fail to load without it.

The package is far bigger than expected

Sample content, pack assets or unused Lyra features are still being cooked. Right-click each of your maps in the Content Browser and choose Size Map... to see what it pulls in, and see Megascans at shipping size.

More in Build and editor troubleshooting.

Going further