Touch events
Introduction¶
Built-in touch/mouse events of phaser.
- Author: Richard Davey
Note
No touch input event fired in preload stage.
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; // ... }, scope);
- On any touching end
scene.input.on('pointerup', function(pointer){ var touchX = pointer.x; var touchY = pointer.y; // ... }, scope);
- On touch game object start
gameObject.setInteractive().on('pointerdown', function(pointer, localX, localY, event){ // ... }, scope);
- On touch game object end
gameObject.setInteractive().on('pointerup', function(pointer, localX, localY, event){ // ... }, scope);
- Drag game object
gameObject .setInteractive({ draggable: true }) .on('dragstart', function(pointer, dragX, dragY){ // ... }, scope); .on('drag', function(pointer, dragX, dragY){ gameObject.setPosition(dragX, dragY); }, scope); .on('dragend', function(pointer, dragX, dragY, dropped){ // ... }, scope);
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 game object
gameObject.setInteractive(shape, callback);
- Circle
- shape :
new Phaser.Geom.Circle(x, y, radius)
- callback :
Phaser.Geom.Circle.Contains
- shape :
- Ellipse
- shape :
new Phaser.Geom.Ellipse(x, y, width, height)
- callback :
Phaser.Geom.Ellipse.Contains
- shape :
- Rectangle
- shape :
new Phaser.Geom.Rectangle(x, y, width, height)
- callback :
Phaser.Geom.Rectangle.Contains
- shape :
- Triangle
- shape :
new Phaser.Geom.Triangle(x1, y1, x2, y2, x3, y3)
- callback :
Phaser.Geom.Triangle.Contains
- shape :
- Polygon
- shape :
new Phaser.Geom.Polygon(points)
- callback :
Phaser.Geom.Polygon.Contains
- shape :
- Hexagon
- shape :
new Phaser.Geom.rexHexagon(x, y, size, type)
- callback :
Phaser.Geom.Polygon.Contains
- shape :
- Rhombus
- shape :
new Phaser.Geom.rexRhombus(x, y, width, height)
- callback :
Phaser.Geom.Polygon.Contains
- shape :
- Note:
x
,y
relate to the top-left of the gameObject.
- Circle
- Set hit area from input plugin
scene.input.setHitArea(gameObjects, shape, callback);
- Circle
scene.input.setHitAreaCircle(gameObjects, x, y, radius); // scene.input.setHitAreaCircle(gameObjects, x, y, radius, callback); // callback = Circle.Contains
- Ellipse
scene.input.setHitAreaEllipse(gameObjects, x, y, width, height); // scene.input.setHitAreaEllipse(gameObjects, x, y, width, height, callback); // callback = Ellipse.Contains
- Rectangle
scene.input.setHitAreaRectangle(gameObjects, x, y, width, height); // scene.input.setHitAreaRectangle(gameObjects, x, y, width, height, callback); // callback = Rectangle.Contains
- Triangle
scene.input.setHitAreaTriangle(gameObjects, x1, y1, x2, y2, x3, y3); // scene.input.setHitAreaTriangle(gameObjects, x1, y1, x2, y2, x3, y3, callback); // callback = Triangle.Contains
- Note:
x
,y
relate to the top-left of the gameObject.
- Circle
- Set interactive configuration
gameObject.setInteractive({ hitArea: shape, hitAreaCallback: callback, hitAreaDebug: shape, draggable: false, dropZone: false, useHandCursor: false, cursor: CSSString, pixelPerfect: false, alphaTolerance: 1 });
- 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 }
shape
: Hit area objectx
,y
: Local position of texture.gameObject
: Game object.
hitAreaDebug
: Debug shape.
- Dragging
draggable
:true
- Drop zone
dropZone
:true
- Cursor
cursor
: CSS stringuseHandCursor
:true
- Hit area
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();
- 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);
Each scene can has its own scene.input.topOnly
setting.
Touch events¶
Trigger these events from top scene to bottom scene.
- Events on touched Game object
gameObject.on('pointerdown', function(pointer, localX, localY, event){ /* ... */ }, scope); gameObject.on('pointerup', function(pointer, localX, localY, event){ /* ... */ }, scope); gameObject.on('pointermove', function(pointer, localX, localY, event){ /* ... */ }, scope); gameObject.on('pointerover', function(pointer, localX, localY, event){ /* ... */ }, scope); gameObject.on('pointerout', function(pointer, event){ /* ... */ }, scope);
- Cancel remaining touched events
function(pointer, localX, localY, event) { event.stopPropagation(); }
- Cancel remaining touched events
- Event on input plugin for each touched Game object
scene.input.on('gameobjectdown', function(pointer, gameObject, event){ /* ... */ }, scope); scene.input.on('gameobjectup', function(pointer, gameObject, event){ /* ... */ }, scope); scene.input.on('gameobjectmove', function(pointer, gameObject, event){ /* ... */ }, scope); scene.input.on('gameobjectover', function(pointer, gameObject, event){ /* ... */ }, scope); scene.input.on('gameobjectout', function(pointer, gameObject, event){ /* ... */ }, scope);
- Cancel remaining touched events
function(pointer, gameObject, event) { event.stopPropagation(); }
- Cancel remaining touched events
- Events to get all touched Game Objects
scene.input.on('pointerdown', function(pointer, currentlyOver){ /* ... */ }, scope); scene.input.on('pointerdownoutside', function(pointer){ /* ... */ }, scope); scene.input.on('pointerup', function(pointer, currentlyOver){ /* ... */ }, scope); scene.input.on('pointerupoutside', function(pointer){ /* ... */ }, scope); scene.input.on('pointermove', function(pointer, currentlyOver){ /* ... */ }, scope); scene.input.on('pointerover', function(pointer, justOver){ /* ... */ }, scope); scene.input.on('pointerout', function(pointer, justOut){ /* ... */ }, scope); scene.input.on('gameout', function(timeStamp, domEvent){ /* ... */ }, scope); scene.input.on('gameover', function(timeStamp, domEvent){ /* ... */ }, scope);
Game canvas¶
scene.input.on('gameout', function(timeStamp, event){ /* ... */ }, scope);
scene.input.on('gameover', function(timeStamp, event){ /* ... */ }, scope);
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){ /* ... */ }, scope);
gameObject.on('drag', function(pointer, dragX, dragY){ /* ... */ }, scope);
gameObject.on('dragend', function(pointer, dragX, dragY, dropped){ /* ... */ }, scope);
scene.input.on('dragstart', function(pointer, gameObject){ /* ... */ }, scope);
scene.input.on('drag', function(pointer, gameObject, dragX, dragY){ /* ... */ }, scope);
scene.input.on('dragend', function(pointer, gameObject, dropped){ /* ... */ }, scope);
dropped
:'dragend'
and also'drop'
.
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){ /* ... */ }, scope);
gameObject.on('dragenter', function(pointer, target){ /* ... */ }, scope);
gameObject.on('dragover', function(pointer, target){ /* ... */ }, scope);
gameObject.on('dragleave', function(pointer, target){ /* ... */ }, scope);
scene.input.on('drop', function(pointer, gameObject, target){ /* ... */ }, scope);
scene.input.on('dragenter', function(pointer, gameObject, target){ /* ... */ }, scope);
scene.input.on('dragover', function(pointer, gameObject, target){ /* ... */ }, scope);
scene.input.on('dragleave', function(pointer, gameObject, target){ /* ... */ }, scope);
First event of all¶
scene.input.on('preupdate', function() { /* ... */ }, scope);
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;
1
in desktop2
in touch device. (0
for mouse,1
for 1 touch pointer)
Pointer¶
- Position
- Current touching
- Position in screen :
pointer.x
,pointer.y
- Position in camera :
- Single camera :
var worldX = pointer.worldX; var worldY = pointer.worldY;
- Multiple cameras :
var worldXY = pointer.positionToCamera(camera); // worldXY: {x, y} // var worldXY = pointer.positionToCamera(camera, worldXY); var worldX = worldXY.x; var worldY = worldXY.y;
- Single camera :
- Position of previous moving :
pointer.prevPosition.x
,pointer.prevPosition.y
- Updating when pointer-down, potiner-move, or pointer-up.
- Interpolated position :
var points = pointer.getInterpolatedPosition(step); // var out = pointer.getInterpolatedPosition(step, out);
- Position in screen :
- Drag
- Touching start :
pointer.downX
,pointer.downY
- Touching end :
pointer.upX
,pointer.upY
- Drag distance between pointer-down to latest pointer :
pointer.getDistance()
- Horizontal drag distance :
pointer.getDistanceX()
- Vertical drag distance :
pointer.getDistanceY()
- Horizontal drag distance :
- Drag angle :
pointer.getAngle()
- Touching start :
- Current touching
- Time
- Touching start :
pointer.downTime
- Touching end :
pointer.upTime
- Drag :
pointer.getDuration()
- Touching start :
- Touch state
- Is touching/any button down :
pointer.isDown
- Is primary button down :
pointer.primaryDown
- Is touching/any button down :
- Button state :
pointer.button
- On Touch devices the value is always
0
.
- On Touch devices the value is always
- Button down
- No button down :
pointer.noButtonDown()
- Is primary (left) button down :
pointer.leftButtonDown()
- Is secondary (right) button down :
pointer.rightButtonDown()
- Is middle (mouse wheel) button down :
pointer.middleButtonDown()
- Is back button down :
pointer.backButtonDown()
- Is forward button down :
pointer.forwardButtonDown()
- No button down :
- Button released
- Is primary (left) button released :
pointer.leftButtonReleased()
- Is secondary (right) button released :
pointer.rightButtonReleased()
- Is middle (mouse wheel) button released :
pointer.middleButtonReleased()
- Is back button released :
pointer.backButtonReleased()
- Is forward button released :
pointer.forwardButtonReleased()
- Is primary (left) button released :
- Index in
scene.input.manager.pointers
:pointer.id
- Motion
- Angle:
pointer.angle
- Distance:
pointer.distance
- Velocity:
pointer.velocity
pointer.velocity.x
,`pointer.velocity.y
- Angle:
Input object¶
gameObject.input
: Game object's input object.gameObject.input.localX
,gameObject.input.localY
: Pointer to local position of texture.gameObject.input.dragStartX
,gameObject.input.dragStartY
: The x/y coordinate of the Game Object that owns this Interactive Object when the drag started.gameObject.input.dragStartXGlobal
,gameObject.input.dragStartYGlobal
: The x/y coordinate that the Pointer started dragging this Interactive Object from.gameObject.input.dragX
,gameObject.input.dragY
: The x/y coordinate that this Interactive Object is currently being dragged to.
Smooth¶
Get touch position from interpolation of previous touch position and current touch position.
Touch-position = (current-touch-position * smooth-factor) + (previous-touch-position * (1 - smooth-factor))
- Set smooth factor. In game configuration
var config = { // .... input: { smoothFactor: 0 } }
- Get touch position
var x = pointer.x; var y = pointer.y; var worldX = pointer.worldX; var worldY = pointer.worldY;
Debug¶
- Enable, draw shape of (shape) hit area.
scene.input.enableDebug(gameObject); // scene.input.enableDebug(gameObject, color);
- Disable
scene.input.removeDebug(gameObject);
- Get debug shape game object
var shape = gameObject.input.hitAreaDebug;
Poll rate¶
- Poll when touches moved, or updated. Default behavior.
scene.input.setPollOnMove();
- Poll every tick.
scene.input.setPollAlways();
- Set poll rate.
scene.input.setPollRate(rate);