# WebXR Hand Tracking & Controller Parity in Godot 4

> Unified Quest bare-hand tracking and controller input in Godot 4 using GameXR pinch/grab hysteresis, fingertip poke, and button_3d.

- **Canonical page:** https://gamecrew.ai/techniques/godot/webxr-hand-tracking-quest-browser
- **Techniques hub:** https://gamecrew.ai/techniques
- **Engine:** Godot 4
- **Category:** vr
- **Tags:** `webxr`, `vr`, `hand-tracking`, `quest`, `pinch`, `grab`, `haptics`
- **Verification:** Compile-verified pattern

## When to Use & Field Best Practices

Quest players launch WebXR games with bare hands, Touch controllers, or switch between both mid-session without reloading. Building interactions only on raw `XRController3D` buttons breaks bare-hand players, while assuming 25 skeletal joints leaves controller users stuck:

1. **Let `GameXR` Own the Rig & Skinned Hands**: Never instantiate a second `XROrigin3D` or `XRController3D`. Configure locomotion and articulated hands once via `GameXR.locomotion(...)` and `GameXR.hands(...)`.
2. **Use `pinching` / `grabbing` + `pinch_point` Parity**: With controllers, `GameXR.Hand.pinching` tracks the trigger and `grabbing` tracks grip squeeze. With tracked bare hands, both use filtered joint hysteresis automatically — no special-case branches required.
3. **Add Subtle Tactile Feedback Safely**: Call `hand.pulse(strength, seconds)` on hover/snap; on bare hands it safely no-ops without errors, while controllers buzz crisply.

## Mathematical & Algorithmic Core

- **Pinch Activation Point**:
  $$\mathbf{p}_{\text{pinch}} = \begin{cases} \frac{1}{2}(\mathbf{p}_{\text{thumb\_tip}} + \mathbf{p}_{\text{index\_tip}}), & \text{tracked bare hand} \\ \mathbf{p}_{\text{grip}}, & \text{controller} \end{cases}$$
- **Reach Distance Gate**: Clamp grab radius around `0.18–0.26 m` on handles (`"power"`), balls (`"sphere"`), or tiny tokens (`"pinch"`) so fingers close cleanly onto the object mesh.

## Engine Implementation

### Dual-Mode Hand Interaction Rig (`Assets/Game/Scripts/gameplay/xr_relic_bench.gd`)

```gdscript
extends Node3D
## Demonstrates Quest bare-hand + controller parity via GameXR signals, fingertip poke, and grabbable grips.

@export var relic_mesh: Node3D
@export var chime_pad: Node3D

var _right_pinching_last := false
var _last_source := "none"


func _ready() -> void:
	GameXR.locomotion({"speed": 2.2, "turn": "snap", "vignette": true})
	GameXR.hands({"style": "glove", "tone": "medium"})

	var rig := GameXR.rig()
	rig.pinch_started.connect(_on_pinch_started)
	rig.grab_started.connect(_on_grab_started)

	if relic_mesh != null:
		var item := GameXR.grabbable(relic_mesh, {
			"grip": "pinch",
			"reach": 0.22,
		})
		item.grabbed.connect(func(side: String) -> void:
			GameXR.hand(side).pulse(0.45, 0.03)
		)

	if chime_pad != null:
		var pad_btn := GameXR.button_3d(chime_pad, {
			"radius": 0.12,
		})
		pad_btn.pressed.connect(func(side: String) -> void:
			GameXR.hand(side).pulse(0.6, 0.04)
		)


func _process(_delta: float) -> void:
	if not GameXR.active():
		return
	var right := GameXR.hand("right")
	if right.tracked and right.source != _last_source:
		_last_source = right.source

	# Smooth continuous pinch tracking works identically for tracked fingers and analog triggers
	if right.pinching and not _right_pinching_last:
		var tip := right.joint("index-finger-tip").origin
		if relic_mesh != null and tip.distance_to(relic_mesh.global_position) < 0.25:
			right.pulse(0.35, 0.025)
	_right_pinching_last = right.pinching


func _on_pinch_started(side: String) -> void:
	var h := GameXR.hand(side)
	if h.tracked:
		var _pinch_world := h.pinch_point
		h.pulse(0.25, 0.02)


func _on_grab_started(side: String) -> void:
	GameXR.hand(side).pulse(0.4, 0.03)
```

## Headset & Desktop Budgets

- **Single WorldEnvironment & Mobile Compatibility Profile**: Keep draw calls compact (`<= 200`) and avoid full-screen blur filters in WebXR so stereo rendering holds 72+ Hz in Quest Browser.
- **Flat Play Parity**: Always test interactions with mouse/keyboard fallback so desktop testers can pick up, poke, and complete every objective.

## Verification Checklist

1. Drive `GameXR.sim().track_hand("right", "pinch")` and `GameXR.sim().reach("right", ...)` in a headless VR test and assert `grab` and `pinch_started` fire without script errors.
2. Confirm switching between `"controller"` and `"hand"` `source` preserves continuous grab state.

## Official references

- WebXR Hand Input Module Level 1 Specification
- GameCrew Godot XR Kit Reference
