@m2c2kit/core 0.3.32 → 0.3.34

package/dist/index.d.ts

@@ -4867,6 +4867,44 @@ interface PluginEvent extends M2Event<Plugin> {
 }
 
 declare class RandomDraws {
+    private static randomFunction;
+    private static seededPRNG;
+    /**
+     * Sets the seed for the pseudo-random number generator (PRNG) and
+     * instructs methods within `RandomDraws` to use a seeded PRNG
+     * instead of the default `Math.random()`.
+     *
+     * @remarks The implementation of the seeded PRNG is based on David Bau's
+     * `seedrandom` library at https://github.com/davidbau/seedrandom
+     *
+     * @param seed - The seed string to initialize the PRNG.
+     */
+    static setSeed(seed: string): void;
+    /**
+     * Instructs methods within `RandomDraws` to use the default
+     * `Math.random()` from the runtime environment as the random number
+     * function instead of a seeded PRNG.
+     */
+    static useDefaultRandom(): void;
+    /**
+     * Instructs methods within `RandomDraws` to use the seeded
+     * pseudo-random number generator (PRNG).
+     *
+     * @remarks This method will throw an error if `setSeed()` has not
+     * been called first to initialize the seeded PRNG.
+     */
+    static useSeededRandom(): void;
+    /**
+     * Generates a random number in the range [0, 1) using the current
+     * random function.
+     *
+     * @remarks This method will return a number from `Math.random()` in the
+     * runtime environment, unless `setSeed()` has been called to initialize
+     * a seeded PRNG.
+     *
+     * @returns A random number in the range [0, 1) using the current random function.
+     */
+    static random(): number;
     /**
      * Draws a single random integer from a uniform distribution of integers in
      * the specified range.
@@ -4875,6 +4913,10 @@ declare class RandomDraws {
      * @param maximumInclusive - Upper bound of range
      * @returns A sampled integer
      */
+    static singleFromRange(minimumInclusive: number, maximumInclusive: number): number;
+    /**
+     * @deprecated Use `singleFromRange()` instead.
+     */
     static SingleFromRange(minimumInclusive: number, maximumInclusive: number): number;
     /**
      * Draws random integers, without replacement, from a uniform distribution
@@ -4885,6 +4927,10 @@ declare class RandomDraws {
      * @param maximumInclusive - Upper bound of range
      * @returns An array of integers
      */
+    static fromRangeWithoutReplacement(n: number, minimumInclusive: number, maximumInclusive: number): Array<number>;
+    /**
+     * @deprecated Use `fromRangeWithoutReplacement()` instead.
+     */
     static FromRangeWithoutReplacement(n: number, minimumInclusive: number, maximumInclusive: number): Array<number>;
     /**
      * Draw random grid cell locations, without replacement, from a uniform
@@ -4902,6 +4948,13 @@ declare class RandomDraws {
      * @returns Array of grid cells. Each cell is object in form of:
      * &#123 row: number, column: number &#125;. Grid cell locations are zero-based
      */
+    static fromGridWithoutReplacement(n: number, rows: number, columns: number, predicate?: (row: number, column: number) => boolean): Array<{
+        row: number;
+        column: number;
+    }>;
+    /**
+     * @deprecated Use `fromGridWithoutReplacement()` instead.
+     */
     static FromGridWithoutReplacement(n: number, rows: number, columns: number, predicate?: (row: number, column: number) => boolean): Array<{
         row: number;
         column: number;

package/dist/index.js

@@ -12762,7 +12762,57 @@ const _LegacyTimer = class _LegacyTimer {
 _LegacyTimer._timers = new Array();
 let LegacyTimer = _LegacyTimer;
 
-class RandomDraws {
+const _RandomDraws = class _RandomDraws {
+  /**
+   * Sets the seed for the pseudo-random number generator (PRNG) and
+   * instructs methods within `RandomDraws` to use a seeded PRNG
+   * instead of the default `Math.random()`.
+   *
+   * @remarks The implementation of the seeded PRNG is based on David Bau's
+   * `seedrandom` library at https://github.com/davidbau/seedrandom
+   *
+   * @param seed - The seed string to initialize the PRNG.
+   */
+  static setSeed(seed) {
+    this.seededPRNG = seedrandom(seed);
+    this.randomFunction = this.seededPRNG;
+  }
+  /**
+   * Instructs methods within `RandomDraws` to use the default
+   * `Math.random()` from the runtime environment as the random number
+   * function instead of a seeded PRNG.
+   */
+  static useDefaultRandom() {
+    this.randomFunction = Math.random;
+  }
+  /**
+   * Instructs methods within `RandomDraws` to use the seeded
+   * pseudo-random number generator (PRNG).
+   *
+   * @remarks This method will throw an error if `setSeed()` has not
+   * been called first to initialize the seeded PRNG.
+   */
+  static useSeededRandom() {
+    if (this.seededPRNG === null) {
+      throw new M2Error(
+        "Cannot use seeded random function because no seed has been set. Call setSeed() first."
+      );
+    }
+    this.randomFunction = this.seededPRNG;
+  }
+  /**
+   * Generates a random number in the range [0, 1) using the current
+   * random function.
+   *
+   * @remarks This method will return a number from `Math.random()` in the
+   * runtime environment, unless `setSeed()` has been called to initialize
+   * a seeded PRNG.
+   *
+   * @returns A random number in the range [0, 1) using the current random function.
+   */
+  static random() {
+    return this.randomFunction();
+  }
   /**
    * Draws a single random integer from a uniform distribution of integers in
    * the specified range.
@@ -12771,10 +12821,26 @@ class RandomDraws {
    * @param maximumInclusive - Upper bound of range
    * @returns A sampled integer
    */
-  static SingleFromRange(minimumInclusive, maximumInclusive) {
-    const sampledNumber = Math.floor(Math.random() * (maximumInclusive - minimumInclusive + 1)) + minimumInclusive;
+  static singleFromRange(minimumInclusive, maximumInclusive) {
+    if (!Number.isInteger(minimumInclusive) || !Number.isInteger(maximumInclusive)) {
+      throw new M2Error("All inputs must be integers");
+    }
+    if (maximumInclusive < minimumInclusive) {
+      throw new M2Error(
+        `maximumInclusive (${maximumInclusive}) must be >= minimumInclusive (${minimumInclusive})`
+      );
+    }
+    const sampledNumber = Math.floor(
+      this.randomFunction() * (maximumInclusive - minimumInclusive + 1)
+    ) + minimumInclusive;
     return sampledNumber;
   }
+  /**
+   * @deprecated Use `singleFromRange()` instead.
+   */
+  static SingleFromRange(minimumInclusive, maximumInclusive) {
+    return this.singleFromRange(minimumInclusive, maximumInclusive);
+  }
   /**
    * Draws random integers, without replacement, from a uniform distribution
    * of integers in the specified range.
@@ -12784,21 +12850,39 @@ class RandomDraws {
    * @param maximumInclusive - Upper bound of range
    * @returns An array of integers
    */
-  static FromRangeWithoutReplacement(n, minimumInclusive, maximumInclusive) {
-    if (n > maximumInclusive - minimumInclusive + 1) {
+  static fromRangeWithoutReplacement(n, minimumInclusive, maximumInclusive) {
+    if (!Number.isInteger(n) || !Number.isInteger(minimumInclusive) || !Number.isInteger(maximumInclusive)) {
+      throw new M2Error("All inputs must be integers");
+    }
+    const rangeSize = maximumInclusive - minimumInclusive + 1;
+    if (n > rangeSize) {
       throw new M2Error(
-        `number of requested draws (n = ${n}) is greater than number of integers in range [ ${minimumInclusive}, ${maximumInclusive}]`
+        `number of requested draws (n = ${n}) is greater than number of integers in range [${minimumInclusive}, ${maximumInclusive}]`
       );
     }
-    const result = new Array();
-    for (let i = 0; i < n; i++) {
-      const sampledNumber = RandomDraws.SingleFromRange(
+    const selected = /* @__PURE__ */ new Set();
+    for (let i = rangeSize - n; i < rangeSize; i++) {
+      const t = _RandomDraws.singleFromRange(
         minimumInclusive,
-        maximumInclusive
+        minimumInclusive + i
       );
-      result.includes(sampledNumber) ? n++ : result.push(sampledNumber);
+      if (selected.has(t)) {
+        selected.add(minimumInclusive + i);
+      } else {
+        selected.add(t);
+      }
     }
-    return result;
+    return Array.from(selected);
+  }
+  /**
+   * @deprecated Use `fromRangeWithoutReplacement()` instead.
+   */
+  static FromRangeWithoutReplacement(n, minimumInclusive, maximumInclusive) {
+    return this.fromRangeWithoutReplacement(
+      n,
+      minimumInclusive,
+      maximumInclusive
+    );
   }
   /**
    * Draw random grid cell locations, without replacement, from a uniform
@@ -12816,10 +12900,10 @@ class RandomDraws {
    * @returns Array of grid cells. Each cell is object in form of:
    * &#123 row: number, column: number &#125;. Grid cell locations are zero-based
    */
-  static FromGridWithoutReplacement(n, rows, columns, predicate) {
+  static fromGridWithoutReplacement(n, rows, columns, predicate) {
     const result = new Array();
     const maximumInclusive = rows * columns - 1;
-    const draws = this.FromRangeWithoutReplacement(n, 0, maximumInclusive);
+    const draws = this.fromRangeWithoutReplacement(n, 0, maximumInclusive);
     let i = 0;
     let replacementCell = NaN;
     while (i < n) {
@@ -12830,7 +12914,7 @@ class RandomDraws {
         i++;
       } else {
         do {
-          replacementCell = this.FromRangeWithoutReplacement(
+          replacementCell = this.fromRangeWithoutReplacement(
             1,
             0,
             maximumInclusive
@@ -12841,6 +12925,98 @@ class RandomDraws {
     }
     return result;
   }
+  /**
+   * @deprecated Use `fromGridWithoutReplacement()` instead.
+   */
+  static FromGridWithoutReplacement(n, rows, columns, predicate) {
+    return this.fromGridWithoutReplacement(n, rows, columns, predicate);
+  }
+};
+_RandomDraws.randomFunction = Math.random;
+_RandomDraws.seededPRNG = null;
+let RandomDraws = _RandomDraws;
+const pool = [];
+const width = 256;
+const chunks = 6;
+const digits = 52;
+const startDenom = Math.pow(width, chunks);
+const significance = Math.pow(2, digits);
+const overflow = significance * 2;
+const mask = width - 1;
+function seedrandom(seed) {
+  const key = [];
+  mixKey(seed, key);
+  const arc4 = new ARC4(key);
+  const prng = (() => {
+    let n = arc4.g(chunks);
+    let d = startDenom;
+    let x = 0;
+    while (n < significance) {
+      n = (n + x) * width;
+      d *= width;
+      x = arc4.g(1);
+    }
+    while (n >= overflow) {
+      n /= 2;
+      d /= 2;
+      x >>>= 1;
+    }
+    return (n + x) / d;
+  });
+  prng.int32 = () => arc4.g(4) | 0;
+  prng.quick = () => arc4.g(4) / 4294967296;
+  prng.double = prng;
+  mixKey(tostring(arc4.S), pool);
+  return prng;
+}
+class ARC4 {
+  constructor(key) {
+    this.i = 0;
+    this.j = 0;
+    this.S = [];
+    let t;
+    let keylen = key.length;
+    const s = this.S;
+    if (!keylen) key = [keylen++];
+    for (let i = 0; i < width; i++) s[i] = i;
+    for (let i = 0, j = 0; i < width; i++) {
+      t = s[i];
+      j = mask & j + key[i % keylen] + t;
+      s[i] = s[j];
+      s[j] = t;
+    }
+    this.g(width);
+  }
+  /** Returns the next `count` outputs concatenated as a single number. */
+  g(count) {
+    let r = 0;
+    let i = this.i;
+    let j = this.j;
+    const s = this.S;
+    while (count--) {
+      const t = s[i = mask & i + 1];
+      const u = s[j = mask & j + t];
+      s[i] = u;
+      s[j] = t;
+      r = r * width + s[mask & u + t];
+    }
+    this.i = i;
+    this.j = j;
+    return r;
+  }
+}
+function mixKey(seed, key) {
+  let hash = 0;
+  let j = 0;
+  while (j < seed.length) {
+    key[mask & j] = mask & (hash ^= key[mask & j] * 19) + seed.charCodeAt(j);
+    j++;
+  }
+  return tostring(key);
+}
+function tostring(a) {
+  const arr = Array.prototype.slice.call(a, 0);
+  return String.fromCharCode.apply(null, arr);
 }
 
 class SoundPlayer extends M2Node {
@@ -13300,7 +13476,7 @@ class Story {
   }
 }
 
-console.log("\u26AA @m2c2kit/core version 0.3.32 (f8bdff76)");
+console.log("\u26AA @m2c2kit/core version 0.3.34 (d289d12c)");
 
 export { Action, ActivityType, CanvasKitHelpers, ColorfulMutablePath, Composite, Constants, ConstraintType, CustomAction, Dimensions, Easings, Equal, Equals, EventStore, EventStoreMode, FadeAlphaAction, FontManager, Game, GroupAction, I18n, ImageManager, Label, LabelHorizontalAlignmentMode, LayoutConstraint, LegacyTimer, M2Error, M2EventType, M2ImageStatus, M2Node, M2NodeFactory, M2NodeType, M2SoundStatus, M2c2KitHelpers, MoveAction, MutablePath, NoneTransition, PlayAction, RandomDraws, RepeatAction, RepeatForeverAction, RotateAction, ScaleAction, Scene, SceneTransition, SequenceAction, Shape, ShapeType, SlideTransition, SoundManager, SoundPlayer, SoundRecorder, Sprite, Story, TextLine, Timer, Transition, TransitionDirection, TransitionType, Uuid, WaitAction, WebColors, WebGlInfo, handleInterfaceOptions };
 //# sourceMappingURL=index.js.map