Added getFirstNth and getLastNth

Author: photonstorm

src/gameobjects/group/Group.js

@@ -686,7 +686,7 @@ var Group = new Class({
     },
 
     /**
-     * Scans the group for the first member that has an {@link Phaser.GameObjects.GameObject#active} state matching the argument,
+     * Scans the Group, from top to bottom, for the first member that has an {@link Phaser.GameObjects.GameObject#active} state matching the argument,
      * assigns `x` and `y`, and returns the member.
      *
      * If no matching member is found and `createIfNull` is true and the group isn't full then it will create a new Game Object using `x`, `y`, `key`, `frame`, and `visible`.
@@ -707,18 +707,44 @@ var Group = new Class({
      */
     getFirst: function (state, createIfNull, x, y, key, frame, visible)
     {
-        return this.getHandler(true, state, createIfNull, x, y, key, frame, visible);
+        return this.getHandler(true, 1, state, createIfNull, x, y, key, frame, visible);
     },
 
     /**
-     * Scans the group for the last member that has an {@link Phaser.GameObjects.GameObject#active} state matching the argument,
+     * Scans the Group, from top to bottom, for the nth member that has an {@link Phaser.GameObjects.GameObject#active} state matching the argument,
+     * assigns `x` and `y`, and returns the member.
+     *
+     * If no matching member is found and `createIfNull` is true and the group isn't full then it will create a new Game Object using `x`, `y`, `key`, `frame`, and `visible`.
+     * Unless a new member is created, `key`, `frame`, and `visible` are ignored.
+     *
+     * @method Phaser.GameObjects.Group#getFirstNth
+     * @since 3.5.2
+     *
+     * @param {integer} nth - The nth matching Group member to search for.
+     * @param {boolean} [state=false] - The {@link Phaser.GameObjects.GameObject#active} value to match.
+     * @param {boolean} [createIfNull=false] - Create a new Game Object if no matching members are found, using the following arguments.
+     * @param {number} [x] - The horizontal position of the Game Object in the world.
+     * @param {number} [y] - The vertical position of the Game Object in the world.
+     * @param {string} [key=defaultKey] - The texture key assigned to a new Game Object (if one is created).
+     * @param {(string|integer)} [frame=defaultFrame] - A texture frame assigned to a new Game Object (if one is created).
+     * @param {boolean} [visible=true] - The {@link Phaser.GameObjects.Components.Visible#visible} state of a new Game Object (if one is created).
+     *
+     * @return {?Phaser.GameObjects.GameObject} The first matching group member, or a newly created member, or null.
+     */
+    getFirstNth: function (nth, state, createIfNull, x, y, key, frame, visible)
+    {
+        return this.getHandler(true, nth, state, createIfNull, x, y, key, frame, visible);
+    },
+
+    /**
+     * Scans the Group for the last member that has an {@link Phaser.GameObjects.GameObject#active} state matching the argument,
      * assigns `x` and `y`, and returns the member.
      *
      * If no matching member is found and `createIfNull` is true and the group isn't full then it will create a new Game Object using `x`, `y`, `key`, `frame`, and `visible`.
      * Unless a new member is created, `key`, `frame`, and `visible` are ignored.
      *
      * @method Phaser.GameObjects.Group#getLast
-     * @since 3.6.0
+     * @since 3.5.2
      *
      * @param {boolean} [state=false] - The {@link Phaser.GameObjects.GameObject#active} value to match.
      * @param {boolean} [createIfNull=false] - Create a new Game Object if no matching members are found, using the following arguments.
@@ -732,7 +758,33 @@ var Group = new Class({
      */
     getLast: function (state, createIfNull, x, y, key, frame, visible)
     {
-        return this.getHandler(false, state, createIfNull, x, y, key, frame, visible);
+        return this.getHandler(false, 1, state, createIfNull, x, y, key, frame, visible);
+    },
+
+    /**
+     * Scans the Group for the last nth member that has an {@link Phaser.GameObjects.GameObject#active} state matching the argument,
+     * assigns `x` and `y`, and returns the member.
+     *
+     * If no matching member is found and `createIfNull` is true and the group isn't full then it will create a new Game Object using `x`, `y`, `key`, `frame`, and `visible`.
+     * Unless a new member is created, `key`, `frame`, and `visible` are ignored.
+     *
+     * @method Phaser.GameObjects.Group#getLastNth
+     * @since 3.5.2
+     *
+     * @param {integer} nth - The nth matching Group member to search for.
+     * @param {boolean} [state=false] - The {@link Phaser.GameObjects.GameObject#active} value to match.
+     * @param {boolean} [createIfNull=false] - Create a new Game Object if no matching members are found, using the following arguments.
+     * @param {number} [x] - The horizontal position of the Game Object in the world.
+     * @param {number} [y] - The vertical position of the Game Object in the world.
+     * @param {string} [key=defaultKey] - The texture key assigned to a new Game Object (if one is created).
+     * @param {(string|integer)} [frame=defaultFrame] - A texture frame assigned to a new Game Object (if one is created).
+     * @param {boolean} [visible=true] - The {@link Phaser.GameObjects.Components.Visible#visible} state of a new Game Object (if one is created).
+     *
+     * @return {?Phaser.GameObjects.GameObject} The first matching group member, or a newly created member, or null.
+     */
+    getLastNth: function (nth, state, createIfNull, x, y, key, frame, visible)
+    {
+        return this.getHandler(false, nth, state, createIfNull, x, y, key, frame, visible);
     },
 
     /**
@@ -744,9 +796,10 @@ var Group = new Class({
      *
      * @method Phaser.GameObjects.Group#getHandler
      * @private
-     * @since 3.6.0
+     * @since 3.5.2
      *
      * @param {boolean} forwards - Search front to back or back to front?
+     * @param {integer} nth - Stop matching after nth successful matches.
      * @param {boolean} [state=false] - The {@link Phaser.GameObjects.GameObject#active} value to match.
      * @param {boolean} [createIfNull=false] - Create a new Game Object if no matching members are found, using the following arguments.
      * @param {number} [x] - The horizontal position of the Game Object in the world.
@@ -757,36 +810,48 @@ var Group = new Class({
      *
      * @return {?Phaser.GameObjects.GameObject} The first matching group member, or a newly created member, or null.
      */
-    getHandler: function (forwards, state, createIfNull, x, y, key, frame, visible)
+    getHandler: function (forwards, nth, state, createIfNull, x, y, key, frame, visible)
     {
         if (state === undefined) { state = false; }
         if (createIfNull === undefined) { createIfNull = false; }
 
         var gameObject;
 
+        var i;
+        var total = 0;
         var children = this.children.entries;
 
         if (forwards)
         {
-            for (var i = 0; i < children.length; i++)
+            for (i = 0; i < children.length; i++)
             {
                 gameObject = children[i];
 
                 if (gameObject.active === state)
                 {
-                    break;
+                    total++;
+
+                    if (total === nth)
+                    {
+                        break;
+                    }
                 }
             }
         }
         else
         {
-            for (var i = children.length - 1; i >= 0; i--)
+            for (i = children.length - 1; i >= 0; i--)
             {
                 gameObject = children[i];
 
                 if (gameObject.active === state)
                 {
-                    break;
+                    total++;
+
+                    if (total === nth)
+                    {
+                        break;
+                    }
                 }
             }
         }