Skip to content

Touch events

Introduction

Built-in touch/mouse events of phaser.

  • Author: Richard Davey

Usage

Quick start

  • Is touching
    var pointer = scene.input.activePointer;
    if (pointer.isDown) {
        var touchX = pointer.x;
        var touchY = pointer.y;
        // ...
    }
    
  • On any touching start
    scene.input.on('pointerdown', function(pointer){
        var touchX = pointer.x;
        var touchY = pointer.y;
        // ...
     });
    
  • On any touching end
    scene.input.on('pointerup', function(pointer){
        var touchX = pointer.x;
        var touchY = pointer.y;
        // ...
     });
    
  • On touch game object start
    gameObject.setInteractive().on('pointerdown', function(pointer, localX, localY, event){
        // ...
    })
    
  • On touch game object end
    gameObject.setInteractive().on('pointerup', function(pointer, localX, localY, event){
        // ...
    })
    

Reference : Properties of point

Register interactive

Call gameObject.setInteractive(...) to register touch input of Game Object before listening touching events.

  • Set hit area from width & height (rectangle) of the texture
    gameObject.setInteractive();
    
  • Set hit area from shape
    gameObject.setInteractive(shape, callback);
    
    • Circle
      • shape : new Phaser.Geom.Circle(x, y, radius)
      • callback : Phaser.Geom.Circle.Contains
    • Ellipse
      • shape : new Phaser.Geom.Ellipse(x, y, width, height)
      • callback : Phaser.Geom.Ellipse.Contains
    • Rectangle
      • shape : new Phaser.Geom.Rectangle(x, y, width, height)
      • callback : Phaser.Geom.Rectangle.Contains
    • Triangle
      • shape : new Phaser.Geom.Triangle(x1, y1, x2, y2, x3, y3)
      • callback : Phaser.Geom.Triangle.Contains
    • Polygon
      • shape : new Phaser.Geom.Polygon(points)
      • callback : Phaser.Geom.Polygon.Contains
    • Hexagon
      • shape : new Phaser.Geom.rexHexagon(x, y, size, type)
      • callback : Phaser.Geom.Polygon.Contains
    • Rhombus
      • shape : new Phaser.Geom.rexRhombus(x, y, width, height)
      • callback : Phaser.Geom.Polygon.Contains
    • Note: x, y relate to the top-left of the gameObject.
  • Set interactive configuration
    gameObject.setInteractive({
        hitArea: shape,
        hitAreaCallback: callback,
        pixelPerfect: true,
        alphaTolerance: 1,
        draggable: true,
        dropZone: true,
        cursor: CSSString,
        useHandCursor: true
    });
    
    • Hit area
      • shape
      • Pixel alpha
        • pixelPerfect : true
        • alphaTolerance : 1 (0-255)
      • Custom hit-testing function
        • hitAreaCallback
          function(shape, x, y, gameObject) {
              return hit;  // true/false
          }
          
    • Dragging
      • draggable : true
    • Drop zone
      • dropZone : true
    • Cursor
      • cursor : CSS string
      • useHandCursor : true

Pixel perfect hit-testing

This is an expensive process, should only be enabled on Game Objects that really need it.

Disable interactive

  • Disable temporary
    gameObject.disableInteractive();
    
    or
    gameObject.setInteractive(false);
    
  • Remove interaction
    gameObject.removeInteractive();
    

Top only

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.

  • Get
    var topOnly = scene.input.topOnly;
    
  • Set
    scene.input.topOnly = topOnly;
    scene.input.setTopOnly(topOnly);
    

Touch events

  1. Events on touched Game object
    gameObject.on('pointerdown', function(pointer, localX, localY, event){ /* ... */ });
    gameObject.on('pointerup', function(pointer, localX, localY, event){ /* ... */ });
    gameObject.on('pointermove', function(pointer, localX, localY, event){ /* ... */ });
    gameObject.on('pointerover', function(pointer, localX, localY, event){ /* ... */ });
    gameObject.on('pointerout', function(pointer, event){ /* ... */ });
    
    • Cancel remaining touched events
      function(pointer, localX, localY, event) {
          event.stopPropagation();
      }
      
  2. Event on input plugin for each touched Game object
    scene.input.on('gameobjectdown', function(pointer, gameObject, event){ /* ... */ });
    scene.input.on('gameobjectup', function(pointer, gameObject, event){ /* ... */ });
    scene.input.on('gameobjectmove', function(pointer, gameObject, event){ /* ... */ });
    scene.input.on('gameobjectover', function(pointer, gameObject, event){ /* ... */ });
    scene.input.on('gameobjectout', function(pointer, gameObject, event){ /* ... */ });
    
    • Cancel remaining touched events
      function(pointer, gameObject, event) {
          event.stopPropagation();
      }
      
  3. Events to get all touched Game Objects
    scene.input.on('pointerdown', function(pointer, currentlyOver){ /* ... */ });
    scene.input.on('pointerup', function(pointer, currentlyOver){ /* ... */ });
    scene.input.on('pointermove', function(pointer, currentlyOver){ /* ... */ });
    scene.input.on('pointerover', function(pointer, justOver){ /* ... */ });
    scene.input.on('pointerout', function(pointer, justOut){ /* ... */ });
    

