Apple TV / tvOS

This guide discusses setup, features, and development for Apple TV and tvOS in Corona.

Important

Before you proceed with experimentation and tvOS development, remember to evaluate various design aspects including deployment to a much larger screen and a pure controller-based interaction model. Converting an existing mobile app to tvOS will typically require thorough consideration of how the layout, UI, and controls will be affected.

Developing for tvOS

Sample Project

We recommend that you start with the Pew Pew! demo because the primary interaction model requires controllers (there is no touch interface on a TV). This sample is available in our GitHub repository.

Orientation

Apple TV does not have the concept of portrait versus landscape orientation. All Corona tvOS projects are run in the "landscapeRight" orientation. An app must support landscape orientation to be built through the Corona Simulator.

Icons / Launch Image / Top Shelf

Apple’s Human Interface Guidelines on Icons and Images defines how your app should present itself on the Apple TV. This means that you’ll need a new type of icon, at least one static Top Shelf image, and a launch image.

All assets provided must be .png files of specific sizes. The Top Shelf image, displayed when your app is one of the first on the user’s home screen, is a 1920×720 static .png file, and the launch image is a 1920×1080 static .png file.

App icons are not simply one image file, but multiple images stacked as layers. Additionally, you must provide both small (home screen) and large (app store) assets. Small assets are 400×240, while large assets are 1280×768. The bottom-most image in the stack must not have any transparency and it should serve as a background for the icon.

By editing your build.settings file, Corona will create the required bundles for you. Below is an example of what the tvos section of build.settings should look like:

settings =
{
    tvos =
    {
        -- Apple TV app icons consist of multiple "layers" in both small and large sizes
        icon =
        {
            -- A collection of 400x240 images, in order from top to bottom
            small =
            {
                "Icon-tvOS-Small-4.png",
                "Icon-tvOS-Small-3.png",
                "Icon-tvOS-Small-2.png",
                "Icon-tvOS-Small-1.png",
            },
            -- A collection of 1280x768 images, in order from top to bottom
            large =
            {
                "Icon-tvOS-Large-4.png",
                "Icon-tvOS-Large-3.png",
                "Icon-tvOS-Large-2.png",
                "Icon-tvOS-Large-1.png",
            }
        },

        -- A 1920x720 image file, displayed when your app is on the "top shelf"
        topShelfImage = "Icon-tvOS-TopShelf.png",

        -- A 2320x720 image file, displayed when your app is on the "top shelf" of a widescreen TV
        topShelfImageWide = "Icon-tvOS-TopShelfWide.png",

        -- A 1920x1080 image file, displayed briefly as your app loads
        launchImage = "Icon-tvOS-Launch.png",
    },
}

Interaction Model

The interaction model for Apple TV is centered around the Apple TV Remote. This remote operates like a game controller but in the “micro gamepad” profile, meaning that it has a limited set of buttons. In contrast, traditional game controllers like those for Xbox or PlayStation offer more buttons and thus have a more extended profile.

For more information on interaction, see the Game Controllers and MFi Controllers guides.

Important

  • Touch events don’t apply to tvOS — this platform revolves around relativeTouch, axis, and key events. Adapt your game accordingly!

  • All tvOS games are expected to work with the Apple TV Remote’s “micro gamepad” profile.

  • You can connect a MFi Controller to your Mac to send controller events to your app running in the Corona Simulator.

Important

The menu button on controllers (keyName of "menu") is expected to pause the app or move the user to the previous screen. Once the user is at the main menu, the app must use system.activate( "controllerUserInteraction" ) (documentation) and system.deactivate( "controllerUserInteraction" ) (documentation) to tell the operating system that a menu button press should back out of the app.

Note that a long press of the menu button will always exit your app, and is the default method to exit the app unless changed as described above.

Idle Timer

Your tvOS app should disable the screen idle timer via system.setIdleTimer():

system.setIdleTimer( false )

Widget Focus

Corona widgets do not have built-in support for focus. In order to interact with widgets on Apple TV, you will need to write custom code to handle focus. See the Pew Pew! sample for a demonstration of how to control widgets when they receive focus and how game controller events change focus.

Native Display Objects

The following native object functions are supported and, unlike widgets, these objects automatically support both focus and controller interaction:

Checklist for tvOS

Apple provides a checklist for games on tvOS. Please consult it to make sure your game adheres to their requirements.

Build Process

Building your tvOS app is a simple process once you have your certificate and provisioning profiles installed.

  1. From the Corona Simulator, select File → Open… to load the project you wish to build.

  2. Select File → Build → tvOS…

  3. Fill in the information:

    • Application Name — by default, this will match your project folder; keep this name or specify another.

    • Version — specify a version name for your app.

    • Provisioning Profile — select the appropriate provisioning profile for either development or distribution.

    • tvOS SDK — select the version of tvOS to build for.

    • Save to Folder — specify where to save the compiled app.

    • After Build — select which action should be performed after the app is successfully built.

  4. Click Build and Corona will compile the app. You will then have an application file that can be loaded on an Apple TV or submitted to the App Store, depending on which provisioning profile you selected.

Installation

There are two methods to install your app on an Apple TV, as outlined below.

You can not test an app built for App Store Distribution on an Apple TV. Apps built for distribution are intended for submission to Apple.

Copy to Device

  1. Connect the Apple TV to your computer.

  2. Follow the steps outlined in Build Process above, ensuring that you select Copy to device for the After Build option.

Xcode

  1. Connect your Apple TV, open Xcode, and then open the Devices window by selecting Window → Devices.

  2. In the left column, select the Apple TV.

  3. In the main pane, look for the Installed Apps section which shows the currently installed apps (this list may be empty initially). Below the list, click the [+] button and navigate to the location of the .app file which was generated by Corona. Select the file and click Open. Assuming there are no provisioning/certificate errors, the app should install on the device.

Feature Comparison

In general, tvOS contains a subset of the APIs available for iOS. See here for more details.

Libraries

Supported Unsupported
audio.* ads.*
composer.* facebook.*
crypto.* licensing.*
display.* native.*, except as noted above
easing.* media.*
(globals) store.*
graphics.*
io.*
json.*
lfs.*
math.*
network.*
os.*, except os.exit
package.*
physics.*
socket.*
sqlite3.*
string.*
system.*
table.*
timer.*
transition.*
widget.*

Events

Supported Unsupported
accelerometer colorSample
audio gyroscope
axis heading (compass)
collision inputDeviceStatus
completion licensing
enterFrame location (GPS)
finalize mapAddress
lateUpdate [mapLoca tion]api.event.mapLocation
memoryWarning mapMarker
networkRequest mouse
networkStatus notification
particleCollision orientation
postCollision popup
preCollision resize
relativeTouch tap
scene touch
sprite userInput
system
timer
unhandledError
urlRequest
video

Solar2D Native

The App project template contains Xcode projects under the tvOS subdirectory. Note that the plugin itself doesn’t do much.

Important

The virtual remote in the tvOS/Xcode Simulator can not be used to send controller events. Please test on a device or connect a MFi Controller.

Plugins / Frameworks

Plugins on tvOS are packaged as dynamic frameworks. Dynamic frameworks provide more flexibility, allowing code and resource files to be packaged together.

The App project template for tvOS contains an embedded Plugin project that you can modify. This project contains two targets:

  1. Corona_plugin_library — This is the target where you should add additional source files and frameworks that the plugin depends on (this is different from iOS plugins where dependencies are specified in metadata.lua).
  2. Corona_plugin_library.framework — This is the target to use if you want to publish/distribute your plugins to the Corona Store. It builds a universal framework (Apple TV device and tvOS/Xcode simulator).

When renaming your plugin frameworks, be sure to follow these conventions:

  • All frameworks must begin with the prefix Corona_ followed by the name of the library (the string passed to require()).
  • Change each dot (.) to an underscore (_).

For example:

require "plugin.myCoolLibrary" → Corona_plugin_myCoolLibrary.framework