# 3. XR Controller Haptics on Quest
Part of [[Haptics and Controller Rumble]]. Previous: [[2. Gamepad Rumble Service and Patterns]]. Next: [[4. Routing Combat Feel Events to Haptics]].
> [!warning] Code not compiled
> `XRHapticPatternPlayer` and `XRHaptics` use XRI 3.4 `HapticImpulsePlayer` and `HapticsUtility`. Not compiled and not felt on a Quest 2.
> [!note] Version
> For Quest 2 use **Unity 6.3 LTS (6000.3.27f2+)** as in [[0.Choosing a Unity Version]]. On 6000.3 the XRI package page lists 3.3.2 as released with 3.4.x to 3.7.0 available; these notes use the **3.4** API pages. The same pattern assets from part 2 work in both your 6000.5 gamepad projects and 6.3 LTS Quest projects.
## 3.1 Three ways to send an impulse
| Layer | API | Use when |
|---|---|---|
| XRI component | `HapticImpulsePlayer.SendHapticImpulse(amplitude, duration[, frequency])` on each controller | You have an XRI rig (you do). Respects `amplitudeMultiplier` |
| XRI static helper | `HapticsUtility.SendHapticImpulse(amplitude, duration, HapticsUtility.Controller.Left/Right/Both, frequency = 0, channel = 0)` | Quick one-offs from anywhere |
| OpenXR action | `OpenXRInput.SendHapticImpulse(actionRef, amplitude, duration)` / `StopHaptics` | You bound a Haptic output action yourself |
| Legacy XR | `UnityEngine.XR.InputDevice.SendHapticImpulse(channel, amplitude, duration)` | Non-XRI projects; the docs note duration "only supported on Oculus" |
This series uses the XRI component, so one multiplier on the rig controls everything.
## 3.2 No-code: SimpleHapticFeedback
For interaction feedback (hover, select, activate) XRI ships **Simple Haptic Feedback** (`UnityEngine.XR.Interaction.Toolkit.Feedback.SimpleHapticFeedback`):
1. Select the **Near-Far Interactor** (or Direct/Ray) under a controller in the XR Origin.
2. Add **Simple Haptic Feedback** if the rig does not already have it, and set its **Haptic Impulse Player** to the controller's Haptic Impulse Player (Starter Assets rigs include one per controller; exact rig contents vary by XRI version, **unverified** for yours).
3. Enable **Play Select Entered** with amplitude 0.3, duration 0.05 for grabs; optionally **Play Hover Entered** at 0.1.
That covers grabbing ([[4. Grab Interactables and Throwing]]) with no code. Note: poke interactors do not derive from the input interactor base in XRI 3.x, so haptics for poke buttons go through the code path below (see [[5. Poke Buttons and Pinch Grabs Alongside Controllers]]).
## 3.3 One-off impulses: XRHaptics.cs
```csharp
using UnityEngine.XR.Interaction.Toolkit.Inputs.Haptics;
/// <summary>Tiny wrapper so gameplay code reads well. Not compiled in Unity.</summary>
public static class XRHaptics
{
public static void Tick(HapticsUtility.Controller hand) =>
HapticsUtility.SendHapticImpulse(0.25f, 0.03f, hand);
public static void Thump(HapticsUtility.Controller hand) =>
HapticsUtility.SendHapticImpulse(0.8f, 0.12f, hand);
}
```
Example: `XRHaptics.Tick(HapticsUtility.Controller.Right);` when a poke button is pressed by the right controller.
## 3.4 Patterns as impulse trains: XRHapticPatternPlayer.cs
A Quest controller takes "amplitude A for D seconds". To play a curve, send a stream of short impulses whose durations slightly overlap, re-sampling the curve each time. A new impulse replaces the running one on most runtimes **(unverified for Quest 2 over OpenXR)**, which is what makes this work.
```csharp
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.XR.Interaction.Toolkit.Inputs.Haptics;
/// <summary>
/// Plays HapticPattern assets on one XR controller through its HapticImpulsePlayer.
/// Voices mix by maximum, like the gamepad service. Put one on each controller. Not compiled in Unity.
/// </summary>
public sealed class XRHapticPatternPlayer : MonoBehaviour
{
public enum Hand { Left, Right }
[SerializeField] Hand hand;
[SerializeField] HapticImpulsePlayer impulsePlayer;
[Range(0f, 1f)] [SerializeField] float masterIntensity = 1f;
[SerializeField] bool hapticsEnabled = true;
[Tooltip("Seconds between impulses while a pattern plays.")]
[SerializeField, Range(0.01f, 0.1f)] float step = 0.03f;
[Tooltip("Each impulse lasts step * overlap so there is no gap between them.")]
[SerializeField, Range(1f, 2f)] float overlap = 1.5f;
static readonly Dictionary<Hand, XRHapticPatternPlayer> players = new Dictionary<Hand, XRHapticPatternPlayer>();
struct Voice { public HapticPattern pattern; public float elapsed; public float scale; public bool loop; public int handle; }
readonly List<Voice> voices = new List<Voice>(4);
float sinceImpulse;
int nextHandle = 1;
bool paused;
public static XRHapticPatternPlayer For(Hand hand) => players.TryGetValue(hand, out var p) ? p : null;
/// <summary>Set to false while the user is hand tracking (no actuator).</summary>
public bool ControllerActive { get; set; } = true;
public float MasterIntensity { get => masterIntensity; set => masterIntensity = Mathf.Clamp01(value); }
public bool HapticsEnabled { get => hapticsEnabled; set { hapticsEnabled = value; if (!value) voices.Clear(); } }
void OnEnable() => players[hand] = this;
void OnDisable()
{
if (players.TryGetValue(hand, out var p) && p == this) players.Remove(hand);
voices.Clear();
}
void Reset() => impulsePlayer = GetComponentInParent<HapticImpulsePlayer>();
public int Play(HapticPattern pattern, float scale = 1f, bool loop = false)
{
if (pattern == null || !hapticsEnabled || !ControllerActive || impulsePlayer == null) return 0;
int h = nextHandle++;
voices.Add(new Voice { pattern = pattern, scale = Mathf.Max(0f, scale), loop = loop, handle = h });
sinceImpulse = step; // send on this frame
return h;
}
public void Stop(int handle)
{
for (int i = voices.Count - 1; i >= 0; i--)
if (voices[i].handle == handle) voices.RemoveAt(i);
}
public void SetPaused(bool value)
{
paused = value;
if (value && impulsePlayer != null) impulsePlayer.SendHapticImpulse(0f, 0.01f); // cut the current impulse
}
void Update()
{
if (paused || voices.Count == 0) return;
float dt = Time.unscaledDeltaTime;
float amplitude = 0f;
float frequency = 0f;
for (int i = voices.Count - 1; i >= 0; i--)
{
Voice v = voices[i];
v.elapsed += v.pattern.unscaledTime ? dt : Time.deltaTime;
float n = v.elapsed / v.pattern.duration;
if (n >= 1f)
{
if (!v.loop) { voices.RemoveAt(i); continue; }
v.elapsed %= v.pattern.duration;
n = v.elapsed / v.pattern.duration;
}
float a = v.pattern.XRAmplitude(n) * v.scale;
if (a > amplitude) { amplitude = a; frequency = v.pattern.xrFrequency; }
voices[i] = v;
}
sinceImpulse += dt;
if (sinceImpulse < step) return;
sinceImpulse = 0f;
amplitude = Mathf.Clamp01(amplitude * masterIntensity);
if (amplitude <= 0.001f) return;
float duration = step * overlap;
if (frequency > 0f) impulsePlayer.SendHapticImpulse(amplitude, duration, frequency);
else impulsePlayer.SendHapticImpulse(amplitude, duration);
}
}
```
Explanations:
- **Step and overlap:** 30 ms steps with 45 ms impulses give a continuous feel at 72/90 Hz frame rates. Shorter steps cost nothing measurable but some runtimes may round very short durations **(unverified)**.
- **`For(Hand)`** gives the router (part 4) a simple lookup without finding objects.
- **`ControllerActive`**: set it from the input modality (see 3.5) so patterns are not sent to a controller lying on the desk.
- **The `HapticImpulsePlayer` multiplier** (`amplitudeMultiplier`) applies on top of `masterIntensity`; keep it at 1 and use the settings in part 5.
- **Pause** sends a tiny zero-amplitude impulse to cut a running one; `OpenXRInput.StopHaptics` is the explicit alternative if you use OpenXR actions.
## 3.5 Hands versus controllers
From [[2. Hands and Controllers Rig with Input Modality Manager]]: the **XR Input Modality Manager** switches the rig between hand and controller GameObjects. Hook it so haptics only go to controllers:
```csharp
using UnityEngine;
/// <summary>
/// Tells the XR haptic players whether a physical controller is in use.
/// Call from the XR Input Modality Manager's tracked/untracked UnityEvents. Not compiled in Unity.
/// </summary>
public sealed class HapticsModalityHook : MonoBehaviour
{
[SerializeField] XRHapticPatternPlayer leftPlayer;
[SerializeField] XRHapticPatternPlayer rightPlayer;
public void OnLeftControllerModeStarted() => leftPlayer.ControllerActive = true;
public void OnLeftControllerModeEnded() => leftPlayer.ControllerActive = false;
public void OnRightControllerModeStarted() => rightPlayer.ControllerActive = true;
public void OnRightControllerModeEnded() => rightPlayer.ControllerActive = false;
}
```
When hands are active, replace haptics with a sound and a visual (the hand-tracking parts already press poke buttons visibly).
## 3.6 Check
- [ ] Grabbing an interactable gives a short tick (SimpleHapticFeedback).
- [ ] A 0.45 s knockdown pattern feels continuous, not like a series of clicks.
- [ ] Two overlapping patterns: the stronger wins.
- [ ] With hands tracked, no haptic calls are made.
## Sources
- XRI 3.4 `HapticImpulsePlayer`: https://docs.unity3d.com/Packages/
[email protected]/api/UnityEngine.XR.Interaction.Toolkit.Inputs.Haptics.HapticImpulsePlayer.html
- XRI 3.4 `HapticsUtility`: https://docs.unity3d.com/Packages/
[email protected]/api/UnityEngine.XR.Interaction.Toolkit.Inputs.Haptics.HapticsUtility.html
- XRI 3.4 `HapticsUtility.Controller`: https://docs.unity3d.com/Packages/
[email protected]/api/UnityEngine.XR.Interaction.Toolkit.Inputs.Haptics.HapticsUtility.Controller.html
- XRI 3.4 `SimpleHapticFeedback`: https://docs.unity3d.com/Packages/
[email protected]/api/UnityEngine.XR.Interaction.Toolkit.Feedback.SimpleHapticFeedback.html
- XRI 3.4 `XRBaseInputInteractor.SendHapticImpulse`: https://docs.unity3d.com/Packages/
[email protected]/api/UnityEngine.XR.Interaction.Toolkit.Interactors.XRBaseInputInteractor.html
- OpenXR 1.16 `OpenXRInput` (`SendHapticImpulse`, `StopHaptics`): https://docs.unity3d.com/Packages/
[email protected]/api/UnityEngine.XR.OpenXR.Input.OpenXRInput.html
- `InputDevice.SendHapticImpulse` (6000.3): https://docs.unity.com/en-us/engine/6000.3/script-reference/unityengine/xr/inputdevice/sendhapticimpulse
- XRI on 6000.3: https://docs.unity.com/en-us/engine/6000.3/manual/packages-list/packages-all/pack-safe/com-unity-xr-interaction-toolkit