Packaging Projects

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 needs to be converted into a format that can be used by the target platform (so called content cooking). After that, compiled code and cooked content will be bundled up 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/distribution.

For 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.

Once you select the platform, the editor will compile your game if it contains code, cook all of your game data, and then package the content. This can end up being a slow process if you included the Starter Content in your project, or if you have made a lot of test/temporary content and maps.

Setting A Game Default Map

Before you package your game you will first need to set a Game Default Map to 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

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 neither of these windows are visible, they can be accessed by the Window > Developer Tools > Output Log / Message Log options.

Running Packaged Games

When you packaged, you selected a directory for the output. If packaging completes successfully, your packaged game will be in a platform-specific subdirectory. For instance, if you selected TappyChicken/Final, then the iOS build would be in TappyChicken/Final/IOS and an Android build would be in TappyChicken/Final/Android. When you go to that subdirectory, you will see the packaged game, in a format appropriate for the platform. For Android, you will see .apk, .obb, and .bat files (run the .bat to install the game on your device). For IOS, you will see an .ipa file. This can be installed via iTunes or Xcode. The number and type of files created will vary depending on the target platform. The following image shows example output for a Windows project:

results.png

To run your packaged game:

  1. Find the executable for your packaged game using the table below:

    Configuration EXE Name EXE Location
    Development [ProjectName].exe [PackageDirectory]\WindowsNoEditor
    Shipping [ProjectName]-Win32-Shipping.exe [PackageDirectory]\WindowsNoEditor
  2. Double-click the executable to run the game.

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 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 Distro_MyProject.mobileprovision and MyProject.mobileprovision).

On Android, you will need to create a key to sign the .apk, 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 (no Java directory), 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 select Debug, for most other development with minimal debugging support, but better performance select Development, and for the final shipping build 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 enabled 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 built to.
Http Chunk Install Data Version This is the version name for HTTP chunk install data.
Include Prerequisites This specifies whether to include 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.