- This interface defines an individual gamepad device. + This interface represents an individual gamepad device. A Gamepad is a + live object; that is, user interaction with the device is periodically reflected + in the state of the object's properties. When the system receives new + data from a connected gamepad, a microtask MUST be queued with the user + interaction task source to update the state of the {{Gamepad}} object.
[Exposed=Window]
@@ -236,28 +240,70 @@
index attribute
- 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.
+
+ Zero-based index of the gamepad in the {{Navigator}}. The index
+ MUST NOT change once the Gamepad object has been returned to script.
+
+
+ When the system is notified that a gamepad has been connected,
+ its index attribute MUST be assigned to the lowest index that is not
+ assigned to any currently connected gamepad, starting at zero.
+
+
+ When the system is notified that a previously connected gamepad has
+ become unavailable, the `index` attribute of other gamepads MUST NOT
+ be reassigned. However, if a gamepad is disconnected, and
+ subsequently the same or a different gamepad is connected, the
+ lowest previously used index MUST be assigned to the newly connected
+ gamepad.
+
+
+
+ // Consider three gamepads padA, padB, and padC.
+ // Initially, padA and padB are connected with indices 0 and 1.
+ // padC is not connected.
+ var gamepads = navigator.getGamepads();
+ // The following statements should all evaluate to true.
+ gamepads.length == 2;
+ gamepads[0].index == 0; // padA
+ gamepads[1].index == 1; // padB
+ // padA is disconnected.
+ gamepads.length == 2;
+ gamepads[0] == null;
+ gamepads[1].index == 1; // padB
+ // padC is connected and takes the lowest unassigned index (0).
+ gamepads.length == 2;
+ gamepads[0].index == 0; // padC
+ gamepads[1].index == 1; // padB
+ // padA is reconnected and takes the lowest unassigned index (2).
+ gamepads.length == 3;
+ gamepads[0].index == 0; // padC
+ gamepads[1].index == 1; // padB
+ gamepads[2].index == 2; // padA
+
connected attribute
+
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 `connected` attribute MUST be set to false.
+ still connected to the system.
+
+
+ When the system is notified that a previously-connected gamepad has
+ become unavailable, whether by being physically disconnected,
+ powered off, or otherwise unusable, a microtask MUST be queued with
+ the user interaction task source to set the `connected` attribute to
+ false.
+
timestamp attribute
- Last time the data for this gamepad was updated. Timestamp is a
+
+ Last time the data for this gamepad was updated. The `timestamp` is a
monotonically increasing value that allows the author to determine if
the axes and button data have been updated from the
hardware. The value must be relative to the
@@ -265,10 +311,21 @@
PerformanceTiming interface. Since values are monotonically
increasing they can be compared to determine the ordering of updates,
as newer values will always be greater than or equal to older values.
+
+
If no data has been received from the hardware, the value of the
- timestamp attribute should be the time relative to
+ `timestamp` attribute MUST be the time relative to
navigationStart when the Gamepad object was first
made available to script.
+
+
+ When the system receives new data from a connected gamepad, a
+ microtask MUST be queued with the user interaction task source to
+ update the gamepad state. If the updated data would cause an
+ observable change to the `buttons` or `axes` attributes, then the
+ timestamp MUST be set to the time that the data was received from
+ hardware, not the time when the microtask was executed.
+
mapping attribute
@@ -287,6 +344,7 @@
axes attribute
+
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,
@@ -295,20 +353,45 @@
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).
+ axis of a directional stick.
+
+
+ When the system receives new data from a connected gamepad, a
+ microtask MUST be queued with the user interaction task source to
+ update the gamepad state. If the gamepad has the same axes in the same
+ order as the previous update, and if no axis values have changed
+ since the previous update, then the axes attribute MUST return the
+ same array object. If the number of axes has changed, or if any axis
+ value has changed, then the axis attribute MUST return a new array.
+
+
+ Once the system is notified that a previously connected gamepad has
+ been disconnected, the {{Gamepad/axes}} attribute MUST continue to return the
+ last state received from the gamepad before disconnection.
+
buttons attribute
- 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).
+
+ Array of {{GamepadButton}} objects representing the current state of
+ 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.
+
+
+ When the system receives new data from a connected gamepad, a
+ microtask MUST be queued with the user interaction task source to
+ update the gamepad state. If the gamepad has the same buttons in the
+ same order as the previous update, the buttons attribute MUST return
+ the same array object. If the number of buttons or the ordering of
+ buttons has changed, the buttons attribute MUST return a new array
+ object. If a button in the new array represents the same physical
+ button as a button from the previous array, the same {{GamepadButton}}
+ object MUST be reused.
+
@@ -317,8 +400,19 @@
GamepadButton Interface
- This interface defines the state of an individual button on a gamepad
- device.
+ This interface represents the current state of an individual button on a gamepad
+ device. A {{GamepadButton}} is a live object; that is, user interaction with
+ the button represented by the object is periodically reflected in the object's
+ properties. When the system receives new data from a connected gamepad,
+ a microtask MUST be queued with the user interaction task source to
+ update the state of the GamepadButton objects representing the buttons
+ on the gamepad.
+
+
+ Once the system is notified that a previously-connected gamepad has been
+ disconnected, the GamepadButton objects representing its buttons MUST
+ continue to return the last state received from the gamepad before
+ disconnection.
[Exposed=Window]
@@ -408,7 +502,7 @@
[Exposed=Window]
partial interface Navigator {
- sequence<Gamepad?> getGamepads();
+ [NewObject] sequence<Gamepad?> getGamepads();
};
@@ -416,7 +510,7 @@
getGamepads
-
- Retrieve a snapshot of the data for the the currently connected and
+ Retrieve a sequence of {{Gamepad}} objects representing currently connected and
interacted-with gamepads. Gamepads MUST only appear in the list if
they are currently connected to the user agent, and at least
one device has been interacted with by the user. If no devices have
@@ -428,7 +522,7 @@
each Gamepad present at the index in the array specified by its
{{Gamepad/index}} attribute. Array indices for which there is no
connected Gamepad with the corresponding index should return null.
-
+
The gamepad state returned from getGamepads() does not reflect
disconnection or connection until after the gamepaddisconnected
@@ -752,10 +846,14 @@
DOM Events. [[DOM]]
+ When the system is notified that a gamepad has been connected, a
+ microtask MUST be queued with the user interaction task source to fire a
+ gamepadconnected event.
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.
+ when the user presses a button or moves an axis on any connected
+ gamepad.
@@ -771,10 +869,11 @@
of DOM Events. [[DOM]]
- 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.
+ If a gamepadconnected event was previously dispatched for a
+ particular gamepad and the system is notified that the gamepad has
+ become unavailable, a microtask MUST be queued with the user interaction
+ task source to dispatch a gamepaddisconnected event to the same
+ window.