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, Java to compile and build the Android application, and will construct and package the final APK and project assets.

Prerequisite software and packages

Android SDK

The Android SDK contains Android libraries, packages, NDKs, and other tools needed to build the Android application 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 additional SDKs from within Android Studio. Once Android Studio is set up, you can locate the Android SDK Home by selecting Tools > SDK Manager or selecting the SDK Manager icon in the toolbar. You will find the location under Android SDK Location.

Alternatively, you can download the Android SDK command line tools only package without the need to install Android Studio. The location where the command line tools package is installed to will determine the location of the Android SDK Home. Refer to the SDK Manager instructions for details on where to install the package.

Once the Android SDK location is determined, it needs to be set in the Android configuration setting ‘sdk.root’

Note:

In order for the generation script to automatically download the required packages, you must accept the license agreements that represent those packages. This can be done either through Android Studio, or through the sdkmanager command line tool with the --licenses argument.

Java Development Kit (JDK)

The Android SDK command line tool needs the Java Development Kit (JDK) to compile the Android Java source for the project and create a Java Key Storage (JKS) files used to sign the APK. The version of the JDK required for Android depends on the requirements for the Android SDK . The location of the JDK installation must be set in the JAVA_HOME environment variable, or the location of the JDK executable must be in the PATH environment.

Note:

The version of the Java Development Kit must be compatible with the SDK Manager . However, if you wish to specify older versions of the Android Gradle Plugin, the version of the JDK that is used to run the Gradle build may be different, and may require setting the JAVA_HOME environment to match an older versions of SDK in order to build the APK successfully.

Gradle and the Android Gradle Plugin

Gradle is the build system designed to build and create Android applications. The Android Gradle Plugin adds features to the Gradle build system to support Android builds. The current Android Project Generation script supports version 8.1 or newer of the Android Gradle Plugin, which in turn requires Gradle version 8.1 or newer. The location of the Gradle installation must be set in at least one of the three ways in order for it to be discoverable:

Note:

Older versions (4.2.0 or newer) of the Android Gradle Plugin are support, but not recommended.

1. Android configuration setting gradle.home
2. Set in the GRADLE_HOME environment variable.
3. The location of the gradle executable script is in the PATH environment.

CMake

CMake (version 3.22.0 or newer) is a project generator that O3DE uses for all native C++ builds, regardless of the platform. As with the discoverability requirements for Gradle, the location of the CMake installation must be set in at least one of the three ways:

1. Android configuration setting cmake.home
2. Set in the CMAKE_HOME environment variable.
3. The location of the cmake executable script is in the PATH environment.

Ninja Build System

CMake uses the Ninja build system to build the underlying native C++ code for an O3DE project. Ninja must be set in the PATH environment.

Configuring the environment

The Android Project Generation script needs to be configured with the user specified settings and the locations of the prerequisite software in order for it to generate O3DE Android Gradle scripts. The android settings are managed with the android-configure command from the O3DE Command Line.

Below is the list of configurable android settings.

APK Signing

All APKs must be digitally signed before they can be installed onto an Android device. This is done by providing a signing configuration in the Android Project Gradle script. This signing configuration is meant for a debug development environment and is insecure by design. You can generate the signing configuration key store, signing key, and certificate through Android Studio . You can also create a key store from the command line using the JDK keytool command.

(More details of APK signing and how to create the keystore, keys, and certificates can be found here . )

During the creation of the Android Project Gradle script, if any of the signconfig.* values are set, the generation process will attempt to embed the signing configuration information with the following values:

• Key Store File

  The key store file that contains the signing key and certificate. ( --signconfig-store-file/signconfig.store.file)

• Signing Key Alias

  The alias of the signing key inside the key store file.( --signconfig-key-alias/signconfig.key.alias)

• Key Store Password

  The password for the key store file.(signconfig.store.password)

• Signing Key Password

  The password for the signing key needed to perform the signing operation.(signconfig.key.password)

Note:

You cannot pass in any of the two passwords through the android-configure or android-generate commands. When you run android-generate but are missing any of the signing passwords, the command will present a standard password set and confirm prompt to enter to embed in the generated project. If you want to set the passwords that will be used for the signing configs without prompting for them, you will need to call android-configure with the argument --set-password SETTING where SETTING is either signconfig.store.password or signconfig.key.password. This will present the same standard password set and confirm prompt, but will store it in the android settings for future calls to android-generate.

Android assets

Before you can generate an O3DE Android project, you must process 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 <engine-root>\Registry\AssetProcessorPlatformConfig.setreg file.

In the Amazon/AssetProcessor/Platforms section of the file, set the "android" flag to "enabled". For example:

"Amazon": {
    "AssetProcessor": {
        ...
        "Platforms": {
            //"pc": "enabled",
            "android": "enabled"
            //"ios": "enabled",
            //"mac": "enabled",
            //"server": "enabled"
         }
    ...
}

You must pass in the --platforms=android argument 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.

Legacy Android Project Generation Script

The original android generation script can still be found at <engine-root>/cmake/Tools/Platform/Android/generate_android_project.py, but only supports the Android Gradle Plugn version 4.x.

The generate_android_project.py script contains the following arguments:

Android Deployment Script

Find the script to deploy the Android project at <engine-root>/cmake/Tools/Platform/Android/deploy_android.py.

The deploy_android.py script contains the following arguments:

Additional Topics

• Generating Android Projects on Windows