Class: InputManager

Phaser.Input. InputManager

The Input Manager is responsible for handling the pointer related systems in a single Phaser Game instance.

Based on the Game Config it will create handlers for mouse and touch support.

Keyboard and Gamepad are plugins, handled directly by the InputPlugin class.

It then manages the event queue, pointer creation and general hit test related operations.

You rarely need to interact with the Input Manager directly, and as such, all of its properties and methods
should be considered private. Instead, you should use the Input Plugin, which is a Scene level system, responsible
for dealing with all input events for a Scene.


new InputManager(game, config)

Parameters:
Name Type Description
game Phaser.Game

The Game instance that owns the Input Manager.

config object

The Input Configuration object, as set in the Game Config.

Since: 3.0.0
Source: src/input/InputManager.js (Line 17)

Members


activePointer :Phaser.Input.Pointer

The most recently active Pointer object.

If you've only 1 Pointer in your game then this will accurately be either the first finger touched, or the mouse.

If your game doesn't need to support multi-touch then you can safely use this property in all of your game
code and it will adapt to be either the mouse or the touch, based on device.

Type:
Since: 3.0.0
Source: src/input/InputManager.js (Line 243)

bounds :Phaser.Geom.Rectangle

The bounds of the Input Manager, used for pointer hit test calculations.

Type:
Since: 3.0.0
Source: src/input/InputManager.js (Line 299)

canvas :HTMLCanvasElement

The Canvas that is used for all DOM event input listeners.

Type:
  • HTMLCanvasElement
Since: 3.0.0
Source: src/input/InputManager.js (Line 56)

config :object

The Input Configuration object, as set in the Game Config.

Type:
  • object
Since: 3.0.0
Source: src/input/InputManager.js (Line 65)

defaultCursor :string

The default CSS cursor to be used when interacting with your game.

See the setDefaultCursor method for more details.

Type:
  • string
Since: 3.10.0
Source: src/input/InputManager.js (Line 167)

dirty :boolean

Reset every frame. Set to true if any of the Pointers are dirty this frame.

Type:
  • boolean
Since: 3.10.0
Source: src/input/InputManager.js (Line 257)

enabled :boolean

If set, the Input Manager will run its update loop every frame.

Type:
  • boolean
Since: 3.0.0
Default Value:
  • true
Source: src/input/InputManager.js (Line 74)

events :Phaser.Events.EventEmitter

The Event Emitter instance that the Input Manager uses to emit events from.

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

<readonly> game :Phaser.Game

The Game instance that owns the Input Manager.
A Game only maintains on instance of the Input Manager at any time.

Type:
Since: 3.0.0
Source: src/input/InputManager.js (Line 45)

globalTopOnly :boolean

If the top-most Scene in the Scene List receives an input it will stop input from
propagating any lower down the scene list, i.e. if you have a UI Scene at the top
and click something on it, that click will not then be passed down to any other
Scene below. Disable this to have input events passed through all Scenes, all the time.

Type:
  • boolean
Since: 3.0.0
Default Value:
  • true
Source: src/input/InputManager.js (Line 275)

ignoreEvents :boolean

An internal flag that controls if the Input Manager will ignore or process native DOM events this frame.
Set via the InputPlugin.stopPropagation method.

Type:
  • boolean
Since: 3.0.0
Default Value:
  • false
Source: src/input/InputManager.js (Line 288)

<nullable> mouse :Phaser.Input.Mouse.MouseManager

A reference to the Mouse Manager class, if enabled via the input.mouse Game Config property.

Type:
Since: 3.0.0
Source: src/input/InputManager.js (Line 178)

<nullable> mousePointer :Phaser.Input.Pointer

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
Source: src/input/InputManager.js (Line 232)

pointers :Array.<Phaser.Input.Pointer>

An array of Pointers that have been added to the game.
The first entry is reserved for the Mouse Pointer, the rest are Touch Pointers.

By default there is 1 touch pointer enabled. If you need more use the addPointer method to start them,
or set the input.activePointers property in the Game Config.

Type:
Since: 3.10.0
Source: src/input/InputManager.js (Line 196)

<readonly> pointersTotal :integer

The number of touch objects activated and being processed each update.

You can change this by either calling addPointer at run-time, or by
setting the input.activePointers property in the Game Config.

Type:
  • integer
Since: 3.10.0
Source: src/input/InputManager.js (Line 209)

queue :array

A standard FIFO queue for the native DOM events waiting to be handled by the Input Manager.

Type:
  • array
Since: 3.0.0
Default Value:
  • []
Source: src/input/InputManager.js (Line 93)

scale :Object

The Scale factor being applied to input coordinates.

Type:
  • Object
Since: 3.0.0
Source: src/input/InputManager.js (Line 266)

touch :Phaser.Input.Touch.TouchManager

