Unity 场景设置

在场景中添加手部和 HEXR 装置（rig），并连接手套。

HEXR 场景需要什么

场景共需四样东西。手部由你的 XR SDK 提供，其余部分用 HexR → Create HexR Rig 一次性添加。

新建场景

最快的方法：HexR → Create Demo Scene 会生成一个可直接试用的场景，包含装置、一个触觉球体和一个可抓取的立方体。它无法添加手部，因此请先完成下方第 1 步，再运行 HexR → Troubleshoot → Re-run Auto Setup。

也可以自己搭建：

1. 添加手部

   HEXR 会挂接到场景中已有的手部上，不会自行创建手部。请添加一个会把手部放进 Hierarchy 的装置：

   后端	需要添加
   Meta OVR	Meta → Tools → Building Blocks → Interactions Rig。不要用 Hand Tracking 模块：它的手部要到应用运行后才会出现，对 HEXR 来说为时已晚
   OpenXR 或 PICO	在 Window → Package Manager → XR Interaction Toolkit → Samples 中导入 Hands Interaction Demo，并将其中的 XR Origin Hands (XR Rig) 预制体拖入场景。删除场景中的 Main Camera，因为该装置自带相机

   检查：在 Hierarchy 中搜索 OpenXRLeftHand（Meta）或 L_Wrist（OpenXR）。如果搜不到，说明场景中还没有手部。

2. 添加 HEXR 装置

   运行 HexR → Create HexR Rig → 你的后端。它会添加 HexR Main 和 Pressure Controller（压力控制器），然后运行 Auto Setup，在手部放置触点。

3. 验证

   运行 HexR → Troubleshoot → Validate Scene Setup，并修复它列出的所有问题。它能发现那些原本会被误以为是手套故障的错误。

4. 连接手套

   打开手臂模块电源。在头显构建版本中，点击 HexR 菜单上的 Connect Left Glove 或 Connect Right Glove。在 Windows 上的 Unity Editor 中，点击 Play，然后通过 HexR → HexR Tools → HexR Haptics Tester 连接。首次在头显上运行时，请允许蓝牙权限，见在头显上允许蓝牙。

如果 Auto Setup 找不到某些对象

• “Couldn’t find a tracked hand”：场景中还没有手部。先完成第 1 步，再运行 HexR → Troubleshoot → Re-run Auto Setup。每次更改手部后都要重新运行。
• 无法自动找到交互器（“Couldn’t auto-find”，Meta）：将装置左手的 Hand Grab Interactor 和 Poke Interactor 拖到 Left Pressure Controller 的对应字段中，右手的则拖到 Right Pressure Controller 中。
• 添加了 Meta 的 Hand Tracking 模块？删除它的两个 [BuildingBlock] Hand Tracking 对象，改为添加 Interactions Rig，然后重新运行 Auto Setup。

将 HEXR 添加到现有项目

1. 安装插件包

   按照项目设置操作。请通过 git URL 安装，不要从教程项目中复制 HEXR 文件夹，否则会产生重复代码并导致编译错误。要从旧版 HEXR 升级？请先阅读更新日志。

2. 检查手部

   HEXR 通过关节名称查找装置中的手部，因此手部必须来自 Meta 的 Interaction SDK 或 Unity 的 XR Hands（名称见 HEXR 场景）。在 Hierarchy 中搜索 OpenXRLeftHand（Meta）或 L_Wrist（OpenXR）。搜不到？说明你的手部要到应用运行后才会出现，见新建场景的第 1 步。

3. 将装置添加到应用的启动场景

   运行 HexR → Create HexR Rig → 你的后端。它会添加 HexR Main 和 Pressure Controller（压力控制器），Auto Setup 会在你现有的手部上放置触点，并连接好你的抓取和戳按交互器。你的相机装置、手部和对象都保持不变。然后运行 HexR → Troubleshoot → Validate Scene Setup。

4. 为其他每个场景添加 Pressure Controller

   加载新场景时，HexR Main 会被保留，并自动找到该场景中的手部；但每个场景都需要自己的一对 Pressure Controller（压力控制器）：在每个场景中运行 HexR → Add Pressure Controller。

5. 让对象产生触感

   将 HexRInteractableHaptics 添加到已有的可交互组件旁边：OpenXR 上是 XR Grab Interactable，Meta 上是 Grabbable 和 Hand Grab Interactable。其他情况请参阅我需要哪个组件？

HexR 菜单

在头显中悬浮显示的面板，主要用于通过蓝牙连接手套。它随装置一起提供，位于用户左侧并朝向用户；用真实的指尖按下它的按钮即可。要将它添加到你自己的场景中，请使用 HexR → Add HexR Menu。

