isaacscript-common 4.0.3 → 4.0.4

package/functions/playerIndex.ts

@@ -1,195 +0,0 @@
-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.
- */
-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/functions/pocketItems.ts

@@ -1,149 +0,0 @@
-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/functions/positionVelocity.ts

@@ -1,188 +0,0 @@
-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/functions/random.ts

@@ -1,77 +0,0 @@
-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()`.
- */
-export function getRandomInt(
-  min: int,
-  max: int,
-  seedOrRNG: Seed | RNG = getRandomSeed(),
-): int {
-  const rng = isRNG(seedOrRNG) ? seedOrRNG : newRNG(seedOrRNG);
-
-  if (min > max) {
-    const oldMin = min;
-    const oldMax = max;
-    min = oldMax;
-    max = oldMin;
-  }
-
-  return rng.RandomInt(max - min + 1) + min;
-}