Gamepad

2. Dependencies

This specification references interfaces from a number of other specifications:

• PerformanceTiming [NAVIGATION-TIMING].

3. Scope

Interfacing with external devices designed to control games has the potential to become large and intractable if approached in full generality. In this specification we explicitly choose to narrow scope to provide a useful subset of functionality that can be widely implemented and broadly useful.

Specifically, we choose to only support the functionality required to support gamepads. Support for gamepads requires two input types: buttons and axes. Both buttons and axes are reported as analog values, buttons ranging from [0..1], and axes ranging from [-1..1].

While the primary goal is support for gamepad devices, supporting these two types of analog inputs allows support for other similar devices common to current gaming systems including joysticks, driving wheels, pedals, and accelerometers. As such, the name "gamepad" is exemplary rather than trying to be a generic name for the entire set of devices addressed by this specification.

We specifically exclude support for more complex devices that may also be used in some gaming contexts, including those that that do motion sensing, depth sensing, video analysis, gesture recognition, and so on.

4. Gamepad interface

This interface represents an individual gamepad device. A Gamepad is a live object; that is, user interaction with the device is periodically reflected in the state of the object's properties. When the system receives new data from a connected gamepad, a microtask MUST be queued with the user interaction task source to update the state of the Gamepad object.

[Exposed=Window]
interface Gamepad {
  readonly attribute DOMString id;
  readonly attribute long index;
  readonly attribute boolean connected;
  readonly attribute DOMHighResTimeStamp timestamp;
  readonly attribute GamepadMappingType mapping;
  readonly attribute FrozenArray<double> axes;
  readonly attribute FrozenArray<GamepadButton> buttons;
};

id attribute

An identification string for the gamepad. This string identifies the brand or style of connected gamepad device. Typically, this will include the USB vendor and a product ID.

index attribute

Zero-based index of the gamepad in the Navigator. The index MUST NOT change once the Gamepad object has been returned to script.

When the system is notified that a gamepad has been connected, its index attribute MUST be assigned to the lowest index that is not assigned to any currently connected gamepad, starting at zero.

When the system is notified that a previously connected gamepad has become unavailable, the index attribute of other gamepads MUST NOT be reassigned. However, if a gamepad is disconnected, and subsequently the same or a different gamepad is connected, the lowest previously used index MUST be assigned to the newly connected gamepad.

Example 1

// Consider three gamepads padA, padB, and padC.
// Initially, padA and padB are connected with indices 0 and 1.
// padC is not connected.
var gamepads = navigator.getGamepads();
// The following statements should all evaluate to true.
gamepads.length == 2;
gamepads[0].index == 0;  // padA
gamepads[1].index == 1;  // padB
// padA is disconnected.
gamepads.length == 2;
gamepads[0] == null;
gamepads[1].index == 1;  // padB
// padC is connected and takes the lowest unassigned index (0).
gamepads.length == 2;
gamepads[0].index == 0;  // padC
gamepads[1].index == 1;  // padB
// padA is reconnected and takes the lowest unassigned index (2).
gamepads.length == 3;
gamepads[0].index == 0;  // padC
gamepads[1].index == 1;  // padB
gamepads[2].index == 2;  // padA

connected attribute

Indicates whether the physical device represented by this object is still connected to the system.

When the system is notified that a previously-connected gamepad has become unavailable, whether by being physically disconnected, powered off, or otherwise unusable, a microtask MUST be queued with the user interaction task source to set the connected attribute to false.

timestamp attribute

Last time the data for this gamepad was updated. The timestamp is a monotonically increasing value that allows the author to determine if the axes and button data have been updated from the hardware. The value must be relative to the navigationStart attribute of the PerformanceTiming interface. Since values are monotonically increasing they can be compared to determine the ordering of updates, as newer values will always be greater than or equal to older values.

If no data has been received from the hardware, the value of the timestamp attribute MUST be the time relative to navigationStart when the Gamepad object was first made available to script.

When the system receives new data from a connected gamepad, a microtask MUST be queued with the user interaction task source to update the gamepad state. If the updated data would cause an observable change to the buttons or axes attributes, then the timestamp MUST be set to the time that the data was received from hardware, not the time when the microtask was executed.

mapping attribute

The mapping in use for this device. If the user agent has knowledge of the layout of the device, then it SHOULD indicate that a mapping is in use by setting this property to a known mapping name. Currently the only known mapping is "standard", which corresponds to the Standard Gamepad layout. If the user agent does not have knowledge of the device layout and is simply providing the controls as represented by the driver in use, then it MUST set the mapping property to the empty string.

axes attribute

Array of values for all axes of the gamepad. All axis values MUST be linearly normalized to the range [-1.0 .. 1.0]. If the controller is perpendicular to the ground with the directional stick pointing up, -1.0 SHOULD correspond to "forward" or "left", and 1.0 SHOULD correspond to "backward" or "right". Axes that are drawn from a 2D input device SHOULD appear next to each other in the axes array, X then Y. It is RECOMMENDED that axes appear in decreasing order of importance, such that element 0 and 1 typically represent the X and Y axis of a directional stick.

When the system receives new data from a connected gamepad, a microtask MUST be queued with the user interaction task source to update the gamepad state. If the gamepad has the same axes in the same order as the previous update, and if no axis values have changed since the previous update, then the axes attribute MUST return the same array object. If the number of axes has changed, or if any axis value has changed, then the axis attribute MUST return a new array.

Once the system is notified that a previously connected gamepad has been disconnected, the axes attribute MUST continue to return the last state received from the gamepad before disconnection.

buttons attribute

Array of GamepadButton objects representing the current state of all buttons of the gamepad. It is RECOMMENDED that buttons appear in decreasing importance such that the primary button, secondary button, tertiary button, and so on appear as elements 0, 1, 2, ... in the buttons array.

When the system receives new data from a connected gamepad, a microtask MUST be queued with the user interaction task source to update the gamepad state. If the gamepad has the same buttons in the same order as the previous update, the buttons attribute MUST return the same array object. If the number of buttons or the ordering of buttons has changed, the buttons attribute MUST return a new array object. If a button in the new array represents the same physical button as a button from the previous array, the same GamepadButton object MUST be reused.

5. GamepadButton Interface

This interface represents the current state of an individual button on a gamepad device. A GamepadButton is a live object; that is, user interaction with the button represented by the object is periodically reflected in the object's properties. When the system receives new data from a connected gamepad, a microtask MUST be queued with the user interaction task source to update the state of the GamepadButton objects representing the buttons on the gamepad.

Once the system is notified that a previously-connected gamepad has been disconnected, the GamepadButton objects representing its buttons MUST continue to return the last state received from the gamepad before disconnection.

[Exposed=Window]
interface GamepadButton {
  readonly attribute boolean pressed;
  readonly attribute boolean touched;
  readonly attribute double value;
};

pressed attribute

The pressed state of the button. This property MUST be true if the button is currently pressed, and false if it is not pressed. For buttons which do not have a digital switch to indicate a pure pressed or released state, the user agent MUST choose a threshold value to indicate the button as pressed when its value is above a certain amount. If the platform API gives a recommended value, the user agent SHOULD use that. In other cases, the user agent SHOULD choose some other reasonable value.

touched attribute

The touched state of the button. If the button is capable of detecting touch this property MUST be true if the button is currently being touched and false otherwise. If the button is not capable of detecting touch and is capable of reporting an analog value this property MUST be true if the value property is greater than zero and false if the value is 0. If the button is not capable of detecting touch and can only report a digital value this property MUST mirror the pressed value.

value attribute

For buttons that have an analog sensor, this property MUST represent the amount which the button has been pressed. All button values MUST be linearly normalized to the range [0.0 .. 1.0]. 0.0 MUST mean fully unpressed, and 1.0 MUST mean fully pressed. For buttons without an analog sensor, only the values 0.0 and 1.0 for fully unpressed and fully pressed MUST be provided.

6. GamepadMappingType enum

This enum defines the set of known mappings for a Gamepad.

enum GamepadMappingType {
  "",
  "standard",
};

""

The empty string indicates that no mapping is in use for this gamepad.

standard

The Gamepad's controls have been mapped to the Standard Gamepad layout.

7. Navigator Interface extension

This partial interface defines an extension to the Navigator interface.

[Exposed=Window]
partial interface Navigator {
  [NewObject] sequence<Gamepad?> getGamepads();
};

getGamepads

Retrieve a sequence of Gamepad objects representing currently connected and interacted-with gamepads. Gamepads MUST only appear in the list if they are currently connected to the user agent, and at least one device has been interacted with by the user. If no devices have been interacted with, devices MUST NOT appear in the list to avoid a malicious page from fingerprinting the user. The length of the array returned MUST be one more than the maximum index value of the Gamepad objects returned in the array. The entries in the array MUST be the set of Gamepad objects that are visible to the current page, with each Gamepad present at the index in the array specified by its index attribute. Array indices for which there is no connected Gamepad with the corresponding index should return null.

The gamepad state returned from getGamepads() does not reflect disconnection or connection until after the gamepaddisconnected or gamepadconnected events have fired.

As an example, if there is one connected gamepad with an index of 1, then the following code snippet describes the expected behavior:

Example 2

// gamepads should look like [null, [object Gamepad]]
var gamepads = navigator.getGamepads();
// The following statements should all evaluate to true.
gamepads[0] == null;
gamepads[1].index == 1;
gamepads.length == 2;

8. GamepadEvent Interface

[Exposed=Window]

interface GamepadEvent: Event {
  constructor(DOMString type, GamepadEventInit eventInitDict);
  [SameObject] readonly attribute Gamepad gamepad;
};

gamepad

The single gamepad attribute provides access to the associated gamepad data for this event.

dictionary GamepadEventInit : EventInit {
  required Gamepad gamepad;
};

9. Remapping

Each device manufacturer creates many different products and each has unique styles and layouts of buttons and axes. It is intended that the user agent support as many of these as possible.

Additionally there are de facto standard layouts that have been made popular by game consoles. When the user agent recognizes the attached device, it is RECOMMENDED that it be remapped to a canonical ordering when possible. Devices that are not recognized should still be exposed in their raw form.

There is currently one canonical device, the "Standard Gamepad". The standard gamepad has 4 axes, and up to 17 buttons. When remapping, the indices in axes[] and buttons[] should correspond as closely as possible to the physical locations in the diagram below. Additionally, the mapping property of the Gamepad SHOULD be set to the string "standard".

The "Standard Gamepad" physical button locations are layed out in a left cluster of four buttons, a right cluster of four buttons, a center cluster of three buttons, and a pair of front facing buttons on the left and right side of the gamepad. The four axes of the "Standard Gamepad" are associated with a pair of analog sticks, one on the left and one on the right. The following table describes the buttons/axes and their physical locations.

11. The gamepadconnected event

User agents implementing this specification must provide a new DOM event, named gamepadconnected. The corresponding event MUST be of type GamepadEvent and MUST fire on the window object. Registration for and firing of the gamepadconnected event MUST follow the usual behavior of DOM Events. [DOM]

When the system is notified that a gamepad has been connected, a microtask MUST be queued with the user interaction task source to fire a gamepadconnected event. A user agent MUST dispatch this event type to indicate the user has connected a gamepad. If a gamepad was already connected when the page was loaded, the gamepadconnected event SHOULD be dispatched when the user presses a button or moves an axis on any connected gamepad.

12. The gamepaddisconnected event

User agents implementing this specification must provide a new DOM event, named gamepaddisconnected. The corresponding event MUST be of type GamepadEvent and MUST fire on the window object. Registration for and firing of the gamepaddisconnected event MUST follow the usual behavior of DOM Events. [DOM]

If a gamepadconnected event was previously dispatched for a particular gamepad and the system is notified that the gamepad has become unavailable, a microtask MUST be queued with the user interaction task source to dispatch a gamepaddisconnected event to the same window.

13. Other events

More discussion needed, on whether to include or exclude axis and button changed events, and whether to roll them more together (gamepadchanged?), separate somewhat (gamepadaxischanged?), or separate by individual axis and button.

14. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MUST, MUST NOT, RECOMMENDED, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.