This manual page is primarily aimed at helping developers transition from iOSApple’s mobile operating system. More info
See in Glossary to tvOS. The Apple TV platform, also known as tvOS, builds on the foundation of the iOS platform, but also creates new challenges for app developers. You can easily deploy an existing iOS app on tvOS, but often you must adapt your app’s content to work with tvOS input controls and display correctly on a bigger screen.
To develop for tvOS, you need the following:
It’s best practice to create a separate branch or copy of your app and port that to Apple TV. Many iOS plug-insA set of code created outside of Unity that creates functionality in Unity. There are two kinds of plug-ins you can use in Unity: Managed plug-ins (managed .NET assemblies created with tools like Visual Studio) and Native plug-ins (platform-specific native code libraries). More info
See in Glossary aren’t compatible with Apple TV, because Apple TV only supports a subset of the iOS framework. Unity has no control over third-party plug-ins and their cross-platform compatibility.
If your app uses more than 4 GB on disk, break it into smaller parts and use On Demand Resources. To learn more, see the On Demand Resources section below.
Note: Bitcode is included with tvOS builds, which adds around 130 MB to your executables. App Store servers strip this code, so it doesn’t affect your distribution size. To estimate Bitcode size, analyze the LLVM sections in your executable from the command line with otool -l
.
There are two main inputs for tvOS:
The Apple TV Remote (Siri Remote) is a multi-purpose input device that works as a traditional menu navigation controller, app controller, gyroscope, acceleration sensor, and as a touch gesture device. Unity routes Apple TV Remote input to corresponding Unity APIs, but performs no other processing on that input.
Your app might need some adjustments to its input scheme to leverage the Apple TV Remote’s specific input features. For instance, your app can treat it as a traditional app controller, with one analog axis and an extra action button, or your app can use the accelerometer for interactions such as steering. You can experiment with various schemes when porting an app to tvOS.
Unity offers Made For iOS (MFi), which is standardized controller support for iOS and tvOS. MFi controllers offer out of the box input mappings, and you can set up custom action mappings in the Unity Editor (menu: Edit > Project Settings…, then select the Input category). For more information, see documentation on iOS Game Controller support, and Apple developer documentation on Game ControllersA device to control objects and characters in a game.
See in Glossary.
Two further wireless Made For iOS (MFi) app controllers can be connected to an Apple TV device, which effectively turns it into a console. Your app can use the controllers in the same way as iOS MFi controllers, but you must ensure its usability with the Apple TV Remote alone. The tvOS system limits the number of additional controllers to two.
Here are some technical details on accessing specific TV Remote features:
Apple TV Remote button or function | Notes |
---|---|
Touch area | Maps to both Input.touches (Touch.type is set to Indirect and is ignored by the Unity GUI), and the Joystick Input API (for example, Input.GetAxis("Horizontal"); ). |
Touch area click | Maps to button A, which then maps to joystick button 14. |
Gyroscope | Maps to Input.gyro . Input.gyro.attitude derives from the gravity vector, and as such it doesn’t rotate around the axis parallel to the gravity vector. The same applies for Input.gyro.rotationRate . |
Acceleration | Maps to Input.acceleration . Note: Input.acceleration derives from the gyroscope API and might have some instabilities. The tvOS SDK doesn’t have a dedicated accelerometer API. |
Pause/Play button | Maps to button X, which then maps to joystick button 15. |
Menu button | A long press calls the tvOS task switcher. You can’t override this behavior. Your app can process short taps one of two ways: a) Return to the tvOS system home screen, if UnityEngine.tvOS.Remote.allowExitToHome is true.b) Let your app respond to taps (which maps to the Pause button/joystick button 0) when UnityEngine.tvOS.Remote.allowExitToHome is false. This the default behavior.Your app should switch between a) and b) based on its current state: - If the user is currently interacting with the top menu, enable behavior a). - If they’re interacting with the app in real time, enable behavior b) and call the in-app pause menu when they press this button. |
Swipe to the edge of the remote | Generates directional pad (D-pad) up/down/left/right button presses. For a list of mappings, see documentation on iOS Game Controller support. |
You can control the Apple TV Remote operational modes via a dedicated API as follows:
* UnityEngine.tvOS.Remote.allowExitToHome
* UnityEngine.tvOS.Remote.allowRemoteRotation
* UnityEngine.tvOS.Remote.reportAbsoluteDpadValues
* UnityEngine.tvOS.Remote.touchesEnabled
Note: When UnityEngine.Apple.TV.Remote.allowExitToHome
is false, the Menu button maps to joystick button 0. This causes a conflict with the default Input window, because it also uses joystick button 0 to map the Submit virtual button. This results in the Menu button triggering actions on UI elements. To fix this issue, remove or modify the Submit virtual button bindings in the Input window (menu: Edit > Project SettingsA broad collection of settings which allow you to configure how Physics, Audio, Networking, Graphics, Input and many other areas of your project behave. More info
See in Glossary
, then select the Input category).
You must provide custom visual resources to the Apple Game Center for its native leaderboard UI(User Interface) Allows a user to interact with your application. Unity currently supports three UI systems. More info
See in Glossary
. Here’s how to set them up in Xcode:
Note: Apple TV Remote navigation doesn’t work while your app is running in the TV Simulator.
The Apple Game Center requires you to provide custom visual resources for its native leaderboard UI. Here’s how to set them up in Xcode:
Tip: If your asset compilation fails after making this chnage, try disabling the On Demand Resources option in the in Xcode build settings.
tvOS limits how much disk space your application can reserve. The main application installation bundle size can’t be larger than 4 GB. The limits for additional downloadable content are up to 2GB for in-use assets, and up to 20GB of total downloadable content. Apple recommends On Demand Resources (ODR) for tvOS downloadable content, which is the best disk space management for tvOS. Unity supports ODROn-demand resources (ODR) is a feature available for the iOS and tvOS platforms, from version 9.0 of iOS and tvOS onwards. It allows you to reduce the size of your application by separating the core assets (those that are needed from application startup) from assets which may be optional, or which appear in later levels of your game. More info
See in Glossary
via Asset Bundles. For more information about ODR implementation, see the Unity blog Mastering on-demand resources for Apple platforms.
When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer.
More information
These cookies enable the website to provide enhanced functionality and personalisation. They may be set by us or by third party providers whose services we have added to our pages. If you do not allow these cookies then some or all of these services may not function properly.
These cookies allow us to count visits and traffic sources so we can measure and improve the performance of our site. They help us to know which pages are the most and least popular and see how visitors move around the site. All information these cookies collect is aggregated and therefore anonymous. If you do not allow these cookies we will not know when you have visited our site, and will not be able to monitor its performance.
These cookies may be set through our site by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant adverts on other sites. They do not store directly personal information, but are based on uniquely identifying your browser and internet device. If you do not allow these cookies, you will experience less targeted advertising. Some 3rd party video providers do not allow video views without targeting cookies. If you are experiencing difficulty viewing a video, you will need to set your cookie preferences for targeting to yes if you wish to view videos from these providers. Unity does not control this.
These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, logging in or filling in forms. You can set your browser to block or alert you about these cookies, but some parts of the site will not then work. These cookies do not store any personally identifiable information.