In this article we give the required steps to get the tvOS platform up and running. Note that we assume you already have an Apple Developer Account and a physical tvOS device, as both are required to be able to use this target platform.
NOTE: If you are new to Apple development and/or do not have a Developer Account with Apple, then the following external link will take you to a tutorial that explains everything related to getting your developer licence and creating certifcates, etc.: https://www.raywenderlich.com/127936/submit-an-app-part-1
It is important to note that, per your Apple Developer Agreement, we require you to have a real, physical Mac to create games for tvOS. We cannot support setting up a virtual machine or "hackintosh", as GameMaker Studio 2 uses Apple's own build tools in order to create game packages and testing releases, so we must follow their requirements.
To target tvOS from the IDE, you use the Target Manager, which is located in the top-right of the main GameMaker Studio 2 workspace:
For the tvOS target platform 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 special 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 (when using YYC the debugger will not start). The YYC target however, gives a much greater optimisation (and corresponding performance boost) especially with logic-heavy games, but large projects can take some time to compile.
On a PC, to compile your game using either the VM or YYC, you will first need to set up your Devices so that GameMaker Studio 2 can communicate with your macOS build machine and transfer files to build for tvOS.
To do this, you should first follow the guide linked below, as it explains how to set up your Mac to accept the files as well as how to set up Xcode and provisioning profiles etc...
Once you have set up the Mac side of things - and in the GameMaker Studio 2 target manager you have tested the macOS device and it shows as "connected" (make sure to APPLY the device before continuing) - you can then go to the tvOS section click the Detect Devices button:
The device manager will then connect to the Mac and retrieve all the available connected and simulated devices available. You can now skip the following sections of this article and continue from the section "Set Up Your tvOS Devices", unless you haven't already set up your Mac, in which case, you should read on.
NOTE: GameMaker Studio 2 requires a physical Mac computer to be able to test or compile your tvOS projects, and although you can run macOS in a virtual machine, this is not supported and you should own, or have access to, a Mac computer (and preferably) an tvOS device before targeting tvOS with your games.
Set Up macOS
This article is targeted at users with the macOS version High Sierra 10.13.4+. However, if you are using an older version of macOS then you may still be able to test and compile your games whilst Xcode remains supported on your OS, but some steps may be slightly different and you will only be able to test on tvOS versions that are compatible with the version of XCode that works with the macOS being used. We recommend that you have the latest macOS and the latest Xcode to build games for tvOS.
Before going any further, you will first need to download and install Xcode which is what GameMaker Studio 2 will use to build your projects. You can get the latest copy of Xcode here:
Set Up Xcode
Once you have downloaded and installed Xcode, you need to link it with your Apple Developer account so that it can use the required certificates to build your projects. For that you need to follow these steps:
- Go to Xcode > Preferences.
- At the top of the window, click the Accounts button.
- In the lower-left corner, click the Add button (+) .
- Choose Add Apple ID from the pop-up menu.
In the dialog that appears, enter your Apple Developer ID and password and then click Sign In. Your different certificates will now be retrieved. Select the Apple ID you just added and then on the right of the window click the Team Name and then the button Show Details. This should show all the different signing identity certificates options that you have:
You can close these windows now, and move on to setting up GameMaker Studio 2.
Set Up Your macOS Machine
(There is no need for most Mac IDE users to do this section, as GMS will create a Mac device for your local machine automatically. However, if you wish to target a different Mac as your build machine, then you should follow these steps also.)
If you are using GameMaker Studio 2 on a PC, you will first need to have the PC communicate with the Mac that you will be using to build the tvOS projects. This is done from the Device Manager where you will have an extra device category for macOS (if you have both the Desktop and Mobile licence, then you should simply set up the Desktop macOS export before setting up tvOS). Once you have correctly set up the macOS device, you will then be able to continue to set up the tvOS devices.
So, in the Device Manager you should select the macOS platform and then click the Add New Device button to create a new Device and fill out the details (below you can see an example of what information is expected):
The top field, Display Name is simply a name that you can give to the device so that it is easy to identify in the devices list. After filling that out you need to give the Host Name - the IP address or Device Name of the Mac machine on the network that is to host the game - and the User Name and Password of the Mac user account that will be used for testing/creating your game. Finally, supply the Install Folder destination on the Mac system where the GameMaker Studio 2 files should be stored (default should be fine but you can change if required).
NOTE: To get the IP address of the Mac system you simply have to go to System Preferences then click on the Network icon and you can see the IP address there. If you wish to use an actual name to address the Mac, then this will require you to enable the option on the Mac as part of the network connection settings.
With that done you can then click the Test Connection button, and if you have installed all the required packages and the macOS machine is visible over the network then it should say "Connection Successful!":
Set Up Your tvOS Devices
In GameMaker Studio 2 (either on Mac or PC), go to the Targets Window and you can see that there is a section marked Devices with a small "pencil" icon beside it:
Clicking this will open up the Device Manager where you will be adding your tvOS devices.
To set up the tvOS devices you should select the tvOS platform from the list on the left. Here you can configure the tvOS devices that can be targeted when testing your game project. 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 Device Manager for tvOS shows two initial preferences, with the first permitting you to select from the different available macOS machines that have been added for building. On Mac this will show "Default" which is the computer running GameMaker Studio 2 and on PC you should select the Mac that was set up in previous steps. The second option available is to Detect Devices. Clicking this will automatically populate the Device Manager with all the available tvOS devices - both physical and emulated - found on the target Mac:
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 the target manager).
If no devices are found, but the connection test was previously successful, 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, 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, when targeting a simulated device, you will likely want to launch the simulator first from the 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 RAM.
IMPORTANT! While you can test your apps on the simulator, Apple require you to have a physical tvOS device registered on their developer pages to be able to compile an executable. If none is defined then Xcode will show a signing error. If you do have a physical device then Xcode should detect it and take care of all signing issues for you.
GameMaker Studio 2 Preferences for tvOS
With the 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 > tvOS you need to specify your Team Identifier and the macOS Install Path (the default path should be fine, but you can change if required):
NOTE: You can find your Team ID from the "Membership" section of your Apple Developer Account.
The other options you have here are to Suppress build and run - we will explain more about this in the next section of this article, but for now, leave it unchecked (we can troubleshoot later if required) - as well as the Automatic response to tvOS persistent storage limitation warning option, which is simply an option to suppress a warning message about limited local storage when you compile your project. This warning is important, as your tvOS device only has 500k local storage, which is something you should be aware of when developing the target.
Testing Your Project
You are now ready to test your project. Regardless of whether you are using the VM or YYC output, you can simply click the "Play" button at the top of the IDE and the game will build and then be sent to Xcode. If you are building for a simulator (emulator) then we recommend that you start it first before pushing the build, which can be done from the tvOS Device Manager:
At this point, your game should have a bundle ID, which is a reverse URL fomat string like "com.yoyogames.mygame". You can create this in two ways, either by going to the App Store Connect pages and creating a listing for your game, or by letting Xcode generate the correct certificates for it. Either way will require you to supply a Bundle ID in the tvOS Game Options before testing:
It is important to note that if your project is for iOS and tvOS then you can supply the same bundle ID for both targets when compiling and then have a single App Store listing for both targets, rather than two listings, one for iOS and another for tvOS. This is explained in more detail in the article "tvOS: Compiling Your App", linked at the bottom of this page.
You can now test the game and the first time you run 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. If you have flagged "Suppress build and run" in the tvOS Preferences, then you will need to click Xcode's "play" button.
NOTE: If you're having issues with missing provisioning profiles during your builds, try enabling "suppress build and run" in the tvOS Preferences and then starting the build directly in Xcode after GMS2 generates your project and opens it on your Mac. 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 play your game using the "Debug" option at the top of the IDE. This will run the game and launch the debugger (this may require some extra permissions from the OS the first time you launch it, so accept any confirmation dialogues you may see). This module permits you to see in detail how your game is performing, as well as set breakpoints and check for issues or bugs. For more information, see the manual.
Before continuing we recommend that you take a look at the following companion article that outlines some of the features and challenges that developing for iOS represents:
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: