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

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

The Input Plugin belongs to a Scene and handles all input related events and operations for it.

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

It emits events directly. For example, you can do:

this.input.on('pointerdown', callback, context);

To listen for a pointer down event anywhere on the game canvas.

Game Objects can be enabled for input by calling their setInteractive method. After which they will directly emit input events:

var sprite = this.add.sprite(x, y, texture);
sprite.setInteractive();
sprite.on('pointerdown', callback, context);

There are lots of game configuration options available relating to input. See the [Input Config object](code Phaser.Types.Core.InputConfig) for more details, including how to deal with Phaser listening for input events outside of the canvas, how to set a default number of pointers, input capture settings and more.

Please also see the Input examples and tutorials for further information.

Incorrect input coordinates with Angular

If you are using Phaser within Angular, and use nglf or the router, to make the component in which the Phaser game resides change state (i.e. appear or disappear) then you'll need to notify the Scale Manager about this, as Angular will mess with the DOM in a way in which Phaser can't detect directly. Call this.scale.updateBounds() as part of your game init in order to refresh the canvas DOM bounds values, which Phaser uses for input point position calculations.

Constructor:

new InputPlugin(scene)

Parameters:

name type description
scene Phaser.Scene

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

Since: 3.0.0
Source: src/input/InputPlugin.js (Line 29)

Extends


Members

<private> _drag: Object
Focus
Focus

Description:

A list of all Interactive Objects currently considered as being 'draggable' by any pointer, indexed by pointer ID.

Type:
Object
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 339)
Focus
Focus
<private> _dragState: Array.<number>
Focus
Focus

Description:

A array containing the dragStates, for this Scene, index by the Pointer ID.

Type:
Array.<number>
Since: 3.16.0
Source: src/input/InputPlugin.js (Line 349)
Focus
Focus
<private> _draggable: Array.<Phaser.GameObjects.GameObject>
Focus
Focus

Description:

A list of all Game Objects that have been enabled for dragging.

Type:
Default: []
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 328)
Focus
Focus
<private> _eventContainer: Phaser.Types.Input.EventData
Focus
Focus

Description:

Internal event propagation callback container.

Type:
Since: 3.13.0
Source: src/input/InputPlugin.js (Line 222)
Focus
Focus
<private> _eventData: object
Focus
Focus

Description:

Internal event propagation data object.

Type:
object
Since: 3.13.0
Source: src/input/InputPlugin.js (Line 237)
Focus
Focus
<private> _list: Array.<Phaser.GameObjects.GameObject>
Focus
Focus

Description:

A list of all Game Objects that have been set to be interactive in the Scene this Input Plugin is managing.

Type:
Default: []
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 295)
Focus
Focus
<private> _over: Object
Focus
Focus

Description:

A list of all Interactive Objects currently considered as being 'over' by any pointer, indexed by pointer ID.

Type:
Object
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 359)
Focus
Focus
<private> _pendingInsertion: Array.<Phaser.GameObjects.GameObject>
Focus
Focus

Description:

Objects waiting to be inserted to the list on the next call to 'begin'.

Type:
Default: []
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 306)
Focus
Focus
<private> _pendingRemoval: Array.<Phaser.GameObjects.GameObject>
Focus
Focus

Description:

Objects waiting to be removed from the list on the next call to 'begin'.

Type:
Default: []
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 317)
Focus
Focus
<private> _pollTimer: number
Focus
Focus

Description:

Internal poll timer value.

Type:
number
Default: 0
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 209)
Focus
Focus
<private> _temp: array
Focus
Focus

Description:

Used to temporarily store the results of the Hit Test

Type:
array
Default: []
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 273)
Focus
Focus
<private> _tempZones: array
Focus
Focus

Description:

Used to temporarily store the results of the Hit Test dropZones

Type:
array
Default: []
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 284)
Focus
Focus
<private> _updatedThisFrame: boolean
Focus
Focus

Description:

Internal property that tracks frame event state.

Type:
boolean
Since: 3.18.0
Source: src/input/InputPlugin.js (Line 379)
Focus
Focus
<private> _validTypes: Array.<string>
Focus
Focus

Description:

A list of valid DOM event types.

Type:
Array.<string>
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 369)
Focus
Focus
<readonly> activePointer: Phaser.Input.Pointer
Focus
Focus

Description:

The current active input Pointer.

Type:
Since: 3.0.0
Focus
Focus

Description:

A reference to the Scene Cameras Manager. This property is set during the boot method.

Type:
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 149)
Focus
Focus

Description:

A reference to the Scene Display List. This property is set during the boot method.

Type:
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 140)
Focus
Focus
dragDistanceThreshold: number
Focus
Focus

Description:

