Arcade Physics Events

Author: photonstorm

CHANGELOG.md

@@ -299,6 +299,8 @@ one set of bindings ever created, which makes things a lot cleaner.
 * The Keyboard Plugin `keyup` dynamic event string has changed from `keyup_` to `keyup-` to keep it consistent with other keyed events. Note the change from `_` to `-`.
 * The `texturesready` event emitted by the Texture Manager has been renamed to `ready`.
 * The `loadcomplete` event emitted by the Loader Plugin has been renamed to `postprocess` to be reflect what it's used for.
+* Game Objects used to emit a `collide` event if they had an Arcade Physics Body with `onCollide` set, that collided with a Tile. This has changed. The event has been renamed to `tilecollide`. You should now listen for this event from the Arcade Physics World itself: `this.physics.world.on('tilecollide')`. The Game Object will not emit the event any more.
+* Game Objects used to emit a `overlap` event if they had an Arcade Physics Body with `onOverlap` set, that overlapped with a Tile. This has changed. The event has been renamed to `tileoverlap`. You should now listen for this event from the Arcade Physics World itself: `this.physics.world.on('tileoverlap')`. The Game Object will not emit the event any more.
 
 ### Examples and TypeScript
 

src/physics/arcade/Body.js

@@ -7,6 +7,7 @@
 var CircleContains = require('../../geom/circle/Contains');
 var Class = require('../../utils/Class');
 var CONST = require('./const');
+var Events = require('./events');
 var RadToDeg = require('../../math/RadToDeg');
 var Rectangle = require('../../geom/rectangle/Rectangle');
 var RectangleContains = require('../../geom/rectangle/Contains');
