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

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

Constructor:

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

Extends


Members

Description:

An array of KeyCombo objects to process.

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

Description:

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

Type:
boolean
Default: true
Since: 3.10.0
Focus
Focus
game: Phaser.Game
Focus
Focus

Description:

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

Type:
Since: 3.16.0
Focus
Focus

Description:

An array of Key objects to process.

Type:
Since: 3.10.0
Focus
Focus

Description:

A reference to the global Keyboard Manager.

Type:
Since: 3.16.0
Focus
Focus
<private> prevCode: string
Focus
Focus

Description:

Internal repeat key flag.

Type:
string
Since: 3.50.0
Focus
Focus
<private> prevTime: number
Focus
Focus

Description:

Internal repeat key flag.

Type:
number
Since: 3.50.0
Focus
Focus
<private> prevType: string
Focus
Focus

Description:

Internal repeat key flag.

Type:
string
Since: 3.50.1
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
<private> time: number
Focus
Focus

Description:

Internal time value.

Type:
number
Since: 3.11.0
Focus
Focus

Methods

addCapture(keycode)
Focus
Focus

Description:

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.

Returns:
Description:

This KeyboardPlugin object.

Examples:
Since: 3.16.0
Focus
Focus
addKey(key, [enableCapture], [emitOnRepeat])
Focus
Focus

Description:

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

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

Returns:
Description:

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

Examples:
Since: 3.10.0
Focus
Focus
addKeys(keys, [enableCapture], [emitOnRepeat])
Focus
Focus

Description:

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

Returns:
Description:

An object containing Key objects mapped to the input properties.

Type:
  • object
Examples:
Since: 3.10.0
Focus
Focus
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
checkDown(key, [duration])
Focus
Focus

Description:

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 arguments description
key Phaser.Input.Keyboard.Key

A Key object.

duration number <optional>

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

Returns:
Description:

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

Type:
  • boolean
Examples:
Since: 3.11.0
Focus
Focus
clearCaptures()
Focus
Focus

Description:

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.

Returns:
Description:

This KeyboardPlugin object.

Examples:
Since: 3.16.0
Focus
Focus
createCombo(keys, [config])
Focus
Focus

Description:

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 arguments 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.

Returns:
Description:

The new KeyCombo object.

Examples:
Since: 3.10.0
Focus
Focus
createCursorKeys()
Focus
Focus

Description:

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

Returns:
Description:

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

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

Description:

Destroys this Keyboard Plugin instance and all references it holds, plus clears out local arrays.

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

Description:

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.

Returns:
Description:

This KeyboardPlugin object.

Examples:
Since: 3.16.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
enableGlobalCapture()
Focus
Focus

Description:

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.

Returns:
Description:

This KeyboardPlugin object.

Examples:
Since: 3.16.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
getCaptures()
Focus
Focus

Description:

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

Returns:
Description:

An array of all the currently capturing key codes.

Type:
  • Array.
Examples:
Since: 3.16.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
removeAllKeys([destroy])
Focus
Focus

Description:

Removes all Key objects created by this Keyboard Plugin.

Parameters:

name type arguments Default description
destroy boolean <optional> false

Call Key.destroy on each removed Key object?

Returns:
Description:

This KeyboardPlugin object.

Examples:
Since: 3.24.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
removeCapture(keycode)
Focus
Focus

Description:

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.

Returns:
Description:

This KeyboardPlugin object.

Examples:
Since: 3.16.0
Focus
Focus
removeKey(key, [destroy])
Focus
Focus

Description:

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

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?

Returns:
Description:

This KeyboardPlugin object.

Examples:
Since: 3.10.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
resetKeys()
Focus
Focus

Description:

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.

Returns:
Description:

This KeyboardPlugin object.

Examples:
Since: 3.15.0
Focus
Focus
<private> shutdown()
Focus
Focus

Description:

Shuts this Keyboard Plugin down. This performs the following tasks:

1 - Removes all keys created by this Keyboard plugin. 2 - Stops and removes the keyboard event listeners. 3 - Clears out any pending requests in the queue, without processing them.

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> update()
Focus
Focus

Description:

Internal update handler called by the Input Plugin, which is in turn invoked by the Game step.

Examples:
Since: 3.10.0
Focus
Focus