Add chooseMultiple() (#852)

CHANGELOG.md

@@ -2,6 +2,7 @@
 - added `loadMusic()` to load streaming audio (doesn't block in loading screen)
 - added support for arrays in uniforms
 - added support for texture larger than 2048x2048
+- added `chooseMultiple()` and `shuffle()` helper functions
 
 ### v3000.1.17
 - exposed `vel` property on `BodyComp`

src/kaboom.ts

@@ -38,6 +38,8 @@ import {
 	randSeed,
 	chance,
 	choose,
+	chooseMultiple,
+	shuffle,
 	clamp,
 	lerp,
 	map,
@@ -6617,6 +6619,8 @@ export default (gopt: KaboomOpt = {}): KaboomCtx => {
 		hsl2rgb,
 		quad,
 		choose,
+		chooseMultiple,
+		shuffle,
 		chance,
 		lerp,
 		tween,

src/math.ts

@@ -971,6 +971,18 @@ export function chance(p: number): boolean {
 	return rand() <= p
 }
 
+export function shuffle<T>(list: T[]): T[] {
+	for (let i = list.length - 1; i > 0; i--) {
+		const j = Math.floor(Math.random() * (i + 1));
+		[list[i], list[j]] = [list[j], list[i]]
+	}
+	return list
+}
+
+export function chooseMultiple<T>(list: T[], count: number): T[] {
+	return list.length <= count ? list.slice() : shuffle(list.slice()).slice(0, count)
+}
+
 export function choose<T>(list: T[]): T {
 	return list[randi(list.length)]
 }
@@ -1882,7 +1894,7 @@ export class Ellipse {
 			)
 		}
 		else {
-			// Rotation. We need to find the maximum x and y distance from the 
+			// Rotation. We need to find the maximum x and y distance from the
 			// center of the rotated ellipse
 			const angle = deg2rad(this.angle)
 			const c = Math.cos(angle)

src/types.ts

@@ -106,34 +106,34 @@ export interface KaboomCtx {
 	 * @example
 	 * ```js
 	 * // Common way to use this is to have one sprite overlap another sprite, and use readd() to have the bottom sprite on top of the other.
-	 * 
+	 *
 	 * // Create two sprites.
 	 * const greenBean = add([
 	 * sprite("bean"),
 	 * pos(200,140),
 	 * color(255, 255, 255),
          * area(),
 	 * ])
-	 * 
+	 *
 	 * // This bean will overlap the green bean.
 	 * const purpleBean = add([
 	 * sprite("bean"),
 	 * pos(230,140),
 	 * color(255, 0, 255),
   	 * area(),
 	 * ])
-	 * 
+	 *
 	 * // Example 1: simply call readd() on the target you want on top.
-	 * readd(greenBean)   
-	 * 
+	 * readd(greenBean)
+	 *
 	 * // Example 2: using onClick() or other functions with readd().
 	 * // If you comment out the first example, and use this readd() with a function like onClick(), you
 	 * can keep switching which sprite is above the other ( click on edge of face ).
-	 * 
+	 *
 	 * purpleBean.onClick(() => {
 	 * 		readd(greenBean)
 	 * })
-	 *        
+	 *
 	 * greenBean.onClick(() => {
 	 * 		readd(purpleBean)
 	 * })
@@ -209,7 +209,7 @@ export interface KaboomCtx {
 	 *
 	 * @example
 	 * ```js
-	 * // scale uniformly with one value 
+	 * // scale uniformly with one value
 	 * add([
 	 *     sprite("bean"),
 	 * 	   scale(3),
@@ -221,7 +221,7 @@ export interface KaboomCtx {
 	 * ])
 	 *  // scale with vec2(x,y).
 	 * bean.scale = vec2(2,4)
-	 * 
+	 *
 	 * ```
 	 */
 	scale(): ScaleComp,
@@ -703,20 +703,20 @@ export interface KaboomCtx {
 	 *     destroy(bomb)
 	 *     addKaboom(bomb.pos)
 	 * })
-	 * 
+	 *
 	 * // a custom event can be defined manually
 	 * // by passing a name and a callback function
 	 * on("talk", (message, posX, posY) => {
 	 *     add([
-	 *      text(message), 
+	 *      text(message),
 	 *      pos(posX, posY - 100)
 	 *     ])
 	 * })
 	 * onKeyPress("space", () => {
 	 *    // the trigger method on game objs can be used to trigger a custom event
 	 *    npc.trigger("talk", "Hello World!", npc.pos.x, npc.pos.y)
 	 * })
-	 * 
+	 *
 	 * ```
 	 */
 	on(event: string, tag: Tag, action: (obj: GameObj, ...args: any) => void): EventController,
@@ -1894,6 +1894,18 @@ export interface KaboomCtx {
 	 * ```
 	 */
 	choose<T>(lst: T[]): T,
+	/**
+	 * Choose multiple random items from a list.
+	 *
+	 * @since v3000.2
+	 */
+	chooseMultiple<T>(lst: T[], count: number): T[],
+	/**
+	 * Shuffle an array.
+	 *
+	 * @since v3000.2
+	 */
+	shuffle<T>(lst: T[]): T[],
 	/**
 	 * rand(1) <= p
 	 *