isaacscript-common 2.2.0 → 2.3.0

package/src/functions/playerDataStructures.ts

@@ -0,0 +1,150 @@
+import { DefaultMap } from "../classes/DefaultMap";
+import { PlayerIndex } from "../types/PlayerIndex";
+import { getPlayerIndex } from "./playerIndex";
+
+/**
+ * Helper function to make using default maps with an index of `PlayerIndex` easier. Use this
+ * instead of the `DefaultMap.getAndSetDefault` method if you have a default map of this type.
+ *
+ * For example:
+ *
+ * ```ts
+ * const v = {
+ *   run: {
+ *     playersSpeedBoost: new DefaultMap<PlayerIndex, int>(0),
+ *   },
+ * };
+ *
+ * function evaluateCacheSpeed(player: EntityPlayer) {
+ *   player.MoveSpeed = defaultMapGetPlayer(v.run.playersSpeedBoost, player);
+ * }
+ * ```
+ */
+export function defaultMapGetPlayer<V, A extends unknown[]>(
+  map: DefaultMap<PlayerIndex, V, A>,
+  player: EntityPlayer,
+  ...extraArgs: A
+): V {
+  const playerIndex = getPlayerIndex(player);
+  return map.getAndSetDefault(playerIndex, ...extraArgs);
+}
+
+/**
+ * Helper function to make using maps with an index of `PlayerIndex` easier. Use this instead of the
+ * `Map.set` method if you have a map of this type.
+ *
+ * Since `Map` and `DefaultMap` set values in the same way, this function is simply an alias for the
+ * `mapSetPlayer` helper function.
+ */
+export function defaultMapSetPlayer<V>(
+  map: Map<PlayerIndex, V>,
+  player: EntityPlayer,
+  value: V,
+): void {
+  mapSetPlayer(map, player, value);
+}
+
+/**
+ * Helper function to make using maps with an index of `PlayerIndex` easier. Use this instead of the
+ * `Map.get` method if you have a map of this type.
+ *
+ * For example:
+ *
+ * ```ts
+ * const v = {
+ *   run: {
+ *     playersSpeedBoost: new Map<PlayerIndex, int>(),
+ *   },
+ * };
+ *
+ * function incrementSpeedBoost(player: EntityPlayer) {
+ *   const oldSpeedBoost = mapGetPlayer(v.run.playersSpeedBoost, player);
+ *   const newSpeedBoost = oldSpeedBoost + 0.1;
+ *   mapSetPlayer(v.run.playersSpeedBoost, player);
+ * }
+ * ```
+ */
+export function mapGetPlayer<V>(
+  map: Map<PlayerIndex, V>,
+  player: EntityPlayer,
+): V | undefined {
+  const playerIndex = getPlayerIndex(player);
+  return map.get(playerIndex);
+}
+
+/**
+ * Helper function to make using maps with an index of `PlayerIndex` easier. Use this instead of the
+ * `Map.has` method if you have a map of this type.
+ */
+export function mapHasPlayer<V>(
+  map: Map<PlayerIndex, V>,
+  player: EntityPlayer,
+): boolean {
+  const playerIndex = getPlayerIndex(player);
+  return map.has(playerIndex);
+}
+
+/**
+ * Helper function to make using maps with an index of `PlayerIndex` easier. Use this instead of the
+ * `Map.set` method if you have a map of this type.
+ *
+ * For example:
+ *
+ * ```ts
+ * const v = {
+ *   run: {
+ *     playersSpeedBoost: new Map<PlayerIndex, int>(),
+ *   },
+ * };
+ *
+ * function incrementSpeedBoost(player: EntityPlayer) {
+ *   const oldSpeedBoost = mapGetPlayer(v.run.playersSpeedBoost, player);
+ *   const newSpeedBoost = oldSpeedBoost + 0.1;
+ *   mapSetPlayer(v.run.playersSpeedBoost, player);
+ * }
+ * ```
+ */
+export function mapSetPlayer<V>(
+  map: Map<PlayerIndex, V>,
+  player: EntityPlayer,
+  value: V,
+): void {
+  const playerIndex = getPlayerIndex(player);
+  map.set(playerIndex, value);
+}
+
+/**
+ * Helper function to make using sets with an type of `PlayerIndex` easier. Use this instead of the
+ * `Set.add` method if you have a set of this type.
+ */
+export function setAddPlayer(
+  set: Set<PlayerIndex>,
+  player: EntityPlayer,
+): Set<PlayerIndex> {
+  const playerIndex = getPlayerIndex(player);
+  return set.add(playerIndex);
+}
+
+/**
+ * Helper function to make using sets with an type of `PlayerIndex` easier. Use this instead of the
+ * `Set.delete` method if you have a set of this type.
+ */
+export function setDeletePlayer(
+  set: Set<PlayerIndex>,
+  player: EntityPlayer,
+): boolean {
+  const playerIndex = getPlayerIndex(player);
+  return set.delete(playerIndex);
+}
+
+/**
+ * Helper function to make using sets with an type of `PlayerIndex` easier. Use this instead of the
+ * `Set.has` method if you have a set of this type.
+ */
+export function setHasPlayer(
+  set: Set<PlayerIndex>,
+  player: EntityPlayer,
+): boolean {
+  const playerIndex = getPlayerIndex(player);
+  return set.has(playerIndex);
+}

