IN THIS ARTICLE
Android Support for Open 3D Engine (O3DE)
Open 3D Engine (O3DE) projects for Android rely on the Gradle build system to build the final APK that launches and runs O3DE projects. O3DE provides the Android Project Generation script, which generates the Gradle build scripts that you need to build your O3DE projects for Android. The Gradle build scripts use CMake to compile the native C++ code, compile and build the Android application (Java), and construct and package the final APK and project assets.
The latest version of the Java Development Kit is needed to both compile the android java source for the project as well as to create a Java Key Storage (JKS) files used by the Android SDK to sign the APK.
Gradle (version 6.7.1 or newer) is the build system designed to build and create Android applications.
The Android SDK contains Android libraries, packages, NDK, and other tools that are needed to build the Android application for an O3DE project. Download the latest version of Android SDK through the Android Studio or the command line tools.
CMake (version 3.22.0 or newer) is a project generator that O3DE uses for all native C++ builds, regardless of the platform.
The Ninja build system is used by CMake to build the underlying native C++ code for an O3DE project.
You can set up and configure the Android SDK by using Android Studio, an IDE commonly used with Gradle to develop and build Android applications. When you launch Android Studio for the first time, follow the steps to download and install at least one SDK platform. You can also set up and configure SDKs from within Android Studio, if it’s already set up.
Keep track of the location where you installed the Android SDK, as you will need it later to generate an Android project for O3DE.
In order to simplify project generation steps, add the other prerequisites (Java, Gradle, CMake, and Ninja) to your PATH environment variable. Otherwise, you must configure the paths to each respective package by using the command line arguments for the Android Project Generation script.
The Android build process creates APKs that you must sign before you can deploy them. You can configure a signed APK for your generated project after creating the project through Android Studio, or you can sign the APK during the project generation step. Android uses the JKS format so you can use the
keytool Java command to sign your APK.
|Distinguished Name ( DN )
|Descriptive name of an entity to identify the owner of the key.
|The identifier for the key and certificate in the KeyStore file. A KeyStore file may contain multiple keys and certificates.
|The password to protect the individual signing key.
|The password to protect the entire KeyStore file.
|The length of time in days that the certificate is valid for, starting from the day the KeyStore was created.
Before you can generate an O3DE Android project, you must process and prepare the assets for Android. You can do this by using the O3DE Editor and the Asset Processor (or Asset Processor Batch) on your project.
Specifically for Android, you must configure the registry settings value so that the Asset Processor can process Android platform assets. To do this, update the
Amazon/AssetProcessor/Platforms section of the file, set the
"android" flag to
"enabled". For example:
Alternatively, you can use
--platforms=android when launching the Asset Processor Batch. Refer to step 3 in
Generating Android Projects on Windows.
After you’ve processed the assets for Android, you can proceed to generate the Android project.
Find the script to generate an Android project at
generate_android_project.py script contains the following arguments:
|The path to the root of the engine folder.
|The path to create the project’s
build folder at.
|This path can be relative to the engine root or absolute.
|The path to O3DE’s designated third party folder.
|This correlates to O3DE’s
LY_3RDPARTY_PATH CMake variable.
|The path to the Android SDK folder.
|This path is normally set when you configure Android Studio.
|The path to the O3DE project to generate an Android project for.
|The Android API level to base the build on.
|The latest installed API level in the
|The API level needs to match the version of the target Android device. (For a description of API levels, refer to
Currently, the minimum API level that’s supported is 28.
|Override the Android build tools version.
|The latest Android build tools installed in the
|The version of the Android Gradle plugin to specify for the build.
|The minimum supported version is
4.2.0 (default). For details, refer to
4.2.0 is supported. This script can be updated to support future versions.
|The specific NDK value to base the build on
|The values are based on the NDK’s full revision number:
You can also use the
* wildcard to select the most recent version. For example,
21.* selects the most recent version of NDK21.
|The API level that the NDK supports, for native CMake Android support.
|The API Level set by the
|- The minimum API Level for the NDK is
|(Optional) Compiles source code with unity build.
|Unity build disabled.
|(Optional) Includes the game assets in the APK.
|Assets not included in the APK.
|Configures how to include assets in the APK. Asset Mode values can be
LOOSE (default): Unpacks and stores assets as individual files that are contained within the asset cache.
PAK: Packs the assets into PAK files.
VFS: References assets remotely from the target device through the Virtual File System.
|The type of assets to include in the APK
|In the future, this argument will be deprecated and will only support
android type assets.
|If the Gradle command is not in the PATH environment, or if you want to specify an alternate Gradle folder, this argument allows you to override the installed version of Gradle to use for the project generation.
|The path to Gradle that’s installed in the PATH environment.
|- The minimum version of Gradle is
6.7.1, which is compatible with the minimum version of the Android Gradle plugin,
- If you don’t specify this argument and Gradle is not installed in the PATH environment, an error will occur.
|If the CMake command is not in the PATH environment, or you want to specify an alternate CMake installation, this argument allows you to override the installed version of CMake to use for the project generation.
|The CMake installation that’s part of the PATH environment.
|- The minimum version of CMake is
3.21, which supports Android Gradle plugin version
- If you don’t specify this argument and CMake is not installed in the PATH environment, an error will occur.
|If the Ninja command is not in the PATH environment, or you want to specify an alternate Ninja installation, this argument allows you to override the installed version of Ninja to use for the project generation.
|The Ninja build tool installation that’s part of the PATH environment.
|- If you don’t specify this argument and Ninja is not installed in the PATH environment, an error will occur.
|(Optional) An Android JKS KeyStore that is used for APK signing when the project needs to be built and deployed to an Android device. If this option is omitted, then it must be set up later in Android Studio in order to deploy to Android. Otherwise, the project can only generate unsigned APKs. (Refer to the Android Key Store section for more information.)
|- If not specified, the generated Android project will not include any signing information. You can still build the Android project, but you cannot deploy to any device.
- You can add the signing key information after project generation through Android Studio.
|A required password for the Android JKS KeyStore file, if specified by
|- Required if you specify a JKS using
|A required alias of the signing key in an Android JKS KeyStore file, if specified by
|- Required if you specify a JKS using
|A required password to use the signing key in an Android JKS KeyStore file, if specified by
|- Required if you specify a JKS using
|(Optional) Overwrites existing scripts in the target build folder if they already exist.
|Does not overwrite.
Find the script to deploy the Android project at
deploy_android.py script contains the following arguments:
|Shows the help message and exits.
|The build directory of the project to deploy from.
|The build configuration of the built binaries to deploy from.
|A comma separated list of connected Android device IDs to filter the deployment to.
|All connected Android devices.
|Only used when multiple devices are connected and you want to filter which devices will be the target for the deployment.
|The type (
BOTH) to deploy:
Deploys only the APK without any external assets (refer to the
--include-apk-assets option in
generate_android_project.py). Any assets that’re already included in the APK will be deployed as well.
Deploys only the assets for the APK. This option is only valid if you didn’t set
--include-apk-assets during the project generation.
Deploys both the APK and assets, regardless of the
|Deploying the APK and assets separately can optimize different workflows. For example, developers who update only the code should use
APK to make their deployments more efficient (provided that the assets are deployed at least initially). In another example, technical artists who only update the assets should use
ASSETS (provided that
--include-apk-assets was not set during project generation).
|Cleans the target Android device by uninstalling any pre-existing projects before deploying.
|Uninstalling the project also deletes all the assets deployed as well.
|Option to kill adb server at the end of deployment.
|Option to enable debug messages.