isaacscript-common 40.0.0 → 41.0.0

package/src/core/constants.ts

@@ -14,6 +14,7 @@ import {
   newReadonlyVector,
 } from "../functions/readOnly";
 import { asCollectibleType } from "../functions/types";
+import { eRange } from "../functions/utils";
 import { NUM_NORMAL_PILL_COLORS } from "./constantsFirstLast";
 
 /**
@@ -245,7 +246,19 @@ export const NEW_RUN_PLAYER_STARTING_POSITION = newReadonlyVector(320, 380);
 /** Corresponds to the maximum value for `EntityPlayer.SamsonBerserkCharge`. */
 export const MAX_TAINTED_SAMSON_BERSERK_CHARGE = 100_000;
 
-export const NUM_DIMENSIONS = getEnumLength(Dimension) - 1; // Account for "Dimension.CURRENT"
+/**
+ * The number of dimensions, not including `Dimension.CURRENT`. (This is derived from the
+ * `Dimension` enum.)
+ */
+export const NUM_DIMENSIONS = getEnumLength(Dimension) - 1;
+
+/**
+ * An array containing every valid `Dimension`, not including `Dimension.CURRENT`. (This is derived
+ * from the `NUM_DIMENSIONS` constant.)
+ */
+export const DIMENSIONS: readonly Dimension[] = eRange(
+  NUM_DIMENSIONS,
+) as Dimension[];
 
 /**
  * The pill pool for each run is comprised of one effect for each unique pill color (minus gold and
@@ -253,7 +266,7 @@ export const NUM_DIMENSIONS = getEnumLength(Dimension) - 1; // Account for "Dime
  */
 // TypeDoc will not work properly with the preferred export form.
 // eslint-disable-next-line unicorn/prefer-export-from
-export const NUM_PILLS_IN_POOL = NUM_NORMAL_PILL_COLORS;
+export const NUM_PILL_COLORS_IN_POOL = NUM_NORMAL_PILL_COLORS;
 
 export const ONE_BY_ONE_ROOM_GRID_SIZE = 135;
 

package/src/core/constantsFirstLast.ts

@@ -1,4 +1,8 @@
-// Constants related to modded items can be found in the "firstLast.ts" file.
+/**
+ * Constants relating to the first and last value for various vanilla objects.
+ *
+ * @module
+ */
 
 import {
   CardType,

package/src/core/constantsVanilla.ts

@@ -0,0 +1,183 @@
+/**
+ * Constants relating to collections for various vanilla objects.
+ *
+ * @module
+ */
+
+import type {
+  CardType,
+  CollectibleType,
+  PillEffect,
+  TrinketType,
+} from "isaac-typescript-definitions";
+import {
+  asCardType,
+  asCollectibleType,
+  asPillEffect,
+  asTrinketType,
+} from "../functions/types";
+import { iRange } from "../functions/utils";
+import { ReadonlySet } from "../types/ReadonlySet";
+import { itemConfig } from "./cachedClasses";
+import {
+  FIRST_CARD_TYPE,
+  FIRST_COLLECTIBLE_TYPE,
+  FIRST_PILL_EFFECT,
+  FIRST_TRINKET_TYPE,
+  LAST_VANILLA_CARD_TYPE,
+  LAST_VANILLA_COLLECTIBLE_TYPE,
+  LAST_VANILLA_PILL_EFFECT,
+  LAST_VANILLA_TRINKET_TYPE,
+} from "./constantsFirstLast";
+
+// ------------
+// Collectibles
+// ------------
+
+/**
+ * An array that represents the range from the first vanilla collectible type to the last vanilla
+ * collectible type. This will include integers that do not represent any valid collectible types.
+ *
+ * This function is only useful when building collectible type objects. For most purposes, you
+ * should use the `VANILLA_COLLECTIBLE_TYPES` or `VANILLA_COLLECTIBLE_TYPES_SET` constants instead.
+ */
+export const VANILLA_COLLECTIBLE_TYPE_RANGE: readonly int[] = iRange(
+  FIRST_COLLECTIBLE_TYPE,
+  LAST_VANILLA_COLLECTIBLE_TYPE,
+);
+
+/**
+ * An array that contains every valid vanilla collectible type, as verified by the
+ * `ItemConfig.GetCollectible` method. Vanilla collectible types are not contiguous, so every valid
+ * must be verified. (There are several gaps, e.g. 666.)
+ *
+ * If you need to do O(1) lookups, use the `VANILLA_COLLECTIBLE_TYPES_SET` constant instead.
+ */
+// eslint-disable-next-line isaacscript/strict-enums
+export const VANILLA_COLLECTIBLE_TYPES: readonly CollectibleType[] =
+  VANILLA_COLLECTIBLE_TYPE_RANGE.filter((potentialCollectibleType) => {
+    const collectibleType = asCollectibleType(potentialCollectibleType);
+    const itemConfigItem = itemConfig.GetCollectible(collectibleType);
+    return itemConfigItem !== undefined;
+  });
+
+/**
+ * A set that contains every valid vanilla collectible type, as verified by the
+ * `ItemConfig.GetCollectible` method. Vanilla collectible types are not contiguous, so every valid
+ * must be verified. (There are several gaps, e.g. 666.)
+ */
+export const VANILLA_COLLECTIBLE_TYPES_SET = new ReadonlySet(
+  VANILLA_COLLECTIBLE_TYPES,
+);
+
+// --------
+// Trinkets
+// --------
+
+/**
+ * An array that represents the range from the first vanilla trinket type to the last vanilla
+ * trinket type. This will include integers that do not represent any valid trinket types.
+ *
+ * This function is only useful when building trinket type objects. For most purposes, you should
+ * use the `VANILLA_TRINKET_TYPES` or `VANILLA_TRINKET_TYPES_SET` constants instead.
+ */
+export const VANILLA_TRINKET_TYPE_RANGE: readonly int[] = iRange(
+  FIRST_TRINKET_TYPE,
+  LAST_VANILLA_TRINKET_TYPE,
+);
+
+/**
+ * An array that contains every valid vanilla trinket type, as verified by the
+ * `ItemConfig.GetTrinket` method. Vanilla trinket types are not contiguous, so every valid must be
+ * verified. (The only gap is 47 for `POLAROID_OBSOLETE`.)
+ *
+ * If you need to do O(1) lookups, use the `VANILLA_TRINKET_TYPES_SET` constant instead.
+ */
+// eslint-disable-next-line isaacscript/strict-enums
+export const VANILLA_TRINKET_TYPES: readonly TrinketType[] =
+  VANILLA_TRINKET_TYPE_RANGE.filter((potentialTrinketType) => {
+    const trinketType = asTrinketType(potentialTrinketType);
+    const itemConfigTrinket = itemConfig.GetTrinket(trinketType);
+    return itemConfigTrinket !== undefined;
+  });
+
+/**
+ * A set that contains every valid vanilla trinket type, as verified by the `ItemConfig.GetTrinket`
+ * method. Vanilla trinket types are not contiguous, so every valid must be verified. (The only gap
+ * is 47 for `POLAROID_OBSOLETE`.)
+ */
+export const VANILLA_TRINKET_TYPES_SET = new ReadonlySet(VANILLA_TRINKET_TYPES);
+
+// ----------
+// Card Types
+// ----------
+
+/**
+ * An array that represents the range from the first vanilla card type to the last vanilla card
+ * type.
+ *
+ * This function is only useful when building card type objects. For most purposes, you should use
+ * the `VANILLA_CARD_TYPES` or `VANILLA_CARD_TYPES_SET` constants instead.
+ */
+export const VANILLA_CARD_TYPE_RANGE: readonly int[] = iRange(
+  FIRST_CARD_TYPE,
+  LAST_VANILLA_CARD_TYPE,
+);
+
+/**
+ * An array that contains every valid vanilla card type, as verified by the `ItemConfig.GetCard`
+ * method. Vanilla card types are contiguous, but we validate every entry to double check.
+ *
+ * If you need to do O(1) lookups, use the `VANILLA_CARD_TYPES_SET` constant instead.
+ */
+// eslint-disable-next-line isaacscript/strict-enums
+export const VANILLA_CARD_TYPES: readonly CardType[] =
+  VANILLA_CARD_TYPE_RANGE.filter((potentialCardType) => {
+    const cardType = asCardType(potentialCardType);
+    const itemConfigCard = itemConfig.GetCard(cardType);
+    return itemConfigCard !== undefined;
+  });
+
+/**
+ * A set that contains every valid vanilla card type, as verified by the `ItemConfig.GetCard`
+ * method. Vanilla card types are contiguous, but we validate every entry to double check.
+ */
+export const VANILLA_CARD_TYPES_SET = new ReadonlySet(VANILLA_CARD_TYPES);
+
+// ------------
+// Pill Effects
+// ------------
+
+/**
+ * An array that represents the range from the first vanilla pill effect to the last vanilla pill
+ * effect.
+ *
+ * This function is only useful when building pill effect objects. For most purposes, you should use
+ * the `VANILLA_PILL_EFFECTS` or `VANILLA_PILL_EFFECTS_SET` constants instead.
+ */
+export const VANILLA_PILL_EFFECT_RANGE: readonly int[] = iRange(
+  FIRST_PILL_EFFECT,
+  LAST_VANILLA_PILL_EFFECT,
+);
+
+/**
+ * An array that contains every valid vanilla pill effect, as verified by the
+ * `ItemConfig.GetPillEffect` method. Vanilla pill effects are contiguous, but we validate every
+ * entry to double check.
+ *
+ * If you need to do O(1) lookups, use the `VANILLA_PILL_EFFECT_SET` constant instead.
+ */
+// eslint-disable-next-line isaacscript/strict-enums
+export const VANILLA_PILL_EFFECTS: readonly PillEffect[] =
+  VANILLA_PILL_EFFECT_RANGE.filter((potentialPillEffect) => {
+    const pillEffect = asPillEffect(potentialPillEffect);
+    const itemConfigPillEffect = itemConfig.GetPillEffect(pillEffect);
+    return itemConfigPillEffect !== undefined;
+  });
+
+/**
+ * A set that contains every valid vanilla pill effect, as verified by the
+ * `ItemConfig.GetPillEffect` method. Vanilla pill effects are contiguous, but we validate every
+ * entry to double check.
+ */
+export const VANILLA_PILL_EFFECTS_SET = new ReadonlySet(VANILLA_PILL_EFFECTS);

package/src/core/upgradeMod.ts

@@ -62,7 +62,7 @@ export function upgradeMod<T extends readonly ISCFeature[] = never[]>(
   return mod as ModUpgradedWithFeatures<T>;
 }
 
-/** Initialize every optional feature that the end-user specified. */
+/** Initialize every optional feature that the end-user specified, if any. */
 function initOptionalFeatures(mod: ModUpgraded, features: ISCFeature[]) {
   for (const feature of features) {
     // We intentionally access the private method here, so we use the string index escape hatch:
@@ -74,6 +74,11 @@ function initOptionalFeatures(mod: ModUpgraded, features: ISCFeature[]) {
     // provides a convenient API for end-users.)
     const modRecord = mod as unknown as Record<string, AnyFunction>;
     for (const [funcName, func] of exportedMethodTuples) {
+      if (modRecord[funcName] !== undefined) {
+        error(
+          `Failed to upgrade the mod since two or more features share the name function name of "${funcName}". This should never happen, so report this error to the library authors.`,
+        );
+      }
       modRecord[funcName] = func;
     }
   }

package/src/functions/cards.ts

@@ -1,10 +1,7 @@
 import type { CardType } from "isaac-typescript-definitions";
 import { ItemConfigCardType, UseFlag } from "isaac-typescript-definitions";
 import { itemConfig } from "../core/cachedClasses";
-import {
-  FIRST_CARD_TYPE,
-  LAST_VANILLA_CARD_TYPE,
-} from "../core/constantsFirstLast";
+import { LAST_VANILLA_CARD_TYPE } from "../core/constantsFirstLast";
 import {
   CARD_DESCRIPTIONS,
   DEFAULT_CARD_DESCRIPTION,
@@ -12,7 +9,6 @@ import {
 import { CARD_NAMES, DEFAULT_CARD_NAME } from "../objects/cardNames";
 import { ITEM_CONFIG_CARD_TYPES_FOR_CARDS_SET } from "../sets/itemConfigCardTypesForCardsSet";
 import { addFlag } from "./flag";
-import { iRange } from "./utils";
 
 /**
  * Helper function to get a card description from a Card enum value.
@@ -77,16 +73,6 @@ export function getItemConfigCardType(
   return itemConfigCard.CardType;
 }
 
-/**
- * Helper function to get an array with every valid vanilla card sub-type.
- *
- * Note that unlike collectibles and trinkets, there are no gaps in the card types, so this is a
- * simple range from the first card type to the last vanilla card type.
- */
-export function getVanillaCardTypes(): CardType[] {
-  return iRange(FIRST_CARD_TYPE, LAST_VANILLA_CARD_TYPE);
-}
-
 /**
  * Returns true for cards that have the following card type:
  * - CardType.TAROT

package/src/functions/collectibles.ts

@@ -16,10 +16,7 @@ import {
 } from "isaac-typescript-definitions";
 import { game, itemConfig } from "../core/cachedClasses";
 import { BLIND_ITEM_PNG_PATH, DEFAULT_ITEM_POOL_TYPE } from "../core/constants";
-import {
-  FIRST_COLLECTIBLE_TYPE,
-  LAST_VANILLA_COLLECTIBLE_TYPE,
-} from "../core/constantsFirstLast";
+import { LAST_VANILLA_COLLECTIBLE_TYPE } from "../core/constantsFirstLast";
 import {
   COLLECTIBLE_DESCRIPTION_MAP,
   DEFAULT_COLLECTIBLE_DESCRIPTION,
@@ -34,7 +31,6 @@ import { hasFlag } from "./flag";
 import { isCollectible } from "./pickupVariants";
 import { clearSprite, spriteEquals } from "./sprites";
 import { isInteger } from "./types";
-import { iRange } from "./utils";
 
 const COLLECTIBLE_ANM2_PATH = "gfx/005.100_collectible.anm2";
 
@@ -406,19 +402,6 @@ export function getCollectibleTags(
   return itemConfigItem === undefined ? ItemConfigTagZero : itemConfigItem.Tags;
 }
 
-/**
- * Helper function to get an array that represents the range from the first collectible type to the
- * last vanilla collectible type. This will include integers that do not represent any valid
- * collectible types.
- *
- * This function is only useful when building collectible type objects. For most purposes, you
- * should use the `getVanillaCollectibleArray` or `getVanillaCollectibleSet` helper functions
- * instead (which are part of `ISCFeature.MODDED_ELEMENT_SETS`).
- */
-export function getVanillaCollectibleTypeRange(): CollectibleType[] {
-  return iRange(FIRST_COLLECTIBLE_TYPE, LAST_VANILLA_COLLECTIBLE_TYPE);
-}
-
 /** Returns true if the item type in the item config is equal to `ItemType.ITEM_ACTIVE`. */
 export function isActiveCollectible(collectibleType: CollectibleType): boolean {
   const itemType = getCollectibleItemType(collectibleType);

package/src/functions/dimensions.ts

@@ -1,15 +1,7 @@
 import { Dimension } from "isaac-typescript-definitions";
 import { game } from "../core/cachedClasses";
-import { NUM_DIMENSIONS } from "../core/constants";
+import { DIMENSIONS } from "../core/constants";
 import { getRoomGridIndex } from "./roomData";
-import { eRange } from "./utils";
-
-/**
- * Helper function to get an array with every valid `Dimension` (not including `Dimension.CURRENT`).
- */
-export function getAllDimensions(): Dimension[] {
-  return eRange(NUM_DIMENSIONS);
-}
 
 /**
  * Helper function to get the current dimension. Most of the time, this will be `Dimension.MAIN`,
@@ -21,7 +13,7 @@ export function getDimension(): Dimension {
   const roomDescription = level.GetRoomByIdx(roomGridIndex, Dimension.CURRENT);
   const currentRoomHash = GetPtrHash(roomDescription);
 
-  for (const dimension of getAllDimensions()) {
+  for (const dimension of DIMENSIONS) {
     const dimensionRoomDescription = level.GetRoomByIdx(
       roomGridIndex,
       dimension,

package/src/functions/pills.ts

@@ -9,7 +9,6 @@ import { game, itemConfig } from "../core/cachedClasses";
 import {
   FIRST_HORSE_PILL_COLOR,
   FIRST_PILL_COLOR,
-  FIRST_PILL_EFFECT,
   LAST_HORSE_PILL_COLOR,
   LAST_NORMAL_PILL_COLOR,
   LAST_VANILLA_PILL_EFFECT,
@@ -193,11 +192,6 @@ export function getPillEffectType(
   return pillEffectClass ?? DEFAULT_PILL_EFFECT_TYPE;
 }
 
-/** Helper function to get an array with every vanilla pill effect. */
-export function getVanillaPillEffects(): PillEffect[] {
-  return iRange(FIRST_PILL_EFFECT, LAST_VANILLA_PILL_EFFECT);
-}
-
 /** Helper function to see if the given pill color is either a gold pill or a horse gold pill. */
 export function isGoldPill(pillColor: PillColor): boolean {
   return pillColor === PillColor.GOLD || pillColor === PillColor.HORSE_GOLD;

package/src/functions/rooms.ts

@@ -19,11 +19,11 @@ import {
   StageID,
 } from "isaac-typescript-definitions";
 import { game, sfxManager } from "../core/cachedClasses";
-import { MAX_LEVEL_GRID_INDEX } from "../core/constants";
+import { DIMENSIONS, MAX_LEVEL_GRID_INDEX } from "../core/constants";
 import { ROOM_TYPE_NAMES } from "../objects/roomTypeNames";
 import { MINE_SHAFT_ROOM_SUB_TYPE_SET } from "../sets/mineShaftRoomSubTypesSet";
 import { ReadonlySet } from "../types/ReadonlySet";
-import { getAllDimensions, inDimension } from "./dimensions";
+import { inDimension } from "./dimensions";
 import {
   closeAllDoors,
   getDoors,
@@ -223,7 +223,7 @@ export function getRoomsInsideGrid(
   const level = game.GetLevel();
 
   const dimensions = includeExtraDimensionalRooms
-    ? getAllDimensions()
+    ? DIMENSIONS
     : [Dimension.CURRENT];
 
   /** We use a map instead of an array because room shapes occupy more than one room grid index. */

package/src/functions/trinkets.ts

@@ -7,10 +7,7 @@ import {
 import { TRINKET_SLOT_VALUES } from "../arrays/cachedEnumValues";
 import { itemConfig } from "../core/cachedClasses";
 import { BLIND_ITEM_PNG_PATH } from "../core/constants";
-import {
-  FIRST_TRINKET_TYPE,
-  LAST_VANILLA_TRINKET_TYPE,
-} from "../core/constantsFirstLast";
+import { LAST_VANILLA_TRINKET_TYPE } from "../core/constantsFirstLast";
 import { MysteriousPaperEffect } from "../enums/MysteriousPaperEffect";
 import {
   DEFAULT_TRINKET_DESCRIPTION,
@@ -27,7 +24,6 @@ import { isTrinket } from "./pickupVariants";
 import { isCharacter } from "./players";
 import { clearSprite } from "./sprites";
 import { asNumber } from "./types";
-import { iRange } from "./utils";
 
 /**
  * Add this to a `TrinketType` to get the corresponding golden trinket type.
@@ -185,18 +181,6 @@ export function getTrinketName(trinketType: TrinketType): string {
   return DEFAULT_TRINKET_NAME;
 }
 
-/**
- * Helper function to get an array that represents the range from the first trinket type to the last
- * vanilla trinket type. This will include integers that do not represent any valid trinket types.
- *
- * This function is only useful when building collectible type objects. For most purposes, you
- * should use the `getVanillaTrinketArray` or `getVanillaTrinketSet` helper functions instead (which
- * are part of `ISCFeature.MODDED_ELEMENT_SETS`).
- */
-export function getVanillaTrinketTypeRange(): TrinketType[] {
-  return iRange(FIRST_TRINKET_TYPE, LAST_VANILLA_TRINKET_TYPE);
-}
-
 /** 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) =>

package/src/index.ts

@@ -4,6 +4,7 @@ export * from "./classes/ModUpgraded";
 export * from "./core/cachedClasses";
 export * from "./core/constants";
 export * from "./core/constantsFirstLast";
+export * from "./core/constantsVanilla";
 export * from "./core/upgradeMod";
 export * from "./enums/AmbushType";
 export * from "./enums/CornerType";