# Physical 6DoF VR Hand Interactions, Throw Windows & Spatial Comfort in Godot 4

> Physical 6DoF VR hand interactions in Godot 4 using GameXR and XRInteract: the kit's articulated hands (controller-posed and hand-tracked, pinch and grab with hysteresis, power/pinch/sphere grip poses), near-grab + distance-pull cones, 6-step sliding-window throws, snap holsters, 3D buttons, teleport + smooth + seated comfort, and flat+VR parity.

- **Canonical page:** https://gamecrew.ai/techniques/godot/vr-interactions-ergonomics
- **Techniques hub:** https://gamecrew.ai/techniques
- **Engine:** Godot 4
- **Category:** vr
- **Tags:** `vr`, `xr`, `webxr`, `hands`, `hand tracking`, `fingers`, `pinch`, `grip pose`, `grab`, `grabbable`, `throw`, `socket`, `haptics`, `locomotion`, `teleport`, `seated`, `comfort`
- **Verification:** Compile-verified pattern

## When to Use & Field Best Practices

Godot 4 VR games in the studio run through **`GameXR`** (`Assets/CCGD/xr/game_xr.gd` + `xr_interact.gd` — never instantiate `XROrigin3D` or set `get_viewport().use_xr = true` yourself!). Physical 6DoF interactions turn flat button-prompts into tactile presence while preserving flat-screen play on the same URL:
1. **Human Reach & Distance-Pull Cone**: Place levers, orbs, and switches at `0.75 – 1.55 m` above the floor (`local-floor`), and use `GameXR.grabbable(node, {"reach": 0.24, "pull_distance": 2.4})` so seated players can point-and-squeeze to pull distant items smoothly into their palm.
2. **6-Step Sliding-Window Throws**: `GameXR.velocity(side)` and `XRInteract.Grabbable` weight 6 physics steps of hand grip motion and automatically drop a trailing zero-motion stall frame when the player opens their fingers, giving `RigidBody3D` throws crisp, predictable arcs.
3. **Zero Forced Camera Tilt**: Gate all flat camera trauma/shake behind `if not GameXR.active():` so the headset horizon stays rock-steady (`TURN = "snap"` + comfort vignette).
4. **Simulated Headset Playtests**: Verify every grab, throw, holster snap, and 3D button press deterministically via `var xr := GameXR.sim(); await xr.enter(); xr.reach("right", item.global_position)`.
5. **The Kit's Hands Are the Player's**: Every VR game gets articulated, skinned hands (`XRHand`): posed from the controller (grip curls middle/ring/pinky, trigger curls the index, analog and smoothed), following every joint of a tracked bare hand, and closing onto whatever they hold. Never draw a placeholder hand or parent a model to the grip to stand in for one; style them instead with `GameXR.hands({"style": "glove"})` (`"skin"`, `"glove"`, `"ghost"`; `"tone"` for skin).
6. **Grip Poses Per Object**: Give each grabbable a real `CollisionShape3D` and a grip: `"power"` (handles, tools, rods: a fist wraps it), `"pinch"` (keys, gems, seeds: thumb and index tips), `"sphere"` (balls, fruit, orbs: spread curved fingers). `"auto"` picks from the shape's size. The object comes to the palm or the fingertips; the fingers stop at its surface.
7. **Bare Hands Need No Buttons**: With hand tracking, a pinch is the trigger and a fist is the grip (each with hysteresis: a pinch starts under 18 mm between the tips and ends only past 32 mm), so every action, menu and grab works; listen to `pinch_started` / `grab_started` on `GameXR.rig()` for gestures.
8. **Comfort Choices**: Offer `"move": "both"` (left stick walks with a vignette, right stick teleports, right stick snap-turns), `"teleport"` and `"stick"`, and a seated toggle (`GameXR.seated(true)` raises the view to standing height). Change them live by calling `GameXR.locomotion(...)` again from a comfort panel.

## Mathematical & Algorithmic Core

- **Weighted Sliding-Window Linear Velocity** (dropping a release-frame stall when $v_{n-1} < 0.35 v_{n-2}$ and $v_{n-2} > 1.2\text{ m/s}$):
  $$\mathbf{v}_{\text{throw}} = \frac{\sum_{i=0}^{m-1} (i + 1) \frac{\Delta \mathbf{p}_i}{\Delta t_i}}{\sum_{i=0}^{m-1} (i + 1)}$$
- **Distance-Pull Cone Selection**: Score candidates inside $\arccos(\hat{\mathbf{d}}_{\text{ray}} \cdot \hat{\mathbf{u}}) \le \theta_{\text{cone}}$ by $S = 4(1 - \cos\theta) + 0.15 d$ so aim precision beats raw distance when two props sit near each other.

## Engine Implementation

### Grabbable Power Cell, Holster Socket & Tactile 3D Switch (`Assets/Game/Scripts/gameplay/vr_workbench.gd`)

