Microtube Meta Quest tutorial project
Sideload the finished demo, then open the same project in Unity and follow how every part of it works.
Try it on a headset first
Before installing anything, put the finished tutorial on your Quest and feel what you are about to build. This is the tutorial project, already built — no Unity, no compiling.
Download the Quest APK (84 MB) ↓
The scenes run and hand-tracking works without one, so you can look around and see how everything is put together — but nothing will actuate until a HEXR glove is paired.
Sideloading it
Quest headsets do not install APKs from a file manager; you push the build from a computer. Either tool works — SideQuest ↗ if you would rather click than type, or adb if you already have the Android platform tools:
adb install -r HexR-Developer-Tutorial-MetaOVR.apkBoth need Developer Mode enabled on the headset, which you turn on in the Meta Quest phone app under your headset's settings. Once installed, the app appears in your library under Unknown Sources rather than alongside your store apps — that catches most people out the first time.
Give the headset its Bluetooth permissions
Do this before you launch the app, whether you sideloaded it or built it yourself. The glove talks to the headset over Bluetooth Low Energy, and Android will not let an app discover a BLE device without location permission — a quirk of how Android treats BLE scanning, not something HEXR chose. Skip this and the app looks broken: it runs, but the glove never appears.
In the headset, go to Settings → Privacy and Security → App Permissions and set:
| Permission | Set to |
|---|---|
| Location | Precise — not just “allowed” |
| Nearby Devices | On |
“The app runs but the glove never connects.” It is almost always these two permissions. Check them first, before suspecting the hardware or your code.
Get the project
Clone the repository and open it in Unity 6 (6000.0 or newer):
This project’s floor is higher than the package’s. com.microtube.hexr itself runs on Unity 2022.3 and newer; it is the Meta XR SDK pinned here (com.meta.xr.sdk.all 205.0.0) that declares "unity": "6000.0" and sets the floor for this repository.
git clone https://github.com/MicrotubeTechnologies/HexR-Developer-Tutorial-Meta-OVR.gitThere is nothing to install afterwards. The HEXR package is already embedded in the project at Packages/com.microtube.hexr, so Unity picks it up the moment the project opens. You do not add it through Package Manager here — that step is for your own projects, and is covered in Unity integration.
You do need the Meta XR SDK, because this tutorial targets the Meta OVR backend and Unity's registry does not carry it. Add the free Meta XR All-in-One SDK ↗ to your Unity account, then install it from Package Manager → My Assets. If you would rather work in OpenXR, use the OpenXR tutorial ↗ instead.
How the project is laid out
Two folders matter. Everything else is set dressing.
| Where | What it holds |
|---|---|
Assets/Scenes/ | The tutorial scenes. This is where you start. |
Packages/com.microtube.hexr/ | The HEXR package itself — the rig prefabs, the components, and the HaptGlove runtime that talks to the hardware. Read it, do not edit it; in your own project this is a read-only dependency. |
Assets/Tutorial/Art/ | Models, materials and effects for the demo scenes — the hospital room, the fountain, the storm cloud. Nothing HEXR-specific. |
Assets/Tutorial/Scripts/ | Small helper scripts belonging to the demos rather than to HEXR. |
The useful habit: when a scene does something you want to reproduce, select the object and read its components in the Inspector. Every haptic behaviour in these scenes is a component on an object, not hidden code.
The scenes, and what each one teaches
| Scene | What it demonstrates |
|---|---|
| 1. Basic Tutorial | The place to start. Four objects, four different ways to trigger feedback: a foam block (haptic zone on a child object), a key (pinch, fired from an interactor event), a torch (palm grab, plus a vibrating flame zone) and a button (poke). |
| 2. Hospital Tutorial | The same ideas dressed as a realistic training scene — closer to what a real application looks like. |
| 3. Water Effects | Feedback driven by trigger volumes rather than grabbing: reach into the fountain or under the rain cloud and the zone drives the effect. |
| Meta Vs HexR Grab | A side-by-side of Meta's grab interactors against HEXR's own HexRGrabbable, so you can feel the difference before committing to one. |
Meta's interactors and HexRGrabbable both work, and they feel different — the physics and the haptic trigger points are not the same. Neither is the “right” one. Try the comparison scene and pick per object.
Connecting the glove
HEXR does not pair through the headset's Bluetooth settings, and there is no companion app. Your application opens the connection itself, which is why the permissions above matter.
Power on the arm module, then either press Connect on the in-scene HexR Panel — every tutorial scene has one — or call it yourself:
ConnectLeftBT(); // left hand
ConnectRightBT(); // right handEach hand is an independent connection with its own battery and its own state, so a working left hand tells you nothing about the right. Calibration & fit goes further.
Customising the haptics
Four routes, from “tick a box in the Inspector” to “drive the hardware directly”. They mix freely — most objects in the demos use more than one.
1. Make an object grabbable — HexRGrabbable
Add it to any object that also has a Collider set to trigger and a Rigidbody. Because the interaction is physics-based, the collider shape matters more than you expect — match it to the visible object or grabbing feels wrong.
| Setting | What it does |
|---|---|
| Type of Grab | Palm needs the palm and at least one finger; Pinch needs the thumb and at least one finger. Pick whichever matches how the real object would be held. |
| Gravity | Whether the object falls when released. |
| Haptic slider | Strength of the squeeze while held: 0 is off, 60 is maximum. |
| On Grab / On Release | UnityEvents, for driving sound, scoring or logic off the same interaction. |
2. Make a region feel like something — SpecialHaptics
A haptic zone is a trigger collider that plays a prepared sensation when a finger or palm enters it — the rain, the fountain spray and the torch flame in the demos are all this component. Add SpecialHaptics plus a trigger collider, press Find Hand Physics in the Inspector to wire it up, then choose an effect from the dropdown.
Size the collider to the sensation, not the mesh. The rain zone is a large soft volume; the flame is tight around the fire.
3. Fire haptics from an interaction event — Meta OVR
The two components above are physics-driven: a collider decides when something is being touched, so how good it feels depends on how well that collider matches the shape. Events sidestep that. Meta's interaction components raise UnityEvents at the exact moment a grab, pinch or poke is recognised, and you wire those straight to HEXR — no collider accuracy involved.
This is how the discrete interactions in 1. Basic Tutorial fire. Meta's PointableUnityEventWrapper turns an interactable's state changes into UnityEvents you can drop targets onto in the Inspector:
| Wire this event | To this method on PressureTrackerMain |
|---|---|
| When Select — grabbed, pinched or pressed | TriggerAllHapticsIncrease(float) — squeezes every finger and the palm to the pressure you pass, 0–1 |
| When Unselect — released | RemoveAllHaptics() — lets everything go |
Both are public and take either a single float or nothing at all, so they show up directly in the UnityEvent dropdown — there is no glue script to write. The same pair works from HexRGrabbable's own On Grab / On Release events if you are using HEXR's grabbing rather than Meta's.
They answer different questions. A zone answers “is a finger inside this region?” — right for surfaces and materials, like rain, foam or a flame. An event answers “has this object been grabbed?” — right for discrete actions, where firing at the exact instant matters more than precisely where the fingers are. The torch in the demo uses both: an event for the pickup, a zone for the flame.
Remember that TriggerAllHapticsIncrease still checks IsHandNear() internally, so an event alone is not enough if nothing is feeding that signal — see the warning below.
4. Drive the hardware yourself
For anything the components do not cover, call the runtime directly through HaptGloveHandler (namespace HaptGlove). Pressure is a squeeze; vibration is a texture:
// finger, on/off, intensity 0.1-1.0, speed 0.1-1.0
HEXRPressure(finger, true, 0.8f, 0.5f);
// finger, on/off, frequency 0.1-40.0, intensity 0.1-1.0,
// peakRatio 0.2-0.8, speed 0.1-1.0
HEXRVibration(finger, true, 12f, 0.6f, 0.5f, 0.5f);Every actuation is gated on whether HEXR thinks a hand is near the object. On Meta OVR that signal comes from the grab and poke interactors, so it is usually handled for you. On OpenXR it comes only from a ProximityCheck component — without one, the calls succeed and nothing moves. Run HexR → Validate Scene Setup; it flags exactly this.
Build settings
The project is already configured for Quest, so a fresh clone needs only the platform switch:
Switch to Android
File → Build Settings → Android → Switch Platform. First switch reimports every asset, so expect it to take a while.
Check the headset is connected
With Developer Mode on and the headset plugged in, it appears in the Run Device dropdown. Accept the “Allow USB debugging” prompt inside the headset — it is easy to miss with it on your face.
Build And Run
Builds, installs and launches in one step. Build alone gives you an APK to distribute instead.
For reference, these are the settings that make it a valid Quest build — useful when configuring a project of your own:
| Setting | Value |
|---|---|
| Minimum API level | Android 10 (API 29) |
| Target architecture | ARM64 only |
| XR plug-in provider | Oculus |
| Texture compression | ASTC |
The tutorial ships as com.Microtube.HexRTest under the product name “HexR Test”. Change the package name and product name in Player Settings before you distribute anything, or it will collide with other people's installs of this same demo.
Where to go next
Once the demos make sense, the reference material picks up:
| If you want to… | Read |
|---|---|
| Add HEXR to a project of your own | Unity integration |
| Understand what triggers feedback and when | Triggering feedback |
| Work with hand-tracking rigs | Working with hand-tracking |
| Look up a method or an event | Unity (C#) reference |
| Drive the glove without Unity | Python integration |
Stuck on something the docs do not answer? Talk to us — or open an issue on the tutorial repository ↗.