Gamepad

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.

A gamepad is a collection of input controls and output controls. An input control has a collection of input values that may update over time. Input controls include the buttons, triggers, joysticks, thumbsticks, and touch surfaces of the gamepad. An output control is a feature that changes the behavior of the gamepad to provide feedback to the user interacting with the gamepad. Output controls include the haptic actuators of the gamepad. A gamepad is available if the user agent can read the current state of its input controls. A gamepad that is not available is unavailable. The input controls and output controls for a gamepad cannot change while the gamepad is available.

The user agent is responsible for:

• Enumerating available gamepads,
• Detecting when gamepads become available or unavailable,
• Detecting when input controls have updated input values,
• Reading the current state of input values, and
• Commanding the gamepad to use its output controls.

A gamepad has a gamepad identifier string, a human-readable string that identifies the brand or style of gamepad. The content is decided by the user agent.

This interface represents a gamepad.

WebIDL[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;
  readonly attribute FrozenArray<GamepadTouch> touches;
  [SameObject] readonly attribute GamepadHapticActuator vibrationActuator;
};

The algorithms used to communicate with the system typically complete asynchronously, queuing work on the gamepad task source.

Instances of Gamepad are created with the internal slots described in the following table:

id attribute

The gamepad's gamepad identifier string.

The exact format of the id string is left unspecified. It is RECOMMENDED that the user agent select a string that identifies the product without uniquely identifying the device. For example, a USB gamepad may be identified by its idVendor and idProduct values. Unique identifiers like serial numbers or Bluetooth device addresses MUST NOT be included in the id string.

index attribute

The index of the Gamepad object in Navigator.[[gamepads]].

connected attribute

Indicates whether the gamepad is available.

The connected getter steps are:

1. Return this.[[connected]].

timestamp attribute

The timestamp allows the author to determine when the input values for this Gamepad updated.

Warning

User agents SHOULD set a minimum resolution of the timestamp attribute to 5 microseconds, following [HR-TIME]'s clock resolution recommendation.

The timestamp getter steps are:

1. Return this.[[timestamp]].

mapping attribute

Indicates whether inputs in the axis list and button list are reordered when setting Gamepad.axes and Gamepad.buttons. If the user agent has knowledge of the input control layout, then it SHOULD indicate that a mapping is in use by setting mapping to the corresponding GamepadMappingType value.

To select a mapping for a gamepad, run the following steps:

1. If the input control layout corresponds with the Standard Gamepad layout, then return "standard".
2. Return "".

axes attribute

Array of values for all axis inputs of the gamepad normalized to the range [-1 .. 1]. If the gamepad is perpendicular to the ground with the thumbsticks pointing up, -1 SHOULD correspond to "forward" or "left", and 1 SHOULD correspond to "backward" or "right". Axis inputs with input values from a thumbstick, joystick, or another input control that reports X and Y values SHOULD appear next to each other in the axes array, X then Y. It is RECOMMENDED that axis inputs appear in decreasing order of importance, such that element 0 and 1 typically represent the X and Y axes of a thumbstick or joystick. The same object MUST be returned until the user agent needs to return different values (or values in a different order).

The axes getter steps are:

1. Return this.[[axes]].

buttons attribute

Array of button states for 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. The same object MUST be returned until the user agent needs to return different values (or values in a different order).

The buttons getter steps are:

1. Return this.[[buttons]].

touches attribute

A list of GamepadTouch objects representing the current contact points across all touch surfaces.

The touches getter steps are:

1. Return this.[[touches]].

vibrationActuator attribute

A GamepadHapticActuator object that represents the gamepad's vibration actuator.

The vibrationActuator getter steps are:

1. Return this.[[vibrationActuator]].

This interface defines the state of an individual button on a gamepad at a single point in time.

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

Instances of GamepadButton are created with the internal slots described in the following table:

pressed attribute

Indicates whether the button is pressed. 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 button press threshold 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.

The pressed getter steps are:

1. Return this.[[pressed]].

touched attribute

Indicates whether the button is detecting any interaction, including interactions that do not cause the button to activate. If the button has a button touch value, touched is the button touch value. If the button does not have a button touch value but has an analog button value, touched is true if the current analog button value is greater than the logical minimum, otherwise false. If the button does not have a button touch value or an analog button value, touched mirrors pressed.

The touched getter steps are:

1. Return this.[[touched]].

value attribute

A value in the range [0 .. 1] representing the degree to which the button is activated. For buttons that have an analog button value, this property MUST be the analog button value clamped to the logical minimum and logical maximum and then linearly normalized to the range [0 .. 1]. 0 MUST mean fully unpressed, and 1 MUST mean fully pressed. For buttons without an analog button value, only the values 0 and 1 for fully unpressed and fully pressed respectively, MUST be provided.

The value getter steps are:

1. Return this.[[value]].

This interface represents a touch point on a touch surface. The object consists of a touchId that uniquely identifies the touch point from the time the input medium (e.g. finger, stylus, etc) makes contact with the touch surface, up to the time the input medium is no longer making contact with the surface.

WebIDLdictionary GamepadTouch {
  unsigned long touchId;
  octet surfaceId;
  DOMPointReadOnly position;
  DOMRectReadOnly? surfaceDimensions;
};

touchId attribute

Identifier shared by touch points that are part of an existing active touch point. Range is [0 .. 4294967295].

surfaceId attribute

Identifier of the touch surface that generated the touch point.

position attribute

A DOMPointReadOnly which holds the normalized touch x coordinate and touch y coordinate of the touch point as x and y. The z and w values are currently unused. The range of each coordinate is normalized to [-1 .. 1]. Along the x-axis, -1 references the leftmost coordinate and 1 references the rightmost coordinate. Along the y-axis, -1 references the topmost coordinate and 1 references the bottommost coordinate.

surfaceDimensions attribute

A DOMRectReadOnly initialized with the surface width and surface height of the touch surface as width and height, if the touch surface has surface dimensions. Otherwise, null.

This enum defines the mapping types for mapping from a gamepad to a Gamepad.

WebIDLenum GamepadMappingType {
  "",
  "standard",
  "xr-standard",
};

""

The empty string indicates that the gamepad does not have an input control layout, or the user agent does not know the gamepad's input control layout, or the layout corresponds with none of the standard layouts. The axes and buttons arrays are not reordered.

"standard"

The gamepad's input control layout corresponds with the Standard Gamepad layout. The axes and buttons arrays are reordered.

"xr-standard"

The gamepad's controls have been mapped to the "xr-standard" gamepad mapping. This mapping is reserved for use by the WebXR Gamepads Module - Level 1. Gamepad objects returned by getGamepads() MUST NOT report a mapping of "xr-standard".

This interface represents a haptic actuator capable of playing haptic effects that move the gamepad in a way that can be felt by the user.

WebIDL[Exposed=Window]
interface GamepadHapticActuator {
  [SameObject] readonly attribute FrozenArray<GamepadHapticEffectType> effects;
  Promise<GamepadHapticsResult> playEffect(
      GamepadHapticEffectType type,
      optional GamepadEffectParameters params = {}
  );
  Promise<GamepadHapticsResult> reset();
};

Instances of GamepadHapticActuator are created with the internal slots described in the following table:

effects attribute

Array of GamepadHapticEffectType values representing all the types of haptic effects that the GamepadHapticActuator supports. This property lists the GamepadHapticEffectType values that the actuator supports, unless the user agent does not support playing effects of that type.

The effects getter steps are:

1. Return this.[[effects]].

playEffect() method

The playEffect() method steps, called with GamepadHapticEffectType type and GamepadEffectParameters params, are:

1. If params does not describe a valid effect of type type, return a promise rejected with a TypeError.
2. If the current global object is not a Window, return a promise rejected with an "InvalidStateError" DOMException.
3. Let window be the current global object.
4. Let document be the window's associated Document.
5. If document is not fully active or document's visibility state is "hidden", return a promise rejected with an "InvalidStateError" DOMException.
6. If this.[[playingEffectPromise]] is not null:
   1. Let effectPromise be this.[[playingEffectPromise]].
   2. Set this.[[playingEffectPromise]] to null.
   3. Queue a global task on the gamepad task source with window to resolve effectPromise with "preempted".
7. If this GamepadHapticActuator cannot play effects with type type, return a promise rejected with reason NotSupportedError.
8. Let [[playingEffectPromise]] be a new promise.
9. Let playEffectTimestamp be the current high resolution time given window.
10. Do the following steps in parallel:
    1. Play a haptic effect on the haptic actuator represented by this with type, params, and the playEffectTimestamp.
    2. When the effect completes, if this.[[playingEffectPromise]] is not null, queue a global task on the gamepad task source with window to run the following steps:
       1. If this.[[playingEffectPromise]] is null, abort these steps.
       2. Resolve this.[[playingEffectPromise]] with "complete".
       3. Set this.[[playingEffectPromise]] to null.
11. Return [[playingEffectPromise]].

reset() method

The reset() method steps are:

1. If the current global object is not a Window, return a promise rejected with an "InvalidStateError" DOMException.
2. Let window be the current global object.
3. Let document be window's associated Document.
4. If document is not fully active or document's visibility state is "hidden", return a promise rejected with an "InvalidStateError" DOMException.
5. Let resetResultPromise be a new promise.
6. If this.[[playingEffectPromise]] is not null, do the following steps in parallel:
   1. Let effectPromise be this.[[playingEffectPromise]].
   2. Stop haptic effects on the haptic actuator represented by this GamepadHapticActuator.
   3. If the effect has been successfully stopped, do:
      1. If effectPromise and this.[[playingEffectPromise]] are still the same, set this.[[playingEffectPromise]] to null.
      2. Queue a global task on gamepad task source with window to resolve effectPromise with "preempted".
   4. Resolve resetResultPromise with "complete"
7. Return resetResultPromise.

A GamepadHapticActuator can play effects with type type if type can be found in the [[effects]] list.

To check if an effect with GamepadHapticEffectType type and GamepadEffectParameters params describes a valid effect, run the following steps:

1. Given the value of GamepadHapticEffectType type, switch on:

   "dual-rumble"

   If params does not describe a valid dual-rumble effect, return false.

   "trigger-rumble"

   If params does not describe a valid trigger-rumble effect, return false.

2. Return true

To play a haptic effect on a haptic actuator, the user agent MUST command the haptic actuator to render a haptic effect of type and try to make it use the provided params. The user agent SHOULD use the provided playEffectTimestamp for more precise playback timing when params.startDelay is not 0. The user agent MAY modify the effect to increase compatibility. For example, an effect intended for a rumble motor may be transformed into a waveform-based effect for a device that supports waveform haptics but lacks rumble motors.

To stop haptic effects on a haptic actuator, the user agent MUST command the haptic actuator to abort any effects currently being played on that actuator. If a haptic effect was interrupted, the actuator SHOULD return to a motionless state as quickly as possible.

WebIDLenum GamepadHapticsResult {
  "complete",
  "preempted"
};

complete

The haptic effect completed playing.

preempted

The current haptic effect was stopped or replaced (i.e., "preempted") by another effect.

Each value represents a different style of haptic effect. The effect type defines how to generate a haptic effect from the GamepadEffectParameters.

WebIDLenum GamepadHapticEffectType {
  "dual-rumble",
  "trigger-rumble"
};

"dual-rumble" effect type

"dual-rumble" describes a haptic configuration with an eccentric rotating mass (ERM) vibration motor in each handle of a gamepad. In this configuration, either motor is capable of vibrating the whole gamepad. The vibration effects created by each motor are unequal so that the effects of each can be combined to create more complex haptic effects.

A "dual-rumble" effect is a fixed-duration, constant-intensity vibration effect intended for an actuator of this type. "dual-rumble" effects are defined by startDelay, duration, strongMagnitude, and weakMagnitude, none of which are required because they default to 0.

strongMagnitude and weakMagnitude set the intensity levels for the low-frequency and high-frequency vibrations, normalized to the range [0 .. 1], defaulting to 0.

Given GamepadEffectParameters params, a valid dual-rumble effect must have a valid duration, a valid startDelay, and both the strongMagnitude and the weakMagnitude must be in the range [0 .. 1].

"trigger-rumble" effect type

"trigger-rumble" describes a haptics configuration with a vibration motor in each of the bottom front buttons of a Standard Gamepad (buttons with canonical indices 6 and 7) in addition to the two handle motors used for "dual-rumble". These buttons most commonly take the form of spring-loaded triggers. In this configuration, either motor is capable of providing localized haptic feedback on the button's surface.

A "trigger-rumble" effect is a fixed-duration, constant-intensity vibration effect intended for an actuator of this type. "trigger-rumble" effects are defined by startDelay, duration, strongMagnitude, weakMagnitude, leftTrigger, and rightTrigger, none of which are required because they default to 0.

startDelay, duration, strongMagnitude, weakMagnitude share the same definition with "dual-rumble". leftTrigger and rightTrigger, respectively, set the intensity levels for the left and right bottom front buttons vibrations, normalized to the range [0 .. 1], defaulting to 0.

Given GamepadEffectParameters params, a valid trigger-rumble effect must have a valid duration, a valid startDelay, and the strongMagnitude, weakMagnitude, leftTrigger, and rightTrigger must be in the range [0 .. 1].

A GamepadEffectParameters dictionary contains keys for parameters used by haptic effects. The meaning of each key is defined by the haptic effect type, and some keys may be unused.

To mitigate unwanted long-running effects, the user agent MAY limit the total effect duration for a valid effect to some maximum duration. It is RECOMMENDED that the user agent use a maximum of 5 seconds.

WebIDLdictionary GamepadEffectParameters {
    unsigned long long duration = 0;
    unsigned long long startDelay = 0;
    double strongMagnitude = 0.0;
    double weakMagnitude = 0.0;
    double leftTrigger = 0.0;
    double rightTrigger = 0.0;
};

duration member

duration sets the duration of the vibration effect in milliseconds.

startDelay member