The distance, in pixels, a pointer has to move while being held down, before it thinks it is being dragged.

Type:
number
Default: 0
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 247)
Focus
Focus
dragTimeThreshold: number
Focus
Focus

Description:

The amount of time, in ms, a pointer has to be held down before it thinks it is dragging.

The default polling rate is to poll only on move so once the time threshold is reached the drag event will not start until you move the mouse. If you want it to start immediately when the time threshold is reached, you must increase the polling rate by calling setPollAlways or setPollRate.

Type:
number
Default: 0
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 257)
Focus
Focus
enabled: boolean
Focus
Focus

Description:

If true this Input Plugin will process DOM input events.

Type:
boolean
Default: true
Since: 3.5.0
Source: src/input/InputPlugin.js (Line 130)
Focus
Focus

Description:

An instance of the Gamepad Plugin class, if enabled via the input.gamepad Scene or Game Config property. Use this to create access Gamepads connected to the browser and respond to gamepad buttons.

Type:
Since: 3.10.0
Focus
Focus
<readonly> isOver: boolean
Focus
Focus

Description:

Are any mouse or touch pointers currently over the game canvas?

Type:
boolean
Since: 3.16.0
Focus
Focus

Description:

An instance of the Keyboard Plugin class, if enabled via the input.keyboard Scene or Game Config property. Use this to create Key objects and listen for keyboard specific events.

Type:
Since: 3.10.0
Focus
Focus

Description:

A reference to the Game Input Manager.

Type:
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 111)
Focus
Focus

Description:

A reference to the Mouse Manager.

This property is only set if Mouse support has been enabled in your Game Configuration file.

If you just wish to get access to the mouse pointer, use the mousePointer property instead.

Type:
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 161)
Focus
Focus
<readonly> mousePointer: Phaser.Input.Pointer
Focus
Focus

Description:

The mouse has its own unique Pointer object, which you can reference directly if making a desktop specific game. If you are supporting both desktop and touch devices then do not use this property, instead use activePointer which will always map to the most recently interacted pointer.

Type:
Since: 3.10.0
Focus
Focus
<private> pluginEvents: Phaser.Events.EventEmitter
Focus
Focus

Description:

Internal event queue used for plugins only.

Type:
Since: 3.10.0
Source: src/input/InputPlugin.js (Line 120)
Focus
Focus
<readonly> pointer1: Phaser.Input.Pointer
Focus
Focus

Description:

A touch-based Pointer object. This will be undefined by default unless you add a new Pointer using addPointer.

Type:
Since: 3.10.0
Focus
Focus
<readonly> pointer10: Phaser.Input.Pointer
Focus
Focus

Description:

A touch-based Pointer object. This will be undefined by default unless you add a new Pointer using addPointer.

Type:
Since: 3.10.0
Focus
Focus
<readonly> pointer2: Phaser.Input.Pointer
Focus
Focus

Description:

A touch-based Pointer object. This will be undefined by default unless you add a new Pointer using addPointer.

Type:
Since: 3.10.0
Focus
Focus
<readonly> pointer3: Phaser.Input.Pointer
Focus
Focus

Description:

A touch-based Pointer object. This will be undefined by default unless you add a new Pointer using addPointer.

Type:
Since: 3.10.0
Focus
Focus
<readonly> pointer4: Phaser.Input.Pointer
Focus
Focus

Description:

A touch-based Pointer object. This will be undefined by default unless you add a new Pointer using addPointer.

Type:
Since: 3.10.0
Focus
Focus
<readonly> pointer5: Phaser.Input.Pointer
Focus
Focus

Description:

A touch-based Pointer object. This will be undefined by default unless you add a new Pointer using addPointer.

Type:
Since: 3.10.0
Focus
Focus
<readonly> pointer6: Phaser.Input.Pointer
Focus
Focus

Description:

A touch-based Pointer object. This will be undefined by default unless you add a new Pointer using addPointer.

Type:
Since: 3.10.0
Focus
Focus
<readonly> pointer7: Phaser.Input.Pointer
Focus
Focus

Description:

A touch-based Pointer object. This will be undefined by default unless you add a new Pointer using addPointer.

Type:
Since: 3.10.0
Focus
Focus
<readonly> pointer8: Phaser.Input.Pointer
Focus
Focus

Description:

A touch-based Pointer object. This will be undefined by default unless you add a new Pointer using addPointer.

Type:
Since: 3.10.0
Focus
Focus
<readonly> pointer9: Phaser.Input.Pointer
Focus
Focus

Description:

A touch-based Pointer object. This will be undefined by default unless you add a new Pointer using addPointer.

Type:
Since: 3.10.0
Focus
Focus
pollRate: number
Focus
Focus

Description:

