GameMaker Studio 2 Mobile comes with several export platforms: Android, iOS, and tvOS.
In this article we give the required steps to set up Android (which also supports Amazon Fire devices and store releases).
Note that whenever possible you should stick to the specific versions advised in the Required SDKs FAQ, as newer SDK versions than we state there are likely to be unsupported - Google do update the SDK/NDK pretty frequently, so be careful when updating.
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 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...
Install Android Studio
To start working with your Android/Amazon devices you will need to download and install Android Studio. Just get the latest version unless the Required SDKs FAQ explicitly said there was an issue.
- 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.
- Similarly, the obsolete "NDK Bundle" package Google used to offer is no longer valid - you need to use the "side-by-side" install type.
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 Helpdesk ticket support for bugs found when testing games on emulators - 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, Android Studio will then shortly start up.
Install The Android SDK Tools You Require
On the Splash Screen, click to the menu labelled Configure and in the drop-down menu select 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.
We recommend that you always tick Hide Obsolete Packages and Show Package Details, as you do not need to download everything for an API to make it work with GMS2 - you only need the "Android SDK platform" bit for each API you wish to install, as shown here:
(Our screenshot shows we installed 3 different APIs, however you should only install more than one if you knowingly require multiple APIs.)
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 then need to click on the SDK Tools tab and install the remaining tools you require.
Start by selecting/installing these two and then tick the Show Package Details.
Now you need to ensure you have the newest matching Android SDK Build Tools for each API you installed on the previous screen. Expand the group at the top of the list and then tick the ones you need. So in our case, because we had 3 APIs installed this looks like:
But again, you probably only need one.
And finally if you want to do any Android YYC builds you also need to install a copy of the Android NDK. So expand that group and again just pick the one entry in the list which matches what we say on the Required SDKs FAQ:
One final reminder that you probably only need one.
Note that (apart from the NDK install) if you do not install everything you require on this screen, whenever you attempt an Android build inside GMS2 the Android's own tools will try to "repair your install" by downloading the missing bits during the build process. However, we would not suggest you rely on this, and it may not be suitable for your antivirus/firewall setup also.
Similarly, be aware by default Gradle will assume/require an internet connection and will perform an update check and download any required components you do not have installed at the start of each GMS2 project build. We would recommend you leave this enabled, but if required you can disable this within Android Studio (of course, if you start seeing projects fail to build, before you contact us you should perform an update of Gradle and download any missing components manually and confirm if this fixes your issue): https://developer.android.com/studio/intro/studio-config#offline
With that done, you are likely now ready to go and set up your project in GameMaker Studio 2.
Amazon Fire 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:
Set Up GMS2's Preferences
When you now return to GameMaker Studio 2, you need to set up the Platform Settings sections in Preferences:
Android NDK Location
Android Studio will always install your NDK into a subfolder of the SDK install location you set earlier. Nowadays, you must choose the "NDK side-by-side" section like we showed above (the old "NDK Bundle" at the bottom of that screen is hidden and marked as obsolete even though Google do currently maintain it to an extent).
Assuming you did use the values we recommended earlier as your SDK installation path you will get your NDK installed to something like:
- Windows: C:\AndroidSDK\ndk\20.0.5594570\
- macOS: /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 the SDK Manager screen in Android Studio.
Java JDK Location
Android Studio comes with its own version of OpenJDK 8, 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 Oracle Java just because. (Google recommend you use the copy they ship anyway, but also Oracle changed their 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...)
Again, assuming you did use the values we recommended earlier as your SDK installation path you will get your JDK installed to:
- Windows: C:\Program Files\Android Studio\jre
- macOS: /Applications/Android Studio.app/Contents/jre/jdk/Contents/Home
Android SDK Location
Select wherever you installed your SDK within Android Studio.
Assuming you did use the values we recommended earlier as your SDK installation path you will get your SDK installed to something like:
- Windows: C:\AndroidSDK\
- macOS: /Users/[your macOS username]/AndroidSDK/
Generate a Keystore File
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!
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.
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.
- Alias Password - Which can differ from the password above if you wish, but must be set also.
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 ignore any warnings about the keystore being in an old format, and please do not "upgrade" your keystore using external tools. GMS2 will support the newer keystore format in a later release, but this is not in any way mandatory with Google at this time (Dec 2020).
You can now Apply/OK and you're done.
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.
Set Up Your 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!":
Set Up Your Game Options
Unlike some other target platforms, before you can test your game you need to set some things in Game Options > Android, 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 have installed.
We would recommend that you do this by simply picking the API Level you want in the dropdown at the top of this section. (Note that this will show all APIs up to and including the latest one you installed further up this guide, but of course you may only have a very small number of these installed, so do pick carefully.)
Should you want to customise any of these, always refer to what you have actually installed in Android Studio and get the version numbers from there.
- The Build Tools value: if you chose API 30 or above you will see this is left blank because Google have changed this so you specify the Compile SDK value and the Android SDK works out the correct build tools you need. If you're compiling with API 30+, then any version you type here will be ignored by Google's tools. If you are targeting an Android API below 30 the a suitable build tools value will be set for you.
- 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 - e.g., if you try and use API 28 features in your game but only set Compile SDK to 26, then you will get a compilation error. Note that if you set a recent version you can usually still run the app on an older API device.
- 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.
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 open 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.
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 if you have followed the guide above correctly 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 whenever you do an Android build if you are online at the time.
If all has gone well, you should soon see your game project running on your target device!
Creating Your Store Packages
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: