isaacscript-common 44.0.0 → 44.1.0

package/src/functions/playerCollectibles.ts

@@ -0,0 +1,372 @@
+import {
+  ActiveSlot,
+  CollectibleType,
+  PlayerType,
+} from "isaac-typescript-definitions";
+import { ACTIVE_SLOT_VALUES } from "../arrays/cachedEnumValues";
+import { game, itemConfig } from "../core/cachedClasses";
+import { ReadonlySet } from "../types/ReadonlySet";
+import { sumArray } from "./array";
+import { getCollectibleMaxCharges } from "./collectibles";
+import { getAllPlayers, getPlayers } from "./playerIndex";
+import { isCharacter } from "./players";
+
+/**
+ * Helper function to add one or more collectibles to a player.
+ *
+ * This function is variadic, meaning that you can supply as many collectible types as you want to
+ * add.
+ */
+export function addCollectible(
+  player: EntityPlayer,
+  ...collectibleTypes: CollectibleType[]
+): void {
+  for (const collectibleType of collectibleTypes) {
+    player.AddCollectible(collectibleType);
+  }
+}
+
+export function addCollectibleCostume(
+  player: EntityPlayer,
+  collectibleType: CollectibleType,
+): void {
+  const itemConfigItem = itemConfig.GetCollectible(collectibleType);
+  if (itemConfigItem === undefined) {
+    return;
+  }
+
+  player.AddCostume(itemConfigItem, false);
+}
+
+/**
+ * Helper function to check to see if any player has a particular collectible.
+ *
+ * @param collectibleType The collectible type to check for.
+ * @param ignoreModifiers If set to true, only counts collectibles the player actually owns and
+ *                        ignores effects granted by items like Zodiac, 3 Dollar Bill and Lemegeton.
+ *                        Default is false.
+ */
+export function anyPlayerHasCollectible(
+  collectibleType: CollectibleType,
+  ignoreModifiers?: boolean,
+): boolean {
+  const players = getAllPlayers();
+
+  return players.some((player) =>
+    player.HasCollectible(collectibleType, ignoreModifiers),
+  );
+}
+
+/**
+ * Helper function to find the active slots that the player has the corresponding collectible type
+ * in. Returns an empty array if the player does not have the collectible in any active slot.
+ */
+export function getActiveItemSlots(
+  player: EntityPlayer,
+  collectibleType: CollectibleType,
+): ActiveSlot[] {
+  return ACTIVE_SLOT_VALUES.filter((activeSlot) => {
+    const activeItem = player.GetActiveItem(activeSlot);
+    return activeItem === collectibleType;
+  });
+}
+
+/**
+ * Helper function to return the total amount of collectibles that a player has that match the
+ * collectible type(s) provided.
+ *
+ * This function is variadic, meaning that you can specify N collectible types.
+ *
+ * Note that this will filter out non-real collectibles like Lilith's Incubus.
+ */
+export function getPlayerCollectibleCount(
+  player: EntityPlayer,
+  ...collectibleTypes: CollectibleType[]
+): int {
+  let numCollectibles = 0;
+  for (const collectibleType of collectibleTypes) {
+    // We specify "true" as the second argument to filter out things like Lilith's Incubus.
+    numCollectibles += player.GetCollectibleNum(collectibleType, true);
+  }
+
+  return numCollectibles;
+}
+
+/**
+ * Helper function to get only the players that have a certain collectible.
+ *
+ * This function is variadic, meaning that you can supply as many collectible types as you want to
+ * check for. It only returns the players that have all of the collectibles.
+ */
+export function getPlayersWithCollectible(
+  ...collectibleTypes: CollectibleType[]
+): EntityPlayer[] {
+  const players = getPlayers();
+
+  return players.filter((player) =>
+    collectibleTypes.every((collectibleType) =>
+      player.HasCollectible(collectibleType),
+    ),
+  );
+}
+
+/**
+ * Returns the total number of collectibles amongst all players. For example, if player 1 has 1 Sad
+ * Onion and player 2 has 2 Sad Onions, then this function would return 3.
+ *
+ * Note that this will filter out non-real collectibles like Lilith's Incubus.
+ */
+export function getTotalPlayerCollectibles(
+  collectibleType: CollectibleType,
+): int {
+  const players = getPlayers();
+  const numCollectiblesArray = players.map((player) =>
+    // We specify "true" as the second argument to filter out things like Lilith's Incubus.
+    player.GetCollectibleNum(collectibleType, true),
+  );
+
+  return sumArray(numCollectiblesArray);
+}
+
+/**
+ * Helper function to check to see if a player has one or more collectibles.
+ *
+ * This function is variadic, meaning that you can supply as many collectible types as you want to
+ * check for. Returns true if the player has any of the supplied collectible types.
+ *
+ * This function always passes `false` to the `ignoreModifiers` argument.
+ */
+export function hasCollectible(
+  player: EntityPlayer,
+  ...collectibleTypes: CollectibleType[]
+): boolean {
+  return collectibleTypes.some((collectibleType) =>
+    player.HasCollectible(collectibleType),
+  );
+}
+
+/**
+ * Helper function to check to see if a player has a specific collectible in one or more active
+ * slots.
+ *
+ * This function is variadic, meaning that you can specify as many active slots as you want to check
+ * for. This function will return true if the collectible type is located in any of the active slots
+ * provided.
+ */
+export function hasCollectibleInActiveSlot(
+  player: EntityPlayer,
+  collectibleType: CollectibleType,
+  ...activeSlots: ActiveSlot[]
+): boolean {
+  const matchingActiveSlotsSet = new ReadonlySet(activeSlots);
+  const activeItemSlots = getActiveItemSlots(player, collectibleType);
+
+  return activeItemSlots.some((activeSlot) =>
+    matchingActiveSlotsSet.has(activeSlot),
+  );
+}
+
+/**
+ * Returns whether the player can hold an additional active item, beyond what they are currently
+ * carrying. This takes the Schoolbag into account.
+ *
+ * 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 hasOpenActiveItemSlot(player: EntityPlayer): boolean {
+  if (isCharacter(player, PlayerType.SOUL_B)) {
+    return false;
+  }
+
+  const activeItemPrimary = player.GetActiveItem(ActiveSlot.PRIMARY);
+  const activeItemSecondary = player.GetActiveItem(ActiveSlot.SECONDARY);
+  const hasSchoolbag = player.HasCollectible(CollectibleType.SCHOOLBAG);
+
+  if (hasSchoolbag) {
+    return (
+      activeItemPrimary === CollectibleType.NULL ||
+      activeItemSecondary === CollectibleType.NULL
+    );
+  }
+
+  return activeItemPrimary === CollectibleType.NULL;
+}
+
+/**
+ * Helper function to check if the active slot of a particular player is empty.
+ *
+ * @param player The player to check.
+ * @param activeSlot Optional. The active slot to check. Default is `ActiveSlot.PRIMARY`.
+ */
+export function isActiveSlotEmpty(
+  player: EntityPlayer,
+  activeSlot = ActiveSlot.PRIMARY,
+): boolean {
+  const activeCollectibleType = player.GetActiveItem(activeSlot);
+  return activeCollectibleType === CollectibleType.NULL;
+}
+
+/**
+ * Helper function to remove all of the active items from a player. This includes the Schoolbag item
+ * and any pocket actives.
+ */
+export function removeAllActiveItems(player: EntityPlayer): void {
+  for (const activeSlot of ACTIVE_SLOT_VALUES) {
+    const collectibleType = player.GetActiveItem(activeSlot);
+    if (collectibleType === CollectibleType.NULL) {
+      continue;
+    }
+
+    let stillHasCollectible: boolean;
+    do {
+      player.RemoveCollectible(collectibleType);
+      stillHasCollectible = player.HasCollectible(collectibleType);
+    } while (stillHasCollectible);
+  }
+}
+
+/**
+ * Helper function to remove one or more collectibles to a player.
+ *
+ * This function is variadic, meaning that you can supply as many collectible types as you want to
+ * remove.
+ */
+export function removeCollectible(
+  player: EntityPlayer,
+  ...collectibleTypes: CollectibleType[]
+): void {
+  for (const collectibleType of collectibleTypes) {
+    player.RemoveCollectible(collectibleType);
+  }
+}
+
+/**
+ * Helper function to remove a collectible costume from a player. Use this helper function to avoid
+ * having to request the collectible from the item config.
+ */
+export function removeCollectibleCostume(
+  player: EntityPlayer,
+  collectibleType: CollectibleType,
+): void {
+  const itemConfigItem = itemConfig.GetCollectible(collectibleType);
+  if (itemConfigItem === undefined) {
+    return;
+  }
+
+  player.RemoveCostume(itemConfigItem);
+}
+
+/**
+ * Helper function to remove one or more collectibles from all players. If any player has more than
+ * one copy of the item, then all copies of it will be removed.
+ *
+ * This function is variadic, meaning that you can specify as many collectibles as you want to
+ * remove.
+ */
+export function removeCollectibleFromAllPlayers(
+  ...collectibleTypes: CollectibleType[]
+): void {
+  for (const player of getAllPlayers()) {
+    for (const collectibleType of collectibleTypes) {
+      while (player.HasCollectible(collectibleType, true)) {
+        player.RemoveCollectible(collectibleType);
+      }
+    }
+  }
+}
+
+/**
+ * Helper function to set an active collectible to a particular slot. This has different behavior
+ * than calling the `player.AddCollectible` method with the `activeSlot` argument, because this
+ * function will not shift existing items into the Schoolbag and it handles
+ * `ActiveSlot.SLOT_POCKET2`.
+ *
+ * Note that if an item is set to `ActiveSlot.SLOT_POCKET2`, it will disappear after being used and
+ * will be automatically removed upon entering a new room.
+ *
+ * @param player The player to give the item to.
+ * @param collectibleType The collectible type of the item to give.
+ * @param activeSlot Optional. The slot to set. Default is `ActiveSlot.PRIMARY`.
+ * @param charge Optional. The argument of charges to set. If not specified, the item will be set
+ *               with maximum charges.
+ * @param keepInPools Optional. Whether to remove the item from pools. Default is false.
+ */
+export function setActiveItem(
+  player: EntityPlayer,
+  collectibleType: CollectibleType,
+  activeSlot = ActiveSlot.PRIMARY,
+  charge?: int,
+  keepInPools = false,
+): void {
+  const itemPool = game.GetItemPool();
+  const primaryCollectibleType = player.GetActiveItem(ActiveSlot.PRIMARY);
+  const primaryCharge = player.GetActiveCharge(ActiveSlot.PRIMARY);
+  const secondaryCollectibleType = player.GetActiveItem(ActiveSlot.SECONDARY);
+
+  if (charge === undefined) {
+    charge = getCollectibleMaxCharges(collectibleType);
+  }
+
+  if (!keepInPools) {
+    itemPool.RemoveCollectible(collectibleType);
+  }
+
+  switch (activeSlot) {
+    case ActiveSlot.PRIMARY: {
+      // If there is a Schoolbag item, removing the primary item will shift the Schoolbag item to
+      // the primary slot.
+      if (primaryCollectibleType !== CollectibleType.NULL) {
+        player.RemoveCollectible(primaryCollectibleType);
+      }
+
+      // If there was a Schoolbag item, adding a new primary item will shift it back into the
+      // secondary slot.
+      player.AddCollectible(collectibleType, charge, false);
+
+      break;
+    }
+
+    case ActiveSlot.SECONDARY: {
+      if (primaryCollectibleType !== CollectibleType.NULL) {
+        player.RemoveCollectible(primaryCollectibleType);
+      }
+
+      if (secondaryCollectibleType !== CollectibleType.NULL) {
+        player.RemoveCollectible(secondaryCollectibleType);
+      }
+
+      // Add the new item, which will go to the primary slot.
+      player.AddCollectible(secondaryCollectibleType, charge, false);
+
+      // Add back the original primary item, if any.
+      if (primaryCollectibleType !== CollectibleType.NULL) {
+        player.AddCollectible(primaryCollectibleType, primaryCharge, false);
+      }
+
+      break;
+    }
+
+    case ActiveSlot.POCKET: {
+      player.SetPocketActiveItem(collectibleType, activeSlot, keepInPools);
+      player.SetActiveCharge(charge, activeSlot);
+
+      break;
+    }
+
+    case ActiveSlot.POCKET_SINGLE_USE: {
+      player.SetPocketActiveItem(collectibleType, activeSlot, keepInPools);
+      break;
+    }
+  }
+}
+
+/**
+ * Helper function to use an active item without showing an animation, keeping the item, or adding
+ * any costumes.
+ */
+export function useActiveItemTemp(
+  player: EntityPlayer,
+  collectibleType: CollectibleType,
+): void {
+  player.UseActiveItem(collectibleType, false, false, true, false, -1);
+}

