XR 插件框架

XR API 参考

针对 XR 配置 Unity 项目

要针对 XR 配置您的 Unity 项目，请按照以下步骤操作：

打开 Project Settings 窗口（菜单：Edit > Project Settings），然后选择 XR Plug-in Management。
单击 Install XR Plug-in Management（如果尚未安装此包）。还可以从 Package Manager 窗口中安装此包。
安装完成后，选择 Plug-in Provider 为对应的构建目标启用此包。为此需要执行以下操作：
1. 选择一个构建目标（例如 Android）。
2. 选中要用于该构建目标的每个插件左侧的复选框。
插件加载后会显示在左侧导航栏中的 XR Plug-in Management 下方。单击该插件可为每个构建目标配置相应的设置。
要设置跟踪，请从 Unity 的主菜单中选择 GameObject > XR > Add XR Rig。

注意：

选择一个 XR 插件提供程序将为相应的构建目标启用该提供程序。如果该插件包还不存在，则 Unity 会自动安装该插件包。
禁用插件不会自动卸载现有的包。从 Package Manager 中卸载提供程序插件。
有关第三方插件的列表，请参阅 [VROverview](Getting Started with VR Development)。

在 XR 插件框架中设置跟踪

在 2019.3 之前的 Unity 版本中使用的隐式摄像机跟踪已在新的 XR 插件框架中删除。隐式跟踪适用于仅支持 HMD 的简单应用程序，但是与控制器和其他交互方式关联使用时，隐式跟踪并不那么直观。

要确保在 XR 插件框架中正确配置 XR 跟踪，请按照以下步骤操作。

从新场景开始

如果从新场景开始，或者从满足以下条件的场景开始，则需要遵循下方的说明：

场景中只有一个摄像机，并且该摄像机被标记为主摄像机 (Main Camera)。
场景中的摄像机位于层级视图的根目录。

从 Unity 的主菜单中，选择 GameObject > XR > Add XR Rig。这时会尝试将新场景转换为正确支持 XR 插件框架的场景。

如果在控制台日志中没有看到任何错误，则现在应该可以在场景中单击 Play，并看到在 XR Plug-in Management 包中配置的设备所对应的摄像机跟踪。

如果 Unity 无法正确迁移场景，则控制台日志中会显示错误。请遵循以下从现有场景开始部分中的说明。

从现有场景开始

与迁移空场景相比，从现有场景进行迁移还需要一些其他步骤。因此，根据场景的配置方式会有不同的选项。总体目标是使场景跟踪的方式与迁移到 XR Plug-in Framework 之前的方式相同。

识别场景类型

在场景中找到被标记为主摄像机 (Main Camera) 的摄像机。Unity 使用此摄像机来渲染到 HMD 或其他主要设备。

如果主摄像机游戏对象：

位于项目层级视图的根目录，请遵循有关迁移简单场景的步骤进行操作。
不在项目层级视图的根目录，请遵循有关迁移复杂场景的步骤进行操作。

迁移简单场景

要迁移简单的场景，请遵循以下步骤。

1.创建 XR 绑定 (XR Rig) 预制件的实例。

迁移以前位于场景层级视图根目录的摄像机，这样可以通过实例化此包所包含的 XR 绑定预制件而将现有摄像机交换为 XR 绑定。

可以在 Packages/XR Legacy Input Helpers/Prefabs 文件夹中找到此预制件。将此预制件拖动到场景层级视图中即可创建该预制件的新实例。

2.移动 XR 绑定以匹配摄像机的位置。

现在有了 XR 绑定预制件的实例，接下来需要配置 XR 绑定游戏对象，以便在应用程序启动时生成的摄像机位置正确无误。

更改 XR 绑定游戏对象的位置和旋转，使其与当前主摄像机的位置匹配。如果要将缩放变换应用于主摄像机，请确保也将此缩放比例应用于 XR 绑定游戏对象。如果缩放 XR 绑定，强烈建议在所有三个轴上使用统一的缩放比例。

3.如果需要，请复制位置更改。

如果未迁移场景中的主摄像机位于地面上方（其 Y 分量大于 0.0f），则需要复制此位置更改。可以通过几种不同的方式来执行此操作，具体取决于要复制更改的原始位置。

3.1 - 升高用于模拟用户的身高

