Language:
Page Info
Skill Level:
Engine Version:

Packaging Projects

Choose your OS:

Before an Unreal project can be distributed to users, it must be properly packaged. Packaging ensures that all code and content is up to date and in the proper format to run on the desired target platform.

A number of steps will be performed during the packaging process. When a project has custom source code, this code will first be compiled. Then, all required content will be converted, or "cooked", into a format that can be used by the target platform. After that, compiled code and cooked content will be bundled into a distributable set of files, such as an installer for Windows.

Under the main File menu, there is an option called Package Project, with a submenu. This sub menu shows all the platforms that you can prepare a package for. The purpose of packaging is to test your full game instead of a single map, or to prepare your game for submission or distribution.

For packaging on Android, there will be multiple selections. See the Android Texture Formats page for more information.

There are also some Advanced options you can set before packaging.

Setting A Game Default Map

Before packaging your game, you will first need to set a Game Default Map, which will load when your packaged game starts. If you do not set a map and are using a blank project, you will only see a black screen when the packaged game starts. If you have used one of the template maps, like the First Person template or Third Person template, the starting map will be loaded.

To set the Game Default Map, click on Edit > Project Settings > Maps & Modes in the Editor's main menu:

Project_Settings_MapsNModes.png

Creating Packages

To package a project for a specific platform, click on File > Package Project > [PlatformName] in the Editor's main menu:

packaging_menu.png

packaging_menu_Mac.png

You will be presented with a dialog for selecting the target directory. If packaging completes successfully, this directory will then contain the packaged project.

Confirming the target directory will then initiate the actual process that packages the project for the selected platform. Because packaging can be very time consuming, this process is executed in the background, and you can continue to use the Editor. A status indicator will be displayed in the bottom right corner of the Editor to indicate the progress:

progress.png

The status indicator provides a way to cancel the active packaging process by clicking the Cancel button. It is also possible to display extended output log information by clicking the Show Log link. The output log is useful for figuring out what went wrong in case a packaging process did not complete successfully:

log.png

For less experienced users, the most important log messages, such as errors and warnings, are logged to the regular Message Log window:

message_log.png

If these windows are not visible, they can be accessed by the Window > Developer Tools > Output Log / Message Log options.

Running Packaged Games

When packaging, you will be prompted to pick a directory for the output of the packaging process. Your packaged game will be placed in a subdirectory based on its platform. For example, if you selected a directory called C:/PackagedOutput/, a Windows build would be placed in C:/PackagedOutput/WindowsNoEditor/. In that subdirectory, you will find the packaged game in a format appropriate to the platform. For example, Windows games will have a .exe file, Android games will have .apk and .obb files along with a .bat installer, and iOS games will have a .ipa file. The number and type of files created will vary depending on the target platform. The following image shows example output for a Windows project, inside the WindowsNoEditor subdirectory:

results.png

Distribution

To submit an iOS or Android game to the App Store or Google Play Store, you need to create your package in Distribution mode. To do this, go to the Packaging Settings option in the Packaging menu, and check the Distribution check box. This will sign the final package appropriately.

On iOS, you will need to create a Distribution Certificate and MobileProvision on Apple's developer website. Install the Distribution Certificate the same way as your Development certificate, and name your distribution provision with a "Distro_" prefix, next to your other one (so you would have both Distro_MyProject.mobileprovision and MyProject.mobileprovision).

On Android, you will need to create a key to sign the .apk file, and give some information to our build tools with a file called SigningConfig.xml. This file exists in the installed Engine directory (Engine/Build/Android/Java/). If you edit this file, it will apply to all your projects. However, you can copy this file to your project's Build/Android/ directory (without the Java/ subdirectory), and it will be used for just that project. Directions for how to generate the key and fill out the file are found in the file itself.

Advanced Settings

Clicking File > Package Project > Packaging Settings... or Edit > Project Settings > Packaging in the main menu will present you with a number of advanced configuration options for the packaging feature.

settings.png

Currently, these include:

Option

Description

Build Configuration

The build configuration to compile your code-based project with. For debugging a code project, select DebugGame. Note that Blueprint-only projects will not have this option. For most other development with minimal debugging support, but better performance, select Development. For the final shipping build, which will have no debugging information and no debugging-oriented features (such as drawing debug shapes or printing debug messages on the screen), select Shipping.

Staging Directory

The directory that will contain your packaged build. This will be updated automatically when you pick a different directory in the target directory selection.

Full Rebuild

Whether all of your code should be compiled. If disabled, only the modified code will be compiled. This may speed up the packaging process. For shipping builds you should always do a full rebuild to make sure nothing is missing or outdated. This option is enabled by default.

Use Pak File

