isaacscript-common 2.3.0 → 3.0.0

package/src/functions/playerDataStructures.ts

@@ -1,150 +0,0 @@
-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

@@ -1,318 +0,0 @@
-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

@@ -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;
-}