Class: Pointer

Phaser.Input. Pointer

A Pointer object encapsulates both mouse and touch input within Phaser.

By default, Phaser will create 2 pointers for your game to use. If you require more, i.e. for a multi-touch game, then use the InputPlugin.addPointer method to do so, rather than instantiating this class directly, otherwise it won't be managed by the input system.

You can reference the current active pointer via InputPlugin.activePointer. You can also use the properties InputPlugin.pointer1 through to pointer10, for each pointer you have enabled in your game.

The properties of this object are set by the Input Plugin during processing. This object is then sent in all input related events that the Input Plugin emits, so you can reference properties from it directly in your callbacks.


new Pointer(manager, id)

Parameters:
Name Type Description
manager Phaser.Input.InputManager

A reference to the Input Manager.

id integer

The internal ID of this Pointer.

Since: 3.0.0
Source: src/input/Pointer.js (Line 14)

Members


active :boolean

An active Pointer is one that is currently pressed down on the display. A Mouse is always considered as active.

Type:
  • boolean
Since: 3.10.0
Source: src/input/Pointer.js (Line 451)

<readonly> angle :number

The current angle the Pointer is moving, in radians, based on its previous and current position.

The angle is based on the old position facing to the current position.

This property is updated whenever the Pointer moves, regardless of any button states. In other words, it changes based on movement alone - a button doesn't have to be pressed first.

Type:
  • number
Since: 3.16.0
Source: src/input/Pointer.js (Line 171)

buttons :integer

0: No button or un-initialized 1: Left button 2: Right button 4: Wheel button or middle button 8: 4th button (typically the "Browser Back" button) 16: 5th button (typically the "Browser Forward" button)

For a mouse configured for left-handed use, the button actions are reversed. In this case, the values are read from right to left.

Type:
  • integer
Since: 3.0.0
Default Value:
  • 0
Source: src/input/Pointer.js (Line 104)

camera :Phaser.Cameras.Scene2D.Camera

The camera the Pointer interacted with during its last update.

A Pointer can only ever interact with one camera at once, which will be the top-most camera in the list should multiple cameras be positioned on-top of each other.

Type:
Since: 3.0.0
Default Value:
  • null
Source: src/input/Pointer.js (Line 91)

dirty :boolean

A dirty flag for this Pointer, used internally by the Input Plugin.

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

<readonly> distance :number

The distance the Pointer has moved, based on its previous and current position.

This value is smoothed out each frame, according to the motionFactor property.

This property is updated whenever the Pointer moves, regardless of any button states. In other words, it changes based on movement alone - a button doesn't have to be pressed first.

If you need the total distance travelled since the primary buttons was pressed down, then use the Pointer.getDistance method.

Type:
  • number
Since: 3.16.0
Source: src/input/Pointer.js (Line 186)

<readonly> downElement :any

The DOM element the Pointer was pressed down on, taken from the DOM event.

Type:
  • any
Since: 3.16.0
Source: src/input/Pointer.js (Line 71)

downTime :number

Time when Button 1 (left button), or Touch, was pressed, used for dragging objects.

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

downX :number

X coordinate of the Pointer when Button 1 (left button), or Touch, was pressed, used for dragging objects.

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

downY :number

Y coordinate of the Pointer when Button 1 (left button), or Touch, was pressed, used for dragging objects.

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

event :TouchEvent|MouseEvent

The most recent native DOM Event this Pointer has processed.

Type:
  • TouchEvent | MouseEvent
Since: 3.0.0
Source: src/input/Pointer.js (Line 62)

<readonly> id :integer

The internal ID of this Pointer.

Type:
  • integer
Since: 3.0.0
Source: src/input/Pointer.js (Line 52)

identifier :number

The identifier property of the Pointer as set by the DOM event when this Pointer is started.

Type:
  • number
Since: 3.10.0
Source: src/input/Pointer.js (Line 432)

isDown :boolean

Is any button on this pointer considered as being down?

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

justDown :boolean

Is this Pointer considered as being "just down" or not?

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

justMoved :boolean

Is this Pointer considered as being "just moved" or not?

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

justUp :boolean

Is this Pointer considered as being "just up" or not?

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

manager :Phaser.Input.InputManager

A reference to the Input Manager.

Type:
Since: 3.0.0
Source: src/input/Pointer.js (Line 43)

motionFactor :number

The factor applied to the motion smoothing each frame.

This value is passed to the Smooth Step Interpolation that is used to calculate the velocity, angle and distance of the Pointer. It's applied every frame, until the midPoint reaches the current position of the Pointer. 0.2 provides a good average but can be increased if you need a quicker update and are working in a high performance environment. Never set this value to zero.

