GameMaker Studio 2 Mobile includes the tvOS export platform, so in this article we give the required steps to get the platform up and running.
This FAQ assumes you already have an Apple Developer account (you will need one), but if you do not have a Developer Account with Apple, then the following link will take you to a tutorial that explains everything related to getting your developer licence and creating certificates, etc: https://www.raywenderlich.com/127936/submit-an-app-part-1
Windows IDE Users: As part of your developer agreement with Apple, you agreed to use a real, physical Mac to build and submit your tvOS 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, GameMaker Studio 2 support is only offered for a physical Mac and we will not offer support to achieve running macOS in a virtual machine. You should own a Mac computer as well as your PC before beginning any development for macOS/iOS/iPadOS/tvOS.
Set Up Your Mac For Development
Even though this FAQ is for tvOS, the first thing to do is to ensure that your Mac meets GMS2's system requirements and you have followed the macOS development setup guide (as far down as the section Testing Your Projects).
This will ensure your Mac and your Xcode installation are ready for use and that your PC can talk to the Mac and transfer your files over (if you're using the Windows IDE to do your actual development work).
You will need to have done the above before continuing with this guide.
If Your Mac Does Not Support The Required SDKs
If you are using an older version of macOS then you may still be able to test and compile your games using older versions of Xcode, but some steps may be slightly different and you will only be able to test on tvOS versions that are compatible with your version of Xcode.
Be aware you would also not be able to submit your app to the App Store, so you would only be able to do local testing.
Please note that our Helpdesk and bug-reporting services cannot support you in this situation.
Set Up Your tvOS Devices
In GameMaker Studio 2, go to Targets Manager and select tvOS 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 tvOS devices that can be targeted when testing your game projects:
Before continuing, you should ensure that any tvOS devices you own are connected via cable or via Wifi to your Mac so that they can be correctly discovered.
NOTE: For more information on pairing your Mac and tvOS device, see here.
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 tvOS 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 GMS2. 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 GMS2 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.
IMPORTANT! While you can test your apps in a simulator Apple require you to have a physical tvOS device registered on your developer portal to be able to compile any executables. If no physical tvOS is defined on your profile, then Xcode will show a signing error.
GameMaker Studio 2 Preferences for tvOS
With the testing devices now setup, you need to open the GameMaker Studio 2 Preferences (from the File menu at the top of the IDE) and under Platform Settings > iOS you need to specify your Team Identifier:
NOTE: You can find your Team ID from the "Membership" section of your Apple Developer Account.
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 GMS2'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.
The Automatic response to tvOS persistent storage limitation warning option is simply whether to suppress a warning message about limited local storage when you compile your projects. This warning is important, as your tvOS device only has 500kb of local storage, which is something you should be aware of when developing for this operating system.
Testing Your Project
Every game has a bundle name, which is a "reverse URL format" string like GMS2'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 GMS2'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 GMS2 by overwriting "com.company.game", as shown below:
As mentioned above already, to target tvOS you use the Target Manager located in the top-right of the main GameMaker Studio 2 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 tvOS 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 GMS2's tvOS 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 GMS2.
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 GMS2 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.
Platform-Specific Features To Be Aware Of
Before continuing development of your game, we recommend that you take a look at the following companion article, which outlines some of the features and challenges that developing for tvOS represents:
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: