[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 the main spec.
User agents MUST implement the GamepadTouch to only be available in secure contexts. This provides better protection for the user against man-in-the-middle attacks intended to obtain gamepad data. Browsers may ignore this rule for development purposes only.
This enum defines the set of possible hands a gamepad may be held by.
enum GamepadHand {
"", /* unknown, both hands, or not applicable */
"left",
"right"
};
Each GamepadHapticActuator corresponds to a motor or other
actuator that can apply a force for the purposes of haptic feedback.
interface GamepadHapticActuator {
readonly attribute GamepadHapticActuatorType type;
Promise<boolean> pulse(double value, double duration);
};
pulse() applies a value to the actuator for
duration milliseconds. The value passed to
pulse() is clamped to limits defined by the actuator
type. The returned Promise will resolve true once the
pulse has completed.
Repeated calls to pulse() override the previous
values.
The actuator type determines the force applied for a given
value in GamepadHapticActuator.pulse().
enum GamepadHapticActuatorType {
"vibration"
};
value of a vibration
force determines the frequency of the rumble effect and is
normalized between 0.0 and 1.0. The
neutral value is 0.0.
This interface defines the gamepad's position, orientation, velocity, and acceleration.
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 be null if the gamepad is incapable of providing
positional data. When not null, MUST be a
three-element array.
null if the sensor is incapable of providing linear
velocity. When not null, MUST be a three-element array.
null if the sensor is incapable of providing linear
acceleration. When not null, MUST be a three-element
array.
[0, 0, 0, 1] is considered to be forward.
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 be null. When not null, the
orientation MUST be a four-element array.
null if the sensor is incapable of providing angular
velocity. When not null, the
angularVelocity MUST be a three-element array.
null if the sensor is incapable of providing angular
acceleration. When not null,
angularAcceleration MUST be a three-element array.
This interface defines a single touch event on a gamepad device that supports input. The event consists of a touch id that uniquely identifies the touch point from the time the input medium (e.g. finger, stylus, etc) makes contact with the touch device, up to the time the input medium is no longer making contact with the touch device.
[Exposed=Window, SecureContext]
interface GamepadTouch {
readonly attribute unsigned long touchId;
readonly attribute octet surfaceId;
readonly attribute Float32Array position;
readonly attribute Uint32Array? surfaceDimensions;
};
null, MUST be a two-element array.
This partial interface supplements the Gamepad interface described in the main Gamepad spec.
partial interface Gamepad {
readonly attribute GamepadHand hand;
readonly attribute FrozenArray<GamepadHapticActuator> hapticActuators;
readonly attribute GamepadPose? pose;
readonly attribute FrozenArray<GamepadTouch>? touchEvents;
};
null.
null
if the device does not support touch events.