Type:
  • number
Since: 3.16.0
Default Value:
  • 0.2
Source: src/input/Pointer.js (Line 224)

movementX :number

If the mouse is locked, the horizontal relative movement of the Pointer in pixels since last frame.

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

movementY :number

If the mouse is locked, the vertical relative movement of the Pointer in pixels since last frame.

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

moveTime :number

Time when this Pointer was most recently moved (regardless of the state of its buttons, if any)

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

pointerId :number

The pointerId property of the Pointer as set by the DOM event when this Pointer is started. The browser can and will recycle this value.

Type:
  • number
Since: 3.10.0
Source: src/input/Pointer.js (Line 441)

<readonly> position :Phaser.Math.Vector2

The position of the Pointer in screen space.

Type:
Since: 3.0.0
Source: src/input/Pointer.js (Line 122)

<readonly> prevPosition :Phaser.Math.Vector2

The previous position of the Pointer in screen space.

The old x and y values are stored in here during the InputManager.transformPointer call.

Use the properties velocity, angle and distance to create your own gesture recognition.

Type:
Since: 3.11.0
Source: src/input/Pointer.js (Line 132)

primaryDown :boolean

Is the primary button down? (usually button 0, the left mouse button)

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

smoothFactor :number

The smoothing factor to apply to the Pointer position.

Due to their nature, pointer positions are inherently noisy. While this is fine for lots of games, if you need cleaner positions then you can set this value to apply an automatic smoothing to the positions as they are recorded.

The default value of zero means 'no smoothing'. Set to a small value, such as 0.2, to apply an average level of smoothing between positions. You can do this by changing this value directly, or by setting the input.smoothFactor property in the Game Config.

Positions are only smoothed when the pointer moves. If the primary button on this Pointer enters an Up or Down state, then the position is always precise, and not smoothed.

Type:
  • number
Since: 3.16.0
Default Value:
  • 0
Source: src/input/Pointer.js (Line 204)

time :number

Time when this Pointer was most recently updated by the Game step.

Type:
  • number
Since: 3.16.0
Source: src/input/Pointer.js (Line 461)

<readonly> upElement :any

The DOM element the Pointer was released on, taken from the DOM event.

Type:
  • any
Since: 3.16.0
Source: src/input/Pointer.js (Line 81)

upTime :number

Time when Button 1 (left button), or Touch, was released, used for dragging objects.

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

upX :number

X coordinate of the Pointer when Button 1 (left button), or Touch, was released, used for dragging objects.

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

upY :number

Y coordinate of the Pointer when Button 1 (left button), or Touch, was released, used for dragging objects.

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

<readonly> velocity :Phaser.Math.Vector2

The current velocity of the Pointer, based on its current and previous positions.

This value is smoothed out each frame, according to the motionFactor property.

This property is updated whenever the Pointer moves, regardless of any button states. In other words, it changes based on movement alone - a button doesn't have to be pressed first.

Type:
Since: 3.16.0
Source: src/input/Pointer.js (Line 156)

wasCanceled :boolean

Did this Pointer get canceled by a touchcancel event?

Note: "canceled" is the American-English spelling of "cancelled". Please don't submit PRs correcting it!

Type:
  • boolean
Since: 3.15.0
Default Value:
  • false
Source: src/input/Pointer.js (Line 400)

wasTouch :boolean

Did the previous input event come from a Touch input (true) or Mouse? (false)

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

worldX :number

The x position of this Pointer, translated into the coordinate space of the most recent Camera it interacted with.

Type:
  • number
Since: 3.10.0
Default Value:
  • 0
Source: src/input/Pointer.js (Line 240)

worldY :number

The y position of this Pointer, translated into the coordinate space of the most recent Camera it interacted with.

Type:
  • number
Since: 3.10.0
Default Value:
  • 0
Source: src/input/Pointer.js (Line 250)

x :number

The x position of this Pointer. The value is in screen space. See worldX to get a camera converted position.

Type:
  • number
Since: 3.0.0
Source: src/input/Pointer.js (Line 1083)

y :number

The y position of this Pointer. The value is in screen space. See worldY to get a camera converted position.

Type:
  • number
Since: 3.0.0
Source: src/input/Pointer.js (Line 1106)

Methods


backButtonDown()

Checks to see if the back button is being held down on this Pointer.

Since: 3.0.0
Source: src/input/Pointer.js (Line 865)
Returns:

true if the back button is being held down.

Type
boolean

destroy()

Destroys this Pointer instance and resets its external references.

Since: 3.0.0
Source: src/input/Pointer.js (Line 1070)

