GameCrew AIEarly access
Sign in
Three.jsvrCompile-verified pattern

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.

  • vr
  • xr
  • webxr
  • hands
  • hand tracking
  • fingers
  • grip
  • grab
  • grabbable
  • throw
  • socket
  • haptics
  • locomotion
  • comfort
  • threejs

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 (Δ p_i, Δ t_i) (dropping sample $n - 1$ if \|v_n-1\| < 0.35 \|v_n-2\| after a fast swing): $v_throw = fracΣ_i=0^m-1 (i + 1) fracΔ p_iΔ t_iΣ_i=0^m-1 (i + 1)$
  • Aim-Weighted Pull Cone: Inside cone half-angle θ_max, score candidates by 4(1 - cosθ) + 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)

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 ≤ 200 and Triangles ≤ 300k: 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

Playable Three.js games made with GameCrew

Launch a real browser build using this engine and inspect its controls or fork its project tree.

More Three.js techniques

optimization

Instanced Wind Foliage, Object-Pooled Particles & Spring Feel in Three.js →

Single-draw-call THREE.InstancedMesh wind foliage with player bend, zero-GC pooled burst particles, and dt-invariant second-order springs that keep 60 Hz steps under 2 ms.

atmosphere

Raymarched Volumetric Clouds & Atmospheric Sky Shaders in Three.js (WebGL 2) →

Self-contained THREE.ShaderMaterial sky dome in GLSL ES 3.0 raymarching a height-bounded cloud layer with 3D value-Worley FBM, Beer-Powder silver lining, interleaved gradient noise, and mobile step scaling.

physics

BVH Mesh & Character Capsule Collision in Three.js →

Fast capsule-vs-triangle pushout and slope resolution using three-mesh-bvh shapecasts, pre-allocated scratch vectors, and CollisionWorld.

ai

Zero-Allocation Context Steering, Patrol Loops & Telegraphed AI in Three.js →

Deterministic 60 Hz enemy and companion AI in Three.js using 8-slot context steering against CollisionWorld, level.json patrol loops, attack-token pacing, and telegraphed strikes.

Use verified techniques inside a real game

Describe your game idea for free or connect an MCP assistant to search and contribute techniques.

Learn about collaboration