Project Export for iOS

This guide covers how to use project export tooling to build and deploy games on iOS. First, we will use the iOS export script to generate an Xcode project and prepare assets. Afterwards we will walk through how to ensure Xcode is properly setup to build an iOS app.

For this demonstration, we will use the O3DE Atom Sample Viewer project as our reference point for ensuring proper behavior. Results may vary for other projects.

Note:

To learn more about the project export tooling, please consult the page Project Export CLI Tool.

Important:

The iOS export functionality is only available on macOS, which is currently experimental for O3DE.

Prerequisites

1. Make sure that the Project Export CLI Tool page prerequisites are satisfied.
2. Git clone O3DE Atom Sample Viewer project onto your machine.
3. Register O3DE Atom Sample Viewer project with O3DE. You can register the project using:

<O3DE_ENGINE>/scripts/o3de.sh register -pp /path/to/o3de-atom-sampleviewer

4. Have a valid copy of Xcode installed on your machine, and a valid Apple Developer ID associated with that IDE. To set up such an ID, go to developer.apple.com . To use your desired Apple ID, in Xcode go to Xcode -> Settings. In the Settings window, go to the Accounts tab and click the ‘+’ icon at the bottom of the left panel to add your account. Select Apple ID to proceed, and follow on-screen instructions.
5. You will also need to ensure that Xcode has the standard SDKs installed for macOS and iOS, and that your preferred iOS test device is compatible with Xcode. If you are not sure, you can consult this page on installing Simulator Runtimes .

Quickstart

Running the Export Script

Assuming you are just following along using the O3DE Atom Sampleviewer project, this single invocation should be all you need to generate the necessary Xcode project file in the project’s build folder:

export PROJECT_PATH=/path/to/project
$O3DE_ENGINE_PATH/scripts/o3de.sh export-project -es $O3DE_ENGINE_PATH/scripts/o3de/ExportScripts/export_source_ios_xcode.py -pp $PROJECT_PATH

Note:

Make sure the $O3DE_ENGINE_PATH variable is set to the absolute path to the location of the O3DE source and $PROJECT_PATH is set to the absolute path to the location of your project folder.

Assuming the underlying CMake build system finds no issues with your engine or project installation, you should have the corresponding Xcode project file, which will be located at $PROJECT_PATH/build/game_ios. For the Atom SampleViewer, it should be called AtomSampleViewer.xcodeproj.

Using Xcode

Double click the file AtomSampleViewer.xcodeproj to open it in Xcode. This should load everything needed to build the app on an iOS device.

Deploying to an iOS device requires code-signing. Make sure that you have a provisioning profile setup for code-signing.

Next, we’ll open the project configuration details. Click on the AtomSampleViewer project icon in the Explorer tree-view (left hand side of the Xcode IDE). On the left column under “General”, select the build configuration AtomSampleViewer.GameLauncher. The resulting configuration page should look like this:

Go to the “signing and capabilities” tab and setup the provisioning profile to link to your Apple ID. Customize the bundle identifier (add any string you want, for example: append the phrase ’test’). Enable “Automatically manage signing.”

Click on the bar in the region labeled “AtomSampleViewer.GameLauncher” and scroll through the drop down to click “Edit Scheme.”

Set the desired build configuration and set the relevant CLI parameters in the arguments section. An example configuration is shown below:

Note:

For CLI paramter settings that you would like to persist over multiple exports, you can specify the commands to run on launch for a release build via code or by using the autoexec.client.setreg. You can find an example of this in Set the starting level.

Make sure to connect your iOS device to the computer. Xcode should recognize your device, and it should be compatible with the project. If not, follow the Xcode error prompts to trouble shoot the issue and updating may be required. Once this is all correct, press the play button to build and deploy the project.

If the build and deployment successfully completes (assuming you used the sample configuration), you should get the following on your iOS device:

iOS Export Script

O3DE ships with an experimental iOS Export Script , capable of generating an Xcode project file to handle standard use cases of O3DE projects on iOS. This script is only designed to run from an O3DE source installation on a macOS machine.

The export script has two primary sections: the function export_ios_xcode_project and the startup code that only runs if the script is invoked by the CLI . In-depth discussion on these two sections will be made in the Developer Guide in the future.

Usage

To use the export script, you can issue the arguments at the same time that you are running the export-project command. The arguments specific to the script will be deferred until it begins running.

The arguments are as follows:

Here is an example usage of this script:

# On Mac
export IOS_OUTPUT_PATH=/path/to/ios/build/path
$O3DE_ENGINE_PATH/scripts/o3de.sh export-project --export-script $O3DE_ENGINE_PATH/scripts/o3de/ExportScripts/export_source_ios_xcode.py --project-path $PROJECT_PATH --ios-build-path $IOS_OUTPUT_PATH

O3DE_ENGINE_PATH, O3DE_PROJECT_PATH and IOS_OUTPUT_PATH are environment variables. The O3DE_ENGINE_PATH and O3DE_PROJECT_PATH variables point to the path locations for your o3de source engine and o3de project respectively. The IOS_OUTPUT_PATH variable corresponds to the folder path where you would like for the generated Xcode project file to appear.