Class: KeyboardPlugin

Phaser.Input.Keyboard. KeyboardPlugin

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

Its role is to listen for native DOM Keyboard 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.keyboard. For example, you can do:

this.input.keyboard.on('keydown', callback, context);

Or, to listen for a specific key:

this.input.keyboard.on('keydown_A', callback, context);

You can also create Key objects, which you can then poll in your game loop:

var spaceBar = this.input.keyboard.addKey(Phaser.Input.Keyboard.KeyCodes.SPACE);

Note: Many keyboards are unable to process certain combinations of keys due to hardware limitations known as ghosting.
See http://www.html5gamedevs.com/topic/4876-impossible-to-use-more-than-2-keyboard-input-buttons-at-the-same-time/ for more details.

Also please be aware that certain browser extensions can disable or override Phaser keyboard handling.
For example the Chrome extension vimium is known to disable Phaser from using the D key, while EverNote disables the backtick key.
And there are others. So, please check your extensions before opening Phaser issues about keys that don't work.


new KeyboardPlugin(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
Source: src/input/keyboard/KeyboardPlugin.js (Line 19)

Extends

Members


combos :Array.<Phaser.Input.Keyboard.KeyCombo>

An array of KeyCombo objects to process.

Type:
Since: 3.10.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 127)

enabled :boolean

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

Type:
  • boolean
Since: 3.10.0
Default Value:
  • true
Source: src/input/keyboard/KeyboardPlugin.js (Line 97)

keys :Array.<Phaser.Input.Keyboard.Key>

An array of Key objects to process.

Type:
Since: 3.10.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 118)

scene :Phaser.Scene

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

Type:
Since: 3.10.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 70)

sceneInputPlugin :Phaser.Input.InputPlugin

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

Type:
Since: 3.10.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 88)

settings :Phaser.Scenes.Settings.Object

A reference to the Scene Systems Settings.

Type:
Since: 3.10.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 79)

target :any

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

Type:
  • any
Since: 3.10.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 108)

Methods


addKey(key)

Adds a Key object to this Keyboard Plugin.

The given argument can be either an existing Key object, a string, such as A or SPACE, or a key code value.

If a Key object is given, and one already exists matching the same key code, the existing one is replaced with the new one.

Parameters:
Name Type Description
key Phaser.Input.Keyboard.Key | string | integer

Either a Key object, a string, such as A or SPACE, or a key code value.

Since: 3.10.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 366)
Returns:

The newly created Key object, or a reference to it if it already existed in the keys array.

Type
Phaser.Input.Keyboard.Key

addKeys(keys)

A practical way to create an object containing user selected hotkeys.

For example:

this.input.keyboard.addKeys({ 'up': Phaser.Input.Keyboard.KeyCodes.W, 'down': Phaser.Input.Keyboard.KeyCodes.S });

would return an object containing the properties (up and down) mapped to W and S Phaser.Input.Keyboard.Key objects.

You can also pass in a comma-separated string:

this.input.keyboard.addKeys('W,S,A,D');

Which will return an object with the properties W, S, A and D mapped to the relevant Key objects.

To use non-alpha numeric keys, use a string, such as 'UP', 'SPACE' or 'LEFT'.

Parameters:
Name Type Description
keys object | string

An object containing Key Codes, or a comma-separated string.

Since: 3.10.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 309)
Returns:

An object containing Key objects mapped to the input properties.

Type
object

addListener(event, fn [, context])

Add a listener for a given event.

Parameters:
Name Type Argument Default Description
event string | symbol

The event name.

fn function

The listener function.

context * <optional>
this

The context to invoke the listener with.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 111)
Returns:

this.

Type
Phaser.Events.EventEmitter

checkDown(key [, duration])

Checks if the given Key object is currently being held down.

The difference between this method and checking the Key.isDown property directly is that you can provide
a duration to this method. For example, if you wanted a key press to fire a bullet, but you only wanted
it to be able to fire every 100ms, then you can call this method with a duration of 100 and it
will only return true every 100ms.

If the Keyboard Plugin has been disabled, this method will always return false.

Parameters:
Name Type Argument Default Description
key Phaser.Input.Keyboard.Key

A Key object.

duration number <optional>
0

The duration which must have elapsed before this Key is considered as being down.

Since: 3.11.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 489)
Returns:

True if the Key is down within the duration specified, otherwise false.

Type
boolean

createCombo(keys [, config])

