Phaser API Documentation

  Version: 
Filter
This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . Input . Gamepad . GamepadPlugin

This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . Input . Gamepad . GamepadPlugin

The Gamepad Plugin is an input plugin that belongs to the Scene-owned Input system.

Its role is to listen for native DOM Gamepad Events and then process them.

You do not need to create this class directly, the Input system will create an instance of it automatically.

You can access it from within a Scene using this.input.gamepad.

To listen for a gamepad being connected:

this.input.gamepad.once('connected', function (pad) {
    //   'pad' is a reference to the gamepad that was just connected
});

Note that the browser may require you to press a button on a gamepad before it will allow you to access it, this is for security reasons. However, it may also trust the page already, in which case you won't get the 'connected' event and instead should check GamepadPlugin.total to see if it thinks there are any gamepads already connected.

Once you have received the connected event, or polled the gamepads and found them enabled, you can access them via the built-in properties GamepadPlugin.pad1 to pad4, for up to 4 game pads. With a reference to the gamepads you can poll its buttons and axis sticks. See the properties and methods available on the Gamepad class for more details.

As of September 2020 Chrome, and likely other browsers, will soon start to require that games requesting access to the Gamepad API are running under SSL. They will actively block API access if they are not.

For more information about Gamepad support in browsers see the following resources:

https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API https://www.smashingmagazine.com/2015/11/gamepad-api-in-web-games/ http://html5gamepad.com/

Constructor:

new GamepadPlugin(sceneInputPlugin)

Parameters:

name type description
sceneInputPlugin Phaser.Input.InputPlugin

A reference to the Scene Input Plugin that the KeyboardPlugin belongs to.

Since: 3.10.0

Extends


Members

<private> _pad1: Phaser.Input.Gamepad.Gamepad
Focus
Focus

Description:

Internal Gamepad reference.

Type:
Since: 3.10.0
Focus
Focus
<private> _pad2: Phaser.Input.Gamepad.Gamepad
Focus
Focus

Description:

Internal Gamepad reference.

Type:
Since: 3.10.0
Focus
Focus
<private> _pad3: Phaser.Input.Gamepad.Gamepad
Focus
Focus

Description:

Internal Gamepad reference.

Type:
Since: 3.10.0
Focus
Focus
<private> _pad4: Phaser.Input.Gamepad.Gamepad
Focus
Focus

Description:

Internal Gamepad reference.

Type:
Since: 3.10.0
Focus
Focus
enabled: boolean
Focus
Focus

Description:

A boolean that controls if the Gamepad Manager is enabled or not. Can be toggled on the fly.

Type:
boolean
Default: true
Since: 3.10.0
Focus
Focus
gamepads: Array.<Phaser.Input.Gamepad.Gamepad>
Focus
Focus

Description:

An array of the connected Gamepads.

Type:
Default: []
Since: 3.10.0
Focus
Focus
<private> onGamepadHandler: function
Focus
Focus

Description:

Internal event handler.

Type:
function
Since: 3.10.0
Focus
Focus

Description:

A reference to the first connected Gamepad.

This will be undefined if either no pads are connected, or the browser has not yet issued a gamepadconnect, which can happen even if a Gamepad is plugged in, but hasn't yet had any buttons pressed on it.

Type:
Since: 3.10.0
Focus
Focus

Description:

A reference to the second connected Gamepad.

This will be undefined if either no pads are connected, or the browser has not yet issued a gamepadconnect, which can happen even if a Gamepad is plugged in, but hasn't yet had any buttons pressed on it.

Type:
Since: 3.10.0
Focus
Focus

Description:

A reference to the third connected Gamepad.

This will be undefined if either no pads are connected, or the browser has not yet issued a gamepadconnect, which can happen even if a Gamepad is plugged in, but hasn't yet had any buttons pressed on it.

Type:
Since: 3.10.0
Focus
Focus

Description:

A reference to the fourth connected Gamepad.

