Microtube 文档
Ctrl K
EN中文
SDK 0.9.4开发者GitHub ↗
开发者 / 入门 / HEXR 工作原理

入门

设置 HEXR SDK，连接 HEXR 手套，触发你的第一个触觉事件，并了解使用 Unity 或 Python 开发 HEXR 应用的核心概念。

HEXR 工作原理

HEXR 是一款触觉手套：它让用户在 VR 和混合现实中感受到自己触碰的物体。它不追踪手部，也不会自动为现有应用添加触觉。一个 HEXR 应用由四部分组成：

  1. 你的应用

    使用 Unity、Godot 或 Python 构建，并集成了 HEXR SDK。

  2. 与手套的蓝牙连接

    由你的应用直接连接手套：点击 HEXR 装置（rig）菜单上的 Connect，或调用 HexRManager.Instance.Connect(...)。Python 使用 bleak 连接。不要在电脑或头显的蓝牙设置中配对手套。

  3. 手部追踪

    由你的头显提供，例如 Meta Quest 或 PICO（支持的设备）。手部追踪负责确定手在哪里，HEXR 负责决定手感受到什么。

  4. 物体上的 HEXR 组件

    为用户需要感受到的每个物体添加一个组件，可以先从 HexRInteractableHaptics 开始。我需要哪个组件？

接下来，在 HEXR Tester 中试用手套。触碰被感知的速度还取决于你的头显，请参阅延迟。

前提条件

开始之前，请确认你已准备好以下内容：

安装

请在下方选择你的开发平台。

HEXR 是一个 Unity 插件包（com.microtube.hexr），需通过 Git URL 安装。使用 Add package by name 无法找到它。

  1. 打开 Package Manager

    在 Unity 中，前往 Window → Package Manager。

  2. 添加插件包

    点击左上角的 +，选择 Add package from git URL…，粘贴以下 URL，然后点击 Add：

    text
    https://github.com/MicrotubeTechnologies/com.microtube.hexr.git

    如需固定使用某个版本，请在 URL 末尾加上 #v0.9.4。

下一步

在 Unity 指南中设置你的 XR 后端（OpenXR、Meta OVR 或 PICO）和场景。该指南还介绍了如何更新插件包以及解决安装冲突。

HEXR 的 Godot 版本是一个插件（addons/hexr），适用于 Godot 4.6 或更高版本。

  1. 下载插件

    从插件的最新版本 ↗下载 HexR-Godot.zip，并解压到你的项目中。

  2. 启用插件

    打开 Project → Project Settings → Plugins，勾选 HexR。这会添加 HexR 自动加载（autoload）、HexR 菜单和 HexR Tools 停靠面板，与 Unity 中一样。

下一步

在 Godot 项目设置中为 Meta Quest 或 PICO 配置 OpenXR。

你需要 Python 3.8 至 3.13：该库将 bleak 固定为 0.22.3 版本，而该版本无法在 Python 3.14 上安装。克隆 Python 仓库并安装其依赖项：

shell
git clone https://github.com/MicrotubeTechnologies/HaptGlovePython.git
cd HaptGlovePython
pip install -r requirements.txt

Python 指南中的第一个脚本会按名称查找你的手套。而仓库自带的 ExampleHaptics.py 则需要手套的蓝牙地址：运行 AddressDiscovery.py，并把它输出的地址填入该脚本。

注意

Python 控制库使用 bleak 通过蓝牙（BLE）与手套通信。目前需要从克隆的仓库中运行，尚未发布为 pip 包；为仓库添加 pyproject.toml 即可支持 pip install。

从教程项目开始

如果你想从一个可运行的示例开始，而不是从零搭建项目，可以使用下面的 HEXR 教程项目。

每个项目都通过 git URL 获取 HEXR 插件包，并固定为 #v0.9.3（比本插件包落后一个版本；将固定版本改为 #v0.9.4 即可获得相应修复），并且都包含可直接运行的演示场景。

HEXR Tester

