Building Your iOS App
Set up your build environment and build an app that can run on an iOS device.
You must do the following:
Step 1: Configure a Game Project
You have two options for configuring a game project:
-
Use the Samples Project in the
directory as a foundation for your own game project.lumberyard_version
\dev\ -
Create a new game project. For more information, see Creating and Switching Game Projects.
To configure a game project
-
On your Windows computer, navigate to the
directory and open the Project Configurator.lumberyard_version
\dev\Tools\LmbrSetup\Mac\ -
In the Project Configurator, do one of the following:
-
Select SamplesProject and then click Set as default. Follow the instructions for switching game projects.
-
Click Create new. Follow the instructions for creating a game project.
-
-
If you created a new game project, do the following:
-
In the Project Configurator, select your game project name and then click Set as default.
-
In Lumberyard Editor, open your level and then press Ctrl+E. This will export the levels you have created.
-
-
(Optional) Configure system components and memory settings for your game project. For more information, see Configuring Advanced Settings.
Step 2: Prepare Your Assets
You can generate the data for your app on a computer running either Windows or macOS. If you choose to use a Windows computer, you must configure your Windows computer and iOS device to share the same network. For more information, see the Run the Remote Shader Compiler page.
To prepare your assets
-
Do the following to configure Asset Processor for iOS:
-
Navigate to the
directory.lumberyard_version
\dev\ -
Use your preferred text editor to open the
AssetProcessorPlatformConfig.ini
file. -
Remove the preceding semicolon to uncomment
ios=enabled
.[[Platforms] ;pc=enabled ;es3=enabled ios=enabled ;osx_gl=enabled
-
Save the file.
-
-
Do the following to launch Asset Processor:
-
Navigate to the following directory:
-
On a Windows computer:
lumberyard_version
\dev\Bin64vc141
-
On a macOS computer:
lumberyard_version
/dev/Bin64Mac/
-
-
Double-click
AssetProcessor.exe
. -
In Asset Processor, verify that the Status is Idle.
-
Step 3: Configure the Build System
When you build the engine and tools code for macOS or Windows, you initialize the build system and generate project files for Xcode.
To configure the build system
-
In a command line window, type
sh lmbr_waf.sh configure
-
Verify that you see the following in the comments from the build system:
mac config [WAF] 'xcode_ios' finished successfully (3.610s) [WAF] 'xcode_mac' finished successfully (3.507s)
Step 4: Modify Your User Settings
Update your configuration file to help increase the compilation speed and deployment when you build your game project.
To modify your user settings
-
Use your preferred text editor to open the
user_settings.options
file. You can find this file in the
directory.lumberyard_version
\dev\_WAF_\ -
Under
[Build Options]
, setuse_uber_files
toTrue
. -
Save the file.
Step 5: Run the Remote Shader Compiler
Lumberyard uses a versatile shader system to achieve high quality, realistic graphics. When you run a game on an iOS device during development, you must connect to a remote shader compiler on your Windows or macOS computer. This compiles the subset of shaders required by your game, on demand.
When a new shader is compiled, the game waits for the remote shader compiler to compile the binary shader permutation and then send it back to your device. Once this occurs, the shader is cached on your device until you delete the app. When you are ready to release your game, you must pack up and include all cached binary shaders.
You can also run the remote shader compiler on an Amazon EC2 instance. For information, see Running the Shader Compiler on Amazon EC2.
Prerequisites
To use the remote shader compiler, you must do the following:
-
(First time only) Create a
config.ini
file that tells the remote shader compiler the addresses from which to accept connections. For instructions, see the procedure below. -
Connect the remote shader compiler host computer and iOS device to the same network and configure any firewalls to allow traffic through port 61453.
-
Set up the system configuration file (
system_ios_ios.cfg
) for the mobile device to connect to the remote shader compiler on your computer.
You can use an allow list to specify the IP addresses that are allowed to connect to your remote shader compiler. For information, see Creating an allow list for the Remote Shader Compiler.
Enabling a Connection Between the iOS App and the Remote Shader Compiler
You must modify certain configuration files to allow your iOS app to connect to the shader compiler.
To allow your iOS app to connect to the shader compiler
-
Do the following on your macOS computer:
-
Use your preferred text editor to open the
system_ios_ios.cfg
file. You can find this file in the
directory.lumberyard_version
/dev/ -
Set the
r_ShaderCompilerServer
console variable to the IP address of the host computer on which you are running the shader compiler. -
Save the file.
-
-
Do the following on your computer that runs the shader compiler:
-
If one doesn't yet exist, create a
config.ini
file in one of the following directories:-
On Windows:
lumberyard_version
\dev\Tools\CrySCompileServer\x64\profile\ -
On macOS:
lumberyard_version
/dev/Tools/CrySCompileServer/osx/profile/
-
-
Use your preferred text editor to open the
config.ini
file. -
For
whitelist=<device ip address>
, replace<device ip address>
with the IP address, in CIDR format, of your iOS device. -
Save the file.
-
-
On your shader compiler host computer, launch
CrySCompileServer
from one of the following directories:-
On Windows:
lumberyard_version
\dev\Tools\CrySCompileServer\x64\profile\ -
On macOS:
lumberyard_version
/dev/Tools/CrySCompileServer/osx/profile/
-
Step 6: Build Code from a Command Line
Configure and build various targets of your app, depending on your mode of development. You can create a debug, profile, or release build.
-
Debug – Allows you to see your code running under a debugger. This build is slowest to run.
-
Profile – Allows you to debug your code, though some code may be optimized and difficult to trace. This build runs faster on your iOS device.
-
Release – Includes all required asset and shader
.pak
files for a release version of your iOS game. This build runs the fastest; however, special steps are required to generate the build. For more information, see Creating a Release App.
When you build code from a command line, you must take an additional step to run your
app on an iOS device. You use Xcode to open the LumberyardiOSSDK.xcodeproj
project that is generated in the
directory. Then you select your device, follow the standard procedure to build and
run on the device, set breakpoints, and inspect variables.
lumberyard_version
/dev/Solutions/
To build code from a command line
-
On your macOS computer, in a Terminal window, navigate to the
directory.lumberyard_version
/dev/ -
Build various targets of your game:
-
To build debug, type:
sh lmbr_waf.sh build_ios_debug -p all
-
To build profile, type:
sh lmbr_waf.sh build_ios_profile -p all
-
To build release, type:
sh lmbr_waf.sh build_ios_release -p all
-