vr-helper-lib

A small, dependency-free helper library for web-based Virtual Reality (VR) with WebXR. Use it to check session support, work with stereo views and viewports, handle controllers, and read poses from XRFrame.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Subpath Imports
• API Reference
• License

Features

• Zero dependencies — Pure JavaScript; no runtime or peer dependencies.
• Session — Check for immersive-vr support, request default session options.
• Views — Viewport for each XRView, stereo left/right, projection and view matrices.
• Controllers — Input sources by handedness, gamepad, trigger/squeeze, hand tracking.
• Pose — Viewer pose, target-ray and grip poses, position/orientation/matrix from transforms.
• Subpath exports — Import only what you need.

Requirements

• Node.js 14+ (for tooling); in the browser, use a WebXR-capable environment (e.g. Chrome with VR headset).

Installation

npm install vr-helper-lib

Quick Start

const {
  isImmersiveVRSupported,
  getDefaultVRSessionOptions,
  getViewportForView,
  getViewerPose,
  getInputSourceByHandedness,
  getPositionFromTransform,
  isTriggerPressed,
} = require('vr-helper-lib');

// Check if VR is available
const supported = await isImmersiveVRSupported();
if (!supported) return;

// Request session (use with navigator.xr.requestSession)
const options = getDefaultVRSessionOptions();
// const session = await navigator.xr.requestSession('immersive-vr', options);

// In your XR frame loop:
// const viewerPose = getViewerPose(frame, referenceSpace);
// for (const view of viewerPose.views) {
//   const viewport = getViewportForView(view);
//   // set viewport and render with view.projectionMatrix, view.transform.matrix
// }

// Controllers
// const leftController = getInputSourceByHandedness(session, 'left');
// if (leftController && isTriggerPressed(leftController)) { ... }
// const gripPose = getGripPose(frame, leftController, referenceSpace);
// const pos = getPositionFromTransform(gripPose.transform);

Subpath Imports

const session = require('vr-helper-lib/session');
const views = require('vr-helper-lib/views');
const controllers = require('vr-helper-lib/controllers');
const pose = require('vr-helper-lib/pose');

API Reference

session — vr-helper-lib/session

| Function | Description | |----------|-------------| | isBrowser() | Whether running in a browser. | | isWebXRAvailable() | Whether navigator.xr exists. | | isImmersiveVRSupported() | Promise: immersive-vr supported. | | isSessionSupported(mode) | Promise: support for 'inline', 'immersive-vr', 'immersive-ar'. | | REFERENCE_SPACE_TYPES | Object of reference space type names. | | getDefaultVRSessionOptions(overrides?) | Default options for requesting immersive-vr session. |

views — vr-helper-lib/views

| Function | Description | |----------|-------------| | EYE | Object: NONE, LEFT, RIGHT. | | getViewportForView(view, scale?) | Viewport { x, y, width, height } for an XRView. | | getViewportsForViewerPose(viewerPose, scale?) | { left, right } viewports. | | iterateViewerViews(viewerPose, scale?) | Generator of { view, viewport, eye }. | | getProjectionMatrix(view, out?) | Float32Array 4×4 from view.projectionMatrix. | | getViewMatrix(view, out?) | Float32Array 4×4 from view.transform.matrix. |

controllers — vr-helper-lib/controllers

| Function | Description | |----------|-------------| | HANDEDNESS | NONE, LEFT, RIGHT. | | BUTTON_INDICES | TRIGGER, SQUEEZE_GRIP, THUMBSTICK, etc. | | AXIS_INDICES | THUMBSTICK_X/Y, TOUCHPAD_X/Y. | | getInputSourceByHandedness(session, handedness) | Left or right controller. | | getInputSources(session) | All input sources. | | getGamepad(inputSource) | Gamepad from input source. | | hasGripSpace(inputSource) / hasTargetRaySpace(inputSource) | Pose availability. | | isHandTracking(inputSource) | Whether source is hand. | | isTriggerPressed(inputSource) | Button 0 pressed. | | isSqueezePressed(inputSource) | Button 1 (grip) pressed. |

pose — vr-helper-lib/pose

| Function | Description | |----------|-------------| | getViewerPose(frame, referenceSpace) | Viewer pose for the frame. | | getTargetRayPose(frame, inputSource, referenceSpace) | Pointing ray pose. | | getGripPose(frame, inputSource, referenceSpace) | Controller grip pose. | | getPositionFromTransform(transform) | [x, y, z] from XRRigidTransform. | | getOrientationFromTransform(transform) | [x, y, z, w] quaternion. | | getMatrixFromTransform(transform, out?) | 4×4 Float32Array. | | isPoseEmulated(pose) | Whether pose has emulated position. |

License

MIT © vr-helper-lib