# WebXR Gamepads Module - Level 1

## W3C First Public Working Draft, 10 October 2019

This version:
  https://www.w3.org/TR/2019/WD-webxr-gamepads-module-1-20191010/
Latest published version:
  https://www.w3.org/TR/webxr-gamepads-module-1/
Editor's Draft:
  https://immersive-web.github.io/webxr-gamepads-module/
Issue Tracking:
  GitHub
Editors:
  Brandon Jones (Google)
  Nell Waliczek (Amazon [Microsoft until 2018])
Participate:
  File an issue (open issues)
  Mailing list archive
  W3C’s #immersive-web IRC

Copyright © 2019 W3C® (MIT, ERCIM, Keio, Beihang). 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. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

The Immersive Web Working Group maintains a list of all bug reports that the group has not yet addressed. This draft highlights some of the pending issues that are still to be discussed in the working group. No decision has been taken on the outcome of these issues including whether they are valid. Pull requests with proposed specification text for outstanding issues are strongly encouraged.

This document was published by the Immersive Web Working Group as a Working Draft. This document is intended to become a W3C Recommendation.

This document is a First Public Working Draft.

Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. 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 1 March 2019 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:

- Head mounted displays, whether they are opaque, transparent, or utilize video passthrough

- Mobile devices with positional tracking

- Fixed displays with head tracking capabilities

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`:

- A single button and a gripSpace

- More than one button

- One or more axes

Note: `XRInputSource`s in an `XRSession`'s `inputSources` array are "live". As such values within them, such as the `gamepad` button and axis state, are updated in-place. This means that 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 copy the state in question.

### 2.2. XRSession

`XRInputSource`s 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.

## 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.

### 3.1. Navigator

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.

- `gamepad`'s `id` attribute MUST be an empty string (`""`).

- `gamepad`'s `index` attribute MUST be `-1`.

- `gamepad`'s `connected` attribute MUST be `true` until the `XRInputSource` is removed from the list of active XR input sources or the `XRSession` is ended.

- If an axis reported by the `gamepad`'s `axes` array represents an axis of a touchpad, the value MUST be `0` when the associated `GamepadButton`'s `touched` is `false`.

### 3.3. "xr-standard" Gamepad Mapping

This module extends the `GamepadMappingType` to describe the mapping of common XR controller devices.

    enum GamepadMappingType {
      "",            // Defined in the Gamepad API
      "standard",    // Defined in the Gamepad API
      "xr-standard",
    };

The `xr-standard` mapping 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 button, often a trigger, separate from any touchpads or thumbsticks. 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 button/trigger | Yes
buttons[1] | Primary squeeze | 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. Buttons reserved by the UA or platform MUST NOT be exposed.

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.

## 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, `XRInputSource`s 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.

## 5. Acknowledgements

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

- Chris Van Wiemeersch (Mozilla)

- Kearwood Gilbert (Mozilla)

- Rafael Cintron (Microsoft)

- Sebastian Sylvan (Formerly Microsoft)

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

## Index

### Terms defined by this specification

- "", in §3.3
- gamepad, in §2.1
- GamepadMappingType, in §3.3
- placeholder axis, in §3.3
- placeholder button, in §3.3
- "standard", in §3.3
- XR input source, in §2
- xr-standard, in §3.3
- "xr-standard", in §3.3

https://w3c.github.io/gamepad/#dom-gamepad Referenced in:

- 2.1. XRInputSource (2) (3)
- 3. Gamepad API Integration
- 3.1. Navigator (2)
- 3.2. Gamepad (2)
- 3.3. "xr-standard" Gamepad Mapping

https://w3c.github.io/gamepad/#dom-gamepadbutton Referenced in:

- 3.2. Gamepad

https://w3c.github.io/gamepad/#dom-gamepad-axes Referenced in:

- 3.2. Gamepad
- 3.3. "xr-standard" Gamepad Mapping

https://w3c.github.io/gamepad/#dom-gamepad-buttons Referenced in:

- 3.3. "xr-standard" Gamepad Mapping

https://w3c.github.io/gamepad/#dom-gamepad-connected Referenced in:

- 3.2. Gamepad

https://w3c.github.io/gamepad/#dom-gamepad-id Referenced in:

- 3.2. Gamepad
- 4.1. Fingerprinting

https://w3c.github.io/gamepad/#dom-gamepad-index Referenced in:

- 3.2. Gamepad

https://w3c.github.io/gamepad/#dom-gamepad-mapping Referenced in:

- 3.3. "xr-standard" Gamepad Mapping (2)

https://w3c.github.io/gamepad/#dom-navigator-getgamepads Referenced in:

- 3.1. Navigator (2)

https://w3c.github.io/gamepad/#dom-gamepadbutton-pressed Referenced in:

- 3.3. "xr-standard" Gamepad Mapping

https://w3c.github.io/gamepad/#dom-gamepadbutton-touched Referenced in:

- 3.2. Gamepad
- 3.3. "xr-standard" Gamepad Mapping

https://w3c.github.io/gamepad/#dom-gamepadbutton-value Referenced in:

- 3.3. "xr-standard" Gamepad Mapping

https://heycam.github.io/webidl/#SameObject Referenced in:

- 2.1. XRInputSource

https://www.w3.org/TR/webxr/#dom-xrtargetraymode-tracked-pointer Referenced in:

- 3.3. "xr-standard" Gamepad Mapping

https://www.w3.org/TR/webxr/#xrinputsource-interface Referenced in:

- 2. WebXR Device API Integration (2)
- 2.1. XRInputSource (2) (3) (4) (5)
- 2.2. XRSession
- 3. Gamepad API Integration
- 3.1. Navigator
- 3.2. Gamepad (2)
- 3.3. "xr-standard" Gamepad Mapping
- 4.1. Fingerprinting (2)

https://www.w3.org/TR/webxr/#xrsession-interface Referenced in:

- 2.1. XRInputSource
- 3.2. Gamepad
- 4.1. Fingerprinting

https://www.w3.org/TR/webxr/#dom-xrinputsource-gripspace Referenced in:

- 3.3. "xr-standard" Gamepad Mapping

https://www.w3.org/TR/webxr/#dom-xrsession-inputsources Referenced in:

- 2.1. XRInputSource
- 2.2. XRSession (2)

https://www.w3.org/TR/webxr/#list-of-active-xr-input-sources Referenced in:

- 3.2. Gamepad

https://www.w3.org/TR/webxr/#on-input-source-change Referenced in:

- 2.2. XRSession

https://www.w3.org/TR/webxr/#sensitive-information Referenced in:

- 4.1. Fingerprinting

https://www.w3.org/TR/webxr/#dom-xrinputsource-targetraymode Referenced in:

- 3.3. "xr-standard" Gamepad Mapping

https://www.w3.org/TR/webxr/#viewer Referenced in:

- 2. WebXR Device API Integration (2)

https://www.w3.org/TR/webxr/#security Referenced in:

- 4. Security and Privacy

https://www.w3.org/TR/webxr/#xrsession-xr-device Referenced in:

- 2. WebXR Device API Integration (2)

### Terms defined by reference

- [gamepad] defines the following terms:
  - Gamepad
  - GamepadButton
  - axes
  - buttons
  - connected
  - id
  - index
  - mapping
  - navigator.getGamepads()
  - pressed
  - touched
  - value
- [WebIDL] defines the following terms:
  - SameObject
- [webxr device api - level 1] defines the following terms:
  - "tracked-pointer"
  - XRInputSource
  - XRSession
  - gripSpace
  - inputSources
  - list of active xr input sources
  - responding to input source attribute changes
  - sensitive information
  - targetRayMode
  - viewer
  - webxr security and privacy
  - xr device

## References

### Normative References

[GAMEPAD]
  James Hollyer; et al. Gamepad. 3 October 2019. WD. URL: https://www.w3.org/TR/gamepad/
[WebIDL]
  Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

## IDL Index

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

    enum GamepadMappingType {
      "",            // Defined in the Gamepad API
      "standard",    // Defined in the Gamepad API
      "xr-standard",
    };

#xr-input-source Referenced in:

- 2. WebXR Device API Integration (2)
- 2.1. XRInputSource (2)

#dom-xrinputsource-gamepad Referenced in:

- 2.1. XRInputSource (2) (3) (4) (5)
- 2.2. XRSession
- 3. Gamepad API Integration
- 3.1. Navigator
- 3.2. Gamepad (2) (3) (4) (5)
- 3.3. "xr-standard" Gamepad Mapping (2)
- 4.1. Fingerprinting

#enumdef-gamepadmappingtype Referenced in:

- 3.3. "xr-standard" Gamepad Mapping

#dom-gamepadmappingtype-xr-standard Referenced in:

- 3.3. "xr-standard" Gamepad Mapping (2) (3) (4) (5)

#placeholder-button Referenced in:

- 3.3. "xr-standard" Gamepad Mapping (2) (3)

#placeholder-axis Referenced in:

- 3.3. "xr-standard" Gamepad Mapping (2) (3)