Tutorial: How to build for Android devices on you Mac
Tutorial: How to build for Android devices on you Mac This tutorial will guide you through the process of building Samples Project for your Android device on you Mac. 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 via a USB cable. Lumberyard currently supports Android SDK-19 (Kit Kat) through to SDK-23 (Marshmallow) and devices which are capable of running OpenGL ES 3.1.
PC based tools Note that even though you can build for an Android device on your Mac, the Asset Processor and Shader Compiler require the use of a PC. You will need to refer to the document “Building Android on PC” for information on how those tools can be setup and invoked.
Step 1: Getting Started 1. Start by running Lumberyard Launcher which is located in Bin64. You will need to unzip the LumberyardLauncher.zip file and place the .APP in Bin64. After running the application, click on the Getting Started tab and tick the checkbox for “Run the Game”, “Compile for Android Devices” and “Compile the Game Code”.
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. NOTE: You will also need to check the box for the WWise audio library, download it if you do not already have it, and then install it. You will also need to use/install JDK 7 or above. Next, open a command prompt and go to your Lumberyard dev directory and type: sh lmbr_waf.sh configure NOTE: This is the first step to initialise the build system and in the event you see any error messages you can ignore them at this stage. Then open Finder and navigate to Lumberyard\dev; open the file dev/_WAF_/user_settings.options in a text editor. Look for the line with ly_launcher_param and edit it until it matches this: ly_launcher_param = --none --enablecapability compilegame --enablecapability compileandroid --nomodify-environment 2. Once Lumberyard Launcher reports that you have all the software you need, you will need to make some modifications to your environment variables. a) Assuming you are using Bash, edit your .bash_profile and add the path for android- sdk/platformtools and android-sdk/tools. Restart the terminal window to have these changes take affect. b) You will also need to run this from the command line in the SDK directory: tools/android update sdk -no-ui 3. Go to the directory where you installed the Android SDK and run the ‘android’ executable file which can be found in the ‘tools’ directory. You can do this from Finder or from the command line. Once it is running 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. 4. Now we will modify some configuration files in order to tell Lumberyard what version of the SDK to use when building your game. Important note – you will need to save any files with the correct line endings. It is recommended that you research how to do this if you are using a text editor other than vim. If you are using vim you must save the file out by using this command: “w ++ff=mac” 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 (taking note about the line endings as mentioned above) 5. Open a command line prompt and navigate to your Lumberyard dev directory. 6. Type “sh lmbr_waf.sh 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. You can edit this file to set the enabled game project and omit the parameter from the command line for subsequent configuration runs. 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. Refer to the document “Building Android on PC” and follow the instructions for building assets and the Shader Compiler.
Step 2: Building the game You are now ready to build various targets of the game. The commands for each one are: a) Debug: sh lmbr_waf.sh build_android_armv7_gcc_debug –p all b) Profile: sh lmbr_waf.sh build_android_armv7_gcc_profile –p all c) Release: sh lmbr_waf.sh 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.
Debugging the game Debugging is currently only supported on PC using Visual Studio 2015. Refer to the document “Building Android on PC” for more details.
Step 3: Running the game To run the game you can tap 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. 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 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.
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 via a USB cable. Lumberyard currently supports Android SDK-19 (Kit Kat) through to SDK-23 (Marshmallow) and devices which are capable of running OpenGL ES 3.1.
PC based tools Note that even though you can build for an Android device on your Mac, the Asset Processor and Shader Compiler require the use of a PC. You will need to refer to the document “Building Android on PC” for information on how those tools can be setup and invoked.
Step 1: Getting Started 1. Start by running Lumberyard Launcher which is located in Bin64. You will need to unzip the LumberyardLauncher.zip file and place the .APP in Bin64. After running the application, click on the Getting Started tab and tick the checkbox for “Run the Game”, “Compile for Android Devices” and “Compile the Game Code”.
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. NOTE: You will also need to check the box for the WWise audio library, download it if you do not already have it, and then install it. You will also need to use/install JDK 7 or above. Next, open a command prompt and go to your Lumberyard dev directory and type: sh lmbr_waf.sh configure NOTE: This is the first step to initialise the build system and in the event you see any error messages you can ignore them at this stage. Then open Finder and navigate to Lumberyard\dev; open the file dev/_WAF_/user_settings.options in a text editor. Look for the line with ly_launcher_param and edit it until it matches this: ly_launcher_param = --none --enablecapability compilegame --enablecapability compileandroid --nomodify-environment 2. Once Lumberyard Launcher reports that you have all the software you need, you will need to make some modifications to your environment variables. a) Assuming you are using Bash, edit your .bash_profile and add the path for android- sdk/platformtools and android-sdk/tools. Restart the terminal window to have these changes take affect. b) You will also need to run this from the command line in the SDK directory: tools/android update sdk -no-ui 3. Go to the directory where you installed the Android SDK and run the ‘android’ executable file which can be found in the ‘tools’ directory. You can do this from Finder or from the command line. Once it is running 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. 4. Now we will modify some configuration files in order to tell Lumberyard what version of the SDK to use when building your game. Important note – you will need to save any files with the correct line endings. It is recommended that you research how to do this if you are using a text editor other than vim. If you are using vim you must save the file out by using this command: “w ++ff=mac” 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 (taking note about the line endings as mentioned above) 5. Open a command line prompt and navigate to your Lumberyard dev directory. 6. Type “sh lmbr_waf.sh 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. You can edit this file to set the enabled game project and omit the parameter from the command line for subsequent configuration runs. 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. Refer to the document “Building Android on PC” and follow the instructions for building assets and the Shader Compiler.
Step 2: Building the game You are now ready to build various targets of the game. The commands for each one are: a) Debug: sh lmbr_waf.sh build_android_armv7_gcc_debug –p all b) Profile: sh lmbr_waf.sh build_android_armv7_gcc_profile –p all c) Release: sh lmbr_waf.sh 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.
Debugging the game Debugging is currently only supported on PC using Visual Studio 2015. Refer to the document “Building Android on PC” for more details.
Step 3: Running the game To run the game you can tap 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. 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 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.
