SDK Architecture & API

How the HEXR Unity SDK is put together, how the glove connects, how interactions become haptics, and how to drive the glove from your own code.

Package structure

The package is a stack. Your scene talks to the top; the glove sits at the bottom. The two backend layers only compile when their XR SDK is installed, and the core never depends on them.

Backends register themselves with the core when they load. The collider visualizer, HexRUsable and the HexR menu stay in the global namespace so older scenes keep working.

The HEXR scene

HexR → Create HexR Rig adds the first two. Your XR SDK provides the third.

The tracked hand

HexRTrackedHand.handRoot points at your SDK’s hand. HEXR finds the joints by name:

Each touch point is a small trigger collider, a kinematic Rigidbody (Unity needs one for trigger events) and a HapticFingerTrigger that says which hand and finger it is. HEXR has no hand of its own: since 0.9 the touch points sit on the tracked hand on every backend. An older project with a “ghost” hand can remove it with HexR → Migration → Remove Ghost Hand.

Connecting the glove

Your app opens the Bluetooth connection itself. No pairing in system settings, no companion app. Each glove has its own HaptGloveHandler.

• Only one hand scans at a time; the second glove waits for the first.
• On Android a failed attempt is retried with a growing delay for up to a minute, and a glove that drops out is reconnected. Pressing the menu’s Connect again cancels a retry; Connect(hand) never does.
• Disconnecting, quitting and pausing release the glove first. See Releasing the glove.

The whole list, headsets included, is in Platform & headset support.

Events

Public UnityAction fields on HaptGloveHandler. Subscribe with += and unsubscribe with -=. Never assign with =: that removes the handlers HexRManager relies on. They are not UnityEvents, so they do not show in the Inspector.

How haptics fire

Latency

The time from an event in your app to a sensation is three delays added together. They are listed separately because only the last one is set by the glove; the other two depend on your setup.

End-to-end latency — from your event to the moment the user feels it — has not been measured for the current glove, and no figure for it is published here. If your application depends on it, measure it on your own setup.

The hand-near check

A Pressure Controller sends most haptics only while IsHandNear() is true. Any one of these makes it true:

The three results are public fields on each PressureTrackerMain: HandGrabbing, PokeHovering and CollisionNearHand. The check itself, IsHandNear(), is private. It is per hand: one signal anywhere opens it for every gated call on that hand.

Releases are checked too when they go through a checked call: RemovePinchPressure(), and CustomSingleHaptics with false as the last argument, are dropped if the hand has already left. Release with RemoveAllHaptics(), a Remove…Haptics() call, or true as the last argument.

If your call does nothing, select the Pressure Controller, switch the Inspector to Debug and watch its three flags, or pass true as ByPassHandCheck while testing.

Channels and parameters

Six channels: Haptics.Finger.Thumb, Index, Middle, Ring, Pinky, Palm. Each plays one mode at a time. Values outside a range are clamped.

The scene components show their strength on a 10–60 scale — 10 is barely there, 60 is firm — and convert it to the 0.1–1 intensity above. Use PressureTrackerMain.StrengthToIntensity(strength) to do the same in your own code.

Releasing the glove

The glove keeps its last command until it is told otherwise; nothing on it lets go by itself. What the package does about that:

Scene components

Most projects never call the API. These components fire haptics on their own.

Which component do I need?

Using components together

The hand-near check is per hand, not per object: a grab, hover or ProximityCheck anywhere opens it for every gated call on that hand.

C# API

Call these when you want haptics driven by your own logic.

PressureTrackerMain — on each Pressure Controller

HexRManager — HexRManager.Instance

HaptGloveHandler — one per glove, namespace HaptGlove

HexRTrackedHand and FingerUseTracking — on each hand

Scene changes and editor tools

Your SDK’s hands die with their scene; the rig lives on. So after every scene load the manager re-attaches:

Then the log says [HexR] Rebound Left hand … 6 haptic trigger(s): five fingertips and the palm.

Auto Setup does the same in the Editor so it is saved with the scene. It only adds what is missing and never moves a collider you tuned. Run it from Create HexR Rig, HexR → Troubleshoot → Re-run Auto Setup, or the manager’s Auto Set Up HexR button. Validate Scene Setup then reports anything still unwired.

Type index

Every public type in com.microtube.hexr, for looking a name up. Where a section above covers it, the link goes there.

Components

Enums and values

Backend plumbing, editor and internals

Python

Outside Unity, HaptGlovePython builds the same commands; you write them with bleak. It needs Python 3.8 to 3.13. Setup and a tested example are in the Python guide.

Copy-paste examples

Whole scripts for the jobs that come up first. Each one compiles against com.microtube.hexr 0.9.4. Feeling an object while it is grabbed needs no code at all: put HexRInteractableHaptics on it.

Connect both gloves from code

No HexR menu needed. Put it on any object in the scene. In the Editor, connect from the HexR Haptics Tester instead — see Connecting the glove.

using UnityEngine;
using HaptGlove;
using HexR;

// Connects both gloves when the scene starts -- no HexR menu needed --
// and logs each one as it comes up or drops.
public class ConnectGloves : MonoBehaviour
{
    void Start()
    {
        HexRManager rig = HexRManager.Instance;
        rig.leftHand.onBluetoothConnected += OnConnected;
        rig.rightHand.onBluetoothConnected += OnConnected;
        rig.leftHand.onBluetoothDisconnected += OnDisconnected;
        rig.rightHand.onBluetoothDisconnected += OnDisconnected;

        // Does nothing for a glove that is already connected or connecting.
        rig.Connect(HaptGloveHandler.HandType.Left);
        rig.Connect(HaptGloveHandler.HandType.Right);
    }

    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) { Debug.Log(hand + " glove connected"); }
    void OnDisconnected(HaptGloveHandler.HandType hand) { Debug.Log(hand + " glove disconnected"); }
}

Press a finger on your own event

Drag a Pressure Controller into Hand, then wire Press and Release to any UnityEvent.

using UnityEngine;
using HaptGlove;
using HexR;

// Wire Press() and Release() to any UnityEvent: a button, a trigger, an
// animation event. Strength is on the same 10-60 scale as the components'.
public class PressOnEvent : MonoBehaviour
{
    public PressureTrackerMain hand;                  // a Pressure Controller
    public Haptics.Finger finger = Haptics.Finger.Index;
    [Range(10f, 60f)] public float strength = 30f;

    bool pressing;

    public void Press()
    {
        float intensity = PressureTrackerMain.StrengthToIntensity(strength);
        // true skips the hand-near check: this press answers your event, not a touch.
        hand.CustomSingleHaptics(finger, true, intensity, 1f, true);
        pressing = true;
    }

    public void Release()
    {
        if (!pressing) return;
        hand.CustomSingleHaptics(finger, false, 0f, 1f, true);
        pressing = false;
    }

    // Disabled, or the scene changes, mid-press: let go as well.
    void OnDisable() { Release(); }
}

Press the finger that touches an object

On any object with a trigger collider. HapticFingerTrigger on the touch point says which hand and finger touched, so it needs no Pressure Controller of its own.

using System.Collections.Generic;
using UnityEngine;
using HexR;

// On a trigger collider: presses exactly the finger or palm that touches it,
// on the hand it belongs to, and releases it when it leaves.
[RequireComponent(typeof(Collider))]
public class PressWhereTouched : MonoBehaviour
{
    [Range(0.1f, 1f)] public float intensity = 0.5f;

    readonly HashSet<HapticFingerTrigger> touching = new HashSet<HapticFingerTrigger>();

    void OnTriggerEnter(Collider other)
    {
        if (!other.TryGetComponent(out HapticFingerTrigger touch)) return;
        touch.TriggerFixPressure(intensity);   // 0.1-1, skips the hand-near check
        touching.Add(touch);
    }

    void OnTriggerExit(Collider other)
    {
        if (!other.TryGetComponent(out HapticFingerTrigger touch)) return;
        touch.RemoveHaptics();
        touching.Remove(touch);
    }

    // Disabled while a finger is inside: release what is still pressed.
    void OnDisable()
    {
        foreach (HapticFingerTrigger touch in touching)
        {
            if (touch != null) touch.RemoveHaptics();
        }
        touching.Clear();
    }
}

Release on reconnect

A glove whose link dropped is still pressing whatever it was told last. This releases it as soon as it is back.

using UnityEngine;
using HaptGlove;
using HexR;

// A glove whose Bluetooth link dropped keeps its last pressure. When it
// reconnects, release everything before anything else is sent.
public class ReleaseOnReconnect : MonoBehaviour
{
    void Start()
    {
        HexRManager.Instance.leftHand.onBluetoothConnected += ReleaseAll;
        HexRManager.Instance.rightHand.onBluetoothConnected += ReleaseAll;
    }

    void OnDestroy()
    {
        if (HexRManager.Instance == null) return;
        HexRManager.Instance.leftHand.onBluetoothConnected -= ReleaseAll;
        HexRManager.Instance.rightHand.onBluetoothConnected -= ReleaseAll;
    }

    void ReleaseAll(HaptGloveHandler.HandType hand)
    {
        HaptGloveHandler glove = hand == HaptGloveHandler.HandType.Left
            ? HexRManager.Instance.leftHand
            : HexRManager.Instance.rightHand;
        glove.ReleaseAllChannels();
    }
}

Where to go next

Integrating into an existing app? Start with HexRInteractableHaptics before the lower-level PressureTrackerMain or HaptGloveHandler.