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.