iOS GMS2
GameMaker supports iOS and releasing your games on Apple's App Store. Please be aware that the iOS export is fully compatible with iPadOS, as there are very few differences and none of them relevant to how GameMaker makes packages - Apple might change this in future, but for now both operating systems are covered by the one export option.
Target Manager (near the top-right corner of GameMaker) contains two export options for this platform:
-
VM- slower in-game performance, but quick to build each time and supports debugger builds -
YYC- faster in-game performance, especially with logic-heavy games, but much slower to build each time and does not allow debugger builds
Both targets require you to install XCode on a Mac and also set up certificates and profiles for your intended apps before you can continue. In this article we give the required steps to set everything up.
Important
Windows/Ubuntu IDE Users: As part of your developer agreement with Apple, you agreed to use a real, physical Mac to build and submit your apps. They have the right to terminate your Apple Developer account and pull any games from the store if they find you in breach. Accordingly, Helpdesk/bug support is only offered for a physical Mac and we will not offer advice to achieve running macOS in a virtual machine.
We also do not give any support/advice for any methods of avoiding the need for a paid Apple Developer account when developing for any Apple targets (even if you're only selling on Steam/Itch, etc., and not actually using the AppStore).
You should own a Mac computer and have a paid Apple Developer account before beginning any development for macOS/iOS/iPadOS/tvOS.
Even though this FAQ is for iOS, the first thing to do is to ensure that you have followed the macOS development setup guide at least as far down as the end of the section "Testing Your Projects".
This will ensure your Mac and your XCode installation are ready for use - and if you're using the Windows/Ubuntu IDE to do your actual development work, that your other computer can talk to the Mac and transfer your files over during builds.
You MUST follow that macOS guide linked a little above before continuing with the rest of this guide.
On your device, inside Settings > Privacy And Security and way down at the bottom there is an option to enable Developer Mode on your device. You must enable this, allow the device to restart, then confirm a second time that you want to enable developer mode - then the setting should stick. (iOS versions older than 16 do not have this setting and you can just do development work right away.)
Plug your iPhone into your Mac now and after a short delay you should see a "Trust this Mac?" dialog.
You MUST tap "Yes"/"Trust" otherwise your your phone may not be detectable by XCode and for sure builds will always fail to deploy to the phone at the end of the GameMaker build process.
Before continuing, you should ensure that all iOS devices you want to add are connected via cable to your Mac, so that they can be correctly discovered in a minute.
Inside Target Manager, click first on iOS in the left column. Next, there is a column marked Devices and this has a small pencil button at the top. Clicking this button opens Device Manager on its iOS page, where you can add your device(s) to deploy to when building your projects.
The dropdown in the top-left allows you to select from the different available macOS machines that have been added for building. Ensure this shows the correct Mac you wish to connect to. (If you're using the Mac IDE and you haven't added additional Mac build machines, then the dropdown will just show "Default".)
Once your Mac is selected, clicking Detect Devices will automatically populate Device Manager with all the available iOS devices found by XCode on that machine. After your devices have been discovered, they will be listed and you can choose to rename the Display Name of each device (this will only affect what is shown in Target Manager - it won't change anything inside XCode).
When that is setup, you can then click the Test Connection button, and if all is setup correctly it should say all was successful. Now ensure you click the Apply or OK button in Device Manager to save this new device.
If No Devices Are Found, Click Here
Do a connection test to the Mac itself and make sure this is still successful (use the macOS section of Device Manager). If this works, then the iOS detection problem is likely an issue where XCode has not been started on your Mac recently and so does not have its device list ready to send back to GameMaker. Simply open XCode on your Mac, wait a couple of minutes, and then try detecting devices again.
If a physical device connected to the Mac is still not being detected, check XCode > Window > Devices. Ensure that the device is shown here (if it isn't, then something is wrong with the physical connection to the Mac) and that there isn't a spinning circle icon next to the device. If there is a spinning circle, XCode is processing the device's contents and you will need to wait for this process to finish before your device will be sent back to GameMaker when you click the Detect Devices button.
For Info About Simulators, Click Here
Note that not only will any physical devices connected to the Mac be detected, but the different simulator devices in XCode will also be listed, and you can target them like you can any physical device. However, you need to be aware that simulators give different performance levels to real devices and don't show real-world issues, so you really, really, really should test with real devices before you prep all store submissions!
When targeting a simulated device, you likely want to launch the simulator first from Device Manager before starting the builds to test your projects inside GameMaker, as otherwise this will typically cause a lengthy build delay, which might in some cases cause the build to fail - especially if your Mac has low amounts of RAM.
You now need to set your values in Preferences > Platform Settings > iOS.
| Preference | What You Set It To |
|---|---|
| macOS Install Path | Where to save the packages on your Mac - the default value should be fine, but you can change if required |
| Default Team Identifier | Fill in your Team ID (which is the same as you set already on macOS's Preferences screen) |
| Suppress Build And Run | Change GameMaker's build process to generate your XCode project, open it in XCode on your Mac automatically, then stop so you can work in XCode itself before building the game when you're ready - this route is very useful if you use extensions and need to tweak your app's permissions or you have any other custom behaviours you want to enable in your projects |
Before you try running any projects, you need to change some values in Game Options > iOS from GameMaker's examples to the correct ones for your game and your Mac, as otherwise XCode will just say there are certificate/provisioning profile errors and the build will fail.
Note that there are many other Options available to you, which you can set later on as you require, but there are two key ones you should change right away and a third you should check now.
| Option | What You Set It To |
|---|---|
| Display Name | A friendly name for you game/app - note that you should be careful with formatting characters, emoji's, etc., as these could cause build errors |
| Bundle Name | If you have already set your app up on your Apple Developer profile and generated an App ID and signing certificate, etc., then enter the bundle name you created (alternatively, XCode will automate some of this for you if you supply your intended app name and then do a build, but we recommend using the website and controlling everything yourself) |
| Default Team Identifier | If you have already set this in Preferences, then just leave it blank here, but if you need to force an override (perhaps you're doing contract work on someone else's game), then set your ID here |
Note that if you're supplying an intended bundle name it has to be in a specific format, which is a "reverse URL format" string (like GameMaker's default value "com.company.game").
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 Run button on the menubar to compile the project.
The first time you compile a project, XCode should generate (or retrieve) the required Provisioning Profile for the project/device, so that the package can be deployed onto your testing device(s).
Issues With Missing Provisioning Profiles, Click Here
Try enabling "Suppress build and run" in GameMaker's iOS Preferences and then running the build directly in XCode. On your Mac, your project will open inside XCode and the "Signing" section its settings should look something like the image below:
Once your profile has been generated and you have managed to run your game once using XCode, you should be able to un-tick the suppress option again in GameMaker and do further builds just fine.
If all goes well, you should soon see your game project running on your iOS/iPadOS device! (Or, if you enabled the suppress Preference, XCode will open on your Mac and load the new project.)
Tip
If any build ever fails, please read ALL of the Output Window log to determine why the build failed - do not only look at the two lines at the end, as you're missing the important information which will help you fix the issue right away!
When testing VM builds, you can also launch your game in the debugger by using the Debug button on GameMaker's menubar. The debugger allows you to see in detail how your game is performing, as well as set breakpoints and watch variables which will allow you to check for bugs in your code. For more information on how to use the debugger, see the manual by pressing F1 inside GameMaker or opening the Help menu.
Note that YYC builds do not support GameMaker's debugger - if you try to debug when YYC is selected in Target Manager then this will instead show a dialog saying GameMaker will do a VM build this time.
Be aware that running the debugger may require some extra permissions from the OS in terms of allowing firewall access, etc.
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 Helpdesk article: