This guide discusses setup, features, and development for Apple TV and tvOS in Corona.
Before you proceed with experimentation and tvOS development, remember to evaluate various design aspects including deployment to a much larger screen and a pure
We recommend that you start with the PewPew demo because the primary interaction model requires controllers (there is no touch interface on a TV). This sample is available in our GitHub repository or in your local Corona application folder:
/SampleCode/Demos/PewPew
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.
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
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",
},
}
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.
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.
The menu button on controllers keyName of "menu")system.activate( "controllerUserInteraction" )system.deactivate( "controllerUserInteraction" )
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.
Your tvOS app should disable the screen idle timer via system.setIdleTimer():
system.setIdleTimer( false )
Corona widgets do not have
The following native object functions are supported and, unlike widgets, these objects automatically support both focus and controller interaction:
Apple provides a checklist for games on tvOS. Please consult it to make sure your game adheres to their requirements.
Building your tvOS app is a simple process once you have your certificate and provisioning profiles installed.
From the Corona Simulator, select File → Open... to load the project you wish to build.
Select File → Build → tvOS...
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.
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.
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.
Connect the Apple TV to your computer.
Follow the steps outlined in Build Process above, ensuring that you select
Connect your Apple TV, open Xcode, and then open the Devices window by selecting
In the left column, select the Apple TV.
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.
In general, tvOS contains a subset of the APIs available for iOS. See here for more details.
| 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.* |
The App project template contains Xcode projects under the tvOS subdirectory. Note that the plugin itself doesn't do much.
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 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:
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).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:
Corona_ followed by the name of the library (the string passed to require())..) to an underscore (_).For example:
require "plugin.myCoolLibrary" → Corona_plugin_myCoolLibrary.framework
While iOS and tvOS are similar, there are some important differences:
For tvOS, we are not making a distinction between Corona Enterprise and CoronaCards. We will be packaging the Corona engine in a single framework that can be used by Corona Enterprise developers.
Because many CoronaCards header files assume the relative path, for example #include "CoronaCards/CoronaView.h", the framework name is called CoronaCards.framework. However, for those developers familiar with CoronaCards, there is no license file used. Instead, you must activate a Corona Enterprise trial/subscription.