```gdscript
class_name VRWorkbench
extends Node3D

var grab_item: XRInteract.Grabbable
var holster_socket: XRInteract.Socket
var confirm_btn: XRInteract.WorldButton
var activations: int = 0


func setup_station(cell_node: Node3D, socket_anchor: Node3D, button_cap: Node3D) -> void:
	if cell_node != null:
		grab_item = GameXR.grabbable(cell_node, {
			"tag": "power_cell",
			"reach": 0.24,
			"pull_distance": 2.4,
			"pull_cone_deg": 16.0,
			"throw_scale": 1.15,
		})
	if socket_anchor != null:
		holster_socket = GameXR.socket(socket_anchor, {
			"radius": 0.24,
			"accept_tag": "power_cell",
		})
	if button_cap != null:
		confirm_btn = GameXR.button_3d(button_cap, {
			"radius": 0.12,
			"ray_distance": 2.5,
			"travel": 0.018,
		})
		confirm_btn.pressed.connect(_on_button_pressed)


func _on_button_pressed(_side: String) -> void:
	activate_station()


func activate_station() -> bool:
	if holster_socket != null and holster_socket.occupant == null and GameXR.active():
		return false
	activations += 1
	return true


func teardown_station() -> void:
	if grab_item != null:
		grab_item.dispose()
		grab_item = null
	if holster_socket != null:
		holster_socket.dispose()
		holster_socket = null
	if confirm_btn != null:
		confirm_btn.dispose()
		confirm_btn = null
```

### The Hands Holding Things & Gestures (`Assets/Game/Scripts/gameplay/vr_tools.gd`)

```gdscript
extends Node3D

var lantern: XRInteract.Grabbable
var gem: XRInteract.Grabbable


func setup(lantern_body: RigidBody3D, gem_body: RigidBody3D) -> void:
	# a handle: a fist wraps it, the lantern hangs from the palm
	lantern = GameXR.grabbable(lantern_body, {"grip": "power", "reach": 0.22})
	# a small gem: held between the thumb and index tips
	gem = GameXR.grabbable(gem_body, {"grip": "pinch", "reach": 0.15})
	GameXR.hands({"style": "glove"})
	var r := GameXR.rig()
	if r != null:
		r.pinch_started.connect(_on_pinch)


func _on_pinch(side: String) -> void:
	var h := GameXR.hand(side)
	# a bare-hand pinch near the gem's socket casts; the pinch point is between the thumb and index tips
	if h.source == "hand" and h.pinch_point.distance_to(global_position) < 0.3:
		Playtest.log_event("cast", side)


func comfort(move: String, seated: bool) -> void:
	var player := get_tree().get_first_node_in_group("player")
	GameXR.locomotion({"body": player, "move": move, "turn": "snap"})
	GameXR.seated(seated)
```

## Performance & Comfort Traps

- **Mobile/WebGL Rendering Budget**: Keep standalone headset scenes under `200` draw calls and `300k` triangles with zero screen-space post effects (`SSAO`, `SSR`, `SDFGI`, `Glow`).
- **World-Space UI Sizing**: Use `GameUI` (automatically projected onto world panels in VR) or `GameXR.panel(control, {"width": 0.75, "pixels": Vector2i(900, 450)})` with font sizes $\ge 32\text{ px}$.
- **Hands Are Cheap, Keep Them So**: Each hand is one skinned mesh (about 2.4k triangles, one draw call) with a light skin shader; don't add per-finger lights or particles to them. Fingers wrap analytic shapes (sphere, box, capsule, cylinder), so prefer those over concave meshes on grabbables.
- **Dispose Station Handles on Scene Unload**: Call `.dispose()` (or let `_prune_invalid()` clean freed `Node3D` targets) when despawning dynamic stations.

## Verification Checklist

1. Write a `GameTest` play test using `GameXR.sim()` (`enter()`, `reach("right", cell.global_position)`, `press("right-squeeze")`, `reach("right", socket_anchor.global_position)`, `release("right-squeeze")`) asserting `holster_socket.occupant == grab_item`.
2. For each grabbable, a second test with a tracked bare hand: `xr.track_hand("right", "open")`, move the item to `GameXR.hand("right").pinch_point` (pinch grip) or the grip (power/sphere), then `xr.track_hand("right", "pinch")` or `"fist"`, and assert `g.held_by == "right"` and `GameXR.hand("right").visual.holding()`.
3. Run `compile`, `test_play`, and `audit_game` to confirm zero `vr-own-rig` lint errors, clean comfort checks, and a complete `VR` column in `README.md`.

## Official references

- Valve Half-Life: Alyx Distance Pull & Hand Ergonomics (GDC 2020)
- Meta Quest Spatial Comfort Guidelines
- Godot 4 WebXR & SubViewport World UI Reference
