IN THIS ARTICLE

Project Export for iOS

This guide covers how to use project export tooling to build and deploy games on iOS. We will use the iOS export script to generate an Xcode project and prepare assets and then build the project. The end result of export should be an IPA file that can be installed on your iOS device.

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

Make sure that the Project Export CLI Tool page prerequisites are satisfied.
Make sure you have your project created and registered with your engine.
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.
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 .
Make sure the o3de engine bootstrap registry is enabled for ios. To do so, go to your O3DE engine installation and edit the file at $O3DE_ENGINE_PATH/Registry/bootstrap.setreg so that the assets field uses ios. Like so:

"assets": "ios",

Edit the $O3DE_ENGINE_PATH/Registry/AssetProcessorPlatformConfig.setreg file at line 67 by uncommenting the line:

//"ios": "enabled", -> "ios": "enabled",

This will tell the asset processor to make sure ios assets are cached when building the project. 7. Make sure you have a proper provisioning profile setup for Xcode to use when code signing your app. Alternatively, use automatic signing to let Xcode handle it for you. You can learn more about how set it up here. .

Quickstart

Running the Export Script

For building in release mode with bundled PAK files for your IPA, you can use the following export command:

export O3DE_ENGINE_PATH=/path/to/o3de
export PROJECT_PATH=/path/to/project
cd $PROJECT_PATH
$O3DE_ENGINE_PATH/scripts/o3de.sh export-project -es export_source_ios_xcode.py -pp . -ibp build/game-ios -ll INFO --config release

To use profile mode instead, change the --config parameter in the above snippet to use profile instead. Please note though that this will automatically set assets to LOOSE mode, and will not use PAK files for your final IPA.

That invocation should be all that is needed to create an IPA file for your project. To install the IPA on your phone for testing, you can do so manually via Xcode. Please check this page for more details.

As a result of the export process, the resulting Xcode project file was also generated. You can find it in $PROJECT_PATH/build/game-ios. For regular iterative development with frequent deployments to the iOS device, it is recommended you work with Xcode directly using this project file. See the manual export page for more details.

iOS Export Script

O3DE ships with an 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:

Argument Name	Description	Required?
`--script-help`	Display the help information specifically for the export script.	no
`--config`	Defines the CMake build configuration when building the project’s binaries, such as GameLauncher. Options are either `profile` or `release`.	no
`--tool-config`	The CMake build configuration to use when building tool binaries. Options are either `profile` or `release`.	no
`--build-assets`	Override the default behavior to include processing all assets and run the asset bundler for the project. This option is available when the export-project-configure defaults for `option.build.assets` is `False`.	no
`--skip-build-assets`	Override the default behavior to skip reprocessing and rebundling of all assets for the project. This option is available when the export-project-configure defaults for `option.build.assets` is `True`.	no
`--fail-on-asset-errors`	Override the default behavior to fail the export process on any errors that occur during asset processing. This option is available when the export-project-configure defaults for `option.fail.on.asset.errors` is `False`.	no
`--continue-on-asset-errors`	Override the default behavior to ignore any errors that occur during asset processing and continue with the project export. This option is available when the export-project-configure defaults for `option.fail.on.asset.errors` is `True`.	no
`--seedlist`	Path to a seedlist file for asset bundling. You can specify this multiple times for multiple seed lists. This parameter also allows for wildcard matching for paths.	no
`--seedfile`	Path to a seed file for asset bundling. Example seed files are levels or prefabs. You can specify this multiple times for multiple seed files. This parameter also allows for wildcard matching for paths.	no
`--level-name`	The name of the level you want to export. This will look in `<o3de_project_path>/Cache/levels` to fetch the right level prefab. Specify multiple times for each level in your game. This is not necessary if the level is already defined inside of a seed list.	no
`--build-tools`	Builds the O3DE toolchain executables if the engine is not an SDK. This will build AssetBundlerBatch, AssetProcessorBatch. This option is available when the export-project-configure defaults for `option.build.tools` is `False`.	no
`--skip-build-tools`	Skips building the O3DE toolchain executables if the engine. This may be useful if you already have the tools available. This option is available when the export-project-configure defaults for `option.build.tools` if `True`.	no
`--tools-build-path`	Designates where the build files for the O3DE toolchain are generated. If not specified, default is `<o3de_project_path>/build/tools`.	no
`--max-bundle-size`	Specify the maximum size of a given asset bundle.	no
`--ios-build-path`	Designates where the Xcode project file for the project is generated. If not specified, default is `<o3de_project_path>/build/game_ios`.	no
`--quiet`	Suppresses logging information unless an error occurs.	no

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.