A reference to the Touch Manager class, if enabled via the input.touch Game Config property.

Type:
Since: 3.0.0
Source: src/input/InputManager.js (Line 187)

Methods


addDownCallback(callback [, isOnce])

Adds a callback to be invoked whenever the native DOM mousedown or touchstart events are received.
By setting the isOnce argument you can control if the callback is called once,
or every time the DOM event occurs.

Callbacks passed to this method are invoked immediately when the DOM event happens,
within the scope of the DOM event handler. Therefore, they are considered as 'native'
from the perspective of the browser. This means they can be used for tasks such as
opening new browser windows, or anything which explicitly requires user input to activate.
However, as a result of this, they come with their own risks, and as such should not be used
for general game input, but instead be reserved for special circumstances.

If all you're trying to do is execute a callback when a pointer is down, then
please use the internal Input event system instead.

Please understand that these callbacks are invoked when the browser feels like doing so,
which may be entirely out of the normal flow of the Phaser Game Loop. Therefore, you should absolutely keep
Phaser related operations to a minimum in these callbacks. For example, don't destroy Game Objects,
change Scenes or manipulate internal systems, otherwise you run a very real risk of creating
heisenbugs (https://en.wikipedia.org/wiki/Heisenbug) that prove a challenge to reproduce, never mind
solve.

Parameters:
Name Type Argument Default Description
callback function

The callback to be invoked on this dom event.

isOnce boolean <optional>
true

true if the callback will only be invoked once, false to call every time this event happens.

Since: 3.10.0
Source: src/input/InputManager.js (Line 1008)
Returns:

The Input Manager.

Type
Phaser.Input.InputManager

addMoveCallback(callback [, isOnce])

Adds a callback to be invoked whenever the native DOM mousemove or touchmove events are received.
By setting the isOnce argument you can control if the callback is called once,
or every time the DOM event occurs.

Callbacks passed to this method are invoked immediately when the DOM event happens,
within the scope of the DOM event handler. Therefore, they are considered as 'native'
from the perspective of the browser. This means they can be used for tasks such as
opening new browser windows, or anything which explicitly requires user input to activate.
However, as a result of this, they come with their own risks, and as such should not be used
for general game input, but instead be reserved for special circumstances.

If all you're trying to do is execute a callback when a pointer is moved, then
please use the internal Input event system instead.

Please understand that these callbacks are invoked when the browser feels like doing so,
which may be entirely out of the normal flow of the Phaser Game Loop. Therefore, you should absolutely keep
Phaser related operations to a minimum in these callbacks. For example, don't destroy Game Objects,
change Scenes or manipulate internal systems, otherwise you run a very real risk of creating
heisenbugs (https://en.wikipedia.org/wiki/Heisenbug) that prove a challenge to reproduce, never mind
solve.

Parameters:
Name Type Argument Default Description
callback function

The callback to be invoked on this dom event.

isOnce boolean <optional>
false

true if the callback will only be invoked once, false to call every time this event happens.

Since: 3.10.0
Source: src/input/InputManager.js (Line 1056)
Returns:

The Input Manager.

Type
Phaser.Input.InputManager

addPointer( [quantity])

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 Argument Default Description
quantity integer <optional>
1

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

Since: 3.10.0
Source: src/input/InputManager.js (Line 736)
Returns:

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

Type
Array.<Phaser.Input.Pointer>

addUpCallback(callback [, isOnce])

Adds a callback to be invoked whenever the native DOM mouseup or touchend events are received.
By setting the isOnce argument you can control if the callback is called once,
or every time the DOM event occurs.

Callbacks passed to this method are invoked immediately when the DOM event happens,
within the scope of the DOM event handler. Therefore, they are considered as 'native'
from the perspective of the browser. This means they can be used for tasks such as
opening new browser windows, or anything which explicitly requires user input to activate.
However, as a result of this, they come with their own risks, and as such should not be used
for general game input, but instead be reserved for special circumstances.

If all you're trying to do is execute a callback when a pointer is released, then
please use the internal Input event system instead.

Please understand that these callbacks are invoked when the browser feels like doing so,
which may be entirely out of the normal flow of the Phaser Game Loop. Therefore, you should absolutely keep
Phaser related operations to a minimum in these callbacks. For example, don't destroy Game Objects,
change Scenes or manipulate internal systems, otherwise you run a very real risk of creating
heisenbugs (https://en.wikipedia.org/wiki/Heisenbug) that prove a challenge to reproduce, never mind
solve.

Parameters:
Name Type Argument Default Description
callback function

The callback to be invoked on this dom event.

isOnce boolean <optional>
true

true if the callback will only be invoked once, false to call every time this event happens.

Since: 3.10.0
Source: src/input/InputManager.js (Line 960)
Returns:

The Input Manager.

Type
Phaser.Input.InputManager

<protected> boot()

The Boot handler is called by Phaser.Game when it first starts up.
The renderer is available by now.

Since: 3.0.0
Source: src/input/InputManager.js (Line 352)

destroy()

Destroys the Input Manager and all of its systems.

There is no way to recover from doing this.

Since: 3.0.0
Source: src/input/InputManager.js (Line 1406)

getOffsetX()

Returns the left offset of the Input bounds.

Since: 3.0.0
Source: src/input/InputManager.js (Line 1354)
Returns:

The left bounds value.

Type
number

getOffsetY()

Returns the top offset of the Input bounds.

Since: 3.0.0
Source: src/input/InputManager.js (Line 1367)
Returns:

The top bounds value.

Type
number

getScaleX()

Returns the horizontal Input Scale value.

Since: 3.0.0
Source: src/input/InputManager.js (Line 1380)
Returns:

The horizontal scale factor of the input.

Type
number

getScaleY()

Returns the vertical Input Scale value.

Since: 3.0.0
Source: src/input/InputManager.js (Line 1393)
Returns:

The vertical scale factor of the input.

Type
number

hitTest(pointer, gameObjects, camera [, output])

Performs a hit test using the given Pointer and camera, against an array of interactive Game Objects.

The Game Objects are culled against the camera, and then the coordinates are translated into the local camera space
and used to determine if they fall within the remaining Game Objects hit areas or not.

If nothing is matched an empty array is returned.

This method is called automatically by InputPlugin.hitTestPointer and doesn't usually need to be invoked directly.

Parameters:
Name Type Argument Description
pointer Phaser.Input.Pointer

The Pointer to test against.

gameObjects array

An array of interactive Game Objects to check.

camera Phaser.Cameras.Scene2D.Camera

The Camera which is being tested against.

output array <optional>

An array to store the results in. If not given, a new empty array is created.

Since: 3.0.0
Source: src/input/InputManager.js (Line 1149)
Returns:

An array of the Game Objects that were hit during this hit test.

Type
array

pointWithinHitArea(gameObject, x, y)

Checks if the given x and y coordinate are within the hit area of the Game Object.

This method assumes that the coordinate values have already been translated into the space of the Game Object.

If the coordinates are within the hit area they are set into the Game Objects Input localX and localY properties.

Parameters:
Name Type Description
gameObject Phaser.GameObjects.GameObject

The interactive Game Object to check against.

x number

The translated x coordinate for the hit test.

y number

The translated y coordinate for the hit test.

Since: 3.0.0
Source: src/input/InputManager.js (Line 1234)
Returns:

true if the coordinates were inside the Game Objects hit area, otherwise false.

Type
boolean

pointWithinInteractiveObject(object, x, y)

Checks if the given x and y coordinate are within the hit area of the Interactive Object.

This method assumes that the coordinate values have already been translated into the space of the Interactive Object.

If the coordinates are within the hit area they are set into the Interactive Objects Input localX and localY properties.

Parameters:
Name Type Description
object Phaser.Input.InteractiveObject

The Interactive Object to check against.

x number

The translated x coordinate for the hit test.

y number

The translated y coordinate for the hit test.

Since: 3.0.0
Source: src/input/InputManager.js (Line 1271)
Returns:

true if the coordinates were inside the Game Objects hit area, otherwise false.

Type
boolean

resize()

Resizes the Input Manager internal values, including the bounds and scale factor.

Since: 3.2.0
Source: src/input/InputManager.js (Line 392)

setDefaultCursor(cursor)

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.

Since: 3.10.0
Source: src/input/InputManager.js (Line 526)

transformPointer(pointer, pageX, pageY)

Transforms the pageX and pageY values of a Pointer into the scaled coordinate space of the Input Manager.

Parameters:
Name Type Description
pointer Phaser.Input.Pointer

The Pointer to transform the values for.

pageX number

The Page X value.

pageY number

The Page Y value.

Since: 3.10.0
Source: src/input/InputManager.js (Line 1304)

transformX(pageX)

Transforms the pageX value into the scaled coordinate space of the Input Manager.

Parameters:
Name Type Description
pageX number

The DOM pageX value.

Since: 3.0.0
Source: src/input/InputManager.js (Line 1324)
Returns:

The translated value.

Type
number

transformY(pageY)

Transforms the pageY value into the scaled coordinate space of the Input Manager.

Parameters:
Name Type Description
pageY number

The DOM pageY value.

Since: 3.0.0
Source: src/input/InputManager.js (Line 1339)
Returns:

The translated value.

Type
number

updateBounds()

Updates the Input Manager bounds rectangle to match the bounding client rectangle of the
canvas element being used to track input events.

Since: 3.0.0
Source: src/input/InputManager.js (Line 373)