WebXR Gamepads Module - Level 1

Editor’s Draft,

More details about this document
This version:
https://immersive-web.github.io/webxr-gamepads-module/
Latest published version:
https://www.w3.org/TR/webxr-gamepads-module-1/
Feedback:
GitHub
Editors:
(Google)
(Google [Mozilla until 2020])
(Meta)
Former Editor:
(Amazon [Microsoft until 2018])
Participate:
File an issue (open issues)
Mailing list archive
W3C’s #immersive-web IRC

Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

Abstract

This specification module describes support for accessing button, trigger, thumbstick, and touchpad data associated with virtual reality (VR) and augmented reality (AR) devices on the Web.

Status of this document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document was published by the Immersive Web Working Group as an Editors' Draft. This document is intended to become a W3C Recommendation. Feedback and comments on this specification are welcome. Please use Github issues. Discussions may also be found in the public-immersive-web-wg@w3.org archives.

Publication as an Editors' Draft does not imply endorsement by W3C and its Members. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 03 November 2023 W3C Process Document.

This WebXR Gamepads Module is designed as a module to be implemented in addition to WebXR Device API, and was originally included in WebXR Device API which was divided into core and modules.

1. Introduction

Hardware that enables Virtual Reality (VR) and Augmented Reality (AR) applications are now broadly available to consumers, offering an immersive computing platform with both new opportunities and challenges. The ability to interact directly with immersive hardware is critical to ensuring that the web is well equipped to operate as a first-class citizen in this environment. The WebXR Gamepads module adds interfaces and behaviors to the WebXR Device API and the Gamepads API to allow for querying the state of buttons, triggers, thumbsticks, and touchpads available as input sources on many WebXR compatible devices.

This module is an addition to the WebXR Device API.

1.1. Terminology

This document uses the acronym XR throughout to refer to the spectrum of hardware, applications, and techniques used for Virtual Reality, Augmented Reality, and other related technologies. Examples include, but are not limited to:

The important commonality between them being that they offer some degree of spatial tracking with which to simulate a view of virtual content.

Terms like "XR Device", "XR Application", etc. are generally understood to apply to any of the above. Portions of this document that only apply to a subset of these devices will indicate so as appropriate.

XR Devices often have additional controller hardware that allows users to interact with immersive experiences with button, trigger, thumbstick, or touchpad inputs. Frequently these devices are spatially tracked as well, and referred to as "motion controllers", "handheld controllers", or "tracked controllers".

2. WebXR Device API Integration

As defined in the WebXR Device API API, an XRInputSource represents an XR input source, which is any input mechanism which allows the user to perform targeted actions in the same virtual space as the viewer. Example XR input sources include, but are not limited to, handheld controllers, optically tracked hands, and gaze-based input methods that operate on the viewer's pose.

This document outlines the behavior of an XRInputSource when it has button, trigger, thumbstick, or touchpad data to report. This is commonly a motion controller, but may also be headset with buttons, triggers, thumbsticks, or touchpads on the XR device. As stated in the WebXR device API, input mechanisms which are not explicitly associated with the XR Device, such as traditional gamepads, MUST NOT be considered XR input sources.

2.1. XRInputSource

Button, trigger, thumbstick, and touchpad data is reported though a Gamepad object exposed on the XRInputSource it is associated with.

partial interface XRInputSource {
  [SameObject] readonly attribute Gamepad? gamepad;
};

The gamepad attribute is a Gamepad that describes the state of any buttons and axes on the XR input source. If the XR input source does not have at least one of the following properties, the gamepad attribute MUST be null:

2.2. XRSession

XRInputSources are reported in the inputSources array as they are connected and disconnected. When the presence of a gamepad changes for any entry in the inputSources array, the user agent MUST invoke the WebXR Device API’s algorithm for responding to input source attribute changes.

The list of frame updates is updated to include apply gamepad frame updates.

To apply gamepad frame updates for an XRFrame frame, the user agent MUST run the following steps:

  1. For each XRInputSource with a gamepad gamepad associated with frame’s session, perform the following steps:

    1. Update gamepad to reflect the gamepad data at frame’s time.

NOTE: This means that the gamepad object is "live", and any internal state is to be updated in-place every frame. Furthermore, it doesn’t work to save a reference to an XRInputSource's gamepad on one frame and compare it to the same XRInputSource's gamepad from a subsequent frame to test for state changes, because they will be the same object. Therefore developers that wish to compare input state from frame to frame should cache the state in question.

3. Gamepad API Integration

Gamepad instances returned by an XRInputSource's gamepad attribute behave as described by the Gamepad API, with several additional behavioral restrictions.

An XRInputSource's associated Gamepad MAY be exposed via navigator.getGamepads(), even if there is no active XR session by user agent choice. This allows XR devices to be used as "regular" gamepads if the user agent wishes to allow this.

Note: Hand tracking XRInputSources as described in [WEBXR-HAND-INPUT-1] may contain a Gamepad if the user agent wishes to allow hand-based input sources to be used with gamepad-based content.

The Gamepad API states a snapshot of Gamepad data can be retrieved by calling the navigator.getGamepads() function. However, Gamepad instances returned by an XRInputSource's gamepad attribute MUST NOT be included in the array returned by navigator.getGamepads().

3.2. Gamepad

The following Gamepad attributes MUST exhibit the following behavioral restrictions when the Gamepad has been returned by an XRInputSource's gamepad attribute.

3.3. "xr-standard" Gamepad Mapping

The "xr-standard" mapping is defined in the Gamepad API and reserved for use by this spec. It indicates that the layout of the buttons and axes of the gamepad corresponds as closely as possible to the tables below.

In order to report a mapping of "xr-standard" the device MUST report a targetRayMode of "tracked-pointer" and MUST have a non-null gripSpace. It MUST have at least one primary trigger, separate from any touchpads or thumbsticks. The primary trigger MUST trigger the primary action for the input source. The device MAY have a primary squeeze button, which, if present, MUST trigger the primary squeeze action for the input source. If a device does not meet the requirements for the "xr-standard" mapping it may still expose a gamepad with a mapping of "" (empty string). The "xr-standard" mapping MUST only be used by Gamepad instances reported by an XRInputSource.

Buttons xr-standard Mapping Required
buttons[0] Primary trigger Yes
buttons[1] Primary squeeze button No
buttons[2] Primary touchpad No
buttons[3] Primary thumbstick No

Axes xr-standard Mapping Required
axes[0] Primary touchpad X No
axes[1] Primary touchpad Y No
axes[2] Primary thumbstick X No
axes[3] Primary thumbstick Y No

Devices that lack one of the optional inputs listed in the tables above MUST preserve their place in the buttons or axes array, reporting a placeholder button or placeholder axis, respectively. A placeholder button MUST report 0 for value, false for pressed, and false for touched. A placeholder axis MUST report 0. Placeholder buttons and axes MUST be omitted if they are the last element in the array or all following elements are also placeholder buttons or axes.

Additional buttons or axes may be exposed after these reserved indices, and SHOULD appear in order of decreasing importance. Related axes (such as both axes of a thumbstick) MUST be grouped and, if applicable, MUST appear in X, Y, Z order.

3.4. UA/Platform reserved buttons

User Agents SHOULD reserve at least one physical button, when possible, for performing unspoofable actions as part of a trusted UI. For example, the User Agent could designate the "menu" or "app" button present on many controllers as a dedicated button for exiting immersive presentation.

Additionally, many XR platforms also reserve a button for platform specific actions, such as returning to a home environment.

Buttons reserved by the UA or platform MUST NOT be exposed on the Gamepad. Additionally, User Agents SHOULD make an effort to coordinate which buttons are reserved for a given XR platform. The WebXR Input Profiles Registry is the recommended location for coordinating button reservations.

3.5. Example Mappings

This diagram demonstrates how two example controllers would be exposed with the "xr-standard" mapping. Images are not intended to represent any particular device and are used for reference purposes only. Simple 'xr-standard' controller and Advanced 'xr-standard' controller

4. Security and Privacy

The WebXR Device API provides powerful new features which bring with them several unique privacy, security, and comfort risks that user agents must take steps to mitigate. This topic is covered in detail as part of the WebXR Device API. This module adds additional considerations, but does not change the fundamental WebXR security and privacy principles.

4.1. Fingerprinting

Given that the API describes hardware available to the user and its capabilities it will inevitably provide additional surface area for fingerprinting. While it’s impossible to completely avoid this, user agents should take steps to mitigate the issue. As defined in the WebXR Device API, XRInputSources are only reported after an XRSession has been created, which requires additional protections when sensitive information will be exposed. In addition, this module requires XRInputSource's gamepad.id to not report a string identifiers.

Changes

Changes from the First Public Working Draft 10 October 2019

5. Acknowledgements

The following individuals have contributed to the design of the WebXR Device API specification:

And a special thanks to Vladimir Vukicevic (Unity) for kick-starting this whole adventure!

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[GAMEPAD]
Steve Agoston; Matthew Reynolds. Gamepad. URL: https://w3c.github.io/gamepad/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/
[WEBXR]
Brandon Jones; Manish Goregaokar; Rik Cabanier. WebXR Device API. URL: https://immersive-web.github.io/webxr/

Informative References

[WEBXR-HAND-INPUT-1]
Manish Goregaokar. WebXR Hand Input Module - Level 1. URL: https://immersive-web.github.io/webxr-hand-input/

IDL Index

partial interface XRInputSource {
  [SameObject] readonly attribute Gamepad? gamepad;
};