isaacscript-common 2.2.0 → 2.3.0

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,77 @@
+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;
+}

package/src/functions/revive.ts

@@ -0,0 +1,201 @@
+import {
+  CollectibleType,
+  EntityType,
+  NullItemID,
+  PlayerType,
+  TrinketType,
+} from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import {
+  MAX_TAINTED_SAMSON_BERSERK_CHARGE,
+  TAINTED_SAMSON_BERSERK_CHARGE_FROM_TAKING_DAMAGE,
+} from "../constants";
+import { getCharacterDeathAnimationName } from "./character";
+import {
+  getPlayerMaxHeartContainers,
+  getPlayerNumHitsRemaining,
+  hasLostCurse,
+  isKeeper,
+} from "./player";
+import { getLastFrameOfAnimation } from "./sprite";
+import { giveTrinketsBack, temporarilyRemoveTrinket } from "./trinketGive";
+
+/**
+ * Uses the player's current health and other miscellaneous things to determine if incoming damage
+ * will be fatal.
+ */
+export function isDamageToPlayerFatal(
+  player: EntityPlayer,
+  damageAmount: int,
+  damageSource: EntityRef,
+  lastDamageGameFrame: int | undefined,
+): boolean {
+  const gameFrameCount = game.GetFrameCount();
+  const character = player.GetPlayerType();
+  const effects = player.GetEffects();
+  const isBerserk = effects.HasCollectibleEffect(CollectibleType.BERSERK);
+
+  // If we are Tainted Jacob and the damage source is Dark Esau, this will not be fatal damage
+  // (because we will transform into Tainted Jacob's lost form).
+  if (
+    character === PlayerType.JACOB_B &&
+    damageSource.Type === EntityType.DARK_ESAU
+  ) {
+    return false;
+  }
+
+  // If we are berserk, no damage is fatal. (The death is deferred until the end of the berserk
+  // effect.)
+  if (isBerserk) {
+    return false;
+  }
+
+  // If we are playing Tainted Samson and the incoming hit will cause us to become Berserk, then
+  // this will not be fatal damage.
+  const berserkChargeAfterHit =
+    player.SamsonBerserkCharge +
+    TAINTED_SAMSON_BERSERK_CHARGE_FROM_TAKING_DAMAGE;
+  if (
+    character === PlayerType.SAMSON_B &&
+    berserkChargeAfterHit >= MAX_TAINTED_SAMSON_BERSERK_CHARGE
+  ) {
+    return false;
+  }
+
+  // If Spirit Shackles is activated, no damage is fatal.
+  if (willReviveFromSpiritShackles(player)) {
+    return false;
+  }
+
+  // If we are Tainted Jacob in the Lost Form, we may have plenty of health left, but we will still
+  // die in one hit to anything.
+  if (character === PlayerType.JACOB_2_B) {
+    return true;
+  }
+
+  // If we are in the "Lost Curse" form from touching a white fire, all damage will be fatal.
+  if (hasLostCurse(player)) {
+    return true;
+  }
+
+  const playerNumAllHearts = getPlayerNumHitsRemaining(player);
+  if (damageAmount < playerNumAllHearts) {
+    return false;
+  }
+
+  // This will not be fatal damage if the player has Heartbreak and two slots open for broken
+  // hearts.
+  if (willReviveFromHeartbreak(player)) {
+    return false;
+  }
+
+  // This will not be fatal damage if we have Glass Cannon and this is the second time we are taking
+  // damage on the same frame.
+  if (
+    player.HasCollectible(CollectibleType.BROKEN_GLASS_CANNON) &&
+    gameFrameCount === lastDamageGameFrame
+  ) {
+    return false;
+  }
+
+  // This will not be fatal damage if we have two different kinds of hearts. For example, a bomb
+  // explosion deals 2 damage, but if the player has one half soul heart and one half red heart, the
+  // game will only remove the soul heart.
+  const hearts = player.GetHearts();
+  const eternalHearts = player.GetEternalHearts();
+  const soulHearts = player.GetSoulHearts();
+  const boneHearts = player.GetBoneHearts();
+  if (
+    (hearts > 0 && soulHearts > 0) ||
+    (hearts > 0 && boneHearts > 0) ||
+    (soulHearts > 0 && boneHearts > 0) ||
+    (soulHearts > 0 && eternalHearts > 0) ||
+    boneHearts >= 2 // Two bone hearts and nothing else should not result in a death
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Assuming that we are on the frame of fatal damage, this function returns whether or not
+ * Mysterious Paper would rotate to Missing Poster on the frame that the "Game Over" screen would
+ * appear (which would subsequently save the player from fatal damage).
+ *
+ * Mysterious Paper rotates between the 4 items on every frame, in order. The formula for whether
+ * Mysterious Paper be Missing Power is: `gameFrameCount % 4 === 3`
+ */
+export function willMysteriousPaperRevive(player: EntityPlayer): boolean {
+  const gameFrameCount = game.GetFrameCount();
+  const sprite = player.GetSprite();
+
+  // We want to explicitly check the length of the death animation because we might be playing on a
+  // modded character that has a custom death animation.
+  const character = player.GetPlayerType();
+  const animation = getCharacterDeathAnimationName(character);
+  const deathAnimationFrames = getLastFrameOfAnimation(sprite, animation);
+  const frameOfDeath = gameFrameCount + deathAnimationFrames + 1;
+  // (We add 1 because it takes one frame for the death animation to begin.)
+
+  return frameOfDeath % 4 === 3;
+}
+
+/**
+ * The `EntityPlayer.WillPlayerRevive` method does not properly account for Mysterious Paper, so use
+ * this helper function instead for more robust revival detection.
+ */
+export function willPlayerRevive(player: EntityPlayer): boolean {
+  const trinketSituation = temporarilyRemoveTrinket(
+    player,
+    TrinketType.MYSTERIOUS_PAPER,
+  );
+
+  const willRevive =
+    player.WillPlayerRevive() ||
+    (trinketSituation !== undefined && willMysteriousPaperRevive(player));
+
+  giveTrinketsBack(player, trinketSituation);
+
+  return willRevive;
+}
+
+/**
+ * Helper function to determine if the player will be revived by the Heartbreak collectible if they
+ * take fatal damage. This is contingent on the character that they are playing as and the amount of
+ * broken hearts that they already have.
+ */
+export function willReviveFromHeartbreak(player: EntityPlayer): boolean {
+  if (!player.HasCollectible(CollectibleType.HEARTBREAK)) {
+    return false;
+  }
+
+  const maxHeartContainers = getPlayerMaxHeartContainers(player);
+  const numBrokenHeartsThatWillBeAdded = isKeeper(player) ? 1 : 2;
+  const brokenHearts = player.GetBrokenHearts();
+  const numBrokenHeartsAfterRevival =
+    numBrokenHeartsThatWillBeAdded + brokenHearts;
+
+  return maxHeartContainers > numBrokenHeartsAfterRevival;
+}
+
+/**
+ * Helper function to determine if the Spirit Shackles item is in an enabled state. (It can be
+ * either enabled or disabled.)
+ */
+export function willReviveFromSpiritShackles(player: EntityPlayer): boolean {
+  if (!player.HasCollectible(CollectibleType.SPIRIT_SHACKLES)) {
+    return false;
+  }
+
+  const effects = player.GetEffects();
+
+  const spiritShacklesEnabled = !effects.HasNullEffect(
+    NullItemID.SPIRIT_SHACKLES_DISABLED,
+  );
+  const playerInSoulForm = effects.HasNullEffect(
+    NullItemID.SPIRIT_SHACKLES_SOUL,
+  );
+
+  return spiritShacklesEnabled && !playerInSoulForm;
+}