haathWebXR

PC hand emulator

@treefour/haath/emulator lets you play and debug hand-tracked WebXR apps on a desktop, without a headset. It drives IWER emulated hands, and adds a floating panel per hand, keyboard control, and finger poses IWER does not ship: fist, horns, thumbs up and down, shaka, and a two-finger gun.

Real recognition still runs. The emulator poses IWER's joints, so haath.update() classifies them like real hands.

Setup #

IWSDK apps already run IWER in dev through @iwsdk/vite-plugin-iwer. In any other app, install IWER first and switch it to hands:

import { XRDevice, metaQuest3 } from 'iwer';
import { DevUI } from '@iwer/devui';

const device = new XRDevice(metaQuest3);
device.installRuntime({ forceInstall: true }); // desktop Chrome has a native navigator.xr
device.primaryInputMode = 'hand';
new DevUI(device);

Then attach the emulator:

import { createHandEmulator } from '@treefour/haath/emulator';

if (import.meta.env.DEV) {
  const emu = createHandEmulator({
    getSession: () => renderer.xr.getSession(),
    hooks: {
      onPose: (target, pose, gesture, fingerCount) => { /* target: 'left' | 'right' | 'both' */ },
      onStrike: (hand, kind, velocity) => { /* animated strike started */ },
      onStrikeEnd: (hand, gesture) => { /* hand returned to its held pose */ },
      onClap: () => { /* Double Clap button */ },
      onCircleStart: (hand) => {},
      onCircle: (hand, gesture) => { /* circle trace finished */ },
      onResetToOpen: () => {},
    },
  });
  // emu.setPose('thumbs_up', 'right'); emu.triggerClap(); emu.resetToOpenPalm(); emu.destroy();
}

The panels appear only while the session has hand input sources. Hooks are optional. Use them when game logic needs a gesture faster than velocity promotion gives it, for example mapping onClap to a pause overlay.

Keys #

Keys are KeyboardEvent.code values. Override any map with keyMap: { move, hold, strike }.

  • Left hand: W A S D move. Hold 1 punch, 2 slap, 3 poke, 4 gun, Q thumbs up, E thumbs down, R horns, T shaka.
  • Right hand: arrow keys move. Hold U punch, I slap, O poke, P gun, J thumbs up, K thumbs down, L horns, ; shaka.
  • Hold a key to keep a pose. Releasing it restores the previous pose. Clicking a chip in the panel keeps the pose until you click it again.
  • Punch, slap, and poke are static stances. The hand holds a fist, open palm, or pointed finger and reports the strike gesture, and you steer it into targets with the move keys. Animated lunges are available through triggerStrike() or the keyMap.strike map.
  • Movement starts at 0.3 m/s and speeds up to 1.5 m/s while you hold the key (moveSpeed: { min, max, rampSeconds }). Travel is clamped by moveLimit (0.8 m).
  • Shift + WASD and Shift + arrows stay with IWER DevUI for headset movement.

Options #

  • getSession() (required): returns the active XRSession or null.
  • hooks: the callbacks above, all optional.
  • gestureMap: override the gesture string reported for each pose. See DEFAULT_EMULATOR_GESTURE_MAP.
  • keyMap: partial { move, hold, strike } maps. See DEFAULT_EMULATOR_KEYMAP.
  • moveSpeed, moveLimit: movement tuning.
  • debug: log [HaathEmu] lines to the console.

Hands move by driving the IWER DevUI transform handle, so the gizmo, target ray, and IWER position readout follow the hand.

Try it #

Example 04 runs a Three.js scene with IWER and the emulator in a desktop browser.

Last updated 2026-11-16