forwardButtonDown()

Checks to see if the forward button is being held down on this Pointer.

Since: 3.0.0
Source: src/input/Pointer.js (Line 878)
Returns:

true if the forward button is being held down.

Type
boolean

getAngle()

If the Pointer has a button pressed down at the time this method is called, it will return the angle between the Pointer's downX and downY values and the current position.

If no button is held down, it will return the last recorded angle, based on where the Pointer was when the button was released.

The angle is based on the old position facing to the current position.

If you wish to get the current angle, based on the velocity of the Pointer, then see the Pointer.angle property.

Since: 3.16.0
Source: src/input/Pointer.js (Line 990)
Returns:

The angle between the Pointer's coordinates in radians.

Type
number

getDistance()

If the Pointer has a button pressed down at the time this method is called, it will return the distance between the Pointer's downX and downY values and the current position.

If no button is held down, it will return the last recorded distance, based on where the Pointer was when the button was released.

If you wish to get the distance being travelled currently, based on the velocity of the Pointer, then see the Pointer.distance property.

Since: 3.13.0
Source: src/input/Pointer.js (Line 891)
Returns:

The distance the Pointer moved.

Type
number

getDistanceX()

If the Pointer has a button pressed down at the time this method is called, it will return the horizontal distance between the Pointer's downX and downY values and the current position.

If no button is held down, it will return the last recorded horizontal distance, based on where the Pointer was when the button was released.

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

The horizontal distance the Pointer moved.

Type
number

getDistanceY()

If the Pointer has a button pressed down at the time this method is called, it will return the vertical distance between the Pointer's downX and downY values and the current position.

If no button is held down, it will return the last recorded vertical distance, based on where the Pointer was when the button was released.

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

The vertical distance the Pointer moved.

Type
number

getDuration()

If the Pointer has a button pressed down at the time this method is called, it will return the duration since the button was pressed down.

If no button is held down, it will return the last recorded duration, based on the time the Pointer button was released.

Since: 3.16.0
Source: src/input/Pointer.js (Line 966)
Returns:

The duration the Pointer was held down for in milliseconds.

Type
number

getInterpolatedPosition( [steps] [, out])

Takes the previous and current Pointer positions and then generates an array of interpolated values between the two. The array will be populated up to the size of the steps argument.

var points = pointer.getInterpolatedPosition(4);

// points[0] = { x: 0, y: 0 }
// points[1] = { x: 2, y: 1 }
// points[2] = { x: 3, y: 2 }
// points[3] = { x: 6, y: 3 }

Use this if you need to get smoothed values between the previous and current pointer positions. DOM pointer events can often fire faster than the main browser loop, and this will help you avoid janky movement especially if you have an object following a Pointer.

Note that if you provide an output array it will only be populated up to the number of steps provided. It will not clear any previous data that may have existed beyond the range of the steps count.

Internally it uses the Smooth Step interpolation calculation.

Parameters:
Name Type Argument Default Description
steps integer <optional>
10

The number of interpolation steps to use.

out array <optional>

An array to store the results in. If not provided a new one will be created.

Since: 3.11.0
Source: src/input/Pointer.js (Line 1019)
Returns:

An array of interpolated values.

Type
array

leftButtonDown()

Checks to see if the left button is being held down on this Pointer.

Since: 3.0.0
Source: src/input/Pointer.js (Line 826)
Returns:

true if the left button is being held down.

Type
boolean

middleButtonDown()

Checks to see if the middle button is being held down on this Pointer.

Since: 3.0.0
Source: src/input/Pointer.js (Line 852)
Returns:

true if the middle button is being held down.

Type
boolean

noButtonDown()

Checks to see if any buttons are being held down on this Pointer.

Since: 3.0.0
Source: src/input/Pointer.js (Line 813)
Returns:

true if no buttons are being held down.

Type
boolean

positionToCamera(camera [, output])

Takes a Camera and returns a Vector2 containing the translated position of this Pointer within that Camera. This can be used to convert this Pointers position into camera space.

Parameters:
Name Type Argument Description
camera Phaser.Cameras.Scene2D.Camera

The Camera to use for the translation.

output Phaser.Math.Vector2 | object <optional>

A Vector2-like object in which to store the translated position.

Since: 3.0.0
Source: src/input/Pointer.js (Line 471)
Returns:

A Vector2 containing the translated coordinates of this Pointer, based on the given camera.

Type
Phaser.Math.Vector2 | object

rightButtonDown()

Checks to see if the right button is being held down on this Pointer.

Since: 3.0.0
Source: src/input/Pointer.js (Line 839)
Returns:

true if the right button is being held down.

Type
boolean