From eec9f70c1ca48a0b281539e3d0a5c99a39fa556b Mon Sep 17 00:00:00 2001
From: photonstorm <rdavey@gmail.com>
Date: Tue, 18 Mar 2014 16:51:58 +0000
Subject: [PATCH] Math.removeRandom allows you to remove (and return) a random
 object from an array. Updated TypeScript defs to fix getRandom (fix #583)

---
 README.md         |  1 +
 build/phaser.d.ts |  3 ++-
 src/math/Math.js  | 36 ++++++++++++++++++++++++++++++++++++
 3 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 71ee241b7f..25011318dc 100644
--- a/README.md
+++ b/README.md
@@ -85,6 +85,7 @@ Updated:
 New Features:
 
 * Device.getUserMedia boolean added, useful if you need access to the webcam or microphone.
+* Math.removeRandom allows you to remove (and return) a random object from an array.
 
 
 TODO:
diff --git a/build/phaser.d.ts b/build/phaser.d.ts
index c36a1f8ed7..b1e09781dc 100644
--- a/build/phaser.d.ts
+++ b/build/phaser.d.ts
@@ -2431,7 +2431,7 @@ declare module Phaser {
         static fuzzyFloor(val: number, epsilon?: number): boolean;
         static fuzzyGreaterThan(a: number, b: number, epsilon?: number): boolean;
         static fuzzyLessThan(a: number, b: number, epsilon?: number): boolean;
-        static getRandom(objects: Object[], startIndex?: number, length?: number): Object;
+        static getRandom<T>(objects: T[], startIndex?: number, length?: number): T;
         static interpolateAngles(a1: number, a2: number, weight: number, radians?: boolean, ease?: any): number;
         static interpolateFloat(a: number, b: number, weight: number): number;
         static isEven(n: number): boolean;
@@ -2454,6 +2454,7 @@ declare module Phaser {
         static PI2: number;
         static radToDeg(radians: number): number;
         static randomSign(): number;
+        static removeRandom<T>(objects: T[], startIndex?: number, length?: number): T;
         static reverseAngle(angleRed: number): number;
         static roundTo(value: number, place?: number, base?: number): number;
         static shear(n: number): number;
diff --git a/src/math/Math.js b/src/math/Math.js
index 246c567830..9e72703cdb 100644
--- a/src/math/Math.js
+++ b/src/math/Math.js
@@ -981,6 +981,42 @@ Phaser.Math = {
 
     },
 
+    /**
+    * Removes a random object from the given array and returns it.
+    * Will return null if random selection is missing, or array has no entries.
+    *
+    * @method Phaser.Math#removeRandom
+    * @param {array} objects - An array of objects.
+    * @param {number} startIndex - Optional offset off the front of the array. Default value is 0, or the beginning of the array.
+    * @param {number} length - Optional restriction on the number of values you want to randomly select from.
+    * @return {object} The random object that was removed.
+    */
+    removeRandom: function (objects, startIndex, length) {
+
+        if (typeof startIndex === "undefined") { startIndex = 0; }
+        if (typeof length === "undefined") { length = 0; }
+        
+        if (objects != null) {
+
+            var l = length;
+
+            if ((l === 0) || (l > objects.length - startIndex))
+            {
+                l = objects.length - startIndex;
+            }
+
+            if (l > 0)
+            {
+                var idx = startIndex + Math.floor(Math.random() * l);
+                var removed = objects.splice(idx, 1);
+                return removed[0];
+            }
+        }
+
+        return null;
+
+    },
+
     /**
     * Round down to the next whole number. E.g. floor(1.7) == 1, and floor(-2.7) == -2.
     *