haathWebXR

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/haath

haath 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.gesture

Entry points #

  • @treefour/haath: the Haath engine (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.

Last updated 2026-11-16