Unity

Unity 使用指南（Unity 6）

本指南介绍如何在 Unity 6 中下载、配置并使用 AMFITRACK SteamVR Driver。

说明
本教程旨在以最简单的方式演示如何获取 AMFITRACK 的位姿（Pose）数据（位置 Position + 姿态 Rotation）。
本教程**不涉及按钮（Button）和模拟输入（Analog Input）**的读取。
由于 AMFITRACK 驱动基于 SteamVR，因此任何能够读取 SteamVR 数据的方法都适用于 AMFITRACK。
如需更高级的开发方式，可参考 SteamVR 官方 GitHub 文档。

前提条件

开始之前，请确保已安装：

Unity（推荐 Unity 6）
AMFITRACK SteamVR Driver（按照 SteamVR 安装指南完成安装）

Unity 配置

下面介绍如何在 Unity 中配置 SteamVR。

第一步：创建 Unity 项目

打开 Unity Hub

点击：

New Project

选择：

3D

模板。

项目名称例如：

SteamVR_Setup

点击：

Create

官方说明：

本教程基于：

Unity 6

测试完成。

第二步：安装 SteamVR Plugin

打开：

Window
    ↓
Asset Store

或者：

访问 Unity Asset Store 网站。

搜索：

SteamVR Plugin

开发者：

Valve Corporation

点击：

Download

然后：

Import

导入插件。

导入窗口出现后：

保持默认勾选全部资源，

点击：

Import

即可。

第三步：配置项目

导入完成后，

Unity 会提示：

是否启用：

OpenVR / XR 设置。

请选择：

Accept

例如：

启用：

Virtual Reality Supported

第四步：配置 XR Plug-in Management

打开：

Edit
    ↓
Project Settings

找到：

XR Plug-in Management

在：

PC, Mac & Linux Standalone

下：

勾选：

OpenXR

继续在：

OpenXR 设置中，

找到：

Play Mode OpenXR Runtime

设置为：

SteamVR

这样 Unity 将使用：

SteamVR Runtime。

添加 AMFITRACK Unity 脚本

由于：

SteamVR 使用：

右手坐标系（Right-Handed）

而：

Unity 使用：

左手坐标系（Left-Handed）

因此：

需要进行坐标转换。

官方提供了一个 MonoBehaviour。

第一步

创建脚本：

Assets
    ↓
Create
    ↓
Scripting
    ↓
MonoBehaviour Script

第二步

命名：

AMFITRACK_UNITY_VR_Script

当然，

也可以使用其它名字。

第三步

打开脚本。

删除里面所有内容。

将官方提供的 C# 代码完整复制进去。

说明： 此处官方给出的代码保持原样即可，主要作用是：
从 SteamVR 获取指定设备（Controller、Tracker 或 HMD）的位姿数据；
将 SteamVR 的右手坐标系转换为 Unity 的左手坐标系；
在 Update() 中实时更新 Unity 对象的位置和旋转。

将脚本绑定到对象

创建一个测试物体。

例如：

Hierarchy
    ↓
Right Click
    ↓
3D Object
    ↓
Cube

然后：

选中 Cube。

点击：

Add Component

添加：

AMFITRACK_UNITY_VR_Script

设置 Device Index

脚本中有一个参数：

Device Index

它决定：

Cube 跟随哪一个 AMFITRACK 设备。

官方建议：

不要使用 Generic Tracker SRC。

因为：

它与其它 Tracker 的行为不同。

Device Index 对照表

Device Index	AMFITRACK ID	设备类型	SteamVR 序列号
0	—	HMD（头显）	—
16	2	左控制器（Left Controller）	`Amfitrack Controller Left`
17	3	右控制器（Right Controller）	`Amfitrack Controller Right`
18	4	Generic Tracker 01	`Amfitrack Generic Tracker #1`
19	5	Generic Tracker 02	`Amfitrack Generic Tracker #2`
20	6	Generic Tracker 03	`Amfitrack Generic Tracker #3`
21	7	Generic Tracker 04	`Amfitrack Generic Tracker #4`
22	9	HMD Src Tracker	`Amfitrack HMD Src Tracker`

例如：

如果：

Device Index = 16

Cube 就会：

跟随：

左手控制器。

如果：

Device Index = 18

Cube 就会：

跟随：

Generic Tracker #1。

运行程序

连接：

VR 头显。

启动：

SteamVR。

然后：

回到 Unity。

点击：

Play

如果：

一切正常，

Cube 会实时跟随：

对应 AMFITRACK 设备运动。

即：

位置和姿态同步。

故障排查（Troubleshooting）

SteamVR Plugin 找不到

请确认：

已登录 Unity Asset Store
网络连接正常
SteamVR Plugin 已成功导入项目

无法获取位姿数据

请检查：

Device Index 是否设置正确
SteamVR 是否已经启动
VR 头显是否已连接
AMFITRACK 设备是否已连接并正常工作

附加说明

本教程适用于 Unity 6。
如果使用其他 Unity 版本，部分菜单名称或界面可能有所不同。
更多信息请参考 Unity 官方文档。

工作原理

整个开发流程的核心如下：

AMFITRACK Sensor 将位姿数据发送到 SteamVR。
SteamVR 将设备注册为 Controller、Tracker 或 HMD。
Unity 中的脚本通过 OpenVR API（OpenVR.System.GetDeviceToAbsoluteTrackingPose()）读取设备位姿。
脚本将 SteamVR 的右手坐标系转换为Unity 的左手坐标系。
最后调用 transform.SetPositionAndRotation()，实时更新 Unity 场景中对象的位置和旋转，实现与 AMFITRACK 设备同步运动。