Microtube 常见问题
使用 HEXR 进行开发时的常见问题。
常见问题
HEXR 支持哪些头显和平台？
使用 Unity 插件包时，Meta Quest 2、3 和 3S 以及 PICO 4 和 4 Ultra（消费版和企业版）的构建都可以连接手套，Unity Editor 以及 Windows 上的构建同样可以。Microsoft HoloLens 和 Leap Motion 需通过单独的旧版集成方案使用。Python 库可在任何能运行 bleak 的系统上运行：Windows、macOS 和 Linux。各平台的验证情况见平台与头显支持。
如何集成 HEXR？
支持 Godot 吗？
支持。HexR Godot 插件（Godot 4.6 或更高版本）可以从 Meta Quest 和 PICO 头显以及 Windows 连接手套，发送的命令与 Unity 插件包相同，并且支持 HexR Remote。请从 Godot 项目设置开始。
支持 Unreal 吗？
如何获取 Meta XR SDK？
Unity 的包注册表中没有 com.meta.xr.sdk.*，因此 Package Manager 无法单凭名称安装它。请在 Asset Store 打开免费的 Meta XR All-in-One SDK，点击 Add to My Assets，然后在 Unity 中通过 Window → Package Manager → My Assets 安装。之后，在 HexR → HexR Tools → Project Setup 中点击 Re-scan。OpenXR 无需这些步骤——它的所有包都来自 Unity 注册表。PICO 的 OpenXR 插件是个例外：需要从 PICO 开发者网站手动下载。
需要哪个 Unity 版本？
Unity 2022.3 LTS 或更高版本，已验证至 Unity 6000.6。这是 com.microtube.hexr 插件包声明的版本要求，在更早的版本上 Package Manager 会拒绝安装。你的 PATH 中还需要有 git，因为 Unity 会调用它来获取插件包。完整的支持矩阵（以及 Unity 升级导致构建失败时该怎么办）见 Unity 版本支持。
需要把 HEXR 文件夹复制到我的项目中吗？
不需要——至少我们的文件夹不需要。通过 git URL 安装插件包后，HEXR 的所有内容都会随之安装：脚本、预制体、HaptGlove 运行时，以及 Windows 和 Android 的蓝牙传输层。如果改为从教程项目中复制这些文件夹，会产生重复的程序集并导致编译错误。
XR 后端则是另一回事。HEXR 有意不依赖 OpenXR 或 Meta OVR——即使项目中完全没有 XR 也能编译——这也意味着不会有任何东西替你安装后端。你仍需要自行引入后端，并使用该后端的手部追踪装置（rig），而且部分 HEXR 组件要求该后端的类型存在。
打开 HexR → HexR Tools → Project Setup，选择项目使用的后端，然后安装它报告缺失的所有内容。OpenXR 的包都来自 Unity 自己的注册表；Meta XR SDK 则不是，因此需要先将它添加到你的 Unity 账户——见 Unity 集成。
一切都设置好了，但没有任何触觉反馈。哪里出了问题？
在修改任何代码之前，先确定问题出在手套还是你的场景——在 Unity 里，这两种情况看起来完全一样。
单独测试手套
打开 HEXR Tester，连接手套，选择一个通道并点击 Trigger。这样可以完全排除你的项目的影响。
在测试工具中也没有反应？那就是硬件问题
检查手臂模块是否已通电，且电池指示灯不是红色。然后检查贴合情况——手指没有完全插到底时，压头会偏离指尖，即使通道工作正常也感觉不到任何反馈。接着运行 Quick test：单个通道失效说明压头或阀门有故障，六个通道同时失效则是气泵或其供电的问题。
在测试工具中能触发？那手套没问题——问题出在你的场景
按照下面的清单逐项排查，每次只改一处，每改一处就点击一次 Play。如果一次改了三处后出现了触觉反馈，你无法知道究竟是哪一处起了作用；而且这些问题会叠加——手套还没连接时，修好碰撞体也无济于事。
| 检查项 | 为何会导致完全没有反馈 |
|---|---|
| 手套确实已在场景中连接 | 连接是从你自己的项目中发起的。如果没有人点击 HexR 菜单中的 Connect Left Glove / Connect Right Glove，也没有在 Editor 中点击 HexR Haptics Tester 的 Connect，而你的代码也没有调用 HexRManager.Instance.Connect(...)，那么所有调用都不会发送到任何设备。在排查其他问题之前，先检查 bleConnected |
| 场景中有 Pressure Controller（压力控制器） | 每个触觉调用都会查找它，没有它就不会产生任何效果。HexR → Create HexR Rig 会添加它们 |
| 场景中有手 | HEXR 跟随场景中已有的装置（rig），不会自行创建。没有被追踪的手，就没有手部靠近检测，也就没有触觉反馈。在 Meta 上，仅有 Building Blocks 的 Hand Tracking 模块是不够的——请添加 Interactions Rig。见设置场景 |
| 物体具备其组件所需的部件 | SpecialHaptics 需要分配两个 Pressure Controller（Auto Find Hand Physics）。HexRInteractableHaptics 需要物体上有你所用 SDK 的可交互组件（interactable）。物体本身无需 Rigidbody 即可响应触碰：每个触点都已自带一个 |
| 碰撞体已勾选 Is Trigger | 实体碰撞体只会发生碰撞，不会触发 HEXR 监听的触发器事件 |
| 有组件告知 HEXR 手已靠近 | 大多数调用只在抓取交互器、戳按交互器或 ProximityCheck 判定手已靠近时才会触发。在 OpenXR 上，HEXR 会读取 XR Direct 和 XR Poke 交互器，从 0.9.4 起还会读取 Near-Far Interactor——但对 Near-Far 交互器只读取近距离抓取。在 0.9.4 之前，使用 Near-Far Interactor 抓取的装置需要在物体上添加 ProximityCheck。见手部靠近检测 |
| 运行 Validate Scene Setup | HexR → Troubleshoot → Validate Scene Setup 会报告所有尚未连接好的内容，一次就能发现上述大部分问题 |
Auto Setup 提示找不到被追踪的手。缺了什么？
缺的是手。Auto Setup 会把 HEXR 挂接到 Hierarchy 中已有的手部模型上，而此时场景中还没有手部模型。
在 Meta 上，常见原因是 Building Blocks 的 Hand Tracking 模块。它会开启手部追踪，但其手部模型要等应用运行后才会生成，因此在 Editor 中没有可挂接的对象。删除它的两个 [BuildingBlock] Hand Tracking 对象，改为添加 Interactions Rig 模块。在 OpenXR 或 PICO 上，添加 XR Interaction Toolkit 的 Hands Interaction Demo 示例中的 XR Origin Hands (XR Rig) 预制体。
然后运行 HexR → Troubleshoot → Re-run Auto Setup。完整步骤见设置场景。
必须使用手部追踪吗？
是的。HEXR 本身不追踪手部——它依靠头显或 Leap Motion 等外部设备提供的手部追踪，并在此基础上叠加触觉反馈层。见使用手部追踪。
可以用 pip 安装 Python 库吗？
暂时不行——HaptGlovePython 需要克隆仓库后运行（先 git clone，再 pip install -r requirements.txt）。将其发布到 PyPI 后即可使用 pip install。
延迟是多少？
这取决于你的配置，而且当前款手套的端到端延迟尚未测量。延迟由三部分叠加而成：在 Quest 和 PICO 构建上，插件包默认最多每 100 ms 发送一次命令；蓝牙会增加头显或 PC 所选定的连接间隔；手套在收到命令后 20 ms 内启动气泵，然后以全速在大约 90–300 ms 内升至目标值。详细分解见延迟。
可以将 HEXR 用于定制硬件或科研硬件吗？
可以——我们提供定制和科研集成方面的合作。请通过联系页面与我们联系。
在哪里报告 Bug 或提出功能需求？
在 GitHub 上提交 issue，或直接联系我们。