User Guide (Version 1.16)

Creating iOS Release Builds for Distribution

This feature is in preview release and is subject to change.

Once you have finished your Lumberyard iOS game, you can prepare it for store deployment by including the packed assets and cached binary shaders (for information, see Running the Remote Shader Compiler), and editing the Info.plist file (located in the lumberyard_version\dev\Code\project_name\Resources\IOSLauncher directory) to use your project's settings:

  • Display name

  • App icon

  • Splash screen

  • Screen orientation

  • Other related settings


Ensure the Info.plist file is writeable before you make changes to your project settings.

Lumberyard provides default values in the Info.plist file as well as default app icons and splash screens in the Images.xcassets folder. For more information, see the Lumberyard Logos and Branding Guidelines.

For information about setting these values in the Xcode solution, see Configuring Your Xcode Project for Distribution.

Building Asset .Pak Files

Use a command line prompt and batch file to build a .pak file that includes your assets.

To create required assets to run a release build for iOS

  1. On your PC, in a command line window, navigate to the dev directory of your Lumberyard installation.

  2. Run the BuildSamplesProject_Paks_iOS.bat file. The .bat file generates a \Cache\game_project_name\ios_paks directory that includes the files required to run your game, excluding shaders and executables.


    The BuildSamplesProject_Paks_iOS.bat file will only work with the levels in the SamplesProject directory. If you are building a different project, you can copy the .bat file and modify it to reference your project. Each project needs its own .bat file.

Building Shader .Pak Files

Explore every area in your game level to capture all shader permutations, and then use a command line prompt and batch file to build a .pak file that includes your shaders.

To generate and retrieve shaders for your iOS game

  1. Build, deploy, and run your game on an iOS device. For information, see Configuring and Building iOS Games and Deploying iOS Games.

  2. In your game, explore every area in every level to ensure that all shader permutations required for the game are generated. Exit the game when you are finished.

  3. In Xcode, click Window, Devices.

  4. In the Devices window, click the settings wheel and select Download Container.

  5. In the Finder, locate and right-click the container package for your project (.xcappdata file). Select Show Package Contents.

  6. Copy the shaders folder from the /AppData/Library/Application Support/cache directory on your Mac to the Cache\game_project_name\ios\user directory at the root of your Lumberyard installation (lumberyard_version\dev) on your PC.

To build a shader .pak file

  1. In a command line window, navigate to the dev directory of your build and locate the file.

  2. To use the file, enter a command that provides the name of the game project for which to build the shaders as an argument: <Game_Project_Name>

    For example, to build the shaders for the Samples Project, enter the following command in a command line window SamplesProject

Deploying Shader .Pak Files

When the batch file finishes building the shader .pak file for your game project, you will find the following in the \Build\ios\game project name\ directory at the root of your Lumberyard installation (lumberyard_version\dev):

  • ShaderCache.pak – Contains all compiled shaders that are used only when the shader cannot be found in the current level's shader cache.

  • ShaderCacheStartup.pak – Contains a subset of compiled shaders that are required for accelerating the startup time of the engine.

To enable your release game to run the shaders from the .pak files

  1. Copy the shaders*.pak files to the Cache\game_project_name\ios_paks\game_project_name directory at the root of your Lumberyard installation (lumberyard_version\dev).

  2. When the shader .pak files are in the correct cache location, edit the scheme in XCode to use release as the build configuration.

  3. Run the build process.

Deploying and Archiving Release Builds from XCode

After generating all required asset and shader .pak files, you can use Xcode to build, deploy, run, and archive the release version of your iOS game. Use the same method that you would use for any Xcode project. For more information, see Prepare for app distribution in the XCode Help.