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 Dmove. Hold1punch,2slap,3poke,4gun,Qthumbs up,Ethumbs down,Rhorns,Tshaka. - Right hand: arrow keys move. Hold
Upunch,Islap,Opoke,Pgun,Jthumbs up,Kthumbs down,Lhorns,;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 thekeyMap.strikemap. - 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 bymoveLimit(0.8 m). Shift+WASDandShift+ arrows stay with IWER DevUI for headset movement.
Options #
getSession()(required): returns the activeXRSessionor null.hooks: the callbacks above, all optional.gestureMap: override the gesture string reported for each pose. SeeDEFAULT_EMULATOR_GESTURE_MAP.keyMap: partial{ move, hold, strike }maps. SeeDEFAULT_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.