# Physical 6DoF VR Hand Interactions, Throw Windows & Spatial Comfort in Three.js

> Tactile 6DoF WebXR hand interactions in Three.js using game.xr: the kit's articulated hands (controller-posed and tracked, fingers closing on held things), near-grab + distance-pull cones, 6-step sliding-window throws, snap sockets, 3D world buttons, and flat+VR parity.

- **Canonical page:** https://gamecrew.ai/techniques/three/vr-interactions-ergonomics
- **Techniques hub:** https://gamecrew.ai/techniques
- **Engine:** Three.js
- **Category:** vr
- **Tags:** `vr`, `xr`, `webxr`, `hands`, `hand tracking`, `fingers`, `grip`, `grab`, `grabbable`, `throw`, `socket`, `haptics`, `locomotion`, `comfort`, `threejs`
- **Verification:** Compile-verified pattern

## When to Use & Field Best Practices

Three.js VR games in the studio run on **`game.xr`** (`Assets/CCGD/kit/xr.ts` + `xr-interact.ts`) so one URL plays flat on desktop/phone and offers **Enter VR** in headset browsers with zero external CDN imports:
1. **Ergonomic Reach & Distance-Pull Cone**: Place interactive props `0.75 – 1.55 m` off the floor (`local-floor`) and register them via `game.xr.grabbable(mesh, { reach: 0.24, pullDistance: 2.4 })` so seated and standing players alike can pull distant items cleanly into their grip.
2. **6-Step Sliding-Window Throw Physics**: `game.xr.handVelocity(side)` weights 6 simulation steps of hand motion and discards a trailing release-frame tracking stall (`< 35%` of prior speed), giving thrown props predictable, responsive velocity via `onRelease(side, linVel, angVel)`.
3. **Headset Frame-Loop & Comfort Rules**: Always drive logic from `game.onUpdate(dt)` (never `window.requestAnimationFrame`, which headsets suspend during an `immersive-vr` session!), avoid pointer-lock or screen-space `EffectComposer` passes while `game.xr.active`, and gate flat camera shake behind `if (!game.xr.active)`.
4. **Real Hands, Never Primitives**: every VR game already draws articulated, skinned hands (`xr-hands.ts`): posed from the controller's trigger, grip and thumb touches, or from 25 tracked joints. Pick each grabbable's grip so the fingers close on its surface and it sits in the palm: `grip: 'power'` (handles, torches, sticks: they turn to lie along the hand), `'sphere'` (balls, fruit), `'pinch'` (coins, keys, berries). Restyle with `game.xr.handStyle({ material: 'glove' | 'ghost', tone })` instead of hiding the hands and gluing spheres and capsules under `hand.grip`. Read `hand.pinching` / `hand.grabbing` or `game.xr.onHand(e => ...)` for gestures (they work the same for tracked hands), and poke with `hand.tip('index')`.
5. **Dual Flat + VR Controls**: Pass `flatAction: 'interact'` on `game.xr.button3d` (or check `game.input.pressed('interact')`) and document the `VR` column in `README.md` (`| Action | Keys | VR |`).

## Mathematical & Algorithmic Core

- **Recency-Weighted Throw Window**: Across up to 6 steps $(\Delta \mathbf{p}_i, \Delta t_i)$ (dropping sample $n - 1$ if $\|\mathbf{v}_{n-1}\| < 0.35 \|\mathbf{v}_{n-2}\|$ after a fast swing):
  $$\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)}$$
- **Aim-Weighted Pull Cone**: Inside cone half-angle $\theta_{\max}$, score candidates by $4(1 - \cos\theta) + 0.15 d$ so pointing directly at a prop wins over a closer peripheral prop.

## Engine Implementation

### Grabbable Core, Snap Pedestal, Tactile 3D Button & Diegetic World Panel (`Assets/Game/vrStation.ts`)

```ts
import * as THREE from 'three';
import type { Game, WorldPanel, XrGrabbable, XrSocket, XrWorldButton } from 'ccgd';

export interface VrStationHandle {
  readonly grabbable: XrGrabbable;
  readonly socket: XrSocket;
  readonly button: XrWorldButton;
  readonly panel: WorldPanel;
  readonly velocity: THREE.Vector3;
  activations: number;
  dispose(): void;
}

export function createVrStation(
  game: Game,
  coreMesh: THREE.Object3D,
  pedestalAnchor: THREE.Object3D,
  buttonCap: THREE.Object3D
): VrStationHandle {
  const velocity = new THREE.Vector3();
  let flying = false;
  let statusText = 'Dock Core';

  const panel = game.xr.panel({ width: 0.56, height: 0.22, pxPerMetre: 900 });
  panel.object.position.set(
    pedestalAnchor.position.x,
    pedestalAnchor.position.y + 0.45,
    pedestalAnchor.position.z
  );
  game.scene.add(panel.object);

  const redrawPanel = (): void => {
    panel.draw((p) => {
      p.panel(0, 0, p.w, p.h);
      p.text('REACTOR CONSOLE', 24, 26, { size: 28, color: 'muted' });
      p.text(statusText, 24, 78, { size: 44, color: 'accent' });
    });
  };
  redrawPanel();

  const grabbable = game.xr.grabbable(coreMesh, {
    tag: 'reactor-core',
    grip: 'sphere',
    reach: 0.24,
    pullDistance: 2.4,
    pullConeDeg: 16,
    throwScale: 1.15,
    onGrab: () => {
      flying = false;
      velocity.set(0, 0, 0);
      game.audio.play('pickup');
    },
    onRelease: (_side, linVel) => {
      if (!grabbable.socket) {
        velocity.copy(linVel);
        flying = true;
      }
    },
  });

  const socket = game.xr.socket(pedestalAnchor, {
    radius: 0.24,
    acceptTag: 'reactor-core',
    onSnap: () => {
      flying = false;
      velocity.set(0, 0, 0);
      statusText = 'Core Locked';
      redrawPanel();
    },
    onUnsnap: () => {
      statusText = 'Dock Core';
      redrawPanel();
    },
  });

  let activations = 0;
  const button = game.xr.button3d(buttonCap, {
    radius: 0.11,
    rayDistance: 2.4,
    travel: 0.018,
    flatAction: 'interact',
    onPress: () => {
      if (game.xr.active && !socket.occupant) return;
      activations++;
      statusText = `Online x${activations}`;
      game.audio.play('confirm');
      redrawPanel();
    },
  });

  let disposed = false;
  game.onUpdate((dt: number) => {
    if (disposed) return;
    if (flying && !grabbable.heldBy && !grabbable.socket) {
      velocity.y -= 9.81 * dt;
      coreMesh.position.addScaledVector(velocity, dt);
      if (coreMesh.position.y < 0.2) {
        coreMesh.position.y = 0.2;
        velocity.set(0, 0, 0);
        flying = false;
      }
    }
  });

  return {
    grabbable,
    socket,
    button,
    panel,
    velocity,
    get activations() {
      return activations;
    },
    set activations(v: number) {
      activations = v;
    },
    dispose() {
      disposed = true;
      grabbable.dispose();
      socket.dispose();
      button.dispose();
      panel.dispose();
    },
  };
}
```

## Performance & Comfort Traps

- **Keep Stereo Calls $\le 200$ and Triangles $\le 300\text{k}$**: Batch repeated props with `THREE.InstancedMesh` and use analytical shadows or simple unlit contact blobs instead of multi-cascade shadow maps.
- **Hands Are Already Budgeted**: the kit's two hands are 2 draw calls and about 18k triangles; a hand-built glove of spheres and capsules costs more draw calls and looks worse. Keep `castShadow` lights few: each shadow-casting light draws the hands again.
- **No Raw DOM Overlays Without World Counterparts**: Any HUD info added to `ui.root` is invisible inside a headset unless mirrored via `GameUI` or `game.xr.panel(...)` / `game.xr.label(...)`.

## Verification Checklist

1. Hands: `xr.sim.trackHand('right', 'pinch')` then `t.ok(xr.hands.right.pinching, ...)`; after a grab, `t.ok(xr.hands.right.holding === coreMesh, ...)` and check `xr.hands.right.tip('index')` is outside the held thing's surface.
2. Write a `test(...)` in `Assets/Game/Tests/play/` using `t.game.xr.sim.enter()`, `sim.reach('right', coreMesh.position)`, `sim.press('right-squeeze')`, `sim.reach('right', pedestalAnchor.position)`, `sim.release('right-squeeze')`, and `sim.reach('right', buttonCap.position)` asserting `socket.occupant === grabbable` and `station.activations === 1`.
3. Run `compile`, `test_play`, `capture`, and `audit_game` to verify stereo VR captures (`vr.png`, `vr_menu.png`) and zero comfort or lint warnings.

## Official references

- Valve Half-Life: Alyx Distance Pull & Hand Ergonomics (GDC 2020)
- Meta Quest WebXR Performance & Comfort Guide
- Three.js WebXR Stereo Rendering Notes
