isaacscript-common 6.6.1-dev.2 → 6.6.1

package/src/functions/playerIndex.ts

@@ -0,0 +1,198 @@
+import { CollectibleType, PlayerType } from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { PlayerIndex } from "../types/PlayerIndex";
+
+const DEFAULT_COLLECTIBLE_TYPE = CollectibleType.SAD_ONION;
+
+const EXCLUDED_CHARACTERS: ReadonlySet<PlayerType> = new Set([
+  PlayerType.ESAU, // 20
+  PlayerType.THE_SOUL_B, // 40
+]);
+
+/**
+ * Helper function to get every player with no restrictions, by using `Game.GetNumPlayers` and
+ * `Isaac.GetPlayer`.
+ *
+ * This function is almost never what you want to use. For most purposes, use the `getPlayers`
+ * helper function instead to get a filtered list of players.
+ */
+export function getAllPlayers(): EntityPlayer[] {
+  const numPlayers = game.GetNumPlayers();
+
+  const players: EntityPlayer[] = [];
+  for (let i = 0; i < numPlayers; i++) {
+    const player = Isaac.GetPlayer(i);
+    players.push(player);
+  }
+
+  return players;
+}
+
+export function getPlayerFromIndex(
+  playerIndex: PlayerIndex,
+): EntityPlayer | undefined {
+  const players = getPlayers();
+  return players.find((player) => getPlayerIndex(player) === playerIndex);
+}
+
+/**
+ * Mods often have to track variables relating to the player. In naive mods, information will only
+ * be stored about the first player. However, in order to be robust, mods must handle up to 4
+ * players playing at the same time. This means that information must be stored on a map data
+ * structure. Finding a good index for these types of map data structures is difficult:
+ *
+ * - We cannot use the index from `Isaac.GetPlayer(i)` since this fails in the case where there are
+ *   two players and the first player leaves the run.
+ * - We cannot use `EntityPlayer.ControllerIndex` as an index because it fails in the case of Jacob
+ *   & Esau or Tainted Forgotten. It also fails in the case of a player changing their controls
+ *   mid-run.
+ * - We cannot use `EntityPlayer.GetData().index` because it does not persist across saving and
+ *   continuing.
+ * - We cannot use `GetPtrHash()` as an index because it does not persist across exiting and
+ *   relaunching the game.
+ * - We cannot use `EntityPlayer.InitSeed` because it is not consistent with additional players
+ *   beyond the first.
+ *
+ * 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
+ * Spoon Bender (3) will be used for The Soul.
+ */
+export function getPlayerIndex(
+  player: EntityPlayer,
+  differentiateForgottenAndSoul = false,
+): PlayerIndex {
+  // Sub-players use separate RNG values for some reason, so we need to always use the main player:
+  // https://github.com/Meowlala/RepentanceAPIIssueTracker/issues/443
+
+  // 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
+  // "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.
+    const playerParent = getSubPlayerParent(player as EntitySubPlayer);
+    if (playerParent !== undefined) {
+      playerToUse = playerParent;
+    }
+  }
+
+  const collectibleType = getPlayerIndexCollectibleType(
+    player,
+    differentiateForgottenAndSoul,
+  );
+  const collectibleRNG = playerToUse.GetCollectibleRNG(collectibleType);
+  const seed = collectibleRNG.GetSeed();
+
+  return seed as unknown as PlayerIndex;
+}
+
+function getPlayerIndexCollectibleType(
+  player: EntityPlayer,
+  differentiateForgottenAndSoul: boolean,
+) {
+  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;
+    }
+  }
+}
+
+/**
+ * Helper function to return the index of this player with respect to the output of the
+ * `Isaac.GetPlayer` method.
+ *
+ * Note that if you storing information about a player in a data structure, you never want to use
+ * this index; use the `getPlayerIndex` function instead.
+ */
+export function getPlayerIndexVanilla(
+  playerToFind: EntityPlayer,
+): int | undefined {
+  const numPlayers = game.GetNumPlayers();
+  const playerToFindHash = GetPtrHash(playerToFind);
+
+  for (let i = 0; i < numPlayers; i++) {
+    const player = Isaac.GetPlayer(i);
+    const playerHash = GetPtrHash(player);
+    if (playerHash === playerToFindHash) {
+      return i;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * This function always excludes players with a non-undefined parent, since they are not real
+ * players (e.g. the Strawman Keeper).
+ *
+ * If this is not desired, use the `getAllPlayers` helper function instead.
+ *
+ * @param performCharacterExclusions Whether or not to exclude characters that are not directly
+ *                                 controlled by the player (i.e. Esau & Tainted Soul). Default is
+ *                                 false.
+ */
+export function getPlayers(performCharacterExclusions = false): EntityPlayer[] {
+  const players = getAllPlayers();
+  const nonChildPlayers = players.filter((player) => !isChildPlayer(player));
+  const nonChildPlayersFiltered = nonChildPlayers.filter((player) => {
+    const character = player.GetPlayerType();
+    return !EXCLUDED_CHARACTERS.has(character);
+  });
+
+  return performCharacterExclusions ? nonChildPlayersFiltered : nonChildPlayers;
+}
+
+/**
+ * Helper function to get a parent `EntityPlayer` object for a given `EntitySubPlayer` object. This
+ * is useful because calling the `EntityPlayer.GetSubPlayer` method on a sub-player object will
+ * return undefined.
+ */
+export function getSubPlayerParent(
+  subPlayer: EntitySubPlayer,
+): EntityPlayer | undefined {
+  const subPlayerPtrHash = GetPtrHash(subPlayer);
+  const players = getPlayers();
+
+  return players.find((player) => {
+    const thisPlayerSubPlayer = player.GetSubPlayer();
+    if (thisPlayerSubPlayer === undefined) {
+      return false;
+    }
+
+    const thisPlayerSubPlayerPtrHash = GetPtrHash(thisPlayerSubPlayer);
+    return thisPlayerSubPlayerPtrHash === subPlayerPtrHash;
+  });
+}
+
+/**
+ * Some players are "child" players, meaning that they have a non-undefined Parent property. (For
+ * example, the Strawman Keeper.)
+ */
+export function isChildPlayer(player: EntityPlayer): boolean {
+  return player.Parent !== undefined;
+}

package/src/functions/pocketItems.ts

@@ -0,0 +1,149 @@
+import {
+  ActiveSlot,
+  Card,
+  CollectibleType,
+  PillColor,
+  PlayerType,
+  PocketItemSlot,
+} from "isaac-typescript-definitions";
+import { PocketItemType } from "../enums/PocketItemType";
+import { PocketItemDescription } from "../interfaces/PocketItemDescription";
+import { getEnumValues } from "./enums";
+import { isCharacter } from "./player";
+
+/**
+ * Helper function to get the `PocketItemSlot` that the player's pocket active collectible item is
+ * in, if any. Returns undefined if the player does not have a pocket active item.
+ */
+export function getActivePocketItemSlot(
+  player: EntityPlayer,
+): PocketItemSlot | undefined {
+  const pocketItems = getPocketItems(player);
+  for (const pocketItem of pocketItems) {
+    if (pocketItem.type === PocketItemType.ACTIVE_ITEM) {
+      return pocketItem.slot;
+    }
+  }
+
+  return undefined;
+}
+
+export function getFirstCardOrPill(
+  player: EntityPlayer,
+): PocketItemDescription | undefined {
+  const pocketItems = getPocketItems(player);
+  return pocketItems.find(
+    (pocketItem) =>
+      pocketItem.type === PocketItemType.CARD ||
+      pocketItem.type === PocketItemType.PILL,
+  );
+}
+
+/**
+ * Use this helper function as a workaround for the `EntityPlayer.GetPocketItem` method not working
+ * correctly.
+ *
+ * Note that due to API limitations, there is no way to determine the location of a Dice Bag trinket
+ * dice. Furthermore, when the player has a Dice Bag trinket dice and a pocket active at the same
+ * time, there is no way to determine the location of the pocket active item. If this function
+ * cannot determine the identity of a particular slot, it will mark the type of the slot as
+ * `PocketItemType.UNDETERMINABLE`.
+ */
+export function getPocketItems(player: EntityPlayer): PocketItemDescription[] {
+  const pocketItem = player.GetActiveItem(ActiveSlot.POCKET);
+  const hasPocketItem = pocketItem !== CollectibleType.NULL;
+
+  const pocketItem2 = player.GetActiveItem(ActiveSlot.POCKET_SINGLE_USE);
+  const hasPocketItem2 = pocketItem2 !== CollectibleType.NULL;
+
+  const maxPocketItems = player.GetMaxPocketItems();
+  const pocketItemSlots = getEnumValues(PocketItemSlot);
+
+  const pocketItems: PocketItemDescription[] = [];
+  let pocketItemIdentified = false;
+  let pocketItem2Identified = false;
+  for (const slot of pocketItemSlots) {
+    const card = player.GetCard(slot as PocketItemSlot);
+    const pillColor = player.GetPill(slot as PocketItemSlot);
+
+    if (card !== Card.NULL) {
+      pocketItems.push({
+        slot,
+        type: PocketItemType.CARD,
+        subType: card,
+      });
+    } else if (pillColor !== PillColor.NULL) {
+      pocketItems.push({
+        slot,
+        type: PocketItemType.PILL,
+        subType: pillColor,
+      });
+    } else if (hasPocketItem && !hasPocketItem2 && !pocketItemIdentified) {
+      pocketItemIdentified = true;
+      pocketItems.push({
+        slot,
+        type: PocketItemType.ACTIVE_ITEM,
+        subType: pocketItem,
+      });
+    } else if (!hasPocketItem && hasPocketItem2 && !pocketItem2Identified) {
+      pocketItem2Identified = true;
+      pocketItems.push({
+        slot,
+        type: PocketItemType.DICE_BAG_DICE,
+        subType: pocketItem2,
+      });
+    } else if (hasPocketItem && hasPocketItem2) {
+      pocketItems.push({
+        slot,
+        type: PocketItemType.UNDETERMINABLE,
+        subType: 0,
+      });
+    } else {
+      pocketItems.push({
+        slot,
+        type: PocketItemType.EMPTY,
+        subType: 0,
+      });
+    }
+
+    // eslint-disable-next-line isaacscript/strict-enums
+    if (slot + 1 === maxPocketItems) {
+      break;
+    }
+  }
+
+  return pocketItems;
+}
+
+/**
+ * Returns whether or not the player can hold an additional pocket item, beyond what they are
+ * currently carrying. This takes into account items that modify the max number of pocket items,
+ * like Starter Deck.
+ *
+ * If the player is the Tainted Soul, this always returns false, since that character cannot pick up
+ * items. (Only Tainted Forgotten can pick up items.)
+ */
+export function hasOpenPocketItemSlot(player: EntityPlayer): boolean {
+  if (isCharacter(player, PlayerType.THE_SOUL_B)) {
+    return false;
+  }
+
+  const pocketItems = getPocketItems(player);
+  return pocketItems.some(
+    (pocketItem) => pocketItem.type === PocketItemType.EMPTY,
+  );
+}
+
+/**
+ * Helper function to determine whether or not the player's "active" pocket item slot is set to
+ * their pocket active item.
+ */
+export function isFirstSlotPocketActiveItem(player: EntityPlayer): boolean {
+  const pocketItems = getPocketItems(player);
+  const firstPocketItem = pocketItems[0];
+  if (firstPocketItem === undefined) {
+    return false;
+  }
+
+  return firstPocketItem.type === PocketItemType.ACTIVE_ITEM;
+}

package/src/functions/positionVelocity.ts

@@ -0,0 +1,188 @@
+import {
+  EffectVariant,
+  HeavenLightDoorSubType,
+} from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { DISTANCE_OF_GRID_TILE } from "../constants";
+import { getEntities } from "./entity";
+import { getEffects } from "./entitySpecific";
+import { getPlayerCloserThan } from "./player";
+import { getPlayers } from "./playerIndex";
+
+const MAX_FIND_FREE_POSITION_ATTEMPTS = 100;
+
+export function anyEntityCloserThan(
+  entities: Entity[],
+  position: Vector,
+  distance: int,
+): boolean {
+  return entities.some(
+    (entity) => position.Distance(entity.Position) <= distance,
+  );
+}
+
+/** Iterates over all players and checks if any player is close enough to the specified position. */
+export function anyPlayerCloserThan(
+  position: Vector,
+  distance: float,
+): boolean {
+  const players = getPlayers();
+  return players.some(
+    (player) => player.Position.Distance(position) <= distance,
+  );
+}
+
+/**
+ * Helper function to get a room position that is not overlapping with a grid entity, a heaven door,
+ * or a player. The `Room.FindFreePickupSpawnPosition` method will return locations that overlap
+ * with heaven doors and partially overlap with players, if the thing being spawned is bigger than a
+ * tile (like a Blood Donation Machine). Use this function instead if you want to account for those
+ * specific situations.
+ *
+ * @param startingPosition The position to start searching from. If this position is not overlapping
+ *                         with anything, then it will be returned.
+ * @param avoidActiveEntities Optional. Default is false.
+ */
+export function findFreePosition(
+  startingPosition: Vector,
+  avoidActiveEntities = false,
+): Vector {
+  const room = game.GetRoom();
+  const heavenDoors = getEffects(
+    EffectVariant.HEAVEN_LIGHT_DOOR,
+    HeavenLightDoorSubType.HEAVEN_DOOR,
+  );
+
+  for (let i = 0; i < MAX_FIND_FREE_POSITION_ATTEMPTS; i++) {
+    const position = room.FindFreePickupSpawnPosition(
+      startingPosition,
+      i,
+      avoidActiveEntities,
+    );
+
+    const closePlayer = getPlayerCloserThan(position, DISTANCE_OF_GRID_TILE);
+    if (closePlayer !== undefined) {
+      continue;
+    }
+
+    const isCloseHeavenDoor = anyEntityCloserThan(
+      heavenDoors,
+      position,
+      DISTANCE_OF_GRID_TILE,
+    );
+    if (isCloseHeavenDoor) {
+      continue;
+    }
+
+    return position;
+  }
+
+  // We failed to find a free position in N iterations.
+  return room.FindFreePickupSpawnPosition(startingPosition);
+}
+
+/**
+ * Helper function to get a map containing the positions of every entity in the current room.
+ *
+ * This is useful for rewinding entity positions at a later time. Also see `setEntityPositions`.
+ *
+ * @param entities Optional. If provided, will only get the positions of the provided entities. Use
+ *                 this with cached entities to avoid invoking the `Isaac.GetRoomEntities` method
+ *                 multiple times.
+ */
+export function getEntityPositions(entities?: Entity[]): Map<PtrHash, Vector> {
+  if (entities === undefined) {
+    entities = getEntities();
+  }
+
+  const entityPositions = new Map<PtrHash, Vector>();
+  for (const entity of entities) {
+    const ptrHash = GetPtrHash(entity);
+    entityPositions.set(ptrHash, entity.Position);
+  }
+
+  return entityPositions;
+}
+
+/**
+ * Helper function to get a map containing the velocities of every entity in the current room.
+ *
+ * This is useful for rewinding entity velocities at a later time. Also see `setEntityVelocities`.
+ *
+ * @param entities Optional. If provided, will only get the velocities of the provided entities. Use
+ *                 this with cached entities to avoid invoking the `Isaac.GetRoomEntities` method
+ *                 multiple times.
+ */
+export function getEntityVelocities(entities?: Entity[]): Map<PtrHash, Vector> {
+  if (entities === undefined) {
+    entities = getEntities();
+  }
+
+  const entityVelocities = new Map<PtrHash, Vector>();
+  for (const entity of entities) {
+    const ptrHash = GetPtrHash(entity);
+    entityVelocities.set(ptrHash, entity.Velocity);
+  }
+
+  return entityVelocities;
+}
+
+/**
+ * Helper function to set the position of every entity in the room based on a map of positions. If
+ * an entity is found that does not have matching element in the provided map, then that entity will
+ * be skipped.
+ *
+ * This function is useful for rewinding entity positions at a later time. Also see
+ * `getEntityPositions`.
+ *
+ * @param entityPositions The map providing the positions for every entity.
+ * @param entities Optional. If provided, will only set the positions of the provided entities. Use
+ *                 this with cached entities to avoid invoking the `Isaac.GetRoomEntities` method
+ *                 multiple times.
+ */
+export function setEntityPositions(
+  entityPositions: Map<PtrHash, Vector>,
+  entities?: Entity[],
+): void {
+  if (entities === undefined) {
+    entities = getEntities();
+  }
+
+  for (const entity of entities) {
+    const ptrHash = GetPtrHash(entity);
+    const entityPosition = entityPositions.get(ptrHash);
+    if (entityPosition !== undefined) {
+      entity.Position = entityPosition;
+    }
+  }
+}
+
+/**
+ * Helper function to set the velocity of every entity in the room based on a map of velocities. If
+ * an entity is found that does not have matching element in the provided map, then that entity will
+ * be skipped.
+ *
+ * This function is useful for rewinding entity velocities at a later time. Also see
+ * `getEntityVelocities`.
+ *
+ * @param entityVelocities The map providing the velocities for every entity.
+ * @param entities Optional. If provided, will only set the velocities of the provided entities. Use
+ *                 this with cached entities to avoid invoking the `Isaac.GetRoomEntities` method
+ *                 multiple times.
+ */
+export function setEntityVelocities(
+  entityVelocities: Map<PtrHash, Vector>,
+  entities?: Entity[],
+): void {
+  if (entities === undefined) {
+    entities = getEntities();
+  }
+
+  for (const entity of entities) {
+    const ptrHash = GetPtrHash(entity);
+    const entityVelocity = entityVelocities.get(ptrHash);
+    if (entityVelocity !== undefined) {
+      entity.Velocity = entityVelocity;
+    }
+  }
+}

package/src/functions/random.ts

@@ -0,0 +1,89 @@
+import { getRandomSeed, isRNG, newRNG } from "./rng";
+
+/**
+ * This 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()`.
+ */
+export function getRandom(seedOrRNG: Seed | RNG = getRandomSeed()): float {
+  const rng = isRNG(seedOrRNG) ? seedOrRNG : newRNG(seedOrRNG);
+  return rng.RandomFloat();
+}
+
+/**
+ * This returns a random float between min and max.
+ *
+ * For example:
+ *
+ * ```ts
+ * const realNumberBetweenOneAndThree = getRandomFloat(1, 3);
+ * ```
+ *
+ * @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()`.
+ */
+export function getRandomFloat(
+  min: int,
+  max: int,
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+): float {
+  if (min > max) {
+    const oldMin = min;
+    const oldMax = max;
+    min = oldMax;
+    max = oldMin;
+  }
+
+  // From: https://stackoverflow.com/questions/40431966
+  return min + getRandom(seedOrRNG) * (max - min);
+}
+
+/**
+ * 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
+ * random number.
+ *
+ * For example:
+ *
+ * ```ts
+ * const oneTwoOrThree = getRandomInt(1, 3);
+ * ```
+ *
+ * @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 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
+ *                   array.
+ */
+export function getRandomInt(
+  min: int,
+  max: int,
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+  exceptions: int[] | readonly int[] = [],
+): int {
+  const rng = isRNG(seedOrRNG) ? seedOrRNG : newRNG(seedOrRNG);
+
+  if (min > max) {
+    const oldMin = min;
+    const oldMax = max;
+    min = oldMax;
+    max = oldMin;
+  }
+
+  const exceptionsSet = new Set(exceptions);
+
+  let randomInt: int;
+  do {
+    randomInt = rng.RandomInt(max - min + 1) + min;
+  } while (exceptionsSet.has(randomInt));
+
+  return randomInt;
+}