package/src/functions/playerHealth.ts

@@ -11,12 +11,8 @@ import type { PlayerHealth, SoulHeartType } from "../interfaces/PlayerHealth";
 import { countSetBits, getKBitOfN, getNumBitsOfN } from "./bitwise";
 import { getCharacterMaxHeartContainers } from "./characters";
 import { getTotalCharge } from "./charge";
-import {
-  getActiveItemSlots,
-  isCharacter,
-  isKeeper,
-  setActiveItem,
-} from "./players";
+import { getActiveItemSlots, setActiveItem } from "./playerCollectibles";
+import { isCharacter, isKeeper } from "./players";
 import { repeat } from "./utils";
 
 export function addPlayerHealthType(

package/src/functions/playerTrinkets.ts

@@ -0,0 +1,184 @@
+import {
+  PlayerType,
+  TrinketSlot,
+  TrinketType,
+} from "isaac-typescript-definitions";
+import { TRINKET_SLOT_VALUES } from "../arrays/cachedEnumValues";
+import { itemConfig } from "../core/cachedClasses";
+import { getAllPlayers, getPlayers } from "./playerIndex";
+import { isCharacter } from "./players";
+
+export function addTrinketCostume(
+  player: EntityPlayer,
+  trinketType: TrinketType,
+): void {
+  const itemConfigTrinket = itemConfig.GetTrinket(trinketType);
+  if (itemConfigTrinket === undefined) {
+    return;
+  }
+
+  player.AddCostume(itemConfigTrinket, false);
+}
+
+/**
+ * Helper function to check to see if any player has a particular trinket.
+ *
+ * @param trinketType The trinket type to check for.
+ * @param ignoreModifiers If set to true, only counts trinkets the player actually holds and ignores
+ *                        effects granted by other items. Default is false.
+ */
+export function anyPlayerHasTrinket(
+  trinketType: TrinketType,
+  ignoreModifiers?: boolean,
+): boolean {
+  const players = getAllPlayers();
+
+  return players.some((player) =>
+    player.HasTrinket(trinketType, ignoreModifiers),
+  );
+}
+
+/**
+ * Returns the slot number corresponding to where a trinket can be safely inserted.
+ *
+ * For example:
+ *
+ * ```ts
+ * const player = Isaac.GetPlayer();
+ * const trinketSlot = getOpenTrinketSlotNum(player);
+ * if (trinketSlot !== undefined) {
+ *   // They have one or more open trinket slots
+ *   player.AddTrinket(TrinketType.SWALLOWED_PENNY);
+ * }
+ * ```
+ */
+export function getOpenTrinketSlot(player: EntityPlayer): int | undefined {
+  const maxTrinkets = player.GetMaxTrinkets();
+  const trinketType1 = player.GetTrinket(TrinketSlot.SLOT_1);
+  const trinketType2 = player.GetTrinket(TrinketSlot.SLOT_2);
+
+  if (maxTrinkets === 1) {
+    return trinketType1 === TrinketType.NULL ? 0 : undefined;
+  }
+
+  if (maxTrinkets === 2) {
+    if (trinketType1 === TrinketType.NULL) {
+      return 0;
+    }
+
+    return trinketType2 === TrinketType.NULL ? 1 : undefined;
+  }
+
+  error(`The player has an unknown number of trinket slots: ${maxTrinkets}`);
+}
+
+/**
+ * Helper function to get all of the trinkets that the player is currently holding. This will not
+ * include any smelted trinkets.
+ */
+export function getPlayerTrinkets(player: EntityPlayer): TrinketType[] {
+  const trinketTypes: TrinketType[] = [];
+
+  for (const trinketSlot of TRINKET_SLOT_VALUES) {
+    const trinketType = player.GetTrinket(trinketSlot);
+    if (trinketType !== TrinketType.NULL) {
+      trinketTypes.push(trinketType);
+    }
+  }
+
+  return trinketTypes;
+}
+
+/**
+ * Helper function to get only the players that have a certain trinket.
+ *
+ * This function is variadic, meaning that you can supply as many trinket types as you want to check
+ * for. It only returns the players that have all of the trinkets.
+ */
+export function getPlayersWithTrinket(
+  ...trinketTypes: TrinketType[]
+): EntityPlayer[] {
+  const players = getPlayers();
+
+  return players.filter((player) =>
+    trinketTypes.every((trinketType) => player.HasTrinket(trinketType)),
+  );
+}
+
+/** Helper function to check to see if the player is holding one or more trinkets. */
+export function hasAnyTrinket(player: EntityPlayer): boolean {
+  const playerTrinketTypes = TRINKET_SLOT_VALUES.map((trinketSlot) =>
+    player.GetTrinket(trinketSlot),
+  );
+  return playerTrinketTypes.some(
+    (trinketType) => trinketType !== TrinketType.NULL,
+  );
+}
+
+/**
+ * Returns whether the player can hold an additional trinket, beyond what they are currently
+ * carrying. This takes into account items that modify the max number of trinkets, like Mom's Purse.
+ *
+ * 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 hasOpenTrinketSlot(player: EntityPlayer): boolean {
+  if (isCharacter(player, PlayerType.SOUL_B)) {
+    return false;
+  }
+
+  const openTrinketSlot = getOpenTrinketSlot(player);
+  return openTrinketSlot !== undefined;
+}
+
+/**
+ * Helper function to check to see if a player has one or more trinkets.
+ *
+ * This function is variadic, meaning that you can supply as many trinket types as you want to check
+ * for. Returns true if the player has any of the supplied trinket types.
+ *
+ * This function always passes `false` to the `ignoreModifiers` argument.
+ */
+export function hasTrinket(
+  player: EntityPlayer,
+  ...trinketTypes: TrinketType[]
+): boolean {
+  return trinketTypes.some((trinketType) => player.HasTrinket(trinketType));
+}
+
+/**
+ * Helper function to remove all of the held trinkets from a player.
+ *
+ * This will not remove any smelted trinkets, unless the player happens to also be holding a trinket
+ * that they have smelted. (In that case, both the held and the smelted trinket will be removed.)
+ */
+export function removeAllPlayerTrinkets(player: EntityPlayer): void {
+  for (const trinketSlot of TRINKET_SLOT_VALUES) {
+    const trinketType = player.GetTrinket(trinketSlot);
+    if (trinketType === TrinketType.NULL) {
+      continue;
+    }
+
+    let alreadyHasTrinket: boolean;
+    do {
+      player.TryRemoveTrinket(trinketType);
+      alreadyHasTrinket = player.HasTrinket(trinketType);
+    } while (alreadyHasTrinket);
+  }
+}
+
+/**
+ * Helper function to remove a trinket costume from a player. Use this helper function to avoid
+ * having to request the trinket from the item config.
+ */
+export function removeTrinketCostume(
+  player: EntityPlayer,
+  trinketType: TrinketType,
+): void {
+  const itemConfigTrinket = itemConfig.GetTrinket(trinketType);
+  if (itemConfigTrinket === undefined) {
+    return;
+  }
+
+  player.RemoveCostume(itemConfigTrinket);
+}