在编写任何代码之前，先用免费应用 HEXR Tester 试用手套。它通过蓝牙连接手套，让你手动触发任意手指。整个过程大约五分钟；之后如果你自己的应用没有触觉反馈，你也能确定手套本身是正常的。

下载 Windows 版 →从 Google Play 获取 →

使用 Mac？请前往 HEXR Tester 页面获取。

  1. 安装应用

    在 Android 上，从 Google Play 安装。在 Windows 上，运行你下载的安装程序。该程序尚未进行代码签名，因此 Windows 会显示蓝色警告界面：请先按照检查是否正常工作中的说明核验下载的文件，然后选择 More info → Run anyway。

  2. 戴上手套并开机

    将手套连接到手臂模块（左对左，右对右），然后戴上手套，把每根手指完全推入对应的指套。按住电源按钮，直到指示灯亮起。

  3. 通过蓝牙连接

    点击 Scan for gloves。你的手套会显示为 HaptGloveAR Left 或 HaptGloveAR Right；点击该行的 Connect。只能从应用内连接，不要在手机或电脑的蓝牙设置中配对手套。

  4. 触发你的第一个触觉反馈

    在测试界面上，选择对应的手，只勾选 Index，选择 Pressure，将强度设为 0.5 左右，然后点击 Trigger。你会感到食指指尖受到持续的挤压。

  5. 释放

    点击 Release，挤压即停止。手指会一直保持受压，直到你释放它、关闭应用或关闭手臂模块。All off 会一次性停止所有手指。

  6. 自由尝试

    试试其他手指，或同时触发多根手指。从持续挤压切换到振动，并调整强度和频率，感受缓慢的脉冲如何变成快速的嗡嗡振动。应用还会显示实时读数：每根手指的压力、电池电量和供气情况。如果有两只手套，可以同时连接，一起或分别驱动它们。

没有感觉？把手指完全推入指套后再试一次，大多数反馈微弱或没有反馈的问题都与佩戴贴合有关。然后运行 Quick test，它会检查全部六个通道，并逐一报告通过或失败。这两项内容都可以在用户手册中找到。

下一步

准备好开始开发了吗？请从 Unity 项目设置开始；如果要编写脚本，请参阅 Python 指南。

核心概念

触觉触发方式

触发触觉有两种方式。你可以在自己的代码中引发事件，例如在触碰、抓握或松开时触发。也可以交给物理系统处理：在物体上放置碰撞体，接触发生时便会自动触发反馈。需要精确控制触发时机时使用事件；希望触碰直接生效时使用碰撞体。

基于碰撞体的触碰

HEXR 会在每个指尖和手掌上放置一个触发碰撞体。当其中任意一个进入触觉区域（带有 SpecialHaptics 的触发碰撞体）时，该区域的效果就会在对应手指上播放。这是一种免编码的方式：无需编写任何事件绑定，就能感受到场景中的物体。

执行器与手指

每只手套有六个柔性气动通道：五根手指和手掌。你可以按通道发送反馈，指定目标强度、达到目标的速度以及振动频率。超出范围的值会被限制到有效范围内，而不会被拒绝。

参数类型说明
fingerHaptics.Finger要驱动的通道：Thumb、Index、Middle、Ring、Pinky 或 Palm
intensityfloat 0.1–1目标压力，约 15–50 kPa。释放时发送 0
speedfloat 0.1–1升至目标强度的速度：1 表示尽快达到，0.1 表示慢十倍
frequency0.1–40 Hz仅用于振动：压力脉动的快慢。单纯的压力没有频率；0 也不表示关闭，而是会被限制为 0.1 Hz。Python 库最高支持 2 Hz

手部追踪

HEXR 本身不追踪手部，而是依赖头显的手部追踪功能，例如 Meta Quest 2/3/3S 或 PICO 4 / 4 Ultra。HEXR 在此追踪之上添加一层触觉反馈。其他设备请参阅平台与头显支持。

下一步

完整的 Unity 设置请阅读 Unity 集成，然后参阅 SDK 架构与 API，了解每个组件和方法。如果使用 Python，请从 Python 集成开始。