isaacscript-common 6.11.2 → 6.14.0

package/src/functions/color.ts

@@ -1,6 +1,8 @@
 import { SerializationBrand } from "../enums/private/SerializationBrand";
 import { SerializationType } from "../enums/SerializationType";
 import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
+import { getRandom } from "./random";
+import { getRandomSeed, isRNG, newRNG } from "./rng";
 import { copyValuesToTable, getNumbersFromTable, tableHasKeys } from "./table";
 import { isTable } from "./types";
 
@@ -105,6 +107,26 @@ export function copyColor(
   }
 }
 
+/**
+ * Helper function to get a random color.
+ *
+ * @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 alpha Optional. The alpha value to use. Default is 1.
+ */
+export function getRandomColor(
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+  alpha = 1,
+): Color {
+  const rng = isRNG(seedOrRNG) ? seedOrRNG : newRNG(seedOrRNG);
+
+  const r = getRandom(rng);
+  const g = getRandom(rng);
+  const b = getRandom(rng);
+
+  return Color(r, g, b, alpha);
+}
+
 /** Helper function to check if something is an instantiated Color object. */
 export function isColor(object: unknown): object is Color {
   return isIsaacAPIClassOfType(object, OBJECT_NAME);

package/src/functions/entities.ts

@@ -7,6 +7,7 @@ import { getIsaacAPIClassName } from "./isaacAPIClass";
 import { getRandom } from "./random";
 import { isRNG, newRNG } from "./rng";
 import { isPrimitive } from "./types";
+import { isVector, vectorToString } from "./vector";
 
 /**
  * Helper function to count the number of entities in room. Use this over the vanilla
@@ -130,10 +131,10 @@ export function getEntities(
 
 /**
  * Helper function to get all the fields on an entity. For example, this is useful for comparing it
- * to another entity later.
+ * to another entity later. (One option is to use the `logTableDifferences` function for this.)
  *
- * This function will only get fields that are equal to booleans, numbers, or strings, as comparing
- * other types is non-trivial.
+ * This function will only get fields that are equal to booleans, numbers, or strings, or Vectors,
+ * as comparing other types is non-trivial.
  */
 export function getEntityFields(
   entity: Entity,
@@ -187,6 +188,8 @@ function setPrimitiveEntityFields(
     const value = entity[indexKey];
     if (isPrimitive(value)) {
       entityFields.set(indexKey, value);
+    } else if (isVector(value)) {
+      entityFields.set(indexKey, vectorToString(value));
     }
   }
 }

package/src/functions/gridEntities.ts

@@ -19,7 +19,6 @@ import {
 import { BACKDROP_TYPE_TO_ROCK_ALT_TYPE } from "../objects/backdropTypeToRockAltType";
 import { AnyGridEntity } from "../types/AnyGridEntity";
 import { isCircleIntersectingRectangle } from "./math";
-import { getRandomSeed } from "./rng";
 import { roomUpdateSafe } from "./rooms";
 import { clearSprite } from "./sprites";
 import { isNumber } from "./types";
@@ -95,8 +94,8 @@ export function getAllGridIndexes(): int[] {
  * Gets the entities that have a hitbox that overlaps with any part of the square that the grid
  * entity is on.
  *
- * Note that this function will not work properly in the PostNewRoom callback, since entities do not
- * have collision yet in that callback.
+ * Note that this function will not work properly in the `POST_NEW_ROOM` callback, since entities do
+ * not have collision yet in that callback.
  */
 export function getCollidingEntitiesWithGridEntity(
   gridEntity: GridEntity,
@@ -488,7 +487,7 @@ export function removeAllMatchingGridEntities(
  *                   generally a good idea because if the room is not updated, you will be unable to
  *                   spawn another grid entity on the same tile until a frame has passed. However,
  *                   doing this is expensive, since it involves a call to `Isaac.GetRoomEntities`,
- *                   so set this to false if you need to invoke this function multiple times.
+ *                   so set this to false if you need to run this function multiple times.
  * @param cap Optional. If specified, will only remove the given amount of entities.
  * @returns An array of the entities that were removed.
  */
@@ -527,7 +526,7 @@ export function removeGridEntities<T extends AnyGridEntity>(
  *                   generally a good idea because if the room is not updated, you will be unable to
  *                   spawn another grid entity on the same tile until a frame has passed. However,
  *                   doing this is expensive, since it involves a call to `Isaac.GetRoomEntities`,
- *                   so set this to false if you need to invoke this function multiple times.
+ *                   so set this to false if you need to run this function multiple times.
  */
 export function removeGridEntity(
   gridEntityOrGridIndex: GridEntity | int,
@@ -654,57 +653,6 @@ export function spawnGridEntityWithVariant(
   return gridEntity;
 }
 
-/**
- * Helper function for emulating what happens when a vanilla `GridEntityType.ROCK_ALT` grid entity
- * breaks.
- *
- * Note that most of the time, this function will do nothing, similar to how most of the time, when
- * an individual urn is destroyed, nothing will spawn.
- *
- * The logic in this function is based on the rewards listed on the wiki:
- * https://bindingofisaacrebirth.fandom.com/wiki/Rocks
- *
- * @param rockAltType The type of reward to spawn. For example, `RockAltType.URN` will have a chance
- *                    at spawning coins and spiders.
- * @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()`. Normally,
- *                   you should pass the `InitSeed` of the grid entity that was broken.
- * @returns Whether or not this function spawned something.
- */
-export function spawnRockAltReward(
-  rockAltType: RockAltType,
-  _seedOrRNG: Seed | RNG = getRandomSeed(),
-): boolean {
-  /// const chance = getRandom(seedOrRNG);
-
-  switch (rockAltType) {
-    case RockAltType.URN: {
-      // TODO
-      return false;
-    }
-
-    case RockAltType.MUSHROOM: {
-      // TODO
-      return false;
-    }
-
-    case RockAltType.SKULL: {
-      // TODO
-      return false;
-    }
-
-    case RockAltType.POLYP: {
-      // TODO
-      return false;
-    }
-
-    case RockAltType.BUCKET: {
-      // TODO
-      return false;
-    }
-  }
-}
-
 /**
  * Helper function to spawn a Void Portal. This is more complicated than simply spawning a trapdoor
  * with the appropriate variant, as the game does not give it the correct sprite automatically.

package/src/functions/isaacAPIClass.ts

@@ -1,4 +1,5 @@
 import { IsaacAPIClass } from "../types/private/IsaacAPIClass";
+import { trimPrefix } from "./string";
 import { isString, isUserdata } from "./types";
 
 /**
@@ -9,6 +10,10 @@ import { isString, isUserdata } from "./types";
  *
  * Returns undefined if the object is not of type `userdata` or if the "__type" metatable key does
  * not exist.
+ *
+ * In some cases, Isaac classes can be a read-only. If this is the case, the "__type" field will be
+ * prepended with "const ". This function will always strip this prefix, if it exists. For example,
+ * the class name returned for "const Vector" will be "Vector".
  */
 export function getIsaacAPIClassName(object: unknown): string | undefined {
   if (!isUserdata(object)) {
@@ -27,7 +32,40 @@ export function getIsaacAPIClassName(object: unknown): string | undefined {
     return undefined;
   }
 
-  return classType;
+  return trimPrefix(classType, "const ");
+}
+
+/** Helper function to detect if a variable is of type `EntityBomb`. */
+export function isBomb(variable: unknown): variable is EntityBomb {
+  return getIsaacAPIClassName(variable) === "EntityBomb";
+}
+
+/** Helper function to detect if a variable is of type `GridEntityDoor`. */
+export function isDoor(variable: unknown): variable is GridEntityDoor {
+  return getIsaacAPIClassName(variable) === "GridEntityDoor";
+}
+
+/** Helper function to detect if a variable is of type `EntityEffect`. */
+export function isEffect(variable: unknown): variable is EntityEffect {
+  return getIsaacAPIClassName(variable) === "EntityEffect";
+}
+
+/**
+ * Helper function to detect if a variable is of type `Entity`. This will return false for child
+ * classes such as `EntityPlayer` or `EntityTear`.
+ */
+export function isEntity(variable: unknown): variable is Entity {
+  return getIsaacAPIClassName(variable) === "Entity";
+}
+
+/** Helper function to detect if a variable is of type `EntityEffect`. */
+export function isFamiliar(variable: unknown): variable is EntityFamiliar {
+  return getIsaacAPIClassName(variable) === "EntityEffect";
+}
+
+/** Helper function to detect if a variable is of type `GridEntity`. */
+export function isGridEntity(variable: unknown): variable is GridEntity {
+  return getIsaacAPIClassName(variable) === "GridEntity";
 }
 
 /**
@@ -51,6 +89,73 @@ export function isIsaacAPIClassOfType(
   );
 }
 
+/** Helper function to detect if a variable is of type `EntityKnife`. */
+export function isKnife(variable: unknown): variable is EntityKnife {
+  return getIsaacAPIClassName(variable) === "EntityKnife";
+}
+
+/** Helper function to detect if a variable is of type `EntityLaser`. */
+export function isLaser(variable: unknown): variable is EntityLaser {
+  return getIsaacAPIClassName(variable) === "EntityLaser";
+}
+
+/** Helper function to detect if a variable is of type `EntityNPC`. */
+export function isNPC(variable: unknown): variable is EntityNPC {
+  return getIsaacAPIClassName(variable) === "EntityNPC";
+}
+
+/** Helper function to detect if a variable is of type `EntityPickup`. */
+export function isPickup(variable: unknown): variable is EntityPickup {
+  return getIsaacAPIClassName(variable) === "EntityPickup";
+}
+
+/** Helper function to detect if a variable is of type `GridEntityPit`. */
+export function isPit(variable: unknown): variable is GridEntityPit {
+  return getIsaacAPIClassName(variable) === "GridEntityPit";
+}
+
+/** Helper function to detect if a variable is of type `EntityPlayer`. */
+export function isPlayer(variable: unknown): variable is EntityPlayer {
+  return getIsaacAPIClassName(variable) === "EntityPlayer";
+}
+
+/** Helper function to detect if a variable is of type `GridEntityPoop`. */
+export function isPoop(variable: unknown): variable is GridEntityPoop {
+  return getIsaacAPIClassName(variable) === "GridEntityPoop";
+}
+
+/** Helper function to detect if a variable is of type `GridEntityPressurePlate`. */
+export function isPressurePlate(
+  variable: unknown,
+): variable is GridEntityPressurePlate {
+  return getIsaacAPIClassName(variable) === "GridEntityPressurePlate";
+}
+
+/** Helper function to detect if a variable is of type `EntityProjectile`. */
+export function isProjectile(variable: unknown): variable is EntityProjectile {
+  return getIsaacAPIClassName(variable) === "EntityProjectile";
+}
+
+/** Helper function to detect if a variable is of type `GridEntityRock`. */
+export function isRock(variable: unknown): variable is GridEntityRock {
+  return getIsaacAPIClassName(variable) === "GridEntityRock";
+}
+
+/** Helper function to detect if a variable is of type `GridEntitySpikes`. */
+export function isSpikes(variable: unknown): variable is GridEntitySpikes {
+  return getIsaacAPIClassName(variable) === "GridEntitySpikes";
+}
+
+/** Helper function to detect if a variable is of type `GridEntityTNT`. */
+export function isTNT(variable: unknown): variable is GridEntityTNT {
+  return getIsaacAPIClassName(variable) === "GridEntityTNT";
+}
+
+/** Helper function to detect if a variable is of type `EntityTear`. */
+export function isTear(variable: unknown): variable is EntityTear {
+  return getIsaacAPIClassName(variable) === "EntityTear";
+}
+
 /**
  * Helper function to check if an instantiated Isaac API class is equal to another one of the same
  * type. You must provide the list of keys to check for.

package/src/functions/kColor.ts

@@ -1,6 +1,8 @@
 import { SerializationBrand } from "../enums/private/SerializationBrand";
 import { SerializationType } from "../enums/SerializationType";
 import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
+import { getRandom } from "./random";
+import { getRandomSeed, isRNG, newRNG } from "./rng";
 import { copyValuesToTable, getNumbersFromTable, tableHasKeys } from "./table";
 import { isTable } from "./types";
 
@@ -98,6 +100,26 @@ export function copyKColor(
   }
 }
 
+/**
+ * Helper function to get a random color.
+ *
+ * @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 alpha Optional. The alpha value to use. Default is 1.
+ */
+export function getRandomKColor(
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+  alpha = 1,
+): KColor {
+  const rng = isRNG(seedOrRNG) ? seedOrRNG : newRNG(seedOrRNG);
+
+  const r = getRandom(rng);
+  const g = getRandom(rng);
+  const b = getRandom(rng);
+
+  return KColor(r, g, b, alpha);
+}
+
 /** Helper function to check if something is an instantiated KColor object. */
 export function isKColor(object: unknown): object is KColor {
   return isIsaacAPIClassOfType(object, OBJECT_NAME);

package/src/functions/map.ts

@@ -1,3 +1,5 @@
+import { sumArray } from "./array";
+
 /** Helper function to copy a map. (You can also use a Map constructor to accomplish this task.) */
 export function copyMap<K, V>(oldMap: Map<K, V>): Map<K, V> {
   const newMap = new Map<K, V>();
@@ -54,3 +56,11 @@ export function getMapPartialMatch<T>(
 
   return [matchingKey, value];
 }
+
+/** Helper function to sum every value in a map together. */
+export function sumMap(
+  map: Map<unknown, number> | ReadonlyMap<unknown, number>,
+): number {
+  const values = [...map.values()];
+  return sumArray(values);
+}

package/src/functions/npcs.ts

@@ -152,8 +152,8 @@ export function isRaglingDeathPatch(npc: EntityNPC): boolean {
 
 /**
  * The base game `EntityNPC.FireProjectiles` method does not return anything, which is a problem in
- * situations where you need to work with the fired projectiles. This function invokes that method,
- * and then returns the projectiles that were spawned.
+ * situations where you need to work with the fired projectiles. This function runs that method, and
+ * then returns the projectiles that were spawned.
  *
  * @param npc The EntityNPC firing projectiles.
  * @param position The starting position of the projectiles.

package/src/functions/pickupVariants.ts

@@ -18,12 +18,12 @@ export function isKey(pickup: EntityPickup): pickup is EntityPickupKey {
 }
 
 /** For `PickupVariant.BOMB` (40) */
-export function isBomb(pickup: EntityPickup): pickup is EntityPickupBomb {
+export function isBombPickup(pickup: EntityPickup): pickup is EntityPickupBomb {
   return pickup.Variant === PickupVariant.BOMB;
 }
 
 /** For `PickupVariant.POOP` (42) */
-export function isPoop(pickup: EntityPickup): pickup is EntityPickupPoop {
+export function isPoopPickup(pickup: EntityPickup): pickup is EntityPickupPoop {
   return pickup.Variant === PickupVariant.POOP;
 }
 

package/src/functions/playerCenter.ts

@@ -6,7 +6,7 @@ import {
 } from "../constants";
 import { getPlayerFamiliars } from "./familiars";
 import { getCircleDiscretizedPoints } from "./math";
-import { getPlayers } from "./playerIndex";
+import { getAllPlayers } from "./playerIndex";
 
 const CIRCLE_RADIUS_BETWEEN_PLAYERS = 50;
 
@@ -25,7 +25,7 @@ export function movePlayersToCenter(): void {
     ? NEW_FLOOR_STARTING_POSITION_GREED_MODE
     : NEW_FLOOR_STARTING_POSITION_NORMAL_MODE;
 
-  const players = getPlayers();
+  const players = getAllPlayers();
   const firstPlayer = players[0];
   if (firstPlayer === undefined) {
     return;

package/src/functions/playerIndex.ts

@@ -72,9 +72,6 @@ export function getPlayerFromIndex(
  * Instead, we use the `EntityPlayer.GetCollectibleRNG` method with an arbitrary value of Sad Onion
  * (1). This works even if the player does not have any Sad Onions.
  *
- * Since the RNG value is the same for both Tainted Lazarus and Dead Tainted Lazarus, we revert to
- * using the RNG of The Inner Eye (2) for Dead Tainted Lazarus.
- *
  * Note that by default, this returns the same index for both The Forgotten and The Soul. (Even
  * though they are technically different characters, they share the same inventory and InitSeed.) If
  * this is not desired, pass true for the `differentiateForgottenAndSoul` argument, and the RNG of
@@ -94,13 +91,13 @@ export function getPlayerIndex(
   // We can safely ignore the player's character because regardless of whether the main player ends
   // up being The Forgotten or The Soul, the collectible RNG values will be the same. The
   // `EntityPlayer.IsSubPlayer` method can return true for Dead Tainted Lazarus during the
-  // PostPlayerInit callback, but since we fall back to the player in the case of
+  // `POST_PLAYER_INIT` callback, but since we fall back to the player in the case of
   // "getSubPlayerParent" returning undefined, we do not need to explicitly check for this case.
   let playerToUse = player;
   const isSubPlayer = player.IsSubPlayer();
   if (isSubPlayer) {
     // The "getSubPlayerParent" function will return undefined in the situation where we are on Dead
-    // Tainted Lazarus in the PostPlayerInit callback.
+    // Tainted Lazarus in the `POST_PLAYER_INIT` callback.
     const playerParent = getSubPlayerParent(player as EntitySubPlayer);
     if (playerParent !== undefined) {
       playerToUse = playerParent;
@@ -123,23 +120,13 @@ function getPlayerIndexCollectibleType(
 ) {
   const character = player.GetPlayerType();
 
-  switch (character) {
-    // 17
-    case PlayerType.THE_SOUL: {
-      return differentiateForgottenAndSoul
-        ? CollectibleType.SPOON_BENDER
-        : DEFAULT_COLLECTIBLE_TYPE;
-    }
-
-    // 38
-    case PlayerType.LAZARUS_2_B: {
-      return CollectibleType.INNER_EYE;
-    }
-
-    default: {
-      return DEFAULT_COLLECTIBLE_TYPE;
-    }
+  if (character === PlayerType.THE_SOUL) {
+    return differentiateForgottenAndSoul
+      ? CollectibleType.INNER_EYE
+      : DEFAULT_COLLECTIBLE_TYPE;
   }
+
+  return DEFAULT_COLLECTIBLE_TYPE;
 }
 
 /**

package/src/functions/random.ts

@@ -45,7 +45,7 @@ export function getRandomFloat(
 /**
  * This returns a random integer between min and max. It is inclusive on both ends.
  *
- * Note that this function will invoke the `Next` method on the `RNG` object before returning the
+ * Note that this function will run the `Next` method on the `RNG` object before returning the
  * random number.
  *
  * For example:

package/src/functions/rockAlt.ts

@@ -0,0 +1,117 @@
+import {
+  CoinSubType,
+  CollectibleType,
+  TrinketType,
+} from "isaac-typescript-definitions";
+import { DISTANCE_OF_GRID_TILE } from "../constants";
+import { RockAltType } from "../enums/RockAltType";
+import { spawnCoinWithSeed, spawnTrinketWithSeed } from "./pickupsSpecific";
+import { getRandom } from "./random";
+import { getRandomSeed, isRNG, newRNG } from "./rng";
+import { spawnCollectible } from "./spawnCollectible";
+import { repeat } from "./utils";
+import { getRandomVector } from "./vector";
+
+/**
+ * Helper function for emulating what happens when a vanilla `GridEntityType.ROCK_ALT` grid entity
+ * breaks.
+ *
+ * Note that most of the time, this function will do nothing, similar to how most of the time, when
+ * an individual urn is destroyed, nothing will spawn.
+ *
+ * For the purposes of spawning collectibles, this function assumes that the player has not seen the
+ * collectible yet in the current run. In vanilla, it is only possible to get a e.g. Quarter if the
+ * collectible still exists in the Treasure Room pool.
+ *
+ * The logic in this function is based on the rewards listed on the wiki:
+ * https://bindingofisaacrebirth.fandom.com/wiki/Rocks
+ *
+ * @param position The place to spawn the reward.
+ * @param rockAltType The type of reward to spawn. For example, `RockAltType.URN` will have a chance
+ *                    at spawning coins and spiders.
+ * @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()`. Normally, you
+ *                  should pass the `InitSeed` of the grid entity that was broken.
+ * @returns Whether or not this function spawned something.
+ */
+export function spawnRockAltReward(
+  position: Vector,
+  rockAltType: RockAltType,
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+): boolean {
+  const rng = isRNG(seedOrRNG) ? seedOrRNG : newRNG(seedOrRNG);
+  const chance = getRandom(rng);
+
+  switch (rockAltType) {
+    case RockAltType.URN: {
+      let totalChance = 0;
+
+      // Nothing. (68.00%)
+      totalChance += 0.68;
+      if (chance < totalChance) {
+        return false;
+      }
+
+      // One or two random coins. (9.44%)
+      totalChance += 0.0944;
+      if (chance < totalChance) {
+        const numCoinsChance = getRandom(rng);
+        const numCoins = numCoinsChance < 0.5 ? 1 : 2;
+        repeat(numCoins, () => {
+          const velocity = getRandomVector(rng);
+          spawnCoinWithSeed(CoinSubType.NULL, position, rng, velocity);
+        });
+        return true;
+      }
+
+      // Swallowed Penny. (2.50%)
+      totalChance += 0.025;
+      if (chance < totalChance) {
+        spawnTrinketWithSeed(TrinketType.SWALLOWED_PENNY, position, rng);
+      }
+
+      // A Quarter. (0.50%)
+      totalChance += 0.005;
+      if (chance < totalChance) {
+        spawnCollectible(CollectibleType.QUARTER, position, rng);
+      }
+
+      // One or two spiders. (19.48%)
+      totalChance += 0.1948;
+      if (chance < totalChance) {
+        const numSpidersChance = getRandom(rng);
+        const numSpiders = numSpidersChance < 0.5 ? 1 : 2;
+        repeat(numSpiders, () => {
+          const randomVector = getRandomVector(rng);
+          const length = DISTANCE_OF_GRID_TILE * 3;
+          const offset = randomVector.mul(length);
+          const targetPos = position.add(offset);
+          EntityNPC.ThrowSpider(position, undefined, targetPos, false, 0);
+        });
+      }
+
+      // TODO
+      return false;
+    }
+
+    case RockAltType.MUSHROOM: {
+      // TODO
+      return false;
+    }
+
+    case RockAltType.SKULL: {
+      // TODO
+      return false;
+    }
+
+    case RockAltType.POLYP: {
+      // TODO
+      return false;
+    }
+
+    case RockAltType.BUCKET: {
+      // TODO
+      return false;
+    }
+  }
+}

package/src/functions/roomData.ts

@@ -187,9 +187,10 @@ export function getRoomVariant(roomGridIndex?: int): int {
 }
 
 /**
- * Note that the room visited count will be inaccurate during the period before the PostNewRoom
+ * Note that the room visited count will be inaccurate during the period before the `POST_NEW_ROOM`
  * callback has fired (i.e. when entities are initializing and performing their first update). This
- * is because the variable is only incremented immediately before the PostNewRoom callback fires.
+ * is because the variable is only incremented immediately before the `POST_NEW_ROOM` callback
+ * fires.
  *
  * @param roomGridIndex Optional. Default is the current room index.
  */

package/src/functions/rooms.ts

@@ -566,9 +566,9 @@ export function roomGridIndexToXY(roomGridIndex: int): [x: int, y: int] {
 }
 
 /**
- * If the `Room.Update` method is called in a PostNewRoom callback, then some entities will slide
- * around (such as the player). Since those entity velocities are already at zero, setting them to
- * zero will have no effect. Thus, a generic solution is to record all of the entity
+ * If the `Room.Update` method is called in a `POST_NEW_ROOM` callback, then some entities will
+ * slide around (such as the player). Since those entity velocities are already at zero, setting
+ * them to zero will have no effect. Thus, a generic solution is to record all of the entity
  * positions/velocities before updating the room, and then restore those positions/velocities.
  */
 export function roomUpdateSafe(): void {
@@ -585,9 +585,9 @@ export function roomUpdateSafe(): void {
 }
 
 /**
- * Helper function to convert an uncleared room to a cleared room in the PostNewRoom callback. This
- * is useful because if enemies are removed in this callback, a room drop will be awarded and the
- * doors will start closed and then open.
+ * Helper function to convert an uncleared room to a cleared room in the `POST_NEW_ROOM` callback.
+ * This is useful because if enemies are removed in this callback, a room drop will be awarded and
+ * the doors will start closed and then open.
  */
 export function setRoomCleared(): void {
   const room = game.GetRoom();

package/src/functions/set.ts

@@ -1,4 +1,4 @@
-import { getArrayCombinations, getRandomArrayElement } from "./array";
+import { getArrayCombinations, getRandomArrayElement, sumArray } from "./array";
 import { getRandomSeed } from "./rng";
 
 /**
@@ -122,3 +122,9 @@ export function getSortedSetValues<T>(set: Set<T> | ReadonlySet<T>): T[] {
 
   return array;
 }
+
+/** Helper function to sum every value in a set together. */
+export function sumSet(set: Set<number> | ReadonlySet<number>): number {
+  const values = [...set.values()];
+  return sumArray(values);
+}

package/src/functions/stage.ts

@@ -1,4 +1,9 @@
-import { LevelStage, RoomType, StageType } from "isaac-typescript-definitions";
+import {
+  GameStateFlag,
+  LevelStage,
+  RoomType,
+  StageType,
+} from "isaac-typescript-definitions";
 import { game } from "../cachedClasses";
 import { ROOM_TYPE_GOTO_PREFIXES } from "../objects/roomTypeGotoPrefixes";
 import { STAGE_TYPE_SUFFIXES } from "../objects/stageTypeSuffixes";
@@ -116,6 +121,10 @@ export function isRepentanceStage(stageType: StageType): boolean {
   );
 }
 
+export function onAscent(): boolean {
+  return game.GetStateFlag(GameStateFlag.BACKWARDS_PATH);
+}
+
 export function onCathedral(): boolean {
   const level = game.GetLevel();
   const stage = level.GetStage();