isaacscript-common 71.2.0 → 72.0.0

package/src/functions/nextStage.ts

@@ -1,10 +1,12 @@
 import {
   GameStateFlag,
   GridRoom,
+  LevelCurse,
   LevelStage,
   StageType,
 } from "isaac-typescript-definitions";
 import { game } from "../core/cachedClasses";
+import { hasCurse } from "./curses";
 import { getRoomGridIndex } from "./roomData";
 import {
   calculateStageType,
@@ -56,7 +58,10 @@ export function getNextStage(): LevelStage {
         return asNumber(stage) + 1;
       }
 
-      if (stage === LevelStage.DEPTHS_2) {
+      if (
+        stage === LevelStage.DEPTHS_2 ||
+        (stage === LevelStage.DEPTHS_1 && hasCurse(LevelCurse.LABYRINTH))
+      ) {
         // From Depths 2 to Mausoleum 2 through the strange door.
         return LevelStage.DEPTHS_2;
       }

package/src/functions/random.ts

@@ -1,14 +1,18 @@
 import { ReadonlySet } from "../types/ReadonlySet";
-import { getRandomSeed, isRNG, newRNG } from "./rng";
+import { isRNG, newRNG } from "./rng";
 
 /**
  * Returns a random float between 0 and 1. It is inclusive on the low end, but exclusive on the high
  * end. (This is because the `RNG.RandomFloat` method will never return a value of exactly 1.)
  *
- * @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
- *                  `RNG.Next` method will be called. Default is `getRandomSeed()`.
+ * If you want to generate an unseeded number, you must explicitly pass `undefined` to the
+ * `seedOrRNG` parameter.
+ *
+ * @param seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. If `undefined` is provided, it will default to
+ *                  a random seed.
  */
-export function getRandom(seedOrRNG: Seed | RNG = getRandomSeed()): float {
+export function getRandom(seedOrRNG: Seed | RNG | undefined): float {
   const rng = isRNG(seedOrRNG) ? seedOrRNG : newRNG(seedOrRNG);
   return rng.RandomFloat();
 }
@@ -19,18 +23,22 @@ export function getRandom(seedOrRNG: Seed | RNG = getRandomSeed()): float {
  * For example:
  *
  * ```ts
- * const realNumberBetweenOneAndThree = getRandomFloat(1, 3);
+ * const realNumberBetweenOneAndThree = getRandomFloat(1, 3, undefined);
  * ```
  *
+ * If you want to generate an unseeded number, you must explicitly pass `undefined` to the
+ * `seedOrRNG` parameter.
+ *
  * @param min The lower bound for the random number (inclusive).
  * @param max The upper bound for the random number (exclusive).
- * @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
- *                  `RNG.Next` method will be called. Default is `getRandomSeed()`.
+ * @param seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. If `undefined` is provided, it will default to
+ *                  a random seed.
  */
 export function getRandomFloat(
   min: int,
   max: int,
-  seedOrRNG: Seed | RNG = getRandomSeed(),
+  seedOrRNG: Seed | RNG | undefined,
 ): float {
   if (min > max) {
     const oldMin = min;
@@ -46,19 +54,20 @@ export function getRandomFloat(
 /**
  * Returns a random integer between min and max. It is inclusive on both ends.
  *
- * Note that this function will run the `Next` method on the `RNG` object before returning the
- * random number.
- *
  * For example:
  *
  * ```ts
  * const oneTwoOrThree = getRandomInt(1, 3);
  * ```
  *
+ * If you want to generate an unseeded number, you must explicitly pass `undefined` to the
+ * `seedOrRNG` parameter.
+ *
  * @param min The lower bound for the random number (inclusive).
  * @param max The upper bound for the random number (inclusive).
- * @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
- *                  `RNG.Next` method will be called. Default is `getRandomSeed()`.
+ * @param seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. If `undefined` is provided, it will default to
+ *                  a random seed.
  * @param exceptions Optional. An array of elements that will be skipped over when getting the
  *                   random integer. For example, a min of 1, a max of 4, and an exceptions array of
  *                   `[2]` would cause the function to return either 1, 3, or 4. Default is an empty
@@ -67,7 +76,7 @@ export function getRandomFloat(
 export function getRandomInt(
   min: int,
   max: int,
-  seedOrRNG: Seed | RNG = getRandomSeed(),
+  seedOrRNG: Seed | RNG | undefined,
   exceptions: int[] | readonly int[] = [],
 ): int {
   const rng = isRNG(seedOrRNG) ? seedOrRNG : newRNG(seedOrRNG);

package/src/functions/rng.ts

@@ -86,7 +86,7 @@ export function isSerializedRNG(object: unknown): object is SerializedRNG {
 /**
  * Helper function to initialize a new RNG object using Blade's recommended shift index.
  *
- * @param seed The seed to initialize it with. Default is `getRandomSeed()`.
+ * @param seed Optional. The seed to initialize it with. Default is a random seed.
  */
 export function newRNG(seed = getRandomSeed()): RNG {
   const rng = RNG();

package/src/functions/set.ts

@@ -1,6 +1,5 @@
 import { ReadonlySet } from "../types/ReadonlySet";
 import { getArrayCombinations, getRandomArrayElement, sumArray } from "./array";
-import { getRandomSeed } from "./rng";
 import { isPrimitive } from "./types";
 
 /**
@@ -68,14 +67,18 @@ export function deleteSetsFromSet<T>(
 /**
  * Helper function to get a random element from the provided set.
  *
+ * If you want to get an unseeded element, you must explicitly pass `undefined` to the `seedOrRNG`
+ * parameter.
+ *
  * @param set The set to get an element from.
- * @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
- *                  `RNG.Next` method will be called. Default is `getRandomSeed()`.
+ * @param seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. If `undefined` is provided, it will default to
+ *                  a random seed.
  * @param exceptions Optional. An array of elements to skip over if selected.
  */
 export function getRandomSetElement<T>(
   set: Set<T> | ReadonlySet<T>,
-  seedOrRNG: Seed | RNG = getRandomSeed(),
+  seedOrRNG: Seed | RNG | undefined,
   exceptions: T[] | readonly T[] = [],
 ): T {
   const array = getSortedSetValues(set);

package/src/functions/spawnCollectible.ts

@@ -20,10 +20,14 @@ import { getRandomSeed, isRNG } from "./rng";
  * Isaac's rotation mechanic. To handle that, use the `spawnCollectible` helper function instead
  * (which is provided by `ISCFeature.SPAWN_COLLECTIBLE`).
  *
+ * If you want to spawn an unseeded collectible, you must explicitly pass `undefined` to the
+ * `seedOrRNG` parameter.
+ *
  * @param collectibleType The collectible type to spawn.
  * @param positionOrGridIndex The position or grid index to spawn the collectible at.
- * @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
- *                  `RNG.Next` method will be called. Default is `getRandomSeed()`.
+ * @param seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. If `undefined` is provided, it will default to
+ *                  a random seed.
  * @param options Optional. Set to true to make the collectible a "There's Options" style
  *                collectible. Default is false.
  * @param forceFreeItem Optional. Set to true to disable the logic that gives the item a price for
@@ -33,11 +37,15 @@ import { getRandomSeed, isRNG } from "./rng";
 export function spawnCollectibleUnsafe(
   collectibleType: CollectibleType,
   positionOrGridIndex: Vector | int,
-  seedOrRNG: Seed | RNG = getRandomSeed(),
+  seedOrRNG: Seed | RNG | undefined,
   options = false,
   forceFreeItem = false,
   spawner?: Entity,
 ): EntityPickupCollectible {
+  if (seedOrRNG === undefined) {
+    seedOrRNG = getRandomSeed();
+  }
+
   const seed = isRNG(seedOrRNG) ? seedOrRNG.Next() : seedOrRNG;
   const collectible = spawnPickupWithSeed(
     PickupVariant.COLLECTIBLE,
@@ -82,13 +90,17 @@ export function spawnCollectibleUnsafe(
  * Onion because it is a quest collectible and quest collectibles will prevent Damocles from
  * duplicating the pedestal.)
  *
+ * If you want to spawn an unseeded collectible, you must explicitly pass `undefined` to the
+ * `seedOrRNG` parameter.
+ *
  * @param positionOrGridIndex The position or grid index to spawn the empty collectible at.
  * @param seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
- *                  `RNG.Next` method will be called. Default is `getRandomSeed()`.
+ *                  `RNG.Next` method will be called. If `undefined` is provided, it will default to
+ *                  a random seed.
  */
 export function spawnEmptyCollectible(
   positionOrGridIndex: Vector | int,
-  seedOrRNG: Seed | RNG = getRandomSeed(),
+  seedOrRNG: Seed | RNG | undefined,
 ): EntityPickup {
   const collectible = spawnCollectibleUnsafe(
     CollectibleType.BROKEN_SHOVEL_1,

package/src/functions/vector.ts

@@ -6,7 +6,7 @@ import { SerializationBrand } from "../enums/private/SerializationBrand";
 import { angleToDirection } from "./direction";
 import { isIsaacAPIClassOfType, isaacAPIClassEquals } from "./isaacAPIClass";
 import { getRandomFloat } from "./random";
-import { getRandomSeed, isRNG, newRNG } from "./rng";
+import { isRNG, newRNG } from "./rng";
 import {
   copyUserdataValuesToTable,
   getNumbersFromTable,
@@ -109,11 +109,15 @@ export function getClosestVectorTo(
  *
  * Use this over the `RandomVector` function when you need the vector to be seeded.
  *
- * @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
- *                  `RNG.Next` method will be called. Default is `getRandomSeed()`.
+ * If you want to generate an unseeded vector, you must explicitly pass `undefined` to the
+ * `seedOrRNG` parameter.
+ *
+ * @param seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. If `undefined` is provided, it will default to
+ *                  a random seed.
  */
 export function getRandomVector(
-  seedOrRNG: Seed | RNG = getRandomSeed(),
+  seedOrRNG: Seed | RNG | undefined,
 ): Readonly<Vector> {
   const rng = isRNG(seedOrRNG) ? seedOrRNG : newRNG(seedOrRNG);
 

package/src/functions/weighted.ts

@@ -1,17 +1,24 @@
 import type { WeightedArray } from "../types/WeightedArray";
 import { sumArray } from "./array";
 import { getRandomFloat } from "./random";
-import { getRandomSeed } from "./rng";
 import { assertDefined } from "./utils";
 
 /**
  * Get a random value from a `WeightedArray`. (A `WeightedArray` is an array of tuples, where the
  * first element in the tuple is a value, and the second element in the tuple is a float
  * corresponding to the value's weight.)
+ *
+ * If you want to get an unseeded element, you must explicitly pass `undefined` to the `seedOrRNG`
+ * parameter.
+ *
+ * @param weightedArray The array to pick from.
+ * @param seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. If `undefined` is provided, it will default to
+ *                  a random seed.
  */
 export function getRandomFromWeightedArray<T>(
   weightedArray: WeightedArray<T>,
-  seedOrRNG: Seed | RNG = getRandomSeed(),
+  seedOrRNG: Seed | RNG | undefined,
 ): T {
   const randomIndex = getRandomIndexFromWeightedArray(weightedArray, seedOrRNG);
 
@@ -28,10 +35,18 @@ export function getRandomFromWeightedArray<T>(
  * Get a random index from a `WeightedArray`. (A `WeightedArray` is an array of tuples, where the
  * first element in the tuple is a value, and the second element in the tuple is a float
  * corresponding to the value's weight.)
+ *
+ * If you want to get an unseeded index, you must explicitly pass `undefined` to the `seedOrRNG`
+ * parameter.
+ *
+ * @param weightedArray The array to pick from.
+ * @param seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. If `undefined` is provided, it will default to
+ *                  a random seed.
  */
 export function getRandomIndexFromWeightedArray<T>(
   weightedArray: WeightedArray<T>,
-  seedOrRNG: Seed | RNG = getRandomSeed(),
+  seedOrRNG: Seed | RNG | undefined,
 ): int {
   if (weightedArray.length === 0) {
     error(