isaacscript-common 7.18.0 → 8.0.0

package/src/features/firstLast.ts

@@ -0,0 +1,429 @@
+import {
+  Card,
+  CollectibleType,
+  PillEffect,
+  TrinketType,
+} from "isaac-typescript-definitions";
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { itemConfig } from "../core/cachedClasses";
+import {
+  FIRST_CARD,
+  FIRST_PILL_EFFECT,
+  FIRST_TRINKET_TYPE,
+  LAST_VANILLA_CARD,
+  LAST_VANILLA_COLLECTIBLE_TYPE,
+  LAST_VANILLA_PILL_EFFECT,
+  LAST_VANILLA_TRINKET_TYPE,
+  NUM_VANILLA_CARDS,
+  NUM_VANILLA_COLLECTIBLE_TYPES,
+  NUM_VANILLA_PILL_EFFECTS,
+  NUM_VANILLA_TRINKET_TYPES,
+} from "../core/constantsFirstLast";
+import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import {
+  asCard,
+  asCollectibleType,
+  asNumber,
+  asPillEffect,
+  asTrinketType,
+} from "../functions/types";
+import { irange } from "../functions/utils";
+
+const FEATURE_NAME = "firstLast";
+
+let atLeastOneCallbackFired = false;
+
+/** @internal */
+export function firstLastInit(mod: ModUpgraded): void {
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_NEW_ROOM_EARLY,
+    postNewRoomEarly,
+  );
+}
+
+// ModCallbackCustom.POST_NEW_ROOM_EARLY
+function postNewRoomEarly() {
+  atLeastOneCallbackFired = true;
+}
+
+function errorIfNoCallbacksFired(constantType: string) {
+  if (!atLeastOneCallbackFired) {
+    error(
+      `Failed to retrieve a ${constantType} constant. Since not all mods have been loaded yet, any constants of this type will be inaccurate. Thus, you must wait until at least one callback fires before retrieving these types of constants.`,
+    );
+  }
+}
+
+// ------------
+// Collectibles
+// ------------
+
+/**
+ * Returns the first modded collectible type, or undefined if there are no modded collectibles.
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all collectibles will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getFirstModdedCollectibleType(): CollectibleType | undefined {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  errorIfNoCallbacksFired("collectible");
+
+  const firstModdedCollectibleType = asCollectibleType(
+    asNumber(LAST_VANILLA_COLLECTIBLE_TYPE) + 1,
+  );
+  const itemConfigItem = itemConfig.GetCollectible(firstModdedCollectibleType);
+  return itemConfigItem === undefined ? undefined : firstModdedCollectibleType;
+}
+
+/**
+ * Will change depending on how many modded collectibles there are.
+ *
+ * Equal to `itemConfig.GetCollectibles().Size - 1`. (`Size` includes invalid collectibles, like
+ * 666. We subtract one to account for `CollectibleType.NULL`.)
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all collectibles will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getLastCollectibleType(): CollectibleType {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  errorIfNoCallbacksFired("collectible");
+
+  return itemConfig.GetCollectibles().Size - 1;
+}
+
+/**
+ * Helper function to get an array that represents the all modded collectible types.
+ *
+ * This function is only useful when building collectible type objects. For most purposes, you
+ * should use the `getModdedCollectibleSet` helper function instead.
+ *
+ * Returns an empty array if there are no modded collectible types.
+ *
+ * (This function is named differently from the `getVanillaCollectibleTypeRange` function because
+ * all modded collectible types are contiguous. Thus, each value represents a real
+ * `CollectibleType`.)
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all collectibles will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getModdedCollectibleTypes(): CollectibleType[] {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  errorIfNoCallbacksFired("collectible");
+
+  const firstModdedCollectibleType = getFirstModdedCollectibleType();
+  if (firstModdedCollectibleType === undefined) {
+    return [];
+  }
+
+  const lastCollectibleType = getLastCollectibleType();
+  return irange(firstModdedCollectibleType, lastCollectibleType);
+}
+
+/**
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all collectibles will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getNumCollectibleTypes(): int {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  errorIfNoCallbacksFired("collectible");
+
+  const numModdedCollectibleTypes = getNumModdedCollectibleTypes();
+  return NUM_VANILLA_COLLECTIBLE_TYPES + numModdedCollectibleTypes;
+}
+
+/**
+ * Unlike vanilla collectible types, modded collectible types are always contiguous.
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all collectibles will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getNumModdedCollectibleTypes(): int {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  errorIfNoCallbacksFired("collectible");
+
+  const lastCollectibleType = getLastCollectibleType();
+  return lastCollectibleType - LAST_VANILLA_COLLECTIBLE_TYPE;
+}
+
+// --------
+// Trinkets
+// --------
+
+/**
+ * Returns the first modded trinket type, or undefined if there are no modded trinkets.
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all trinkets will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getFirstModdedTrinketType(): TrinketType | undefined {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  errorIfNoCallbacksFired("trinket");
+
+  const firstModdedTrinketType = asTrinketType(
+    asNumber(LAST_VANILLA_TRINKET_TYPE) + 1,
+  );
+  const itemConfigItem = itemConfig.GetTrinket(firstModdedTrinketType);
+  return itemConfigItem === undefined ? undefined : firstModdedTrinketType;
+}
+
+/**
+ * Will change depending on how many modded cards there are.
+ *
+ * This is equal to the number of trinket types, since all trinket types are contiguous (unlike
+ * collectibles).
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all trinkets will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getLastTrinketType(): TrinketType {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  errorIfNoCallbacksFired("trinket");
+
+  const numTrinketTypes = getNumTrinketTypes();
+  return asTrinketType(numTrinketTypes);
+}
+
+/**
+ * Helper function to get an array that represents every modded trinket type.
+ *
+ * Returns an empty array if there are no modded trinket types.
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all trinkets will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getModdedTrinketTypes(): TrinketType[] {
+  const firstModdedTrinketType = getFirstModdedTrinketType();
+  if (firstModdedTrinketType === undefined) {
+    return [];
+  }
+
+  const lastTrinketType = getLastTrinketType();
+  return irange(firstModdedTrinketType, lastTrinketType);
+}
+
+/**
+ * Will change depending on how many modded cards there are.
+ *
+ * Equal to `itemConfig.GetTrinkets().Size - 1`. (We subtract one to account for
+ * `TrinketType.NULL`.)
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all trinkets will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getNumTrinketTypes(): int {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  errorIfNoCallbacksFired("trinket");
+
+  return itemConfig.GetTrinkets().Size - 1;
+}
+
+/**
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all trinkets will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getNumModdedTrinketTypes(): int {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  errorIfNoCallbacksFired("trinket");
+
+  const numTrinketTypes = getNumTrinketTypes();
+  return numTrinketTypes - NUM_VANILLA_TRINKET_TYPES;
+}
+
+/**
+ * Helper function to get an array that contains every trinket type.
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all trinkets will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getTrinketTypes(): TrinketType[] {
+  const lastTrinketType = getLastTrinketType();
+  return irange(FIRST_TRINKET_TYPE, lastTrinketType);
+}
+
+// -----
+// Cards
+// -----
+
+/**
+ * Helper function to get an array with every valid card sub-type. This includes modded cards.
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all cards will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getAllCards(): Card[] {
+  const lastCard = getLastCard();
+  return irange(FIRST_CARD, lastCard);
+}
+
+/**
+ * Returns the first modded card sub-type, or undefined if there are no modded cards.
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all cards will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getFirstModdedCard(): Card | undefined {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  errorIfNoCallbacksFired("card");
+
+  const firstModdedCard = asCard(asNumber(LAST_VANILLA_CARD) + 1);
+  const itemConfigCard = itemConfig.GetCard(firstModdedCard);
+  return itemConfigCard === undefined ? undefined : firstModdedCard;
+}
+
+/**
+ * Will change depending on how many modded cards there are.
+ *
+ * This is equal to the number of cards, since all card sub-types are contiguous (unlike
+ * collectibles).
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all cards will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getLastCard(): Card {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  errorIfNoCallbacksFired("card");
+
+  const numCards = getNumCards();
+  return asCard(numCards);
+}
+
+/**
+ * Helper function to get an array with every modded card sub-type.
+ *
+ * Returns an empty array if there are no modded cards.
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all cards will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getModdedCards(): Card[] {
+  const firstModdedCard = getFirstModdedCard();
+  if (firstModdedCard === undefined) {
+    return [];
+  }
+
+  const lastCard = getLastCard();
+  return irange(firstModdedCard, lastCard);
+}
+
+/**
+ * Will change depending on how many modded cards there are.
+ *
+ * Equal to `itemConfig.GetCards().Size - 1`. (We subtract one to account for `Card.NULL`.)
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all cards will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getNumCards(): int {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  errorIfNoCallbacksFired("card");
+
+  return itemConfig.GetCards().Size - 1;
+}
+
+/**
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all trinkets will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getNumModdedCards(): int {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  errorIfNoCallbacksFired("card");
+
+  const numCards = getNumCards();
+  return numCards - NUM_VANILLA_CARDS;
+}
+
+// ------------
+// Pill Effects
+// ------------
+
+/**
+ * Helper function to get an array with every valid pill effect. This includes modded pill effects.
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all pill effects will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getAllPillEffects(): PillEffect[] {
+  const lastPillEffect = getLastPillEffect();
+  return irange(FIRST_PILL_EFFECT, lastPillEffect);
+}
+
+/**
+ * Returns the first modded pill effect, or undefined if there are no modded pill effects.
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all pill effects will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getFirstModdedPillEffect(): PillEffect | undefined {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  errorIfNoCallbacksFired("pill");
+
+  const firstModdedPillEffect = asPillEffect(
+    asNumber(LAST_VANILLA_PILL_EFFECT) + 1,
+  );
+  const itemConfigPillEffect = itemConfig.GetPillEffect(firstModdedPillEffect);
+  return itemConfigPillEffect === undefined ? undefined : firstModdedPillEffect;
+}
+
+/**
+ * Will change depending on how many modded pill effects there are.
+ *
+ * This is equal to the number of pill effects, since all pill effects are contiguous (unlike
+ * collectibles).
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all pill effects will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getLastPillEffect(): PillEffect {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  errorIfNoCallbacksFired("pill");
+
+  const numPillEffects = getNumPillEffects();
+  return asPillEffect(numPillEffects);
+}
+
+/**
+ * Helper function to get an array with every modded pill effect.
+ *
+ * Returns an empty array if there are no modded pill effects.
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all pill effects will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getModdedPillEffects(): PillEffect[] {
+  const firstModdedPillEffect = getFirstModdedPillEffect();
+  if (firstModdedPillEffect === undefined) {
+    return [];
+  }
+
+  const lastPillEffect = getLastPillEffect();
+  return irange(firstModdedPillEffect, lastPillEffect);
+}
+
+/**
+ * Will change depending on how many modded pill effects there are.
+ *
+ * Equal to `itemConfig.GetPillEffects().Size`. (We do not have to subtract one, because the first
+ * pill effect has an ID of 0 and there is no `PillEffect.NULL`.)
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all pill effects will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getNumPillEffects(): int {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  errorIfNoCallbacksFired("pill");
+
+  return itemConfig.GetPillEffects().Size;
+}
+
+/**
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all pill effects will necessarily be present when a mod first loads (due to mod load order).
+ */
+export function getNumModdedPillEffects(): int {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  errorIfNoCallbacksFired("pill");
+
+  const numPillEffects = getNumPillEffects();
+  return numPillEffects - NUM_VANILLA_PILL_EFFECTS;
+}

package/src/functions/array.ts

@@ -399,15 +399,7 @@ export function getRandomArrayIndex<T>(
   return getRandomInt(0, array.length - 1, seedOrRNG, exceptions);
 }
 
-/**
- * Initializes an array with all elements containing the specified default value.
- *
- * For example:
- *
- * ```ts
- * const playerTransformations = initArray(false, PlayerForm.NUM_PLAYER_FORMS - 1);
- * ```
- */
+/** Initializes an array with all elements containing the specified default value. */
 export function initArray<T>(defaultValue: T, size: int): T[] {
   const array: T[] = [];
   repeat(size, () => {

package/src/functions/cards.ts

@@ -1,11 +1,6 @@
 import { Card, ItemConfigCardType } from "isaac-typescript-definitions";
 import { itemConfig } from "../core/cachedClasses";
-import {
-  FIRST_CARD,
-  FIRST_MODDED_CARD,
-  LAST_CARD,
-  MAX_VANILLA_CARD,
-} from "../core/constantsFirstLast";
+import { FIRST_CARD, LAST_VANILLA_CARD } from "../core/constantsFirstLast";
 import {
   CARD_DESCRIPTIONS,
   DEFAULT_CARD_DESCRIPTION,
@@ -28,14 +23,14 @@ const CARD_TYPE_TO_CARDS_MAP = new Map<ItemConfigCardType, Set<Card>>();
  */
 const CARD_SET = new Set<Card>();
 
-function initCardObjects() {
+function lazyInitCardMapsSets() {
   // 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()) {
+  for (const card of getVanillaCards()) {
     const cardType = getCardType(card);
     const cardTypeSet = CARD_TYPE_TO_CARDS_MAP.get(cardType);
     if (cardTypeSet === undefined) {
@@ -57,11 +52,6 @@ function initCardObjects() {
   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);
-}
-
 /**
  * Helper function to get a card description from a Card enum value.
  *
@@ -131,7 +121,7 @@ export function getCardType(card: Card): ItemConfigCardType {
  */
 export function getCardsOfType(...cardTypes: ItemConfigCardType[]): Set<Card> {
   if (CARD_TYPE_TO_CARDS_MAP.size === 0) {
-    initCardObjects();
+    lazyInitCardMapsSets();
   }
 
   const matchingCards = new Set<Card>();
@@ -149,19 +139,6 @@ export function getCardsOfType(...cardTypes: ItemConfigCardType[]): Set<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);
-}
-
 /**
  * Has an equal chance of returning any card (e.g. Fool, Reverse Fool, Wild Card, etc.).
  *
@@ -216,7 +193,7 @@ export function getRandomRune(
 
 /** Helper function to get an array with every valid vanilla card sub-type. */
 export function getVanillaCards(): Card[] {
-  return irange(FIRST_CARD, MAX_VANILLA_CARD);
+  return irange(FIRST_CARD, LAST_VANILLA_CARD);
 }
 
 /**

package/src/functions/{cacheFlag.ts → collectibleCacheFlag.ts}

@@ -1,6 +1,5 @@
 import { CacheFlag, CollectibleType } from "isaac-typescript-definitions";
 import { itemConfig } from "../core/cachedClasses";
-import { DEFAULT_PLAYER_STAT_MAP } from "../maps/defaultPlayerStatMap";
 import { getCollectibleArray } from "./collectibleSet";
 import { getEnumValues } from "./enums";
 import { hasFlag } from "./flag";
@@ -12,7 +11,11 @@ const CACHE_FLAG_TO_COLLECTIBLES_MAP = new Map<
   Set<CollectibleType>
 >();
 
-function initCacheFlagMap() {
+function lazyInitCacheFlagMap() {
+  if (CACHE_FLAG_TO_COLLECTIBLES_MAP.size > 0) {
+    return;
+  }
+
   for (const cacheFlag of getEnumValues(CacheFlag)) {
     const collectiblesSet = new Set<CollectibleType>();
 
@@ -26,6 +29,7 @@ function initCacheFlagMap() {
   }
 }
 
+/** Helper function to check in the item config if a given collectible has a given cache flag. */
 export function collectibleHasCacheFlag(
   collectibleType: CollectibleType,
   cacheFlag: CacheFlag,
@@ -41,14 +45,14 @@ export function collectibleHasCacheFlag(
 /**
  * Returns a set containing every collectible type with the given cache flag, including modded
  * collectibles.
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all collectibles will necessarily be present when a mod first loads (due to mod load order).
  */
 export function getCollectiblesForCacheFlag(
   cacheFlag: CacheFlag,
 ): Set<CollectibleType> {
-  // Lazy initialize the map.
-  if (CACHE_FLAG_TO_COLLECTIBLES_MAP.size === 0) {
-    initCacheFlagMap();
-  }
+  lazyInitCacheFlagMap();
 
   const collectiblesSet = CACHE_FLAG_TO_COLLECTIBLES_MAP.get(cacheFlag);
   if (collectiblesSet === undefined) {
@@ -58,16 +62,6 @@ export function getCollectiblesForCacheFlag(
   return copySet(collectiblesSet);
 }
 
-/**
- * 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);
-}
-
 /**
  * Returns an array containing every collectible type that the player has that matches the provided
  * CacheFlag.
@@ -82,6 +76,9 @@ export function getDefaultPlayerStat(cacheFlag: CacheFlag): number | undefined {
  *   CollectibleType.DEAD_DOVE,
  * ]
  * ```
+ *
+ * This function can only be called if at least one callback has been executed. This is because not
+ * all collectibles will necessarily be present when a mod first loads (due to mod load order).
  */
 export function getPlayerCollectiblesForCacheFlag(
   player: EntityPlayer,