In this article we give the required steps to set up Android (which also supports Amazon Fire devices and store releases).
You must always use the specific version(s) advised on the Required SDKs FAQ and do not assume newer tools than we list there will be even better, as using newer SDK versions than GameMaker supports will quite possibly introduce build failures you could have easily avoided if you had followed this guide.
When following the screenshots for Android Studio below, ensure you're using the versions gained from that other FAQ, rather than just copying the values shown in the images here.
Overview / Before You Begin
After installing and running GameMaker 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. 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
For which version of Android Studio you need, see the Required SDKs FAQ - do not just get the newest release!
To start working with your Android/Amazon devices you will need to download and install Android Studio. Once you click the installer you will be asked to choose your components:
AVD support is entirely optional and accounts for roughly 1GB of the space required, so if you know you won't use emulators, then it's recommended you deselect this (We won't offer any Helpdesk ticket support for issues found when using emulators, only when running on real devices.)
Choose where you want it to install (the default is fine) and adding shortcuts is your personal preference.
Allow the installer to finish, and then Android Studio will start at the end of the installer.
Set Your SDK Installation Folder
If you are a new Android user, then the first screen you will see is this slightly scary one (you may have had a popup over the top of this one, asking if you wanted to send analytics off to Google - that's up to you):
Click Next on this first screen, and then you will be asked which components you want to install and where:
For that "Android SDK Location" value highlighted above, Google's path names can get very long and 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 in order to avoid errors when building your projects. For Mac and indeed Ubuntu IDE users, we would still recommend using a nice and memorable short path also, but it's less important that you do so.
- Windows IDE Users: We generally use "C:\AndroidSDK\" on our machines, but you can install the SDK onto a different drive if you wish (as shown in the screenshot).
- Mac and Ubuntu IDE Users: We use "~/AndroidSDK/" on our machines.
Note that you cannot just edit the path via the text field - you have to click the little folder button on the right and navigate through to your desired location (creating the folder, if required).
Once you have set the shorter SDK install path (if on a PC), click Next, accept the components list and the licences for those components, and click Finish.
Finally, once your chosen components are downloaded and installed, Android Studio will then shortly start up.
Finishing/Updating Your SDK Installation
When Android Studio appears it may have an update notification already waiting. Ignore this update prompt, as we will install the packages we need as we go through the guide.
Instead, click on the SDK Manager option to begin installing our tools:
This will open a window where you can select and install the SDK platforms that you require.
Before you go any further, tick both of the checkboxes for Hide Obsolete Packages and Show Package Details, as you do not need to download everything for an API to make it work with GameMaker and similarly later on we will want to pick specific tools versions, which may not be the newest versions listed.
On this first SDK Platforms tab, you typically 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.
As mentioned above, note that you only need the one "Android SDK Platform ..." bit for each API you wish to install, as shown here (using Tiramisu as an example):
After you have chosen your required SDK Platform, change to the SDK Tools tab and ensure you have added suitable tools there also.
You should find that Android Studio's installer has already gotten you the latest available non-Beta Android SDK Build Tools, and so your installation might look something like this:
Do not install Android beta/release candidate versions, like the one highlighted above.
Similarly, it will have already installed the current version of Android SDK Platform Tools:
You may also wish to remove the emulator tools as we suggested during the installer (if you did untick the AVD setting earlier, then this is wasted disk space...):
Next, if you want to do any Android YYC builds you also need to install a copy of the Android NDK. So, find the NDK (Side by side) group and again just pick the one entry in the list which matches what we say on the Required SDKs FAQ - for example, here we will download a NDK 25 version:
With that done, click the Apply button at the bottom of SDK Manager, confirm the changes, and then wait for the download process to finish.
You are now ready to go and set up GameMaker for Android development - you can close SDK Manager and indeed Android Studio, as these do not need to be running whilst you work in GameMaker.
Note that (apart from the NDK install) if you did not install everything you require in SDK Manager, whenever you next attempt an Android build inside GameMaker, 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 GameMaker 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
Set Up GameMaker's Preferences
When you now return to GameMaker, you need to set up the Platform Settings sections in Preferences:
Android SDK Location
Type in or select wherever you installed your SDK within Android Studio.
Assuming you did use the values we recommended earlier as your SDK installation path, this would mean something like:
- Windows: C:\AndroidSDK\
- macOS: /Users/[your macOS username]/AndroidSDK/
If you chose a different install location earlier and now want to change this so yours matches our recommendations, or you just need a reminder, you can do this back on the SDK Manager screen in Android Studio.
Android NDK Location
Android Studio always installs your NDK into a subfolder of the SDK install location, so use the file-picker button to find this folder now.
Assuming you did use the values we recommended, this would mean something like:
- Windows: C:\AndroidSDK\ndk\[version number]\
- macOS: /Users/[your macOS username]/AndroidSDK/ndk/[version number]/
Java JDK Location
Android Studio comes with its own version of OpenJDK, which is the only version of JDK Google's build tools actually supports, so use the file-picker button to find this folder now.
Again, assuming you did use the default paths Android Studio's installer recommended earlier, you will get your JDK installed to:
- Windows: C:\Program Files\Android\Android Studio\jre
- macOS: /Applications/Android Studio.app/Contents/jre/jdk/Contents/Home
Electric Eel Users: Electric Eel onwards changed the "jre" folder to be called "jbr", so if you're using Electric Eel type in "jbr" for this path instead of what we show above. Also if you have an existing "jre" folder because you installed Electric Eel over an older Android Studio install AND when installing Android Studio you had left its install paths as the default values it suggested, then you must delete that "jre" folder (not just the things inside - the whole folder!) otherwise Electric Eel will fail to find your Java executable when you attempt to do any builds inside GameMaker later on.
You do not need to install Oracle's JDK separately, so please don't grab the latest version of Oracle Java "just because". Also, Oracle changed their licence for Java a few years ago, which means you may legally need to pay them for any commercial app-development usage, so it's best to avoid that and stick with Google's installation...
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, rather than generating separate keystores for each project.
When creating a new keystore file, you are required to give the following details:
- File Name - Populated by GameMaker 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 you want to use 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 - This needs to be the same password as the one above, as this is what Google's tools require.
All other fields are optional and are not used inside GameMaker, but if you wish to fill them in:
- Common Name - this would normally be your own full name or some other identifier for you
- 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 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 ever "upgrade" your keystore using external tools.
You can now Apply/OK and you're done.
Importing an Existing Keystore
If you have an existing Keystore file, then simply point GameMaker to the file and fill in the details in the required list above exactly as they were when you first generated it.
Do not click the Generate Keystore button this time, 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. GameMaker 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
Inside the Target Manager 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.
For GameMaker 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 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 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 simply pick the newest API Level you have installed in the dropdown at the top of this section and that would be all you need to do here.
(Note that this dropdown will show all APIs up to and including the latest one you installed further up this guide, but of course you may only have one or two of these installed if you have followed this guide as directed, so do pick carefully.)
Should you need to customise any of the other fields, 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 then 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 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!
Amazon Fire Support
If you wish to target Amazon Fire devices 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:
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:
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 article: