Class: GamepadInput
Defined in: src/interaction/GamepadInput.ts:230
Reads live gamepad state for interactive apps and games. Mirrors KeyboardInput: construct, then enable / disable / dispose, and poll once a frame.
Constructors
Constructor
new GamepadInput(
options,getGamepads?,eventTarget?):GamepadInput
Defined in: src/interaction/GamepadInput.ts:256
Create a GamepadInput.
Parameters
options
GamepadInputOptions = {}
Behavior options.
getGamepads?
Snapshot source. Defaults to navigator.getGamepads,
or null when no Gamepad API is present. Tests inject a fake here.
eventTarget?
EventTarget
Target for connection events. Defaults to window.
Returns
GamepadInput
Accessors
hasSource
Get Signature
get hasSource():
boolean
Defined in: src/interaction/GamepadInput.ts:284
Whether a Gamepad API snapshot source is available.
Returns
boolean
hasTarget
Get Signature
get hasTarget():
boolean
Defined in: src/interaction/GamepadInput.ts:289
Whether a DOM target for connection events is available.
Returns
boolean
isEnabled
Get Signature
get isEnabled():
boolean
Defined in: src/interaction/GamepadInput.ts:279
Whether the controller is enabled (connection listeners attached).
Returns
boolean
Methods
anyButtonDown()
anyButtonDown():
boolean
Defined in: src/interaction/GamepadInput.ts:412
Whether any button is held right now.
Returns
boolean
bindBool()
bindBool(
machine,inputName,button):Unsubscribe
Defined in: src/interaction/GamepadInput.ts:543
Hold a StateMachine bool input to match a button: true while held,
false on release.
Parameters
machine
The StateMachine (or any StateMachineInputSink).
inputName
string
The bool input name.
button
The button to track.
string | number
Returns
An unsubscribe function.
bindTrigger()
bindTrigger(
machine,triggerName,button):Unsubscribe
Defined in: src/interaction/GamepadInput.ts:563
Fire a StateMachine trigger input on each button-down.
Parameters
machine
The StateMachine (or any StateMachineInputSink).
triggerName
string
The trigger input name.
button
The button to track.
string | number
Returns
An unsubscribe function.
bindValue()
bindValue(
tracker,button,options):Unsubscribe
Defined in: src/interaction/GamepadInput.ts:579
Drive a ValueTracker from a button: heldValue while held,
releasedValue on release.
Parameters
tracker
The ValueTracker (or any ValueSink).
button
The button to track.
string | number
options
The held and released values.
Returns
An unsubscribe function.
clear()
clear():
void
Defined in: src/interaction/GamepadInput.ts:330
Clear held buttons, both edge sets, and the cached axes and values.
Returns
void
disable()
disable():
void
Defined in: src/interaction/GamepadInput.ts:310
Detach the connection listeners and clear all held and edge state, so no button stays stuck. Reads return defaults until enable is called.
Returns
void
dispose()
dispose():
void
Defined in: src/interaction/GamepadInput.ts:323
Detach listeners and drop every registered callback. Use when the controller is no longer needed.
Returns
void
enable()
enable():
void
Defined in: src/interaction/GamepadInput.ts:297
Attach the gamepadconnected / gamepaddisconnected listeners. A no-op
when already enabled. Polling works even without a DOM target.
Returns
void
getAxis()
getAxis(
index,deadzone):number
Defined in: src/interaction/GamepadInput.ts:458
The raw value [-1, 1] of an axis, with the deadzone applied so a resting
stick reads 0. The API convention is used verbatim: for the vertical
stick axes, up is negative.
Parameters
index
number
The axis index (see STANDARD_AXES).
deadzone
number = ...
Override the instance deadzone for this read.
Returns
number
getButtonValue()
getButtonValue(
button):number
Defined in: src/interaction/GamepadInput.ts:441
The analog value [0, 1] of a button (triggers vary; plain buttons read
0 or 1).
Parameters
button
A button index or name.
string | number
Returns
number
getConnectedGamepads()
getConnectedGamepads():
GamepadLike[]
Defined in: src/interaction/GamepadInput.ts:496
The connected pads in the current snapshot (empty when headless).
Returns
getDirectionVector()
getDirectionVector(): [
number,number]
Defined in: src/interaction/GamepadInput.ts:481
A normalized movement direction [x, y], up is +y. The d-pad wins when
any d-pad button is held; otherwise the left stick is used. A neutral input
stays [0, 0].
Returns
[number, number]
getLeftStick()
getLeftStick(): [
number,number]
Defined in: src/interaction/GamepadInput.ts:466
The left stick as [x, y], deadzone applied, with up as +y (the API's
downward vertical axis is flipped to match KeyboardInput).
Returns
[number, number]
getRightStick()
getRightStick(): [
number,number]
Defined in: src/interaction/GamepadInput.ts:472
The right stick as [x, y], deadzone applied, with up as +y.
Returns
[number, number]
isButtonDown()
isButtonDown(
button):boolean
Defined in: src/interaction/GamepadInput.ts:406
Whether the button is held right now (as of the last poll).
Parameters
button
A button index, or a name ('A', 'dpadUp', 'LT').
string | number
Returns
boolean
onButtonDown()
onButtonDown(
button,callback):Unsubscribe
Defined in: src/interaction/GamepadInput.ts:517
Register a button-down callback, fired by poll on a 0→1 edge.
Parameters
button
A button index or name, or 'any' for every button.
string | number
callback
Called with the button index and the pad.
Returns
An unsubscribe function.
onButtonUp()
onButtonUp(
button,callback):Unsubscribe
Defined in: src/interaction/GamepadInput.ts:527
Register a button-up callback, fired by poll on a 1→0 edge.
Parameters
button
A button index or name, or 'any' for every button.
string | number
callback
Called with the button index and the pad.
Returns
An unsubscribe function.
poll()
poll():
void
Defined in: src/interaction/GamepadInput.ts:350
Read the live gamepad snapshot and compute the press / release edges. Call once per frame before reading state. The edges stay readable until the next poll, so wasButtonPressed is true for exactly one frame.
When no pad is present, any held button is released and the state resets, so a disconnect never leaves a button stuck.
Returns
void
update()
update(
_dt):void
Defined in: src/interaction/GamepadInput.ts:394
Alias of poll for render-loop compatibility with KeyboardInput.
Parameters
_dt
number = 0
Delta time (seconds), accepted but not used.
Returns
void
wasButtonPressed()
wasButtonPressed(
button):boolean
Defined in: src/interaction/GamepadInput.ts:421
Whether the button went down on the last poll. True for exactly one frame after a 0→1 transition.
Parameters
button
A button index or name.
string | number
Returns
boolean
wasButtonReleased()
wasButtonReleased(
button):boolean
Defined in: src/interaction/GamepadInput.ts:431
Whether the button came up on the last poll. True for exactly one frame after a 1→0 transition.
Parameters
button
A button index or name.
string | number
Returns
boolean