- Navigator Interface extension + Extensions to the `Navigator` interface
-- This partial interface defines an extension to the Navigator interface. -
[Exposed=Window]
partial interface Navigator {
sequence<Gamepad?> getGamepads();
};
- -
-
- - getGamepads() - -
-
-
- The gamepad state returned from {{Navigator/getGamepads()}} does - not reflect disconnection or connection until after the - gamepaddisconnected or gamepadconnected events have - fired. -
-- If the current settings object's [=environment settings - object / responsible document=] is not allowed to use the - "`gamepad`" permission, then [=exception/throw=] a - {{"SecurityError"}} {{DOMException}}. -
-
- -
- Retrieve a snapshot of the data for the the 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
- been interacted with, devices MUST NOT appear in the list to avoid a
- malicious page from fingerprinting the user. The length of the array
- returned MUST be one more than the maximum index value of the Gamepad
- objects returned in the array. The entries in the array MUST be the
- set of Gamepad objects that are visible to the current page, with
- 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 or gamepadconnected events have - fired. -
-- As an example, if there is one connected gamepad with an index of - 1, then the following code snippet describes the expected behavior: -
-+
+ Instances of {{Navigator}} are created with the internal slots + described in the following table: +
++
++ ++ Internal slot + ++ Initial value + ++ Description (non-normative) + ++ ++ [[\hasGamepadGesture]] + ++ `false` + ++ A flag indicating that a [=gamepad user gesture=] has been observed + ++ ++ [[\gamepads]] + ++ `[]` + ++ A `sequence<Gamepad?>` with each {{Gamepad}} present at the + index specified by its {{Gamepad/index}} attribute, or `null` for + unassigned indices. + ++ + getGamepads() method +
++ The gamepad state returned from {{Navigator/getGamepads()}} does not + reflect disconnection or connection until after the + {{gamepaddisconnected}} or {{gamepadconnected}} events have fired. +
++ To mitigate fingerprinting, {{Navigator/getGamepads()}} returns an + empty [=list=] before a [=gamepad user gesture=] has been seen. + [[FINGERPRINTING-GUIDANCE]] +
+
-
+ The {{Navigator/getGamepads()}} method steps are: +
+-
+
- If the [=current settings object=]'s [=environment settings + object / responsible document=] is not [=allowed to use=] the + `"gamepad"` permission, then [=exception/throw=] a + {{"SecurityError"}} {{DOMException}} and abort these steps. + +
- If [=this=].{{Navigator/[[hasGamepadGesture]]}} is `false`, then + return an empty [=list=]. + +
- Let |now:DOMHighResTimeStamp| be the [=current high resolution + time=]. + +
- [=list/For each=] |gamepad:Gamepad| of
+ [=this=].{{Navigator/[[gamepads]]}}:
+
-
+
- If |gamepad| is not `null` and
+ |gamepad|.{{Gamepad/[[exposed]]}} is `false`:
+
-
+
- Set |gamepad|.{{Gamepad/[[exposed]]}} to `true`. + +
- Set |gamepad|.{{Gamepad/[[timestamp]]}} to |now|. + +
+
+ - If |gamepad| is not `null` and
+ |gamepad|.{{Gamepad/[[exposed]]}} is `false`:
+
- Return |gamepads|. + +
+ A |gamepad:Gamepad| contains a + gamepad user gesture 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. +
+
@@ -438,8 +1181,8 @@
gamepad
- The single gamepad attribute provides access to the associated
- gamepad data for this event.
+ The {{GamepadEvent/gamepad}} attribute provides access to the
+ associated gamepad data for this event.
@@ -456,43 +1199,64 @@
gamepad member
- The gamepad associated with this event.
+ The {{Gamepad}} associated with this event.
gamepad member
- The gamepad associated with this event.
+ The {{Gamepad}} associated with this event.
- Remapping + Remapping
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. + [=user agent=] support as many of these as possible.
Additionally there are de facto 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 + 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.
- There is currently one canonical device, the "Standard Gamepad". The - standard gamepad has 4 axes, and up to 17 buttons. When remapping, the - indices in axes[] and buttons[] should correspond as - closely as possible to the physical locations in the diagram below. - Additionally, the mapping property of the Gamepad SHOULD be set - to the string {{GamepadMappingType["standard"]}}. -
-- The "Standard Gamepad" physical button locations are layed 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. + There is currently one canonical layout, the Standard + Gamepad. 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"}}. +
++ 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. +
++ An axis input represents a Standard Gamepad axis 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. +
++ A button input represents a Standard Gamepad button 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. +
++ If an axis or button input represents a [=Standard Gamepad=] axis or + button, then its canonical index is the index of the + corresponding [=Standard Gamepad=] axis or button.
