Setting Up For Android

GameMaker Studio 2 Mobile comes with two export platforms: Android and iOS. In this article we give the required steps to get the Android platform up and running.

General Information

After installing and running GameMaker Studio 2 on your PC you should be able to create and test projects immediately using the "Test" target option on your build computer. However you can specifically target Android from the IDE using the Platform Target window, located in the top right of the main GameMaker Studio 2 workspace:

For the Android target platform you can see that there are two output options:

  • VM - This will build your game using interpreted code. 
  • YYC - This will build you game using compiled native code.

The VM option will build your game and use interpreted code within a special YoYo Runner. The performance of this target is less optimised than YYC, but it is faster to compile and offers the ability to run in debug mode (when using YYC the debugger will not start). The YYC target however, gives a much greater optimisation (and corresponding performance boost) especially with logic-heavy games, but large projects can take some time to compile.

Regardless of the output that you select, you will need to add some extra build tools to your development computer before you can continue...

Required Downloads

To start working with your Android devices and GameMaker Studio 2 you will need to download and install the following development kits:

  • Android SDK (Command Line Tools only!)
  • Android NDK
  • Java SE Development Kit (JDK)

These kits will be used when testing and building your game app for Android. Note that the exact versions required for each (along with links for downloading them) can be found from the article:

Required SDKs

Note that these are the minimum required SDK settings that are listed, but in general you should simply install the latest versions.

The Android SDK command line tools will download as a ZIP file and you should create a folder called "Android SDK" and then unzip the contents of the ZIP to that folder (so you have something like C:\Android SDK\Tools for the path).

Android SDK Manager

 Android Studio

Once it has installed click Configure then SDK Manager. This will open the following window

IMG_28042017_100742_0.png

Download the latest SDK and then click on the SDK Tools tab.

IMG_28042017_100749_0.png

 

Command Line Tools Only

Once you have unzipped the contents of the Android SDK tools, you need to add the required libraries to the SDK from the SDK Manager. This can be done from the command line (see here for details) or you can run the android.bat file in the Tools directory to open a command window and run the SDK Manager UI (this rest of this article will refer to this).

The SDK Manager will look like this: 

 

Getting everything downloaded is nearly identical so we shall go on speak as though you used command line tools.

To start with you can leave the Tools folder "as is" (it should have selected Android SDK Tools, Build Tools and Platform Tools), and also leave default Android API that is to be installed (it will have checked the most up-to-date version, but you can run the SDK Manager again later and add further APIs as required). However before installing these you should also check a few things in the Extras folder, namely:

  • Android Support Repository
  • All Extras with "Google" in the title (Google Play Services, Google Play Billing Library, Google USB Driver, etc... see the image below for an example setup)

These are not all going to be used for a simple game on Android (except the Support Library, which is essential), but if you wish to include any type of publicity or online services then you will need them, so it's best to have them installed now to save time later.

Note that while installing the packages you may need to accept certain licence agreements and the SDK Manager may require you to restart (in which case simply close the SDK Manager and run the Android.bat file then continue).

IMPORTANT! Make sure to take note of the Build Tools Rev. (Version) number as well that of the API installed, as you will need these later in GameMaker Studio 2.

If you wish to target the Amazon Fire device or use any of the Amazon services in your game, you will also need to download an additional set of file from the SDK Manager. However, since these are for Amazon and not Google, you need to do it from the Add On Sites window, which you open from the Tools menu of the SDK Manager:

In the Addons window you need to go to the tab "User Defined Sites", then click "New" and give the following URL when prompted:

https://s3.amazonaws.com/android-sdk-manager/redist/addon.xml

The Addons window will now look like this:

When you click the "Close" button, the additional Amazon files will be downloaded by the SDK Manager for you. 

Android NDK

Once you have downloaded the Android NDK you will need to unzip the contents of the ZIP file to a suitable location (for example C:/Android NDK/). It does not require any further setup and is ready for use.

Java JDK

You now need to download and install the Java JDK. It does not require any further setup and is ready for use.

 

Once you have installed the JDK and its components, and have the Android SDK and NDK set up, you can continue with GameMaker Studio 2...

Set Up GameMaker Studio 2 Preferences

When you go back to GameMaker Studio 2 after downloading and installing the required SDK, NDK and JDK files, the first thing you need to do is set up the Android Platform Preferences:

Here you need to link each of the downloaded SDKs with GameMaker Studio so that you can test and build your games. Once you have supplied the required paths for the SDK, NDK and JDK they should show a green "Found" label and you can then continue to create your Keystore file:

The KeyStore is a file that will be used to "sign" all your Android apps so please fill in all the details correctly and then back this file up! We recommend you create a single keystore file for all your projects and not separate ones for each project.

If you lose your keystore or forget the alias/password details you will not be able to perform updates on Google Play or Amazon apps that have already been published!

The Keystore file requires the following details:

  1. File Name - this is the filename of the KeyStore (NOTE: Not your name or the company name!), and once it has been created this field will show the full path to it.
  2. Password - your security password for the KeyStore file which must be at least six characters long.
  3. Alias - this is the name of the "user" for this keystore and can differ from the Name field above.

The right-hand side is optional and has no relation inside GameMaker: Studio, but we'd recommend you fill them in anyway.

  1. Common Name - this would normally be your name
  2. Organisational Unit - the department within the company that you are in
  3. Organisation - the name of your company
  4. Location - the name of the town or city where you are based
  5. Country - the two letter code for the country where you are based

