Merge branch 'master' of https://github.com/photonstorm/phaser

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/gameobjects/rendertexture/RenderTexture.js

@@ -4,6 +4,7 @@
  * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
  */
 
+var BlendModes = require('../../renderer/BlendModes');
 var Camera = require('../../cameras/2d/BaseCamera');
 var CanvasPool = require('../../display/canvas/CanvasPool');
 var Class = require('../../utils/Class');
@@ -187,6 +188,16 @@ var RenderTexture = new Class({
          */
         this._saved = false;
 
+        /**
+         * Internal erase mode flag.
+         *
+         * @name Phaser.GameObjects.RenderTexture#_eraseMode
+         * @type {boolean}
+         * @private
+         * @since 3.16.0
+         */
+        this._eraseMode = false;
+
         /**
          * An internal Camera that can be used to move around the Render Texture.
          * Control it just like you would any Scene Camera. The difference is that it only impacts the placement of what
@@ -463,6 +474,70 @@ var RenderTexture = new Class({
         return this;
     },
 
+    /**
+     * Draws the given object, or an array of objects, to this Render Texture using a blend mode of ERASE.
+     * This has the effect of erasing any filled pixels in the objects from this Render Texture.
+     * 
+     * It can accept any of the following:
+     * 
+     * * Any renderable Game Object, such as a Sprite, Text, Graphics or TileSprite.
+     * * Dynamic and Static Tilemap Layers.
+     * * A Group. The contents of which will be iterated and drawn in turn.
+     * * A Container. The contents of which will be iterated fully, and drawn in turn.
+     * * A Scene's Display List. Pass in `Scene.children` to draw the whole list.
+     * * Another Render Texture.
+     * * A Texture Frame instance.
+     * * A string. This is used to look-up a texture from the Texture Manager.
+     * 
+     * Note: You cannot erase a Render Texture from itself.
+     * 
+     * If passing in a Group or Container it will only draw children that return `true`
+     * when their `willRender()` method is called. I.e. a Container with 10 children,
+     * 5 of which have `visible=false` will only draw the 5 visible ones.
+     * 
+     * If passing in an array of Game Objects it will draw them all, regardless if
+     * they pass a `willRender` check or not.
+     * 
+     * You can pass in a string in which case it will look for a texture in the Texture
+     * Manager matching that string, and draw the base frame.
+     * 
+     * You can pass in the `x` and `y` coordinates to draw the objects at. The use of
+     * the coordinates differ based on what objects are being drawn. If the object is
+     * a Group, Container or Display List, the coordinates are _added_ to the positions
+     * of the children. For all other types of object, the coordinates are exact.
+     * 
+     * Calling this method causes the WebGL batch to flush, so it can write the texture
+     * data to the framebuffer being used internally. The batch is flushed at the end,
+     * after the entries have been iterated. So if you've a bunch of objects to draw,
+     * try and pass them in an array in one single call, rather than making lots of
+     * separate calls.
+     *
+     * @method Phaser.GameObjects.RenderTexture#erase
+     * @since 3.16.0
+     *
+     * @param {any} entries - Any renderable Game Object, or Group, Container, Display List, other Render Texture, Texture Frame or an array of any of these.
+     * @param {number} [x] - The x position to draw the Frame at, or the offset applied to the object.
+     * @param {number} [y] - The y position to draw the Frame at, or the offset applied to the object.
+     *
+     * @return {this} This Render Texture instance.
+     */
+    erase: function (entries, x, y)
+    {
+        this._eraseMode = true;
+
+        var blendMode = this.renderer.currentBlendMode;
+
+        this.renderer.setBlendMode(BlendModes.ERASE);
+
+        this.draw(entries, x, y, 1, 16777215);
+
+        this.renderer.setBlendMode(blendMode);
+
+        this._eraseMode = false;
+
+        return this;
+    },
+
     /**
      * Draws the given object, or an array of objects, to this Render Texture.
      * 
@@ -747,7 +822,10 @@ var RenderTexture = new Class({
         var prevX = gameObject.x;
         var prevY = gameObject.y;
 
-        this.renderer.setBlendMode(gameObject.blendMode);
+        if (!this._eraseMode)
+        {
+            this.renderer.setBlendMode(gameObject.blendMode);
+        }
 
         gameObject.setPosition(x, y);
 
@@ -827,7 +905,19 @@ var RenderTexture = new Class({
 
         if (this.gl)
         {
+            if (this._eraseMode)
+            {
+                var blendMode = this.renderer.currentBlendMode;
+
+                this.renderer.setBlendMode(BlendModes.ERASE);
+            }
+            
             this.pipeline.batchTextureFrame(textureFrame, x, y, tint, alpha, this.camera.matrix, null);
+
+            if (this._eraseMode)
+            {
+                this.renderer.setBlendMode(blendMode);
+            }
         }
         else
         {

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;