Skip to content

Android Development Guide

Jump to bottom
Peter Robinson edited this page Jun 1, 2020 · 1 revision

Introduction

This guide will show you the steps to setup your computer for Android development. This information may slightly change during the development branch testing phase but this documentation is for people who want to start familiarizing themselves with the Android platform early. The official release of Android platform support will come with the master branch push of Torque 2D 3.0.

Steps to Setup the Environment

Android development is broken into two languages. The main language is Java and the secondary language is C/C++ via JNI. Google does provide a native activity that lets you skip Java for most things and that is what Torque2D for Android will be using. So to compile Torque2D for Android you are going to need two SDKs. Please note that these instructions were created on a Mac computer but they should be the same or almost identical if you are using Windows.

  1. Install Java - You may skip this step if you have the latest JDK already installed. The IDE is Eclipse underneath so it requires Java to run. You can grab the latest Java at:

    http://www.oracle.com/technetwork/java/javase/downloads/index.html

  2. Android Developer Tools - The Android Developer Tools consist of the Android SDK as well as the Eclipse IDE that has been reskinned and has extra plugins that are Android specific pre-installed. Google offers these plugins and the SDK separate but I recommend using the ADT download as everything is setup for you. You can grab the ADT by clicking the blue button that says Download the SDK ADT bundle at:

    http://developer.android.com/sdk/index.html

  3. NDK - The NDK is how you do your native development for the Android platform. It contains the cross compiler tools, gdb, etc for C/C++ development and it integrates with the ADT to let you debug straight from Eclipse IDE. You can download the NDK at:

    http://developer.android.com/tools/sdk/ndk/index.html

  4. Setup - Personally on my Mac I create a folder in my home directory called androidDev that I unzip the NDK, SDK, and eclipse folders. You may put them anywhere but the location will be important later for setup. Once you have them unzipped, go into the eclipse folder and run the Eclipse IDE application. It will ask you for a workspace directory - this location needs to be the Torque2D folder that was cloned or downloaded from Github. Setting your workspace somewhere else will cause the linked folders under JNI to not work.

  5. Modify Paths - The first thing you want to do is let Eclipse know where you installed the NDK. You can do so by going to Preferences in Eclipse and expanding the Android category and clicking on the NDK option. Now you want to set the path to the NDK folder that you unzipped earlier. On my Mac that would be /Users/tim/androidDev/android-ndk-r9. You also want to setup an environment variable that points to the NDK. (This is used by the Torque2D project to find the NDK for locating a few includes) To do so expand the C/C++ Build category and click on Environment. Add a new variable named NDK and set its value to the same path you set before for the NDK folder.

  6. Setup Torque 2D Project - Once you have a version of Torque 2D with Android support pulled down from Github, you will need to setup the eclipse project for it. To do this you go to File->New->Project...

    Expand the Android category and choose Android Project from Existing Code and click Next.

    Now on the next screen of the dialog you want to set the Root Directory so click the browse button and navigate to <git repo location>/engine/compilers/android and click Finish.

  7. Finished - At this point you should be able to clean the project and get no errors if you have everything setup correctly. Since this is an NDK project, you have to watch the Console output to see the results of the build. If the clean succeeds then you should be able to build the project and it succeeds as well.

How to Switch between Debug and Release Mode

In Eclipse expand the JNI folder and open Application.mk. Here you can change the APP_OPTIM from release to debug and back. There are a few more steps to setup debugging in eclipse which I will outline below.

How to Setup Eclipse to Debug T2D for Android

  1. Switch APP_OPTIM to debug in Application.mk as outlined above.

  2. Open AndroidManifest.xml and click the Application tab. Scroll down to the Debuggable flag and set it to true.

  3. Right click the project in the left side panel and choose properties. Click the C/C++ Build text in the left pane on the properties popup. To the right you should see Build Command: and in the box it has ndk-build. change that to:

    ndk-build NDK_DEBUG=1

  4. Clean and build the project.

  5. Click the little bug symbol with a device plugged in to launch the game in debug mode. You will not be able to actually debug yet, but this does create a file we need.

  6. Stop the debug session after torque launches and look for a file called gdb.setup located in obj/local/armeabi-v7a/. Open the folder the file is in and make a copy of it called gdb2.setup. Open gdb2.setup in a text editor and remove:

    target remote :5039

  7. Click the arrow next to the bug symbol and choose Debug Configurations. Click Android Native Application and then click the new icon (sheet of paper with a + on it in the top left corner).

    a. Edit the name to whatever you want. i.e. Torque2dDebugNative

    b. Click browse under project and choose Torque2D.

    c. Switch to the debugger tab and click browse next to the GDB Command File and choose the gdb2.setup you edited earlier.

    d. Apply your changes and click Debug.

  8. You also have to setup your device for debugging. It is usually under Settings and either a Developer option or under the About maybe. It varies by device. Click to enable USB debugging. I usually also enable stay awake so the device doesn't go to sleep while you are trying to deploy.

  9. Set a break point and it should stop on it. If you need to debug early in the startup, there is a sleep(10); commented out in the android_main function in platformAndroid/T2DActivity.cpp. This 10 second pause stops execution long enough for the debugger to attach and enable debugging. Eclipse native debugging is very hit and miss. You may get times where it just refuses to do something and you have to restart the debug process again.

Notes on Project Setup for Deploying to a Device

  1. You need to copy all of your assets into engine/compilers/android/assets folder. By default the only thing in there is the splash screen. To get the toys up and running you just copy the main.cs and modules folder into the assets folder.

  2. At the bottom of main.cs there is a function called androidBackButton. You can move it else where if you need to but it is the callback if the users hits the back button on your device. It takes 1 parameter that is true or false (button down vs button up). Currently all the function does is quit Torque when you press the back button.

  3. The splash screen is a Java dialog that has to be hidden from TorqueScript when the game loads. It is currently in the toys code but if you start with a new script setup you will need to add hideSplashScreen() into your scripts when you want to hide it.

  4. Fonts work both from cache generated from the desktop as well as fonts on device (which vary by device and android version) and custom TTF fonts that you can drop into assets/fonts. If you would like to print a list of fonts on your device you can call dumpFontList() and it will print them to LogCat. The font searching on device works by partial name as well. For instance the script use the font Droid so it will pick the first font from your device that has the word Droid in it (which quite a few android device fonts do since its all custom fonts). You can also specify the full font name to make sure it only uses that one. But remember you may have some devices where that font does not exist.

  5. Android applications have 4 callbacks specific to the platform. Note #2 covered androidBackButton. The other 3 callbacks are:

  • onAndroidResignActive - called when the game is no longer the active foreground application
  • onAndroidBecomeActive - called when the game regains focus and is no longer a background app
  • onAndroidWillTerminate - called before the general "onExit" callback and before the game is shutdown

Keep these callbacks in mind when developing your game - the engine does not automatically handle things like pausing any music or other sounds when the app is pushed into the background. You will need to script that functionality yourself.

Android Studio

Android Studio is not covered by this guide, but it is supported by T2D. Someday this guide will cover its use in depth, but for now instructions on using it can be found here.

Clone this wiki locally