Note that all names must have only letters, numbers and spaces but no special characters.

Once this information is filled in and you are happy with it, press the button marked "Generate Keystore" for GameMaker Studio 2 to create the necessary KeyStore file. This may take a moment, but once it is done it normally will not need to be changed again.

If you are using a previous Keystore file, then simply point GameMaker Studio 2 to the file and fill in the details exactly as they were when you first generated it, but do not hit the Generate Keystore button and instead click Apply.

Just to repeat what was said before, as it's very important: please backup your keystore file somewhere safe and make sure to remember your details - we recommend taking a screenshot with the passwords showing and then back this image file up along with your keystore. You can find the generated keystore at the path you have in the top field of this preferences form.

Once everything is setup here you can continue to add one or more devices for testing.

Set Up GameMaker Studio 2 Devices

Back to your GameMaker Studio 2 machine, and in the Targets Window you can see that there is a section marked Devices with a small "pencil" icon beside it:

Clicking this will open up the Android Device Manager where you can add one or more Android devices to target when running and building your projects for the Android platform.

Now, if you have an Android device and it is connected via USB, then you should be able to simply click the Detect Device button and the device will be added automatically for you. However if you want to connect over Wifi, you will need to click the Add New Device button and then fill out the details, giving it an identifying Display Name for the IDE and where the Host Name corresponds to the local IP of the device (which will be something like 192.168.1.17):

IMPORTANT! Your test device(s) must have Developer Mode and USB Debugging enabled! 

If you have issues with GameMaker Studio 2 finding the device on USB, or you cannot find the IP of the device, or have any other connection issues, please see the article on Android Troubleshooting.

With that done you can then click the Test Connection button, and if the Android device is visible over the network (or correctly connected via USB) then it should say "Connection Successful!":

Note that there is also an option to use an Android Virtual Device (AVD) for those of you without test devices, or that want to test on a wider range of devices. Clicking this button will open the AVD Manager where you can create and then run your virtual device. Once you have it running, you can go back to GameMaker Studio 2 and click the Detect Device button to add it to the list of devices in the Device Manager. For more information on AVDs see here: Create And Manage AVDs

NOTE: Before you can use an AVD you must have disabled Hyper V (if you have it installed), and also ensure that HAXM is installed (from the Android SDK Manager) and will work on your machine. For more information on HAXM please see here.

 

Set Up GameMaker Studio 2 Game Options

Unlike some other target platforms, before you can test your game you need to set some things in the Android Game Options, namely the initial Build Settings:

GameMaker Studio 2 gives you the option to selectively target specific versions of Android, mainly due to the fragmented nature of the Android OS on devices and the fact that certain extensions require different SDK or build tools. For a "vanilla" project (ie: one that has no extensions or extra requirements) you would normally set these to the most up to date versions of everything.

You first need to give the Build Tools version, which can be found from the Android SDK Manager, as shown in the example below (your version numbers may be different and the image is provided purely as an illustration of where to look):

You also need to give the Support Library to use. Recent versions of the SDK Manager no longer list these separately and instead they are included as part of the Support Repository, so to target the correct one simply use the initial Build Tools version number (for example, in the above image the build tools are 25.0.2, so the support library would be 25.0.0).

Next you have to set the Target, Minimum and Compile SDK versions. The Compile SDK version is the version of the API that the project is compiled against. This means you can use Android API features included in that version of the API. If you try and use API 16 features - for example - but set Compile SDK 15, then you will get a compilation error. If you set the Compile SDK to 16 then you can still run the app on an API 15 device (as well as all other previous versions too).

The Target SDK, however, has nothing to do with how your app is compiled or what APIs you can utilize. The Target SDK indicates that you have tested your app on (up to and including) the version you specify. This is simply to give the Android OS an idea of how it should handle your app in terms of OS features. For all practical purposes, most apps are going to want to set Target SDK to the latest released version of the API (as used by the Compile SDK setting). This will ensure your app looks as good as possible on the most recent Android devices.

The Minimum SDK version is the minimum API level that will run your project. This is set to 9 by default, and in general this will be fine, but if you add extensions then they may require a higher minimum API level.

You don't need to give any further information here for testing your projects so you can close the Game Options.

Testing On An Android Device

Before testing your project on the Android target you should have:

  1. Installed the Android SDK, NDK and Java JDK
  2. Set up a Device for testing in the Device Manager
  3. Set up the API and Build tools to use in the Game Options

Once those three steps are completed and you have a project ready for testing, you can go to the Target Manager in the GameMaker Studio 2 IDE and select the target, output and device options that you want to use:

You can then click the "Play" button in the GameMaker Studio IDE to compile the project and push it to your test device.

NOTE: If you are want to test on an emulated device via AVD, you must have started the AVD manager from the Device Manager, and have already started the emulated device there.

Note that the first time you try to test an Android game, the compile process may need to connect to the internet to download additional files and tools, which in turn may prompt a firewall alert - if this happens you should allow the connection otherwise the build will fail. This is normal and should only happen the very first time you test a game.

If all has gone well, you should see your game project running on your target device. Once you have finished testing and are happy with the project, then you'll want to look at creating a final executable package and publishing it to a store. This process is explained in the following article:

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.
Powered by Zendesk