In this article, we give the required steps to get the iOS platform up and running.
Please be aware that the iOS export is 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.
Set Up Your Mac For iOS Development
Even though this FAQ is for iOS, the first thing to do is to ensure that your Mac meets GameMaker's system requirements and you have followed the macOS development setup guide 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.
Enable Developer Mode On Your iOS Device
As of iOS 16 you will now find inside Settings > Privacy And Security and way down at the bottom there is a new 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.
Older versions of iOS do not have this setting.
Regardless of which iOS version you are using, 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 builds will always fail to deploy to the phone at the end of the GameMaker build process.
Detect Your iOS Devices Inside GameMaker
In GameMaker, go to Targets Manager and select iOS in the Platform column. Then you can see that the Devices column has a small "pencil" button beside it. Clicking this will open up the Device Manager, where you will add the iOS devices that can be targeted when testing your game projects:
Before continuing, you should ensure that any iOS devices you want to add are connected via cable to your Mac, so that they can be correctly discovered on the next screen.
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 the Device Manager with all the available iOS devices found by Xcode on that machine. Something like the following:
Once 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).
If no devices are found, but a connection test to the Mac itself is still successful (use the macOS section of Device Manager), then this 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 button.
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 build to test your project, 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.
GameMaker Preferences For iOS
With the testing devices now setup, you need to open the GameMaker Preferences (from the File menu at the top of the IDE) and under Platform Settings > iOS you need to specify your Team Identifier:
NOTE: Help on finding your Team ID is in this section of the macOS setup guide.
The default macOS Install Path value should be fine, but you can change if required.
The other option you have here is Suppress build and run. Enabling this will change GameMaker's build process to simply generate your Xcode project and then open this on your Mac. In this way, you can then continue working on your project in Xcode itself - this method 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. In order to then actually get your game onto your testing device, you will need to actually build the project inside Xcode.
Testing Your Project
Every game has a bundle name, which is a "reverse URL format" string like GameMaker's default value "com.company.game". However, before you can build and test your game you need to generate your own app's bundle name and set this in GameMaker's Game Options, as Xcode needs to be told which certificate and provisioning profile are to be used when building this project and deploying it to a testing device.
You create this by going to the App Store Connect pages and creating an App ID listing for your game, then adding in the name you want to use there. Whilst you are on your Apple Developer portal you can go on to create your development certificates and provisioning profile manually for this app if you wish, or you can let Xcode do this for you later on.
Either way, once you have created your own bundle name, add it into GameMaker by overwriting "com.company.game", as shown below:
As mentioned above already, to target iOS you use the Target Manager located in the top-right of the main GameMaker window. You can see that there are two output options:
- VM - This will build your game using interpreted code.
- YYC - This will build you game using compiled native code.
The VM option will build your game and use interpreted code within a pre-built 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 is completely custom to your own game's code and gives a performance boost compared to VM (especially with logic-heavy games), but large projects can take some time to compile.
Once you have chosen your output package and the device to test with, you can now run the game and the first time you compile it, Xcode should generate (or retrieve) the required Provisioning Profile for the project.
In Xcode on your Mac, your project should open and the initial page look something like the image above.
If all has gone correctly your project should now run on the test device or simulator - although, of course, if you have enabled "Suppress build and run" in your iOS Preferences then you need to click Xcode's "play" button to actually build the project...
NOTE: If you're having issues with missing provisioning profiles during your initial builds, try enabling "Suppress build and run" in GameMaker's iOS Preferences and then running the build directly in Xcode. Once your profile has been generated and you have managed to run your game once, you will be able to un-tick the suppress option again in GameMaker.
Note that you can also test your game using the "Debug" button on the menubar. When clicked, this will always run a VM version of the game (there is no YYC debugger) and load the debugger UI inside GameMaker at the same time. The debugger then permits you to see in detail how your game is performing, as well as set breakpoints and use these to check for issues or eliminate bugs. For more information about the debugger and what you can do with it, see the manual. Be aware that running the debugger may require some extra permissions from the OS in terms of allowing firewall access, etc.
Ready To Publish?
When your game is finished and ready to distribute through the App Store, you'll want to create a final compiled package and upload it. To find out more about this process, please see the following article: