Extensions to the base Gamepad specification to enable access to more advanced device capabilities.
If you have comments for this spec, please send them to public-webapps@w3.org with a Subject: prefix of [gamepad]. See Bugzilla for this specification's open bugs.

Introduction

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.

GamepadHand Enum

This enum defines the set of possible hands a gamepad may be held by. 

        enum GamepadHand {
          "",  /* unknown, both hands, or not applicable */
          "left",
          "right"
        };
"" (the empty string)
The empty string indicates the hand that is holding the gamepad is unknown or not applicable (e.g., if the gamepad is held with two hands).
"left"
Gamepad is held or is most likely to be held in the left hand.
right
Gamepad is held or is most likely to be held in the right hand.

GamepadHapticActuator Interface

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 pulse(double value, double duration);
        };
pulse

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.

GamepadHapticActuatorType Enum

The actuator type determines the force applied for a given value in GamepadHapticActuator.pulse(). 

        enum GamepadHapticActuatorType {
          "vibration"
        };
vibration
Vibration is a rumbling effect often implemented as an offset weight driven on a rotational axis. The 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.

GamepadPose Interface

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
The hasOrientation attribute MUST return whether the gamepad is capable of tracking its orientation.
hasPosition
The hasPosition attribute MUST return whether the gamepad is capable of tracking its position.
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:

  • Positive X is to the user's right.
  • Positive Y is up.
  • Positive Z is behind the user.

MUST be null if the gamepad is incapable of providing positional data. When not null, MUST be a three-element array.

linearVelocity
Linear velocity of the gamepad in meters per second. MUST be null if the sensor is incapable of providing linear velocity. When not null, MUST be a three-element array.
linearAcceleration
Linear acceleration of the gamepad in meters per second. MUST be null if the sensor is incapable of providing linear acceleration. When not null, MUST be a three-element array.
orientation
Orientation of the gamepad as a quaternion. An orientation of [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.
angularVelocity
Angular velocity of the gamepad in meters per second. MUST be null if the sensor is incapable of providing angular velocity. When not null, the angularVelocity MUST be a three-element array.
angularAcceleration
Angular acceleration of the gamepad in meters per second. MUST be null if the sensor is incapable of providing angular acceleration. When not null, angularAcceleration MUST be a three-element array.

GamepadLightIndicatorType Enum

This enum defines the type of light indicators supported by gamepads. 

        enum GamepadLightIndicatorType {
          "on-off",
          "rgb"
        };
"on-off"
Light indicator that supports a single color.
"rgb"
Light indicator that supports multiple colors.

GamepadLightColor

This represents the color of a light indicator. 

        dictionary GamepadLightColor {
          required octet red;
          required octet green;
          required octet blue;
       };
red
Red component of the light color, or non-zero value for an on-off light indicator that indicates ON.
green
Blue component of the light color, or non-zero value for an on-off light indicator that indicates ON.
blue
Green component of the light color, or non-zero value for an on-off light indicator that indicates ON.

GamepadLightIndicator

This interface defines a light indicator. 

        interface GamepadLightIndicator {
          readonly attribute GamepadLightIndicatorType type;
        
          Promise setColor(GamepadLightColor color);
      };
type
Type of light indicator supported by the gamepad.
setColor
Sets the color of a light indicator, or sets the light indicator to ON or OFF. For on-off light indicators, one or more non zero values denotes the light indicator is ON, whereas a zero value for all components indicates the light indicator is OFF. For RGB light indicators, one or more non zero values specify the color of the light indicator, whereas all zero values indicate the light indicator is OFF. The returned Promise will resolve true when setting the color has succeeded, and will reject the device API error code on failure.

Partial Gamepad Interface

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<GamepadLightIndicator>?
          lightIndicators;
        };
hand
Describes the hand the controller is held in or is most likely to be held in.
hapticActuators
A list of all the haptic actuators in the gamepad. The same object MUST be returned until the user agent needs to return different values (or values in a different order).
pose
The current pose of the gamepad, if supported by the hardware. Includes position, orientation, velocity, and acceleration. If the hardware cannot supply any pose values, MUST be set to null.
lightIndicators
A list of all light indicators in the gamepad. null if the gamepad does not have or does not support a light indicator.