Android

This guide explains the process involved in creating projects when using Tier 2 for the Android platform. As the requirement is for Android 2.3.3 and above, you are able to code in native C/C++, rather than Java.

NOTE: This guide is intended to be used when compiling on Windows. For example, instead of C:\AndroidDev\, you might use /home/[NAME]/AndroidDev/.

What you need

You will need to download the following files and packages. This assumes you have a 64-bit computer, if you have a 32-bit computer then download the 32-bit (x86) versions instead.

• Java JDK. ~200MB.
• Go to http://www.oracle.com/technetwork/java/javase/downloads/index.html and download the latest version of the JDK, as of writing this is Java SE 8u77. Click the download button next to the JDK, accept the license, and download the Windows x64 package (file should be called something like jdk-8u77-windows-x64.exe).
• Android NDK. ~400MB.
• Go to https://developer.android.com/ndk/downloads/index.html and download the 64-bit package for Windows. At time of writing the latest version is r16b, but it may be higher now.
• Android Studio. ~350MB.
• Go to http://developer.android.com/sdk/index.html and download the latest version of Android Studio for your platform. At time of writing this is version 3.1.2, but it may be higher now.

NOTE: The AGK Tier 2 files must be installed in a path with no spaces, otherwise the NDK will fail to compile the necessary files.

The Preparation sections only need be completed once. After that, you can just start from Creating a New Game Project.

Preparation: JDK

The following steps will show you how to install the JDK.

• Run the downloaded file, it should look something like jdk-8u77-windows-x64.exe, and install it to a location of your choice.

Preparation: Android NDK

The following steps will show you how to set up the Android NDK.

• Run the downloaded file, it should look something like android-ndk-rxxb-windows-x64.exe. It should extract somes files to a new folder in the same location as the downloaded file.
• Move the new folder to a location of your choice, for example C:\AndroidDev\, this path should not have any spaces.

Preparation: Android Studio

The following steps will show you how to set up the Android Studio.

• Run the downloaded file, it should look something like android-studio-ide-141.2456560-windows.exe, the numbers will vary based on the latest version at the time.
• When asked to choose components the Android Virtual Device is optional and can be unticked if you will be testing on a real Android device.
• Agree to the license agreement and install to a location of your choice.
• If you downloaded the 32-bit version of the JDK then on the final screen after installation untick Start Android Studio as this will try to start the 64-bit version and cause an error. Using the generated shortcut will also try to start the 64-bit version, so instead you will need to find the 32-bit exectuable in the installation folder.
• To find the executable, browse to the Android Studio install folder, by default this is C:\Program Files\Android\Android Studio\ then open the bin folder and run studio.exe for 32-bit or studio64.exe for the 64-bit version.
• Note that the version of Android Studio that you use (32-bit or 64-bit) depends on the JDK version you have installed, they must match or you will get an error.
• Android Studio should automatically detect your Java installation, if not you will get an error message saying that Android Studio can't find it and ask you to set a JAVA_HOME variable. Double check your Java installation and set up a JAVA_HOME variable if necessary.
• When Android Studio first runs it will present an SDK Components Setup dialog, click Next or Finish and let it install the default components.
• When completed you should see a list of options such as Start a new Android Studio Project and Open and existing Android Studio Project, select Configure and then SDK Manager.
• In the SDK Platforms tab Android Studio will have automatically installed the latest SDK Platform, but we need to install a specific version. If the latest version is not 8.0 (API 26) then tick the box next to Android 8.0 (API 26). You only need the Platform option, not the Google APIs or any of the others.
• Now switch to the SDK Tools tab and tick Android Support Repository, Google Play Services, and Google USB driver, then click OK and let it install.
• Come back out of the Configure option and choose Open an existing Android Studio Project, browse to your AGK Tier 2 folder, then apps, select the template_android_google folder and click ok.
• When the project first loads, Gradle will attempt to sync and build the project, Grade is the build manager that ships with Android Studio. You will likely get some messages from Grade Sync saying it failed to find the correct Build Tools version, click the provided link to install the missing version
• Now Android Studio should be working without error, however it will not produce a valid application until we compile the NDK libraries for our project.
• Minimize Android Studio and browse to the location you installed the AGK Tier 2 files, then go to apps\template_android_google\AGK2Template\src\main
• In here you will see a file named jniCompile.bat, right click on it and choose Edit
• Change the line that starts set NDKBUILDCMD= to point to your NDK location, for example set NDKBUILDCMD="C:\AndroidDev\android-ndk-r16b\ndk-build", save this file and close it, then double click it to run the NDK compile process for this project. The NDK folder name may vary based on which version of the NDK you downloaded. The folder name itself is not important as long as it points to the NDK you downloaded.
• It will compile three libraries, one for arm64-v8a, one for armeabi-v7a, and one for x86, these cover the three most popular architectures that run Android. The libraries will be placed in the appropriate folders for Android Studio to pick up next time it builds an APK of your project.
• When it is done it should end with a line starting [x86] Install, if not then there was an error and you should check the log.txt file in the same folder as the jniCompile.bat file for details
• Now return to Android Studio and choose Build->Make Project it should display the Grade Console window with its progress and end with a BUILD SUCCESSFUL message. You can attempt to run this project on your device if you have already enabled it for USB Debugging, if not continue to the next section, or you can create a virtual device to test the project in an emulator.
• The template_android_google app should display a pale blue screen with the framerate displayed near the top left. It is not recommended that you make changes to this project as it can serve as the template for future projects. The recommended approach is to copy the template project and make changes to the copy, see the Creating a New Game Project for details.

Preparation: Running On A Device

The following steps will show you how to setup your device for testing your apps.

• Connect your Android device (your phone or tablet) to your PC by USB and turn on USB Debugging in Android's settings. To turn on USB Debugging:
• Plug in your device.
• Open Settings, scroll down to and tap on Developer Options, and tap the on-off switch at the top-right.
• Tap USB Debugging and accept the warning to enable it.
• This should trigger windows to re-detect your device with additional device components, this is where the Google USB Driver comes in that we downloaded earlier. Windows may automatically detect the debug portion of your device successfully, or it may require you install the Google USB Driver to detect it correctly.
• More detailed instructions on USB Debugging and how to install the USB debug driver vary by device, and are outside the scope of this guide, but there are plenty of tutorials online.
• You will also need to enable the Unknown Sources option in the security section so that apps can be installed that have not been downloaded through Google Play.
• Once your device is setup to receive debug apps you can click the Run icon in Android Studio and it should automatically detect your connected device and upload your newly compiled app to it.

Creating a New Game Project

The following steps will show you how to set up a new project. Once you've completed all the Preparation sections of this guide, this is where you should start from each time you want to make a new project.

• Navigate to your AGK Tier 2 files folder, open the apps folder and make a copy of the template_android_google folder. This will be your new project folder, and you can rename it as you wish as long as you don't use spaces.
• Note that for simplicity your new folder should remain within the apps folder as it contains relative paths to other areas of the AGK Tier 2 folder, notably the platform/android/jni folder.
• When you open Android Studio it will default to opening the last project you had open, go to File->Close Project to return to the main menu if you no longer want to work with it, you can then open your new project with Open an existing Android Studio Project and browsing to the new project folder you created.
• NDK support in Android Studio is still experimental so we use the jniCompile.bat file mentioned earlier, but you can still edit the C++ files (those with the .cpp or .h extensions) inside Android Studio. Be sure to call the jniCompile.bat file after you make any changes to those files.
• To change the package name for your app open the AndroidManifest.xml file and edit the package field from its default of com.mycompany.mytemplate. Note that when you do this you will need to go through the other files and change any instance of com.mycompany.mytemplate to your new package name, you will get an error if you forget to do this.
• Leave any instances of com.thegamecreators.agk_player as they are, it does not affect the final app and is used to tie together lots of parts of the app, so handle with care.
• Open the build.gradle file for the AGK2Template module and edit the applicationId field from its default of com.mycompany.mytemplate to your chosen package name.
• To change the name of the app, open the res/values/strings.xml file and edit the app_name field.
• To write your app code you only need to modify the template.h and template.cpp files, these files are only read by the Android NDK when you run jniCompile.bat (or compile manually using the command line)
• If you wish to add more .cpp files you will need to edit the AGK2Template\src\main\jni\Android.mk file in notepad, look for the LOCAL_SRC_FILES := line and add additional .cpp files there, save it, and run jniCompile.bat again to recompile.
• To add media to your project, create an assets folder at [project_folder_name]\AGK2Template\src\main\assets replacing [project_folder_name] with your renamed folder. Note that in Tier 2 a folder named media is not required and you can place images, sounds, etc, directly in the assets folder. If you do use a media folder then remember to use agk::SetFolder("/media") near the start of your program to make it behave more like Tier 1.

Last Updated: 25th April 2018