Apple TV / tvOS

本指南讨论在 Corona 中 Apple TV 和 tvOS 的设置、功能和开发。

tvOS 开发
构建流程
安装
功能比较
Solar2D Native

重要

在您开始试验和 tvOS 开发之前，请务必评估各种设计方面，包括部署到更大的屏幕和纯基于控制器的交互模型。将现有的移动应用转换为 tvOS 通常需要仔细考虑布局、UI 和控件将受到的影响。

tvOS 开发

示例项目

我们建议您从 Pew Pew! 演示开始，因为主要的交互模型需要控制器（电视上没有触摸界面）。此示例可在我们的 GitHub 仓库中找到。

方向

Apple TV 没有纵向与横向的概念。所有 Corona tvOS 项目均以 "landscapeRight"（右横向）方向运行。应用必须支持横向才能通过 Corona 模拟器构建。

图标 / 启动图像 / 顶部货架

Apple 关于图标和图像的人机界面指南定义了您的应用在 Apple TV 上的呈现方式。这意味着您需要一种新型图标、至少一个静态顶部货架图像和一个启动图像。

提供的所有素材必须是特定大小的 .png 文件。顶部货架图像（当您的应用是用户主屏幕上的首批应用之一时显示）是一个 1920×720 的静态 .png 文件，启动图像是一个 1920×1080 的静态 .png 文件。

应用图标不仅仅是一个图像文件，而是多个图像堆叠为图层。此外，您必须提供小型（主屏幕）和大型（应用商店）素材。小型素材为 400×240，而大型素材为 1280×768。位于最底部的图像堆栈不得有任何透明度，它应该作为图标的背景。

通过编辑 build.settings 文件，Corona 将为您创建所需的捆绑包。以下是 build.settings 的 tvos 部分应该是什么样子的示例

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",
    },
}

交互模型

Apple TV 的交互模型以 Apple TV 遥控器为中心。此遥控器的工作方式类似于游戏控制器，但采用“微型游戏手柄”配置文件，这意味着它只有一组有限的按钮。相比之下，Xbox 或 PlayStation 等传统游戏控制器的按钮更多，因此配置文件更扩展。

有关交互的更多信息，请参阅游戏控制器和 MFi 控制器指南。

重要

触摸事件不适用于 tvOS — 此平台围绕 relativeTouch、axis 和 key 事件。请相应地调整您的游戏！
所有 tvOS 游戏都应与 Apple TV 遥控器的“微型游戏手柄”配置文件兼容。
您可以将 MFi 控制器连接到 Mac，以将控制器事件发送到 Corona 模拟器中运行的应用。

重要

控制器上的菜单按钮（keyName 为 "menu"）应暂停应用或将用户移至上一屏幕。用户进入主菜单后，应用必须使用system.activate( "controllerUserInteraction" )（文档）和system.deactivate( "controllerUserInteraction" )（文档）告诉操作系统按下菜单按钮应退出应用。

请注意，长按菜单按钮将始终退出您的应用，并且是退出应用的默认方法，除非如上所述进行更改。

空闲计时器

您的 tvOS 应用应通过 system.setIdleTimer() **禁用** 屏幕空闲计时器

system.setIdleTimer( false )

原生显示对象

以下原生对象函数受支持，并且与控件不同，这些对象自动支持焦点和控制器交互

tvOS 检查清单

Apple 提供了 tvOS 上游戏的检查清单。请查阅它以确保您的游戏符合其要求。

构建流程

安装证书和描述文件后，构建 tvOS 应用是一个简单的过程。

从 Corona 模拟器中，选择 **文件** → **打开…** 加载要构建的项目。
选择 **文件** → **构建** → **tvOS…**
填写信息
- **应用程序名称** — 默认情况下，这将与您的项目文件夹匹配；保留此名称或指定其他名称。
- **版本** — 指定应用的版本名称。
- **描述文件** — 选择适用于 **开发** 或 **分发** 的相应描述文件。
- **tvOS SDK** — 选择要构建的 tvOS 版本。
- **保存到文件夹** — 指定编译后应用的保存位置。
- **构建后** — 选择应用成功构建后要执行的操作。
单击 **构建**，Corona 将编译该应用。然后，您将获得一个应用程序文件，可以将其加载到 Apple TV 上或提交到 App Store，具体取决于您选择的描述文件。

安装

有两种方法可以将您的应用安装在 Apple TV 上，如下所述。

您**不能**在 Apple TV 上测试为**App Store 分发** 而构建的应用。为分发而构建的应用旨在提交给 Apple。

复制到设备

将 Apple TV 连接到您的计算机。
按照上面构建流程中概述的步骤操作，确保选择复制到设备作为 **构建后** 选项。

Xcode

连接 Apple TV，打开 **Xcode**，然后选择**窗口** → **设备**.
打开 **设备** 窗口。
在左列中，选择 Apple TV。在主窗格中，查找 **已安装的应用** 部分，其中显示当前已安装的应用（此列表最初可能为空）。在列表下方，单击 [**+**] 按钮并导航到 Corona 生成的 .app 文件的位置。选择该文件并单击 **打开**。假设没有描述文件/证书错误，该应用应安装在设备上。

功能比较

通常，tvOS 包含 iOS 可用 API 的一个子集。有关更多详细信息，请参阅此处。

库

支持	不支持
audio.*	ads.*
composer.*	facebook.*
crypto.*	licensing.*
display.*	native.*，以上注明者除外
easing.*	media.*
（全局变量）	store.*
graphics.*
io.*
json.*
lfs.*
math.*
network.*
os.*，`os.exit` 除外
package.*
physics.*
socket.*
sqlite3.*
string.*
system.*
table.*
timer.*
transition.*
widget.*

事件

支持	不支持
accelerometer（加速度计）	colorSample（颜色采样）
audio（音频）	gyroscope（陀螺仪）
axis（轴）	heading (compass)（航向（指南针））
collision（碰撞）	inputDeviceStatus（输入设备状态）
completion（完成）	licensing（许可）
enterFrame（进入帧）	location (GPS)（位置（GPS））
finalize（终结）	mapAddress（地图地址）
lateUpdate [mapLocation]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（URL 请求）
video（视频）

Solar2D Native

“应用”项目模板在“tvOS”子目录下包含 Xcode 项目。请注意，插件本身并没有做太多工作。

重要

tvOS/Xcode 模拟器中的虚拟遥控器无法用于发送控制器事件。请在设备上测试或连接MFi 控制器。

插件 / 框架

tvOS 上的插件打包为动态框架。动态框架提供了更大的灵活性，允许将代码和资源文件打包在一起。

tvOS 的“应用”项目模板包含一个嵌入式“插件”项目，您可以对其进行修改。该项目包含两个目标

“`Corona_plugin_library`”——这是您应该添加插件依赖的附加源文件和框架的目标（这与 iOS 插件不同，在 iOS 插件中，依赖项在“`metadata.lua`”中指定）。
“`Corona_plugin_library.framework`”——如果您想将插件发布/分发到 Corona 商店，则应使用此目标。它构建一个通用框架（Apple TV 设备和 tvOS/Xcode 模拟器）。

重命名插件框架时，请务必遵循以下约定

所有框架都必须以`Corona_`前缀开头，后跟库的名称（传递给`require()`的字符串）。
将每个点 (`.`) 更改为下划线 (`_`)。

例如

`require "plugin.myCoolLibrary"` → `Corona_plugin_myCoolLibrary.framework`