package/src/functions/playerHealth.ts

@@ -0,0 +1,318 @@
+import { HeartSubType, PlayerType } from "isaac-typescript-definitions";
+import { MAX_PLAYER_HEART_CONTAINERS } from "../constants";
+import { HealthType } from "../enums/HealthType";
+import { PlayerHealth } from "../interfaces/PlayerHealth";
+import {
+  getPlayerBlackHearts,
+  getPlayerHearts,
+  getPlayerSoulHearts,
+  isCharacter,
+} from "./player";
+import { ensureAllCases, repeat } from "./utils";
+
+export function addPlayerHealthType(
+  player: EntityPlayer,
+  healthType: HealthType,
+  numHearts: int,
+): void {
+  switch (healthType) {
+    case HealthType.RED: {
+      player.AddHearts(numHearts);
+      return;
+    }
+
+    case HealthType.SOUL: {
+      player.AddSoulHearts(numHearts);
+      return;
+    }
+
+    case HealthType.ETERNAL: {
+      player.AddEternalHearts(numHearts);
+      return;
+    }
+
+    case HealthType.BLACK: {
+      player.AddBlackHearts(numHearts);
+      return;
+    }
+
+    case HealthType.GOLDEN: {
+      player.AddGoldenHearts(numHearts);
+      return;
+    }
+
+    case HealthType.BONE: {
+      player.AddBoneHearts(numHearts);
+      return;
+    }
+
+    case HealthType.ROTTEN: {
+      player.AddRottenHearts(numHearts);
+      return;
+    }
+
+    case HealthType.BROKEN: {
+      player.AddBrokenHearts(numHearts);
+      return;
+    }
+
+    case HealthType.MAX_HEARTS: {
+      player.AddMaxHearts(numHearts, false);
+      return;
+    }
+
+    default: {
+      ensureAllCases(healthType);
+    }
+  }
+}
+
+/**
+ * Helper function to get an object representing the player's health. You can use this in
+ * combination with the `setPlayerHealth` function to restore the player's health back to a certain
+ * configuration at a later time.
+ *
+ * This is based on the `REVEL.StoreHealth` function in the Revelations mod.
+ */
+export function getPlayerHealth(player: EntityPlayer): PlayerHealth {
+  const character = player.GetPlayerType();
+  const soulHeartTypes: HeartSubType[] = [];
+  let maxHearts = player.GetMaxHearts();
+  let hearts = getPlayerHearts(player); // We use the helper function to remove rotten hearts
+  let soulHearts = player.GetSoulHearts();
+  let boneHearts = player.GetBoneHearts();
+  const goldenHearts = player.GetGoldenHearts();
+  const eternalHearts = player.GetEternalHearts();
+  const rottenHearts = player.GetRottenHearts();
+  const brokenHearts = player.GetBrokenHearts();
+  const subPlayer = player.GetSubPlayer();
+  const soulCharges = player.GetEffectiveSoulCharge();
+  const bloodCharges = player.GetEffectiveBloodCharge();
+
+  // The Forgotten and The Soul has special health, so we need to account for this.
+  if (character === PlayerType.THE_FORGOTTEN && subPlayer !== undefined) {
+    // The Forgotten does not have red heart containers.
+    maxHearts = boneHearts * 2;
+    boneHearts = 0;
+
+    // The Forgotten will always have 0 soul hearts; we need to get the soul heart amount from the
+    // sub player.
+    soulHearts = subPlayer.GetSoulHearts();
+  } else if (character === PlayerType.THE_SOUL && subPlayer !== undefined) {
+    // The Soul will always have 0 bone hearts; we need to get the bone heart amount from the sub
+    // player. We need to store it as "maxHearts" instead of "boneHearts".
+    maxHearts = subPlayer.GetBoneHearts() * 2;
+    hearts = subPlayer.GetHearts();
+  }
+
+  // This is the number of individual hearts shown in the HUD, minus heart containers.
+  const extraHearts = math.ceil(soulHearts / 2) + boneHearts;
+
+  // Since bone hearts can be inserted anywhere between soul hearts, we need a separate counter to
+  // track which soul heart we're currently at.
+  let currentSoulHeart = 0;
+
+  for (let i = 0; i < extraHearts; i++) {
+    let isBoneHeart = player.IsBoneHeart(i);
+    if (character === PlayerType.THE_FORGOTTEN && subPlayer !== undefined) {
+      isBoneHeart = subPlayer.IsBoneHeart(i);
+    }
+    if (isBoneHeart) {
+      soulHeartTypes.push(HeartSubType.BONE);
+    } else {
+      // We need to add 1 here because only the second half of a black heart is considered black.
+      let isBlackHeart = player.IsBlackHeart(currentSoulHeart + 1);
+      if (character === PlayerType.THE_FORGOTTEN && subPlayer !== undefined) {
+        isBlackHeart = subPlayer.IsBlackHeart(currentSoulHeart + 1);
+      }
+      if (isBlackHeart) {
+        soulHeartTypes.push(HeartSubType.BLACK);
+      } else {
+        soulHeartTypes.push(HeartSubType.SOUL);
+      }
+
+      // Move to the next heart.
+      currentSoulHeart += 2;
+    }
+  }
+
+  return {
+    maxHearts,
+    hearts,
+    eternalHearts,
+    soulHearts,
+    boneHearts,
+    goldenHearts,
+    rottenHearts,
+    brokenHearts,
+    soulCharges,
+    bloodCharges,
+    soulHeartTypes,
+  };
+}
+
+export function getPlayerHealthType(
+  player: EntityPlayer,
+  healthType: HealthType,
+): int {
+  switch (healthType) {
+    // 5.10.1
+    case HealthType.RED: {
+      // We use the standard library helper function since the `EntityPlayer.GetHearts` method
+      // returns a value that includes rotten hearts.
+      return getPlayerHearts(player);
+    }
+
+    // 5.10.3
+    case HealthType.SOUL: {
+      // We use the standard library helper function since the `EntityPlayer.GetSoulHearts` method
+      // returns a value that includes black hearts.
+      return getPlayerSoulHearts(player);
+    }
+
+    // 5.10.4
+    case HealthType.ETERNAL: {
+      return player.GetEternalHearts();
+    }
+
+    // 5.10.6
+    case HealthType.BLACK: {
+      // We use the standard library helper function since the `EntityPlayer.GetBlackHearts` method
+      // returns a bit mask.
+      return getPlayerBlackHearts(player);
+    }
+
+    // 5.10.7
+    case HealthType.GOLDEN: {
+      return player.GetGoldenHearts();
+    }
+
+    // 5.10.11
+    case HealthType.BONE: {
+      return player.GetBoneHearts();
+    }
+
+    // 5.10.12
+    case HealthType.ROTTEN: {
+      return player.GetRottenHearts();
+    }
+
+    case HealthType.BROKEN: {
+      return player.GetBrokenHearts();
+    }
+
+    case HealthType.MAX_HEARTS: {
+      return player.GetMaxHearts();
+    }
+
+    default: {
+      return ensureAllCases(healthType);
+    }
+  }
+}
+
+export function removeAllPlayerHealth(player: EntityPlayer): void {
+  const goldenHearts = player.GetGoldenHearts();
+  const eternalHearts = player.GetEternalHearts();
+  const boneHearts = player.GetBoneHearts();
+  const brokenHearts = player.GetBrokenHearts();
+
+  // To avoid bugs, we have to remove the exact amount of certain types of hearts. We remove Golden
+  // Hearts first so that they don't break.
+  player.AddGoldenHearts(goldenHearts * -1);
+  player.AddEternalHearts(eternalHearts * -1);
+  player.AddBoneHearts(boneHearts * -1);
+  player.AddBrokenHearts(brokenHearts * -1);
+  player.AddMaxHearts(MAX_PLAYER_HEART_CONTAINERS * -2, true);
+  player.AddSoulHearts(MAX_PLAYER_HEART_CONTAINERS * -2);
+
+  // If we are The Soul, the `EntityPlayer.AddBoneHearts` method will not remove Forgotten's bone
+  // hearts, so we need to explicitly handle this.
+  if (isCharacter(player, PlayerType.THE_SOUL)) {
+    const forgotten = player.GetSubPlayer();
+    if (forgotten !== undefined) {
+      const forgottenBoneHearts = forgotten.GetBoneHearts();
+      forgotten.AddBoneHearts(forgottenBoneHearts * -1);
+    }
+  }
+}
+
+/**
+ * Helper function to set a player's health to a specific state. You can use this in combination
+ * with the `getPlayerHealth` function to restore the player's health back to a certain
+ * configuration at a later time.
+ *
+ * Based on the `REVEL.LoadHealth` function in the Revelations mod.
+ */
+export function setPlayerHealth(
+  player: EntityPlayer,
+  playerHealth: PlayerHealth,
+): void {
+  const character = player.GetPlayerType();
+  const subPlayer = player.GetSubPlayer();
+
+  removeAllPlayerHealth(player);
+
+  // Add the red heart containers.
+  if (character === PlayerType.THE_SOUL && subPlayer !== undefined) {
+    // Adding health to The Soul is a special case.
+    subPlayer.AddMaxHearts(playerHealth.maxHearts, false);
+  } else {
+    player.AddMaxHearts(playerHealth.maxHearts, false);
+  }
+
+  // Add the eternal hearts.
+  player.AddEternalHearts(playerHealth.eternalHearts);
+
+  // Add the soul / black / bone hearts.
+  let soulHeartsRemaining = playerHealth.soulHearts;
+  playerHealth.soulHeartTypes.forEach((heartType, i) => {
+    const isHalf =
+      playerHealth.soulHearts + playerHealth.boneHearts * 2 < (i + 1) * 2;
+    let addAmount = 2;
+    if (isHalf || heartType === HeartSubType.BONE || soulHeartsRemaining < 2) {
+      // Fix the bug where a half soul heart to the left of a bone heart will be treated as a full
+      // soul heart.
+      addAmount = 1;
+    }
+
+    if (heartType === HeartSubType.SOUL) {
+      player.AddSoulHearts(addAmount);
+      soulHeartsRemaining -= addAmount;
+    } else if (heartType === HeartSubType.BLACK) {
+      player.AddBlackHearts(addAmount);
+      soulHeartsRemaining -= addAmount;
+    } else if (heartType === HeartSubType.BONE) {
+      player.AddBoneHearts(addAmount);
+    }
+  });
+
+  /**
+   * Fill in the red heart containers.
+   *
+   * (Rotten Hearts must be filled in first in order for this to work properly, since they conflict
+   * with half red hearts.)
+   *
+   * The `EntityPlayer.AddRottenHearts` method is not like actually picking up a rotten heart, since
+   * it will only grant one rotten heart to Tainted Magdalene (whereas picking up a rotten heart
+   * would grant two).
+   */
+  player.AddRottenHearts(playerHealth.rottenHearts);
+  repeat(playerHealth.hearts, () => {
+    player.AddHearts(1);
+
+    // Adding 1 heart to Tainted Magdalene will actually add two hearts.
+    if (character === PlayerType.MAGDALENE_B) {
+      player.AddHearts(-1);
+    }
+  });
+  player.AddGoldenHearts(playerHealth.goldenHearts);
+  player.AddBrokenHearts(playerHealth.brokenHearts);
+
+  // Set the Bethany / Tainted Bethany charges.
+  if (character === PlayerType.BETHANY) {
+    player.SetSoulCharge(playerHealth.soulCharges);
+  } else if (character === PlayerType.BETHANY_B) {
+    player.SetBloodCharge(playerHealth.bloodCharges);
+  }
+}

package/src/functions/playerIndex.ts

@@ -0,0 +1,195 @@
+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;
+}