Getting started
haath is a zero-dependency WebXR hand tracking library. Create one Haath, call update() once per XR frame, and read hand signs, punches, slaps, claps, and other gestures from haath.state.
Install #
npm i @treefour/haathhaath ships ESM and CJS builds with TypeScript types. It has zero runtime dependencies, so it works with Three.js, IWSDK, Babylon.js, React Three Fiber, PlayCanvas, or a raw WebXR loop.
Request hand tracking #
Your XR session must ask for the hand-tracking feature:
navigator.xr.requestSession('immersive-vr', { optionalFeatures: ['hand-tracking'] });On Meta Quest, hand tracking also has to be on in the headset settings.
Three.js #
import { Haath } from '@treefour/haath';
const haath = new Haath();
let last = performance.now();
renderer.setAnimationLoop((_time, frame) => {
const now = performance.now();
const dt = (now - last) / 1000; // seconds
last = now;
if (frame) {
const session = renderer.xr.getSession();
const refSpace = renderer.xr.getReferenceSpace();
const state = haath.update(frame, refSpace, session?.inputSources, dt, now);
if (state.right.tracked && state.right.gesture === 'punch') {
console.log('right punch at', state.right.motionSpeed.toFixed(2), 'm/s');
}
if (state.twoHand.clap.doubleClap) openPauseMenu();
}
renderer.render(scene, camera);
});IWSDK (Meta Immersive Web SDK) #
This is how DunJun runs haath. Keep one instance on a system and let other systems read haath.state.
import { createSystem } from '@iwsdk/core';
import { Haath } from '@treefour/haath';
export class HandSystem extends createSystem({}) {
haath = new Haath({ punchSpeed: 1.3, slapSpeed: 1.8 });
update(delta: number) {
const xr = this.world.renderer.xr;
if (!xr.isPresenting) return;
const frame = xr.getFrame();
const session = xr.getSession();
if (!frame || !session) return;
// delta is seconds (IWSDK clock), which is what haath expects
this.haath.update(frame, xr.getReferenceSpace(), session.inputSources, delta);
}
}
// elsewhere: this.world.getSystem(HandSystem).haath.state.left.gestureEntry points #
@treefour/haath: theHaathengine (signs, strikes, circle, clap, triangle, blast),HoldRecognizer, colliders, vector math, constants, and types.@treefour/haath/v2: compositional engine with pose packs (including ASL), motion states, trajectory shapes, micro-gestures, and two-hand compounds.@treefour/haath/debug: DOM overlay with live signs, kinematics, and spells.@treefour/haath/emulator: PC hand emulator for desktop testing with IWER.
Next steps #
- Read the hand state: every field
update()returns. - Recipes: punch hits, hold-to-confirm menus, gun aim, spells.
- Examples: runnable apps, including one that needs no headset.