isaacscript-common 8.4.6 → 8.5.0

package/src/functions/input.ts

@@ -6,7 +6,6 @@ import {
 } from "isaac-typescript-definitions";
 import { KEYBOARD_TO_STRING } from "../maps/keyboardToString";
 import { getEnumValues } from "./enums";
-import { copySet } from "./set";
 import { trimPrefix } from "./string";
 
 const MODIFIER_KEYS: readonly Keyboard[] = [
@@ -52,12 +51,12 @@ export function controllerToString(controller: Controller): string | undefined {
   return trimPrefix(key, "BUTTON_");
 }
 
-export function getMoveActions(): Set<ButtonAction> {
-  return copySet(MOVEMENT_ACTIONS_SET);
+export function getMoveActions(): ReadonlySet<ButtonAction> {
+  return MOVEMENT_ACTIONS_SET;
 }
 
-export function getShootActions(): Set<ButtonAction> {
-  return copySet(SHOOTING_ACTIONS_SET);
+export function getShootActions(): ReadonlySet<ButtonAction> {
+  return SHOOTING_ACTIONS_SET;
 }
 
 /** Iterates over all inputs to determine if a particular button is pressed (i.e. held down). */

package/src/functions/playerHealth.ts

@@ -3,19 +3,16 @@ import {
   CollectibleType,
   HeartSubType,
   PlayerType,
+  TrinketType,
 } from "isaac-typescript-definitions";
 import { MAX_PLAYER_HEART_CONTAINERS } from "../core/constants";
 import { HealthType } from "../enums/HealthType";
 import { PlayerHealth, SoulHeartType } from "../interfaces/PlayerHealth";
+import { countSetBits, getKBitOfN, getNumBitsOfN } from "./bitwise";
+import { getCharacterMaxHeartContainers } from "./characters";
 import { getTotalCharge } from "./charge";
 import { getEnumValues } from "./enums";
-import {
-  getPlayerBlackHearts,
-  getPlayerHearts,
-  getPlayerSoulHearts,
-  isCharacter,
-  setActiveItem,
-} from "./players";
+import { isCharacter, isKeeper, setActiveItem } from "./players";
 import { repeat } from "./utils";
 
 export function addPlayerHealthType(
@@ -71,6 +68,78 @@ export function addPlayerHealthType(
   }
 }
 
+/**
+ * Returns whether or not all of the player's soul-heart-type hearts are black hearts.
+ *
+ * Note that this function does not consider red heart containers.
+ *
+ * For example:
+ *
+ * - If the player has one black heart, this function would return true.
+ * - If the player has one soul heart and two black hearts, this function would return false.
+ * - If the player has no black hearts, this function will return false.
+ * - If the player has one red heart container and three black hearts, this function would return
+ *   true.
+ */
+export function doesPlayerHaveAllBlackHearts(player: EntityPlayer): boolean {
+  const soulHearts = getPlayerSoulHearts(player);
+  const blackHearts = getPlayerBlackHearts(player);
+
+  return blackHearts > 0 && soulHearts === 0;
+}
+
+/**
+ * Returns whether or not all of the player's soul-heart-type hearts are soul hearts.
+ *
+ * Note that this function does not consider red heart containers.
+ *
+ * For example:
+ *
+ * - If the player has two soul hearts and one black heart, this function would return false.
+ * - If the player has no soul hearts, this function will return false.
+ * - If the player has one red heart container and three soul hearts, this function would return
+ *   true.
+ */
+export function doesPlayerHaveAllSoulHearts(player: EntityPlayer): boolean {
+  const soulHearts = getPlayerSoulHearts(player);
+  const blackHearts = getPlayerBlackHearts(player);
+
+  return soulHearts > 0 && blackHearts === 0;
+}
+
+/**
+ * Returns the number of slots that the player has remaining for new heart containers, accounting
+ * for broken hearts. For example, if the player is Judas and has 1 red heart containers and 2 full
+ * soul hearts and 3 broken hearts, then this function would return 6 (i.e. 12 - 1 - 2 - 3).
+ */
+export function getPlayerAvailableHeartSlots(player: EntityPlayer): int {
+  const maxHeartContainers = getPlayerMaxHeartContainers(player);
+  const effectiveMaxHearts = player.GetEffectiveMaxHearts();
+  const normalAndBoneHeartContainers = effectiveMaxHearts / 2;
+  const soulHearts = player.GetSoulHearts();
+  const soulHeartContainers = math.ceil(soulHearts / 2);
+  const totalHeartContainers =
+    normalAndBoneHeartContainers + soulHeartContainers;
+  const brokenHearts = player.GetBrokenHearts();
+  const totalOccupiedHeartSlots = totalHeartContainers + brokenHearts;
+
+  return maxHeartContainers - totalOccupiedHeartSlots;
+}
+
+/**
+ * Returns the number of black hearts that the player has, excluding any soul hearts. For example,
+ * if the player has one full black heart, one full soul heart, and one half black heart, this
+ * function returns 3.
+ *
+ * This is different from the `EntityPlayer.GetBlackHearts` method, since that returns a bitmask.
+ */
+export function getPlayerBlackHearts(player: EntityPlayer): int {
+  const blackHeartsBitmask = player.GetBlackHearts();
+  const blackHeartBits = countSetBits(blackHeartsBitmask);
+
+  return blackHeartBits * 2;
+}
+
 /**
  * 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
@@ -211,6 +280,159 @@ export function getPlayerHealthType(
   }
 }
 
+/**
+ * Returns the number of red hearts that the player has, excluding any rotten hearts. For example,
+ * if the player has one full black heart, one full soul heart, and one half black heart, this
+ * function returns 3.
+ *
+ * This is different from the `EntityPlayer.GetHearts` method, since that returns a value that
+ * includes rotten hearts.
+ */
+export function getPlayerHearts(player: EntityPlayer): int {
+  const rottenHearts = player.GetRottenHearts();
+  const hearts = player.GetHearts();
+
+  return hearts - rottenHearts * 2;
+}
+
+/**
+ * Helper function that returns the type of the rightmost heart. This does not including golden
+ * hearts or broken hearts, since they cannot be damaged directly.
+ */
+export function getPlayerLastHeart(player: EntityPlayer): HealthType {
+  const hearts = player.GetHearts();
+  const effectiveMaxHearts = player.GetEffectiveMaxHearts();
+  const soulHearts = player.GetSoulHearts();
+  const blackHearts = player.GetBlackHearts();
+  const eternalHearts = player.GetEternalHearts();
+  const boneHearts = player.GetBoneHearts();
+  const rottenHearts = player.GetRottenHearts();
+
+  const soulHeartSlots = soulHearts / 2;
+  const lastHeartIndex = boneHearts + soulHeartSlots - 1;
+  const isLastHeartBone = player.IsBoneHeart(lastHeartIndex);
+
+  if (isLastHeartBone) {
+    const isLastContainerEmpty = hearts <= effectiveMaxHearts - 2;
+    if (isLastContainerEmpty) {
+      return HealthType.BONE;
+    }
+
+    if (rottenHearts > 0) {
+      return HealthType.ROTTEN;
+    }
+
+    if (eternalHearts > 0) {
+      return HealthType.ETERNAL;
+    }
+
+    return HealthType.RED;
+  }
+
+  if (soulHearts > 0) {
+    const numBits = getNumBitsOfN(blackHearts);
+    const finalBit = getKBitOfN(numBits - 1, blackHearts);
+    const isBlack = finalBit === 1;
+
+    if (isBlack) {
+      return HealthType.BLACK;
+    }
+
+    // If it is not a black heart, it must be a soul heart.
+    return HealthType.SOUL;
+  }
+
+  if (eternalHearts > 0) {
+    return HealthType.ETERNAL;
+  }
+
+  if (rottenHearts > 0) {
+    return HealthType.ROTTEN;
+  }
+
+  return HealthType.RED;
+}
+
+/**
+ * Returns the maximum heart containers that the provided player can have. Normally, this is 12, but
+ * it can change depending on the character (e.g. Keeper) and other things (e.g. Mother's Kiss).
+ * This function does not account for Broken Hearts; use the `getPlayerAvailableHeartSlots` helper
+ * function for that.
+ */
+export function getPlayerMaxHeartContainers(player: EntityPlayer): int {
+  const character = player.GetPlayerType();
+  const characterMaxHeartContainers = getCharacterMaxHeartContainers(character);
+
+  // 1
+  // Magdalene can increase her maximum heart containers with Birthright.
+  if (
+    character === PlayerType.MAGDALENE &&
+    player.HasCollectible(CollectibleType.BIRTHRIGHT)
+  ) {
+    const extraMaxHeartContainersFromBirthright = 6;
+    return characterMaxHeartContainers + extraMaxHeartContainersFromBirthright;
+  }
+
+  // 14, 33
+  // Keeper and Tainted Keeper can increase their coin containers with Mother's Kiss and Greed's
+  // Gullet.
+  if (isKeeper(player)) {
+    const numMothersKisses = player.GetTrinketMultiplier(
+      TrinketType.MOTHERS_KISS,
+    );
+    const hasGreedsGullet = player.HasCollectible(
+      CollectibleType.GREEDS_GULLET,
+    );
+    const coins = player.GetNumCoins();
+    const greedsGulletCoinContainers = hasGreedsGullet
+      ? Math.floor(coins / 25)
+      : 0;
+
+    return (
+      characterMaxHeartContainers +
+      numMothersKisses +
+      greedsGulletCoinContainers
+    );
+  }
+
+  return characterMaxHeartContainers;
+}
+
+/**
+ * Returns the number of soul hearts that the player has, excluding any black hearts. For example,
+ * if the player has one full black heart, one full soul heart, and one half black heart, this
+ * function returns 2.
+ *
+ * This is different from the `EntityPlayer.GetSoulHearts` method, since that returns the combined
+ * number of soul hearts and black hearts.
+ */
+export function getPlayerSoulHearts(player: EntityPlayer): int {
+  const soulHearts = player.GetSoulHearts();
+  const blackHearts = getPlayerBlackHearts(player);
+
+  return soulHearts - blackHearts;
+}
+
+/**
+ * Helper function to determine how many heart containers that Tainted Magdalene has that will not
+ * be automatically depleted over time. By default, this is 2, but this function will return 4 so
+ * that it is consistent with the `player.GetHearts` and `player.GetMaxHearts` methods.
+ *
+ * If Tainted Magdalene has Birthright, she will gained an additional non-temporary heart container.
+ *
+ * This function does not validate whether or not the provided player is Tainted Magdalene; that
+ * should be accomplished before invoking this function.
+ */
+export function getTaintedMagdaleneNonTemporaryMaxHearts(
+  player: EntityPlayer,
+): int {
+  const maxHearts = player.GetMaxHearts();
+  const hasBirthright = player.HasCollectible(CollectibleType.BIRTHRIGHT);
+  const maxNonTemporaryMaxHearts = hasBirthright ? 6 : 4;
+
+  return Math.min(maxHearts, maxNonTemporaryMaxHearts);
+}
+
 /** Returns a `PlayerHealth` object with all zeros. */
 export function newPlayerHealth(): PlayerHealth {
   return {
@@ -421,3 +643,43 @@ export function setPlayerHealth(
     );
   }
 }
+
+/**
+ * Helper function to see if a certain damage amount would deal "permanent" damage to Tainted
+ * Magdalene.
+ *
+ * Tainted Magdalene has "permanent" health and "temporary" health. When standing still and doing
+ * nothing, all of Tainted Magdalene's temporary health will eventually go away.
+ *
+ * Before using this function, it is expected that you check to see if the player is Tainted
+ * Magdalene first, or else it will give a nonsensical result.
+ */
+export function wouldDamageTaintedMagdaleneNonTemporaryHeartContainers(
+  player: EntityPlayer,
+  damageAmount: float,
+): boolean {
+  // Regardless of the damage amount, damage to a player cannot remove a soul heart and a red heart
+  // at the same time.
+  const soulHearts = player.GetSoulHearts();
+  if (soulHearts > 0) {
+    return false;
+  }
+
+  // Regardless of the damage amount, damage to a player cannot remove a bone heart and a red heart
+  // at the same time.
+  const boneHearts = player.GetBoneHearts();
+  if (boneHearts > 0) {
+    return false;
+  }
+
+  // Account for rotten hearts eating away at more red hearts than usual.
+  const hearts = player.GetHearts();
+  const rottenHearts = player.GetRottenHearts();
+  const effectiveDamageAmount =
+    damageAmount + Math.min(rottenHearts, damageAmount);
+
+  const heartsAfterDamage = hearts - effectiveDamageAmount;
+  const nonTemporaryMaxHearts =
+    getTaintedMagdaleneNonTemporaryMaxHearts(player);
+  return heartsAfterDamage < nonTemporaryMaxHearts;
+}