GameMaker Studio 2 Mobile comes with several export platforms: Android, Amazon Fire, iOS and tvOS. In this article we give the required steps to set up Android and Amazon Fire, as both targets require the same tools to create executables and to test your projects. This guide covers the Mac and Windows IDEs.
Note that whenever possible you should stick to the specific versions advised in the Required SDKs FAQ, as newer versions are likely to be unsupported - Google do update the SDK/NDK pretty frequently, so be careful if you're someone who likes just grabbing the latest stuff each time Google releases something. We would also strongly suggest you do not install beta SDK/tools versions!
Overview / Before You Begin
After installing and running GameMaker Studio 2 on your PC or Mac you can build projects for Android/Amazon using the Target Manager window opened by clicking the "target" button in the top right of the main window:
For the target platform you can see that there are two output options:
- VM - This will build your game using interpreted code.
- YYC - This will build your 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 performance boost, especially with logic-heavy games, but large projects can take some time to compile and you cannot use the debugger.
Regardless of the output that you select, you will need to add some extra build tools to your development computer before you can continue...
Set Up the Android SDK and NDK
To start working with your Android/Amazon devices you will need to download and install Android Studio.
- The old "SDK Manager" method of installing your Android SDK on Windows is no longer supported in GMS2 2.2.4+, as Google won't allow AndroidX to be downloaded via SDK manager. You will need to change to Android Studio.
Allow it to install with the default components it suggests for your PC/Mac, but when it asks you where you want to install your SDK, please be aware that Google's path names can get very long, which can cause issues with Window's path length limit of 256 characters, so we would highly recommend installing as close to the root folder of your drive as possible AND not using any whitespace - e.g: "C:\AndroidSDK" for your Android Studio path - in order to avoid errors later on, when building your projects. For macOS users, we would still recommend using a nice and memorable short path also, but it's less important that you do so. We use "~/AndroidSDK/" on our machines.
Ignoring this advice and still putting whitespace in your path will cause Android Studio to warn you this can cause issues when using the NDK tools (which therefore means all YYC builds inside GMS2 may fail), so just avoid doing this.
To do this, start the Android Studio Installer and choose Custom and click Next:
Now, it gives you the option to set the path to the install folder:
You can see that this screen also gives you the option to install AVD emulators if your PC supports them. You can install this if you wish, but please note that the emulators are only compatible with some CPU architectures, so they may refuse to install, and emulators are never a replacement for real device testing anyway.
YoYo also won't offer any support for testing games on emulators, if you send a Helpdesk ticket about this - we only offer support when running on real devices.
Once you have set the shorter SDK install path (if on a PC) and your chosen components are installed, on the Splash Screen, go to the menu labelled "Configure", and in the drop-down menu select the SDK Manager.
This will open the following window, where you can select and install the platform SDKs that you require - typically, you only need the one API version we say to use on the Required SDKs FAQ, however if you are using extensions in your project then these third-party SDKs may require you to install additional packages later on.
When ready, click the "Apply" button to download the SDK components, and don't forget to take note of the Android SDK Location value written at the top of the window. as you'll need it later for entering into GameMaker Studio 2's Preferences.
Once you have downloaded the required SDK platform, you need to click on the SDK Tools tab and then ensure the following are downloaded and installed (select each of them from the list then click Apply to download them - note that you may need to accept licence agreements before the download begins):
IMPORTANT! Make sure to take note of the Build Tools Version number as well that of the API installed, as you will need these later in GameMaker Studio 2.
Amazon Support
If you wish to target Amazon Fire or use any of the Amazon services in your Android games, you need to download an additional set of tools. However, since these are for Amazon and not Google, you need to do it from the SDK Update Sites tab. Here you need to click the (+) at the bottom and then enter the following in the window that opens:
https://s3.amazonaws.com/android-sdk-manager/redist/addon.xml
Name the entry something like "Amazon Fire" then click "Okay" and then in Android Studio click Apply. The SDK Update Sites tab should now look like this:
If you go back to the SDK Tools tab, you will now have new entries for Amazon Fire, and you should select these then click Apply to install the components:
With that done, you are now ready to go and set up your project in GameMaker Studio 2.
NDK Install Location
Android Studio will always install your NDK into a subfolder of the SDK install location you set earlier. You have the choice of the "NDK" or the "NDK side-by-side"- it's up to you which one you pick, but be aware this slightly changes the install location thereafter. Assuming you did use the values we recommended earlier as your SDK installation path:
- For the "I only want one NDK install at once" option, it's simply C:\AndroidSDK\ndk\ or /Users/[your macOS username]/AndroidSDK/ndk
- And for the "side-by-side" option, it adds a subfolder for the exact version number - e.g., C:\AndroidSDK\ndk\20.0.5594570\ or /Users/[your macOS username]/AndroidSDK/ndk/20.0.5594570/
If you chose a different install location earlier and now want to change this so yours matches our recommendations, you can do so back on teh SDK Manager screen in Android Studio.
Java JDK Install Location
Android Studio comes with its own version of OpenJDK8, which is the only/the latest version of JDK Google's build tools actually supports. You do not need to install a JDK separately, so please don't just grab the latest version of Java just because.
(Google recommend you use the copy they ship, and Oracle have changed the licence for Java which means you may now need to pay for commercial app development usage, so it's best to avoid that and stick with Google's tools...)
By default, on Windows your JDK path would be C:\Program Files\Android Studio\jre and on macOS it would be /Applications/Android Studio.app/Contents/jre/jdk/Contents/Home
Set Up GMS2's Preferences
When you now return to GameMaker Studio 2, you need to set up the Platform Settings sections in Preferences (here, we show Android, but Amazon Fire is identical). Fill in your SDK, NDK, and JDK install paths, as discussed in the two sections of this guide just above, so it looks something like this:
Now you can scroll down and create your Keystore file. This is a file that will be used to codesign all your Android apps, so please fill in all the details correctly and then back this file up along with a screenshot or other record of your username and passwords!
When creating a new keystore file, you are required to give the following details:
- File Name - Populated by GMS2 to show you where the keystore is location (you don't fill this in unless you're importing an existing keystore file)
- Password - The password for the KeyStore file itself, which must be at least six characters long.
- Alias - This is the name of the "user" for this keystore and can differ from the Name field above.
All other fields are optional (as shown in the screenshot above) and are not used inside GameMaker Studio 2, but if you wish to fill them in:
- Common Name - this would normally be your own name
- Organisational Unit - the department within the company that you are in
- Organisation - the name of your company
- Location - the name of the town or city where you are based
- Country - the two letter code for the country where you are based
Note that all names must have only letters, numbers and spaces - no other "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 and then you should see the key has fields are filled in for you. You can now Apply/OK and you're done.
We recommend you create a single keystore file for your organisation and use this same file for all your projects, not separate keystores for each project.
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 backing this image file up along with your keystore.
Importing an Existing Keystore
If you are using an existing 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. Do not hit the Generate Keystore button, instead click Show Key Hash to confirm all works fine, then click Apply/OK.
The specification for a keystore file does allow you to have multiple users ("aliases") in a single keystore file. GMS2 doesn't provide for creating keystores in this fashion, but if you import a keystore which already has multiple aliases in it, then you just supply the master password and the details for the one alias you wish to use.
Once everything is setup here you can continue to add one or more devices for testing.
Set Up Android Devices
Back to GameMaker Studio 2 and in Target Manager 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. For GameMaker Studio 2 to detect your device it must first have been plugged into the the PC or Mac using a USB cable, and must have Developer Mode and USB Debugging enabled. On Mac you will also need to have installed the Android File Transfer App.
Once the device is connected, clicking Detect Device should automatically detect it and add it to the list of connected devices:
If you have issues with GameMaker Studio 2 finding 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 and 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. You can find out more about setting up AVDs on both PC and Mac using Android Studio from the following article:
Setting Up Android Virtual Devices
Once you have set up an AVD you need to start the emulation before going back to GameMaker Studio 2 and clicking the Detect Devices button. A list of detected emulated devices will be shown and you can proceed to use them as targets for compiling (note that if you do not start the emulator before testing your project then the device will not be found and compilation will fail). If you want to check that the devices have been detected and can be used before trying to compile you can click the Test Device button for each of the discovered devices.
Set Up The 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 (i.e., 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 SDK Tools section of the SDK Manager in Android Studio, although note that you will need to check the "Package Details" to see it:
The next option is a legacy option for the "Support Library". From GameMaker Studio v2.2.4 onwards, this is no longer required and any values placed here will be ignored. However for all previous runtimes, this is still required (along with the installation of the Support Repository in Android Studio). 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 28 features - for example - but set Compile SDK 26, then you will get a compilation error. If you set the Compile SDK to 28 then you can still run the app on an API 26 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 16 by default, and in general this will be fine, but if you add extensions then they may require a higher minimum API level.
IMPORTANT! If you are using the AVD and an emulated device then you must open the Architectures section and check the x86 target, otherwise the project will not compile and run.
You don't need to give any further information here if you are just testing your projects, and so you can close the Game Options and continue.
Testing On An Android Device
Once the above sections are completed and you have a project ready for testing, you can go to Target Manager 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.
Remember: If you are want to test on an emulated device via AVD, you must have started the AVD manager from an Android Studio project (PC and Mac), and have already started the emulated device there.
Note that the first time you try to test an Android game, Google's compile tools 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 first time you build using those SDK values. Be aware that Gradle (the Google tool in question) will occasionally check for its own updates, though, if you are online at the time.
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 articles: