In order to utilize GameMaker: Studio’s iOS support you will need to first prepare GameMaker: Studio and your device for use, as well as fulfil a number of prerequisites from Apple. To make things easier we have outlined below all the necessary steps for you to take in this simple setup process.
What You Need To Get Started
Before beginning to work with the iOS module with GameMaker: Studio you must be a registered Apple developer and have all certificates and licenses up to date. For more information on becoming a registered Apple Developer and how to get the necessary certificates, please visit the Apple developer site here.
Please note that, per your Apple Developer Agreement, we require you to have a real, physical Mac as well as your PC. We cannot support setting up a virtual machine or "hackintosh". Our tools extend and use Apple's own in order to create game packages and testing releases, so we must follow their requirements. You will need a recent Mac with a copy of OS X 10.9 (Mavericks) or 10.10 (Yosemite) and Xcode 6.1.1 (6.2 if your iPhone/iPad uses iOS 8) - please see Apple's developer information for exactly which software versions are allowed to submit to the store at any given time (they change it *fairly* frequently...).
To be able to develop for an Apple product there are a number of things that you should have from Apple :
- Development Certificate - This is the certificate that Apple gives you permitting you to create for their products
- App ID - This is the profile for the game you're making: it's bundle name, details about devices you will support, etc.
- Development Certificate - This is required for signing the app package when outside of Apple services (during testing, really).
- Provisional Profile - This is what ties a product to your Development Certificate and devices, basically saying "The product I am making can only be tested on these devices". This gets installed onto your iDevices in order to allow Xcode to install and run apps as you're developing them.
- Distribution Certificate - This is required for signing your app package whenever you want to distribute it on the AppStore or other Apple service.
If you are already a registered developer it is worth noting before starting that nearly all iOS devices are compatible with GameMaker:Studio (even if they may not be supported by new versions of iOS or the AppStore) including :
- iPhone 4, 4S, 5, 5C & 5S
- iPad 1 and above
- iPod Touch 3rd Generation or higher
It also doesn't matter if you are testing on an iPhone or an iPad as all iOS project builds created by GameMaker:Studio are, as standard, universal apps. This means that they will run on both iPhone and iPad devices without problems. (You need to limit a project inside its Global Game Settings if you require it to be limited to only iPhone or only iPad.)
Syncing Your Mac and PC
For GameMaker: Studio to work with the iOS targets you will need your PC to connect with your Mac, which you can do with an ethernet cable or wirelessly (ethernet is recommended). Make sure both computers are turned on and connected to your LAN, then on the Mac, go to system preferences and click on sharing. Now turn file sharing ON, then go to Finder and see if there is anything found under SHARED. If not, you may have to do something similar on your PC, and then you will have to type in your PC's password to access all you PC's files on your Mac.
Now, on your PC, open GameMaker: Studio and Windows Explorer at the same time. In Explorer, go to NETWORK and you should see your Mac's name there. You need to take a note of it and then in GameMaker: Studio open the Preferences from the File Menu and go to the Mac OSX Tab. Now enter THAT name into Mac Host Name text box. In the other boxes you should have your normal Mac username and password. Now check that your connection is working, and move on.
Export An App for OSX
Now that you have your connection set up you may want to test exporting your game so you can play it on Mac, just to confirm that the network connection and file permissions are set up okay. Switch the target to Mac OSX and click on the 'create executable for target' button. If everything has gone as it should, your game should shortly be open and available for playing on your Mac. If not, then you should re-pass the above steps and make sure that the two computers are connected properly, as without this step you cannot continue.
You can find a more detailed article on setting up your Mac here: Develop And Distribute To Mac OSX
The Apple App Store Provisioning Certificates
For any type of app to be submitted to the Apple App Store you need to do the following:
- Get a developer certificate and download it to your Mac.
- Register your device (ipod, iphone,ipad) with the Apple App Store.
- Get an app ID - a unique "number" - for your app.
- Get both a Provisioning AND a Distribution profile for your app and download these.
All this can be achieved by logging into the Apple Developers pages here, and is explained in more detail below.
The Developer Certificate
For testing on iOS you will need a Developer Certificate and for creating your final game a Distribution Certificate.
If you're a solo developer or the first person in your team to set everything up, generate a Certificate Signing Request via the Keychain Access application (this can be found in the Applications > Utilities folder). Note that you only need one CSR per computer, so this file will be used for all your games, on both the Mac and iOS platforms. If you have previously created one for the Mac target module then there is no need to create another one and you can skip this step.
This will open the Certificate Assistant wizard, and in the menu for this application choose the default options. Now it's best to go to the Developer Site: https://developer.apple.com/ and sign into the developers account that you created earlier.
Once that is done, you should go to the Developer Center and here you make sure that your details are correct (click the Your Account link at the top of the page to make sure) then go back to the main page and click on section Certificates, Identifiers & Profiles. This will take you to the following page:
Register Your Device
The first thing to do here is click the button labelled "Devices". Clicking this button will take you to a page where you can see all the devices that you have registered as development devices, and at the top is a button marked with a "+". If you click that it will take you to the following page:
Here you can give your device a descriptive name and then add the UDID. You can get this by doing the following:
- Open Xcode on your Mac.
- Connect the device via USB to the Mac.
- In Xcode, click Window on the menubar, then Devices.
- Click on your device in the list in the top-left corner to be shown its details page.
- Copy the device Name and ID into the form on the website.
- Click on the Continue button to register the device.
With the device registered, you can now continue and register your App ID, and create your provisioning profile certificates.
Before you can do any testing of your game on iOS, you have to create an App ID for it. To set this up, in the Certificates, Identifiers & Profiles section of the Developer Dashboard, click the section marked "App IDs" (visible on the left) and you will be taken to a new screen that lists all of the currently defined App ID's (if this is your first game then it will be empty) . You should then click on the "+" at the top of the screen to register a new game, which requires you to input a few pieces of information:
App ID Description - the name of your game or app.
App ID Suffix - This is basically the identifying string for your app and it's subsequent certificates. If you are simply developing and testing, then you can create a "Wildcard" bundle ID which will permit you to use the same ID for multiple apps (very useful when developing multiple projects or simply for testing prototypes). If you are preparing to upload a finished game, then you should give an explicit bundle ID. Note that this bundle ID should be in reverse URL format, com.[User/Company Name].[AppName].
App Services - Select the optional services that you want the game is to use (these can also be edited at a later time).
With your device and app registered with Apple, you'll now need to make the provisioning profile certificates, which come in two types:
- Development Provisioning Profile
- Production Provisioning profile
The first one for development and necessary for creating test packages or finished games you do not wish to sell on the AppStore, while the other is for distribution and is essential if you wish to market your game through the AppStore later.
Creating The Development Certificate
To create the development certificate, click on the Development link in the Certificates section of the dashboard.
- Click the "+" at the top of the page, then select "iOS Developement" and continue.
- You will then be prompted to select a developer certificate to use and after that a device for testing on (you should have set this up previously).
- You will be now be asked to give your new development profile a name, and will be shown a brief summary of the choices you have made.
- If you are happy that everything is correct, click the Generate button
NOTE: It is recommended that you use some form of suffix for your common name to indicate that this is a test app, as the name you place here cannot be re-used. So, for example, if your game is called "SpaceOut", the common name here would be "SpaceOut Ad_hoc", or "SpaceOut Test". If you simply use "SpaceOut" then when you create the final Production certificate, you will not be able to use that name.
As you can see, the development certificate has been created and you can now download it onto your Mac for installing, or install it through Xcode (which is explained below).
Creating The Distribution Certificate
As with the Development certificate, the Distribution certificate requires that you give a common name and an App Id and that you link the game to an Apple Developer Certificate. This will need to be downloaded and installed on your Mac before you can create a game to be distributed to the App Store.
Whilst you can manually install the certificates you have made (ie: downloading them to your Mac and then double-clicking), you should nowadays install them through Xcode. If you go to the Xcode Preferences, then Accounts and select the "View Details" option, you'll be presented with a window showing all the certificates linked to the chosen account.
You can click on the "refresh" icon in the bottom left corner of the window and have Xcode fetch the certificates and profiles you have created from the Apple Developers site and install them automatically.
Click your development certificate (IPhone Developer:' [your name] (your ID)) to expose the key tied to it, then right-click on the key and choose "Get Info". Switch to the Access Control tab and change from "Confirm..." to "Allow all...". This will stop several code signing errors which would break the build process (more on this later).
GameMaker: Studio Setup
Now you have all your certificates in order and you have installed Xcode correctly, you can Install GameMaker: Studio (if you haven't already) and do the following :
- Launch GameMaker: Studio
- Enter your License Key
- Create a new Project
- Select File > Preferences > Mac OS X
The preferences tab for Mac OS looks like this:
The top field, Mac Host Name is the name (or the IP) of the Mac on your network that is to host the game, and the Mac User Name and Mac Password sections should contain the details of the account that will be used for testing/creating your Mac OS app. Finally, you can specify the Mac Install Directory which is where GameMaker: Studio will create the necessary files for the build process. Please note that you need to enable Remote Login for that user on the Mac for GameMaker: Studio to communicate properly, as mentioned earlier.
Global Game Settings
With that done you should then open up the Global Game Settings for your game and make sure that the General details are correct, ie: the Bundle ID matches that which you created on the store, the icons are correct, and you have filtered the orientation options and target devices.
You will also need to make sure you have selected the correct Provisioning Profile and Development certificate from the provisioning tab:
You can click the "Refresh From Mac" button if no profiles are listed to have GameMaker: Studio pull the available ones from your Mac. Note that GameMaker: Studio only needs the Development certificate, even when creating a final app as you will be asked by Xcode to provide the correct Distribution Certificate when your app is built and ready for upload to the App Store.
The Web Server
If you haven't already configured GM's web server, then you should do this now, since GameMaker: Studio can use this to "push" files to your device if USB connection between your iDevice and Mac is currently not possible. If you are not sure how to do this, please see the article Setup GameMaker Studios Micro Web Server. Please note that we would recommend, however, that you always have your iDevice plugged into your Mac during deployment.
Running A Game From GameMaker:Studio On Your iOS Device
Even if you wish to use the web server and a wifi connection to your iDevice, the first time you test something on your iDevice you will have to make sure that it is connected to your Mac using the USB cable, as GameMaker: Studio will need to place the YoYo Runner onto it. After this initial "push" however you are free to use Wifi to connect to your device, as long as the Web Server settings are correct (see above).
- Select the platform's drop-down from the toolbar inside GM and select iOS as your target
- Click the Green play button to compile your game. Once compiled, it will be "pushed" to your device via the USB cable and the game should start automatically. Please note with current Xcode tools if your iDevice is iOS 7 or lower, it will install the package, but likely not launch it and you will get a "compiler error" about failing to launch the game. This is fine - simply tap the game icon to launch the game manually.
Please be aware when the YoYo Runner is started using Wifi we will attempt to determine your PC's IP address on your network and the web server port in use and pre-populate the Runner with these values, but (depending on your network setup) you may be presented with a connection progress bar screen where you must do the following :
- Select Settings
- Select IP and enter your PC's IP (If you are not sure of your local IP address, you can find it easily by following the instructions found here)
- Select Port and ensure this matches the port number you entered within GameMaker: Studio preferences for your web server (the default 51268 normally doesn't need changing)
This section covers some of the known issues that you may have when testing or compiling your game for iOS.
"Instruments Trace Error : Failed to start trace" (Xcode 5) or anything to do with "Tests" failing (Xcode 6)
Please note that for several GM releases and anything built with Xcode 6 Instruments is not used any more, so if you are getting Instruments errors this is because you're using either an old GM or an old Xcode (or both). You should update your copies of both as soon as possible.
Any Instruments or Tests errors that you get when compiling means that your build was actually a success, as otherwise Xcode wouldn't be trying to install your built package. You should find that your app has been installed, but it simply isn't running on the device when you look at it. if you tap the app icon, it should run as expected.
This error is caused by the incorrect profile certificates being used when testing or building your game or the provisioning profile not already being installed on the device please note that with Xcode 6.1.1+ you should also get a plaintext message telling you it's the provisioning profile which is missing, if this is the error).
At all times in Gamemaker: Studio you should be using your Development profile and certificates, as you will sign the game using the Distribution certificates in Xcode when uploading your game to the App Store. So, to resolve this, simply open up the Global Game Settings and in the iOS > Provisioning tab make sure that you are only using the developer certificates.
If this does not resolve the issue, then you may need to check the name of your app, both in the Global Game Settings and also as it is saved, to make sure it has no non-standard characters and no spaces. For example, if your game is called "hello world.gmx" then you should re-save it as "hello_world.gmx" and modify all the path and internal names to match.