改用你自己的菜单

HexR 菜单并非必需。从 SDK 0.9.4 起，HEXR 不依赖该菜单也能工作，因此你可以通过自己的按钮或直接在代码中连接，不必使用它。以下是相关调用，均位于 HexRManager.Instance 上：

HexRManager rig = HexRManager.Instance;
var left = HaptGloveHandler.HandType.Left;   // or HandType.Right

rig.Connect(left);       // connect; asks for Bluetooth permission where needed,
                         // does nothing if already connected or connecting
rig.Disconnect(left);    // release the glove, then disconnect

bool connected  = rig.IsConnected(left);
bool connecting = rig.IsConnecting(left);        // includes waiting for permission or a retry
float battery   = rig.leftHand.GetBatteryLevel();   // 0-1, once connected

一个现成的脚本，供你自己的按钮使用。将它挂到任意对象上，把每个 UI Button 的 On Click () 指向它的四个方法之一，再把 Status Changed 连接到一个文本字段，即可显示当前状态。

using UnityEngine;
using UnityEngine.Events;
using HaptGlove;
using HexR;

// Connect buttons of your own, instead of the HexR menu. Point each UI Button's
// On Click () at one of the four methods, and wire Status Changed to a text field.
public class GloveButtons : MonoBehaviour
{
    public UnityEvent<string> statusChanged;

    public void ConnectLeft()     => HexRManager.Instance.Connect(HaptGloveHandler.HandType.Left);
    public void ConnectRight()    => HexRManager.Instance.Connect(HaptGloveHandler.HandType.Right);
    public void DisconnectLeft()  => HexRManager.Instance.Disconnect(HaptGloveHandler.HandType.Left);
    public void DisconnectRight() => HexRManager.Instance.Disconnect(HaptGloveHandler.HandType.Right);

    void Start()
    {
        HexRManager rig = HexRManager.Instance;
        rig.leftHand.onBluetoothConnected += OnConnected;
        rig.rightHand.onBluetoothConnected += OnConnected;
        rig.leftHand.onBluetoothDisconnected += OnDisconnected;
        rig.rightHand.onBluetoothDisconnected += OnDisconnected;
    }

    void OnDestroy()
    {
        HexRManager rig = HexRManager.Instance;
        if (rig == null) return;
        rig.leftHand.onBluetoothConnected -= OnConnected;
        rig.rightHand.onBluetoothConnected -= OnConnected;
        rig.leftHand.onBluetoothDisconnected -= OnDisconnected;
        rig.rightHand.onBluetoothDisconnected -= OnDisconnected;
    }

    void OnConnected(HaptGloveHandler.HandType hand)    => statusChanged.Invoke(hand + " glove connected");
    void OnDisconnected(HaptGloveHandler.HandType hand) => statusChanged.Invoke(hand + " glove disconnected");
}

如需在场景启动时立即连接、完全不用按钮，请参阅通过代码连接两只手套。所有连接事件都列在事件中。

将应用安装到头显

可以直接从 Unity 构建，也可以安装 APK 文件。无论哪种方式，都需要先在头显上开启开发者模式。

开启开发者模式

每台头显只需设置一次。

然后用 USB 线将头显连接到电脑，并在头显中接受 Allow USB debugging 提示。

从 Unity 安装

在头显已连接的情况下，进入 File → Build Profiles → Android → Switch Platform，然后点击 Build And Run。Unity 会安装并启动应用。如果想得到一个可分享的 APK 文件，请改为点击 Build。

从 APK 文件安装

• SideQuest（Quest 和 PICO）：一款免费的桌面应用。连接头显后，使用其中的安装 APK 按钮，或将文件拖到窗口上。获取 SideQuest ↗
• Meta Quest Developer Hub（仅限 Quest）：Meta 官方的桌面工具，用于安装和管理应用。Meta Quest Developer Hub ↗
• adb（Quest 和 PICO）：安装 Android 的 platform-tools ↗ 后，在终端中运行：

adb install -r YourApp.apk

在头显上找到应用：以这种方式安装的应用不会和商店应用放在一起。在 Quest 上，打开应用库并选择 Unknown Sources；在 PICO 上，请在资源库（Library）的未知来源筛选中查找。

在头显上允许蓝牙

应用首次连接手套时，头显会请求蓝牙使用权限。请允许。如果拒绝，应用会继续运行，但始终找不到手套。HexR 菜单和 HexRManager.Instance.Connect(...) 都会自动为你请求该权限。