CameraManager.remove has a new argument runDestroy which, if set, will automatically call Camera.destroy on the Cameras removed from the Camera Manager.

Author: photonstorm

CHANGELOG.md

@@ -12,6 +12,7 @@
 * The `RequestAnimationFrame.step` and `stepTimeout` functions have been updated so that the new Frame is requested from raf before the main game step is called. This allows you to now stop the raf callback from within the game update or render loop. Fix #3952 (thanks @tolimeh)
 * If you pass zero as the width or height when creating a TileSprite it will now use the dimensions of the texture frame as the size of the TileSprite. Fix #4073 (thanks @jcyuan)
 * `TileSprite.setFrame` has had both the `updateSize` and `updateOrigin` arguments removed as they didn't do anything for TileSprites and were misleading.
+* `CameraManager.remove` has a new argument `runDestroy` which, if set, will automatically call `Camera.destroy` on the Cameras removed from the Camera Manager. You should nearly always allow this to happen (thanks jamespierce)
 
 ### Bug Fixes
 

src/cameras/2d/BaseCamera.js

@@ -1441,10 +1441,13 @@ var BaseCamera = new Class({
      */
 
     /**
-     * Destroys this Camera instance. You rarely need to call this directly.
-     *
-     * Called by the Camera Manager. If you wish to destroy a Camera please use `CameraManager.remove` as
-     * cameras are stored in a pool, ready for recycling later, and calling this directly will prevent that.
+     * Destroys this Camera instance and its internal properties and references.
+     * Once destroyed you cannot use this Camera again, even if re-added to a Camera Manager.
+     * 
+     * This method is called automatically by `CameraManager.remove` if that methods `runDestroy` argument is `true`, which is the default.
+     * 
+     * Unless you have a specific reason otherwise, always use `CameraManager.remove` and allow it to handle the camera destruction,
+     * rather than calling this method directly.
      *
      * @method Phaser.Cameras.Scene2D.BaseCamera#destroy
      * @fires CameraDestroyEvent

src/cameras/2d/CameraManager.js

@@ -531,18 +531,22 @@ var CameraManager = new Class({
      * If found in the Camera Manager it will be immediately removed from the local cameras array.
      * If also currently the 'main' camera, 'main' will be reset to be camera 0.
      * 
-     * The removed Camera is not destroyed. If you also wish to destroy the Camera, you should call
-     * `Camera.destroy` on it, so that it clears all references to the Camera Manager.
+     * The removed Cameras are automatically destroyed if the `runDestroy` argument is `true`, which is the default.
+     * If you wish to re-use the cameras then set this to `false`, but know that they will retain their references
+     * and internal data until destroyed or re-added to a Camera Manager.
      *
      * @method Phaser.Cameras.Scene2D.CameraManager#remove
      * @since 3.0.0
      *
      * @param {(Phaser.Cameras.Scene2D.Camera|Phaser.Cameras.Scene2D.Camera[])} camera - The Camera, or an array of Cameras, to be removed from this Camera Manager.
+     * @param {boolean} [runDestroy=true] - Automatically call `Camera.destroy` on each Camera removed from this Camera Manager.
      * 
      * @return {integer} The total number of Cameras removed.
      */
-    remove: function (camera)
+    remove: function (camera, runDestroy)
     {
+        if (runDestroy === undefined) { runDestroy = true; }
+
         if (!Array.isArray(camera))
         {
             camera = [ camera ];
@@ -557,12 +561,18 @@ var CameraManager = new Class({
 
             if (index !== -1)
             {
+                if (runDestroy)
+                {
+                    cameras[index].destroy();
+                }
+
                 cameras.splice(index, 1);
+
                 total++;
             }
         }
 
-        if (!this.main)
+        if (!this.main && cameras[0])
         {
             this.main = cameras[0];
         }