Added new displayList property and Layer documentation

Author: photonstorm

src/gameobjects/DisplayList.js

@@ -110,7 +110,14 @@ var DisplayList = new Class({
     {
         gameObject.emit(GameObjectEvents.ADDED_TO_SCENE, gameObject, this.scene);
 
-        gameObject.depthList = this;
+        if (gameObject.displayList)
+        {
+            gameObject.displayList.remove(gameObject);
+        }
+
+        gameObject.displayList = this;
+
+        this.queueDepthSort();
 
         this.events.emit(SceneEvents.ADDED_TO_SCENE, gameObject, this.scene);
     },
@@ -130,7 +137,9 @@ var DisplayList = new Class({
     {
         gameObject.emit(GameObjectEvents.REMOVED_FROM_SCENE, gameObject, this.scene);
 
-        gameObject.depthList = null;
+        gameObject.displayList = null;
+
+        this.queueDepthSort();
 
         this.events.emit(SceneEvents.REMOVED_FROM_SCENE, gameObject, this.scene);
     },

src/gameobjects/GameObject.js

@@ -49,6 +49,20 @@ var GameObject = new Class({
          */
         this.scene = scene;
 
+        /**
+         * Holds a reference to the Display List that contains this Game Object.
+         *
+         * This is set automatically when this Game Object is added to a Scene or Layer.
+         *
+         * You should treat this property as being read-only.
+         *
+         * @name Phaser.GameObjects.GameObject#displayList
+         * @type {(Phaser.GameObjects.DisplayList|Phaser.GameObjects.Layer)}
+         * @default null
+         * @since 3.50.0
+         */
+        this.displayList = null;
+
         /**
          * A textual representation of this Game Object, i.e. `sprite`.
          * Used internally by Phaser but is available for your own custom classes to populate.
@@ -679,16 +693,15 @@ var GameObject = new Class({
 
         this.emit(Events.DESTROY, this);
 
-        var sys = this.scene.sys;
-
         if (!fromScene)
         {
-            sys.displayList.remove(this);
+            this.displayList.remove(this);
         }
 
         if (this.input)
         {
-            sys.input.clear(this);
+            this.scene.sys.input.clear(this);
+
             this.input = undefined;
         }
 
@@ -702,6 +715,7 @@ var GameObject = new Class({
         if (this.body)
         {
             this.body.destroy();
+
             this.body = undefined;
         }
 
@@ -710,14 +724,14 @@ var GameObject = new Class({
         //  Tell the Scene to re-sort the children
         if (!fromScene)
         {
-            sys.queueDepthSort();
+            this.displayList.queueDepthSort();
         }
 
         this.active = false;
         this.visible = false;
 
         this.scene = undefined;
-
+        this.displayList = undefined;
         this.parentContainer = undefined;
 
         this.removeAllListeners();

src/gameobjects/components/Depth.js

@@ -25,19 +25,6 @@ var Depth = {
      */
     _depth: 0,
 
-    /**
-     * Holds a reference to the Display List responsible for depth sorting
-     * this Game Object. This is set automatically when this Game Object is
-     * added to the Display List in a Scene, or to a Layer. You should treat
-     * this property as being read-only.
-     *
-     * @name Phaser.GameObjects.Components.Depth#depthList
-     * @type {(Phaser.GameObjects.DisplayList|Phaser.GameObjects.Layer)}
-     * @default null
-     * @since 3.50.0
-     */
-    depthList: null,
-
     /**
      * The depth of this Game Object within the Scene.
      *
@@ -62,9 +49,9 @@ var Depth = {
 
         set: function (value)
         {
-            if (this.depthList)
+            if (this.displayList)
             {
-                this.depthList.queueDepthSort();
+                this.displayList.queueDepthSort();
             }
 
             this._depth = value;

src/gameobjects/layer/Layer.js

@@ -21,6 +21,46 @@ var StableSort = require('../../utils/array/StableSort');
  * @classdesc
  * A Layer Game Object.
  *
+ * A Layer is a special type of Game Object that acts as a Display List. You can add any type of Game Object
+ * to a Layer, just as you would to a Scene. Layers can be used to visually group together 'layers' of Game
+ * Objects:
+ *
+ * ```javascript
+ * const spaceman = this.add.sprite(150, 300, 'spaceman');
+ * const bunny = this.add.sprite(400, 300, 'bunny');
+ * const elephant = this.add.sprite(650, 300, 'elephant');
+ *
+ * const layer = this.add.layer();
+ *
+ * layer.add([ spaceman, bunny, elephant ]);
+ * ```
+ *
+ * The 3 sprites in the example above will now be managed by the Layer they were added to. Therefore,
+ * if you then set `layer.setVisible(false)` they would all vanish from the display.
+ *
+ * You can also control the depth of the Game Objects within the Layer. For example, calling the
+ * `setDepth` method of a child of a Layer will allow you to adjust the depth of that child _within the
+ * Layer itself_, rather than the whole Scene. The Layer, too, can have its depth set as well.
+ *
+ * The Layer class also offers many different methods for manipulating the list, such as the
+ * methods `moveUp`, `moveDown`, `sendToBack`, `bringToTop` and so on. These allow you to change the
+ * display list position of the Layers children, causing it to adjust the order in which they are
+ * rendered. Using `setDepth` on a child allows you to override this.
+ *
+ * Layers can have Post FX Pipelines set, which allows you to easily enable a post pipeline across
+ * a whole range of children, which, depending on the effect, can often be far more efficient that doing so
+ * on a per-child basis.
+ *
+ * Layers have no position or size within the Scene. This means you cannot enable a Layer for
+ * physics or input, or change the position, rotation or scale of a Layer. They also have no scroll
+ * factor, texture, tint, origin, crop or bounds.
+ *
+ * If you need those kind of features then you should use a Container instead. Containers can be added
+ * to Layers, but Layers cannot be added to Containers.
+ *
+ * However, you can set the Alpha, Blend Mode, Depth, Mask and Visible state of a Layer. These settings
+ * will impact all children being rendered by the Layer.
+ *
  * @class Layer
  * @extends Phaser.Structs.List.<Phaser.GameObjects.GameObject>
  * @memberof Phaser.GameObjects
@@ -73,6 +113,20 @@ var Layer = new Class({
          */
         this.scene = scene;
 
+        /**
+         * Holds a reference to the Display List that contains this Game Object.
+         *
+         * This is set automatically when this Game Object is added to a Scene or Layer.
+         *
+         * You should treat this property as being read-only.
+         *
+         * @name Phaser.GameObjects.Layer#displayList
+         * @type {(Phaser.GameObjects.DisplayList|Phaser.GameObjects.Layer)}
+         * @default null
+         * @since 3.50.0
+         */
+        this.displayList = null;
+
         /**
          * A textual representation of this Game Object, i.e. `sprite`.
          * Used internally by Phaser but is available for your own custom classes to populate.
@@ -544,7 +598,12 @@ var Layer = new Class({
     {
         gameObject.emit(GameObjectEvents.ADDED_TO_SCENE, gameObject, this.scene);
 
-        gameObject.depthList = this;
+        if (gameObject.displayList)
+        {
+            gameObject.displayList.remove(gameObject);
+        }
+
+        gameObject.displayList = this;
 
         this.queueDepthSort();
 
@@ -566,7 +625,7 @@ var Layer = new Class({
     {
         gameObject.emit(GameObjectEvents.REMOVED_FROM_SCENE, gameObject, this.scene);
 
-        gameObject.depthList = null;
+        gameObject.displayList = null;
 
         this.queueDepthSort();
 
@@ -664,11 +723,10 @@ var Layer = new Class({
 
         this.emit(GameObjectEvents.DESTROY, this);
 
-        var sys = this.systems;
-
-        if (!fromScene)
+        if (!fromScene && this.displayList)
         {
-            sys.displayList.remove(this);
+            this.displayList.remove(this);
+            this.displayList.queueDepthSort();
         }
 
         if (this.data)
@@ -678,16 +736,11 @@ var Layer = new Class({
             this.data = undefined;
         }
 
-        //  Tell the Scene to re-sort the children
-        if (!fromScene)
-        {
-            sys.queueDepthSort();
-        }
-
         this.active = false;
         this.visible = false;
 
         this.scene = undefined;
+        this.displayList = undefined;
         this.systems = undefined;
         this.events = undefined;
     }