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

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

Constructor:

new Pointer(manager, id)

Parameters:

name type description
manager Phaser.Input.InputManager

A reference to the Input Manager.

id number

The internal ID of this Pointer.

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

Members

active: boolean
Focus
Focus

Description:

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 438)
Focus
Focus
<readonly> angle: number
Focus
Focus

Description:

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 192)
Focus
Focus
<readonly> button: number
Focus
Focus

Description:

A read-only property that indicates which button was pressed, or released, on the pointer during the most recent event. It is only set during up and down events.

On Touch devices the value is always 0.

Users may change the configuration of buttons on their pointing device so that if an event's button property is zero, it may not have been caused by the button that is physically left–most on the pointing device; however, it should behave as if the left button was clicked in the standard button layout.

Type:
number
Default: 0
Since: 3.18.0
Source: src/input/Pointer.js (Line 107)
Focus
Focus
buttons: number
Focus
Focus

Description:

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:
number
Default: 0
Since: 3.0.0
Source: src/input/Pointer.js (Line 125)
Focus
Focus

Description:

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:
Default: null
Since: 3.0.0
Source: src/input/Pointer.js (Line 94)
Focus
Focus
deltaX: number
Focus
Focus

Description:

The horizontal scroll amount that occurred due to the user moving a mouse wheel or similar input device.

Type:
number
Default: 0
Since: 3.18.0
Source: src/input/Pointer.js (Line 464)
Focus
Focus
deltaY: number
Focus
Focus

Description:

The vertical scroll amount that occurred due to the user moving a mouse wheel or similar input device. This value will typically be less than 0 if the user scrolls up and greater than zero if scrolling down.

Type:
number
Default: 0
Since: 3.18.0
Source: src/input/Pointer.js (Line 474)
Focus
Focus
deltaZ: number
Focus
Focus

Description:

The z-axis scroll amount that occurred due to the user moving a mouse wheel or similar input device.

Type:
number
Default: 0
Since: 3.18.0
Source: src/input/Pointer.js (Line 485)
Focus
Focus
<readonly> distance: number
Focus
Focus

Description:

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 207)
Focus
Focus
<readonly> downElement: any
Focus
Focus

Description:

The DOM element the Pointer was pressed down on, taken from the DOM event. In a default set-up this will be the Canvas that Phaser is rendering to, or the Window element.

Type:
any
Since: 3.16.0
Source: src/input/Pointer.js (Line 72)
Focus
Focus
downTime: number
Focus
Focus

Description:

The Event timestamp when the first button, or Touch input, was pressed. Used for dragging objects.

Type:
number
Default: 0
Since: 3.0.0
Source: src/input/Pointer.js (Line 317)
Focus
Focus
downX: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Source: src/input/Pointer.js (Line 297)
Focus
Focus
downY: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Source: src/input/Pointer.js (Line 307)
Focus
Focus
event: TouchEvent | MouseEvent
Focus
Focus

Description:

The most recent native DOM Event this Pointer has processed.

Type:
TouchEvent | MouseEvent
Since: 3.0.0
Source: src/input/Pointer.js (Line 63)
Focus
Focus
<readonly> id: number
Focus
Focus

Description:

The internal ID of this Pointer.

Type:
number
Since: 3.0.0
Source: src/input/Pointer.js (Line 53)
Focus
Focus
identifier: number
Focus
Focus

Description:

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 419)
Focus
Focus
isDown: boolean
Focus
Focus

Description:

Is any button on this pointer considered as being down?

Type:
boolean
Default: false
Since: 3.0.0
Source: src/input/Pointer.js (Line 367)
Focus
Focus
<readonly> locked: boolean
Focus
Focus

Description:

Is this pointer Pointer Locked?

Only a mouse pointer can be locked and it only becomes locked when requested via the browsers Pointer Lock API.

You can request this by calling the this.input.mouse.requestPointerLock() method from a pointerdown or pointerup event handler.