Creates a new KeyCombo.

A KeyCombo will listen for a specific string of keys from the Keyboard, and when it receives them
it will emit a keycombomatch event from this Keyboard Plugin.

The keys to be listened for can be defined as:

A string (i.e. 'ATARI')
An array of either integers (key codes) or strings, or a mixture of both
An array of objects (such as Key objects) with a public 'keyCode' property

For example, to listen for the Konami code (up, up, down, down, left, right, left, right, b, a, enter)
you could pass the following array of key codes:

this.input.keyboard.createCombo([ 38, 38, 40, 40, 37, 39, 37, 39, 66, 65, 13 ], { resetOnMatch: true });

this.input.keyboard.on('keycombomatch', function (event) {
    console.log('Konami Code entered!');
});

Or, to listen for the user entering the word PHASER:

this.input.keyboard.createCombo('PHASER');
Parameters:
Name Type Argument Description
keys string | Array.<integer> | Array.<object>

The keys that comprise this combo.

config KeyComboConfig <optional>

A Key Combo configuration object.

Since: 3.10.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 447)
Returns:

The new KeyCombo object.

Type
Phaser.Input.Keyboard.KeyCombo

createCursorKeys()

Creates and returns an object containing 4 hotkeys for Up, Down, Left and Right, and also Space Bar and shift.

Since: 3.10.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 289)
Returns:

An object containing the properties: up, down, left, right, space and shift.

Type
CursorKeys

emit(event [, args])

Calls each of the listeners registered for a given event.

Parameters:
Name Type Argument Description
event string | symbol

The event name.

args * <optional>
<repeatable>

Additional arguments that will be passed to the event handler.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 86)
Returns:

true if the event had listeners, else false.

Type
boolean

eventNames()

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

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 55)
Returns:
Type
array

isActive()

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

Since: 3.10.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 208)
Returns:

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

Type
boolean

listenerCount(event)

Return the number of listeners listening to a given event.

Parameters:
Name Type Description
event string | symbol

The event name.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 75)
Returns:

The number of listeners.

Type
number

listeners(event)

Return the listeners registered for a given event.

Parameters:
Name Type Description
event string | symbol

The event name.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 64)
Returns:

The registered listeners.

Type
array

off(event, fn, context, once)

Remove the listeners of a given event.

Parameters:
Name Type Description
event string | symbol

The event name.

fn function

Only remove the listeners that match this function.

context *

Only remove the listeners that have this context.

once boolean

Only remove one-time listeners.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 151)
Returns:

this.

Type
Phaser.Events.EventEmitter

on(event, fn [, context])

Add a listener for a given event.

Parameters:
Name Type Argument Default Description
event string | symbol

The event name.

fn function

The listener function.

context * <optional>
this

The context to invoke the listener with.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 98)
Returns:

this.

Type
Phaser.Events.EventEmitter

once(event, fn [, context])

Add a one-time listener for a given event.

Parameters:
Name Type Argument Default Description
event string | symbol

The event name.

fn function

The listener function.

context * <optional>
this

The context to invoke the listener with.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 124)
Returns:

this.

Type
Phaser.Events.EventEmitter

removeAllListeners( [event])

Remove all listeners, or those of the specified event.

Parameters:
Name Type Argument Description
event string | symbol <optional>

The event name.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 165)
Returns:

this.

Type
Phaser.Events.EventEmitter

removeKey(key)

Removes a Key object from this Keyboard Plugin.

The given argument can be either a Key object, a string, such as A or SPACE, or a key code value.

Parameters:
Name Type Description
key Phaser.Input.Keyboard.Key | string | integer

Either a Key object, a string, such as A or SPACE, or a key code value.

Since: 3.10.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 413)

removeListener(event, fn, context, once)

Remove the listeners of a given event.

Parameters:
Name Type Description
event string | symbol

The event name.

fn function

Only remove the listeners that match this function.

context *

Only remove the listeners that have this context.

once boolean

Only remove one-time listeners.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 137)
Returns:

this.

Type
Phaser.Events.EventEmitter

resetKeys()

Resets all Key objects created by this Keyboard Plugin back to their default un-pressed states.
This can only reset keys created via the addKey, addKeys or createCursors methods.
If you have created a Key object directly you'll need to reset it yourself.

This method is called automatically when the Keyboard Plugin shuts down, but can be
invoked directly at any time you require.

Since: 3.15.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 586)