Tutorial: How to build for Android devices on PC
Tutorial: How to build for Android devices on PC This tutorial will guide you through the process of building Samples Project for your Android device. By the end of this guide you will understand how to:
Build assets for Android Build shaders using the Remote Shader Compiler Build the Lumberyard run-time using the build tools.
Prerequisites It is assumed that you have already set up your device for development, as described here, and that it is connected to your computer. Lumberyard currently supports Android SDK-19 (Kit Kat) through to SDK-23 (Marshmallow) and devices which are capable of running OpenGL ES 3.1.
Step 1: Getting Started 1. Start by running Lumberyard Launcher which is located in Bin64. Under Getting Started, tick the checkbox for “Compile for Android Devices”.
2. If you see a cross mark against the “Required SDK’s” tab, you will need to install some software. Click on the tab and select “Get It” for anything that is not yet installed on your computer.
3. Once Lumberyard Launcher reports that you have all the software you need, you will need to make some modifications to your environment variables. a) Open you control panel and go to System->Advanced Sytems Settings->Environment Variables. b) Scroll down to PATH and add the directory where you installed the Android SDK along with the platform-tools and tools subdirectories, for example c:\Android\android-sdk, c:\Android\androidsdk\platform-tools, c:\Android\android-sdk\tools c) Add the path to the Java SDK and JRE (example could be C:\Program Files\Java\jdk1.7.0_79\bin\ and C:\Program Files\Java\jre7\bin). JDK 7 or later needs to be installed. 4. Go to the directory where you installed the Android SDK and run the SDK Manager. Select the version of the SDK you want to install. Lumberyard currently supports SDK-19 (Android 4.4.2) through SDK-23 (Android 6.0). You will also need to install a version of Build Tools – make a note of the version you have installed as it will be required for the next step. 5. Now we will modify some configuration files in order to tell Lumberyard what version of the SDK to use when building your game. a) Open File Explorer and navigate to your Lumberyard directory. Open the file _WAF_\android\android_settings.json in a text editor. b) Edit the BUILD_TOOLS_VER field with the version of the build tools you installed earlier. c) Edit the SDK_VERSION field with the version of the SDK you want to use. d) Save the file 6. Open a command line prompt and navigate to your Lumberyard dev directory. 7. Type “lmbr_waf.bat configure”. This will initialise Lumberyard so it can build SamplesProject. If there are any errors reported, follow the steps given to fix them and repeat the command until it reports a successful configuration. Note that after you run the configuration command for the first time a file called user_settings.options will be created. Your computer is now ready to build the game. Before we do that, we will build the assets that the game will use as well as build and start the Shader Compiler which is needed at run-time.
Step 2: Building assets for your game The Asset Processor can build assets for your Android game but you must first edit some configuration files. 1. Open bootstrap.cfg in a text editor. Make sure sys_game_folder is set to SamplesProject 2. Open AssetProcessorPlatformConfig.ini in a text editor. Uncomment out the line at the top of the document for es3=enabled and save the file. 3. You can now launch the GUI or batch version of the Asset Processor from the Bin64 directory (called AssetProcessor.exe and AssetProcessorBatch.exe respectively). If the AssetProcessor is already running (not the batch version) it will automatically restart itself and start building assets for Android for the project set in the bootstrap.cfg file. All the processed assets will be stored in the ‘cache’ folder of your Lumberyard dev directory. So if you are building SamplesProject, the assets will be in dev\cache\SamplesProject\es3
Step 3: Using assets in your game There are two ways to use assets in your game. You can either copy them to your device manually or pack them into the APK. The method you use is entirely your choice but if you are iterating on data it may be more convenient to use the manual method as the build times are faster.
Manually copying assets As part of the build process, Lumberyard can automatically copy assets to your device if they have been built by the Asset Processor. You can also manually copy them from the command line using ADB. The game expects assets to be copied to /storage/sdcard0/ Example: adb push cache/SamplesProject/es3 /storage/sdcard0/SamplesProject
If you are using a Samsung device, read the notes at the end of this guide for some extra steps that you will need to follow.
Building assets into the APK You can also build an APK which contains all the assets but do note that your build times will be longer. To do this, go to your project directory and open project.json - In this case the file is at {Lumberyard}/dev/SamplesProject/project.json). Look for the “android_settings” and change “place_assets_in_apk” to 1:
"android_settings": { "package_name" : "com.lumberyard.samples", "version_number": 1, "version_name" : "1.0.0.0", "orientation" : "landscape", "place_assets_in_apk" : 1 }, Now when you generate a build, which is described below, your computer will create an APK which contains the executable and game data. Note that you will still need to run the shader compiler when running your game for the first time.
Step 4: Building and Running the Shader Compiler Lumberyard comes with a versatile, next generation, shader system. When running a game for the first time it is necessary to run the Shader Compiler on a PC which will create the shaders needed for your game. Note that the PC and your Android device must be on the same network. Make sure any firewalls are configured to allow traffic through port 61453.
Building If you have built the PC Editor you will already have the Shader Compiler available. If not, type the following on the command line, in your dev directory, which will invoke the build system to build only the Shader Compiler: lmbr_waf.bat build_win_x64_profile -p pipeline --targets=CrySCompileServer,HLSLcc You will see some output from the build system as the executable is generated.
Running Before you run the Shader Compiler you will need to edit system_android_es3.cfg which is located in your dev directory. Look for this line and replace ‘localhost’ with the IP address of the PC you will be running the compiler on: r_ShaderCompilerServer=localhost This setting will be passed on to the run-time later so it can connect to the compiler. Now run CrySCompileServer.exe on your PC, located in: dev/Tools/CrySCompileServer/x64/profile
Step 5: Building the game You are now ready to build various targets of the game. The commands for each one are: a) Debug: lmbr_waf.bat build_android_armv7_gcc_debug –p all b) Profile: lmbr_waf.bat build_android_armv7_gcc_profile –p all c) Release: lmbr_waf.bat build_android_armv7_gcc_release –p all For now, just build the debug version. Once the build has finished successfully you will have an APK in BinAndroid.Debug.
Step 6: Debugging your game Debugging is currently only supported through Visual Studio 2015 which can be downloaded from Microsoft. During installation, make sure you select “Cross platform tools for C++ development”. Once installed go to Tools->Options, and select Cross Platform->C++->Android on the left hand side. Edit the paths to point at the correct directories on your machine:
Visual Studio 2015 (no updates) 1. After you have built a debug version of an APK, launch Visual Studio and go to File->Open Project/Solution. Navigate to your APK (it should be in BinAndroid.Debug\) and select it. 2. Once the IDE settles down go to the project window, right click on the project and select 'Properties' 3. Edit the 'Launch Activity' field by adding '.CryEngineActivity' (don’t forget the period!) 4. For 'Additional Symbol Search Paths' include the following directories 1) dev/Code 2) dev/BinAndroid.Debug 5. You should end up with something like this:
Visual Studio 2015 with Update 1 or Update 2
1. After you have built a debug version of an APK, launch Visual Studio and go to File->Open Project/Solution. Navigate to your APK (it should be in BinAndroid.Debug\) and select it. 2. Once the IDE settles down go to the project window, right click on the project and select 'Properties' 3. The Launch Activity field should already be set to the correct activity; in this example you should see “LAUNCHER activity (com.lumberyard.samples.SamplesProjectActivity) 4. For 'Additional Symbol Search Paths' include the following directories a. dev/Code b. dev/BinAndroid.Debug You should end up with something like this:
Debugging continued… 1. Open code files through File->Open or Ctrl+O. 2. Set breakpoints if necessary and then hit F5 to run You should now be able to step through code and inspect variables as per normal.
Step 7: Running the game If you’re not launching directly from the Visual Studio debugger, as described above, you can run the game by tapping on the icon from the home screen of your device. You may find it useful to view the logging information by running “adb logcat” from the command line. If there is too much output from that command you can also use –s “LMBR” to filter out the output to be only things that the lumberyard engine is printing out. After deploying to your Android device and running, you should now see something similar to the following:
You can run other levels by modifying SamplesProject/autoexec.cfg and re-deploying/running the game. The ones which are currently supported on Android devices are: -
Animation_Basic_Sample Camera_Sample (the default, shown above)
Controls: You can switch between different cameras by selecting the on-screen buttons in the lower right-hand corner of the screen. In the “Character Controller” views, you can control the robot using the touch screen through some simple virtual thumb-stick controls; move using the left side of the screen, look around using the right side of the screen, and jump by double tapping anywhere on the screen. Please see the document entitled “Cross Platform Authoring and Design Considerations” for more information about mobile specific input, along with other things you may need to consider when developing for Android.
Additional information: Using a Samsung device with Lumberyard If you plan to use a Samsung device to test a Lumberyard game you will need to perform some additional steps for building and debugging. Firstly you will need to install Visual Studio 2015 Update 1 from Microsoft. Note that there is currently a bug which prevents Visual Studio from deploying your APK to the device automatically. You will need to uncheck the Deploy step from the Configuration Manager from the APK's Properties:
You may also encounter an error where Visual Studio will tell you it cannot execute ‘run-as’. There are a number of ways to address this, which is specific a particular device, and can be found by searching the web.
Build assets for Android Build shaders using the Remote Shader Compiler Build the Lumberyard run-time using the build tools.
Prerequisites It is assumed that you have already set up your device for development, as described here, and that it is connected to your computer. Lumberyard currently supports Android SDK-19 (Kit Kat) through to SDK-23 (Marshmallow) and devices which are capable of running OpenGL ES 3.1.
Step 1: Getting Started 1. Start by running Lumberyard Launcher which is located in Bin64. Under Getting Started, tick the checkbox for “Compile for Android Devices”.
2. If you see a cross mark against the “Required SDK’s” tab, you will need to install some software. Click on the tab and select “Get It” for anything that is not yet installed on your computer.
3. Once Lumberyard Launcher reports that you have all the software you need, you will need to make some modifications to your environment variables. a) Open you control panel and go to System->Advanced Sytems Settings->Environment Variables. b) Scroll down to PATH and add the directory where you installed the Android SDK along with the platform-tools and tools subdirectories, for example c:\Android\android-sdk, c:\Android\androidsdk\platform-tools, c:\Android\android-sdk\tools c) Add the path to the Java SDK and JRE (example could be C:\Program Files\Java\jdk1.7.0_79\bin\ and C:\Program Files\Java\jre7\bin). JDK 7 or later needs to be installed. 4. Go to the directory where you installed the Android SDK and run the SDK Manager. Select the version of the SDK you want to install. Lumberyard currently supports SDK-19 (Android 4.4.2) through SDK-23 (Android 6.0). You will also need to install a version of Build Tools – make a note of the version you have installed as it will be required for the next step. 5. Now we will modify some configuration files in order to tell Lumberyard what version of the SDK to use when building your game. a) Open File Explorer and navigate to your Lumberyard directory. Open the file _WAF_\android\android_settings.json in a text editor. b) Edit the BUILD_TOOLS_VER field with the version of the build tools you installed earlier. c) Edit the SDK_VERSION field with the version of the SDK you want to use. d) Save the file 6. Open a command line prompt and navigate to your Lumberyard dev directory. 7. Type “lmbr_waf.bat configure”. This will initialise Lumberyard so it can build SamplesProject. If there are any errors reported, follow the steps given to fix them and repeat the command until it reports a successful configuration. Note that after you run the configuration command for the first time a file called user_settings.options will be created. Your computer is now ready to build the game. Before we do that, we will build the assets that the game will use as well as build and start the Shader Compiler which is needed at run-time.
Step 2: Building assets for your game The Asset Processor can build assets for your Android game but you must first edit some configuration files. 1. Open bootstrap.cfg in a text editor. Make sure sys_game_folder is set to SamplesProject 2. Open AssetProcessorPlatformConfig.ini in a text editor. Uncomment out the line at the top of the document for es3=enabled and save the file. 3. You can now launch the GUI or batch version of the Asset Processor from the Bin64 directory (called AssetProcessor.exe and AssetProcessorBatch.exe respectively). If the AssetProcessor is already running (not the batch version) it will automatically restart itself and start building assets for Android for the project set in the bootstrap.cfg file. All the processed assets will be stored in the ‘cache’ folder of your Lumberyard dev directory. So if you are building SamplesProject, the assets will be in dev\cache\SamplesProject\es3
Step 3: Using assets in your game There are two ways to use assets in your game. You can either copy them to your device manually or pack them into the APK. The method you use is entirely your choice but if you are iterating on data it may be more convenient to use the manual method as the build times are faster.
Manually copying assets As part of the build process, Lumberyard can automatically copy assets to your device if they have been built by the Asset Processor. You can also manually copy them from the command line using ADB. The game expects assets to be copied to /storage/sdcard0/ Example: adb push cache/SamplesProject/es3 /storage/sdcard0/SamplesProject
If you are using a Samsung device, read the notes at the end of this guide for some extra steps that you will need to follow.
Building assets into the APK You can also build an APK which contains all the assets but do note that your build times will be longer. To do this, go to your project directory and open project.json - In this case the file is at {Lumberyard}/dev/SamplesProject/project.json). Look for the “android_settings” and change “place_assets_in_apk” to 1:
"android_settings": { "package_name" : "com.lumberyard.samples", "version_number": 1, "version_name" : "1.0.0.0", "orientation" : "landscape", "place_assets_in_apk" : 1 }, Now when you generate a build, which is described below, your computer will create an APK which contains the executable and game data. Note that you will still need to run the shader compiler when running your game for the first time.
Step 4: Building and Running the Shader Compiler Lumberyard comes with a versatile, next generation, shader system. When running a game for the first time it is necessary to run the Shader Compiler on a PC which will create the shaders needed for your game. Note that the PC and your Android device must be on the same network. Make sure any firewalls are configured to allow traffic through port 61453.
Building If you have built the PC Editor you will already have the Shader Compiler available. If not, type the following on the command line, in your dev directory, which will invoke the build system to build only the Shader Compiler: lmbr_waf.bat build_win_x64_profile -p pipeline --targets=CrySCompileServer,HLSLcc You will see some output from the build system as the executable is generated.
Running Before you run the Shader Compiler you will need to edit system_android_es3.cfg which is located in your dev directory. Look for this line and replace ‘localhost’ with the IP address of the PC you will be running the compiler on: r_ShaderCompilerServer=localhost This setting will be passed on to the run-time later so it can connect to the compiler. Now run CrySCompileServer.exe on your PC, located in: dev/Tools/CrySCompileServer/x64/profile
Step 5: Building the game You are now ready to build various targets of the game. The commands for each one are: a) Debug: lmbr_waf.bat build_android_armv7_gcc_debug –p all b) Profile: lmbr_waf.bat build_android_armv7_gcc_profile –p all c) Release: lmbr_waf.bat build_android_armv7_gcc_release –p all For now, just build the debug version. Once the build has finished successfully you will have an APK in BinAndroid.Debug.
Step 6: Debugging your game Debugging is currently only supported through Visual Studio 2015 which can be downloaded from Microsoft. During installation, make sure you select “Cross platform tools for C++ development”. Once installed go to Tools->Options, and select Cross Platform->C++->Android on the left hand side. Edit the paths to point at the correct directories on your machine:
Visual Studio 2015 (no updates) 1. After you have built a debug version of an APK, launch Visual Studio and go to File->Open Project/Solution. Navigate to your APK (it should be in BinAndroid.Debug\) and select it. 2. Once the IDE settles down go to the project window, right click on the project and select 'Properties' 3. Edit the 'Launch Activity' field by adding '.CryEngineActivity' (don’t forget the period!) 4. For 'Additional Symbol Search Paths' include the following directories 1) dev/Code 2) dev/BinAndroid.Debug 5. You should end up with something like this:
Visual Studio 2015 with Update 1 or Update 2
1. After you have built a debug version of an APK, launch Visual Studio and go to File->Open Project/Solution. Navigate to your APK (it should be in BinAndroid.Debug\) and select it. 2. Once the IDE settles down go to the project window, right click on the project and select 'Properties' 3. The Launch Activity field should already be set to the correct activity; in this example you should see “LAUNCHER activity (com.lumberyard.samples.SamplesProjectActivity) 4. For 'Additional Symbol Search Paths' include the following directories a. dev/Code b. dev/BinAndroid.Debug You should end up with something like this:
Debugging continued… 1. Open code files through File->Open or Ctrl+O. 2. Set breakpoints if necessary and then hit F5 to run You should now be able to step through code and inspect variables as per normal.
Step 7: Running the game If you’re not launching directly from the Visual Studio debugger, as described above, you can run the game by tapping on the icon from the home screen of your device. You may find it useful to view the logging information by running “adb logcat” from the command line. If there is too much output from that command you can also use –s “LMBR” to filter out the output to be only things that the lumberyard engine is printing out. After deploying to your Android device and running, you should now see something similar to the following:
You can run other levels by modifying SamplesProject/autoexec.cfg and re-deploying/running the game. The ones which are currently supported on Android devices are: -
Animation_Basic_Sample Camera_Sample (the default, shown above)
Controls: You can switch between different cameras by selecting the on-screen buttons in the lower right-hand corner of the screen. In the “Character Controller” views, you can control the robot using the touch screen through some simple virtual thumb-stick controls; move using the left side of the screen, look around using the right side of the screen, and jump by double tapping anywhere on the screen. Please see the document entitled “Cross Platform Authoring and Design Considerations” for more information about mobile specific input, along with other things you may need to consider when developing for Android.
Additional information: Using a Samsung device with Lumberyard If you plan to use a Samsung device to test a Lumberyard game you will need to perform some additional steps for building and debugging. Firstly you will need to install Visual Studio 2015 Update 1 from Microsoft. Note that there is currently a bug which prevents Visual Studio from deploying your APK to the device automatically. You will need to uncheck the Deploy step from the Configuration Manager from the APK's Properties:
You may also encounter an error where Visual Studio will tell you it cannot execute ‘run-as’. There are a number of ways to address this, which is specific a particular device, and can be found by searching the web.