How often should the Pointers be checked?

The value is a time, given in ms, and is the time that must have elapsed between game steps before the Pointers will be polled again. When a pointer is polled it runs a hit test to see which Game Objects are currently below it, or being interacted with it.

Pointers will always be checked if they have been moved by the user, or press or released.

This property only controls how often they will be polled if they have not been updated. You should set this if you want to have Game Objects constantly check against the pointers, even if the pointer didn't itself move.

Set to 0 to poll constantly. Set to -1 to only poll on user movement.

Type:
number
Default: -1
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 187)
Focus
Focus
scene: Phaser.Scene
Focus
Focus

Description:

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

Type:
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 84)
Focus
Focus

Description:

A reference to the Scene Systems Settings.

Type:
Since: 3.5.0
Source: src/input/InputPlugin.js (Line 102)
Focus
Focus

Description:

A reference to the Scene Systems class.

Type:
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 93)
Focus
Focus
topOnly: boolean
Focus
Focus

Description:

When set to true (the default) the Input Plugin will emulate DOM behavior by only emitting events from the top-most Game Objects in the Display List.

If set to false it will emit events from all Game Objects below a Pointer, not just the top one.

Type:
boolean
Default: true
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 174)
Focus
Focus
<readonly> x: number
Focus
Focus

Description:

The x coordinates of the ActivePointer based on the first camera in the camera list. This is only safe to use if your game has just 1 non-transformed camera and doesn't use multi-touch.

Type:
number
Since: 3.0.0
Focus
Focus
<readonly> y: number
Focus
Focus

Description:

The y coordinates of the ActivePointer based on the first camera in the camera list. This is only safe to use if your game has just 1 non-transformed camera and doesn't use multi-touch.

Type:
number
Since: 3.0.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
addPointer([quantity])
Focus
Focus

Description:

Adds new Pointer objects to the Input Manager.

By default Phaser creates 2 pointer objects: mousePointer and pointer1.

You can create more either by calling this method, or by setting the input.activePointers property in the Game Config, up to a maximum of 10 pointers.

The first 10 pointers are available via the InputPlugin.pointerX properties, once they have been added via this method.

Parameters:

name type arguments Default description
quantity number <optional> 1

The number of new Pointers to create. A maximum of 10 is allowed in total.

Returns:
Description:

An array containing all of the new Pointer objects that were created.

Type:
Examples:
Since: 3.10.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.5.1
Source: src/input/InputPlugin.js (Line 393)
Focus
Focus
clear(gameObject, [skipQueue])
Focus
Focus

Description:

Clears a Game Object so it no longer has an Interactive Object associated with it. The Game Object is then queued for removal from the Input Plugin on the next update.

Parameters:

name type arguments Default description
gameObject Phaser.GameObjects.GameObject

The Game Object that will have its Interactive Object removed.

skipQueue boolean <optional> false

Skip adding this Game Object into the removal queue?

Returns:
Description:

The Game Object that had its Interactive Object removed.

Examples:
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 764)
Focus
Focus
<private> destroy()
Focus
Focus

Description:

The Scene that owns this plugin is being destroyed. We need to shutdown and then kill off all external references.

Overrides: Phaser.Events.EventEmitter#destroy
Examples:
Since: 3.0.0
Focus
Focus
disable(gameObject)
Focus
Focus

Description:

Disables Input on a single Game Object.

An input disabled Game Object still retains its Interactive Object component and can be re-enabled at any time, by passing it to InputPlugin.enable.

Parameters:

name type description
gameObject Phaser.GameObjects.GameObject

The Game Object to have its input system disabled.

Examples:
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 828)
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
enable(gameObject, [hitArea], [hitAreaCallback], [dropZone])
Focus
Focus

Description:

Enable a Game Object for interaction.

If the Game Object already has an Interactive Object component, it is enabled and returned.

Otherwise, a new Interactive Object component is created and assigned to the Game Object's input property.

Input works by using hit areas, these are nearly always geometric shapes, such as rectangles or circles, that act as the hit area for the Game Object. However, you can provide your own hit area shape and callback, should you wish to handle some more advanced input detection.

If no arguments are provided it will try and create a rectangle hit area based on the texture frame the Game Object is using. If this isn't a texture-bound object, such as a Graphics or BitmapText object, this will fail, and you'll need to provide a specific shape for it to use.

You can also provide an Input Configuration Object as the only argument to this method.

Parameters:

name type arguments Default description
gameObject Phaser.GameObjects.GameObject

The Game Object to be enabled for input.

hitArea any | Phaser.Types.Input.InputConfiguration <optional>

Either an input configuration object, or a geometric shape that defines the hit area for the Game Object. If not specified a Rectangle will be used.

hitAreaCallback Phaser.Types.Input.HitAreaCallback <optional>

The 'contains' function to invoke to check if the pointer is within the hit area.

dropZone boolean <optional> false

Is this Game Object a drop zone or not?

Returns:
Description:

This Input Plugin.

Examples:
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 844)
Focus
Focus
enableDebug(gameObject, [color])
Focus
Focus

Description:

Creates an Input Debug Shape for the given Game Object.

The Game Object must have already been enabled for input prior to calling this method.

This is intended to assist you during development and debugging.

Debug Shapes can only be created for Game Objects that are using standard Phaser Geometry for input, including: Circle, Ellipse, Line, Polygon, Rectangle and Triangle.

Game Objects that are using their automatic hit areas are using Rectangles by default, so will also work.

The Debug Shape is created and added to the display list and is then kept in sync with the Game Object it is connected with. Should you need to modify it yourself, such as to hide it, you can access it via the Game Object property: GameObject.input.hitAreaDebug.

Calling this method on a Game Object that already has a Debug Shape will first destroy the old shape, before creating a new one. If you wish to remove the Debug Shape entirely, you should call the method InputPlugin.removeDebug.

Note that the debug shape will only show the outline of the input area. If the input test is using a pixel perfect check, for example, then this is not displayed. If you are using a custom shape, that doesn't extend one of the base Phaser Geometry objects, as your hit area, then this method will not work.

Parameters:

name type arguments Default description
gameObject Phaser.GameObjects.GameObject

The Game Object to create the input debug shape for.

color number <optional> 0x00ff00

The outline color of the debug shape.

Returns:
Description:

This Input Plugin.

Examples:
Since: 3.19.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
getDragState(pointer)
Focus
Focus

Description:

Returns the drag state of the given Pointer for this Input Plugin.

The state will be one of the following:

0 = Not dragging anything 1 = Primary button down and objects below, so collect a draglist 2 = Pointer being checked if meets drag criteria 3 = Pointer meets criteria, notify the draglist 4 = Pointer actively dragging the draglist and has moved 5 = Pointer actively dragging but has been released, notify draglist

Parameters:

name type description
pointer Phaser.Input.Pointer

The Pointer to get the drag state for.

Returns:
Description:

The drag state of the given Pointer.

Type:
  • number
Examples:
Since: 3.16.0
Focus
Focus
hitTestPointer(pointer)
Focus
Focus

Description:

Takes the given Pointer and performs a hit test against it, to see which interactive Game Objects it is currently above.

The hit test is performed against which-ever Camera the Pointer is over. If it is over multiple cameras, it starts checking the camera at the top of the camera list, and if nothing is found, iterates down the list.

Parameters:

name type description
pointer Phaser.Input.Pointer

The Pointer to check against the Game Objects.

Returns:
Description:

An array of all the interactive Game Objects the Pointer was above.

Examples:
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 894)
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
Source: src/input/InputPlugin.js (Line 529)
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
makePixelPerfect([alphaTolerance])
Focus
Focus

Description:

Creates a function that can be passed to setInteractive, enable or setHitArea that will handle pixel-perfect input detection on an Image or Sprite based Game Object, or any custom class that extends them.

The following will create a sprite that is clickable on any pixel that has an alpha value >= 1.

this.add.sprite(x, y, key).setInteractive(this.input.makePixelPerfect());

The following will create a sprite that is clickable on any pixel that has an alpha value >= 150.

this.add.sprite(x, y, key).setInteractive(this.input.makePixelPerfect(150));

Once you have made an Interactive Object pixel perfect it impacts all input related events for it: down, up, dragstart, drag, etc.

As a pointer interacts with the Game Object it will constantly poll the texture, extracting a single pixel from the given coordinates and checking its color values. This is an expensive process, so should only be enabled on Game Objects that really need it.

You cannot make non-texture based Game Objects pixel perfect. So this will not work on Graphics, BitmapText, Render Textures, Text, Tilemaps, Containers or Particles.

Parameters:

name type arguments Default description
alphaTolerance number <optional> 1

The alpha level that the pixel should be above to be included as a successful interaction.

Returns:
Description:

A Pixel Perfect Handler for use as a hitArea shape callback.

Type:
  • function
Examples:
Since: 3.10.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
<private> onGameOut()
Focus
Focus

Description:

Game Out handler.

Examples:
Since: 3.16.2
Source: src/input/InputPlugin.js (Line 462)
Focus
Focus
<private> onGameOver()
Focus
Focus

Description:

Game Over handler.

Examples:
Since: 3.16.2
Source: src/input/InputPlugin.js (Line 446)
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> preUpdate()
Focus
Focus

Description:

The pre-update handler is responsible for checking the pending removal and insertion lists and deleting old Game Objects.

Examples:
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 478)
Focus
Focus
<private> processDownEvents(pointer)
Focus
Focus

Description:

An internal method that handles the Pointer down event.

Parameters:

name type description
pointer Phaser.Input.Pointer

The Pointer being tested.

Returns:
Description:

The total number of objects interacted with.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 947)
Focus
Focus
<private> processDragDownEvent(pointer)
Focus
Focus

Description:

Processes a 'drag down' event for the given pointer. Checks the pointer state, builds-up the drag list and prepares them all for interaction.

Parameters:

name type description
pointer Phaser.Input.Pointer

The Pointer to process the drag event on.

Returns:
Description:

The number of items that were collected on the drag list.

Type:
  • number
Examples:
Since: 3.18.0
Focus
Focus
<private> processDragMoveEvent(pointer)
Focus
Focus

Description:

Processes a 'drag move' event for the given pointer.

Parameters:

name type description
pointer Phaser.Input.Pointer

The Pointer to process the drag event on.

Returns:
Description:

The number of items that were updated by this drag event.

Type:
  • number
Examples:
Since: 3.18.0
Focus
Focus
<private> processDragStartList(pointer)
Focus
Focus

Description:

Processes the drag list for the given pointer and dispatches the start events for each object on it.

Parameters:

name type description
pointer Phaser.Input.Pointer

The Pointer to process the drag event on.

Returns:
Description:

The number of items that DRAG_START was called on.

Type:
  • number
Examples:
Since: 3.18.0
Focus
Focus
<private> processDragThresholdEvent(pointer, time)
Focus
Focus

Description:

Checks to see if a Pointer is ready to drag the objects below it, based on either a distance or time threshold.

Parameters:

name type description
pointer Phaser.Input.Pointer

The Pointer to check the drag thresholds on.

time number

The current time.

Examples:
Since: 3.18.0
Focus
Focus
<private> processDragUpEvent(pointer)
Focus
Focus

Description:

Processes a 'drag down' event for the given pointer. Checks the pointer state, builds-up the drag list and prepares them all for interaction.

Parameters:

name type description
pointer Phaser.Input.Pointer

The Pointer to process the drag event on.

Returns:
Description:

The number of items that were updated by this drag event.

Type:
  • number
Examples:
Since: 3.18.0
Focus
Focus
<private> processMoveEvents(pointer)
Focus
Focus

Description:

An internal method that handles the Pointer movement event.

Parameters:

name type description
pointer Phaser.Input.Pointer

The pointer to check for events against.

Returns:
Description:

The total number of objects interacted with.

Type:
  • number
Examples:
Since: 3.0.0
Focus
Focus
<private> processOutEvents(pointer)
Focus
Focus

Description:

An internal method that handles the Pointer out events. This is called when a touch input leaves the canvas, as it can never be 'over' in this case.

Parameters:

name type description
pointer Phaser.Input.Pointer

The pointer to check for events against.

Returns:
Description:

The total number of objects interacted with.

Type:
  • number
Examples:
Since: 3.18.0
Focus
Focus
<private> processOverEvents(pointer)
Focus
Focus

Description:

An internal method that handles the Pointer over events. This is called when a touch input hits the canvas, having previously been off of it.

Parameters:

name type description
pointer Phaser.Input.Pointer

The pointer to check for events against.

Returns:
Description:

The total number of objects interacted with.

Type:
  • number
Examples:
Since: 3.18.0
Focus
Focus
<private> processOverOutEvents(pointer)
Focus
Focus

Description:

An internal method that handles the Pointer over and out events.

Parameters:

name type description
pointer Phaser.Input.Pointer

The pointer to check for events against.

Returns:
Description:

The total number of objects interacted with.

Type:
  • number
Examples:
Since: 3.0.0
Focus
Focus
<private> processUpEvents(pointer)
Focus
Focus

Description:

An internal method that handles the Pointer up events.

Parameters:

name type description
pointer Phaser.Input.Pointer

The pointer to check for events against.

Returns:
Description:

The total number of objects interacted with.

Type:
  • number
Examples:
Since: 3.0.0
Focus
Focus
<private> processWheelEvent(pointer)
Focus
Focus

Description:

An internal method that handles a mouse wheel event.

Parameters:

name type description
pointer Phaser.Input.Pointer

The pointer to check for events against.

Returns:
Description:

The total number of objects interacted with.

Type:
  • number
Examples:
Since: 3.18.0
Focus
Focus
<private> queueForInsertion(child)
Focus
Focus

Description:

Queues a Game Object for insertion into this Input Plugin on the next update.

Parameters:

name type description
child Phaser.GameObjects.GameObject

The Game Object to add.

Returns:
Description:

This InputPlugin object.

Examples:
Since: 3.0.0
Focus
Focus
<private> queueForRemoval(child)
Focus
Focus

Description:

Queues a Game Object for removal from this Input Plugin on the next update.

Parameters:

name type description
child Phaser.GameObjects.GameObject

The Game Object to remove.

Returns:
Description:

This InputPlugin object.

Examples:
Since: 3.0.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
removeDebug(gameObject)
Focus
Focus

Description:

Removes an Input Debug Shape from the given Game Object.

The shape is destroyed immediately and the hitAreaDebug property is set to null.

Parameters:

name type description
gameObject Phaser.GameObjects.GameObject

The Game Object to remove the input debug shape from.

Returns:
Description:

This Input Plugin.

Examples:
Since: 3.19.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
setDefaultCursor(cursor)
Focus
Focus

Description:

Tells the Input system to set a custom cursor.

This cursor will be the default cursor used when interacting with the game canvas.

If an Interactive Object also sets a custom cursor, this is the cursor that is reset after its use.

Any valid CSS cursor value is allowed, including paths to image files, i.e.:

this.input.setDefaultCursor('url(assets/cursors/sword.cur), pointer');

Please read about the differences between browsers when it comes to the file formats and sizes they support:

https://developer.mozilla.org/en-US/docs/Web/CSS/cursor https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_User_Interface/Using_URL_values_for_the_cursor_property

It's up to you to pick a suitable cursor format that works across the range of browsers you need to support.

Parameters:

name type description
cursor string

The CSS to be used when setting the default cursor.

Returns:
Description:

This Input instance.

Examples:
Since: 3.10.0
Focus
Focus
setDragState(pointer, state)
Focus
Focus

Description:

Sets the drag state of the given Pointer for this Input Plugin.

The state must be one of the following values:

0 = Not dragging anything 1 = Primary button down and objects below, so collect a draglist 2 = Pointer being checked if meets drag criteria 3 = Pointer meets criteria, notify the draglist 4 = Pointer actively dragging the draglist and has moved 5 = Pointer actively dragging but has been released, notify draglist

Parameters:

name type description
pointer Phaser.Input.Pointer

The Pointer to set the drag state for.

state number

The drag state value. An integer between 0 and 5.

Examples:
Since: 3.16.0
Focus
Focus
setDraggable(gameObjects, [value])
Focus
Focus

Description:

Sets the draggable state of the given array of Game Objects.

They can either be set to be draggable, or can have their draggable state removed by passing false.

A Game Object will not fire drag events unless it has been specifically enabled for drag.

Parameters:

name type arguments Default description
gameObjects Phaser.GameObjects.GameObject | Array.<Phaser.GameObjects.GameObject>

An array of Game Objects to change the draggable state on.

value boolean <optional> true

Set to true if the Game Objects should be made draggable, false if they should be unset.

Returns:
Description:

This InputPlugin object.

Examples:
Since: 3.0.0
Focus
Focus
setGlobalTopOnly(value)
Focus
Focus

Description:

When set to true the global Input Manager will emulate DOM behavior by only emitting events from the top-most Scene in the Scene List. By default, if a Scene receives an input event it will then stop the event from flowing down to any Scenes below it in the Scene list. To disable this behavior call this method with false.

Parameters:

name type description
value boolean

Set to true to stop processing input events on the Scene that receives it, or false to let the event continue down the Scene list.

Returns:
Description:

This InputPlugin object.

Examples:
Since: 3.0.0
Focus
Focus
setHitArea(gameObjects, [hitArea], [hitAreaCallback])
Focus
Focus

Description:

Sets the hit area for the given array of Game Objects.

A hit area is typically one of the geometric shapes Phaser provides, such as a Phaser.Geom.Rectangle or Phaser.Geom.Circle. However, it can be any object as long as it works with the provided callback.

If no hit area is provided a Rectangle is created based on the size of the Game Object, if possible to calculate.

The hit area callback is the function that takes an x and y coordinate and returns a boolean if those values fall within the area of the shape or not. All of the Phaser geometry objects provide this, such as Phaser.Geom.Rectangle.Contains.

Parameters:

name type arguments description
gameObjects Phaser.GameObjects.GameObject | Array.<Phaser.GameObjects.GameObject>

An array of Game Objects to set the hit area on.

hitArea any | Phaser.Types.Input.InputConfiguration <optional>

Either an input configuration object, or a geometric shape that defines the hit area for the Game Object. If not specified a Rectangle will be used.

hitAreaCallback Phaser.Types.Input.HitAreaCallback <optional>

The 'contains' function to invoke to check if the pointer is within the hit area.

Returns:
Description:

This InputPlugin object.

Examples:
Since: 3.0.0
Focus
Focus
setHitAreaCircle(gameObjects, x, y, radius, [callback])
Focus
Focus

Description:

Sets the hit area for an array of Game Objects to be a Phaser.Geom.Circle shape, using the given coordinates and radius to control its position and size.

Parameters:

name type arguments description
gameObjects Phaser.GameObjects.GameObject | Array.<Phaser.GameObjects.GameObject>

An array of Game Objects to set as having a circle hit area.

x number

The center of the circle.

y number

The center of the circle.

radius number

The radius of the circle.

callback Phaser.Types.Input.HitAreaCallback <optional>

The hit area callback. If undefined it uses Circle.Contains.

Returns:
Description:

This InputPlugin object.

Examples:
Since: 3.0.0
Focus
Focus
setHitAreaEllipse(gameObjects, x, y, width, height, [callback])
Focus
Focus

Description:

Sets the hit area for an array of Game Objects to be a Phaser.Geom.Ellipse shape, using the given coordinates and dimensions to control its position and size.

Parameters:

name type arguments description
gameObjects Phaser.GameObjects.GameObject | Array.<Phaser.GameObjects.GameObject>

An array of Game Objects to set as having an ellipse hit area.

x number

The center of the ellipse.

y number

The center of the ellipse.

width number

The width of the ellipse.

height number

The height of the ellipse.

callback Phaser.Types.Input.HitAreaCallback <optional>

The hit area callback. If undefined it uses Ellipse.Contains.

Returns:
Description:

This InputPlugin object.

Examples:
Since: 3.0.0
Focus
Focus
setHitAreaFromTexture(gameObjects, [callback])
Focus
Focus

Description:

Sets the hit area for an array of Game Objects to be a Phaser.Geom.Rectangle shape, using the Game Objects texture frame to define the position and size of the hit area.

Parameters:

name type arguments description
gameObjects Phaser.GameObjects.GameObject | Array.<Phaser.GameObjects.GameObject>

An array of Game Objects to set as having an ellipse hit area.

callback Phaser.Types.Input.HitAreaCallback <optional>

The hit area callback. If undefined it uses Rectangle.Contains.

Returns:
Description:

This InputPlugin object.

Examples:
Since: 3.0.0
Focus
Focus
setHitAreaRectangle(gameObjects, x, y, width, height, [callback])
Focus
Focus

Description:

Sets the hit area for an array of Game Objects to be a Phaser.Geom.Rectangle shape, using the given coordinates and dimensions to control its position and size.

Parameters:

name type arguments description
gameObjects Phaser.GameObjects.GameObject | Array.<Phaser.GameObjects.GameObject>

An array of Game Objects to set as having a rectangular hit area.

x number

The top-left of the rectangle.

y number

The top-left of the rectangle.

width number

The width of the rectangle.

height number

The height of the rectangle.

callback Phaser.Types.Input.HitAreaCallback <optional>

The hit area callback. If undefined it uses Rectangle.Contains.

Returns:
Description:

This InputPlugin object.

Examples:
Since: 3.0.0
Focus
Focus
setHitAreaTriangle(gameObjects, x1, y1, x2, y2, x3, y3, [callback])
Focus
Focus

Description:

Sets the hit area for an array of Game Objects to be a Phaser.Geom.Triangle shape, using the given coordinates to control the position of its points.

Parameters:

name type arguments description
gameObjects Phaser.GameObjects.GameObject | Array.<Phaser.GameObjects.GameObject>

An array of Game Objects to set as having a triangular hit area.

x1 number

The x coordinate of the first point of the triangle.

y1 number

The y coordinate of the first point of the triangle.

x2 number

The x coordinate of the second point of the triangle.

y2 number

The y coordinate of the second point of the triangle.

x3 number

The x coordinate of the third point of the triangle.

y3 number

The y coordinate of the third point of the triangle.

callback Phaser.Types.Input.HitAreaCallback <optional>

The hit area callback. If undefined it uses Triangle.Contains.

Returns:
Description:

This InputPlugin object.

Examples:
Since: 3.0.0
Focus
Focus
setPollAlways()
Focus
Focus

Description:

Sets the Pointers to always poll.

When a pointer is polled it runs a hit test to see which Game Objects are currently below it, or being interacted with it, regardless if the Pointer has actually moved or not.

You should enable this if you want objects in your game to fire over / out events, and the objects are constantly moving, but the pointer may not have. Polling every frame has additional computation costs, especially if there are a large number of interactive objects in your game.

Returns:
Description:

This InputPlugin object.

Examples:
Since: 3.0.0
Focus
Focus
setPollOnMove()
Focus
Focus

Description:

Sets the Pointers to only poll when they are moved or updated.

