Skip to content

Spec gamepad input events #234

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gabrielsanbrito wants to merge 4 commits into
base: gh-pages
Choose a base branch
from
Open

Spec gamepad input events #234

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e8f355a
First changes
gabrielsanbrito Sep 16, 2026
f9eb63d
Tidying up
gabrielsanbrito Sep 16, 2026
a766729
Addressing feedback
gabrielsanbrito Sep 26, 2026
4ddacb4
Addressing feedback
gabrielsanbrito Oct 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
184 changes: 162 additions & 22 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -787,9 +787,25 @@ <h3>
following steps:
</p>
<ol>
<li>Let |navigator:Navigator| be |gamepad|'s [=relevant global
object=]'s {{Navigator}} object.
</li>
<li>Let |document:Document?| be |gamepad|'s [=relevant global
object=]'s [=associated `Document`=]; otherwise `null`.
</li>
<li>If |document| is `null` or not [=Document/fully active=], abort
these steps.
</li>
<li>If |document| is not [=allowed to use=] the [=policy-controlled
feature=] named "gamepad", then abort these steps.
</li>
Comment thread
gabrielsanbrito marked this conversation as resolved.
<li>Let |now:DOMHighResTimeStamp| be the [=current high resolution
time=] given |gamepad|'s [=relevant global object=].
</li>
<li>Let |oldGamepad:Gamepad| be a {{Gamepad}} object.
</li>
<li>Copy the state from |gamepad| into |oldGamepad|.
</li>
<li>Set |gamepad|.{{Gamepad/[[timestamp]]}} to |now|.
</li>
<li>Run the steps to [=map and normalize axes=] for |gamepad|.
Expand All @@ -798,14 +814,6 @@ <h3>
</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>Let |document:Document?| be |gamepad|'s [=relevant global
object=]'s [=associated `Document`=]; otherwise `null`.
</li>
<li>If |document| is `null`, abort these steps.
</li>
<li>If |navigator|.{{Navigator/[[hasGamepadGesture]]}} is `false` and
|document| is a [=Document/fully active descendant of a top-level
traversable with user attention=] and |gamepad| [=contains a gamepad
Expand All @@ -825,20 +833,34 @@ <h3>
<li>Set |connectedGamepad|.{{Gamepad/[[timestamp]]}} to
|now|.
</li>
<li>If |document| is not `null` and is [=Document/fully
active=], then [=queue a global 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>[=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>
<li>If |navigator|.{{Navigator/[[hasGamepadGesture]]}} is `true`:
<ol>
<li>Let |hasInputChanged:boolean| be the result of running the
steps to [=detect gamepad input changes=] between |oldGamepad|
and |gamepad|.
</li>
<li>If |hasInputChanged| is `true`:
<ol>
<li>[=Fire an event=] named {{gamepadrawinputchanged}} at
|gamepad|'s [=relevant global object=] using {{GamepadEvent}}
with its {{GamepadEvent/gamepad}} attribute initialized to
|gamepad|.
</li>
</ol>
</li>
</ol>
</li>
</ol>
<p>
To <dfn>map and normalize axes</dfn> for |gamepad:Gamepad|, run the
Expand Down Expand Up @@ -870,7 +892,7 @@ <h3>
<li>Let |normalizedValue:double| be 2 (|logicalValue| −
|logicalMinimum|) / (|logicalMaximum| − |logicalMinimum|) − 1.
</li>
<li>Set |gamepad|.{{Gamepad/[[axes]]}}[|axisIndex|] to be
<li>Set |gamepad|.{{Gamepad/[[axes]]}}[|mappedIndex|] to be
|normalizedValue|.
</li>
</ol>
Expand Down Expand Up @@ -1006,6 +1028,108 @@ <h3>
</ol>
</li>
</ol>
<p>
To <dfn>detect gamepad input changes</dfn> between |gamepad1:Gamepad|
and |gamepad2:Gamepad|, run the following steps:
</p>
<ol class="algorithm">
<li>Assert: |gamepad1| and |gamepad2| are not `null`.
</li>
<li>If |gamepad1|.{{Gamepad/[[axes]]}}'s [=list/size=] is not equal
to |gamepad2|.{{Gamepad/[[axes]]}}'s [=list/size=], return `true`.
</li>
<li>[=list/For each=] index |axisIndex| of
|gamepad1|.{{Gamepad/[[axes]]}}:
<ol>
<li>If |gamepad1|.{{Gamepad/[[axes]]}}[|axisIndex|] is not equal
to |gamepad2|.{{Gamepad/[[axes]]}}[|axisIndex|], return `true`.
</li>
</ol>
</li>
<li>If |gamepad1|.{{Gamepad/[[buttons]]}}'s [=list/size=] is not
equal to |gamepad2|.{{Gamepad/[[buttons]]}}'s [=list/size=], return
`true`.
</li>
<li>[=list/For each=] index |buttonIndex| of
|gamepad1|.{{Gamepad/[[buttons]]}}:
<ol>
<li>Let |button1:GamepadButton| be
|gamepad1|.{{Gamepad/[[buttons]]}}[|buttonIndex|].
</li>
<li>Let |button2:GamepadButton| be
|gamepad2|.{{Gamepad/[[buttons]]}}[|buttonIndex|].
</li>
<li>If any of the following are true, then return `true`:
<ul>
<li>|button1|.{{GamepadButton/[[value]]}} is not equal to
|button2|.{{GamepadButton/[[value]]}}
</li>
<li>|button1|.{{GamepadButton/[[pressed]]}} is not equal to
|button2|.{{GamepadButton/[[pressed]]}}
</li>
<li>|button1|.{{GamepadButton/[[touched]]}} is not equal to
|button2|.{{GamepadButton/[[touched]]}}
</li>
</ul>
</li>
</ol>
</li>
<li>If |gamepad1|.{{Gamepad/[[touches]]}}'s [=list/size=] is not
equal to |gamepad2|.{{Gamepad/[[touches]]}}'s [=list/size=], return
`true`.
</li>
<li>[=list/For each=] index |touchIndex| of
|gamepad1|.{{Gamepad/[[touches]]}}:
<ol>
<li>Let |touch1:GamepadTouch| be
|gamepad1|.{{Gamepad/[[touches]]}}[|touchIndex|].
</li>
<li>Let |touch2:GamepadTouch| be
|gamepad2|.{{Gamepad/[[touches]]}}[|touchIndex|].
</li>
<li>If any of the following are true, then return `true`:
<ul>
<li>|touch1|.{{GamepadTouch/touchId}} is not equal to
|touch2|.{{GamepadTouch/touchId}}
</li>
<li>|touch1|.{{GamepadTouch/surfaceId}} is not equal to
|touch2|.{{GamepadTouch/surfaceId}}
</li>
<li>|touch1|.{{GamepadTouch/position}}.{{DOMPointReadOnly/x}}
is not equal to
|touch2|.{{GamepadTouch/position}}.{{DOMPointReadOnly/x}}
</li>
<li>|touch1|.{{GamepadTouch/position}}.{{DOMPointReadOnly/y}}
is not equal to
|touch2|.{{GamepadTouch/position}}.{{DOMPointReadOnly/y}}
</li>
<li>Exactly one of
|touch1|.{{GamepadTouch/surfaceDimensions}} and
|touch2|.{{GamepadTouch/surfaceDimensions}} is `null`.
</li>
<li>|touch1|.{{GamepadTouch/surfaceDimensions}} and
|touch2|.{{GamepadTouch/surfaceDimensions}} are both not
`null`, and any of the following are true:
<ul>
<li>
|touch1|.{{GamepadTouch/surfaceDimensions}}.{{DOMRectReadOnly/width}}
is not equal to
|touch2|.{{GamepadTouch/surfaceDimensions}}.{{DOMRectReadOnly/width}}
</li>
<li>
|touch1|.{{GamepadTouch/surfaceDimensions}}.{{DOMRectReadOnly/height}}
is not equal to
|touch2|.{{GamepadTouch/surfaceDimensions}}.{{DOMRectReadOnly/height}}
</li>
</ul>
</li>
</ul>
</li>
</ol>
</li>
<li>Return `false`.
</li>
</ol>
</section>
<section>
<h3>
Expand Down Expand Up @@ -2103,9 +2227,9 @@ <h3>
<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>If |doc| is not [=allowed to use=] the [=policy-controlled
feature=] named "gamepad", then [=exception/throw=] a
{{"SecurityError"}} {{DOMException}} and abort these steps.
</li>
<li>If [=this=].{{Navigator/[[hasGamepadGesture]]}} is `false`, then
return an empty [=list=].
Expand Down Expand Up @@ -2515,7 +2639,7 @@ <h2 id="event-gamepadconnected">
[=associated `Document`=]; otherwise `null`.
</li>
<li>If |document| is not `null` and is not [=allowed to use=] the
`"gamepad"` permission, then abort these steps.
[=policy-controlled feature=] named "gamepad", then abort these steps.
</li>
<li>[=Queue a global task=] on the [=gamepad task source=] with the
[=current global object=] to perform the following steps:
Expand Down Expand Up @@ -2610,6 +2734,21 @@ <h2 id="event-gamepaddisconnected">
dispatched to that same {{Window}}.
</p>
</section>
<section>
<h2 id="event-gamepadrawinputchanged">
The <dfn class="event">gamepadrawinputchanged</dfn> event
</h2>
<p>
This event is fired whenever the system [=receives new button or axis
input values=], and [=detect gamepad input changes|input changes are
detected=] for a gamepad device.
</p>
<p>
[=User agents=] implementing this specification MUST provide a new DOM
event, named {{gamepadrawinputchanged}}. The corresponding event MUST
be of type {{GamepadEvent}} and MUST fire on the {{Window}} object.
</p>
</section>
<section>
<h2>
Other events
Expand All @@ -2634,6 +2773,7 @@ <h2>
partial interface mixin WindowEventHandlers {
attribute EventHandler ongamepadconnected;
attribute EventHandler ongamepaddisconnected;
attribute EventHandler ongamepadrawinputchanged;
};
</pre>
</section>
Expand All @@ -2653,8 +2793,8 @@ <h2>
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.
{{Navigator/getGamepads()}}, nor will the {{gamepadconnected}},
{{gamepaddisconnected}}, and {{gamepadrawinputchanged}} events fire.
</p>
</div>
</section>
Expand Down
Loading