Class: InputPlugin

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

Please see the Input examples and tutorials for more information.


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

Extends

Members


<readonly> activePointer :Phaser.Input.Pointer

The current active input Pointer.

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

cameras :Phaser.Cameras.Scene2D.CameraManager

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

displayList :Phaser.GameObjects.DisplayList

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

dragDistanceThreshold :number

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

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/input/InputPlugin.js (Line 233)

dragTimeThreshold :number

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

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/input/InputPlugin.js (Line 243)

enabled :boolean

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

Type:
  • boolean
Since: 3.5.0
Default Value:
  • true
Source: src/input/InputPlugin.js (Line 116)

<nullable> gamepad :Phaser.Input.Gamepad.GamepadPlugin

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
Source: src/input/gamepad/GamepadPlugin.js (Line 624)

<readonly> isOver :boolean

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

Type:
  • boolean
Since: 3.16.0
Source: src/input/InputPlugin.js (Line 2503)

<nullable> keyboard :Phaser.Input.Keyboard.KeyboardPlugin

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

manager :Phaser.Input.InputManager

A reference to the Game Input Manager.

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

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

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

<readonly> 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/InputPlugin.js (Line 2520)

<readonly> pointer1 :Phaser.Input.Pointer

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

Type:
Since: 3.10.0
Source: src/input/InputPlugin.js (Line 2556)

<readonly> pointer2 :Phaser.Input.Pointer

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

Type:
Since: 3.10.0
Source: src/input/InputPlugin.js (Line 2574)

<readonly> pointer3 :Phaser.Input.Pointer

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

Type:
Since: 3.10.0
Source: src/input/InputPlugin.js (Line 2592)

<readonly> pointer4 :Phaser.Input.Pointer

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

Type:
Since: 3.10.0
Source: src/input/InputPlugin.js (Line 2610)

<readonly> pointer5 :Phaser.Input.Pointer

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

Type:
Since: 3.10.0
Source: src/input/InputPlugin.js (Line 2628)

<readonly> pointer6 :Phaser.Input.Pointer

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

Type:
Since: 3.10.0
Source: src/input/InputPlugin.js (Line 2646)

<readonly> pointer7 :Phaser.Input.Pointer

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

Type:
Since: 3.10.0
Source: src/input/InputPlugin.js (Line 2664)

<readonly> pointer8 :Phaser.Input.Pointer

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

Type:
Since: 3.10.0
Source: src/input/InputPlugin.js (Line 2682)

<readonly> pointer9 :Phaser.Input.Pointer

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

Type:
Since: 3.10.0
Source: src/input/InputPlugin.js (Line 2700)

<readonly> pointer10 :Phaser.Input.Pointer

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

Type:
Since: 3.10.0
Source: src/input/InputPlugin.js (Line 2718)

pollRate :integer

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

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

Type:
  • integer
Since: 3.0.0
Default Value:
  • -1
Source: src/input/InputPlugin.js (Line 173)

scene :Phaser.Scene

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

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

settings :Phaser.Types.Scenes.SettingsObject

A reference to the Scene Systems Settings.

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

systems :Phaser.Scenes.Systems

A reference to the Scene Systems class.

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

topOnly :boolean

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
Since: 3.0.0
Default Value:
  • true
Source: src/input/InputPlugin.js (Line 160)

<readonly> x :number

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

<readonly> y :number

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

Methods


addDownCallback(callback [, isOnce])

Note: As of Phaser 3.16 this method is no longer required unless you have set input.queue = true in your game config, to force it to use the legacy event queue system. This method is deprecated and will be removed in a future version.

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
Deprecated:
  • Yes
Source: src/input/InputPlugin.js (Line 2212)
Returns:

The Input Plugin.

Type
Phaser.Input.InputPlugin

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

addMoveCallback(callback [, isOnce])

Note: As of Phaser 3.16 this method is no longer required unless you have set input.queue = true in your game config, to force it to use the legacy event queue system. This method is deprecated and will be removed in a future version.

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
Deprecated:
  • Yes
Source: src/input/InputPlugin.js (Line 2254)
Returns:

The Input Plugin.

Type
Phaser.Input.InputPlugin

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/InputPlugin.js (Line 2296)
Returns:

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

Type
Array.<Phaser.Input.Pointer>

addUpCallback(callback [, isOnce])

Note: As of Phaser 3.16 this method is no longer required unless you have set input.queue = true in your game config, to force it to use the legacy event queue system. This method is deprecated and will be removed in a future version.

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
Deprecated:
  • Yes
Source: src/input/InputPlugin.js (Line 2170)
Returns:

The Input Plugin.

Type
Phaser.Input.InputPlugin

clear(gameObject [, skipQueue])

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 Argument 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?

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

The Game Object that had its Interactive Object removed.

Type
Phaser.GameObjects.GameObject

disable(gameObject)

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.

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

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

enable(gameObject [, shape] [, callback] [, dropZone])

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 Argument Default Description
gameObject Phaser.GameObjects.GameObject

The Game Object to be enabled for input.

shape Phaser.Types.Input.InputConfiguration | any <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.

callback 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?

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

This Input Plugin.

Type
Phaser.Input.InputPlugin

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

getDragState(pointer)

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.

Since: 3.16.0
Source: src/input/InputPlugin.js (Line 918)
Returns:

The drag state of the given Pointer.

Type
integer

hitTestPointer(pointer)

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.

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

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

Type
Array.<Phaser.GameObjects.GameObject>

isActive()

Checks to see if both this plugin and the Scene to which it belongs is active.

Since: 3.10.0
Source: src/input/InputPlugin.js (Line 509)
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

makePixelPerfect( [alphaTolerance])

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

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

Since: 3.10.0
Source: src/input/InputPlugin.js (Line 1668)
Returns:

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

Type
function

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

Remove the listeners of a given event.

Parameters:
Name Type Argument Description
event string | symbol

The event name.

fn function <optional>

Only remove the listeners that match this function.

context * <optional>

Only remove the listeners that have this context.

once boolean <optional>

Only remove one-time listeners.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 151)
Returns:

this.

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

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

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/InputPlugin.js (Line 2319)
Returns:

This Input instance.

Type
Phaser.Input.InputPlugin

setDraggable(gameObjects [, value])

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

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

This InputPlugin object.

Type
Phaser.Input.InputPlugin

setDragState(pointer, state)

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 integer

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

Since: 3.16.0
Source: src/input/InputPlugin.js (Line 942)

setGlobalTopOnly(value)

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.

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

This InputPlugin object.

Type
Phaser.Input.InputPlugin

setHitArea(gameObjects [, shape] [, callback])

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 Argument Description
gameObjects Phaser.GameObjects.GameObject | Array.<Phaser.GameObjects.GameObject>

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

shape Phaser.Types.Input.InputConfiguration | any <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.

callback Phaser.Types.Input.HitAreaCallback <optional>

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

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

This InputPlugin object.

Type
Phaser.Input.InputPlugin

setHitAreaCircle(gameObjects, x, y, radius [, callback])

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

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

This InputPlugin object.

Type
Phaser.Input.InputPlugin

setHitAreaEllipse(gameObjects, x, y, width, height [, callback])

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

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

This InputPlugin object.

Type
Phaser.Input.InputPlugin

setHitAreaFromTexture(gameObjects [, callback])

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

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

This InputPlugin object.

Type
Phaser.Input.InputPlugin

setHitAreaRectangle(gameObjects, x, y, width, height [, callback])

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

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

This InputPlugin object.

Type
Phaser.Input.InputPlugin

setHitAreaTriangle(gameObjects, x1, y1, x2, y2, x3, y3 [, callback])

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

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

This InputPlugin object.

Type
Phaser.Input.InputPlugin

setPollAlways()

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.

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

This InputPlugin object.

Type
Phaser.Input.InputPlugin

setPollOnMove()

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.

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

This InputPlugin object.

Type
Phaser.Input.InputPlugin

setPollRate(value)

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.

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

This InputPlugin object.

Type
Phaser.Input.InputPlugin

setTopOnly(value)

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.

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

This InputPlugin object.

Type
Phaser.Input.InputPlugin

sortGameObjects(gameObjects)

Given an array of 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.

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

The sorted array of Game Objects.

Type
Array.<Phaser.GameObjects.GameObject>

stopPropagation()

Causes the Input Manager to stop emitting any events for the remainder of this game step.

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

This InputPlugin object.

Type
Phaser.Input.InputPlugin