Creating a Release App
Once you have finished your Lumberyard iOS game, you can prepare it for the App Store
by creating a release app and including the assets and shaders in .pak
files. You must do the following:
Preparing Your Code
Modify the code in the IConsole.h
file to enable the creation of mobile release builds.
To modify the IConsole.h file
-
On your macOS computer, navigate to the
directory.lumberyard_version
\dev\Code\CryEngine\CryCommon\ -
Use your preferred text editor to open the
IConsole.h
file. -
Modify line 41 as follows:
//Enable modification of CVARS for mobile release builds #if defined(AZ_PLATFORM_APPLE_IOS) #define ALLOW_CONST_CVAR_MODIFICATIONS 1 #else #define ALLOW_CONST_CVAR_MODIFICATIONS 0 #endif
-
Save the file.
Modifying Your Settings
Modify the settings in your system configuration file to disable communication between the iOS device and the remote shader compiler. For release builds, Lumberyard packages the shaders directly to the iOS device instead of compiling shaders on demand.
To modify the system configuration file
-
On your macOS computer, navigate to the
directory.lumberyard_version
\dev\ -
Use your preferred text editor to open the
system_ios_ios.cfg
file. -
Set the following console variables to
0
.-
r_AssetProcessorShaderCompiler
-
r_ShadersRemoteCompiler
-
r_ShadersAllowCompilation
-
-
Save the file.
Creating .Pak Files
Lumberyard apps use .pak
files to include assets and shaders for your app build. The .pak
files are required for release apps and must be created manually.
Building Shader .Pak Files
Use the Remote Shader Compiler to generate the shaders that are packed into your app build. You must run your app in profile or debug and view every surface in your game level to capture all shader permutations. Lumberyard supports both GMEM 128 and GMEM 256 and generates shaders on the highest version that a device supports. As a result, you must run your game on two devices, one that supports GMEM 128 and one that supports GMEM 256.
To generate shaders for your iOS app
-
Build, deploy, and run your game in profile or debug mode. For information, see Building Your iOS App.
-
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.
To build a shader .pak file
-
Run the Remote Shader Compiler. For more information, see Running the Remote Shader Compiler.
-
In a command line window, navigate to the
directory and locate thelumberyard_version
\dev\lmbr_pak_shaders.sh
file. -
To use the
lmbr_pak_shaders.sh
file, enter a command that provides the name of the game project and the platform.lmbr_pak_shaders.sh
game_project_name
METAL iosExample
To build the shaders for the Samples Project, enter the following command:
lmbr_pak_shaders.sh SamplesProject METAL ios
Deploying Shader .Pak Files
When the batch file finishes building the shader .pak
file for your game project, verify that the following files exist in the
directory:
lumberyard_version
\dev\Build\ios\game_project_name
\
-
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 used to accelerate the startup time of the engine.
To pack assets for your app
-
Navigate to the
directory.lumberyard_version
\dev\ -
Copy the
Build
file and rename it to<game_project_name>
_Paks_PC.batBuild
.<game_project_name>
_Paks_iOS.bat -
Use your preferred text editor to open the
Build
file.<game_project_name>
_Paks_iOS.bat -
Edit the file as follows:
-
Line 20:
.\%BINFOLDER%\AssetProcessorBatch.exe /gamefolder=
game_project_name
/platforms=ios -
Line 25:
.\%BINFOLDER%\rc\rc.exe /job=%BINFOLDER%\rc\RCJob_Generic_MakePaks.xml /p=ios /game=
game_project_name
-
-
Save the file.
-
Run the
Build<game_project_name>_Paks_iOS.bat
file and wait for the.pak
files to finish building.
Using Shader .Pak Files
Add the shader .pak files to your Xcode project.
To use shader .pak files
-
Navigate to the
directory. The generated .pak files are saved here.lumberyard_version
\dev\Cache\game_project_name\ios_paks\ -
Do one of the following to add the .pak files to your Xcode project:
-
If you're sharing the
Cache
directory between your Windows and macOS computers, reopen your Xcode project. This will add the files to yourResources
directory. -
Copy the
ios_paks
directory and save it in the
directory on your macOS computer. Then reopen your Xcode project.lumberyard_version
\dev\Cache\game_project_name
\
-
Configuring the App Store Settings
Every Lumberyard project includes an Info.plist
file that contains the default values for the following settings:
-
Display name
-
App icon
-
Splash screen
-
Screen orientation
-
Other related settings
You can access the Info.plist
file in the
directory. The default app icons and splash screens are in the lumberyard_version
\dev\Code\game_project_name
\Resources\IOSLauncher\Images.xcassets
directory. For information about using the default app icons and splash screens,
see the Lumberyard Logos and Branding Guidelines
Verify the Info.plist
file is writeable and then use Xcode to modify the values for these settings. For
information about modifying these settings in Xcode, see Configuring Your Xcode Project for Distribution
Generating a Build
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 app. Use the same method that you would use for any Xcode project. For more
information, see Prepare for app distribution
To generate a build
-
On your macOS computer, open Xcode.
-
In Xcode, navigate to your project and then choose Edit Scheme.
-
On the project page, for Build Configuration, select release.
-
Build your project as you would any Xcode project.
-
In the menu, choose Product, Archive.
-
In the dialog box, on the Archives page, click Export.
-
Generate your iOS app.