Merge pull request phaserjs#4129 from samme/docs/events

Docs for input and physics events

Author: photonstorm

src/gameobjects/GameObject.js

@@ -531,8 +531,9 @@ var GameObject = new Class({
      * Game Object Pool instead of destroying it, as destroyed objects cannot be resurrected.
      *
      * @method Phaser.GameObjects.GameObject#destroy
+     * @fires Phaser.GameObjects.GameObject#destroyEvent
      * @since 3.0.0
-     * 
+     *
      * @param {boolean} [fromScene=false] - Is this Game Object being destroyed as the result of a Scene shutdown?
      */
     destroy: function (fromScene)
@@ -607,3 +608,8 @@ var GameObject = new Class({
 GameObject.RENDER_MASK = 15;
 
 module.exports = GameObject;
+
+/**
+ * The Game Object will be destroyed.
+ * @event Phaser.GameObjects.GameObject#destroyEvent
+ */

src/input/InputPlugin.js

@@ -748,6 +748,9 @@ var InputPlugin = new Class({
      *
      * @method Phaser.Input.InputPlugin#processDownEvents
      * @private
+     * @fires Phaser.GameObjects.GameObject#pointerdownEvent
+     * @fires Phaser.Input.InputPlugin#gameobjectdownEvent
+     * @fires Phaser.Input.InputPlugin#pointerdownEvent
      * @since 3.0.0
      *
      * @param {Phaser.Input.Pointer} pointer - The Pointer being tested.
@@ -809,6 +812,20 @@ var InputPlugin = new Class({
      *
      * @method Phaser.Input.InputPlugin#processDragEvents
      * @private
+     * @fires Phaser.GameObjects.GameObject#dragendEvent
+     * @fires Phaser.GameObjects.GameObject#dragenterEvent
+     * @fires Phaser.GameObjects.GameObject#dragEvent
+     * @fires Phaser.GameObjects.GameObject#dragleaveEvent
+     * @fires Phaser.GameObjects.GameObject#dragoverEvent
+     * @fires Phaser.GameObjects.GameObject#dragstartEvent
+     * @fires Phaser.GameObjects.GameObject#dropEvent
+     * @fires Phaser.Input.InputPlugin#dragendEvent
+     * @fires Phaser.Input.InputPlugin#dragenterEvent
+     * @fires Phaser.Input.InputPlugin#dragEvent
+     * @fires Phaser.Input.InputPlugin#dragleaveEvent
+     * @fires Phaser.Input.InputPlugin#dragoverEvent
+     * @fires Phaser.Input.InputPlugin#dragstartEvent
+     * @fires Phaser.Input.InputPlugin#dropEvent
      * @since 3.0.0
      *
      * @param {Phaser.Input.Pointer} pointer - The Pointer to check against the Game Objects.
@@ -1077,6 +1094,8 @@ var InputPlugin = new Class({
      *
      * @method Phaser.Input.InputPlugin#processMoveEvents
      * @private
+     * @fires Phaser.GameObjects.GameObject#pointermoveEvent
+     * @fires Phaser.Input.InputPlugin#gameobjectmoveEvent
      * @since 3.0.0
      *
      * @param {Phaser.Input.Pointer} pointer - The pointer to check for events against.
@@ -1142,6 +1161,10 @@ var InputPlugin = new Class({
      *
      * @method Phaser.Input.InputPlugin#processOverOutEvents
      * @private
+     * @fires Phaser.GameObjects.GameObject#pointeroutEvent
+     * @fires Phaser.GameObjects.GameObject#pointeroverEvent
+     * @fires Phaser.Input.InputPlugin#gameobjectoutEvent
+     * @fires Phaser.Input.InputPlugin#gameobjectoverEvent
      * @since 3.0.0
      *
      * @param {Phaser.Input.Pointer} pointer - The pointer to check for events against.
@@ -1312,6 +1335,8 @@ var InputPlugin = new Class({
      *
      * @method Phaser.Input.InputPlugin#processUpEvents
      * @private
+     * @fires Phaser.GameObjects.GameObject#pointerupEvent
+     * @fires Phaser.Input.InputPlugin#gameobjectupEvent
      * @since 3.0.0
      *
      * @param {Phaser.Input.Pointer} pointer - The pointer to check for events against.
@@ -2493,3 +2518,161 @@ var InputPlugin = new Class({
 PluginCache.register('InputPlugin', InputPlugin, 'input');
 
 module.exports = InputPlugin;
+
+/**
+ * A Pointer stopped dragging the Game Object.
+ * @event Phaser.GameObjects.GameObject#dragendEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer that was dragging this Game Object.
+ * @param {number} dragX - The x coordinate where the Pointer is dragging the object, in world space.
+ * @param {number} dragY - The y coordinate where the Pointer is dragging the object, in world space.
+ * @param {boolean} dropped - True if the object was dropped within its drop target. (In that case, 'drop' was emitted before this.)
+ *
+ * The Game Object entered its drop target, while being dragged.
+ * @event Phaser.GameObjects.GameObject#dragenterEvent
+ * @param {Phaser.Input.Pointer} pointer - The pointer dragging this Game Object.
+ * @param {Phaser.GameObjects.GameObject} target - The Game Object's drop target.
+ *
+ * The Game Object is being dragged by a Pointer.
+ * @event Phaser.GameObjects.GameObject#dragEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer dragging this Game Object.
+ * @param {number} dragX - The x coordinate where the Pointer is dragging the object, in world space.
+ * @param {number} dragY - The y coordinate where the Pointer is dragging the object, in world space.
+ *
+ * The Game Object left its drop target, while being dragged.
+ * @event Phaser.GameObjects.GameObject#dragleaveEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer dragging this Game Object.
+ * @param {Phaser.GameObjects.GameObject} target - The Game Object's drop target.
+ *
+ * The Game Object is within its drop target, while being dragged.
+ * @event Phaser.GameObjects.GameObject#dragoverEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer dragging this Game Object.
+ * @param {Phaser.GameObjects.GameObject} target - The Game Object's drop target.
+ *
+ * A Pointer began dragging the Game Object.
+ * @event Phaser.GameObjects.GameObject#dragstartEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer dragging this Game Object.
+ * @param {number} dragX - The x coordinate where the Pointer is dragging the object, in world space.
+ * @param {number} dragY - The y coordinate where the Pointer is dragging the object, in world space.
+ *
+ * The Game Object was released on its drop target, after being dragged.
+ * @event Phaser.GameObjects.GameObject#dropEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer dragging this Game Object.
+ * @param {Phaser.GameObjects.GameObject} target - The Game Object's drop target.
+ *
+ * A Pointer was pressed on the Game Object.
+ * @event Phaser.GameObjects.GameObject#pointerdownEvent
+ * @param {Phaser.Input.Pointer}
+ * @param {number} localX - The x coordinate that the Pointer interacted with this object on, relative to the Game Object's top-left position.
+ * @param {number} localY - The y coordinate that the Pointer interacted with this object on, relative to the Game Object's top-left position.
+ * @param {object} eventContainer
+ *
+ * A Pointer moved while over the Game Object.
+ * @event Phaser.GameObjects.GameObject#pointermoveEvent
+ * @param {Phaser.Input.Pointer}
+ * @param {number} localX - The x coordinate that the Pointer interacted with this object on, relative to the Game Object's top-left position.
+ * @param {number} localY - The y coordinate that the Pointer interacted with this object on, relative to the Game Object's top-left position.
+ * @param {object} eventContainer
+ *
+ * A Pointer left the Game Object, after being over it.
+ * @event Phaser.GameObjects.GameObject#pointeroutEvent
+ * @param {Phaser.Input.Pointer} - The Pointer.
+ * @param {object} eventContainer
+ *
+ * A Pointer entered the Game Object, after being outside it.
+ * @event Phaser.GameObjects.GameObject#pointeroverEvent
+ * @param {Phaser.Input.Pointer} - The Pointer.
+ * @param {number} localX - The x coordinate that the Pointer interacted with this object on, relative to the Game Object's top-left position.
+ * @param {number} localY - The y coordinate that the Pointer interacted with this object on, relative to the Game Object's top-left position.
+ * @param {object} eventContainer
+ *
+ * A Pointer was released while over the Game Object, after being pressed on the Game Object.
+ * @event Phaser.GameObjects.GameObject#pointerupEvent
+ * @param {Phaser.Input.Pointer} - The Pointer.
+ * @param {number} localX - The x coordinate that the Pointer interacted with this object on, relative to the Game Object's top-left position.
+ * @param {number} localY - The y coordinate that the Pointer interacted with this object on, relative to the Game Object's top-left position.
+ * @param {object} eventContainer
+ */
+
+/**
+ * A Game Object was released, after being dragged.
+ * @event Phaser.Input.InputPlugin#dragendEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer.
+ * @param {Phaser.GameObjects.GameObject} gameObject - The Game Object.
+ * @param {boolean} dropped - True if the Game Object was dropped onto its drop target.
+ *
+ * A dragged Game Object entered it drop target.
+ * @event Phaser.Input.InputPlugin#dragenterEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer.
+ * @param {Phaser.GameObjects.GameObject} gameObject - The Game Object.
+ * @param {Phaser.GameObjects.GameObject} target - The drop target.
+ *
+ * A Game Object is being dragged by a Pointer.
+ * @event Phaser.Input.InputPlugin#dragEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer.
+ * @param {Phaser.GameObjects.GameObject} gameObject - The Game Object.
+ * @param {number} dragX - The x coordinate where the Pointer is dragging the object, in world space.
+ * @param {number} dragY - The y coordinate where the Pointer is dragging the object, in world space.
+ *
+ * A dragged Game Object left its drop target.
+ * @event Phaser.Input.InputPlugin#dragleaveEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer.
+ * @param {Phaser.GameObjects.GameObject} gameObject - The Game Object.
+ * @param {?Phaser.GameObjects.GameObject} target - The drop target.
+ *
+ * A dragged Game Object is within its drop target.
+ * @event Phaser.Input.InputPlugin#dragoverEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer.
+ * @param {Phaser.GameObjects.GameObject} gameObject - The Game Object.
+ * @param {?Phaser.GameObjects.GameObject} target - The drop target.
+ *
+ * A Pointer started dragging a Game Object.
+ * @event Phaser.Input.InputPlugin#dragstartEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer.
+ * @param {Phaser.GameObjects.GameObject} gameObject - The Game Object.
+ *
+ * A Game Object was dropped within its drop target.
+ * @event Phaser.Input.InputPlugin#dropEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer.
+ * @param {Phaser.GameObjects.GameObject} gameObject - The Game Object.
+ * @param {?Phaser.GameObjects.GameObject} target - The drop target.
+ *
+ * A Pointer was pressed while over a Game Object.
+ * @event Phaser.Input.InputPlugin#gameobjectdownEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer.
+ * @param {Phaser.GameObjects.GameObject} gameObject - The Game Object.
+ * @param {object} eventContainer
+ *
+ * A Pointer moved while over a Game Object.
+ * @event Phaser.Input.InputPlugin#gameobjectmoveEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer.
+ * @param {Phaser.GameObjects.GameObject} gameObject - The Game Object.
+ * @param {object} eventContainer
+ *
+ * A Pointer moved off of a Game Object, after being over it.
+ * @event Phaser.Input.InputPlugin#gameobjectoutEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer.
+ * @param {Phaser.GameObjects.GameObject} gameObject - The Game Object.
+ * @param {object} eventContainer
+ *
+ * A Pointer moved onto a Game Object, after being off it.
+ * @event Phaser.Input.InputPlugin#gameobjectoverEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer.
+ * @param {Phaser.GameObjects.GameObject} gameObject - The Game Object.
+ * @param {object} eventContainer
+ *
+ * A Pointer was released while over a Game Object, after being pressed on the Game Object.
+ * @event Phaser.Input.InputPlugin#gameobjectupEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer.
+ * @param {Phaser.GameObjects.GameObject} gameObject - The Game Object.
+ * @param {object} eventContainer
+ *
+ * A Pointer was pressed down.
+ * @event Phaser.Input.InputPlugin#pointerdownEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer.
+ * @param {Phaser.GameObjects.GameObject[]} currentlyOver - All the Game Objects currently under the Pointer.
+ *
+ * A Pointer was released, after being pressed down.
+ * @event Phaser.Input.InputPlugin#pointerupEvent
+ * @param {Phaser.Input.Pointer} pointer - The Pointer.
+ * @param {Phaser.GameObjects.GameObject[]} currentlyOver - All the Game Objects currently under the Pointer.
+ */

src/physics/arcade/Body.js

@@ -401,7 +401,7 @@ var Body = new Class({
          * @type {boolean}
          * @default false
          * @since 3.0.0
-         * @see Phaser.Physics.Arcade.World#event:worldbounds
+         * @see Phaser.Physics.Arcade.World#worldboundsEvent
          */
         this.onWorldBounds = false;
 
@@ -412,7 +412,7 @@ var Body = new Class({
          * @type {boolean}
          * @default false
          * @since 3.0.0
-         * @see Phaser.Physics.Arcade.World#event:collide
+         * @see Phaser.Physics.Arcade.World#collideEvent
          */
         this.onCollide = false;
 
@@ -423,7 +423,7 @@ var Body = new Class({
          * @type {boolean}
          * @default false
          * @since 3.0.0
-         * @see Phaser.Physics.Arcade.World#event:overlap
+         * @see Phaser.Physics.Arcade.World#overlapEvent
          */
         this.onOverlap = false;
 

src/physics/arcade/World.js

@@ -32,36 +32,47 @@ var Vector2 = require('../../math/Vector2');
 var Wrap = require('../../math/Wrap');
 
 /**
- * @event Phaser.Physics.Arcade.World#pause
+ * The physics simulation paused.
+ * @event Phaser.Physics.Arcade.World#pauseEvent
  */
 
 /**
- * @event Phaser.Physics.Arcade.World#resume
+ * The physics simulation resumed (from a paused state).
+ * @event Phaser.Physics.Arcade.World#resumeEvent
  */
 
 /**
- * @event Phaser.Physics.Arcade.World#collide
+ * Two Game Objects collided.
+ * This event is emitted only if at least one body has `onCollide` enabled.
+ * @event Phaser.Physics.Arcade.World#collideEvent
  * @param {Phaser.GameObjects.GameObject} gameObject1
  * @param {Phaser.GameObjects.GameObject} gameObject2
  * @param {Phaser.Physics.Arcade.Body|Phaser.Physics.Arcade.StaticBody} body1
  * @param {Phaser.Physics.Arcade.Body|Phaser.Physics.Arcade.StaticBody} body2
+ * @see Phaser.Physics.Arcade.Body#onCollide
  */
 
 /**
- * @event Phaser.Physics.Arcade.World#overlap
+ * Two Game Objects overlapped.
+ * This event is emitted only if at least one body has `onOverlap` enabled.
+ * @event Phaser.Physics.Arcade.World#overlapEvent
  * @param {Phaser.GameObjects.GameObject} gameObject1
  * @param {Phaser.GameObjects.GameObject} gameObject2
  * @param {Phaser.Physics.Arcade.Body|Phaser.Physics.Arcade.StaticBody} body1
  * @param {Phaser.Physics.Arcade.Body|Phaser.Physics.Arcade.StaticBody} body2
+ * @see Phaser.Physics.Arcade.Body#onOverlap
  */
 
 /**
- * @event Phaser.Physics.Arcade.World#worldbounds
+ * A Body contacted the world boundary.
+ * This event is emitted only if the body has `onWorldBounds` enabled.
+ * @event Phaser.Physics.Arcade.World#worldboundsEvent
  * @param {Phaser.Physics.Arcade.Body} body
  * @param {boolean} up
  * @param {boolean} down
  * @param {boolean} left
  * @param {boolean} right
+ * @see Phaser.Physics.Arcade.Body#onWorldBounds
  */
 
 /**
@@ -853,7 +864,7 @@ var World = new Class({
      * checks.
      *
      * @method Phaser.Physics.Arcade.World#pause
-     * @fires Phaser.Physics.Arcade.World#pause
+     * @fires Phaser.Physics.Arcade.World#pauseEvent
      * @since 3.0.0
      *
      * @return {Phaser.Physics.Arcade.World} This World object.
@@ -871,7 +882,7 @@ var World = new Class({
      * Resumes the simulation, if paused.
      *
      * @method Phaser.Physics.Arcade.World#resume
-     * @fires Phaser.Physics.Arcade.World#resume
+     * @fires Phaser.Physics.Arcade.World#resumeEvent
      * @since 3.0.0
      *
      * @return {Phaser.Physics.Arcade.World} This World object.
@@ -1361,8 +1372,8 @@ var World = new Class({
      * Separates two Bodies.
      *
      * @method Phaser.Physics.Arcade.World#separate
-     * @fires Phaser.Physics.Arcade.World#collide
-     * @fires Phaser.Physics.Arcade.World#overlap
+     * @fires Phaser.Physics.Arcade.World#collideEvent
+     * @fires Phaser.Physics.Arcade.World#overlapEvent
      * @since 3.0.0
      *
      * @param {Phaser.Physics.Arcade.Body} body1 - The first Body to be separated.
@@ -1476,8 +1487,8 @@ var World = new Class({
      * Separates two Bodies, when both are circular.
      *
      * @method Phaser.Physics.Arcade.World#separateCircle
-     * @fires Phaser.Physics.Arcade.World#collide
-     * @fires Phaser.Physics.Arcade.World#overlap
+     * @fires Phaser.Physics.Arcade.World#collideEvent
+     * @fires Phaser.Physics.Arcade.World#overlapEvent
      * @since 3.0.0
      *
      * @param {Phaser.Physics.Arcade.Body} body1 - The first Body to be separated.
@@ -2132,8 +2143,10 @@ var World = new Class({
      * Please use Phaser.Physics.Arcade.World#collide instead.
      *
      * @method Phaser.Physics.Arcade.World#collideSpriteVsTilemapLayer
-     * @fires Phaser.Physics.Arcade.World#collide
-     * @fires Phaser.Physics.Arcade.World#overlap
+     * @fires Phaser.GameObjects.GameObject#collideEvent
+     * @fires Phaser.GameObjects.GameObject#overlapEvent
+     * @fires Phaser.Physics.Arcade.World#collideEvent
+     * @fires Phaser.Physics.Arcade.World#overlapEvent
      * @since 3.0.0
      *
      * @param {Phaser.GameObjects.GameObject} sprite - The first object to check for collision.
@@ -2363,3 +2376,23 @@ var World = new Class({
 });
 
 module.exports = World;
+
+/**
+ * A physics-enabled Game Object collided with a Tile.
+ * This event is emitted only if the Game Object's body has `onCollide` enabled.
+ * @event Phaser.GameObjects.GameObject#collideEvent
+ * @param {Phaser.GameObjects.GameObject} gameObject
+ * @param {Phaser.Tilemaps.Tile} tile
+ * @param {Phaser.Physics.Arcade.Body|Phaser.Physics.Arcade.StaticBody} body
+ * @see Phaser.Physics.Arcade.Body#onCollide
+ */
+
+/**
+ * A physics-enabled Game Object overlapped with a Tile.
+ * This event is emitted only if the Game Object's body has `onOverlap` enabled.
+ * @event Phaser.GameObjects.GameObject#overlapEvent
+ * @param {Phaser.GameObjects.GameObject} gameObject
+ * @param {Phaser.Tilemaps.Tile} tile
+ * @param {Phaser.Physics.Arcade.Body|Phaser.Physics.Arcade.StaticBody} body
+ * @see Phaser.Physics.Arcade.Body#onOverlap
+ */