Type:
boolean
Since: 3.19.0
Source: src/input/Pointer.js (Line 448)
Focus
Focus

Description:

A reference to the Input Manager.

Type:
Since: 3.0.0
Source: src/input/Pointer.js (Line 44)
Focus
Focus
<private> midPoint: Phaser.Math.Vector2
Focus
Focus

Description:

An internal vector used for calculations of the pointer speed and angle.

Type:
Since: 3.16.0
Source: src/input/Pointer.js (Line 167)
Focus
Focus
motionFactor: number
Focus
Focus

Description:

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
Default: 0.2
Since: 3.16.0
Source: src/input/Pointer.js (Line 245)
Focus
Focus
moveTime: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Source: src/input/Pointer.js (Line 287)
Focus
Focus
movementX: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Source: src/input/Pointer.js (Line 399)
Focus
Focus
movementY: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Source: src/input/Pointer.js (Line 409)
Focus
Focus
pointerId: number
Focus
Focus

Description:

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 428)
Focus
Focus
<readonly> position: Phaser.Math.Vector2
Focus
Focus

Description:

The position of the Pointer in screen space.

Type:
Since: 3.0.0
Source: src/input/Pointer.js (Line 143)
Focus
Focus
<readonly> prevPosition: Phaser.Math.Vector2
Focus
Focus

Description:

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 153)
Focus
Focus
primaryDown: boolean
Focus
Focus

Description:

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

Type:
boolean
Default: false
Since: 3.0.0
Source: src/input/Pointer.js (Line 357)
Focus
Focus
smoothFactor: number
Focus
Focus

Description:

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
Default: 0
Since: 3.16.0
Source: src/input/Pointer.js (Line 225)
Focus
Focus
<readonly> time: number
Focus
Focus

Description:

Time when this Pointer was most recently updated by a DOM Event. This comes directly from the event.timeStamp property. If no event has yet taken place, it will return zero.

Type:
number
Since: 3.16.0
Source: src/input/Pointer.js (Line 1259)
Focus
Focus
<readonly> upElement: any
Focus
Focus

Description:

The DOM element the Pointer was released on, taken from the DOM event. In a default set-up this will be the Canvas that Phaser is rendering to, or the Window element.

Type:
any
Since: 3.16.0
Source: src/input/Pointer.js (Line 83)
Focus
Focus
upTime: number
Focus
Focus

Description:

The Event timestamp when the final button, or Touch input, was released. Used for dragging objects.

Type:
number
Default: 0
Since: 3.0.0
Source: src/input/Pointer.js (Line 347)
Focus
Focus
upX: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Source: src/input/Pointer.js (Line 327)
Focus
Focus
upY: number
Focus
Focus

Description:

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

Type:
number
Default: 0
Since: 3.0.0
Source: src/input/Pointer.js (Line 337)
Focus
Focus
<readonly> velocity: Phaser.Math.Vector2
Focus
Focus

Description:

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 177)
Focus
Focus
wasCanceled: boolean
Focus
Focus

Description:

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
Default: false
Since: 3.15.0
Source: src/input/Pointer.js (Line 387)
Focus
Focus
wasTouch: boolean
Focus
Focus

Description:

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

Type:
boolean
Default: false
Since: 3.0.0
Source: src/input/Pointer.js (Line 377)
Focus
Focus
worldX: number
Focus
Focus

Description:

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

If you wish to use this value outside of an input event handler then you should update it first by calling the Pointer.updateWorldPoint method.

Type:
number
Default: 0
Since: 3.10.0
Source: src/input/Pointer.js (Line 261)
Focus
Focus
worldY: number
Focus
Focus

Description:

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

If you wish to use this value outside of an input event handler then you should update it first by calling the Pointer.updateWorldPoint method.

Type:
number
Default: 0
Since: 3.10.0
Source: src/input/Pointer.js (Line 274)
Focus
Focus
x: number
Focus
Focus

Description:

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 1213)
Focus
Focus
y: number
Focus
Focus

Description:

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 1236)
Focus
Focus

