Developing for Apple tvOS is a relatively simple affair, especially if you've already got experience using the sister platform, iOS. However it does present some unique features and challenges which should be taken into consideration when creating your or modifying your games to run on it. In this article we outline these and give you some tips on how to make the most of what the platform offers.
NOTE: If you haven't already gone through the process of setting up for tvOS, please see the following article first and then return to this one:
The tvOS "Siri Remote" Controller
An important feature of the Apple tvOS system is the remote control which has some quite sophisticated functionality. Basically is configured to respond as both a mouse/touch screen controller and a gamepad, and when creating your controller configurations in GameMaker you have to take this into account, as GameMaker will detect both of them simultaneously.
Essentially, the top part of the controller is a touch sensitive pad, and it will act as both a mouse and a gamepad controller. So, as the user moves their finger over the pad, it will update the mouse position on the screen and also generate gamepad axis values. This means that your game should be configured to use one or the other, but not both (with perhaps an option in-game to switch between them).
Apple have some strict rules and guidelines on how your game should interface with tvOS, so you should be sure to read through them and make sure that your games comply:
Apple also has a nice explanatory video about the Siri Remote which can be viewed here.
Using The Controller As A Mouse/Touch Screen
When a user moves their finger over the touch pad, the mouse x/y positions will be updated and if they swipe their finger across the pad then gesture events will also be generated. It is worth noting that the mouse position is not absolute on the pad, and - for example - swiping left then lifting the finger and swiping left again, will constantly subtract from the mouse x position. This means that the mouse cursor position can be off the screen and you may want to clamp the values to the screen bounds in your games. Also note that the pad can be clicked, which will generate mouse button pressed/down/released events.
Additional mouse buttons can be detected as MB Right from the Menu button and the MB Middle from the Play/Pause button on the controller:
It is important to note that if you are using the Menu button to detect a right mouse click, then it can only detect presses over one frame and it cannot be held down, as long presses of the MENU on tvOS return the application to the main menu, and this is handled by the tvOS operating system. So, only a pressed / released event can be detected for the RMB.
Also note that by default you cannot see the mouse cursor on the screen, but if you assign a mouse cursor to the current window, using window_set_cursor() this will show a cursor while the remote has any touch (it will fade away when not moving). You can also set the cursor to be visible automatically from the tvOS Game Options by checking the appropriate option:
Using The Controller As A Gamepad
If you wish to use the controller as a gamepad, then the touch pad will act as both an analog stick and a d-pad control, generating both inputs at the same time. This means that you should design your game around one or the other control schemes, but not both as you'll be getting duplicated input. The input received from the controller is as follows:
When using the controller as a gamepad, you can set whether the touch pad should be used in absolute mode or relative mode. In absolute mode, the center of the touch pad is considered the (0,0) position - ie: where the analog stick is at rest or where the center of the dpad would be - and movement around this position will generate input. When set to relative, then the (0,0) position will be considered as being wherever the initial touch on the pad is made and all input will be generated from that position, not the center of the pad.
To change this setting you can use the gamepad_set_option() function using the string "dpad_absolute" as the option_key, like this:
gamepad_set_option(gp_index, "dpad_absolute", true);
gamepad_set_option(gp_index, "dpad_absolute", false);
Note that there is also a corresponding get function that will take the same key string so you can see what the current setting is.
Remote Orientation
The tvOS controller can be used in both horizontal and vertical orientation, and should adjust automatically based on how the user is holding it. Input from a rotated remote will still be correct and will be compensated for without any extra code required. However it may be that you want to lock the remote into a horizontal position and not permit rotation, in which case you will need the above-mentioned gamepad_set_option() function with the option_key string "allow_rotation":
gamepad_set_option(gp_index, "allow_rotation", true);
gamepad_set_option(gp_index, "allow_rotation", false);
Note that there is also a corresponding get function that will take the same key string so you can see what the current setting is.
Multiple Controllers
It is possible for tvOS games to have multiple controllers connected at once, as users can turn their mobile Apple devices into "fake" Siri remote controls, and also have one or more Steel Series gamepads linked to the device. All connected devices will be detected by GameMaker as gamepads (even though they may also generate mouse input), and as such will trigger an Asynchronous System event when they are initially detected, or connected or removed during the game. This means that you should have some way of detecting these events - for example, a persistent controller object - and then update your game controls as required, or show messages to the user if no controller or an inadequate controller is being used.
Saving Data
If you've tried building a game for the tvOS platform already, you may have been shown the following message initially:
This message appears because the tvOS system only has a very limited amount of local storage for saving files (500k, max) and as such you are recommended to use some kind of cloud / online storage solution for any data that needs saved and loaded.