Build and deploy your project for Android
Once you've set up your
environment and configured your
project, it's time to build your Amazon Lumberyard project for Android and get it
running on a device. In this section, you'll set up an attached device to use the
Shader Compiler, build your
project with lmbr_waf
or Android Studio, and deploy to a device. You'll also
learn how to configure the Lumberyard build system to activate or deactivate automatically
deploying to a device whenever you build.
Topics
Connect to the Shader Compiler
During development, your Lumberyard project connects to the Shader Compiler to generate the shaders for your device. To do this, by set up a reverse proxy between the Android device and the host machine, in order to connect to the Asset Processor. Note that through the VFS you can connect to a remote Asset Processor, which will handle shader compilation. Follow the steps in Serving assets over the Virtual File System (VFS) to configure VFS.
The Shader Compiler only runs on Windows PCs. If you're using another environment to develop your Android game, you'll need access to a server with the Shader Compiler running and accessible through a firewall. One option is to run a Windows GPU-based EC2 instance. For more information on running a dedicated Shader Compiler service, see Remote Shader Compiler.
To connect to the Shader Compiler
-
Open the
file in a text editor.lumberyard_install_dir
\dev\system_android_es3.cfg -
Change the value of
r_AssetProcessorShaderCompiler
to1
.r_AssetProcessorShaderCompiler=1
-
Change the value of
r_ShaderCompilerServer
to the IPv4 address of the machine that's running the Shader Compiler. Unless you're running the Shader Compiler in a dedicated environment, use127.0.0.1
.r_ShaderCompilerServer=
server-ip
Important Make sure that the IPv4 address of the Android device is in the allow list for your Shader Compiler. Connections to the compiler are made from the device, not proxied through the host.
-
Change the value of
r_ShaderCompilerPort
to the port that's used by the Shader Compiler. By default, the port for the Shader Compiler is 61453. To see if you're using another port, examine the Remote Shader Compiler Configuration on the Shader Compiler host.r_ShaderCompilerPort=
shader-port
-
Save the file.
-
If running the Shader Compiler locally: Open a command prompt and use
adb
to redirect traffic at the Shader Compiler port on the device to the Shader Compiler port on your development machine. By default, the port for the Shader Compiler is 61453.adb reverse tcp:
shader-port
tcp:shader-port
Important This step relies on the
adb
command being in thePATH
environment variable. Follow the instructions in Set up your environment to develop for Android with Lumberyard to add Android tools to yourPATH
.
Whether or not you need to manually start the Shader Compiler is dependent upon whether you use the deployment tool. If you're using the Deployment Tool, the Asset Processor automatically starts a Shader Compiler in the background for you. Otherwise, you need to start the Shader Compiler manually for a deployment. See Running the Remote Shader Compiler to learn more.
Build your project
With asset loading and the shader compiler configured, you're ready to build your
Lumberyard project for Android! You can build from the command line,
or load the projects created by lmbr_waf configure
into Android Studio. This section covers how to build
your project from the command line, including information on the available Android
targets and build system configuration options that are
explicitly for use with Android.
If you've enabled Incredibuild, turn the feature off to be able to compile for Android. Lumberyard doesn't take advantage of the Incredibuild hooks for Android.
Build with lmbr_waf
When using lmbr_waf
, Android builds use the
android_armv8_clang
platform. When building for Android, all of the
usual tasks, options, build configurations, and specs are available with
lmbr_waf
. For example, to build the game and engine for Android in
profiling mode, use the command lmbr_waf build_android_armv8_clang_profile -p
game_and_engine
.
For more information about the Lumberyard build system, see Using the Waf Build System. For information on the
Android-specific build settings and lmbr_waf
command-line options, see
the Reference for Android.
Build with Android Studio
The
Gradle
project created by lmbr_waf configure
can be directly imported into
Android Studio without any changes. Follow the instructions from Android Studio - Import Gradle project
. For further
instructions, including how to select targets and configure for debugging, read the
Android Studio
documentationlumberyard_install_dir
\dev\Solutions\LumberyardAndroidSDK
Targets in Android Studio are called Build Variants and are named
. Each build variant produces
the bootstrap executable that loads the assets and code for the named project, and
the Lumberyard engine.
project-name
Launcher
If you're comfortable using the Android build tools from the command line, you can also build any Lumberyard targets using the Android build tools or Gradle. Keep in mind that this only builds your executable and doesn't recompile the assets.
Deployment prerequisites
In order to deploy to an Android device, you need the following:
-
An Android device that meets the minimum requirements for Lumberyard. Lumberyard projects won't deploy to an Android emulator.
-
The device has developer mode and USB debugging enabled. See Configure developer options
in the official Android documentation for instructions on how to enable these features. -
The device is accessible from an Android debug bridge (adb) server on the host running the deployment tools.
Deploy with Lumberyard Editor
The Lumberyard Editor offers a way to deploy to a mobile device: the Lumberyard Deployment Tool. If you're a content creator who rapidly iterates on their work, this is an ideal way to get on-device testing and validation. Using the Deployment Tool requires that you have the Lumberyard Editor and Asset Processor, and an Android device connected to the machine that's running both.
To use the Deployment Tool
-
From the Editor main menu, select File > Project Settings > Deploy to device.
-
In the Deployment Tool UI, select Android ARMv8 for the Target platform value.
-
Select your build configuration, and set the option toggles for Build game and Load current level. It's only necessary to rebuild your game if you're testing updates to the code itself, and not just asset changes.
-
In the Deploy section, select the Local Device tab.
-
Under Deployment Settings, select your target device. Unless you have multiple Android devices connected, there's no need to change this value. Make sure the value for Device IP address is
127.0.0.1
. For Android, the Deployment Tool automatically manages port forwarding and connections through the Android debug bridge. -
Check the Clean device box to remove any files for your project that are copied to the device, including any installed APKs. This is recommended if you're doing a large asset update.
-
Under Asset Options, select your asset mode. Unless you're running the Asset Processor remotely, make sure that the value for Asset Processor IP address is
127.0.0.1 (localhost)
. If you'll be building shaders through the Shader Compiler, uncheck the Use Asset Processor for shaders checkbox. -
Select the Deploy to local device button.
Note If you're using source control for your project, you might see a warning that some files are not writable when you try to deploy the project. Either check these files out in your source control system, or select the Continue button to overwrite them.
Deploy from command line
If you need to deploy less frequently, or can't meet the requirements of the
Deployment Tool, deploy-on-build is another option. Deployments during build can be
performed automatically, or controlled through a command-line option passed to
lmbr_waf
. You can also deploy directly from Android Studio if you're
using it as your build environment. For more information on using Android Studio for
Lumberyard builds, see Build with Android Studio and the Android Studio documentation
As part of using deploy-on-build, you'll want to make sure that your assets are properly updated first. This will always involve running the Asset Processor and the shader compiler before a build.
Automatic deploy during build
At the start of development, and for anyone working on the Lumberyard engine or gems that contain code, deploy to a device every time you rebuild. This keeps the APK on the device up to date and ready to test, at a minimal cost of deployment time to the device. As your project grows in size and assets are added, you might choose to turn this feature off – copying assets to the device is what takes the longest amount of time in a deployment.
To modify the build configuration to automatically deploy
-
Open the
file in a text editor.lumberyard_install_dir
\dev\_WAF_\user_settings.options -
Edit the
[Android Deploy]
section of the file to the following:[Android Deploy] deploy_android = True deploy_android_clean_device = True deploy_android_executable = True deploy_android_replace_apk = True
Command-line options still take precedence over anything in the configuration file. When building for Android and you don't want to deploy, you can add the arguments shown in the next command to keep the current on-device APK installed:
lmbr_waf build_android_armv8_clang_profile -p all ^ --deploy-android-executable=False ^ --deploy-android-clean-device=False ^ --deploy-android-replace-apk=False
Using this feature with the deploy_android_armv8_clang_profile
build
command is useful when you don't want to replace the executable on the device, but
do need to deploy changed assets.
For a full description of all of the available Android deployment options and their effects, see the Reference for Android.
Manual deploy during build
When working from the command line with lmbr_waf
, you can control
deployments by adding arguments. When you're ready to build for deployment, add the
arguments --deploy-android-executable=True --deploy-android-clean-device=True
--deploy-android-replace-apk=True
to your invocation. The following
command is used to deploy during a build:
lmbr_waf build_android_armv8_clang_profile -p game_and_engine ^ --deploy-android-executable=True ^ --deploy-android-clean-device=True ^ --deploy-android-replace-apk=True
During early testing and development, you'll want to always push to a device only when you've confirmed that all of your asset settings, device network configuration, and other build configurations are appropriate for your project. You only need to push new APKs when updating configurations, making code changes, or adding gems.
For a full description of all of the available Android deployment options and their effects, see the Reference for Android.
Deploy with lmbr_waf
If your game and engine are already built and up to date, you can run a deployment without doing a build. By running a deploy-only operation, you can update the assets on a device to test and preview them without the cost of a full rebuild. You can even switch the asset deployment type before doing a manual deployment.
Deployments are performed with the
deploy_android_armv8_clang_profile
command. When you're running
deployments in this way, make sure to use the --deploy-android-*
arguments to specify exactly what should be cleaned and which assets or binaries
will be deployed to the device. In general, when you're only updating assets, make
sure to avoid cleaning assets from the device and don't re-deploy the binaries. The
following command shows how to do an asset-only update:
lmbr_waf deploy_android_armv8_clang_profile -p all ^ --deploy-android-executable=False ^ --deploy-android-clean-device=False ^ --deploy-android-replace-apk=False
For a full description of all of the available Android deployment options and their effects, see the Reference for Android.
Next steps
Now that you have your Lumberyard project building and running on an Android device, learn more about mobile-specific design considerations and releasing to the Google Play Store.