@toji what is the status of this issue? It's come up in Intent to Ship: WebXR Gamepad Module on blink-dev.

If this isn't interoperable as this issue suggests it isn't, then resolving it in the spec seems fairly high priority.

FWIW, given the "The same object MUST be returned until the user agent needs to return different values (or values in a different order)" wording for axes and buttons, it seems like it was at one point the intention for a Gamepad object to be live in the sense that its attributes can start returning new values, and this does make sense to me. Gamepad objects do have an id, but to have to call navigator.getGamepads() for every animation frame seems odd given the naming of the API.

To clarify, I'm no longer an editor on this spec.

Speaking from the perspective of an editor within the Immersive Web Working Group, however, I understand the concern that our use of gamepad differs from how this spec text implies they should be used. It is worth noting that every Gamepad implementation I'm familiar with does update the gamepad objects in-place upon calling getGamepads(), which seems to contradict the spec text. I'm skeptical that the UA implementations will change to match the spec text any time soon, given that I believe it's already been previously identified by Microsoft as a content compatibility issue. As such, I would rather that WebXR be consistent with the observed behavior of gamepads rather than the single sentence in the Gamepad spec that states they should behave otherwise.

That said, I also don't think the spec and implementations should disagree. It would be best if either the spec updated to reflect the currently observed behavior accurately or we get agreement from all UAs that they will update getGamepads() to return actual snapshots. If this group takes the latter route then WebXR would be willing to change to match, especially given that backwards compatibility will already be broken at that point. In the meantime, since it's not clear which direction the Gamepad group wants to go, WebXR will continue with (and ship) a live attribute.

There's a couple issues here, right? Does getGamepads() return new objects or the same objects. What's the lifetime of those objects if they're the same (agent lifetime I guess). And if they are the same, when is their state updated and is that allowed to violate run-to-completion semantics? (Ideally not.)

Related: immersive-web/webxr-gamepads-module#18

There's some relevant discussion in Intent to Ship: WebXR Gamepad Module on blink-dev.

It sounds like because the number of buttons don't change, the buttons could keep returning the same array every time, and could be decorated with [SameObject]. The GamepadButton objects are what would change, at some well defined time. Maybe that's at every microtask checkpoint, top of the event loop or rendering frame, as long as it doesn't change while script is running anything is probably web compatible.

If axes needs to change it would however need to return a new array, so that can't be given the [SameObject] extended attribute.

As long as each get does not return a new array that is fine (same principle as the other getters). My main concern here is not so much compatibility by the way, but violating run-to-completion semantics.

From what I can tell this can be made sensible in terms of not changing state while script is running and FrozenArray<T> can be used.

I think any remaining warts after this might be with navigator.getGamepads() itself. It currently returns an array of fixed length where all entries can be null, presumably because originally the index was to be kept stable when the Gamepad instance might be replaced. If a Gamepad object is connected to the underlying gamepad and updated at well defined times, it seems to me that navigator.getGamepads() could just return an empty array if there are no gamepads. But there's some chance that's not web compatible.

@nondebug (Matt Reynolds) can you describe roughly the changes you'd like to make here?

Sure, please take a look:

getGamepads() should return an array of Gamepad objects. The gamepad array is NOT a live array; the returned array will always hold the same Gamepad objects even if gamepads are connected and disconnected. The same gamepad array may be returned if no gamepads have been connected or disconnected. (But it's also fine to construct a new array for each call.)

Each non-null item in the array returned by getGamepads() corresponds to a single connected gamepad. As long as the gamepad remains connected, getGamepads() should return the same Gamepad object for that gamepad, at the same array index.

Gamepad objects are live. The id and index members should not be modified once the object is returned to script, but other members may be updated due to user interaction with the gamepad. (Should mapping or hand be allowed to change? This might be useful for devices that can be operated in multiple modes without a disconnection, eg Switch Joy-Cons.)

The connected member should return true as long as the gamepad remains connected, and false afterward.

The axes member is NOT a live array; it should hold the same array until any axis changes or the order of axes changes, after which it should return a new array with the updated axis state. (Should we continue to return the same array after disconnection?)

The buttons member is NOT a live array; it should hold the same array of GamepadButton objects as long as the gamepad remains connected and the order of buttons does not change. If the order of buttons changes, a new array should be returned. Each item in the array should hold the same GamepadButton object for the lifetime of the buttons array. (Should we continue to return the same array after disconnection?)

GamepadButton is live and its properties (value, pressed, touched) may change after the button has been returned to script.

The timestamp member should be updated whenever connected, axes, or buttons (also pose) is updated with new values. If there is no observable state change, the timestamp should not change. (This differs from the current spec language which describes the timestamp as "Last time the data for this gamepad was updated" which could include updates where the data received from the device matches the previous state. IMO this is not useful, API users should assume the browser is receiving updates continuously until the gamepad is disconnected.)

Live objects (Gamepad, GamepadButton) are updated when script is not running. If a change occurs while script is running, they will continue to hold the same values until the top of the event loop.

(But it's also fine to construct a new array for each call.)

That's not great, either store the JavaScript array object on the object and replace it when needed, or always create a new array based on the internal data.

should return

Must, right? (Same for other shoulds.)

other members may be updated due to user interaction with the gamepad

This will have to be defined as updating internal state on the Gamepad objects at a specific point in time to avoid violating run-to-completion semantics. (You're saying as much at the end, but I hope the eventual definition of this will fall out of the processing model.)

If both Firefox and Chrome's implementations do not match the spec text then I think the spec text should be changed to match the implementations. Someone should test Safari and Edge as well. I was under the impression that the Chrome implementation was snapshots, but perhaps that changed over time?

Regardless, last I knew the Firefox implementation actually implemented updates to Gamepad objects by doing the internal equivalent of queuing microtasks to update the state, so using some spec language like "Updates to Gamepad objects should be queued as microtasks in the current event loop" should both be sensible and not contradict the Firefox implementation. Note that there have been requests to add support for the Gamepad API to Web Workers so ideally the spec text could be written to not make it more difficult to add that in the future.

There are some existing manual web platform tests, it should be possible to write new tests for this behavior.

@nondebug thanks, that look great! On the various "new array" questions, this is my best understanding:

• navigator.getGamepads() has to return a new each time, because the return value is sequence<T>. It was discussed earlier in the issue but I think this should be uncontroversial now.
• axes should return the same frozen array for every call until its values need to change, at which point it starts returning another frozen array.
• buttons is actually the same, that the values are objects and not numbers doesn't change much in terms of when a new array is returned.

For when updates happen, I think there are three choices:

• The spec defines exactly where in the rendering loop it happens, i.e., it would only happen between animation frames. I don't think this is what anyone wants though, because the gamepads aren't actually synchronized with the rendering at the hardware level.
• Allow updates to happen at the top of the event loop.
• Allow updates to happen at any microtask checkpoint.

Between the last two, I think "top of the event loop" is probably fine? But just matching what is or will be implemented is more important than what I think :)

FWIW in immersive-web/webxr-gamepads-module#18 (PR at immersive-web/webxr-gamepads-module#22 ) WebXR seems to be settling on making them live, but updated every XR frame. We already have a reliable frame tick which we can piggyback on for this (so we don't need to create new tasks).

That's not great, either store the JavaScript array object on the object and replace it when needed, or always create a new array based on the internal data

navigator.getGamepads() has to return a new each time, because the return value is sequence<T>.

If Gamepad is a live object then the array returned by getGamepads() should only need to change when gamepads are added or removed from the list.

Must, right? (Same for other shoulds.)

Yes, apologies, I'm new to spec language.

This will have to be defined as updating internal state on the Gamepad objects at a specific point in time to avoid violating run-to-completion semantics. (You're saying as much at the end, but I hope the eventual definition of this will fall out of the processing model.)

Regardless, last I knew the Firefox implementation actually implemented updates to Gamepad objects by doing the internal equivalent of queuing microtasks to update the state, so using some spec language like "Updates to Gamepad objects should be queued as microtasks in the current event loop" should both be sensible and not contradict the Firefox implementation.

For when updates happen, I think there are three choices:

Let's go with "updates should be queued as microtasks in the current event loop" to match the Firefox implementation.

Note that there have been requests to add support for the Gamepad API to Web Workers so ideally the spec text could be written to not make it more difficult to add that in the future.

@luser, can you elaborate on this? (Is there an issue with tying the update to microtasks or the event queue in a Web Worker?)

If Gamepad is a live object then the array returned by getGamepads() should only need to change when gamepads are added or removed from the list.

The objects in the arrays may be the same, but each time getGamepads() is called it has to return a new array. This is how sequence<T> conversion is defined, see "Let A be a new Array" at step 2 of "An IDL sequence value S of type sequence is converted to an ECMAScript Array object as follows" in https://heycam.github.io/webidl/#es-sequence.

@luser, can you elaborate on this? (Is there an issue with tying the update to microtasks or the event queue in a Web Worker?)

I just wanted to call that out to make sure that we don't wind up with spec text that ties the update rate to requestAnimationFrame or anything like that which would make it harder to make things work in a Web Worker in the future. I think your proposed text should be fine!