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);

If you have multiple parallel Scenes, each trying to get keyboard input, be sure to disable capture on them to stop them from stealing input from another Scene in the list. You can do this with this.input.keyboard.enabled = false within the Scene to stop all input, or this.input.keyboard.preventDefault = false to stop a Scene halting input on another Scene.

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 21)

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 141)

enabled :boolean

A boolean that controls if this 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 121)

game :Phaser.Game

A reference to the core game, so we can listen for visibility events.

Type:
Since: 3.16.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 76)

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 132)

manager :Phaser.Input.InputPlugin

A reference to the global Keyboard Manager.

Type:
Since: 3.16.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 112)

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 85)

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 103)

settings :Phaser.Types.Scenes.SettingsObject

A reference to the Scene Systems Settings.

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

Methods

addCapture(keycode)

By default when a key is pressed Phaser will not stop the event from propagating up to the browser. There are some keys this can be annoying for, like the arrow keys or space bar, which make the browser window scroll.

This addCapture method enables consuming keyboard events for specific keys, so they don't bubble up the browser and cause the default behaviors.

Please note that keyboard captures are global. This means that if you call this method from within a Scene, to say prevent the SPACE BAR from triggering a page scroll, then it will prevent it for any Scene in your game, not just the calling one.

You can pass a single key code value:

this.input.keyboard.addCapture(62);

An array of key codes:

this.input.keyboard.addCapture([ 62, 63, 64 ]);

Or, a comma-delimited string:

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

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

You can also provide an array mixing both strings and key code integers.

Parameters:
Name Type Description
keycode string | number | Array.<number> | Array.<any>

The Key Codes to enable event capture for.
Since: 3.16.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 242)
Returns:

This KeyboardPlugin object.

Type
Phaser.Input.Keyboard.KeyboardPlugin

addKey(key [, enableCapture] [, emitOnRepeat])

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 Argument Default Description
key Phaser.Input.Keyboard.Key | string | number

Either a Key object, a string, such as A or SPACE, or a key code value.
enableCapture boolean <optional>
 true

Automatically call preventDefault on the native DOM browser event for the key codes being added.
emitOnRepeat boolean <optional>
 false

Controls if the Key will continuously emit a 'down' event while being held down (true), or emit the event just once (false, the default).
Since: 3.10.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 474)
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 [, enableCapture] [, emitOnRepeat])

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 Argument Default Description
keys object | string

An object containing Key Codes, or a comma-separated string.
enableCapture boolean <optional>
 true

Automatically call preventDefault on the native DOM browser event for the key codes being added.
emitOnRepeat boolean <optional>
 false

Controls if the Key will continuously emit a 'down' event while being held down (true), or emit the event just once (false, the default).
Since: 3.10.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 412)
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.Input.Keyboard.KeyboardPlugin

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 670)
Returns:

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

Type
boolean

clearCaptures()

Removes all keyboard captures.

Note that this is a global change. It will clear all event captures across your game, not just for this specific Scene.

Since: 3.16.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 375)
Returns:

This KeyboardPlugin object.

Type
Phaser.Input.Keyboard.KeyboardPlugin

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.<number> | Array.<object>

The keys that comprise this combo.
config Phaser.Types.Input.Keyboard.KeyComboConfig <optional>

A Key Combo configuration object.
Since: 3.10.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 628)
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 392)
Returns:

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

Type
Phaser.Types.Input.Keyboard.CursorKeys

disableGlobalCapture()

Disables Phaser from preventing any key captures you may have defined, without actually removing them. You can use this to temporarily disable event capturing if, for example, you swap to a DOM element.

Since: 3.16.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 359)
Returns:

This KeyboardPlugin object.

Type
Phaser.Input.Keyboard.KeyboardPlugin

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

enableGlobalCapture()

Allows Phaser to prevent any key captures you may have defined from bubbling up the browser. You can use this to re-enable event capturing if you had paused it via disableGlobalCapture.

Since: 3.16.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 343)
Returns:

This KeyboardPlugin object.

Type
Phaser.Input.Keyboard.KeyboardPlugin

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.<(string|symbol)>

getCaptures()

Returns an array that contains all of the keyboard captures currently enabled.

Since: 3.16.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 330)
Returns:

An array of all the currently capturing key codes.

Type
Array.<number>

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 229)
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.<function()>

off(event [, fn] [, context] [, once])

Remove the listeners of a given event.

Parameters:
Name Type Argument 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.
Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 151)
Returns:

this.

Type
Phaser.Input.Keyboard.KeyboardPlugin

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.Input.Keyboard.KeyboardPlugin

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.Input.Keyboard.KeyboardPlugin

removeAllKeys( [destroy])

Removes all Key objects created by this Keyboard Plugin.

Parameters:
Name Type Argument Default Description
destroy boolean <optional>
 false

Call Key.destroy on each removed Key object?
Since: 3.24.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 596)
Returns:

This KeyboardPlugin object.

Type
Phaser.Input.Keyboard.KeyboardPlugin

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.Input.Keyboard.KeyboardPlugin

removeCapture(keycode)

Removes an existing key capture.

Please note that keyboard captures are global. This means that if you call this method from within a Scene, to remove the capture of a key, then it will remove it for any Scene in your game, not just the calling one.

You can pass a single key code value:

this.input.keyboard.removeCapture(62);

An array of key codes:

this.input.keyboard.removeCapture([ 62, 63, 64 ]);

Or, a comma-delimited string:

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

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

You can also provide an array mixing both strings and key code integers.

Parameters:
Name Type Description
keycode string | number | Array.<number> | Array.<any>

The Key Codes to disable event capture for.
Since: 3.16.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 288)
Returns:

This KeyboardPlugin object.

Type
Phaser.Input.Keyboard.KeyboardPlugin

removeKey(key [, destroy])

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 Argument Default Description
key Phaser.Input.Keyboard.Key | string | number

Either a Key object, a string, such as A or SPACE, or a key code value.
destroy boolean <optional>
 false

Call Key.destroy on the removed Key object?
Since: 3.10.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 540)
Returns:

This KeyboardPlugin object.

Type
Phaser.Input.Keyboard.KeyboardPlugin

removeListener(event [, fn] [, context] [, once])

Remove the listeners of a given event.

Parameters:
Name Type Argument 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.
Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 137)
Returns:

this.

Type
Phaser.Input.Keyboard.KeyboardPlugin

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 createCursorKeys 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 823)
Returns:

This KeyboardPlugin object.

Type
Phaser.Input.Keyboard.KeyboardPlugin