IN THIS ARTICLE
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.
- Make sure that the Project Export CLI Tool page prerequisites are satisfied.
- Git clone O3DE Atom Sample Viewer project onto your machine.
- 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
- 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 .
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:
$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_PATHvariable is set to the absolute path to the location of the O3DE source and
$PROJECT_PATHis 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
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:
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.
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:
|Display the help information specifically for the export script.
|Specifies whether to build O3DE toolchain executables. This will build AssetBundlerBatch and AssetProcessorBatch. If asset tools have not been built, then assets cannot be processed.
|Designates where the build files for the O3DE toolchain are generated. If not specified, default is
|Designates where the Xcode project file for the project is generated. If not specified, default is
|For iOS building and deployment, the export script assumes that assets should be processed and built. If this behavior is not desired, use this flag to disable it.
|Suppresses logging information unless an error occurs.
Here is an example usage of this script:
# On Mac
$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
IOS_OUTPUT_PATH are environment variables. The
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.