This will be undefined if either no pads are connected, or the browser has not yet issued a gamepadconnect, which can happen even if a Gamepad is plugged in, but hasn't yet had any buttons pressed on it.

Type:
Since: 3.10.0
Focus
Focus
<private> queue: Array.<GamepadEvent>
Focus
Focus

Description:

An internal event queue.

Type:
Array.<GamepadEvent>
Since: 3.10.0
Focus
Focus
scene: Phaser.Scene
Focus
Focus

Description:

A reference to the Scene that this Input Plugin is responsible for.

Type:
Since: 3.10.0
Focus
Focus
sceneInputPlugin: Phaser.Input.InputPlugin
Focus
Focus

Description:

A reference to the Scene Input Plugin that created this Keyboard Plugin.

Type:
Since: 3.10.0
Focus
Focus

Description:

A reference to the Scene Systems Settings.

Type:
Since: 3.10.0
Focus
Focus
target: any
Focus
Focus

Description:

The Gamepad Event target, as defined in the Game Config. Typically the browser window, but can be any interactive DOM element.

Type:
any
Since: 3.10.0
Focus
Focus
total: number
Focus
Focus

Description:

The total number of connected game pads.

Type:
number
Since: 3.10.0
Focus
Focus

Methods

addListener(event, fn, [context])
Focus
Focus

Description:

Add a listener for a given event.

Parameters:

name type arguments Default description
event string | symbol

The event name.

fn function

The listener function.

context * <optional> this

The context to invoke the listener with.

Returns:
Description:

this.

Inherited from: Phaser.Events.EventEmitter#addListener
Examples:
Since: 3.0.0
Focus
Focus
<private> boot()
Focus
Focus

Description:

This method is called automatically, only once, when the Scene is first created. Do not invoke it directly.

Examples:
Since: 3.10.0
Focus
Focus
<private> destroy()
Focus
Focus

Description:

Destroys this Gamepad Plugin, disconnecting all Gamepads and releasing internal references.

Overrides: Phaser.Events.EventEmitter#destroy
Examples:
Since: 3.10.0
Focus
Focus
disconnectAll()
Focus
Focus

Description:

Disconnects all current Gamepads.

Examples:
Since: 3.10.0
Focus
Focus
emit(event, [args])
Focus
Focus

Description:

Calls each of the listeners registered for a given event.

Parameters:

name type arguments description
event string | symbol

The event name.

args * <optional>

Additional arguments that will be passed to the event handler.

Returns:
Description:

true if the event had listeners, else false.

Type:
  • boolean
Inherited from: Phaser.Events.EventEmitter#emit
Examples:
Since: 3.0.0
Focus
Focus
eventNames()
Focus
Focus

Description:

Return an array listing the events for which the emitter has registered listeners.

Type:
  • Array.<(string
  • symbol)>
Inherited from: Phaser.Events.EventEmitter#eventNames
Examples:
Since: 3.0.0
Focus
Focus
getAll()
Focus
Focus

Description:

Returns an array of all currently connected Gamepads.

Returns:
Description:

An array of all currently connected Gamepads.

Examples:
Since: 3.10.0
Focus
Focus
getPad(index)
Focus
Focus

Description:

Looks-up a single Gamepad based on the given index value.

Parameters:

name type description
index number

The index of the Gamepad to get.

Returns:
Description:

The Gamepad matching the given index, or undefined if none were found.

Examples:
Since: 3.10.0
Focus
Focus
isActive()
Focus
Focus

Description:

Checks to see if both this plugin and the Scene to which it belongs is active.

Returns:
Description:

true if the plugin and the Scene it belongs to is active.

Type:
  • boolean
Examples:
Since: 3.10.0
Focus
Focus
listenerCount(event)
Focus
Focus

Description:

Return the number of listeners listening to a given event.

Parameters:

name type description
event string | symbol

The event name.

Returns:
Description:

