[gamepad]. See Bugzilla for this specification's open bugs.The Gamepad API provides a tightly scoped interface to gamepad devices and is focused on the most common elements of those devices, namely axis and button inputs. It specifically excludes support for more complex devices (e.g., those that do motion tracking or haptic feedback).
However, some uses of gamepads (e.g., those paired with Virtual Reality headsets) rely heavily on those more advanced features. This supplemetary spec describes extensions to the base API to accommodate those use cases. If they prove to be broadly useful, the hope is that they will be eventually merged into themain spec.
This enum defines the set of possible hands a gamepad may be held by.
enum GamepadHand { "", /* unknown, both hands, or not applicable */ "left", "right" };This interface defines the gamepad's position, orientation, velocity, and acceleration.
[Exposed=Window] interface GamepadPose { readonly attribute boolean hasOrientation; readonly attribute boolean hasPosition; readonly attribute Float32Array? position; readonly attribute Float32Array? linearVelocity; readonly attribute Float32Array? linearAcceleration; readonly attribute Float32Array? orientation; readonly attribute Float32Array? angularVelocity; readonly attribute Float32Array? angularAcceleration; };hasOrientation attribute MUST return whether the gamepad is capable of tracking its orientation.hasPosition attribute MUST return whether the gamepad is capable of tracking its position.Position of the gamepad as a 3D vector, given in meters from an origin point, which is determined by the gamepad hardware and MAY be the position of the gamepad when first polled if no other reference point is available. The coordinate system uses these axis definitions, assuming the user is holding the gamepad in the forward orientation:
MUST benull if the gamepad is incapable of providing positional data. When notnull, MUST be a three-element array.
null if the sensor is incapable of providing linear velocity. When notnull, MUST be a three-element array.null if the sensor is incapable of providing linear acceleration. When notnull, MUST be a three-element array.[0, 0, 0, 1] is considered to beforward. The forward direction MUST be determined by the gamepad hardware. The forward direction MAY be the orientation of the hardware when it was first polled if no other reference orientation is available. If the sensor is incapable of providing orientation data, the orientation MUST benull. When notnull, theorientation MUST be a four-element array.null if the sensor is incapable of providing angular velocity. When notnull, theangularVelocity MUST be a three-element array.null if the sensor is incapable of providing angular acceleration. When notnull,angularAcceleration MUST be a three-element array.This partial interface supplements the Gamepad interface described in the mainGamepad spec.
partial interface Gamepad { readonly attribute GamepadHand hand; readonly attribute FrozenArray<GamepadHapticActuator> hapticActuators; readonly attribute GamepadPose? pose; };Instances of {{Gamepad}} are created with the internal slots described in the following table:
| Internal slot | Initial value | Description (non-normative) |
|---|---|---|
| [[\hand]] | `undefined` | Indicates the hand the controller is held in. |
| [[\hapticActuators]] | `undefined` | List of all the haptic actuators in the gamepad. |
| [[\pose]] | `null` | The current pose of the gamepad. |
This section supplements theReceiving inputs section of the mainGamepad specification.
This section supplements theConstructing a `Gamepad` section of the mainGamepad specification.
This partial interface supplements the {{GamepadHapticActuator}} interface described in the mainGamepad spec.
[Exposed=Window] partial interface GamepadHapticActuator { Promise<boolean> pulse(double value, double duration); }; {{GamepadHapticActuator/pulse()}} applies a |value:double| to the actuator forduration milliseconds. Thevalue passed topulse() is clamped to limits defined by the actuator type. The returned Promise will resolvetrue once the pulse has completed.
Repeated calls topulse() override the previous values.