如果将先前的主摄像机抬高到地面上方以模拟用户的身高，并且应用程序使用设备跟踪原点（有时称为“固定”跟踪模式），则 Camera Offset 组件会执行这一附加升高。否则，请参阅下一节。

要将摄像机配置为当应用程序以设备跟踪原点模式使用时摄像机垂直升高，则可以在 XR 绑定 (XR Rig) 游戏对象的 Camera Offset 组件中设置以下选项：

选项	值
Requested Tracking Mode	设备
Camera Y Offset	将此选项设置为将现有主摄像机升高的高度（以模拟用户身高）。

配置完这些选项后，将 XR 绑定 (XR Rig) 游戏对象的 Y Position 更改为您在应用程序中通常视为“地面”的值（通常是 0.0f）。Camera Offset 组件会根据需要增加任何附加升高。

3.2 - 升高指示摄像机位置

如果未迁移的场景使用地面跟踪原点（以前称为“房间规模”跟踪模式），并且主摄像机的位置代表用户的起点，但不含身高（即，摄像机实际上是在逻辑“地面”上），请按照以下步骤正确迁移场景：

移动 XR 绑定以使其在 Unity 世界空间中匹配主摄像机的当前位置和旋转方式。
如果应用程序使用地面跟踪原点，请在 Camera Offset 组件中将 Requested Tracking Mode 设置为 Floor。这样可以确保摄像机具有正确的垂直偏移。
如果应用程序未使用地面跟踪原点，请在 Camera Offset 组件中将 Requested Tracking Mode 设置为 Default。无论应用程序以哪种设备跟踪模式启动，都将应用正确的行为。
如果您以前使用其他组件垂直移动摄像机并处理设备和地面跟踪原点之间的差异，则可能需要禁用或修改此组件，以使不同组件不会多次错误地移动摄像机。

接下来，从 XR 绑定实例中删除主摄像机游戏对象，并将现有的主摄像机 (Main Camera) 游戏对象设置为摄像机偏移 (Camera Offset) 游戏对象的父代。

确保主摄像机游戏对象的位置和旋转均为 0,0,0。请始终更改 XR 绑定游戏对象的位置，而不是更改摄像机的位置。另外，请确保从游戏对象或组件到主摄像机的任何链接仍然正确。

5.针对 XR 配置项目

请参阅上文的针对 XR 配置 Unity 项目部分。

6.按 Play

现在，您的场景已成功迁移，接下来请按 Play，并确保摄像机的起始位置与迁移到 XR 插件框架之前的位置相同。如果不是，请参阅下面的“故障排除”部分。

迁移复杂场景

如果当前场景使用来自旧版 VR 系统的隐式摄像机跟踪，并且主摄像机是游戏对象层级视图的一部分，请按照以下步骤将旧版 VR 跟踪系统迁移到 XR 插件框架。

隐式摄影机更新会在每一帧中更新主摄像机游戏对象的本地变换两次，这会使主摄像机游戏对象相对于其所在层级视图的位置、缩放和旋转进行移动。

在这种情况下，有两种方法来迁移场景：

保留现有层级视图并添加组件以在当前层级视图中启用跟踪
迁移现有层级视图以使用 XR 绑定结构。

如果您的场景具有依赖于现有层级视图结构的功能，通常建议保留该层级视图。如果具有相对简单的配置，则可以直接迁移到 XR 绑定。

保留

此方法只需要对现有场景层级视图进行最少的修改，即可在 Unity 中启用跟踪。这一过程涉及将跟踪姿势驱动程序 (Tracked Pose Driver) 添加到场景中的主摄像机。这样可以确保需要当前游戏对象层级视图的任何其他功能继续正常运行。

1.找到主摄像机，并向其中添加一个跟踪姿势驱动程序 (Tracked Pose Driver)

在场景中查找主摄像机。

使用 XR 绑定的主摄像机所用的相同设置来添加跟踪姿势驱动程序 (Tracked Pose Driver)。以下截屏显示了这些设置：

对场景中的所有主摄像机执行此操作。如果需要跟踪场景中的其他设备，请参阅跟踪姿势驱动程序 (Tracked Pose Driver) 设置以获取适用于具体用例的正确选项。

2.针对 XR 配置项目