Math.removeRandom allows you to remove (and return) a random object f…

…rom an array.

Updated TypeScript defs to fix getRandom (fix phaserjs#583)

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:

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;

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.
     *