Lumberyard
User Guide (Version 1.15)

Building Android Games

This feature is in preview release and is subject to change.

Before you can deploy your game to Android devices, you must ensure the following:

  • The shader compiler (located in the lumberyard_version\dev\Tools\CrySCompileServer\x64\profile\CrySCompileServer.exe directory) is running on your PC. For information, see Building Shaders for Android Games.

  • You are using Android NDK r11 or above. For information, see Android Support.

Building Android Games Using the Lumberyard Editor Deployment Tool Plugin

Lumberyard Editor includes a plugin that allows you to build and deploy Android applications. You can access the plugin by clicking Tools, Other, Deployment Tool.

Note

If you change your default project, you must ensure the new default project is set for enabled_game_options in the user_settings.options file (located in the \_WAF_ directory at the root of your Lumberyard installation). Then you can run the lmbr_waf.bat configure command in a command line window prior to starting Lumberyard Editor and using the Deployment Tool. This allows the appropriate files to be processed and created for your project.

To build and deploy your game for Android using the Deployment Tool

  1. In Lumberyard Editor, click File, Project Settings, Deployment Tool.

  2. If this is your first time building and deploying to an Android device, do the following to ensure that the Deployment Tool will build the game before deployment and will install the game and APK to the Android device before attempting to launch it:

    1. For Deploy Options, select the Build Game check box.

    2. Click Advanced Options and select the Install the Executable check box.

  3. (Optional) Use the File Transfer Option drop-down list to specify how the Deployment Tool should deploy the assets for the game:

    • Push Files – Assets are copied and pushed to the Android device before the game runs. The game will read all assets from the Android device, allowing the game to run faster. This option disables the ability to hot reload assets.

    • Use Virtual File System – Assets remain on the PC and the game retrieves the assets at runtime as needed. This option allows assets that support hot reloading to automatically update in-game if changes are detected on the PC.

  4. Click Deploy to build and deploy the game to the Android device, start the remote shader compiler, and launch the game on the Android device. You will see the process output in the Deployment Console.

  5. (Optional) After your initial deployment, if you plan to change only art and level assets, do the following to decrease the deployment time:

    1. For Deploy Options, clear the Build Game check box.

    2. Click Advanced Options and clear the Install the Executable check box.

    Clearing these options will prevent the Deployment Tool from building and installing the executable, which is only necessary if you change code.

    Note

    If you add new gems to your game project, you must select the Build Game and Install the Executable check boxes in order to include the functionality of those gems.

Setting Deployment Tool Options

The Deployment Tool provides the following basic options that you can set to build and deploy your game:

  • Hardware Platform – Android is the only device supported.

  • Select Build Configuration – Choose Debug, Profile, or Release. In most cases Profile is the best option to use for performance and ease-of-use. To use Release, you must have already built the .pak files for a release build.

  • Select Compiler – Choose Clang.

  • File Transfer Option – Choose how the Deployment Tool handles game assets:

    • Push Files – Assets are copied and pushed to the Android device before the game runs. The game will read all assets from the Android device, allowing the game to run faster. This option disables the ability to hot reload assets.

    • Use Virtual File System – Assets remain on the PC and the game retrieves the assets at runtime as needed. This option allows assets that support hot reloading to automatically update in-game if changes are detected on the PC.

  • Build Game – Select to build the game before deployment and launch.

The Deployment Tool provides the following advanced options that you can set for finer control:

  • Clear Device Before Deploying – Select to uninstall the previous version of the game and delete any assets that were copied to the device prior to deployment.

  • Install the Executable – Select to install the game on the Android device. If cleared, the Deployment Tool will only process the assets.

  • VFS Remote IP and Port – Configure the IP address and port for the virtual file system (VFS) to use when communicating with the Android device. We recommend using the default values.

    Note

    If you change the port number in the Deployment Tool and then click Deploy, the tool will update the bootstrap.cfg file (located in the \dev directory at the root of your Lumberyard installation) with the new port value. To ensure that VFS works properly and the asset processor can listen to the new port, you must restart the asset processor after changing the port number. Alternatively, you can change the port number in the bootstrap.cfg file before restarting the asset processor, and then open the Deployment Tool.

  • Shader Compiler Settings:

    • Connect through Asset Processor – Select to enable the asset processor to process shader compiler requests. The game will not connect directly to the remote shader compiler.

    • Shader Compiler IP and Port – Provide the IP address of the remote shader compiler to which the game should connect. The game will not use the asset processor to process shader compiler requests.

Building Android Games Using Clang

You can build your game for Android using Clang. Building for Android (ARM) in Visual Studio will build using Clang.

To build your game for Android using Clang (recommended)

  1. Ensure you are using Android SDK 21 or later and Android NDK r11 or later. For information, see Android Support.

  2. In a command line window, navigate to \dev in the directory where you installed Lumberyard.

  3. Build various targets of your game:

    • To build debug

      • On a PC, run the following command: lmbr_waf.bat build_android_armv7_clang_debug -p all

      • On a Mac, run the following command: sh lmbr_waf.sh build_android_armv7_clang_debug -p all

    • To build profile

      • On a PC, run the following command: lmbr_waf.bat build_android_armv7_clang_profile -p all

      • On a Mac, run the following command: sh lmbr_waf.sh build_android_armv7_clang_profile -p all

    • To build release

      • On a PC, run the following command: lmbr_waf.bat build_android_armv7_clang_release -p all

      • On a Mac, run the following command: sh lmbr_waf.sh build_android_armv7_clang_release -p all

  4. Debug your application. For information, see Android Debugging.