isaacscript-common 6.6.1-dev.1 → 6.6.1-dev.5

package/src/functions/boss.ts

@@ -0,0 +1,230 @@
+import {
+  EntityType,
+  LokiVariant,
+  StageType,
+} from "isaac-typescript-definitions";
+import { VectorZero } from "../constants";
+import {
+  ALL_BOSSES_SET,
+  STAGE_TO_COMBINED_BOSS_SET_MAP,
+  STAGE_TO_STAGE_TYPE_TO_BOSS_SET_MAP,
+} from "../sets/bossSets";
+import { SIN_ENTITY_TYPES_SET } from "../sets/sinEntityTypesSet";
+import { getNPCs, spawnNPC } from "./entitySpecific";
+import { getAliveNPCs } from "./npc";
+import { isRNG } from "./rng";
+import { copySet } from "./set";
+import { repeat } from "./utils";
+
+const BOSSES_THAT_REQUIRE_MULTIPLE_SPAWNS: ReadonlySet<EntityType> = new Set([
+  EntityType.LARRY_JR, // 19 (and The Hollow / Tuff Twins / The Shell)
+  EntityType.CHUB, // 28 (and C.H.A.D. / The Carrion Queen)
+  EntityType.LOKI, // 69 (only for Lokii)
+  EntityType.GURGLING, // 237 (and Turdling)
+  EntityType.TURDLET, // 918
+]);
+
+const DEFAULT_BOSS_MULTI_SEGMENTS = 4;
+
+/**
+ * Helper function to get all of the non-dead bosses in the room.
+ *
+ * This function will not include bosses on an internal blacklist, such as Death's scythes or Big
+ * Horn holes.
+ */
+export function getAliveBosses(
+  matchingEntityType?: EntityType,
+  matchingVariant?: int,
+  matchingSubType?: int,
+  ignoreFriendly = false,
+): EntityNPC[] {
+  const aliveNPCs = getAliveNPCs(
+    matchingEntityType,
+    matchingVariant,
+    matchingSubType,
+    ignoreFriendly,
+  );
+  return aliveNPCs.filter((aliveNPC) => aliveNPC.IsBoss());
+}
+
+/**
+ * Helper function to get the set of every boss in the game.
+ *
+ * The set contains strings with the entity type and variant, separated by a period.
+ *
+ * Also see the `getBossSet` and `getCombinedBossSet` functions.
+ */
+export function getAllBossesSet(): Set<string> {
+  return copySet(ALL_BOSSES_SET);
+}
+
+/**
+ * Helper function to get the set of vanilla bosses for a particular stage and stage type
+ * combination.
+ *
+ * The set contains strings with the entity type and variant, separated by a period.
+ *
+ * Also see the `getAllBossesSet` and `getCombinedBossSet` functions.
+ */
+export function getBossSet(
+  stage: int,
+  stageType: StageType,
+): ReadonlySet<string> | undefined {
+  const stageTypeMap = STAGE_TO_STAGE_TYPE_TO_BOSS_SET_MAP.get(stage);
+  if (stageTypeMap === undefined) {
+    return undefined;
+  }
+
+  const bossSet = stageTypeMap.get(stageType);
+  if (bossSet === undefined) {
+    return undefined;
+  }
+
+  return copySet(bossSet);
+}
+
+/** Helper function to get all of the bosses in the room. */
+export function getBosses(
+  matchingEntityType?: EntityType,
+  matchingVariant?: int,
+  matchingSubType?: int,
+  ignoreFriendly = false,
+): EntityNPC[] {
+  const npcs = getNPCs(
+    matchingEntityType,
+    matchingVariant,
+    matchingSubType,
+    ignoreFriendly,
+  );
+  return npcs.filter((npc) => npc.IsBoss());
+}
+
+/**
+ * Helper function to get the set of vanilla bosses for a particular stage across all of the stage
+ * types. For example, specifying a stage of 2 will return a set with all of the bosses for
+ * Basement, Cellar, Burning Basement, Downpour, and Dross.
+ *
+ * The set contains strings with the entity type and variant, separated by a period.
+ *
+ * Also see the `getAllBossesSet` and `getBossSet` functions.
+ */
+export function getCombinedBossSet(stage: int): Set<string> | undefined {
+  const bossSet = STAGE_TO_COMBINED_BOSS_SET_MAP.get(stage);
+  if (bossSet === undefined) {
+    return undefined;
+  }
+
+  return copySet(bossSet);
+}
+
+/** Helper function to check if the provided NPC is a Sin miniboss, such as Sloth or Lust. */
+export function isSin(npc: EntityNPC): boolean {
+  return SIN_ENTITY_TYPES_SET.has(npc.Type);
+}
+
+/**
+ * Helper function to spawn a boss.
+ *
+ * Use this function instead of `spawnNPC` since it handles automatically spawning multiple segments
+ * for multi-segment bosses.
+ *
+ * By default, this will spawn Chub (and his variants) with 3 segments, Lokii with 2 copies,
+ * Gurglings/Turdlings with 2 copies, and other multi-segment bosses with 4 segments. You can
+ * customize this via the "numSegments" argument.
+ */
+export function spawnBoss(
+  entityType: EntityType,
+  variant: int,
+  subType: int,
+  position: Vector,
+  velocity: Vector = VectorZero,
+  spawner: Entity | undefined = undefined,
+  seedOrRNG: Seed | RNG | undefined = undefined,
+  numSegments?: int,
+): EntityNPC {
+  const seed = isRNG(seedOrRNG) ? seedOrRNG.Next() : seedOrRNG;
+  const npc = spawnNPC(
+    entityType,
+    variant,
+    subType,
+    position,
+    velocity,
+    spawner,
+    seed,
+  );
+
+  if (BOSSES_THAT_REQUIRE_MULTIPLE_SPAWNS.has(entityType)) {
+    const numBossSegments = getNumBossSegments(
+      entityType,
+      variant,
+      numSegments,
+    );
+    const remainingSegmentsToSpawn = numBossSegments - 1;
+    repeat(remainingSegmentsToSpawn, () => {
+      spawnNPC(entityType, variant, subType, position, velocity, spawner, seed);
+    });
+  }
+
+  return npc;
+}
+
+function getNumBossSegments(
+  entityType: EntityType,
+  variant: int,
+  numSegments: int | undefined,
+) {
+  if (numSegments !== undefined) {
+    return numSegments;
+  }
+
+  switch (entityType) {
+    // 28
+    case EntityType.CHUB: {
+      // Chub is always composed of 3 segments.
+      return 3;
+    }
+
+    // 69
+    case EntityType.LOKI: {
+      return (variant as LokiVariant) === LokiVariant.LOKII ? 2 : 1;
+    }
+
+    // 237
+    case EntityType.GURGLING: {
+      // Gurglings & Turdlings are always encountered in groups of 2.
+      return 2;
+    }
+
+    default: {
+      return DEFAULT_BOSS_MULTI_SEGMENTS;
+    }
+  }
+}
+
+/**
+ * Helper function to spawn a boss with a specific seed.
+ *
+ * For more information, see the documentation for the `spawnBoss` function.
+ */
+export function spawnBossWithSeed(
+  entityType: EntityType,
+  variant: int,
+  subType: int,
+  position: Vector,
+  seedOrRNG: Seed | RNG,
+  velocity: Vector = VectorZero,
+  spawner: Entity | undefined = undefined,
+  numSegments?: int,
+): EntityNPC {
+  const seed = isRNG(seedOrRNG) ? seedOrRNG.Next() : seedOrRNG;
+  return spawnBoss(
+    entityType,
+    variant,
+    subType,
+    position,
+    velocity,
+    spawner,
+    seed,
+    numSegments,
+  );
+}

