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

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

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

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

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

manager :Phaser.Input.InputPlugin

A reference to the global Keyboard Manager.

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

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

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

settings :Phaser.Scenes.Settings.Object

A reference to the Scene Systems Settings.

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

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 | integer | Array.<integer> | Array.<any>

The Key Codes to enable event capture for.

Since: 3.16.0
Source: src/input/keyboard/KeyboardPlugin.js (Line 215)
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 | integer

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 459)
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 397)
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 605)
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 348)
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.<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 563)
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 377)
Returns:

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

Type
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 332)
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 316)
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

getCaptures()

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

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

An array of all the currently capturing key codes.

Type
Array.<integer>

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 202)
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 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.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

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 | integer | Array.<integer> | Array.<any>

The Key Codes to disable event capture for.

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

This KeyboardPlugin object.

Type
Phaser.Input.Keyboard.KeyboardPlugin

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 525)
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.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 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 753)
Returns:

This KeyboardPlugin object.

Type
Phaser.Input.Keyboard.KeyboardPlugin