startDelay sets the duration of the delay after playEffect() is called until vibration is started, in milliseconds. During the delay interval, the actuator SHOULD NOT vibrate.

strongMagnitude member

The vibration magnitude for the low frequency rumble in a "dual-rumble" or "trigger-rumble" effect.

weakMagnitude member

The vibration magnitude for the high frequency rumble in a "dual-rumble" or "trigger-rumble" effect.

leftTrigger member

The vibration magnitude for the bottom left front button (canonical index 6) rumble in a "trigger-rumble" effect.

rightTrigger member

The vibration magnitude for the bottom right front button (canonical index 7) rumble in a "trigger-rumble" effect.

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

Instances of Navigator are created with the internal slots described in the following table:

WebIDL[Exposed=Window]

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

gamepad attribute

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

WebIDLdictionary GamepadEventInit : EventInit {
  required Gamepad gamepad;
};

Each device manufacturer creates many different products and each has unique styles and input control layouts. 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 layout, the Standard Gamepad. When remapping, the indices in axes and buttons should correspond as closely as possible to the physical locations in the diagram below. Additionally, mapping SHOULD be set to "standard".

The Standard Gamepad buttons are laid 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 axis inputs 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 input controls and their physical locations.

An axis input represents a Standard Gamepad axis if it reports the input values for a thumbstick axis, the thumbstick is located in approximately the same location as the corresponding Standard Gamepad thumbstick, and the orientation of the axis (up-down or left-right) matches the orientation of the Standard Gamepad axis. If there are multiple axis inputs that represent the same Standard Gamepad axis, then the user agent SHOULD select one to be the Standard Gamepad axis and assign a different index to the other axis.

A button input represents a Standard Gamepad button if it reports the input values for a button or trigger, and the button or trigger is located in approximately the same location as the corresponding Standard Gamepad button or trigger.

If an axis or button input represents a Standard Gamepad axis or button, then its canonical index is the index of the corresponding Standard Gamepad axis or button.

When a gamepad availableGamepad becomes available, run the following steps for each top-level traversable traversable of the user agent's top-level traversable set:

1. For each navigable navigable of traversable's active document's inclusive descendant navigables:
   1. Let window be navigable's active window.
   2. Run the steps to add an available gamepad availableGamepad given window.

To add an available gamepad rawGamepad given window:

1. If window's associated Document is not allowed to use the "gamepad" permission, then abort these steps.
2. Queue a global task on the gamepad task source given window to perform the following steps:
   1. Let gamepad be a new Gamepad representing availableGamepad for window.
   2. Set window.navigator.[[gamepads]][gamepad.index] to gamepad.
   3. If window.navigator.[[hasGamepadGesture]] is true:
      1. Set gamepad.[[exposed]] to true.
      2. If document is not null and is fully active, then fire an event named gamepadconnected at window using GamepadEvent with its gamepad attribute initialized to gamepad.

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.

A user agent MUST dispatch this event type to indicate a gamepad has become available. If a gamepad was already available when the page was loaded, the gamepadconnected event SHOULD be dispatched once any Gamepad contains a gamepad user gesture.

When a gamepad unavailableGamepad becomes unavailable, run the following steps for each top-level traversable traversable of the user agent's top-level traversable set:

1. For each navigable navigable of traversable's active document's inclusive descendant navigables:
   1. Let window be navigable's active window.
   2. Run the steps to remove an unavailable gamepad unavailableGamepad given window.

To remove an unavailable gamepad rawGamepad given window:

1. Let gamepad be the Gamepad in window.navigator.[[gamepads]] representing unavailableGamepad.
2. Queue a global task on the gamepad task source given window to perform the following steps:
   1. Set gamepad.[[connected]] to false.
   2. Let document be window's associated Document.
   3. If gamepad.[[exposed]] is true and document is fully active, then fire an event named gamepaddisconnected at window using GamepadEvent with its gamepad attribute initialized to gamepad.
   4. Set window.navigator.[[gamepads]][gamepad.index] to null.
   5. While window.navigator.[[gamepads]] is not empty and the last item of window.navigator.[[gamepads]] is null, remove the last item of window.navigator.[[gamepads]].

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.

When a gamepad becomes unavailable, if the user agent has previously dispatched a gamepadconnected event for that gamepad to a Window, a gamepaddisconnected event MUST be dispatched to that same Window.

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.

This specification extends the WindowEventHandlers interface mixin from HTML to add event handler IDL attributes to facilitate the event handler registration.

WebIDLpartial interface mixin WindowEventHandlers {
  attribute EventHandler ongamepadconnected;
  attribute EventHandler ongamepaddisconnected;
};

This specification defines a policy-controlled feature identified by the string "gamepad". Its default allowlist is *.

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 MAY, MUST, MUST NOT, RECOMMENDED, SHOULD, and SHOULD NOT 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.