package/src/functions/cacheFlag.ts

@@ -0,0 +1,12 @@
+import { CacheFlag } from "isaac-typescript-definitions";
+import { DEFAULT_PLAYER_STAT_MAP } from "../maps/defaultPlayerStatMap";
+
+/**
+ * Returns the starting stat that Isaac (the default character) starts with. For example, if you
+ * pass this function `CacheFlag.DAMAGE`, it will return 3.5.
+ *
+ * Note that the default fire delay is represented in the tear stat, not the `MaxFireDelay` value.
+ */
+export function getDefaultPlayerStat(cacheFlag: CacheFlag): number | undefined {
+  return DEFAULT_PLAYER_STAT_MAP.get(cacheFlag);
+}

package/src/functions/cards.ts

@@ -0,0 +1,271 @@
+import { Card, ItemConfigCardType } from "isaac-typescript-definitions";
+import { itemConfig } from "../cachedClasses";
+import {
+  FIRST_CARD,
+  FIRST_MODDED_CARD,
+  LAST_CARD,
+  MAX_VANILLA_CARD,
+} from "../constantsFirstLast";
+import {
+  CARD_DESCRIPTIONS,
+  DEFAULT_CARD_DESCRIPTION,
+} from "../objects/cardDescriptions";
+import { CARD_NAMES, DEFAULT_CARD_NAME } from "../objects/cardNames";
+import { CARD_TYPES, DEFAULT_CARD_TYPE } from "../objects/cardTypes";
+import { getEnumValues } from "./enums";
+import { getRandomSeed } from "./rng";
+import { addSetsToSet, getRandomSetElement } from "./set";
+import { irange } from "./utils";
+
+const CARD_TYPE_TO_CARDS_MAP = new Map<ItemConfigCardType, Set<Card>>();
+
+/**
+ * Contains all of the entries in the `Card` enum with the following types:
+ * - ItemConfigCardType.TAROT
+ * - ItemConfigCardType.SUIT
+ * - ItemConfigCardType.SPECIAL
+ * - ItemConfigCardType.TAROT_REVERSE
+ */
+const CARD_SET = new Set<Card>();
+
+function initCardObjects() {
+  // The card type to cards map should be valid for every card type, so we initialize it with empty
+  // sets.
+  for (const cardType of getEnumValues(ItemConfigCardType)) {
+    CARD_TYPE_TO_CARDS_MAP.set(cardType, new Set<Card>());
+  }
+
+  for (const card of getAllCards()) {
+    const cardType = getCardType(card);
+    const cardTypeSet = CARD_TYPE_TO_CARDS_MAP.get(cardType);
+    if (cardTypeSet === undefined) {
+      error(`Failed to get the card set for card type: ${cardType}`);
+    }
+    cardTypeSet.add(card);
+  }
+
+  // i.e. everything except for:
+  // - ItemConfigCardType.RUNE
+  // - ItemConfigCardType.SPECIAL_OBJECT
+  // - ItemConfigCardType.MODDED
+  const cards = getCardsOfType(
+    ItemConfigCardType.TAROT,
+    ItemConfigCardType.SUIT,
+    ItemConfigCardType.SPECIAL,
+    ItemConfigCardType.TAROT_REVERSE,
+  );
+  addSetsToSet(CARD_SET, cards);
+}
+
+/** Helper function to get an array with every valid card sub-type. This includes modded cards. */
+export function getAllCards(): Card[] {
+  return irange(FIRST_CARD, LAST_CARD) as Card[];
+}
+
+/**
+ * Helper function to get a card description from a Card enum value.
+ *
+ * For example:
+ *
+ * ```ts
+ * const card = Card.FOOL;
+ * const cardDescription = getCardDescription(card); // cardDescription is "Where journey begins"
+ * ```
+ */
+export function getCardDescription(card: Card): string {
+  // "ItemConfigCard.Description" is bugged with vanilla cards on patch v1.7.6, so we use a
+  // hard-coded map as a workaround.
+  const cardDescription = CARD_DESCRIPTIONS[card];
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (cardDescription !== undefined) {
+    return cardDescription;
+  }
+
+  const itemConfigCard = itemConfig.GetCard(card);
+  if (itemConfigCard !== undefined) {
+    return itemConfigCard.Description;
+  }
+
+  return DEFAULT_CARD_DESCRIPTION;
+}
+
+/**
+ * Helper function to get a card name from a Card.
+ *
+ * For example:
+ *
+ * ```ts
+ * const card = Card.FOOL;
+ * const cardName = getCardName(card); // cardName is "0 - The Fool"
+ * ```
+ */
+export function getCardName(card: Card): string {
+  // "ItemConfigCard.Name" is bugged with vanilla cards on patch v1.7.6, so we use a hard-coded map
+  // as a workaround.
+  const cardName = CARD_NAMES[card];
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (cardName !== undefined) {
+    return cardName;
+  }
+
+  const itemConfigCard = itemConfig.GetCard(card);
+  if (itemConfigCard !== undefined) {
+    return itemConfigCard.Name;
+  }
+
+  return DEFAULT_CARD_NAME;
+}
+
+export function getCardType(card: Card): ItemConfigCardType {
+  const cardType = CARD_TYPES[card];
+  // Handle modded cards.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  return cardType === undefined ? DEFAULT_CARD_TYPE : cardType;
+}
+
+/**
+ * Helper function to get a set of cards matching the type. Also see the `CardType` enum.
+ *
+ * This function is variadic, meaning that you can you can specify N card types to get a set
+ * containing cards that match any of the specified types.
+ */
+export function getCardsOfType(...cardTypes: ItemConfigCardType[]): Set<Card> {
+  if (CARD_TYPE_TO_CARDS_MAP.size === 0) {
+    initCardObjects();
+  }
+
+  const matchingCards = new Set<Card>();
+  for (const cardType of cardTypes) {
+    const cardSet = CARD_TYPE_TO_CARDS_MAP.get(cardType);
+    if (cardSet === undefined) {
+      error(`Failed to get the cards for type: ${cardType}`);
+    }
+
+    for (const card of cardSet.values()) {
+      matchingCards.add(card);
+    }
+  }
+
+  return matchingCards;
+}
+
+/**
+ * Helper function to get an array with every modded card sub-type.
+ *
+ * Returns an empty array if there are no modded cards.
+ */
+export function getModdedCards(): Card[] {
+  if (MAX_VANILLA_CARD === LAST_CARD) {
+    return [];
+  }
+
+  return irange(FIRST_MODDED_CARD, LAST_CARD) as Card[];
+}
+
+/**
+ * Has an equal chance of returning any card (e.g. Fool, Reverse Fool, Wild Card, etc.).
+ *
+ * This will not return:
+ * - any runes
+ * - any objects like Dice Shard
+ * - any modded cards (since there is not a way to distinguish between modded cards and modded
+ *   runes/objects)
+ *
+ * @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()`.
+ * @param exceptions Optional. An array of cards to not select.
+ */
+export function getRandomCard(
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+  exceptions: Card[] = [],
+): Card {
+  return getRandomSetElement(CARD_SET, seedOrRNG, exceptions);
+}
+
+/**
+ * @param cardType The card type that represents the pool of cards to select from.
+ * @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()`.
+ * @param exceptions Optional. An array of cards to not select.
+ */
+export function getRandomCardOfType(
+  cardType: ItemConfigCardType,
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+  exceptions: Card[] = [],
+): Card {
+  const cardSet = getCardsOfType(cardType);
+  return getRandomSetElement(cardSet, seedOrRNG, exceptions);
+}
+
+/**
+ * Has an equal chance of returning any rune (e.g. Rune of Hagalaz, Blank Rune, Black Rune, Soul of
+ * Isaac, etc.). This will never return a Rune Shard.
+ *
+ * @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()`.
+ * @param exceptions Optional. An array of runes to not select.
+ */
+export function getRandomRune(
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+  exceptions: Card[] = [],
+): Card {
+  const runesSet = getCardsOfType(ItemConfigCardType.RUNE);
+  runesSet.delete(Card.RUNE_SHARD);
+  return getRandomSetElement(runesSet, seedOrRNG, exceptions);
+}
+
+/** Helper function to get an array with every valid vanilla card sub-type. */
+export function getVanillaCards(): Card[] {
+  return irange(FIRST_CARD, MAX_VANILLA_CARD) as Card[];
+}
+
+/**
+ * Returns true for cards that have the following card type:
+ * - CardType.TAROT
+ * - CardType.SUIT
+ * - CardType.SPECIAL
+ * - CardType.TAROT_REVERSE
+ */
+export function isCard(card: Card): boolean {
+  return CARD_SET.has(card);
+}
+
+/** Returns whether or not the given card matches the specified card type. */
+export function isCardType(card: Card, cardType: ItemConfigCardType): boolean {
+  return cardType === getCardType(card);
+}
+
+/** Returns true for cards that have `CardType.MODDED`. */
+export function isModdedCard(card: Card): boolean {
+  return isCardType(card, ItemConfigCardType.MODDED);
+}
+
+/** Returns true for cards that have `CardType.SPECIAL_OBJECT`. */
+export function isPocketItemObject(card: Card): boolean {
+  return isCardType(card, ItemConfigCardType.SPECIAL_OBJECT);
+}
+
+/** Returns true for cards that have `CardType.TAROT_REVERSE`. */
+export function isReverseTarotCard(card: Card): boolean {
+  return isCardType(card, ItemConfigCardType.TAROT_REVERSE);
+}
+
+/** Returns true for cards that have `CardType.RUNE`. */
+export function isRune(card: Card): boolean {
+  return isCardType(card, ItemConfigCardType.RUNE);
+}
+
+/** Returns true for cards that have `CardType.SPECIAL`. */
+export function isSpecialCard(card: Card): boolean {
+  return isCardType(card, ItemConfigCardType.SPECIAL);
+}
+
+/** Returns true for cards that have `CardType.SUIT`. */
+export function isSuitCard(card: Card): boolean {
+  return isCardType(card, ItemConfigCardType.SUIT);
+}
+
+/** Returns true for cards that have `CardType.TAROT`. */
+export function isTarotCard(card: Card): boolean {
+  return isCardType(card, ItemConfigCardType.TAROT);
+}

package/src/functions/challenges.ts

@@ -0,0 +1,13 @@
+import { Challenge } from "isaac-typescript-definitions";
+import {
+  CHALLENGE_NAMES,
+  DEFAULT_CHALLENGE_NAME,
+} from "../objects/challengeNames";
+
+/** Get the proper name for a `Challenge` enum. This will only work for vanilla challenges. */
+export function getChallengeName(challenge: Challenge): string {
+  const challengeName = CHALLENGE_NAMES[challenge];
+  // Handle modded challenges.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  return challengeName === undefined ? DEFAULT_CHALLENGE_NAME : challengeName;
+}

package/src/functions/character.ts

@@ -0,0 +1,120 @@
+import { PlayerType } from "isaac-typescript-definitions";
+import { LAST_VANILLA_CHARACTER } from "../constantsFirstLast";
+import { CHARACTER_NAMES } from "../objects/characterNames";
+import { CHARACTERS_THAT_START_WITH_AN_ACTIVE_ITEM_SET } from "../sets/charactersThatStartWithAnActiveItemSet";
+import { CHARACTERS_WITH_BLACK_HEART_FROM_ETERNAL_HEART_SET } from "../sets/charactersWithBlackHeartFromEternalHeartSet";
+import { CHARACTERS_WITH_FREE_DEVIL_DEALS_SET } from "../sets/charactersWithFreeDevilDealsSet";
+import { CHARACTERS_WITH_NO_RED_HEARTS_SET } from "../sets/charactersWithNoRedHeartsSet";
+import { CHARACTERS_WITH_NO_SOUL_HEARTS_SET } from "../sets/charactersWithNoSoulHeartsSet";
+import { LOST_STYLE_CHARACTERS_SET } from "../sets/lostStyleCharactersSet";
+
+/**
+ * Helper function to determine if the given character can have red heart containers. Returns true
+ * for characters like Isaac, Magdalene, or Cain. Returns true for Keeper and Tainted Keeper, even
+ * though coin containers are not technically the same as red heart containers. Returns false for
+ * characters like Blue Baby. Returns false for The Lost and Tainted Lost.
+ */
+export function characterCanHaveRedHearts(character: PlayerType): boolean {
+  return !CHARACTERS_WITH_NO_RED_HEARTS_SET.has(character);
+}
+
+/**
+ * Helper function to determine if the given character can have soul hearts. Returns true for
+ * characters like Isaac, Magdalene, or Cain. Returns false for characters like Bethany. Returns
+ * false for The Lost and Tainted Lost.
+ */
+export function characterCanHaveSoulHearts(character: PlayerType): boolean {
+  return !CHARACTERS_WITH_NO_SOUL_HEARTS_SET.has(character);
+}
+
+/**
+ * Helper function for determining whether the given character can take free Devil Deals. (e.g. The
+ * Lost, Tainted Lost, etc.)
+ */
+export function characterCanTakeFreeDevilDeals(character: PlayerType): boolean {
+  return CHARACTERS_WITH_FREE_DEVIL_DEALS_SET.has(character);
+}
+
+/**
+ * Normally, characters get a red heart container upon reaching a new floor with an eternal heart,
+ * but some characters grant a black heart instead. Returns true for Dark Judas and Tainted Judas.
+ * Otherwise, returns false.
+ */
+export function characterGetsBlackHeartFromEternalHeart(
+  character: PlayerType,
+): boolean {
+  return CHARACTERS_WITH_BLACK_HEART_FROM_ETERNAL_HEART_SET.has(character);
+}
+
+/**
+ * Helper function to determine if the specified character starts with an active item.
+ *
+ * For the purposes of this function, the save file is considered to be fully unlocked (e.g. Isaac
+ * is considered to starts with the D6, but this is not the case on a brand new save file).
+ */
+export function characterStartsWithActiveItem(character: PlayerType): boolean {
+  return CHARACTERS_THAT_START_WITH_AN_ACTIVE_ITEM_SET.has(character);
+}
+
+/**
+ * - Most characters have a 56 frame death animation (i.e. the "Death" animation).
+ * - The Lost and Tainted Lost have a 38 frame death animation (i.e. the "LostDeath" animation).
+ * - Tainted Forgotten have a 20 frame death animation (i.e. the "ForgottenDeath" animation).
+ */
+export function getCharacterDeathAnimationName(character: PlayerType): string {
+  if (LOST_STYLE_CHARACTERS_SET.has(character)) {
+    return "LostDeath";
+  }
+
+  if (character === PlayerType.THE_FORGOTTEN_B) {
+    return "ForgottenDeath";
+  }
+
+  return "Death";
+}
+
+/**
+ * Returns the maximum heart containers that the provided character can have. Normally, this is 12,
+ * but with Keeper it is 3, and with Tainted Keeper it is 2. This does not account for Birthright or
+ * Mother's Kiss; use the `getPlayerMaxHeartContainers` helper function for that.
+ */
+export function getCharacterMaxHeartContainers(character: PlayerType): int {
+  // 14
+  if (character === PlayerType.KEEPER) {
+    return 3;
+  }
+
+  // 16
+  if (character === PlayerType.THE_FORGOTTEN) {
+    return 6;
+  }
+
+  // 17
+  if (character === PlayerType.THE_SOUL) {
+    return 6;
+  }
+
+  // 33
+  if (character === PlayerType.KEEPER_B) {
+    return 2;
+  }
+
+  return 12;
+}
+
+/** Helper function to get the name of a character. Returns "Unknown" for modded characters. */
+export function getCharacterName(character: PlayerType): string {
+  if (isModdedCharacter(character)) {
+    return "Unknown";
+  }
+
+  return CHARACTER_NAMES[character];
+}
+
+export function isModdedCharacter(character: PlayerType): boolean {
+  return !isVanillaCharacter(character);
+}
+
+export function isVanillaCharacter(character: PlayerType): boolean {
+  return character <= LAST_VANILLA_CHARACTER;
+}