@@ -946,7 +947,7 @@ var Body = new Class({
 
             if (this.collideWorldBounds && this.checkWorldBounds() && this.onWorldBounds)
             {
-                this.world.emit('worldbounds', this, this.blocked.up, this.blocked.down, this.blocked.left, this.blocked.right);
+                this.world.emit(Events.WORLD_BOUNDS, this, this.blocked.up, this.blocked.down, this.blocked.left, this.blocked.right);
             }
         }
 

src/physics/arcade/World.js

@@ -11,6 +11,7 @@ var Collider = require('./Collider');
 var CONST = require('./const');
 var DistanceBetween = require('../../math/distance/DistanceBetween');
 var EventEmitter = require('eventemitter3');
+var Events = require('./events');
 var FuzzyEqual = require('../../math/fuzzy/Equal');
 var FuzzyGreaterThan = require('../../math/fuzzy/GreaterThan');
 var FuzzyLessThan = require('../../math/fuzzy/LessThan');
@@ -31,50 +32,6 @@ var TransformMatrix = require('../../gameobjects/components/TransformMatrix');
 var Vector2 = require('../../math/Vector2');
 var Wrap = require('../../math/Wrap');
 
-/**
- * The physics simulation paused.
- * @event Phaser.Physics.Arcade.World#pauseEvent
- */
-
-/**
- * The physics simulation resumed (from a paused state).
- * @event Phaser.Physics.Arcade.World#resumeEvent
- */
-
-/**
- * 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
- */
-
-/**
- * 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
- */
-
-/**
- * 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
- */
-
 /**
  * @typedef {object} ArcadeWorldConfig
  *
@@ -864,7 +821,7 @@ var World = new Class({
      * checks.
      *
      * @method Phaser.Physics.Arcade.World#pause
-     * @fires Phaser.Physics.Arcade.World#pauseEvent
+     * @fires Phaser.Physics.Arcade.Events#PAUSE
      * @since 3.0.0
      *
      * @return {Phaser.Physics.Arcade.World} This World object.
@@ -873,7 +830,7 @@ var World = new Class({
     {
         this.isPaused = true;
 
-        this.emit('pause');
+        this.emit(Events.PAUSE);
 
         return this;
     },
@@ -882,7 +839,7 @@ var World = new Class({
      * Resumes the simulation, if paused.
      *
      * @method Phaser.Physics.Arcade.World#resume
-     * @fires Phaser.Physics.Arcade.World#resumeEvent
+     * @fires Phaser.Physics.Arcade.Events#RESUME
      * @since 3.0.0
      *
      * @return {Phaser.Physics.Arcade.World} This World object.
@@ -891,7 +848,7 @@ var World = new Class({
     {
         this.isPaused = false;
 
-        this.emit('resume');
+        this.emit(Events.RESUME);
 
         return this;
     },
@@ -1372,8 +1329,8 @@ var World = new Class({
      * Separates two Bodies.
      *
      * @method Phaser.Physics.Arcade.World#separate
-     * @fires Phaser.Physics.Arcade.World#collideEvent
-     * @fires Phaser.Physics.Arcade.World#overlapEvent
+     * @fires Phaser.Physics.Arcade.Events#COLLIDE
+     * @fires Phaser.Physics.Arcade.Events#OVERLAP
      * @since 3.0.0
      *
      * @param {Phaser.Physics.Arcade.Body} body1 - The first Body to be separated.
@@ -1466,7 +1423,7 @@ var World = new Class({
         {
             if (overlapOnly && (body1.onOverlap || body2.onOverlap))
             {
-                this.emit('overlap', body1.gameObject, body2.gameObject, body1, body2);
+                this.emit(Events.OVERLAP, body1.gameObject, body2.gameObject, body1, body2);
             }
             else
             {
@@ -1475,7 +1432,7 @@ var World = new Class({
 
                 if (body1.onCollide || body2.onCollide)
                 {
-                    this.emit('collide', body1.gameObject, body2.gameObject, body1, body2);
+                    this.emit(Events.COLLIDE, body1.gameObject, body2.gameObject, body1, body2);
                 }
             }
         }
@@ -1487,8 +1444,8 @@ var World = new Class({
      * Separates two Bodies, when both are circular.
      *
      * @method Phaser.Physics.Arcade.World#separateCircle
-     * @fires Phaser.Physics.Arcade.World#collideEvent
-     * @fires Phaser.Physics.Arcade.World#overlapEvent
+     * @fires Phaser.Physics.Arcade.Events#COLLIDE
+     * @fires Phaser.Physics.Arcade.Events#OVERLAP
      * @since 3.0.0
      *
      * @param {Phaser.Physics.Arcade.Body} body1 - The first Body to be separated.
@@ -1561,7 +1518,7 @@ var World = new Class({
         {
             if (overlap !== 0 && (body1.onOverlap || body2.onOverlap))
             {
-                this.emit('overlap', body1.gameObject, body2.gameObject, body1, body2);
+                this.emit(Events.OVERLAP, body1.gameObject, body2.gameObject, body1, body2);
             }
 
             //  return true if there was some overlap, otherwise false
@@ -1673,7 +1630,7 @@ var World = new Class({
 
         if (body1.onCollide || body2.onCollide)
         {
-            this.emit('collide', body1.gameObject, body2.gameObject, body1, body2);
+            this.emit(Events.COLLIDE, body1.gameObject, body2.gameObject, body1, body2);
         }
 
         //  sync changes back to the bodies
@@ -2143,10 +2100,8 @@ var World = new Class({
      * Please use Phaser.Physics.Arcade.World#collide instead.
      *
      * @method Phaser.Physics.Arcade.World#collideSpriteVsTilemapLayer
-     * @fires Phaser.GameObjects.GameObject#collideEvent
-     * @fires Phaser.GameObjects.GameObject#overlapEvent
-     * @fires Phaser.Physics.Arcade.World#collideEvent
-     * @fires Phaser.Physics.Arcade.World#overlapEvent
+     * @fires Phaser.Physics.Arcade.Events#TILE_COLLIDE
+     * @fires Phaser.Physics.Arcade.Events#TILE_OVERLAP
      * @since 3.0.0
      *
      * @param {Phaser.GameObjects.GameObject} sprite - The first object to check for collision.
@@ -2232,11 +2187,11 @@ var World = new Class({
 
                 if (overlapOnly && body.onOverlap)
                 {
-                    sprite.emit('overlap', body.gameObject, tile, body, null);
+                    this.emit(Events.TILE_OVERLAP, body.gameObject, tile, body);
                 }
                 else if (body.onCollide)
                 {
-                    sprite.emit('collide', body.gameObject, tile, body, null);
+                    this.emit(Events.TILE_COLLIDE, body.gameObject, tile, body);
                 }
 
                 //  sync changes back to the body
@@ -2376,23 +2331,3 @@ 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
- */

src/physics/arcade/events/COLLIDE_EVENT.js

@@ -0,0 +1,26 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Arcade Physics World Collide Event.
+ * 
+ * This event is dispatched by an Arcade Physics World instance if two bodies collide _and_ at least
+ * one of them has their [onCollide]{Phaser.Physics.Arcade.Body#onCollide} property set to `true`.
+ * 
+ * It provides an alternative means to handling collide events rather than using the callback approach.
+ * 
+ * Listen to it from a Scene using: `this.physics.world.on('collide', listener)`.
+ * 
+ * Please note that 'collide' and 'overlap' are two different things in Arcade Physics.
+ *
+ * @event Phaser.Physics.Arcade.Events#COLLIDE
+ * 
+ * @param {Phaser.GameObjects.GameObject} gameObject1 - The first Game Object involved in the collision. This is the parent of `body1`.
+ * @param {Phaser.GameObjects.GameObject} gameObject2 - The second Game Object involved in the collision. This is the parent of `body2`.
+ * @param {Phaser.Physics.Arcade.Body|Phaser.Physics.Arcade.StaticBody} body1 - The first Physics Body involved in the collision.
+ * @param {Phaser.Physics.Arcade.Body|Phaser.Physics.Arcade.StaticBody} body2 - The second Physics Body involved in the collision.
+ */
+module.exports = 'collide';

src/physics/arcade/events/OVERLAP_EVENT.js

@@ -0,0 +1,26 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Arcade Physics World Overlap Event.
+ * 
+ * This event is dispatched by an Arcade Physics World instance if two bodies overlap _and_ at least
+ * one of them has their [onOverlap]{Phaser.Physics.Arcade.Body#onOverlap} property set to `true`.
+ * 
+ * It provides an alternative means to handling overlap events rather than using the callback approach.
+ * 
+ * Listen to it from a Scene using: `this.physics.world.on('overlap', listener)`.
+ * 
+ * Please note that 'collide' and 'overlap' are two different things in Arcade Physics.
+ *
+ * @event Phaser.Physics.Arcade.Events#OVERLAP
+ * 
+ * @param {Phaser.GameObjects.GameObject} gameObject1 - The first Game Object involved in the overlap. This is the parent of `body1`.
+ * @param {Phaser.GameObjects.GameObject} gameObject2 - The second Game Object involved in the overlap. This is the parent of `body2`.
+ * @param {Phaser.Physics.Arcade.Body|Phaser.Physics.Arcade.StaticBody} body1 - The first Physics Body involved in the overlap.
+ * @param {Phaser.Physics.Arcade.Body|Phaser.Physics.Arcade.StaticBody} body2 - The second Physics Body involved in the overlap.
+ */
+module.exports = 'overlap';

src/physics/arcade/events/PAUSE_EVENT.js

@@ -0,0 +1,16 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Arcade Physics World Pause Event.
+ * 
+ * This event is dispatched by an Arcade Physics World instance when it is paused.
+ * 
+ * Listen to it from a Scene using: `this.physics.world.on('pause', listener)`.
+ *
+ * @event Phaser.Physics.Arcade.Events#PAUSE
+ */
+module.exports = 'pause';

src/physics/arcade/events/RESUME_EVENT.js

@@ -0,0 +1,16 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Arcade Physics World Resume Event.
+ * 
+ * This event is dispatched by an Arcade Physics World instance when it resumes from a paused state.
+ * 
+ * Listen to it from a Scene using: `this.physics.world.on('resume', listener)`.
+ *
+ * @event Phaser.Physics.Arcade.Events#RESUME
+ */
+module.exports = 'resume';

src/physics/arcade/events/TILE_COLLIDE_EVENT.js

@@ -0,0 +1,25 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Arcade Physics Tile Collide Event.
+ * 
+ * This event is dispatched by an Arcade Physics World instance if a body collides with a Tile _and_
+ * has its [onCollide]{Phaser.Physics.Arcade.Body#onCollide} property set to `true`.
+ * 
+ * It provides an alternative means to handling collide events rather than using the callback approach.
+ * 
+ * Listen to it from a Scene using: `this.physics.world.on('tilecollide', listener)`.
+ * 
+ * Please note that 'collide' and 'overlap' are two different things in Arcade Physics.
+ *
+ * @event Phaser.Physics.Arcade.Events#TILE_COLLIDE
+ * 
+ * @param {Phaser.GameObjects.GameObject} gameObject - The Game Object involved in the collision. This is the parent of `body`.
+ * @param {Phaser.Tilemaps.Tile} tile - The tile the body collided with.
+ * @param {Phaser.Physics.Arcade.Body} body - The Arcade Physics Body of the Game Object involved in the collision.
+ */
+module.exports = 'tilecollide';

src/physics/arcade/events/TILE_OVERLAP_EVENT.js

@@ -0,0 +1,25 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Arcade Physics Tile Overlap Event.
+ * 
+ * This event is dispatched by an Arcade Physics World instance if a body overlaps with a Tile _and_
+ * has its [onOverlap]{Phaser.Physics.Arcade.Body#onOverlap} property set to `true`.
+ * 
+ * It provides an alternative means to handling overlap events rather than using the callback approach.
+ * 
+ * Listen to it from a Scene using: `this.physics.world.on('tileoverlap', listener)`.
+ * 
+ * Please note that 'collide' and 'overlap' are two different things in Arcade Physics.
+ *
+ * @event Phaser.Physics.Arcade.Events#TILE_OVERLAP
+ * 
+ * @param {Phaser.GameObjects.GameObject} gameObject - The Game Object involved in the overlap. This is the parent of `body`.
+ * @param {Phaser.Tilemaps.Tile} tile - The tile the body overlapped.
+ * @param {Phaser.Physics.Arcade.Body} body - The Arcade Physics Body of the Game Object involved in the overlap.
+ */
+module.exports = 'tileoverlap';

src/physics/arcade/events/WORLD_BOUNDS_EVENT.js

@@ -0,0 +1,25 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Arcade Physics World Bounds Event.
+ * 
+ * This event is dispatched by an Arcade Physics World instance if a body makes contact with the world bounds _and_
+ * it has its [onWorldBounds]{Phaser.Physics.Arcade.Body#onWorldBounds} property set to `true`.
+ * 
+ * It provides an alternative means to handling collide events rather than using the callback approach.
+ * 
+ * Listen to it from a Scene using: `this.physics.world.on('worldbounds', listener)`.
+ *
+ * @event Phaser.Physics.Arcade.Events#WORLD_BOUNDS
+ * 
+ * @param {Phaser.Physics.Arcade.Body} body - The Arcade Physics Body that hit the world bounds.
+ * @param {boolean} up - Is the Body blocked up? I.e. collided with the top of the world bounds.
+ * @param {boolean} down - Is the Body blocked down? I.e. collided with the bottom of the world bounds.
+ * @param {boolean} left - Is the Body blocked left? I.e. collided with the left of the world bounds.
+ * @param {boolean} right - Is the Body blocked right? I.e. collided with the right of the world bounds.
+ */
+module.exports = 'worldbounds';