Recently, Google has begun pushing its App Bundle system for creating Android games and distributing them through Google Play (see here for more information on App Bundles). This means that uploading a single APK to the Play Store may result in you getting warnings like the following:
While this warning shouldn't stop you uploading and publishing an APK, it appears that some in some regions an app bundle submission is now the obligatory upload for publishing, making it imperative that users switch to this system. Please be aware Google's docs say if you previously had to use APK Expansion because your game is large, then this will very likely be mandatory for you.
However, versions of GameMaker Studio 2 up to and including 2.2.3 won't create an App Bundle automatically and instead you need to create one yourself after making your regular .apk file. This article explains how you can do this. (The 2.2.4 release will add this functionality directly into the IDE and so you will be able to choose if you want an .apk or an .aab file to be generated.)
NOTE: If your JDK version isn’t at least 1.80 you will need to upgrade to this version or higher before you will be able to complete this guide.
Please note that the guidance in this FAQ is not applicable to GM: S 1.4 in any way and only GMS2 is compliant with the current Google Play requirements, as 1.4 stopped being supported June 2018.
Paths to Be Aware Of
When following along with the steps below, because this guide covers two OSes when we say "Runtimes folder" we're referring to the following locations, which is what GMS2 will use by default:
- Windows - C:\ProgramData\GameMakerStudio2\cache\runtimes
- macOS - /Users/Shared/GameMakerStudio2/cache/runtimes
If you want to confirm these locations are correct before going any further, just copy and paste the path above into Explorer/Finder and navigate to it. As long as the runtimes folder opens, you're good to carry on.
Note: If you know that your school/company/security policy maps %ProgramData% or /Users/Shared/ to a custom location, then you will need to take this into account when following along with this guide.
Similarly, when we refer to "runtime version" we mean the specific version number of runtime you'd like to modify with this change (e.g., "runtime-22.214.171.1241" or "runtime-126.96.36.1996"). Be aware that if you need to swap back-and-forth with your runtimes, then you will need to apply this modification to all runtimes you want to use when building app bundles, as they do not share this information.
Modifying Your Android Runtime
The first thing that you will be required to do to build an App Bundle is to upgrade the version of gradle that is to be used during your build. For that, you need to open the build.gradle file, found at the following location:
[runtimes folder]\[runtime version]\android\runner\rootfiles\build.gradle
You can open and edit this file in any text editor. Remove everything currently in the file and replace it with everything in the following code block:
// Top-level build file where you can add configuration options common to all sub-projects/modules.
Save and close the build.gradle file.
Next, you need to edit the settings.gradle file in the same runtime directory as the above file. In this file, you simply need to add the following after what's already there, so it becomes the third line in the file:
rootProject.name = 'root'
Save and close the settings.gradle file.
The final file we have to edit is the gradle-wrapper.properties file, which can be found at:
[runtimes folder]\[runtime version]\android\runner\gradle\gradle\wrapper\gradle-wrapper.properties
Find the "distributionUrl" line in the file and change the version it's looking for from "gradle-3.1-bin.zip" to "gradle-5.1.1-all.zip", so you end up with the following:
Save and close the gradle-wrapper.properties file.
You will then need to browse to [runtimes folder]\[runtime version]\android\runner\gradle\ and run the executable file "gradlew.bat" (Windows) or "gradlew" (macOS) by simply double-clicking it. You should see cmd/Terminal opens and you get the following download progress bar plus a few commands at the end:
This will download, unzip, and perform the gradle install, then the window will close itself on Windows / can be closed on macOS.
Note, that this application will require internet access, so you might get a firewall prompt for the batch file and/or for Java, which will be launched during the batch file running its commands. Ensure you allow this traffic!
Make Your APK
You must now clean the Android build cache, which you do using the "broom" icon at the top of the GameMaker Studio 2 IDE. If this fails for any reason, then you may need to browse to the cache directory and manually delete the files there.
Now, compile your APK for the Android target inside GMS2 as normal. Note that we want to see the build succeeded and also reference that you were using gradle 5.1.1:
Deprecated Gradle features were used in this build, making it incompatible with Gradle 6.0.
Use '--warning-mode all' to show the individual deprecation warnings.
BUILD SUCCESSFUL in 1m 37s
But the overall runtime process needs to fail. E.g.:
System.IO.FileNotFoundException: Could not find file 'W:/YYGTest_DF66C898\Android\default\com.yoyogames.yygtest\build\outputs\apk\com.yoyogames.yygtest-release.apk'.
File name: 'W:/YYGTest_DF66C898\Android\default\com.yoyogames.yygtest\build\outputs\apk\com.yoyogames.yygtest-release.apk'
at System.IO.__Error.WinIOError(Int32 errorCode, String maybeFullPath)
at System.IO.File.InternalCopy(String sourceFileName, String destFileName, Boolean overwrite, Boolean checkHost)
at System.IO.File.Copy(String sourceFileName, String destFileName, Boolean overwrite)
at Igor.AndroidUtils.(YYDictionary`2 , String , Boolean , String )
FAILED: Package Program Complete
If you don't get this (i.e., your whole build process worked), then you have not applied the runtime changes and installed the new gradle files correctly, and so you would have errors when trying to generate the bundle file later on in this guide.
IMPORTANT! After you have made these changes the updated version of gradle will output all *.APK files to a different directory when building with this runtime, meaning that GMS2 will always "fail" when creating an APK. As shown above, it does actually build correctly - it is just that the APK file will be created in a different directory:
- %appdata%\GameMakerStudio2\Cache\GMS2CACHE\[project name]\Android\default\[package name]\build\outputs\apk\release
- ~/.config/GameMakerStudio2/Cache/GMS2CACHE/[project name]/Android/default/[package name]/build/outputs/apk/release
You can install it to your device from the command line by typing "adb install " (note the extra space) and then dropping the apk onto the cmd/Terminal window to append its filepath. Press Enter and your .apk should be installed if your device is connected okay.
Check Your System Variables Are Correct
You need to ensure that you have valid JAVA_HOME and ANDROID_HOME environment variables set in Windows/macOS and that these point to the same directories as you have set in the GameMaker Studio 2 preferences. E.g.:
or on macOS:
Open System Properties by opening Control Panel > System > "Advanced system settings" in the list on the left. Then click the Advanced tab on the dialog which opens.
On the Advanced tab, click the New button for the top panel and add your two system variables, so you end up with something like the following:
Now you need to ensure your Android tools folders are part of the PATH variable set for the system, which is done in the second panel of Environment Variables:
Of course, you need to the change the values shown here to match your actual Android SDK installation folder as set in GMS2. Also, by default, Android Studio will install your SDK a few folders deep on your hard drive, so your path value might be a lot longer than is shown here.
Once you are happy the three variables are set correctly, OK the variables window and the System Properties one, as it's not until you do this that your settings are applied (Windows 7 users you very likely have to reboot your PC before the settings are applied!).
Please note GMS2 requires Bash, so this guide will only relate to that. If you are using a different shell you will need to adjust the paths shown accordingly.
Open the file ~/.bash_profile in Text Edit (or similar) and confirm that there are values in here for JAVA_HOME, ANDROID_HOME, and PATH and that these match what's set in GMS2. E.g.:
Once you are happy the three variables are set correctly, save and close the text file. If you don't have this file already, create it and add the three variables using your own installation paths in place of ours above!
If you had to edit this file at all, please close all Terminal sessions, otherwise you won't see your updated values.
Building Your App Bundle
NOTE: Again, if your JDK version isn’t at least 1.80 you will need to upgrade to this version or higher before you will be able to complete this section.
The final steps require you to change directory from the command prompt to the build cache directory, normally located here:
- %appdata%\GameMakerStudio2\Cache\GMS2CACHE\[project name]\Android\default
- ~/.config/GameMakerStudio2/Cache/GMS2CACHE/[project name]/Android/default/
It's easiest if you find the correct folder in Explorer/Finder first and copy the address you need.
Copy that address.
Press Windows key + R, type cmd and hit Enter.
Important: If your project contains extensions, then you might have to use subst before your bundle will build successfully (the Google Play Services extension will definitely require this). In your cmd window type "subst Z:\ " (note the extra space) and then right-click and paste your folder path in. Then press Enter. If this complains Z is already in use by GMS2, then just pick a different drive letter and try again. Once you have successfully mapped the drive, simply use this drive letter in the "cd " command in the Both section below (e.g., "cd Z:"), rather than pasting in your folder path again.
Now open Terminal
Type "cd " (note the space at the end), and then paste the address via the right-click context menu (Ctrl+V usually doesn't work on older versions of Windows) and press Enter.
You should end up "inside" the folder, as shown below:
From here, you need to run the gradlew file from the Runtime Cache directory with the following command and parameters:
[runtimes folder]\[runtime version]\android\runner\gradle\gradlew build bundleRelease -x lint
If you get the following error at this point it's because you did not set the path variables correctly in the previous section of this guide (you need to close this cmd window and then go fix your paths - if you don't close the cmd window, it won't see any changes):
And if you have the following error it's because you did not apply the runtime configuration changes correctly (you need to close this cmd window and then restart this guide, ensuring GMS2 makes an apk but then fails the overall process, as mentioned earlier):
And if you are on Windows and you get an errors which blames a file in one of your extensions, then you need to go back up to the Windows section above and map your cache folder to a drive letter using subst, then try the bundle build again from inside that drive letter.
You want to see the following:
This will have generated your app bundle in:
- %appdata%\GameMakerStudio2\Cache\GMS2CACHE\[project name]\Android\default\[package name]\build\outputs\bundle\release
- ~/.config/GameMakerStudio2/Cache/GMS2CACHE/[project name]/Android/default/[package name]/build/outputs/bundle/release
The .aab App Bundle file found in that folder can then be uploaded to the Google Play store.
How To Build More Packages
All of the setup changes we have made so far only need to be done once (unless you reinstall the runtime for some reason), so you don't need to repeat the entire guide each time you want to make a bundle file.
You simply need to ensure your build cache is cleaned and then make your .apk inside GMS2, confirm that it "failed", then repeat only the "Building Your App Bundle" section.
How To Revert The Change
If you need to revert your runtime for whatever reason, it's quick and easy to simply ensure GMS2 is closed, delete the entire runtime folder in Explorer/Finder, and then allow GMS2 to re-download the runtime the next time you start the IDE.
Alternatively, you can work through the guide above and reset the values by hand.