index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>
      Gamepad
    </title>
    <meta charset="utf-8"><!--
      === NOTA BENE ===
      For the three scripts below, if your spec resides on dev.w3 you can check them
      out in the same tree and use relative links so that they'll work offline,
     -->

    <script src='https://www.w3.org/Tools/respec/respec-w3c' class=
    'remove'></script>
    <script class='remove'>
      var respecConfig = {
          previousMaturity: "FPWD",
          shortName: "gamepad",
          // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
          specStatus:           "ED",
          // if your specification has a subtitle that goes below the main
          // formal title, define it here
          // subtitle   :  "an excellent document",

          // if you wish the publication date to be other than today, set this
          //publishDate:  "2011-01-01",

          // if the specification's copyright date is a range of years, specify
          // the start date here:
          // copyrightStart: "2005"

          // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
          // and its maturity status
          testSuiteURI: "https://wpt.live/gamepad/",

          // if this is a LCWD, uncomment and set the end of its review period
          // lcEnd: "2009-08-05",

          // editors, add as many as you like
          // only "name" is required
          editors:  [
              { name: "Steve Agoston", w3cid: "103815",
                company: "Sony", companyURL: "https://www.sony.com/"},
              { name: "Matt Reynolds", w3cid: "105511",
                company: "Google", companyURL: "https://www.google.com/"},
          ],

          formerEditors: [
              { name: "James Hollyer", w3cid: 115233,
                company: "Google", companyURL: "https://www.google.com/"},
              { name: "Brandon Jones", url: "http://tojicode.com/",
                company: "Google", companyURL: "http://www.google.com/",
                w3cid: 87824 },
              { name: "Scott Graham", url: "http://h4ck3r.net/",
                company: "Google", companyURL: "https://www.google.com/",
                w3cid: 49028 },
              { name: "Ted Mielczarek", url: "http://ted.mielczarek.org/",
                company: "Mozilla", companyURL: "http://www.mozilla.org/",
                w3cid: 49656 },
          ],

          github: "w3c/gamepad",

          group: "webapps",

          implementationReportURI: "https://wpt.fyi/results/gamepad",
          caniuse: "gamepad",
          xref: ["HTML", "DOM", "PERMISSIONS-POLICY", "HR-TIME", "Infra", "geometry-1"],
      };
    </script>
  </head>
  <body data-cite="">
    <section id='abstract'>
      <p>
        The Gamepad specification defines a low-level interface that represents
        gamepad devices.
      </p>
    </section>
    <section id='sotd'>
      <p>
        This is a work in progress.
      </p>
    </section>
    <section id='introduction' class='informative'>
      <h2>
        Introduction
      </h2>
      <p>
        Some [=user agent=]s have connected gamepad devices. These devices are
        desirable and suited to input for gaming applications, and for "10
        foot" user interfaces (presentations, media viewers).
      </p>
      <p>
        Currently, the only way for a gamepad to be used as input would be to
        emulate mouse or keyboard events, however this would lose information
        and require additional software outside of the [=user agent=] to
        accomplish emulation.
      </p>
      <p>
        Meanwhile, native applications are capable of accessing these devices
        via system APIs.
      </p>
      <p>
        The Gamepad API provides a solution to this problem by specifying
        interfaces that allow web applications to directly act on gamepad data.
      </p>
    </section>
    <section>
      <h2>
        Scope
      </h2>
      <p>
        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.
      </p>
      <p>
        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].
      </p>
      <p>
        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.
      </p>
      <p>
        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.
      </p>
    </section>
    <section data-dfn-for="Gamepad" data-link-for="Gamepad">
      <h2>
        <dfn>Gamepad</dfn> interface
      </h2>
      <p>
        This interface defines an individual gamepad device.
      </p>
      <pre class="idl" data-cite="HR-TIME">
        [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&lt;double&gt; axes;
          readonly attribute FrozenArray&lt;GamepadButton&gt; buttons;
          readonly attribute FrozenArray&lt;GamepadTouch&gt; touches;
          [SameObject] readonly attribute GamepadHapticActuator vibrationActuator;
        };
      </pre>
      <p>
        The algorithms used to communicate with the system typically complete
        asynchronously, queuing work on the <dfn>gamepad task source</dfn>.
      </p>
      <p>
        Instances of {{Gamepad}} are created with the internal slots described
        in the following table:
      </p>
      <table class="simple">
        <tr>
          <th>
            Internal slot
          </th>
          <th>
            Initial value
          </th>
          <th>
            Description (non-normative)
          </th>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Gamepad">[[\connected]]</dfn>
          </td>
          <td>
            `false`
          </td>
          <td>
            A flag indicating that the device is connected to the system
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Gamepad">[[\timestamp]]</dfn>
          </td>
          <td>
            undefined
          </td>
          <td>
            The last time data for this {{Gamepad}} was updated
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Gamepad">[[\axes]]</dfn>
          </td>
          <td>
            An empty [=sequence=]
          </td>
          <td>
            A [=sequence=] of {{double}} values representing the current state
            of axes exposed by this device
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Gamepad">[[\buttons]]</dfn>
          </td>
          <td>
            An empty [=sequence=]
          </td>
          <td>
            A [=sequence=] of {{GamepadButton}} objects representing the
            current state of buttons exposed by this device
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Gamepad">[[\exposed]]</dfn>
          </td>
          <td>
            `false`
          </td>
          <td>
            A flag indicating that the {{Gamepad}} object has been exposed to
            script
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Gamepad">[[\axisMapping]]</dfn>
          </td>
          <td>
            An empty [=ordered map=]
          </td>
          <td>
            Mapping from unmapped axis index to an index in the
            {{Gamepad/axes}} array
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Gamepad">[[\axisMinimums]]</dfn>
          </td>
          <td>
            An empty [=list=]
          </td>
          <td>
            A [=list=] containing the minimum logical value for each axis
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Gamepad">[[\axisMaximums]]</dfn>
          </td>
          <td>
            An empty [=list=]
          </td>
          <td>
            A [=list=] containing the maximum logical value for each axis
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Gamepad">[[\buttonMapping]]</dfn>
          </td>
          <td>
            An empty [=ordered map=]
          </td>
          <td>
            Mapping from unmapped button index to an index in the
            {{Gamepad/buttons}} array
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Gamepad">[[\buttonMinimums]]</dfn>
          </td>
          <td>
            An empty [=list=]
          </td>
          <td>
            A [=list=] containing the minimum logical value for each button.
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Gamepad">[[\buttonMaximums]]</dfn>
          </td>
          <td>
            An empty [=list=]
          </td>
          <td>
            A [=list=] containing the maximum logical value for each button
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Gamepad">[[\touches]]</dfn>
          </td>
          <td>
            Initialize to an [=list/is empty=] [=list=]
          </td>
          <td>
            Holds the list of user-generated touches, if any. If the gamepad
            does not support touch surfaces, then the list will remain empty.
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Gamepad">[[\nextTouchId]]</dfn>
          </td>
          <td>
            Initialize to 0
          </td>
          <td>
            Touch id to use for the next incoming touch.
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Gamepad">[[\vibrationActuator]]</dfn>
          </td>
          <td>
            undefined
          </td>
          <td>
            A {{GamepadHapticActuator}} object capable of generating a haptic
            effect that vibrates the entire gamepad
          </td>
        </tr>
      </table>
      <dl>
        <dt>
          <dfn>id</dfn> attribute
        </dt>
        <dd>
          <p>
            An identification string for the gamepad. This string identifies
            the brand or style of connected gamepad device.
          </p>
          <p>
            The exact format of the {{Gamepad/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
            {{Gamepad/id}} string.
          </p>
        </dd>
        <dt>
          <dfn>index</dfn> attribute
        </dt>
        <dd>
          The index of the gamepad in the {{Navigator}}. When multiple gamepads
          are connected to a [=user agent=], indices MUST be assigned on a
          first-come, first-serve basis, starting at zero. If a gamepad is
          disconnected, previously assigned indices MUST NOT be reassigned to
          gamepads that continue to be connected. However, if a gamepad is
          disconnected, and subsequently the same or a different gamepad is
          then connected, the lowest previously used index MUST be reused.
        </dd>
        <dt>
          <dfn>connected</dfn> attribute
        </dt>
        <dd>
          <p>
            Indicates whether the physical device represented by this object is
            still connected to the system. When a gamepad becomes unavailable,
            whether by being physically disconnected, powered off or otherwise
            unusable, the {{Gamepad/connected}} attribute MUST be set to
            `false`.
          </p>
          <p>
            The {{Gamepad/connected}} getter steps are:
          </p>
          <ol>
            <li>Return [=this=].{{Gamepad/[[connected]]}}.
            </li>
          </ol>
        </dd>
        <dt>
          <dfn>timestamp</dfn> attribute
        </dt>
        <dd>
          <p>
            The {{Gamepad/timestamp}} allows the author to determine the last
            time the {{Gamepad/axes}} or {{Gamepad/buttons}} attribute for this
            gamepad was updated. The value MUST be set to the [=current high
            resolution time=] each time the system [=receives new button or
            axis input values=] from the device. If no data has been received
            from the hardware, {{Gamepad/timestamp}} MUST be the [=current high
            resolution time=] at the time when the {{Gamepad}} was first made
            available to script.
          </p>
          <p class="warning">
            [=User agent=]s SHOULD set a minimum resolution of |gamepad|'s
            {{Gamepad/timestamp}} attribute to 5 microseconds, following
            [[HR-TIME]]'s clock resolution recommendation.
          </p>
          <p>
            The {{Gamepad/timestamp}} getter steps are:
          </p>
          <ol>
            <li>Return [=this=].{{Gamepad/[[timestamp]]}}.
            </li>
          </ol>
        </dd>
        <dt>
          <dfn>mapping</dfn> attribute
        </dt>
        <dd>
          <p>
            The mapping in use for this device. If the user agent has knowledge
            of the layout of the device, then it SHOULD indicate that a mapping
            is in use by setting {{Gamepad/mapping}} to the corresponding
            {{GamepadMappingType}} value.
          </p>
          <p>
            To <dfn data-lt="selecting a mapping">select a mapping</dfn> for a
            gamepad device, run the following steps:
          </p>
          <ol>
            <li>If the button and axis layout of the gamepad device corresponds
            with the [=Standard Gamepad=] layout, then return
            {{GamepadMappingType/"standard"}}.
            </li>
            <li>Return {{GamepadMappingType/""}}.
            </li>
          </ol>
        </dd>
        <dt>
          <dfn>axes</dfn> attribute
        </dt>
        <dd>
          <p>
            Array of values for all axes of the gamepad. All axis values MUST
            be linearly normalized to the range [-1.0 .. 1.0]. If the
            controller is perpendicular to the ground with the directional
            stick pointing up, -1.0 SHOULD correspond to "forward" or "left",
            and 1.0 SHOULD correspond to "backward" or "right". Axes that are
            drawn from a 2D input device SHOULD appear next to each other in
            the axes array, X then Y. It is RECOMMENDED that axes appear in
            decreasing order of importance, such that element 0 and 1 typically
            represent the X and Y axis of a directional stick. The same object
            MUST be returned until the [=user agent=] needs to return different
            values (or values in a different order).
          </p>
          <p>
            The {{Gamepad/axes}} getter steps are:
          </p>
          <ol>
            <li>Return [=this=].{{Gamepad/[[axes]]}}.
            </li>
          </ol>
        </dd>
        <dt>
          <dfn>buttons</dfn> attribute
        </dt>
        <dd>
          <p>
            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).
          </p>
          <p>
            The {{Gamepad/buttons}} getter steps are:
          </p>
          <ol>
            <li>Return [=this=].{{Gamepad/[[buttons]]}}.
            </li>
          </ol>
        </dd>
        <dt>
          <dfn>touches</dfn> attribute
        </dt>
        <dd>
          <p>
            A [=list=] of {{GamepadTouch}} objects generated from all touch
            surfaces.
          </p>
          <p>
            The {{Gamepad/touches}} getter steps are:
          </p>
          <ol>
            <li>Return [=this=].{{Gamepad/[[touches]]}}.
            </li>
          </ol>
        </dd>
        <dt>
          <dfn>vibrationActuator</dfn> attribute
        </dt>
        <dd>
          <p>
            A {{GamepadHapticActuator}} object that represents the device's
            primary vibration actuator.
          </p>
          <p>
            The {{Gamepad/vibrationActuator}} getter steps are:
          </p>
          <ol>
            <li>Return [=this=].{{Gamepad/[[vibrationActuator]]}}.
            </li>
          </ol>
        </dd>
      </dl>
      <section>
        <h3>
          Receiving inputs
        </h3>
        <p>
          When the system <dfn>receives new button or axis input values</dfn>,
          run the following steps:
        </p>
        <ol>
          <li>Let |gamepad:Gamepad| be the {{Gamepad}} object representing the
          device that received new button or axis input values.
          </li>
          <li>[=Queue a task=] on the [=gamepad task source=] to [=update
          gamepad state=] for |gamepad|.
          </li>
        </ol>
        <p>
          To <dfn>update gamepad state</dfn> for |gamepad:Gamepad|, run the
          following steps:
        </p>
        <ol>
          <li>Let |now:DOMHighResTimeStamp| be the [=current high resolution
          time=].
          </li>
          <li>Set |gamepad|.{{Gamepad/[[timestamp]]}} to |now|.
          </li>
          <li>Run the steps to [=map and normalize axes=] for |gamepad|.
          </li>
          <li>Run the steps to [=map and normalize buttons=] for |gamepad|.
          </li>
          <li>Run the steps to [=record touches=] for |gamepad|.
          </li>
          <li>Let |navigator:Navigator| be |gamepad|'s [=relevant global
          object=]'s {{Navigator}} object.
          </li>
          <li>If |navigator|.{{Navigator/[[hasGamepadGesture]]}} is `false` and
          |gamepad| [=contains a gamepad user gesture=]:
            <ol>
              <li>Set |navigator|.{{Navigator/[[hasGamepadGesture]]}} to
              `true`.
              </li>
              <li>[=list/For each=] |connectedGamepad:Gamepad?| of
              |navigator|.{{Navigator/[[gamepads]]}}:
                <ol>
                  <li>If |connectedGamepad| is not equal to `null`:
                    <ol>
                      <li>Set |connectedGamepad|.{{Gamepad/[[exposed]]}} to
                      `true`.
                      </li>
                      <li>Set |connectedGamepad|.{{Gamepad/[[timestamp]]}} to
                      |now|.
                      </li>
                      <li>Let |document:Document?| be |gamepad|'s [=relevant
                      global object=]'s [=associated `Document`=]; otherwise
                      `null`.
                      </li>
                      <li>If |document| is not `null` and is [=Document/fully
                      active=], then [=queue a task=] on the [=gamepad task
                      source=] to [=fire an event=] named {{gamepadconnected}}
                      at |gamepad|'s [=relevant global object=] using
                      {{GamepadEvent}} with its {{GamepadEvent/gamepad}}
                      attribute initialized to |connectedGamepad|.
                      </li>
                    </ol>
                  </li>
                </ol>
              </li>
            </ol>
          </li>
        </ol>
        <p>
          To <dfn>map and normalize axes</dfn> for |gamepad:Gamepad|, run the
          following steps:
        </p>
        <ol>
          <li>Let |axisValues:list| be a [=list=] of {{unsigned long}} values
          representing the most recent logical axis input values for each axis
          input of the device represented by |gamepad|.
          </li>
          <li>Let |maxRawAxisIndex:long| be the [=list/size=] of |axisValues| −
          1.
          </li>
          <li>[=list/For each=] |rawAxisIndex:long| of [=the range=] from 0 to
          |maxRawAxisIndex|:
            <ol>
              <li>Let |mappedIndex:long| be
              |gamepad|.{{Gamepad/[[axisMapping]]}}[|rawAxisIndex|].
              </li>
              <li>Let |logicalValue:unsigned long| be
              |axisValues|[|rawAxisIndex|].
              </li>
              <li>Let |logicalMinimum:unsigned long| be
              |gamepad|.{{Gamepad/[[axisMinimums]]}}[|rawAxisIndex|].
              </li>
              <li>Let |logicalMaximum:unsigned long| be
              |gamepad|.{{Gamepad/[[axisMaximums]]}}[|rawAxisIndex|].
              </li>
              <li>Let |normalizedValue:double| be 2 (|logicalValue| −
              |logicalMinimum|) / (|logicalMaximum| − |logicalMinimum|) − 1.
              </li>
              <li>Set |gamepad|.{{Gamepad/[[axes]]}}[|axisIndex|] to be
              |normalizedValue|.
              </li>
            </ol>
          </li>
        </ol>
        <p>
          To <dfn>map and normalize buttons</dfn> for |gamepad:Gamepad|, run
          the following steps:
        </p>
        <ol>
          <li>Let |buttonValues:list| be a [=list=] of {{unsigned long}} values
          representing the most recent logical button input values for each
          button input of the device represented by |gamepad|.
          </li>
          <li>Let |maxRawButtonIndex:long| be the [=list/size=] of
          |buttonValues| − 1.
          </li>
          <li>[=list/For each=] |rawButtonIndex:long| of [=the range=] from 0
          to |maxRawButtonIndex|:
            <ol>
              <li>Let |mappedIndex:long| be
              |gamepad|.{{Gamepad/[[buttonMapping]]}}[|rawButtonIndex|].
              </li>
              <li>Let |logicalValue:unsigned long| be
              |buttonValues|[|rawButtonIndex|].
              </li>
              <li>Let |logicalMinimum:unsigned long| be
              |gamepad|.{{Gamepad/[[buttonMinimums]]}}[|rawButtonIndex|].
              </li>
              <li>Let |logicalMaximum:unsigned long| be
              |gamepad|.{{Gamepad/[[buttonMaximums]]}}[|rawButtonIndex|].
              </li>
              <li>Let |normalizedValue:double| be (|logicalValue| −
              |logicalMinimum|) / (|logicalMaximum| − |logicalMinimum|).
              </li>
              <li>Let |button:GamepadButton| be
              |gamepad|.{{Gamepad/[[buttons]]}}[|mappedIndex|].
              </li>
              <li>Set |button|.{{GamepadButton/[[value]]}} to
              |normalizedValue|.
              </li>
              <li>
                <p>
                  If the button has a digital switch to indicate a pure pressed
                  or released state, set |button|.{{GamepadButton/[[pressed]]}}
                  to `true` if the button is pressed or `false` if it is not
                  pressed.
                </p>
                <p>
                  Otherwise, set |button|.{{GamepadButton/[[pressed]]}} to
                  `true` if the value is above the [=button press threshold=]
                  or `false` if it is not above the threshold.
                </p>
              </li>
              <li>
                <p>
                  If the button is capable of detecting touch, set
                  |button|.{{GamepadButton/[[touched]]}} to `true` if the
                  button is currently being touched.
                </p>
                <p>
                  Otherwise, set |button|.{{GamepadButton/[[touched]]}} to
                  |button|.{{GamepadButton/[[pressed]]}}.
                </p>
              </li>
            </ol>
          </li>
        </ol>
        <p>
          To <dfn>record touches</dfn> for |gamepad:Gamepad|, run the following
          steps:
        </p>
        <ol class="algorithm">
          <li>Assert: {{Gamepad}}.{{Gamepad/[[touches]]}} is [=list/empty=].
          </li>
          <li>Repeat the following steps for each touch surface on |gamepad| in
          touch surface enumeration order:
            <ol>
              <li>Let |surfaceId:unsigned long| be the current surface
              enumeration index.
              </li>
              <li>If the touch surface exposes maximum surface dimensions in
              device units, then set |touch|.{{GamepadTouch/surfaceDimensions}}
              to a {{DOMRectReadOnly}} with {{DOMRectReadOnly/width}} and
              {{DOMRectReadOnly/height}} initialized to the maximum X and Y
              dimensions on the touch surface in device units.
              </li>
              <li>Repeat the following steps for each active touch point
              reported by the |gamepad| for the current touch surface.
                <ol>
                  <li>Let |touch:GamepadTouch| be a newly created
                  {{GamepadTouch}} object.
                  </li>
                  <li>Set |touch|.{{GamepadTouch/surfaceId}} to be |surfaceId|.
                  </li>
                  <li>If the touch data is part of an existing active touch
                  point tracked by the user agent:
                    <ol>
                      <li>Set |touch|.{{GamepadTouch/touchId}} to the touchId
                      of the active touch point.
                      </li>
                      <li>Otherwise, set touchId to nextTouchId and increment
                      nextTouchId.
                        <p class="note" title=
                        "Touch ids are relative to the Gamepad">
                          If the Gamepad has multiple touch surfaces the touch
                          id will be unique across surfaces.
                        </p>
                      </li>
                    </ol>
                  </li>
                  <li>Set |touch|.{{GamepadTouch/position}} to a [=new=]
                  {{DOMPointReadOnly}} with {{DOMPointReadOnly/x}} initialized
                  to device X coordinate relative to the device touch surface
                  and normalized to [-1.0,1.0] where -1.0 is the leftmost
                  coordinate and 1.0 is the rightmost coordinate and
                  {{DOMPointReadOnly/y}} initialized to the device touch
                  surface and normalized to [-1.0,1.0] where -1.0 is the
                  leftmost coordinate and 1.0 is the rightmost coordinate.
                    <p class="note" title=
                    "Possible implementation (if surfaceDimensions are available)">
                      `x = (2.0 * touchData.x / surfaceDimensions.width) - 1`
                    </p>
                    <p class="note" title=
                    "Possible implementation (if surfaceDimensions are available)">
                      `y = (2.0 * touchData.y / surfaceDimensions.height) - 1`
                    </p>
                  </li>
                  <li>Add |touch| to {{Gamepad}}.{{Gamepad/[[touches]]}}.
                  </li>
                </ol>
              </li>
            </ol>
          </li>
        </ol>
      </section>
      <section>
        <h3>
          Constructing a `Gamepad`
        </h3>
        <p>
          <dfn>A new `Gamepad`</dfn> representing a connected gamepad device is
          constructed by performing the following steps:
        </p>
        <ol>
          <li>Let |gamepad:Gamepad| be a newly created {{Gamepad}} instance:
            <ol>
              <li>Initialize |gamepad|'s {{Gamepad/id}} attribute to an
              identification string for the gamepad.
              </li>
              <li>Initialize |gamepad|'s {{Gamepad/index}} attribute to the
              result of [=selecting an unused gamepad index=] for |gamepad|.
              </li>
              <li>Initialize |gamepad|'s {{Gamepad/mapping}} attribute to the
              result of [=selecting a mapping=] for the gamepad device.
              </li>
              <li>Initialize |gamepad|.{{Gamepad/[[connected]]}} to `true`.
              </li>
              <li>Initialize |gamepad|.{{Gamepad/[[timestamp]]}} to the
              [=current high resolution time=].
              </li>
              <li>Initialize |gamepad|.{{Gamepad/[[axes]]}} to the result of
              [=initializing axes=] for |gamepad|.
              </li>
              <li>Initialize |gamepad|.{{Gamepad/[[buttons]]}} to the result of
              [=initializing buttons=] for |gamepad|.
              </li>
              <li>Initialize |gamepad|.{{Gamepad/[[vibrationActuator]]}}
              following the steps of [=constructing a GamepadHapticActuator=]
              for |gamepad|.
              </li>
            </ol>
          </li>
          <li>Return |gamepad|.
          </li>
        </ol>
        <p>
          To <dfn data-lt="selecting an unused gamepad index">select an unused
          gamepad index</dfn> for |gamepad:Gamepad|, run the following steps:
        </p>
        <ol>
          <li>Let |navigator:Navigator| be |gamepad|'s [=relevant global
          object=]'s {{Navigator}} object.
          </li>
          <li>Let |maxGamepadIndex:long| be the [=list/size=] of
          |navigator|.{{Navigator/[[gamepads]]}} − 1.
          </li>
          <li>[=list/For each=] |gamepadIndex:long| of [=the range=] from 0 to
          |maxGamepadIndex|:
            <ol>
              <li>If |navigator|.{{Navigator/[[gamepads]]}}[|gamepadIndex|] is
              `null`, then return |gamepadIndex|.
              </li>
            </ol>
          </li>
          <li>[=list/Append=] `null` to |navigator|.{{Navigator/[[gamepads]]}}.
          </li>
          <li>Return the [=list/size=] of
          |navigator|.{{Navigator/[[gamepads]]}} − 1.
          </li>
        </ol>
        <p>
          To <dfn data-lt="initializing axes">initialize axes</dfn> for
          |gamepad:Gamepad|, run the following steps:
        </p>
        <ol>
          <li>Let |inputCount:long| be the number of axis inputs exposed by the
          device represented by |gamepad|.
          </li>
          <li>Set |gamepad|.{{Gamepad/[[axisMinimums]]}} to a [=list=] of
          {{unsigned long}} values with [=list/size=] equal to |inputCount|
          containing minimum logical values for each of the axis inputs.
          </li>
          <li>Set |gamepad|.{{Gamepad/[[axisMaximums]]}} to a [=list=] of
          {{unsigned long}} values with [=list/size=] equal to |inputCount|
          containing maximum logical values for each of the axis inputs.
          </li>
          <li>Initialize |unmappedInputList| to be an empty [=list=].
          </li>
          <li>Initialize |mappedIndexList| to be an empty [=list=].
          </li>
          <li>Initialize |axesSize:long| to be 0.
          </li>
          <li>[=list/For each=] |rawInputIndex:long| of [=the range=] from 0 to
          |inputCount| − 1:
            <ol>
              <li>If the the gamepad axis at index |rawInputIndex| [=represents
              a Standard Gamepad axis=]:
                <ol>
                  <li>Let |canonicalIndex:long| be the [=canonical index=] for
                  the axis.
                  </li>
                  <li>If |mappedIndexList| [=list/contain=]s |canonicalIndex|,
                  then append |rawInputIndex| to |unmappedInputList|.
                    <p>
                      Otherwise:
                    </p>
                    <ol>
                      <li>Set
                      |gamepad|.{{Gamepad/[[axisMapping]]}}[|rawInputIndex|] to
                      |canonicalIndex|.
                      </li>
                      <li>[=list/Append=] |canonicalIndex| to
                      |mappedIndexList|.
                      </li>
                      <li>If |canonicalIndex| + 1 is greater than |axesSize|,
                      then set |axesSize| to |canonicalIndex| + 1.
                      </li>
                    </ol>
                  </li>
                </ol>
                <p>
                  Otherwise, [=list/append=] |rawInputIndex| to
                  |unmappedInputList|.
                </p>
              </li>
            </ol>
          </li>
          <li>Initialize |axisIndex:long| to be 0.
          </li>
          <li>[=list/For each=] |rawInputIndex:long| of |unmappedInputList|:
            <ol>
              <li>While |mappedIndexList| [=list/contain=]s |axisIndex|:
                <ol>
                  <li>Increment |axisIndex|.
                  </li>
                </ol>
              </li>
              <li>Set |gamepad|.{{Gamepad/[[axisMapping]]}}[|rawInputIndex|] to
              |axisIndex|.
              </li>
              <li>[=list/Append=] |axisIndex| to |mappedIndexList|.
              </li>
              <li>If |axisIndex| + 1 is greater than |axesSize|, then set
              |axesSize| to |axisIndex| + 1.
              </li>
            </ol>
          </li>
          <li>Initialize |axes| to be an empty [=list=].
          </li>
          <li>[=list/For each=] |axisIndex:long| of [=the range=] from 0 to
          |axesSize| − 1, [=list/append=] 0 to |axes|.
          </li>
          <li>Return |axes|.
          </li>
        </ol>
        <p>
          To <dfn data-lt="initializing buttons">initialize buttons</dfn> for a
          gamepad, run the following steps:
        </p>
        <ol>
          <li>Let |inputCount:long| be the number of button inputs exposed by
          the device represented by |gamepad|.
          </li>
          <li>Set |gamepad|.{{Gamepad/[[buttonMinimums]]}} to be a [=list=] of
          {{unsigned long}} values with [=list/size=] equal to |inputCount|
          containing minimum logical values for each of the button inputs.
          </li>
          <li>Set |gamepad|.{{Gamepad/[[buttonMaximums]]}} to be a [=list=] of
          {{unsigned long}} values with [=list/size=] equal to |inputCount|
          containing maximum logical values for each of the button inputs.
          </li>
          <li>Initialize |unmappedInputList| to be an empty [=list=].
          </li>
          <li>Initialize |mappedIndexList| to be an empty [=list=].
          </li>
          <li>Initialize |buttonsSize:long| to be 0.
          </li>
          <li>[=list/For each=] |rawInputIndex:long| of [=the range=] from 0 to
          |inputCount| − 1:
            <ol>
              <li>If the the gamepad button at index |rawInputIndex|
              [=represents a Standard Gamepad button=]:
                <ol>
                  <li>Let |canonicalIndex:long| be the [=canonical index=] for
                  the button.
                  </li>
                  <li>If |mappedIndexList| [=list/contain=]s |canonicalIndex|,
                  then append |rawInputIndex| to |unmappedInputList|.
                    <p>
                      Otherwise:
                    </p>
                    <ol>
                      <li>Set
                      |gamepad|.{{Gamepad/[[buttonMapping]]}}[|rawInputIndex|]
                      to |canonicalIndex|.
                      </li>
                      <li>[=list/Append=] |canonicalIndex| to
                      |mappedIndexList|.
                      </li>
                      <li>If |canonicalIndex| + 1 is greater than
                      |buttonsSize|, then set |buttonsSize| to |canonicalIndex|
                      + 1.
                      </li>
                    </ol>
                  </li>
                </ol>
                <p>
                  Otherwise, [=list/append=] |rawInputIndex| to
                  |unmappedInputList|.
                </p>
              </li>
              <li>Increment |rawInputIndex|.
              </li>
            </ol>
          </li>
          <li>Initialize |buttonIndex:long| to be 0.
          </li>
          <li>[=list/For each=] |rawInputIndex:long| of |unmappedInputList|:
            <ol>
              <li>While |mappedIndexList| [=list/contain=]s |buttonIndex|:
                <ol>
                  <li>Increment |buttonIndex|.
                  </li>
                </ol>
              </li>
              <li>Set |gamepad|.{{Gamepad/[[buttonMapping]]}}[|rawInputIndex|]
              to |buttonIndex|.
              </li>
              <li>[=list/Append=] |buttonIndex| to |mappedIndexList|.
              </li>
              <li>If |buttonIndex| + 1 is greater than |buttonsSize|, then set
              |buttonsSize| to |buttonIndex| + 1.
              </li>
            </ol>
          </li>
          <li>Initialize |buttons| to be an empty [=list=].
          </li>
          <li>[=list/For each=] |buttonIndex:long| of [=the range=] from 0 to
          |buttonsSize| − 1, [=list/append=] a [=new=] {{GamepadButton}} to
          |buttons|.
          </li>
          <li>Return |buttons|.
          </li>
        </ol>
      </section>
    </section>
    <section data-dfn-for="GamepadButton" data-link-for="GamepadButton">
      <h2>
        <dfn>GamepadButton</dfn> Interface
      </h2>
      <p>
        This interface defines the state of an individual button on a gamepad
        device.
      </p>
      <pre class="idl">
        [Exposed=Window]
        interface GamepadButton {
          readonly attribute boolean pressed;
          readonly attribute boolean touched;
          readonly attribute double value;
        };
      </pre>
      <p>
        Instances of {{GamepadButton}} are created with the internal slots
        described in the following table:
      </p>
      <table class="simple">
        <tr>
          <th>
            Internal slot
          </th>
          <th>
            Initial value
          </th>
          <th>
            Description (non-normative)
          </th>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="GamepadButton">[[\pressed]]</dfn>
          </td>
          <td>
            `false`
          </td>
          <td>
            A flag indicating that the button is pressed
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="GamepadButton">[[\touched]]</dfn>
          </td>
          <td>
            `false`
          </td>
          <td>
            A flag indicating that the button is touched
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="GamepadButton">[[\value]]</dfn>
          </td>
          <td>
            0.0
          </td>
          <td>
            A {{double}} representing the button value scaled to the range [0.0
            .. 1.0]
          </td>
        </tr>
      </table>
      <dl>
        <dt>
          <dfn>pressed</dfn> attribute
        </dt>
        <dd>
          <p>
            The pressed state of the button. 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
            <dfn>button press threshold</dfn> 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.
          </p>
          <p>
            The {{GamepadButton/pressed}} getter steps are:
          </p>
          <ol>
            <li>Return [=this=].{{GamepadButton/[[pressed]]}}.
            </li>
          </ol>
        </dd>
        <dt>
          <dfn>touched</dfn> attribute
        </dt>
        <dd>
          <p>
            The touched state of the button. If the button is capable of
            detecting touch, this property MUST be `true` if the button is
            currently being touched, and `false` otherwise. If the button is
            not capable of detecting touch and is capable of reporting an
            analog value, this property MUST be `true` if the value property is
            greater than 0, and `false` if the value is 0. If the button is not
            capable of detecting touch and can only report a digital value,
            this property MUST mirror the {{GamepadButton/pressed}} attribute.
          </p>
          <p>
            The {{GamepadButton/touched}} getter steps are:
          </p>
          <ol>
            <li>Return [=this=].{{GamepadButton/[[touched]]}}.
            </li>
          </ol>
        </dd>
        <dt>
          <dfn>value</dfn> attribute
        </dt>
        <dd>
          <p>
            For buttons that have an analog sensor, this property MUST
            represent the amount which the button has been pressed. All button
            values MUST be linearly normalized to the range [0.0 .. 1.0]. 0.0
            MUST mean fully unpressed, and 1.0 MUST mean fully pressed. For
            buttons without an analog sensor, only the values 0.0 and 1.0 for
            fully unpressed and fully pressed respectively, MUST be provided.
          </p>
          <p>
            The {{GamepadButton/value}} getter steps are:
          </p>
          <ol>
            <li>Return [=this=].{{GamepadButton/[[value]]}}.
            </li>
          </ol>
        </dd>
      </dl>
    </section>
    <section data-dfn-for="GamepadTouch">
      <h2>
        <dfn>GamepadTouch</dfn> Interface
      </h2>
      <p>
        This interface defines a touch on a gamepad's touch surface that
        supports such input. The object consists of a touch
        {{GamepadTouch/touchId}} 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.
      </p>
      <pre class="idl" data-cite="geometry-1">
        dictionary GamepadTouch {
          unsigned long touchId;
          octet surfaceId;
          DOMPointReadOnly position;
          DOMRectReadOnly? surfaceDimensions;
        };
      </pre>
      <dl>
        <dt>
          <dfn>touchId</dfn> attribute
        </dt>
        <dd>
          Unique id of the touch. Range is [0, 4294967295].
        </dd>
        <dt>
          <dfn>surfaceId</dfn>
        </dt>
        <dd>
          Unique id of the surface that generated the touch.
        </dd>
        <dt>
          <dfn>position</dfn>
        </dt>
        <dd>
          A {{DOMPointReadOnly}} which holds the {{DOMPointReadOnly/x}},
          {{DOMPointReadOnly/y}} coordinates of the touch. The z and w value
          are currently unused. The 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.
        </dd>
        <dt>
          <dfn>surfaceDimensions</dfn>
        </dt>
        <dd>
          A {{DOMRectReadOnly}} initialized with the {{DOMRectReadOnly/width}}
          and {{DOMRectReadOnly/height}} of the touch surface in integer units.
          If not available then <code>null</code>.
        </dd>
      </dl>
    </section>
    <section data-dfn-for="GamepadMappingType">
      <h2>
        <dfn>GamepadMappingType</dfn> enum
      </h2>
      <p>
        This enum defines the set of known mappings for a Gamepad.
      </p>
      <pre class="idl">
        enum GamepadMappingType {
          "",
          "standard",
          "xr-standard",
        };
      </pre>
      <dl>
        <dt>
          <dfn>""</dfn>
        </dt>
        <dd>
          The empty string indicates that no mapping is in use for this
          gamepad.
        </dd>
        <dt>
          "<dfn>standard</dfn>"
        </dt>
        <dd>
          The Gamepad's controls have been mapped to the [=Standard Gamepad=]
          layout.
        </dd>
        <dt>
          "<dfn>xr-standard</dfn>"
        </dt>
        <dd data-cite="webxr-gamepads-module">
          The Gamepad's controls have been mapped to the [="xr-standard"
          gamepad mapping=]. This mapping is reserved for use by the
          [[[webxr-gamepads-module-1]]]. Gamepads returned by
          {{Navigator/getGamepads()}} MUST NOT report a {{Gamepad/mapping}} of
          {{GamepadMappingType/"xr-standard"}}.
        </dd>
      </dl>
    </section>
    <section data-dfn-for="GamepadHapticActuator" data-link-for=
    "GamepadHapticActuator">
      <h2>
        <dfn>GamepadHapticActuator</dfn> Interface
      </h2>
      <p>
        A {{GamepadHapticActuator}} corresponds to a configuration of motors or
        other actuators that can apply a force for the purposes of haptic
        feedback.
      </p>
      <pre class="idl">
        [Exposed=Window]
        interface GamepadHapticActuator {
          [SameObject] readonly attribute FrozenArray&lt;GamepadHapticEffectType&gt; effects;
          Promise&lt;GamepadHapticsResult&gt; playEffect(
              GamepadHapticEffectType type,
              optional GamepadEffectParameters params = {}
          );
          Promise&lt;GamepadHapticsResult&gt; reset();
        };
      </pre>
      <p>
        Instances of {{GamepadHapticActuator}} are created with the internal
        slots described in the following table:
      </p>
      <table class="simple">
        <tr>
          <th>
            Internal slot
          </th>
          <th>
            Initial value
          </th>
          <th>
            Description
          </th>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="GamepadHapticActuator">[[\effects]]</dfn>
          </td>
          <td>
            An empty [=list=] of {{Gamepad/GamepadHapticEffectType}}.
          </td>
          <td>
            Represents the effects supported by the actuator.
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for=
            "GamepadHapticActuator">[[\playingEffectPromise]]</dfn>
          </td>
          <td>
            `null`
          </td>
          <td>
            The {{Promise}} to play some effect, or `null` if no effect is
            playing.
          </td>
        </tr>
      </table>
      <dl data-dfn-for="GamepadHapticActuator">
        <dt>
          <dfn>effects</dfn> attribute
        </dt>
        <dd>
          <p>
            Array of {{Gamepad/GamepadHapticEffectType}} values representing
            all the types of haptic effects that the actuator supports. This
            property lists the {{Gamepad/GamepadHapticEffectType}} values that
            the actuator supports, unless the [=user agent=] does not support
            playing effects of that type.
          </p>
          <p>
            The {{GamepadHapticActuator/effects}} getter steps are:
          </p>
          <ol>
            <li>Return [=this=].{{GamepadHapticActuator/[[effects]]}}.
            </li>
          </ol>
        </dd>
        <dt>
          <dfn>playEffect()</dfn> method
        </dt>
        <dd>
          <p>
            The {{GamepadHapticActuator/playEffect()}} method steps, called
            with {{GamepadHapticEffectType}} |type:GamepadHapticEffectType| and
            {{GamepadEffectParameters}} |params:GamepadEffectParameters |, are:
          </p>
          <ol class="algorithm">
            <li>If |params:GamepadEffectParameters| does not describe a [=valid
            effect=] of type |type:GamepadHapticEffectType|, return [=a promise
            rejected with=] a {{TypeError}}.
            </li>
            <li>Let |document:Document?| be the [=current settings object=]'s
            [=relevant global object=]'s [=associated `Document`=].
            </li>
            <li>If |document| is `null` or |document| is not [=Document/fully
            active=] or |document|'s [=Document/visibility state=] is
            `"hidden"`, return [=a promise rejected with=] an
            "{{InvalidStateError}}" {{DOMException}}.
            </li>
            <li>If [=this=].{{GamepadHapticActuator/[[playingEffectPromise]]}}
            is not `null`:
              <ol>
                <li>Let |effectPromise| be
                [=this=].{{GamepadHapticActuator/[[playingEffectPromise]]}}.
                </li>
                <li>Set
                [=this=].{{GamepadHapticActuator/[[playingEffectPromise]]}} to
                `null`.
                </li>
                <li>[=Queue a global task=] on the [=relevant global object=]
                of [=this=] using the [=gamepad task source=] to [=resolve=]
                |effectPromise| with {{GamepadHapticsResult/"preempted"}}.
                </li>
              </ol>
            </li>
            <li>If |this|'s gamepad's actuator cannot [=play effects with
            type=] |type|, return [=a promise rejected with=] reason
            {{NotSupportedError}}.
            </li>
            <li>Let {{GamepadHapticActuator/[[playingEffectPromise]]}} be [=a
            new promise=].
            </li>
            <li>Let |playEffectTimestamp:DOMHighResTimestamp| be the [=current
            high resolution time=] given the |document|'s [=relevant global
            object=].
            </li>
            <li>Do the following steps [=in parallel=]:
              <ol>
                <li>[=Issue a haptic effect=] to the actuator with |type|,
                |params|, and the |playEffectTimestamp|.
                </li>
                <li>When the effect completes, if
                [=this=].{{GamepadHapticActuator/[[playingEffectPromise]]}} is
                not `null`, [=queue a global task=] on the [=relevant global
                object=] of [=this=] using the [=gamepad task source=] to run
                the following steps:
                  <ol>
                    <li>If
                    [=this=].{{GamepadHapticActuator/[[playingEffectPromise]]}}
                    is `null`, abort these steps.
                    </li>
                    <li>[=Resolve=]
                    [=this=].{{GamepadHapticActuator/[[playingEffectPromise]]}}
                    with {{GamepadHapticsResult/"complete"}}.
                    </li>
                    <li>Set
                    [=this=].{{GamepadHapticActuator/[[playingEffectPromise]]}}
                    to `null`.
                    </li>
                  </ol>
                </li>
              </ol>
            </li>
            <li>Return {{GamepadHapticActuator/[[playingEffectPromise]]}}.
            </li>
          </ol>
        </dd>
        <dt>
          <dfn>reset()</dfn> method
        </dt>
        <dd>
          <p>
            The {{GamepadHapticActuator/reset()}} method steps are:
          </p>
          <ol class="algorithm">
            <li>Let |document:Document?| be the [=current settings object=]'s
            [=relevant global object=]'s [=associated `Document`=].
            </li>
            <li>If |document| is `null` or |document| is not [=Document/fully
            active=] or |document|'s [=Document/visibility state=] is
            `"hidden"`, return [=a promise rejected with=] an
            "{{InvalidStateError}}" {{DOMException}}.
            </li>
            <li>Let |resetResultPromise:Promise| be [=a new promise=].
            </li>
            <li>If [=this=].{{GamepadHapticActuator/[[playingEffectPromise]]}}
            is not `null`, do the following steps [=in parallel=]:
              <ol>
                <li>Let |effectPromise| be
                [=this=].{{GamepadHapticActuator/[[playingEffectPromise]]}}.
                </li>
                <li>[=Stop haptic effects=] on [=this=]'s gamepad's actuator.
                </li>
                <li>If the effect has been successfully stopped, do:
                  <ol>
                    <li>If |effectPromise| and
                    [=this=].{{GamepadHapticActuator/[[playingEffectPromise]]}}
                    are still the same, set
                    [=this=].{{GamepadHapticActuator/[[playingEffectPromise]]}}
                    to `null`.
                    </li>
                    <li>[=Queue a global task=] on the [=relevant global
                    object=] of [=this=] using the [=gamepad task source=] to
                    [=resolve=] |effectPromise| with
                    {{GamepadHapticsResult/"preempted"}}.
                    </li>
                  </ol>
                </li>
                <li>[=Resolve=] |resetResultPromise| with
                {{GamepadHapticsResult/"complete"}}
                </li>
              </ol>
            </li>
            <li>Return |resetResultPromise|.
            </li>
          </ol>
        </dd>
      </dl>
      <p>
        A {{GamepadHapticActuator}} can <dfn>play effects with type</dfn>
        |type:GamepadHapticEffectType| if |type:GamepadHapticEffectType| can be
        found in the {{GamepadHapticActuator/[[effects]]}} [=list=].
      </p>
      <p>
        To check if an effect with {{GamepadHapticEffectType}}
        |type:GamepadHapticEffectType| and {{GamepadEffectParameters}}
        |params:GamepadEffectParameters| describes a <dfn>valid effect</dfn>,
        run the following steps:
      </p>
      <ol class="algorithm">
        <li>Given the value of {{GamepadHapticEffectType}}
        |type:GamepadHapticEffectType|, switch on:
          <dl>
            <dt>
              {{GamepadHapticEffectType/"dual-rumble"}}
            </dt>
            <dd>
              If |params| does not describe a [=valid dual-rumble effect=],
              return `false`.
            </dd>
            <dt>
              {{GamepadHapticEffectType/"trigger-rumble"}}
            </dt>
            <dd>
              If |params| does not describe a [=valid trigger-rumble effect=],
              return `false`.
            </dd>
          </dl>
        </li>
        <li>Return `true`
        </li>
      </ol>
      <p>
        To <dfn>issue a haptic effect</dfn> on an actuator, the [=user agent=]
        MUST send a command to the device to render an effect of
        |type:GamepadHapticEffectType| and try to make it use the provided
        |params:GamepadEffectParameters|. The [=user agent=] SHOULD use the
        provided |playEffectTimestamp:DOMHighResTimestamp| for more precise
        playback timing when |params|.{{GamepadEffectParameters/startDelay}} is
        not `0.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.
      </p>
      <p>
        To <dfn>stop haptic effects</dfn> on an actuator, the [=user agent=]
        MUST send a command to the device to abort any effects currently being
        played. If a haptic effect was interrupted, the actuator SHOULD return
        to a motionless state as quickly as possible.
      </p>
      <section>
        <h3>
          Handling visibility change
        </h3>
        <p>
          When the |document|'s [=Document/visibility state=] becomes
          `"hidden"`, run these steps for each {{GamepadHapticActuator}}
          |actuator:GamepadHapticActuator|:
        </p>
        <ol>
          <li>If |actuator|.{{GamepadHapticActuator/[[playingEffectPromise]]}}
          is `null`, abort these steps.
          </li>
          <li>[=Queue a global task=] on the [=relevant global object=] of
          |actuator| using the [=gamepad task source=] to run the following
          steps:
            <ol>
              <li>If
              |actuator|.{{GamepadHapticActuator/[[playingEffectPromise]]}} is
              `null`, abort these steps.
              </li>
              <li>[=Resolve=]
              |actuator|.{{GamepadHapticActuator/[[playingEffectPromise]]}}
              with {{GamepadHapticsResult/"preempted"}}.
              </li>
              <li>Set
              |actuator|.{{GamepadHapticActuator/[[playingEffectPromise]]}} to
              `null`.
              </li>
            </ol>
          </li>
          <li>[=Stop haptic effects=] on |actuator|.
          </li>
        </ol>
      </section>
      <section>
        <h3>
          Constructing a `GamepadHapticActuator`
        </h3>
        <p>
          <dfn data-lt="constructing a GamepadHapticActuator">A new
          |gamepadHapticActuator:GamepadHapticActuator|</dfn> representing a
          {{Gamepad}}'s primary vibration actuator is constructed by performing
          the following steps:
        </p>
        <ol>
          <li>Let |gamepadHapticActuator:GamepadHapticActuator| be a newly
          created {{GamepadHapticActuator}} instance.
          </li>
          <li>Let `supportedEffectsList` be an empty list.
          </li>
          <li>For each enum value |type:GamepadHapticEffectType| of
          {{GamepadHapticEffectType}}, if the [=user agent=] can send a command
          to initiate effects of that type on that actuator, append |type| to
          `supportedEffectsList`.
          </li>
          <li>Set |gamepadHapticActuator|.{{GamepadHapticActuator/[[effects]]}}
          to `supportedEffectsList`.
          </li>
        </ol>
      </section>
    </section>
    <section>
      <h3>
        <dfn>GamepadHapticsResult</dfn> Enum
      </h3>
      <pre class="idl">
        enum GamepadHapticsResult {
          "complete",
          "preempted"
        };
      </pre>
      <dl data-dfn-for="GamepadHapticsResult">
        <dt>
          <dfn>complete</dfn>
        </dt>
        <dd>
          <p>
            The haptic effected completed playing.
          </p>
        </dd>
        <dt>
          <dfn>preempted</dfn>
        </dt>
        <dd>
          <p>
            The current effect was stopped or replaced (i.e., "preempted") by
            another effect.
          </p>
        </dd>
      </dl>
    </section>
    <section data-dfn-for="GamepadHapticEffectType">
      <h3>
        <dfn>GamepadHapticEffectType</dfn> enum
      </h3>
      <p>
        The effect type defines how the effect parameters are interpreted by
        the actuator.
      </p>
      <pre class="idl">
        enum GamepadHapticEffectType {
          "dual-rumble",
          "trigger-rumble"
        };
      </pre>
      <dl>
        <dt>
          "<dfn>dual-rumble</dfn>" effect type
        </dt>
        <dd>
          <p>
            {{GamepadHapticEffectType/"dual-rumble"}} describes a haptic
            configuration with an eccentric rotating mass (ERM) vibration motor
            in each handle of a standard 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.
          </p>
          <p>
            A {{GamepadHapticEffectType/"dual-rumble"}} effect is a
            fixed-duration, constant-intensity vibration effect intended for an
            actuator of this type. {{GamepadHapticEffectType/"dual-rumble"}}
            effects are defined by {{GamepadEffectParameters/startDelay}},
            {{GamepadEffectParameters/duration}},
            {{GamepadEffectParameters/strongMagnitude}}, and
            {{GamepadEffectParameters/weakMagnitude}}, none of which are
            required because they default to 0.
          </p>
          <p>
            {{GamepadEffectParameters/strongMagnitude}} and
            {{GamepadEffectParameters/weakMagnitude}} set the intensity levels
            for the low-frequency and high-frequency vibrations, normalized to
            the range `[0,1]`, defaulting to 0.
          </p>
          <p>
            Given {{GamepadEffectParameters}} |params:GamepadEffectParameters|,
            a <dfn>valid dual-rumble effect</dfn> must have a [=valid
            effect|valid=] {{GamepadEffectParameters/duration}}, a [=valid
            effect|valid=] {{GamepadEffectParameters/startDelay}}, and both the
            {{GamepadEffectParameters/strongMagnitude}} and the
            {{GamepadEffectParameters/weakMagnitude}} must be in the range
            `[0,1]`.
          </p>
        </dd>
        <dt>
          "<dfn>trigger-rumble</dfn>" effect type
        </dt>
        <dd>
          <p>
            {{GamepadHapticEffectType/"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
            {{GamepadHapticEffectType/"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.
          </p>
          <p>
            A {{GamepadHapticEffectType/"trigger-rumble"}} effect is a
            fixed-duration, constant-intensity vibration effect intended for an
            actuator of this type. {{GamepadHapticEffectType/"trigger-rumble"}}
            effects are defined by {{GamepadEffectParameters/startDelay}},
            {{GamepadEffectParameters/duration}},
            {{GamepadEffectParameters/strongMagnitude}},
            {{GamepadEffectParameters/weakMagnitude}},
            {{GamepadEffectParameters/leftTrigger}}, and
            {{GamepadEffectParameters/rightTrigger}}, none of which are
            required because they default to 0.
          </p>
          <p>
            {{GamepadEffectParameters/startDelay}},
            {{GamepadEffectParameters/duration}},
            {{GamepadEffectParameters/strongMagnitude}},
            {{GamepadEffectParameters/weakMagnitude}} share the same definition
            with {{GamepadHapticEffectType/"dual-rumble"}}.
            {{GamepadEffectParameters/leftTrigger}} and
            {{GamepadEffectParameters/rightTrigger}}, respectively, set the
            intensity levels for the left and right bottom front buttons
            vibrations, normalized to the range `[0,1]`, defaulting to 0.
          </p>
          <p>
            Given {{GamepadEffectParameters}} |params:GamepadEffectParameters|,
            a <dfn>valid trigger-rumble effect</dfn> must have a [=valid
            effect|valid=] {{GamepadEffectParameters/duration}}, a [=valid
            effect|valid=] {{GamepadEffectParameters/startDelay}}, and the
            {{GamepadEffectParameters/strongMagnitude}},
            {{GamepadEffectParameters/weakMagnitude}},
            {{GamepadEffectParameters/leftTrigger}}, and
            {{GamepadEffectParameters/rightTrigger}} must be in the range
            `[0,1]`.
          </p>
        </dd>
      </dl>
    </section>
    <section data-dfn-for="GamepadEffectParameters">
      <h3>
        <dfn>GamepadEffectParameters</dfn> Dictionary
      </h3>
      <p>
        A <code>GamepadEffectParameters</code> dictionary contains keys for
        parameters used by haptic effects. The meaning of each key is defined
        by the haptic effect, and some keys may be unused.
      </p>
      <p>
        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.
      </p>
      <pre class="idl">
        dictionary 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;
        };
      </pre>
      <dl>
        <dt>
          <dfn>duration</dfn> member
        </dt>
        <dd>
          {{GamepadEffectParameters/duration}} sets the duration of the
          vibration effect in milliseconds.
        </dd>
        <dt>
          <dfn>startDelay</dfn> member
        </dt>
        <dd>
          {{GamepadEffectParameters/startDelay}} sets the duration of the delay
          after {{GamepadHapticActuator/playEffect()}} is called until
          vibration is started, in milliseconds. During the delay interval, the
          actuator SHOULD NOT vibrate.
        </dd>
        <dt>
          <dfn>strongMagnitude</dfn> member
        </dt>
        <dd>
          The vibration magnitude for the low frequency rumble in a
          {{GamepadHapticEffectType/"dual-rumble"}} or
          {{GamepadHapticEffectType/"trigger-rumble"}} effect.
        </dd>
        <dt>
          <dfn>weakMagnitude</dfn> member
        </dt>
        <dd>
          The vibration magnitude for the high frequency rumble in a
          {{GamepadHapticEffectType/"dual-rumble"}} or
          {{GamepadHapticEffectType/"trigger-rumble"}} effect.
        </dd>
        <dt>
          <dfn>leftTrigger</dfn> member
        </dt>
        <dd>
          The vibration magnitude for the bottom left front button ([=canonical
          index=] 6) rumble in a {{GamepadHapticEffectType/"trigger-rumble"}}
          effect.
        </dd>
        <dt>
          <dfn>rightTrigger</dfn> member
        </dt>
        <dd>
          The vibration magnitude for the bottom right front button
          ([=canonical index=] 7) rumble in a
          {{GamepadHapticEffectType/"trigger-rumble"}} effect.
        </dd>
      </dl>
    </section>
    <section data-dfn-for="Navigator">
      <h2>
        Extensions to the `Navigator` interface
      </h2>
      <pre class="idl">
        [Exposed=Window]
        partial interface Navigator {
          sequence&lt;Gamepad?&gt; getGamepads();
        };
      </pre>
      <p>
        Instances of {{Navigator}} are created with the internal slots
        described in the following table:
      </p>
      <table class="simple">
        <tr>
          <th>
            Internal slot
          </th>
          <th>
            Initial value
          </th>
          <th>
            Description (non-normative)
          </th>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Navigator">[[\hasGamepadGesture]]</dfn>
          </td>
          <td>
            `false`
          </td>
          <td>
            A flag indicating that a [=gamepad user gesture=] has been observed
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Navigator">[[\gamepads]]</dfn>
          </td>
          <td>
            A empty [=sequence=] of {{Gamepad?}} objects
          </td>
          <td>
            Each {{Gamepad}} present at the index specified by its
            {{Gamepad/index}} attribute, or `null` for unassigned indices.
          </td>
        </tr>
      </table>
      <section>
        <h3>
          <dfn>getGamepads()</dfn> method
        </h3>
        <p class="note">
          The gamepad state returned from {{Navigator/getGamepads()}} does not
          reflect disconnection or connection until after the
          {{gamepaddisconnected}} or {{gamepadconnected}} events have fired.
        </p>
        <p class="note">
          To mitigate fingerprinting, {{Navigator/getGamepads()}} returns an
          empty [=list=] before a [=gamepad user gesture=] has been seen.
          [[FINGERPRINTING-GUIDANCE]]
        </p>
        <aside class="example">
          {{Navigator/getGamepads()}} returns a snapshot of the data for the
          currently connected and interacted-with gamepads. When a gamepad is
          no longer connected, its index in the array should return `null`. If
          there is one connected gamepad with an index of 1, then the following
          code snippet describes the expected behavior:
          <pre class="js">
            // gamepads should look like [null, [object Gamepad]]
            var gamepads = navigator.getGamepads();
            // The following statements should all evaluate to true.
            gamepads[0] == null;
            gamepads[1].index == 1;
            gamepads.length == 2;
          </pre>
        </aside>
        <p>
          The {{Navigator/getGamepads()}} method steps are:
        </p>
        <ol>
          <li>Let |doc:Document?| be the [=current global object=]'s
          [=associated `Document`=].
          </li>
          <li>If |doc| is `null` or |doc| is not [=Document/fully active=],
          then return an empty [=list=].
          </li>
          <li>If |doc| is not [=allowed to use=] the `"gamepad"` permission,
          then [=exception/throw=] a {{"SecurityError"}} {{DOMException}} and
          abort these steps.
          </li>
          <li>If [=this=].{{Navigator/[[hasGamepadGesture]]}} is `false`, then
          return an empty [=list=].
          </li>
          <li>Let |now:DOMHighResTimeStamp| be the [=current high resolution
          time=].
          </li>
          <li>Let |gamepads:sequence&lt;Gamepad?&gt;| be an empty [=list=].
          </li>
          <li>[=list/For each=] |gamepad:Gamepad| of
          [=this=].{{Navigator/[[gamepads]]}}:
            <ol>
              <li>If |gamepad| is not `null` and
              |gamepad|.{{Gamepad/[[exposed]]}} is `false`:
                <ol>
                  <li>Set |gamepad|.{{Gamepad/[[exposed]]}} to `true`.
                  </li>
                  <li>Set |gamepad|.{{Gamepad/[[timestamp]]}} to |now|.
                  </li>
                </ol>
              </li>
              <li>[=list/Append=] |gamepad| to |gamepads|.
              </li>
            </ol>
          </li>
          <li>Return |gamepads|.
          </li>
        </ol>
        <p>
          A |gamepad:Gamepad| <dfn data-lt="gamepad user gesture">contains a
          gamepad user gesture</dfn> if the current input state indicates that
          the user is currently interacting with the gamepad. The [=user
          agent=] MUST provide an algorithm to check if the input state
          contains a gamepad user gesture. For buttons that support a neutral
          default value and have reported a {{GamepadButton/pressed}} value of
          `false` at least once, a {{GamepadButton/pressed}} value of `true`
          SHOULD be considered interaction. If a button does not support a
          neutral default value (for example, a toggle switch), then a
          {{GamepadButton/pressed}} value of `true` SHOULD NOT be considered
          interaction. If a button has never reported a
          {{GamepadButton/pressed}} value of `false` then it SHOULD NOT be
          considered interaction. Axis movements SHOULD be considered
          interaction if the axis supports a neutral default value, the current
          displacement from neutral is greater than a threshold chosen by the
          [=user agent=], and the axis has reported a value below the threshold
          at least once. If an axis does not support a neutral default value
          (for example, an axis for a joystick that does not self-center), or
          an axis has never reported a value below the axis gesture threshold,
          then the axis SHOULD NOT be considered when checking for interaction.
          The axis gesture threshold SHOULD be large enough that random jitter
          is not considered interaction.
        </p>
      </section>
    </section>
    <section data-dfn-for="GamepadEvent">
      <h2>
        <dfn>GamepadEvent</dfn> Interface
      </h2>
      <pre class="idl" data-cite="DOM">
        [Exposed=Window]

        interface GamepadEvent: Event {
          constructor(DOMString type, GamepadEventInit eventInitDict);
          [SameObject] readonly attribute Gamepad gamepad;
        };
      </pre>
      <dl>
        <dt>
          <dfn>gamepad</dfn>
        </dt>
        <dd>
          The {{GamepadEvent/gamepad}} attribute provides access to the
          associated gamepad data for this event.
        </dd>
      </dl>
      <section>
        <h3>
          <dfn>GamepadEventInit</dfn> dictionary
        </h3>
        <pre class="idl" data-cite="DOM">
        dictionary GamepadEventInit : EventInit {
          required Gamepad gamepad;
        };
      </pre>
        <dl data-dfn-for="GamepadEventInit">
          <dt>
            <dfn>gamepad</dfn> member
          </dt>
          <dd>
            The {{Gamepad}} associated with this event.
          </dd>
        </dl>
      </section>
    </section>
    <section>
      <h2>
        Remapping
      </h2>
      <p>
        Each device manufacturer creates many different products and each has
        unique styles and layouts of buttons and axes. It is intended that the
        [=user agent=] support as many of these as possible.
      </p>
      <p>
        Additionally there are <em>de facto</em> 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.
      </p>
      <p data-link-for="Gamepad">
        There is currently one canonical layout, the <dfn>Standard
        Gamepad</dfn>. When remapping, the indices in {{Gamepad/axes}} and
        {{Gamepad/buttons}} should correspond as closely as possible to the
        physical locations in the diagram below. Additionally,
        {{Gamepad/mapping}} SHOULD be set to {{GamepadMappingType/"standard"}}.
      </p>
      <p>
        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 axes 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 buttons/axes and their physical
        locations.
      </p>
      <p>
        An axis input <dfn>represents a Standard Gamepad axis</dfn> if it
        reports the input value 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 axes 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.
      </p>
      <p>
        A button input <dfn>represents a Standard Gamepad button</dfn> if it
        reports the input value for a button or trigger, and the button or
        trigger is located in approximately the same location as the
        corresponding [=Standard Gamepad=] button.
      </p>
      <p>
        If an axis or button input represents a [=Standard Gamepad=] axis or
        button, then its <dfn data-lt="canonical indices">canonical index</dfn>
        is the index of the corresponding [=Standard Gamepad=] axis or button.
      </p>
      <table class="simple">
        <thead>
          <tr>
            <th>
              Type
            </th>
            <th>
              Index
            </th>
            <th>
              Location
            </th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td rowspan="17">
              Button
            </td>
            <td>
              0
            </td>
            <td>
              Bottom button in right cluster
            </td>
          </tr>
          <tr>
            <td>
              1
            </td>
            <td>
              Right button in right cluster
            </td>
          </tr>
          <tr>
            <td>
              2
            </td>
            <td>
              Left button in right cluster
            </td>
          </tr>
          <tr>
            <td>
              3
            </td>
            <td>
              Top button in right cluster
            </td>
          </tr>
          <tr>
            <td>
              4
            </td>
            <td>
              Top left front button
            </td>
          </tr>
          <tr>
            <td>
              5
            </td>
            <td>
              Top right front button
            </td>
          </tr>
          <tr>
            <td>
              6
            </td>
            <td>
              Bottom left front button
            </td>
          </tr>
          <tr>
            <td>
              7
            </td>
            <td>
              Bottom right front button
            </td>
          </tr>
          <tr>
            <td>
              8
            </td>
            <td>
              Left button in center cluster
            </td>
          </tr>
          <tr>
            <td>
              9
            </td>
            <td>
              Right button in center cluster
            </td>
          </tr>
          <tr>
            <td>
              10
            </td>
            <td>
              Left stick pressed button
            </td>
          </tr>
          <tr>
            <td>
              11
            </td>
            <td>
              Right stick pressed button
            </td>
          </tr>
          <tr>
            <td>
              12
            </td>
            <td>
              Top button in left cluster
            </td>
          </tr>
          <tr>
            <td>
              13
            </td>
            <td>
              Bottom button in left cluster
            </td>
          </tr>
          <tr>
            <td>
              14
            </td>
            <td>
              Left button in left cluster
            </td>
          </tr>
          <tr>
            <td>
              15
            </td>
            <td>
              Right button in left cluster
            </td>
          </tr>
          <tr>
            <td>
              16
            </td>
            <td>
              Center button in center cluster
            </td>
          </tr>
          <tr>
            <td rowspan="4">
              axes
            </td>
            <td>
              0
            </td>
            <td>
              Horizontal axis for left stick (negative left/positive right)
            </td>
          </tr>
          <tr>
            <td>
              1
            </td>
            <td>
              Vertical axis for left stick (negative up/positive down)
            </td>
          </tr>
          <tr>
            <td>
              2
            </td>
            <td>
              Horizontal axis for right stick (negative left/positive right)
            </td>
          </tr>
          <tr>
            <td>
              3
            </td>
            <td>
              Vertical axis for right stick (negative up/positive down)
            </td>
          </tr>
        </tbody>
      </table>
      <figure>
        <img src="standard_gamepad.svg" alt="">
        <figcaption>
          Visual representation of a [=Standard Gamepad=] layout.
        </figcaption>
      </figure>
      <section>
        <h3>
          Fingerprinting mitigation
        </h3>
        <p>
          Inspecting the capabilities of {{Gamepad}} objects can be used as a
          means of active fingerprinting. The [=user agent=] MAY alter the
          device information exposed through the API to reduce the
          fingerprinting surface. As an example, an implementation can require
          that a {{Gamepad}} object have exactly the number of buttons and axes
          defined in the [=Standard Gamepad=] layout even if more or fewer
          inputs are present on the connected device.
          [[FINGERPRINTING-GUIDANCE]]
        </p>
      </section>
    </section>
    <section class="informative">
      <h2>
        Usage Examples
      </h2>
      <p>
        The example below demonstrates typical access to gamepads. Note the
        relationship with the
        {{AnimationFrameProvider/requestAnimationFrame()}} method.
      </p>
      <pre class="example js">
        function runAnimation() {
            window.requestAnimationFrame(runAnimation);
            for (const pad of navigator.getGamepads()) {
              // todo; simple demo of displaying pad.axes and pad.buttons
              console.log(pad);
            }
        }

        window.requestAnimationFrame(runAnimation);
      </pre>
      <div class="practice">
        <span id="practice-timing" class="practicelab">Coordination with
        <code>requestAnimationFrame()</code></span>
        <p class="practicedesc">
          Interactive applications will typically be using the
          {{AnimationFrameProvider/requestAnimationFrame()}} method to drive
          animation, and will want coordinate animation with user gamepad
          input. As such, the gamepad data should be polled as closely as
          possible to immediately before the animation callbacks are executed,
          and with frequency matching that of the animation. That is, if the
          animation callbacks are running at 60Hz, the gamepad inputs should
          also be sampled at that rate.
        </p>
      </div>
    </section>
    <section>
      <h3 id="event-gamepadconnected">
        The <dfn class="event">gamepadconnected</dfn> event
      </h3>
      <p>
        When a gamepad becomes available on the system, run the following
        steps:
      </p>
      <ol>
        <li>Let |document:Document?| be the [=current global object=]'s
        [=associated `Document`=]; otherwise `null`.
        </li>
        <li>If |document| is not `null` and is not [=allowed to use=] the
        `"gamepad"` permission, then abort these steps.
        </li>
        <li>[=Queue a task=] on the [=gamepad task source=] to perform the
        following steps:
          <ol>
            <li>Let |gamepad:Gamepad| be [=a new `Gamepad`=] representing the
            gamepad.
            </li>
            <li>Let |navigator:Navigator| be |gamepad|'s [=relevant global
            object=]'s {{Navigator}} object.
            </li>
            <li>Set
            |navigator|.{{Navigator/[[gamepads]]}}[|gamepad|.{{Gamepad/index}}]
            to |gamepad|.
            </li>
            <li>If |navigator|.{{Navigator/[[hasGamepadGesture]]}} is `true`:
              <ol>
                <li>Set |gamepad|.{{Gamepad/[[exposed]]}} to `true`.
                </li>
                <li>If |document| is not `null` and is [=Document/fully
                active=], then [=fire an event=] named {{gamepadconnected}} at
                |gamepad|'s [=relevant global object=] using {{GamepadEvent}}
                with its {{GamepadEvent/gamepad}} attribute initialized to
                |gamepad|.
                </li>
              </ol>
            </li>
          </ol>
        </li>
      </ol>
      <p>
        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.
      </p>
      <p>
        A [=user agent=] MUST dispatch this event type to indicate the user has
        connected a gamepad. If a gamepad was already connected when the page
        was loaded, the {{gamepadconnected}} event SHOULD be dispatched when
        the user presses a button or moves an axis.
      </p>
    </section>
    <section>
      <h3 id="event-gamepaddisconnected">
        The <dfn class="event">gamepaddisconnected</dfn> event
      </h3>
      <p>
        When a gamepad becomes unavailable on the system, run the following
        steps:
      </p>
      <ol>
        <li>Let |gamepad:Gamepad| be the {{Gamepad}} representing the
        unavailable device.
        </li>
        <li>[=Queue a task=] on the [=gamepad task source=] to perform the
        following steps:
          <ol>
            <li>Set |gamepad|.{{Gamepad/[[connected]]}} to `false`.
            </li>
            <li>Let |document:Document?| be |gamepad|'s [=relevant global
            object=]'s [=associated `Document`=]; otherwise `null`.
            </li>
            <li>If |gamepad|.{{Gamepad/[[exposed]]}} is `true` and |document|
            is not `null` and is [=Document/fully active=], then [=fire an
            event=] named {{gamepaddisconnected}} at |gamepad|'s [=relevant
            global object=] using {{GamepadEvent}} with its
            {{GamepadEvent/gamepad}} attribute initialized to |gamepad|.
            </li>
            <li>Let |navigator:Navigator| be |gamepad|'s [=relevant global
            object=]'s {{Navigator}} object.
            </li>
            <li>Set
            |navigator|.{{Navigator/[[gamepads]]}}[|gamepad|.{{Gamepad/index}}]
            to `null`.
            </li>
            <li>While |navigator|.{{Navigator/[[gamepads]]}} [=list/is not
            empty=] and the last [=list/item=] of
            |navigator|.{{Navigator/[[gamepads]]}} is `null`, [=list/remove=]
            the last [=list/item=] of |navigator|.{{Navigator/[[gamepads]]}}.
            </li>
          </ol>
        </li>
      </ol>
      <p>
        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.
      </p>
      <p>
        When a gamepad is disconnected from the [=user agent=], 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}}.
      </p>
    </section>
    <section>
      <h3>
        Other events
      </h3>
      <p>
        <i>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.</i>
      </p>
    </section>
    <section>
      <h2>
        Extensions to the `WindowEventHandlers` Interface Mixin
      </h2>
      <p>
        This specification extends the {{WindowEventHandlers}} interface mixin
        from HTML to add [=event handler IDL attributes=] to facilitate the
        event handler registration.
      </p>
      <pre class="idl">
        partial interface mixin WindowEventHandlers {
          attribute EventHandler ongamepadconnected;
          attribute EventHandler ongamepaddisconnected;
        };
      </pre>
    </section>
    <section id="permission-policy" data-cite="permissions-policy">
      <h2>
        Integration with Permissions Policy
      </h2>
      <p>
        This specification defines a policy-controlled feature identified by
        the string <dfn class="permission">"gamepad"</dfn>. Its
        [=policy-controlled feature/default allowlist=] is [=default
        allowlist/*=].
      </p>
      <div class="note">
        <p>
          A [=document=]’s [=Document/permissions policy=] determines whether
          any content in that document is allowed to access
          {{Navigator/getGamepads()}}. If disabled in any document, no content
          in the document will be [=allowed to use=]
          {{Navigator/getGamepads()}}, nor will the {{gamepadconnected}} and
          {{gamepaddisconnected}} events fire.
        </p>
      </div>
    </section>
    <section id='conformance'>
      <!-- This section is filled automatically by ReSpec. -->
    </section>
    <section class='appendix informative'>
      <h2>
        Acknowledgements
      </h2>
      <p>
        The following people contributed to the development of this document.
      </p>
      <ul id="gh-contributors" style="columns: 3;">
        <li>David Humphrey
        </li>
        <li>Gregg Tavares
        </li>
        <li>Marcin Wichary
        </li>
        <li>Jason Orendorff
        </li>
        <li>Olli Pettay
        </li>
        <li>Rick Waldron
        </li>
      </ul>
    </section>
  </body>
</html>