haathWebXR

Reading hand state

haath.update() returns haath.state, with left, right, and twoHand. It is the same object every frame, updated in place. Positions are in the reference space you pass in, in metres, with forward as -Z.

Per hand: state.left and state.right #

  • tracked: false when the hand is missing or fails the anatomical sanity check. Other fields keep their last values.
  • sign: static hand shape. One of open, fist, thehro (open palm up), niche (open palm down), gun, poke, pinch, thumb, thumbsup, thumbsdown, telephone (shaka), rock-horns, birdie-1, birdie-2, pinkie-out, unknown, idle.
  • gesture: the sign, promoted to punch (fist faster than punchSpeed) or slap (open hand faster than slapSpeed). Use this for combat.
  • fingers: { thumb, index, middle, ring, pinky, count } extension booleans plus a 0 to 5 count.
  • motionSpeed: speed in m/s, sampled at the ring finger tip so it captures arm swing and wrist whip.
  • velocity: [vx, vy, vz] in m/s.
  • wristPosition, palmPosition, palmCenter, indexTipPosition: Float32Array positions.
  • palmQuaternion: [x, y, z, w] at the index proximal joint.
  • palmForward: unit vector out of the fingers.
  • aimOrigin, aimDirection: a stable aim ray from the XR target ray. It stays steady during pinch and curl so it does not dip to the floor. Use it for guns and pointers.
  • circle: { triggered, centroid, normal, meanRadius, revolutions }. triggered is true on the frame a circle completes.

Sign table #

Fingers are listed as thumb, index, middle, ring, pinky. 1 is extended, 0 is curled, * is either.

  • fist: (*, 0, 0, 0, 0)
  • open, thehro, niche: (*, 1, 1, 1, 1), split by palm direction
  • gun: (*, 1, 1, 0, 0) or (1, 1, 0, 0, 0)
  • poke: (0, 1, 0, 0, 0)
  • rock-horns: (1, 1, 0, 0, 1)
  • telephone (shaka): (1, 0, 0, 0, 1)
  • pinkie-out: (0, 0, 0, 0, 1)
  • birdie-1: (0, 0, 1, 0, 0). birdie-2: (1, 0, 1, 0, 0)
  • pinch: index curled and thumb tip within pinchDist of the index tip
  • thumbsup, thumbsdown, thumb: only the thumb out, split by thumb direction

Finger extension uses bone-segment dot products, not wrist-to-tip distance. That makes signs work at any hand size, wrist angle, or arm reach.

Two hands: state.twoHand #

  • fingerCount: 0 to 10 extended fingers across tracked hands. Good for finger-count menus.
  • handsCrossed, wristDistance.
  • clap: { state, singleClap, doubleClap }. singleClap and doubleClap are true for one frame.
  • triangle: { active, centroid, normal }. Index tips together and thumbs together. normal always points away from the player (z <= 0).
  • blast: { active, triggered, charge, origin, direction }. Two palms pushed forward together, with charge from 0 to 1.

One-frame flags #

clap.singleClap, clap.doubleClap, circle.triggered, and blast.triggered are true for a single frame. Read them in the same frame you call update().

Last updated 2026-11-16