Container updated to use preDestroy and remove event hooks

CHANGELOG.md

@@ -17,6 +17,14 @@
 * PluginManager.install has a new property `mapping`. This allows you to give a Global Plugin a property key, so that it is automatically injected into any Scenes as a Scene level instance. This allows you to have a single global plugin running in the PluginManager, that is injected into every Scene automatically.
 * PluginManager.createEntry is a new private method to create a plugin entry and return it. This avoids code duplication in several other methods, which now use this instead.
 * The Plugin File Type has a new optional argument `mapping`, which allows a global plugin to be injected into a Scene as a reference.
+* TileSprite.destroy has been renamed to `preDestroy` to take advantage of the preDestroy callback system.
+* RenderTexture.destroy has been renamed to `preDestroy` to take advantage of the preDestroy callback system.
+* Group.destroy now respects the `ignoreDestroy` property.
+* Graphics.preDestroy now clears the command buffer array.
+* Container addHandler will now remove a child's Scene shutdown listener and only listens to `destroy` once.
+* Container removeHandler will re-instate a child's Scene shutdown listener.
+* Container preDestroy now handles the pre-destroy calls, such as clearing the container.
+* Blitter preDestroy will now clear the children List and renderList.
 
 ### Bug Fixes
 
@@ -24,6 +32,7 @@
 * If a Container and its child were both input enabled they will now be sorted correctly in the InputPlugin (thanks rex)
 * Fix TypeError when colliding a Group as the only argument in Arcade Physics. Fix #3665 (thanks @samme)
 * The Particle tint value was incorrectly calculated, causing the color channels to be inversed. Fix #3643 (thanks @rgk)
+* All Game Objects that were in Containers were being destroyed twice when a Scene was shutdown. Although not required it still worked in most cases, except with TileSprites. TileSprites specifically have been hardened against this now but all Game Objects inside Containers now have a different event flow, stopping them from being destroyed twice (thanks @laptou)
 
 ### Examples, Documentation and TypeScript
 

src/gameobjects/container/Container.js

@@ -174,10 +174,21 @@ var Container = new Class({
          *
          * @name Phaser.GameObjects.Container#_sortKey
          * @type {string}
+         * @private
          * @since 3.4.0
          */
         this._sortKey = '';
 
+        /**
+         * A reference to the Scene Systems Event Emitter.
+         *
+         * @name Phaser.GameObjects.Container#_sysEvents
+         * @type {Phaser.Events.EventEmitter}
+         * @private
+         * @since 3.9.0
+         */
+        this._sysEvents = scene.sys.events;
+
         this.setPosition(x, y);
 
         this.clearAlpha();
@@ -347,7 +358,7 @@ var Container = new Class({
      */
     addHandler: function (gameObject)
     {
-        gameObject.on('destroy', this.remove, this);
+        gameObject.once('destroy', this.remove, this);
 
         if (this.exclusive)
         {
@@ -360,6 +371,10 @@ var Container = new Class({
 
             gameObject.parentContainer = this;
         }
+
+        //  Game Objects automatically listen to the Scene shutdown event, but
+        //  we don't need this if they're in a Container
+        this._sysEvents.off('shutdown', gameObject.destroy, gameObject);
     },
 
     /**
@@ -373,11 +388,13 @@ var Container = new Class({
      */
     removeHandler: function (gameObject)
     {
-        gameObject.off('destroy', this.remove, this);
+        gameObject.off('destroy', this.remove);
 
         if (this.exclusive)
         {
             gameObject.parentContainer = null;
+    
+            this._sysEvents.once('shutdown', gameObject.destroy, gameObject);
         }
     },
 
@@ -1192,21 +1209,13 @@ var Container = new Class({
     },
 
     /**
-     * Destroys this Container, removing it from the Display List.
+     * Internal destroy handler, called as part of the destroy process.
      *
-     * If `Container.exclusive` is `true` then it will also destroy all children.
-     *
-     * Use this to remove a Container from your game if you don't ever plan to use it again.
-     * As long as no reference to it exists within your own code it should become free for
-     * garbage collection.
-     *
-     * If you just want to temporarily disable an object then look at using the
-     * Game Object Pool instead of destroying it, as destroyed objects cannot be resurrected.
-     *
-     * @method Phaser.GameObjects.Container#destroy
-     * @since 3.4.0
+     * @method Phaser.GameObjects.Container#preDestroy
+     * @protected
+     * @since 3.9.0
      */
-    destroy: function ()
+    preDestroy: function ()
     {
         this.removeAll(!!this.exclusive);
 
@@ -1215,8 +1224,6 @@ var Container = new Class({
 
         this.list = [];
         this._displayList = null;
-
-        GameObject.prototype.destroy.call(this);
     }
 
 });