Dragging

Enable dragging

  • Enable dragging when registering interactive
    gameObject.setInteractive({ draggable: true });
    
  • Enable dragging and add it to dragging detecting list after registered interactive
    scene.input.setDraggable(gameObject);
    
  • Enable dragging
    gameObject.input.draggable = true;
    

Disable dragging

  • Remove Game Object from dragging detecting list
    scene.input.setDraggable(gameObject, false);
    
  • Disable dragging but keep it in dragging detecting list
    gameObject.input.draggable = false;
    

Dragging events

gameObject.on('dragstart', function(pointer, dragX, dragY){ /* ... */ });
gameObject.on('drag', function(pointer, dragX, dragY){ /* ... */ });
gameObject.on('dragend', function(pointer, dragX, dragY, dropped){ /* ... */ });
scene.input.on('dragstart', function(pointer, gameObject){ /* ... */ });
scene.input.on('drag', function(pointer, gameObject, dragX, dragY){ /* ... */ });
scene.input.on('dragend', function(pointer, gameObject, dropped){ /* ... */ });

Dragging properties

scene.input.dragDistanceThreshold = 16;
scene.input.dragTimeThreshold = 500;

Drop zone

Enable drop zone

  • Enable dropping when registering interactive
    gameObject.setInteractive({ dropZone: true });
    
  • Enable dropping after registered interactive
    gameObject.input.dropZone = true;
    

Disable drop zone

gameObject.input.dropZone = false;

Dropping events

gameObject.on('drop', function(pointer, target){ /* ... */ });

gameObject.on('dragenter', function(pointer, target){ /* ... */ });
gameObject.on('dragover', function(pointer, target){ /* ... */ });
gameObject.on('dragleave', function(pointer, target){ /* ... */ });
scene.input.on('drop', function(pointer, gameObject, target){ /* ... */ });

scene.input.on('dragenter', function(pointer, gameObject, target){ /* ... */ });
scene.input.on('dragover', function(pointer, gameObject, target){ /* ... */ });
scene.input.on('dragleave', function(pointer, gameObject, target){ /* ... */ });

Single touch

Pointer

var pointer = scene.input.activePointer;

Multi-touch

Amount of active pointers

Set amount of active pointers in game configuration

var config = {
    // ...
    input: {
        activePointers: 1,
        // ...
    }
};
var game = new Phaser.Game(config);

Or add pointers in run-time.

scene.input.addPointer(num);  // total points = num + 1

Pointers

  • pointer 1 ~ 10
    var pointer = scene.input.pointer1;
    // ...
    var pointer = scene.input.pointer10;
    
  • pointer n
    var pointer = scene.input.manager.pointers[n];
    
  • Amount of total pointers
    var amount = scene.input.manager.pointersTotal;
    

Properties of point

  • Position
    • Current touching
      • Position in screen : pointer.x , pointer.y
      • Position in camera : pointer.worldX , pointer.worldY
      • Position of previous moving : pointer.prevPosition.x , pointer.prevPosition.y
    • Dragable object
      • Touching start : pointer.downX, pointer.downY
      • Touching end : pointer.upX, pointer.upY
  • Touch state
    • Is touching : pointer.isDown
    • Is touching start : pointer.justDown
    • Is touching end : pointer.justUp
    • Is touching move : pointer.justMoved
  • Botton down
    • No botton down : pointer.noButtonDown()
    • Is primary (left) botton down : pointer.leftButtonDown()
    • Is secondary (right) botton down : pointer.rightButtonDown()
    • Is middle (mouse wheel) button down : pointer.middleButtonDown()
    • Is back botton down : pointer.backButtonDown()
    • Is forward button down : pointer.forwardButtonDown()
  • Index in scene.input.manager.pointers : pointer.id