haathWebXR

Recipes

Short, tested patterns for the most common hand-tracked game mechanics. Each one reads haath.state after update() in the same frame.

Detect a punch or slap with momentum #

A fist moving faster than punchSpeed (1.3 m/s) becomes punch. An open hand faster than slapSpeed (1.8 m/s) becomes slap.

const hand = haath.state.right;
if (hand.gesture === 'punch' || hand.gesture === 'slap') {
  const mass = 1.5; // kg, tune per game
  applyHit(enemy, hand.velocity[0] * mass, hand.velocity[1] * mass, hand.velocity[2] * mass);
}

Hit enemies with the whole hand #

testHandSphere() tests a target sphere against the palm, wrist, and index tip spheres. It also tests a swept palm segment, so fast hands cannot pass through a target between frames. Create the options object once.

import { CollisionCooldownTracker, type HandSphereTestOptions } from '@treefour/haath';

const cooldown = new CollisionCooldownTracker(200); // ms per (target, hand, gesture)
const opts: HandSphereTestOptions = {
  mode: 'combat',                         // needs a non-idle gesture
  requiredGesture: ['punch', 'slap', 'poke'],
  cooldown,
};

for (const enemy of enemies) {
  opts.targetId = enemy.id;
  opts.prevTargetX = enemy.prev.x; opts.prevTargetY = enemy.prev.y; opts.prevTargetZ = enemy.prev.z;
  const part = haath.testHandSphere('right', enemy.pos.x, enemy.pos.y, enemy.pos.z, enemy.radius, opts);
  if (part !== 'none') damage(enemy, part); // 'palm' | 'wrist' | 'indexTip' | 'sweep'
}

Use mode: 'touch' (any tracked pose) for buttons and pickups.

Hold a sign to confirm #

HoldRecognizer fires once a value stays stable for a set time. It returns a 0 to 1 progress value for a loading ring.

import { HoldRecognizer } from '@treefour/haath';

const confirm = new HoldRecognizer<string>({ holdDurationMs: 1000, stabilityFrames: 10, cooldownMs: 800 });

// per frame (dt in seconds or ms, both accepted)
const hold = confirm.update(haath.state.right.sign === 'thumbsup' ? 'thumbsup' : null, dt);
progressRing.value = hold.progress;
if (hold.triggered) startGame();

It also works with numbers, for example confirm.update(haath.state.twoHand.fingerCount, dt) for finger-count menus.

Finger gun and pointer #

const r = haath.state.right;
if (r.sign === 'gun') fireBullet(r.aimOrigin, r.aimDirection);

aimOrigin and aimDirection come from the XR target ray and stay steady while fingers curl.

Circle spell and triangle laser #

import { intersectLaserSphere, intersectDiscSphere } from '@treefour/haath';

const c = haath.state.right.circle;
if (c.triggered) {
  spawnDisc(c.centroid, c.normal, c.meanRadius);
  haath.resetCircle('right'); // clear history so it cannot re-fire
}

const tri = haath.state.twoHand.triangle;
if (tri.active) {
  for (const e of enemies) {
    // origin, direction, length (m), beam width (m), target, target radius
    if (intersectLaserSphere(tri.centroid, tri.normal, 12, 0.25, e.posArray, e.radius)) burn(e);
  }
}

// Spinning disc vs enemy: position, normal, disc radius, tube thickness, target, radius
intersectDiscSphere(disc.pos, disc.normal, 0.3, 0.05, e.posArray, e.radius);

Circles are detected in any 3D plane: haath fits a plane to the wrist path, so vertical, flat, and tilted circles all count.

Two-palm blast #

const b = haath.state.twoHand.blast;
chargeBar.value = b.charge;
if (b.triggered) fireBlast(b.origin, b.direction);

Double clap to pause #

if (haath.state.twoHand.clap.doubleClap) togglePause();

The clap detector uses separate contact (0.17 m) and release (0.195 m) distances, so it stays reliable when the headset briefly loses one hand during a fast clap.

Last updated 2026-11-16