Whether to package your project's assets as individual files or a single package. If enabled, all assets will be put into a single .pak file instead of copying out all the individual files. If your project has a lot of asset files, using a Pak may make it easier to distribute it, because you do not have to transfer so many files. This option is disabled by default.

Generate Chunks

Whether to generate .pak file chunks that can be used for streaming installs.

Build Http Chunk Install Data

Whether to generate data for HTTP chunk installer. This allows this data to be hosted on a webserver to be installed at runtime.

Http Chunk Install Data Directory

This is the directory where data will be installed once it is built.

Http Chunk Install Data Version

This is the version name for HTTP chunk install data.

Include Prerequisites Intaller

This specifies whether to include installers for prerequisites of packaged games, such as redistributable operating system components.

Content Cooking

As a developer, when iterating over new or modified game content, you may not always want to go through the lengthy process of packaging everything into the staging directory and then running it from there. It is therefore possible to only cook the content for a particular target platform without packaging it by clicking File > Cook Content > [PlatformName].

Please note that this feature will update the content in your project's local developer workspace, and it will not copy out any assets to the staging directory. You can run your game directly from your local developer workspace for fast iteration.

Optimizing Load Times

Short loading times are essential for open-world games, but are valuable in every type of game. The Unreal Engine provides several methods to optimize your project's loading time during the packaging process. Here are some recommended practices to descrease the loading time in your games. For information on how to package your project, see the Packaging and Cooking Games section.

Using the Event Driven Loader (EDL) and the Asyncronous Loading Thread (ALT)

  • The Asynchronous Loading Thread (ALT) is turned off by default, but can be turned on in the Project Settings menu under the Engine - Streaming section. For modified engines, some tweaks may be needed, but in general, ALT should double the speed of loading, including games with "up-front" loading times and games that constantly stream data. The ALT works by running serialization and post-loading code concurrently on two separate threads, and as a result, it adds the requirement that UObject class constructors, PostInitProperties functions, and Serialize functions in your game code must be thread-safe. When activated, ALT doubles loading speed. For further information about using asynchronous loading methods (in C++), see the Asynchronous Asset Loading page.

  • The Event-Driven Loader is activated by default, but can be deactivated in the Project Settings menu under the Engine - Streaming section. For most projects, the EDL will cut load times in half. The EDL is stable and can be back-ported to older versions of the Unreal Engine, or can be tweaked for modified or customized engine versions.

EngineStreamingSettings.png

Compressing your .pak file

  • To use .pak file compression in your project, open Project Settings and find the Packaging section. In that section, open the advanced part of the Packaging heading and check the box labeled "Create compressed cooked packages" that appears.

  • Most platforms don't provide automatic compression, and compressing your .pak files will generally decrease loading times, but there are a few special cases to consider:

Platform

Recommendation

Sony PlayStation 4

Compressing the .pak file will be redundant with the compression automatically applied to every PlayStation 4 title, and will actually result in longer load times without decreased file size. It is therefore not advised to compress .pak files for PlayStation 4 releases.

Nintendo Switch

Compressed .pak files on the Switch will sometimes load more slowly due to the processor time it takes to decompress the data, but will sometimes load faster from compressed files. The recommendation for Switch titles is to test out the load times with each individual title and make a case-by-case decision.

Microsoft XBoxOne

Compression is critical to achieving the fastest possible load times on the XBoxOne platform.

Steam

Steam compresses files while they are being downloaded by users, so initial download times will not be affected by your game's .pak file being compressed. However, Steam's differential patch system will generally work better with uncompressed files. Compressed .pak files save space on the customer's system, but will take longer to download when patching.

Project Settings - Compress Pak option

Check this box to enable compression in your .pak files.

Ordering your .pak file

  • A well-ordered .pak file is critical to reducing load times. To assist with ordering your .pak file optimally, the Unreal Engine provides a set of tools to discover the order in which your data assets are needed, and build faster-loading packages. Conceptually, this process is similar to profile-guided optimization. Follow this method to order our .pak file:

  1. Build and run the packaged game with the "-fileopenlog" command-line option, which causes the engine to log the order in which it opens files.

  2. Exercise all major areas of the game. Load every level, every playable character, every weapon, every vehicle, and so on. Once everything has been loaded, quit the game.

  3. There will be a file in your deployed game called GameOpenOrder.log that contains the information needed to optimize your .pak file order. For example, on Windows builds, the file will be found in WindowsNoEditor/(YourGame)/Build/WindowsNoEditor/FileOpenOrder/. Copy this file to your development directory under the /Build/WindowsNoEditor/FileOpenOrder/ path.

  4. With the log file in place, rebuild the .pak file. This and all future .pak files produced will use the file order indicated in the log file.

  • In a production environment, the log file should be checked into source control and updated periodically with the results of new "-fileopenlog" runs, including a final run when the game is ready to ship.