Building games for Apple TV

Apple TV platform builds on foundation of iOS platform and at the same time brings new paradagims and challenges for game developers. While deploying already pre-existent mobile game on tvOS is one click away, game content often needs adapted to play nicely with new input controls or the fact that it will be played on big screen TV. This manual page is primarely aimed at helping transitioning from iOS to tvOS.

Prerequisites

• You need 4th generation Apple TV device (don’t forget to get USB C <-> USB 3.0 cable, which is not included with consumer package).
• You need Xcode 7.1 or later.
• Setup provisioning for this device the same way as for iOS devices. It’s recommended to create empty tvOS app with Xcode to test if provisioning works correctly.

Things to know before starting

• Many of iOS plugins won’t be compatible with Apple TV, because it supports only subset of iOS frameworks. We recommend you to create separate branch of your game and do porting to Apple TV there. Don’t forget to reach plugin providers and ask them to update plugins.
• If your game takes more than 200 MB on disk, you should break it into smaller parts and use On Demand Resources. For On Demand Resources support in Unity please refer to section below. Note that Bitcode is included with tvOS builds, which will add ~130 MB to your executables. This added size is not accounted for distribution size, as it will be stripped by App Store servers. You can estimate Bitcode size by analyzing LLVM sections in your executable with otool -l.

Implementing Input

Apple TV Remote (Siri Remote) serves as multipurpose input device working both as traditional menu navigation controller, game controller, gyro and acceleration sensor and as touch gesture device. TV Remote input is minimally processed by Unity and mostly routed to corresponding Unity APIs. Usually each game needs slight adjustment of input scheme to leverage unique Apple TV Remote input features. Some games would benefit treating it as traditional game controller with one analog axis and extra action button, while others would benefit using accelerometer for steering purposes. It’s recommended to experiment a bit with various schemes when porting game to tvOS. Here are technical details on how to access specific TV Remote features:

• If you haven’t yet added iOS Game Controller support to your game, you should check the dedicated MFi Game Controller page. Use the mappings written in this manual while setting up your custom action mappings in the Unity Editor Edit->Project Settings->Input.
• Apple TV Remote touch area is mapped to both Input.touches (Touch.type will be set to “Indirect” and will be ignored by Unity GUI) and usual Joystick Input API like Input.GetAxis(“Horizontal”);
• Remote acceleration and gyroscope are mapped accordingly to Input.acceleration and Input.gyro. Input.acceleration internally is derived from gyroscope API and might have some instabilities. Unfortunately there is no dedicated accelerometer API on tvOS SDK. Input.gyro.attitude is derived from gravity vector thus lacks rotation around axis parallel to gravity vector. The same applies for Input.gyro.rotationRate.
• Pause/Play button on remote is mapped to button “X” (which is then mapped to joystick button 15).
• Remote touch area click is mapped to button “A” (which is then mapped to joystick button 14).
• Menu button has special behavior on this device. Long push of it will invoke task switcher and you can’t override this behavior. Short clicks can be processed two ways:
  • a) returning to system home screen (if UnityEngine.Apple.TV.Remote.allowExitToHome is true)
  • b) letting your app respond to it’s clicks (mapped to button “Pause” / joystick button 0), when UnityEngine.Apple.TV.Remote.allowExitToHome is false. This the default behavior. Your app should switch between a) and b) basing on where player is in your game. If they are on the top menu then you should enable behavior a), if it is deep inside the game you should prefer
  • and invoke in game pause menu when this button is pressed.
• Apple TV remote is also generating Dpad UP/DOWN/LEFT/RIGHT button presses when you swipe to the edge of the remote. Check Unity Manual page for iOS Game Controllers to find the mappings. Apple TV remote operational modes can be controlled via dedicated API:
  • UnityEngine.Apple.TV.Remote.allowExitToHome
  • UnityEngine.Apple.TV.Remote.allowRemoteRotation
  • UnityEngine.Apple.TV.Remote.reportAbsoluteDpadValues
  • UnityEngine.Apple.TV.Remote.touchesEnabled
• Two more wireless MFi game controllers can be connected to Apple TV box, effectively turning it into game console. Your game may use them in the same way as iOS MFi controllers (as mentioned above), though your game should be still playbable with Apple TV Remote alone. Currently number of additional controller is limited to two and it’s docummented system limitation.

Warning: due to “Menu” button being reported as joystick button 0 when UnityEngine.Apple.TV.Remote.allowExitToHome is set to false, and default input manager binding “Submit” virtual button to the same joystick button 0, it will trigger actions on UI elements when pressing “Menu” button. To work around this issue, you need to remove or modify “Submit” virtual button bindings in input manager.

Setting up Unity GUI navigation via TV Remote

• Open Project Input settings in Unity Editor. Find first occurrence of “Submit” virtual input, expand it and change it’s “Alt Positive Button” to “joystick button 14”.
• Select EventSystem game object in your scene: In EventSystem component populate “First Selected” field with UI game object that should receive initial focus.
  • You might need to check “Force input module” flag in “Standalone Input Module” component.
  • If everything is done right you should be able to navigate your UI via keyboard while running in Editor or via TV Remote swipes and full stop click when running on device.

Note: TV Remote navigation won’t work while running in TV Simulator.

Adding Leaderboard resources to Xcode project

Game Center requires to provide custom visual resources for native leaderboard UI. Here are quick instructions how to set them up in Xcode:

• Select Images.xcassets in Xcode project
• Right-click under listed files, and from the menu pick Game Center->New AppleTV Leaderboard.
• Add your images there.
• Select Leaderboard and on the right pane pick edit view. Find there “Identifier” field and enter you leaderboard id there.
• If after these modifications your asset compilation starts to fail, try disabling “On Demand Resources” in Xcode “Build Settings”.

Implementing On Demand Resources support

tvOS has strict requirements how much disk space application can reserve. Main application installation bundle size should not exceed 200 MB. Though limits for additional downloadable content are much higher (up to 2GB for in-use assets and up to 20GB of total downloadable content). Apple recommends to use On Demand Resources for tvOS downloadable content, as it enables best disk space management strategies for tvOS. Unity supports ODR via Asset Bundles. ODR implementation guide could be found in our dedicated blogpost

Known limitations

• On screen keyboard is limited to single line entries.
• tvOS Simulator doesn’t emulate TV Remote as Game Controller, thus making it’s input not accessible to games.