Group.remove and clear have optional destroyChild arguments

Author: photonstorm

CHANGELOG.md

@@ -7,6 +7,8 @@
 * Group.getLast will return the last member in the Group matching the search criteria.
 * Group.getFirstNth will return the nth member in the Group, scanning from top to bottom, that matches the search criteria.
 * Group.getLastNth will return the nth member in the Group, scanning in reverse, that matches the search criteria.
+* Group.remove has a new optional argument `destroyChild` that will call `destroy` on the child after removing it.
+* Group.clear has a new optional argument `destroyChild` that will call `destroy` on all children in the Group after removing them.
 
 ### Updates
 
@@ -16,6 +18,7 @@
 * Impact Physics Game Objects have changed `setActive` to `setActiveCollision`, previously the `setActive` collision method was overwriting the Game Objects `setActive` method, hence the renaming.
 * The modifications made to the RTree class in Phaser 3.4.0 to avoid CSP policy violations caused a significant performance hit once a substantial number of bodies were involved. We have recoded how the class deals with its accessor formats and returned to 3.3 level performance while still maintaining CSP policy adherence. Fix #3594 (thanks @16patsle)
 * The Retro Font namespace has changed to `Phaser.GameObjects.RetroFont`. Previously, you would access the parser and constants via `BitmapText`, i.e.: `Phaser.GameObjects.BitmapText.ParseRetroFont.TEXT_SET6`. This has now changed to its own namespace, so the same line would be: `Phaser.GameObjects.RetroFont.TEXT_SET6`. The Parser is available via `Phaser.GameObjects.RetroFont.Parse`. This keeps things cleaner and also unbinds RetroFont from BitmapText, allowing you to cleanly exclude it from your build should you wish. All examples have been updated to reflect this.
+* If using the `removeFromScene` option in Group.remove or Group.clear it will remove the child/ren from the Scene to which they belong, not the Scene the Group belongs to.
 
 ### Bug Fixes
 

src/gameobjects/group/Group.js

@@ -561,21 +561,23 @@ var Group = new Class({
     },
 
     /**
-     * Removes a member of this group.
+     * Removes a member of this Group and optionally removes it from the Scene and / or destroys it.
      *
      * Calls {@link Phaser.GameObjects.Group#removeCallback}.
      *
      * @method Phaser.GameObjects.Group#remove
      * @since 3.0.0
      *
      * @param {Phaser.GameObjects.GameObject} child - The Game Object to remove.
-     * @param {boolean} [removeFromScene=false] - Also remove the group member from the scene.
+     * @param {boolean} [removeFromScene=false] - Optionally remove the Group member from the Scene it belongs to.
+     * @param {boolean} [destroyChild=false] - Optionally call destroy on the removed Group member.
      *
      * @return {Phaser.GameObjects.Group} This Group object.
      */
-    remove: function (child, removeFromScene)
+    remove: function (child, removeFromScene, destroyChild)
     {
         if (removeFromScene === undefined) { removeFromScene = false; }
+        if (destroyChild === undefined) { destroyChild = false; }
 
         if (!this.children.contains(child))
         {
@@ -589,36 +591,42 @@ var Group = new Class({
             this.removeCallback.call(this, child);
         }
 
-        if (removeFromScene)
+        child.off('destroy', this.remove, this);
+
+        if (destroyChild)
         {
-            this.scene.sys.displayList.remove(child);
+            child.destroy();
+        }
+        else if (removeFromScene)
+        {
+            child.scene.sys.displayList.remove(child);
 
             if (child.preUpdate)
             {
-                this.scene.sys.updateList.remove(child);
+                child.scene.sys.updateList.remove(child);
             }
         }
 
-        child.off('destroy', this.remove, this);
-
         return this;
     },
 
     /**
-     * Removes all members of this group.
+     * Removes all members of this Group and optionally removes them from the Scene and / or destroys them.
      *
      * Does not call {@link Phaser.GameObjects.Group#removeCallback}.
      *
      * @method Phaser.GameObjects.Group#clear
      * @since 3.0.0
      *
-     * @param {boolean} [removeFromScene=false] - Also remove each group member from the scene.
+     * @param {boolean} [removeFromScene=false] - Optionally remove each Group member from the Scene.
+     * @param {boolean} [destroyChild=false] - Optionally call destroy on the removed Group members.
      *
      * @return {Phaser.GameObjects.Group} This group.
      */
-    clear: function (removeFromScene)
+    clear: function (removeFromScene, destroyChild)
     {
         if (removeFromScene === undefined) { removeFromScene = false; }
+        if (destroyChild === undefined) { destroyChild = false; }
 
         var children = this.children;
 
@@ -628,13 +636,17 @@ var Group = new Class({
 
             gameObject.off('destroy', this.remove, this);
 
-            if (removeFromScene)
+            if (destroyChild)
+            {
+                gameObject.destroy();
+            }
+            else if (removeFromScene)
             {
-                this.scene.sys.displayList.remove(gameObject);
+                gameObject.scene.sys.displayList.remove(gameObject);
 
                 if (gameObject.preUpdate)
                 {
-                    this.scene.sys.updateList.remove(gameObject);
+                    gameObject.scene.sys.updateList.remove(gameObject);
                 }
             }
         }