Unity scene setup

Put hands and the HEXR rig in your scene, and connect the gloves.

What a HEXR scene needs

Four things. Your XR SDK supplies the hands; HexR → Create HexR Rig adds the rest in one go.

Build a new scene

Quickest: HexR → Create Demo Scene makes a ready-to-try scene with the rig, a haptic sphere and a cube you can grab. It can’t add hands, so do step 1 below, then run HexR → Troubleshoot → Re-run Auto Setup.

Or build it yourself:

1. Add hands

   HEXR attaches to hands that are already in the scene; it doesn’t make its own. Add a rig that puts them in the Hierarchy:

   Backend	Add this
   Meta OVR	Meta → Tools → Building Blocks → Interactions Rig. Not the Hand Tracking block: its hands only appear once the app runs, too late for HEXR
   OpenXR or PICO	In Window → Package Manager → XR Interaction Toolkit → Samples, import Hands Interaction Demo and drag its XR Origin Hands (XR Rig) prefab into the scene. Delete the scene’s Main Camera — the rig has its own

   Check: search the Hierarchy for OpenXRLeftHand (Meta) or L_Wrist (OpenXR). If nothing comes up, there are no hands yet.

2. Add the HEXR rig

   Run HexR → Create HexR Rig → your backend. It adds HexR Main and the Pressure Controllers, then runs Auto Setup, which puts touch points on the hands.

3. Validate

   Run HexR → Troubleshoot → Validate Scene Setup and fix anything it lists. It catches mistakes that would otherwise look like a broken glove.

4. Connect a glove

   Power on the arm module. In a headset build, press Connect Left Glove or Connect Right Glove on the HexR menu. In the Unity Editor on Windows, press Play and connect from HexR → HexR Tools → HexR Haptics Tester. The first time on a headset, allow the Bluetooth permission — see Allow Bluetooth on the headset.

If Auto Setup can’t find something

• “Couldn’t find a tracked hand” — the scene has no hands yet. Do step 1, then run HexR → Troubleshoot → Re-run Auto Setup. Re-run it whenever you change the hands.
• “Couldn’t auto-find” the interactors (Meta) — drag your rig’s left-hand Hand Grab Interactor and Poke Interactor onto the matching fields of the Left Pressure Controller, and the right-hand ones onto the Right.
• Added Meta’s Hand Tracking block? Delete its two [BuildingBlock] Hand Tracking objects, add the Interactions Rig instead, and re-run Auto Setup.

Adding HEXR to an existing project

1. Install the package

   Follow Project setup. Install from the git URL — don’t copy HEXR folders out of a tutorial project, which gives you duplicate code and a compile error. Moving up from an older HEXR? Read the changelog first.

2. Check your hands

   HEXR finds your rig’s hands by their joint names, so they need to come from Meta’s Interaction SDK or Unity’s XR Hands (the names are in The HEXR scene). Search the Hierarchy for OpenXRLeftHand (Meta) or L_Wrist (OpenXR). Nothing there? Your hands only appear once the app runs — see step 1 of Build a new scene.

3. Add the rig to the scene your app starts in

   Run HexR → Create HexR Rig → your backend. It adds HexR Main and the Pressure Controllers, and Auto Setup puts touch points on your existing hands and wires your grab and poke interactors. Your camera rig, hands and objects stay as they are. Then run HexR → Troubleshoot → Validate Scene Setup.

4. Add Pressure Controllers to every other scene

   HexR Main carries over when a scene loads and finds that scene’s hands by itself, but each scene needs its own pair of Pressure Controllers: run HexR → Add Pressure Controller in each one.

5. Make your objects felt

   Put HexRInteractableHaptics next to the interactables you already have — XR Grab Interactable on OpenXR, or Meta’s Grabbable and Hand Grab Interactable. For anything else, see Which component do I need?

The HexR menu

The panel that floats in the headset. Its main job is connecting the gloves over Bluetooth. It comes with the rig, to the user’s left and facing them; press its buttons with a real fingertip. To add it to a scene of your own, use HexR → Add HexR Menu.

Using your own menu instead

You don’t have to use the HexR menu. From SDK 0.9.4, HEXR works without it, so you can connect from your own buttons or straight from code and leave it out. These are the calls, all on 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

A ready-made script for your own buttons. Put it on any object, point each UI Button’s On Click () at one of its four methods, and wire Status Changed to a text field to show what is happening.

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");
}

To connect as soon as the scene starts, with no button at all, use Connect both gloves from code. Every connection event is listed under Events.

Put the app on the headset

Build straight from Unity, or install an APK file. Either way, the headset needs developer mode first.

Turn on developer mode

Once per headset.

Then plug the headset into your computer with a USB cable and accept the Allow USB debugging prompt inside the headset.

From Unity

With the headset plugged in, go to File → Build Profiles → Android → Switch Platform, then press Build And Run. Unity installs the app and starts it. To get an APK file to share instead, press Build.

From an APK file

• SideQuest (Quest and PICO) — a free desktop app. Plug in the headset, then use its install-APK button or drag the file onto it. Get SideQuest ↗
• Meta Quest Developer Hub (Quest only) — Meta’s own desktop tool for installing and managing apps. Meta Quest Developer Hub ↗
• adb (Quest and PICO) — from a terminal, with Android’s platform-tools ↗ installed:

adb install -r YourApp.apk

Finding it on the headset: installed apps don’t sit with your store apps. On Quest, open the app library and choose Unknown Sources; on PICO, look in the Library’s unknown-sources filter.

Allow Bluetooth on the headset

The first time the app connects a glove, the headset asks for permission to use Bluetooth. Allow it. If it is refused, the app keeps running but never finds the glove. The HexR menu and HexRManager.Instance.Connect(...) both ask for it for you.