Methods

backButtonDown()
Focus
Focus

Description:

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

Returns:
Description:

true if the back button is being held down.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/input/Pointer.js (Line 930)
Focus
Focus
backButtonReleased()
Focus
Focus

Description:

Checks to see if the back button was just released on this Pointer.

Returns:
Description:

true if the back button was just released.

Type:
  • boolean
Examples:
Since: 3.18.0
Source: src/input/Pointer.js (Line 995)
Focus
Focus
destroy()
Focus
Focus

Description:

Destroys this Pointer instance and resets its external references.

Examples:
Since: 3.0.0
Source: src/input/Pointer.js (Line 1200)
Focus
Focus
<private> down(event)
Focus
Focus

Description:

Internal method to handle a Mouse Down Event.

Parameters:

name type description
event MouseEvent

The Mouse Event to process.

Examples:
Since: 3.0.0
Source: src/input/Pointer.js (Line 630)
Focus
Focus
forwardButtonDown()
Focus
Focus

Description:

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

Returns:
Description:

true if the forward button is being held down.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/input/Pointer.js (Line 943)
Focus
Focus
forwardButtonReleased()
Focus
Focus

Description:

Checks to see if the forward button was just released on this Pointer.

Returns:
Description:

true if the forward button was just released.

Type:
  • boolean
Examples:
Since: 3.18.0
Source: src/input/Pointer.js (Line 1008)
Focus
Focus
getAngle()
Focus
Focus

Description:

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.

Returns:
Description:

The angle between the Pointer's coordinates in radians.

Type:
  • number
Examples:
Since: 3.16.0
Source: src/input/Pointer.js (Line 1120)
Focus
Focus
getDistance()
Focus
Focus

Description:

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.

Returns:
Description:

The distance the Pointer moved.

Type:
  • number
Examples:
Since: 3.13.0
Source: src/input/Pointer.js (Line 1021)
Focus
Focus
getDistanceX()
Focus
Focus

Description:

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.

Returns:
Description:

The horizontal distance the Pointer moved.

Type:
  • number
Examples:
Since: 3.16.0
Source: src/input/Pointer.js (Line 1048)
Focus
Focus
getDistanceY()
Focus
Focus

Description:

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.

Returns:
Description:

The vertical distance the Pointer moved.

Type:
  • number
Examples:
Since: 3.16.0
Source: src/input/Pointer.js (Line 1072)
Focus
Focus
getDuration()
Focus
Focus

Description:

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 last button on the Pointer was released.

Returns:
Description:

The duration the Pointer was held down for in milliseconds.

Type:
  • number
Examples:
Since: 3.16.0
Source: src/input/Pointer.js (Line 1096)
Focus
Focus
getInterpolatedPosition([steps], [out])
Focus
Focus

Description:

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 arguments Default description
steps number <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.

Returns:
Description:

An array of interpolated values.

Type:
  • array
Examples:
Since: 3.11.0
Source: src/input/Pointer.js (Line 1149)
Focus
Focus
leftButtonDown()
Focus
Focus

Description:

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

Returns:
Description:

true if the left button is being held down.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/input/Pointer.js (Line 891)
Focus
Focus
leftButtonReleased()
Focus
Focus

Description:

Checks to see if the left button was just released on this Pointer.

Returns:
Description:

true if the left button was just released.

Type:
  • boolean
Examples:
Since: 3.18.0
Source: src/input/Pointer.js (Line 956)
Focus
Focus
middleButtonDown()
Focus
Focus

Description:

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

Returns:
Description:

true if the middle button is being held down.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/input/Pointer.js (Line 917)
Focus
Focus
middleButtonReleased()
Focus
Focus

Description:

Checks to see if the middle button was just released on this Pointer.

Returns:
Description:

true if the middle button was just released.

Type:
  • boolean
Examples:
Since: 3.18.0
Source: src/input/Pointer.js (Line 982)
Focus
Focus
<private> move(event)
Focus
Focus

Description:

Internal method to handle a Mouse Move Event.

Parameters:

name type description
event MouseEvent

The Mouse Event to process.

Examples:
Since: 3.0.0
Source: src/input/Pointer.js (Line 680)
Focus
Focus
noButtonDown()
Focus
Focus

Description:

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

Returns:
Description:

true if no buttons are being held down.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/input/Pointer.js (Line 878)
Focus
Focus
positionToCamera(camera, [output])
Focus
Focus

Description:

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 arguments description
camera Phaser.Cameras.Scene2D.Camera

The Camera to use for the translation.

output object | Phaser.Math.Vector2 <optional>

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

Returns:
Description:

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

Type:
Examples:
Since: 3.0.0
Source: src/input/Pointer.js (Line 521)
Focus
Focus
rightButtonDown()
Focus
Focus

Description:

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

Returns:
Description:

true if the right button is being held down.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/input/Pointer.js (Line 904)
Focus
Focus
rightButtonReleased()
Focus
Focus

Description:

Checks to see if the right button was just released on this Pointer.

Returns:
Description:

true if the right button was just released.

Type:
  • boolean
Examples:
Since: 3.18.0
Source: src/input/Pointer.js (Line 969)
Focus
Focus
<private> touchcancel(touch, event)
Focus
Focus

Description:

Internal method to handle a Touch Cancel Event.

Parameters:

name type description
touch Touch

The Changed Touch from the Touch Event.

event TouchEvent

The full Touch Event.

Examples:
Since: 3.15.0
Source: src/input/Pointer.js (Line 844)
Focus
Focus
<private> touchend(touch, event)
Focus
Focus

Description:

Internal method to handle a Touch End Event.

Parameters:

name type description
touch Touch

The Changed Touch from the Touch Event.

event TouchEvent

The full Touch Event.

Examples:
Since: 3.0.0
Source: src/input/Pointer.js (Line 808)
Focus
Focus
<private> touchmove(touch, event)
Focus
Focus

Description:

Internal method to handle a Touch Move Event.

Parameters:

name type description
touch Touch

The Changed Touch from the Touch Event.

event TouchEvent

The full Touch Event.

Examples:
Since: 3.0.0
Source: src/input/Pointer.js (Line 784)
Focus
Focus
<private> touchstart(touch, event)
Focus
Focus

Description:

Internal method to handle a Touch Start Event.

Parameters:

name type description
touch Touch

The Changed Touch from the Touch Event.

event TouchEvent

The full Touch Event.

Examples:
Since: 3.0.0
Source: src/input/Pointer.js (Line 741)
Focus
Focus
<private> up(event)
Focus
Focus

Description:

Internal method to handle a Mouse Up Event.

Parameters:

name type description
event MouseEvent

The Mouse Event to process.

Examples:
Since: 3.0.0
Source: src/input/Pointer.js (Line 586)
Focus
Focus
<private> updateMotion()
Focus
Focus

Description:

Calculates the motion of this Pointer, including its velocity and angle of movement. This method is called automatically each frame by the Input Manager.

Examples:
Since: 3.16.0
Source: src/input/Pointer.js (Line 538)
Focus
Focus
updateWorldPoint(camera)
Focus
Focus

Description:

Takes a Camera and updates this Pointer's worldX and worldY values so they are the result of a translation through the given Camera.

Note that the values will be automatically replaced the moment the Pointer is updated by an input event, such as a mouse move, so should be used immediately.

Parameters:

name type description
camera Phaser.Cameras.Scene2D.Camera

The Camera which is being tested against.

Returns:
Description:

This Pointer object.

Examples:
Since: 3.19.0
Source: src/input/Pointer.js (Line 496)
Focus
Focus
<private> wheel(event)
Focus
Focus

Description:

Internal method to handle a Mouse Wheel Event.

Parameters:

name type description
event WheelEvent

The Wheel Event to process.

Examples:
Since: 3.18.0
Source: src/input/Pointer.js (Line 713)
Focus
Focus