Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 36 ยท Input and Physics

Phaser Pointer Input: Mouse, Touch, Drag and Drop

Handle mouse and touch in Phaser: pointer events, setInteractive and hit areas, hover, dragging, drop zones, multi-touch, swipes and a drawing demo with live code.

On a phone there is no keyboard, and on a desktop many games are played entirely with the mouse. Phaser treats the mouse, a finger and a pen the same way and calls them all pointers. Code written for the pointer works on every device. This lesson shows how to read pointers, make objects clickable, drag them around and drop them on targets.

The pointer in one object

Phaser keeps a pointer object for the mouse (this.input.activePointer or this.input.mousePointer) and up to ten for touches. Its important properties:

Property Meaning
x, y position in screen (canvas) coordinates
worldX, worldY position in game-world coordinates (accounts for the camera scroll and zoom)
isDown is any button or finger down
leftButtonDown(), rightButtonDown() which button
velocity, getDistance(), getDuration() movement and press length, good for swipes
downX, downY, upX, upY where the press began and ended

Use worldX and worldY when your game has a scrolling camera, otherwise your clicks land in the wrong place. With a static camera they equal x and y.

Scene-wide pointer events

JavaScript
this.input.on('pointerdown', (pointer) => {
  console.log('clicked at', pointer.x, pointer.y);
});
this.input.on('pointermove', (pointer) => { /* mouse moved or finger dragged */ });
this.input.on('pointerup', (pointer) => { /* released */ });

These fire anywhere on the canvas, even when no game object is under the pointer. Use them for "click anywhere to start", aiming, painting and joystick-like controls.

Making objects interactive

To react to a click on a particular object, call setInteractive() on it. This tells the input system to test that object, using its rectangle as the hit area:

JavaScript
const button = this.add.image(240, 160, 'button').setInteractive({ useHandCursor: true });

button.on('pointerover', () => button.setTint(0xffff99));
button.on('pointerout',  () => button.clearTint());
button.on('pointerdown', () => button.setScale(0.95));
button.on('pointerup',   () => { button.setScale(1); this.startGame(); });

The usual events on an interactive object:

  • pointerover and pointerout: the pointer entered or left (hover),
  • pointerdown and pointerup: pressed and released while over the object,
  • pointermove: moved over it,
  • wheel: the mouse wheel scrolled over it.

The very common pattern for a button is to act on pointerup (a release over the button), and use pointerdown only for visual feedback. This lets the player change their mind by sliding away before releasing.

Hit areas

By default the hit area is the object's bounding rectangle (circles and polygons included). For other shapes pass a hit area and a callback:

JavaScript
// a circular hit area for a round button (the radius is in local pixels)
obj.setInteractive(new Phaser.Geom.Circle(obj.width / 2, obj.height / 2, 40), Phaser.Geom.Circle.Contains);

// pixel perfect: transparent pixels do not count
obj.setInteractive({ pixelPerfect: true, alphaTolerance: 1 });

Make touch targets generous. A fingertip is about 40 to 48 pixels wide, so a button that is 20 pixels wide is hard to hit on a phone. You can enlarge the hit area without changing the picture by giving a bigger rectangle: setInteractive(new Phaser.Geom.Rectangle(-10, -10, w + 20, h + 20), Phaser.Geom.Rectangle.Contains).

Overlapping objects

When objects overlap, a click normally reaches only the top one (this.input.topOnly is true by default). That is what you want for buttons stacked above a background that is also clickable. Switch it off with this.input.topOnly = false if all objects under the pointer should react.

Dragging

Dragging a card, a slider handle or a piece of a puzzle takes three steps: make it interactive, mark it draggable, and update the position in the drag event.

JavaScript
card.setInteractive({ draggable: true });
// or: this.input.setDraggable(card);

this.input.on('drag', (pointer, gameObject, dragX, dragY) => {
  gameObject.setPosition(dragX, dragY);
});

Related events: dragstart, drag, dragend, and with drop zones dragenter, dragleave, drop.

Drop zones

A drop zone is an interactive object that accepts dragged objects. Create one with this.add.zone(...) (an invisible object) or mark any game object with input.dropZone = true.

Drag cards onto a drop zone

Drag a card onto the right-hand frame: it locks into a stack. Release it elsewhere and it glides back, thanks to the third argument of dragend, which says whether the drop landed on a zone.

Drawing with the pointer

The pointermove event together with pointer.isDown is all a paint program needs. The trick for smooth lines is to connect the previous position to the current one, because on a fast stroke the pointer jumps many pixels between events.

Draw with mouse or finger

The color shifts a little with every segment, so the line becomes a rainbow. pointer.prevPosition holds where the pointer was on the previous event.

Multi-touch

By default Phaser tracks the mouse plus two touches. Add more with this.input.addPointer(2) (three extra, five in total). Each pointer has an id; this.input.pointer1, pointer2 and so on give you the touches. A two-player touch game, a virtual joystick plus a fire button, and pinch-to-zoom all need at least two pointers.

Swipes and gestures

Phaser has no built-in swipe event, but the numbers are easy to read on pointerup:

JavaScript
this.input.on('pointerup', (p) => {
  const dx = p.upX - p.downX, dy = p.upY - p.downY;
  if (p.getDuration() < 400 && Math.hypot(dx, dy) > 40) {      // quick and long enough
    if (Math.abs(dx) > Math.abs(dy)) console.log(dx > 0 ? 'swipe right' : 'swipe left');
    else console.log(dy > 0 ? 'swipe down' : 'swipe up');
  }
});

Other pointer details

  • Right click: the browser shows a context menu. Disable it with this.input.mouse.disableContextMenu() and test pointer.rightButtonDown().
  • Mouse wheel: this.input.on('wheel', (pointer, objects, dx, dy) => ...); dy > 0 is scrolling down.
  • Pointer lock: this.input.mouse.requestPointerLock() hides the cursor and reports relative movement, for first-person style aiming.
  • Cursor styling: this.input.setDefaultCursor('crosshair'), or useHandCursor per object.
  • Disabling: obj.disableInteractive() and obj.setInteractive() again later; obj.removeInteractive() forgets the hit area.

Common mistakes

  • Nothing happens on click. You forgot setInteractive(); also confirm the object is not behind another interactive object.
  • Wrong position with a scrolling camera. Use worldX and worldY.
  • A dragged object snaps to a corner. In drag, use the provided dragX, dragY arguments; they keep the grab offset for you.
  • Tiny buttons. Make hit areas at least about 44 pixels.
  • Using only pointerdown for buttons. Prefer pointerup so players can cancel by sliding off.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What must you do before an object can receive pointerdown events?

    Game objects are ignored by the input system until they are made interactive.
  2. 2. When should you use pointer.worldX instead of pointer.x?

    x and y are screen positions. worldX and worldY account for camera scroll and zoom.
  3. 3. What are the three steps to drag an object?

    Make it interactive and draggable, then update the position in the drag event using dragX and dragY.
  4. 4. How do you let players use two fingers at once?

    Phaser creates the mouse and two touch pointers by default; addPointer adds more.

Summary

  • Phaser unifies mouse, touch and pen as pointers; read x/y for the screen and worldX/worldY for the world.
  • Use this.input.on(...) for scene-wide events and setInteractive() plus pointerover/out/down/up on objects.
  • Act on pointerup for buttons, keep touch targets large and set the hit area when the shape is not a rectangle.
  • Drag with draggable: true, the drag event and drop zones; draw by connecting prevPosition to the current position.
  • Add pointers for multi-touch and compute swipes from the down and up positions.

Next: Arcade Physics Basics