Registry / web-framework / webvr-polyfill

webvr-polyfill

library0.10.12jsnpmunverified

The `webvr-polyfill` library provides a comprehensive JavaScript implementation of the WebVR 1.1 specification, designed to ensure WebVR content functions consistently across a wide array of platforms, regardless of native browser or device WebVR support. Its primary function is to inject a WebVR 1.1 API if absent, patch browsers with incomplete or inconsistent implementations, and offer a synthesized `CardboardVRDisplay` on mobile when native support is missing. The current stable version is 0.10.12, with a release cadence that has slowed as the ecosystem transitions towards the WebXR Device API. A key differentiator is its ability to provide a baseline VR experience by abstracting away fragmented native support, including head tracking orientation prediction to minimize motion-to-photon latency and reduce VR sickness. The project aims to allow developers to target the WebVR API without extensive browser-specific workarounds.

web-framework

npm install webvr-polyfill

github ↗package ↗

INSTALL

IMPORT

SIG · WEBVR-POLYFILL

webvr-polyfill

web-frameworkjavascriptv0.10.12

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

WebVRPolyfill

✓ import WebVRPolyfill from 'webvr-polyfill';

✗ import { WebVRPolyfill } from 'webvr-polyfill';

The library uses a default export for its main constructor in ES modules.

WebVRPolyfill

✓ const WebVRPolyfill = require('webvr-polyfill');

✗ const { WebVRPolyfill } = require('webvr-polyfill');

For CommonJS environments, the module exports the constructor directly as the default export.

WebVRPolyfill (Global)

✓ <script src='webvr-polyfill.js'></script> // WebVRPolyfill is now a global variable

When included via a <script> tag, the `WebVRPolyfill` constructor becomes available as a global variable. No explicit import statement is needed.

Instantiates the WebVRPolyfill with optional custom configuration, then demonstrates how to query for VR displays using `navigator.getVRDisplays()`, adapting the experience based on whether a VR display is found or synthesized.

import WebVRPolyfill from 'webvr-polyfill'; // Example configuration (refer to src/config.js for full options) const polyfillConfig = { // Scales the buffer size for rendering. Lower values improve performance. BUFFER_SCALE: 0.5, // Set to true to disable mobile VR display if you only want native VRDisplays. PROVIDE_MOBILE_VRDISPLAY: true }; // Instantiate the polyfill before any VR-specific code runs const polyfill = new WebVRPolyfill(polyfillConfig); let vrDisplay; navigator.getVRDisplays().then(displays => { if (displays.length) { vrDisplay = displays[0]; console.log(`Using VRDisplay: ${vrDisplay.displayName}`); console.log("WebVR display found or polyfilled. Proceed with VR experience."); // For a full VR experience, you'd typically integrate with a rendering loop: // vrDisplay.requestAnimationFrame(animate); // requires a 'renderer' and 'animate' function } else { console.log("No WebVR displays found. Consider desktop-oriented controls or a non-VR fallback."); } }).catch(error => { console.error("Error getting VR displays:", error); });

Debug

Known issues

breakingVersion 0.10.0 introduced significant internal refactoring, including potential changes to previously 'scope-creeping' functionalities. Code written for versions `<=0.9.x` may require updates.

fix

Consult the `0.9.40 tag` documentation on GitHub for older versions and review `src/config.js` for current configuration options.

affects: >=0.10.0

breakingChrome versions M65 and M66 introduced regressions in `devicemotion` events, specifically affecting `rotationRate`. M65 broke head tracking due to missing data, and M66 changed `DeviceMotionEvent.rotationRate` values from radians to degrees, impacting calculation accuracy.

fix

Ensure you are using `webvr-polyfill@0.10.3` or later, which includes a hotfix for these Chrome regressions. Validate `devicemotion` event handling and coordinate systems in your application.

affects: >=0.10.3

gotchaVR performance is critical; sluggish applications can result from default settings. The `BUFFER_SCALE` configuration property, which defaults to 0.5, can significantly impact performance if set higher.

fix

Adjust `BUFFER_SCALE` to a lower value if experiencing performance issues, especially on lower-end devices. Profile your application to identify bottlenecks.

affects: >=0.1.0

gotchaEmbedding polyfilled WebVR content within iframes introduces specific concerns and caveats, potentially affecting device motion access and overall functionality due to browser security restrictions.

fix

Refer to the `cardboard-vr-display README` on GitHub for detailed information and recommended workarounds regarding iframe usage with the polyfill.

affects: All versions

gotchaHigh motion-to-photon latency (typically >150ms) can induce VR sickness. While the polyfill provides head tracking orientation prediction, developers should be aware of this potential issue if prediction is insufficient or disabled.

fix

Leverage the polyfill's head tracking orientation prediction feature. Optimize rendering pipelines and JavaScript execution to minimize overall latency. Consider target device capabilities.

affects: All versions

Errors

Common errors & fixes

Head tracking is broken or erratic in Chrome.

Chrome M65/M66 introduced regressions in `devicemotion` event handling, causing missing `rotationRate` data or incorrect units (degrees instead of radians).

fix

Upgrade `webvr-polyfill` to version `0.10.3` or higher to include the necessary hotfixes for `devicemotion` event processing.

My VR scene spins uncontrollably or has an incorrect initial orientation.

This often occurs due to misinterpretation of `DeviceMotionEvent.rotationRate` values. Specifically, Chrome M66 changed the units from radians to degrees.

fix

Ensure you are using `webvr-polyfill@0.10.3` or later. This version correctly handles the change in units for `rotationRate` values, preventing rotational inaccuracies.

Upgrade

Version history

0.10.12latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/immersive-web/webvr-polyfill ↗

packagehttps://www.npmjs.com/package/webvr-polyfill ↗