The number of listeners.

Type:
  • number
Inherited from: Phaser.Events.EventEmitter#listenerCount
Examples:
Since: 3.0.0
Focus
Focus
listeners(event)
Focus
Focus

Description:

Return the listeners registered for a given event.

Parameters:

name type description
event string | symbol

The event name.

Returns:
Description:

The registered listeners.

Type:
  • Array.
Inherited from: Phaser.Events.EventEmitter#listeners
Examples:
Since: 3.0.0
Focus
Focus
off(event, [fn], [context], [once])
Focus
Focus

Description:

Remove the listeners of a given event.

Parameters:

name type arguments description
event string | symbol

The event name.

fn function <optional>

Only remove the listeners that match this function.

context * <optional>

Only remove the listeners that have this context.

once boolean <optional>

Only remove one-time listeners.

Returns:
Description:

this.

Inherited from: Phaser.Events.EventEmitter#off
Examples:
Since: 3.0.0
Focus
Focus
on(event, fn, [context])
Focus
Focus

Description:

Add a listener for a given event.

Parameters:

name type arguments Default description
event string | symbol

The event name.

fn function

The listener function.

context * <optional> this

The context to invoke the listener with.

Returns:
Description:

this.

Inherited from: Phaser.Events.EventEmitter#on
Examples:
Since: 3.0.0
Focus
Focus
once(event, fn, [context])
Focus
Focus

Description:

Add a one-time listener for a given event.

Parameters:

name type arguments Default description
event string | symbol

The event name.

fn function

The listener function.

context * <optional> this

The context to invoke the listener with.

Returns:
Description:

this.

Inherited from: Phaser.Events.EventEmitter#once
Examples:
Since: 3.0.0
Focus
Focus
<private> refreshPads()
Focus
Focus

Description:

Refreshes the list of connected Gamepads.

This is called automatically when a gamepad is connected or disconnected, and during the update loop.

Examples:
Since: 3.10.0
Focus
Focus
removeAllListeners([event])
Focus
Focus

Description:

Remove all listeners, or those of the specified event.

Parameters:

name type arguments description
event string | symbol <optional>

The event name.

Returns:
Description:

this.

Inherited from: Phaser.Events.EventEmitter#removeAllListeners
Examples:
Since: 3.0.0
Focus
Focus
removeListener(event, [fn], [context], [once])
Focus
Focus

Description:

Remove the listeners of a given event.

Parameters:

name type arguments description
event string | symbol

The event name.

fn function <optional>

Only remove the listeners that match this function.

context * <optional>

Only remove the listeners that have this context.

once boolean <optional>

Only remove one-time listeners.

Returns:
Description:

this.

Inherited from: Phaser.Events.EventEmitter#removeListener
Examples:
Since: 3.0.0
Focus
Focus
<private> shutdown()
Focus
Focus

Description:

Shuts the Gamepad Plugin down. All this does is remove any listeners bound to it.

Overrides: Phaser.Events.EventEmitter#shutdown
Examples:
Since: 3.10.0
Focus
Focus
<private> start()
Focus
Focus

Description:

This method is called automatically by the Scene when it is starting up. It is responsible for creating local systems, properties and listening for Scene events. Do not invoke it directly.

Examples:
Since: 3.10.0
Focus
Focus
<private> startListeners()
Focus
Focus

Description:

Starts the Gamepad Event listeners running. This is called automatically and does not need to be manually invoked.

Examples:
Since: 3.10.0
Focus
Focus
<private> stopListeners()
Focus
Focus

Description:

Stops the Gamepad Event listeners. This is called automatically and does not need to be manually invoked.

Examples:
Since: 3.10.0
Focus
Focus
<private> update()
Focus
Focus

Description:

The internal update loop. Refreshes all connected gamepads and processes their events.

Called automatically by the Input Manager, invoked from the Game step.

Examples:
Since: 3.10.0
Focus
Focus