When a pointer is polled it runs a hit test to see which Game Objects are currently below it, or being interacted with it.

Returns:
Description:

This InputPlugin object.

Examples:
Since: 3.0.0
Focus
Focus
setPollRate(value)
Focus
Focus

Description:

Sets the poll rate value. This is the amount of time that should have elapsed before a pointer will be polled again. See the setPollAlways and setPollOnMove methods.

Parameters:

name type description
value number

The amount of time, in ms, that should elapsed before re-polling the pointers.

Returns:
Description:

This InputPlugin object.

Examples:
Since: 3.0.0
Focus
Focus
setTopOnly(value)
Focus
Focus

Description:

When set to true this Input Plugin will emulate DOM behavior by only emitting events from the top-most Game Objects in the Display List.

If set to false it will emit events from all Game Objects below a Pointer, not just the top one.

Parameters:

name type description
value boolean

true to only include the top-most Game Object, or false to include all Game Objects in a hit test.

Returns:
Description:

This InputPlugin object.

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

Description:

The Scene that owns this plugin is shutting down. We need to kill and reset all internal properties as well as stop listening to Scene events.

Overrides: Phaser.Events.EventEmitter#shutdown
Examples:
Since: 3.0.0
Focus
Focus
<private> sortDropZoneHandler(childA, childB)
Focus
Focus

Description:

Return the child lowest down the display list (with the smallest index) Will iterate through all parent containers, if present.

Prior to version 3.52.0 this method was called sortHandlerGO.

Parameters:

name type description
childA Phaser.GameObjects.GameObject

The first Game Object to compare.

childB Phaser.GameObjects.GameObject

The second Game Object to compare.

Returns:
Description:

Returns either a negative or positive integer, or zero if they match.

Type:
  • number
Examples:
Since: 3.52.0
Focus
Focus
sortDropZones(gameObjects)
Focus
Focus

Description:

Given an array of Drop Zone Game Objects, sort the array and return it, so that the objects are in depth index order with the lowest at the bottom.

Parameters:

name type description
gameObjects Array.<Phaser.GameObjects.GameObject>

An array of Game Objects to be sorted.

Returns:
Description:

The sorted array of Game Objects.

Examples:
Since: 3.52.0
Focus
Focus
sortGameObjects(gameObjects, pointer)
Focus
Focus

Description:

Given an array of Game Objects and a Pointer, sort the array and return it, so that the objects are in render order with the lowest at the bottom.

Parameters:

name type description
gameObjects Array.<Phaser.GameObjects.GameObject>

An array of Game Objects to be sorted.

pointer Phaser.Input.Pointer

The Pointer to check against the Game Objects.

Returns:
Description:

The sorted array of Game Objects.

Examples:
Since: 3.0.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.5.0
Source: src/input/InputPlugin.js (Line 414)
Focus
Focus
stopPropagation()
Focus
Focus

Description:

This method should be called from within an input event handler, such as pointerdown.

When called, it stops the Input Manager from allowing this specific event to be processed by any other Scene not yet handled in the scene list.

Returns:
Description:

This InputPlugin object.

Examples:
Since: 3.0.0
Focus
Focus
<private> transitionComplete()
Focus
Focus

Description:

The Scene that owns this plugin has finished transitioning in.

Examples:
Since: 3.5.0
Focus
Focus
<private> transitionIn()
Focus
Focus

Description:

The Scene that owns this plugin is transitioning in.

Examples:
Since: 3.5.0
Focus
Focus
<private> transitionOut()
Focus
Focus

Description:

The Scene that owns this plugin is transitioning out.

Examples:
Since: 3.5.0
Focus
Focus
<private> update(type, pointers)
Focus
Focus

Description:

This method is called when a DOM Event is received by the Input Manager. It handles dispatching the events to relevant input enabled Game Objects in this scene.

Parameters:

name type description
type number

The type of event to process.

pointers Array.<Phaser.Input.Pointer>

An array of Pointers on which the event occurred.

Returns:
Description:

true if this Scene has captured the input events from all other Scenes, otherwise false.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/input/InputPlugin.js (Line 661)
Focus
Focus
updatePoll(time, delta)
Focus
Focus

Description:

This is called automatically by the Input Manager. It emits events for plugins to listen to and also handles polling updates, if enabled.

Parameters:

name type description
time number

The current time. Either a High Resolution Timer value if it comes from Request Animation Frame, or Date.now if using SetTimeout.

delta number

The delta time in ms since the last frame. This is a smoothed and capped value based on the FPS rate.

Returns:
Description:

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

Type:
  • boolean
Examples:
Since: 3.18.0
Source: src/input/InputPlugin.js (Line 542)
Focus
Focus