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.

GamepadPose Interface

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

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.

GamepadTouch Interface

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;
        };
      

touchId attribute

Unique id of the touch event. Range is [0, 4294967295].

The user agent is responsible for:

• Incrementing the id for each subsequent touch event based on information provided by the device API.
• Maintaining the uniqueness of the id per origin to prevent fingerprinting.

{{GamepadTouch/touchId}} SHOULD be set to a default value of 0 when a new {{Gamepad}} object is created.

surfaceId

Unique id of the surface that generated the touch event.

position

x, y coordinates of the touch event. Range of each coordinate is normalized to [-1.0, 1.0]. Along the x-axis, -1.0 references the leftmost coordinate and 1.0 references the rightmost coordinate. Along the y-axis, -1.0 references the topmost coordinate and 1.0 references the bottommost coordinate. MUST be a two-element array.

surfaceDimensions

Width and height of the touch surface in integer units. When not null, MUST be a two-element array.

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<GamepadTouch>? touchEvents;
        };
      

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

hand

An enumeration, {{GamepadHand}}, that indicates which hand the controller is being held in or is most likely to be held in.

hapticActuators

A list of all the {{GamepadHapticActuator}}s 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 {{GamepadPose}} 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`.

touchEvents

A list of {{GamepadTouch}} events generated from all touch surfaces. If the device does not support touch events, MUST be set to `null`.

The {{Gamepad/touchEvents}} getter steps are:

1. If [=this=].{{Gamepad/[[touchEvents]]}} not `null` and not empty, return [=this=].{{Gamepad/[[touchEvents]]}}.
2. Otherwise return `null`.

Partial GamepadHapticActuator Interface

This partial interface supplements the {{GamepadHapticActuator}} interface described in the main Gamepad spec.

        [Exposed=Window]
        partial interface GamepadHapticActuator {
          Promise<boolean> pulse(double value, double duration);
        };
      

Glossary

touch surface is a surface that can detect contact from a users fingers and report where on the surface the contact is made.

touch surface enumeration order is an ordered listing of all the surfaces in a |gamepad|.

active touch point is defined in the Touch Events - Level 2 specification.