isaacscript-common 16.1.7 → 17.0.0

package/dist/src/functions/globals.lua

@@ -142,7 +142,6 @@ local DEFAULT_GLOBALS = __TS__New(Set, {
     "SackSubType",
     "SeedEffect",
     "Seeds",
-    "ShockwaveParams",
     "SkinColor",
     "SortingLayer",
     "SoundEffect",

package/dist/src/functions/positionVelocity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"positionVelocity.d.ts","sourceRoot":"","sources":["../../../src/functions/positionVelocity.ts"],"names":[],"mappings":";;;;AAaA,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAAE,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,GAAG,GACZ,OAAO,CAIT;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,KAAK,GACd,OAAO,CAKT;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,gBAAgB,EAAE,MAAM,EACxB,mBAAmB,UAAQ,EAC3B,eAAe,CAAC,EAAE,KAAK,GACtB,MAAM,CA8CR;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAY5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAY7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,eAAe,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,EACrC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,IAAI,CAYN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,EACtC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,IAAI,CAYN"}
+{"version":3,"file":"positionVelocity.d.ts","sourceRoot":"","sources":["../../../src/functions/positionVelocity.ts"],"names":[],"mappings":";;;;AAaA,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAAE,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,GAAG,GACZ,OAAO,CAIT;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,KAAK,GACd,OAAO,CAKT;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,gBAAgB,EAAE,MAAM,EACxB,mBAAmB,UAAQ,EAC3B,eAAe,CAAC,EAAE,KAAK,GACtB,MAAM,CA4CR;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAY5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAY7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,eAAe,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,EACrC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,IAAI,CAYN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,EACtC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,IAAI,CAYN"}

package/dist/src/functions/positionVelocity.lua

@@ -54,11 +54,11 @@ function ____exports.findFreePosition(self, startingPosition, avoidActiveEntitie
     local room = game:GetRoom()
     local heavenDoors = getEffects(nil, EffectVariant.HEAVEN_LIGHT_DOOR, HeavenLightDoorSubType.HEAVEN_DOOR)
     do
-        local i = 0
-        while i < MAX_FIND_FREE_POSITION_ATTEMPTS do
+        local initialStep = 0
+        while initialStep < MAX_FIND_FREE_POSITION_ATTEMPTS do
             do
-                local position = room:FindFreePickupSpawnPosition(startingPosition, i, avoidActiveEntities)
-                local closePlayer = getPlayerCloserThan(nil, position, DISTANCE_OF_GRID_TILE * 1.5)
+                local position = room:FindFreePickupSpawnPosition(startingPosition, initialStep, avoidActiveEntities)
+                local closePlayer = getPlayerCloserThan(nil, position, DISTANCE_OF_GRID_TILE)
                 if closePlayer ~= nil then
                     goto __continue7
                 end
@@ -75,7 +75,7 @@ function ____exports.findFreePosition(self, startingPosition, avoidActiveEntitie
                 return position
             end
             ::__continue7::
-            i = i + 1
+            initialStep = initialStep + 1
         end
     end
     return room:FindFreePickupSpawnPosition(startingPosition)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "16.1.7",
+  "version": "17.0.0",
   "description": "Helper functions and features for IsaacScript mods.",
   "keywords": [
     "isaac",
@@ -22,6 +22,6 @@
   "main": "dist/src/index",
   "types": "dist/src/index.d.ts",
   "dependencies": {
-    "isaac-typescript-definitions": "^9.5.2"
+    "isaac-typescript-definitions": "^10.0.3"
   }
 }

package/src/classes/ModUpgradedBase.ts

@@ -1,4 +1,5 @@
 import { ModCallback } from "isaac-typescript-definitions";
+import { CallbackPriority } from "isaac-typescript-definitions/dist/src/enums/CallbackPriority";
 import { getCallbacks } from "../callbacks";
 import { EXPORTED_METHOD_NAMES_KEY } from "../decorators";
 import { ISCFeature } from "../enums/ISCFeature";
@@ -73,16 +74,27 @@ export class ModUpgradedBase implements Mod {
    * `ModCallback.POST_UPDATE` event corresponds to being executed once at the end of every game
    * logic frame.
    */
-  public AddCallback<T extends ModCallback>(
+  public AddCallback<T extends ModCallback | string>(
     modCallback: T,
-    ...args: AddCallbackParameters[T]
+    ...args: T extends ModCallback ? AddCallbackParameters[T] : unknown[]
+  ): void {
+    this.AddPriorityCallback(modCallback, CallbackPriority.DEFAULT, ...args);
+  }
+
+  public AddPriorityCallback<T extends ModCallback | string>(
+    modCallback: T,
+    priority: CallbackPriority | int,
+    ...args: T extends ModCallback ? AddCallbackParameters[T] : unknown[]
   ): void {
     if (this.debug) {
       const callback = args[0];
       const optionalArg = args[1];
 
       const parentFunctionDescription = getParentFunctionDescription();
-      const callbackName = `ModCallback.${ModCallback[modCallback]}`;
+      const customCallback = type(modCallback) === "string";
+      const callbackName = customCallback
+        ? `${modCallback} (custom callback)`
+        : `ModCallback.${ModCallback[modCallback as ModCallback]}`;
       const signature =
         parentFunctionDescription === undefined
           ? callbackName
@@ -93,6 +105,8 @@ export class ModUpgradedBase implements Mod {
        * prefix.
        */
       const callbackWithLogger: typeof callback = (
+        // @ts-expect-error The compiler is not smart enough to know that the callback args should
+        // match the callback.
         ...callbackArgs: Parameters<typeof callback>
       ) => {
         const startTime = getTime();
@@ -100,6 +114,7 @@ export class ModUpgradedBase implements Mod {
 
         // @ts-expect-error The compiler is not smart enough to know that the callback args should
         // match the callback.
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
         const returnValue = callback(...callbackArgs);
 
         const endTime = getTime();
@@ -113,16 +128,16 @@ export class ModUpgradedBase implements Mod {
           Isaac.DebugString(`${signature} - END`);
         }
 
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
         return returnValue;
       };
 
-      const newArgs = [
-        callbackWithLogger,
-        optionalArg,
-      ] as unknown as AddCallbackParameters[T];
-      this.mod.AddCallback(modCallback, ...newArgs);
+      const newArgs = [callbackWithLogger, optionalArg];
+      // @ts-expect-error The compiler is not smart enough to know that the callback args should
+      // match the callback.
+      this.mod.AddPriorityCallback(modCallback, priority, ...newArgs);
     } else {
-      this.mod.AddCallback(modCallback, ...args);
+      this.mod.AddPriorityCallback(modCallback, priority, ...args);
     }
   }
 

package/src/classes/features/other/ModdedElementSets.ts

@@ -1,14 +1,23 @@
 import {
   CacheFlag,
+  CardType,
   CollectibleType,
+  ItemConfigCardType,
   ItemConfigTag,
   PlayerForm,
   TrinketType,
 } from "isaac-typescript-definitions";
 import { itemConfig } from "../../../core/cachedClasses";
-import { FIRST_GLITCHED_COLLECTIBLE_TYPE } from "../../../core/constants";
+import {
+  FIRST_GLITCHED_COLLECTIBLE_TYPE,
+  ITEM_CONFIG_CARD_TYPES_FOR_CARDS,
+} from "../../../core/constants";
 import { Exported } from "../../../decorators";
 import { ISCFeature } from "../../../enums/ISCFeature";
+import {
+  getItemConfigCardType,
+  getVanillaCardTypes,
+} from "../../../functions/cards";
 import {
   collectibleHasCacheFlag,
   getVanillaCollectibleTypeRange,
@@ -78,6 +87,15 @@ export class ModdedElementSets extends Feature {
   private moddedTrinketTypesArray: TrinketType[] = [];
   private moddedTrinketTypesSet = new Set<TrinketType>();
 
+  private allCardTypesArray: CardType[] = [];
+  private allCardTypesSet = new Set<CardType>();
+
+  private vanillaCardTypesArray: CardType[] = [];
+  private vanillaCardTypesSet = new Set<CardType>();
+
+  private moddedCardTypesArray: CardType[] = [];
+  private moddedCardTypesSet = new Set<CardType>();
+
   private tagToCollectibleTypesMap = new Map<
     ItemConfigTag,
     Set<CollectibleType>
@@ -97,6 +115,19 @@ export class ModdedElementSets extends Feature {
   private edenActiveCollectibleTypesSet = new Set<CollectibleType>();
   private edenPassiveCollectibleTypesSet = new Set<CollectibleType>();
 
+  private itemConfigCardTypeToCardTypeMap = new Map<
+    ItemConfigCardType,
+    Set<CardType>
+  >();
+
+  /**
+   * The set of cards that are not:
+   *
+   * - ItemConfigCardType.RUNE
+   * - ItemConfigCardType.SPECIAL_OBJECT
+   */
+  private cardSet = new Set<CardType>();
+
   private moddedElementDetection: ModdedElementDetection;
 
   /** @internal */
@@ -196,6 +227,49 @@ export class ModdedElementSets extends Feature {
     }
   }
 
+  private lazyInitVanillaCardTypes() {
+    if (this.vanillaCardTypesArray.length > 0) {
+      return;
+    }
+
+    const vanillaCardTypes = getVanillaCardTypes();
+    for (const cardType of vanillaCardTypes) {
+      // Vanilla card types are contiguous, but we check every value just to be safe (and so that
+      // the code is similar to the collectible and trinket functions above).
+      const itemConfigCard = itemConfig.GetCard(cardType);
+      if (itemConfigCard !== undefined) {
+        this.vanillaCardTypesArray.push(cardType);
+        this.vanillaCardTypesSet.add(cardType);
+      }
+    }
+  }
+
+  private lazyInitModdedCardTypes() {
+    if (this.moddedCardTypesArray.length > 0) {
+      return;
+    }
+
+    this.lazyInitVanillaCardTypes();
+
+    for (const cardType of this.vanillaCardTypesArray) {
+      this.allCardTypesArray.push(cardType);
+      this.allCardTypesSet.add(cardType);
+    }
+
+    const moddedCardTypes = this.moddedElementDetection.getModdedCardTypes();
+    for (const cardType of moddedCardTypes) {
+      // Modded card types are contiguous, but we check every value just in case.
+      const itemConfigCard = itemConfig.GetCard(cardType);
+      if (itemConfigCard !== undefined) {
+        this.moddedCardTypesArray.push(cardType);
+        this.moddedCardTypesSet.add(cardType);
+
+        this.allCardTypesArray.push(cardType);
+        this.allCardTypesSet.add(cardType);
+      }
+    }
+  }
+
   private lazyInitTagToCollectibleTypesMap() {
     if (this.tagToCollectibleTypesMap.size > 0) {
       return;
@@ -337,6 +411,114 @@ export class ModdedElementSets extends Feature {
     }
   }
 
+  private lazyInitCardTypes() {
+    if (this.itemConfigCardTypeToCardTypeMap.size > 0) {
+      return;
+    }
+
+    // The card type to cards map should be valid for every card type, so we initialize it with
+    // empty sets.
+    for (const itemConfigCardType of getEnumValues(ItemConfigCardType)) {
+      this.itemConfigCardTypeToCardTypeMap.set(
+        itemConfigCardType,
+        new Set<CardType>(),
+      );
+    }
+
+    for (const cardType of this.getCardArray()) {
+      const itemConfigCardType = getItemConfigCardType(cardType);
+      if (itemConfigCardType !== undefined) {
+        const cardTypeSet =
+          this.itemConfigCardTypeToCardTypeMap.get(itemConfigCardType);
+        if (cardTypeSet === undefined) {
+          error(
+            `Failed to get the card set for item config card type: ${itemConfigCardType}`,
+          );
+        }
+        cardTypeSet.add(cardType);
+
+        if (ITEM_CONFIG_CARD_TYPES_FOR_CARDS.has(itemConfigCardType)) {
+          this.cardSet.add(cardType);
+        }
+      }
+    }
+  }
+
+  // --------------
+  // Public Methods
+  // --------------
+
+  /**
+   * Returns an array containing every valid card type in the game, including modded cards.
+   *
+   * Use this if you need to iterate over the cards in order. If you need to do O(1) lookups, then
+   * use the `getCardSet` helper function instead.
+   *
+   * 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).
+   *
+   * In order to use this function, you must upgrade your mod with `ISCFeature.MODDED_ELEMENT_SETS`.
+   */
+  @Exported
+  public getCardArray(): readonly CardType[] {
+    this.lazyInitModdedCardTypes();
+    return this.allCardTypesArray;
+  }
+
+  /**
+   * Returns a set containing every valid card type in the game, including modded cards.
+   *
+   * Use this if you need to do O(1) lookups. If you need to iterate over the cards in order, then
+   * use the `getCardArray` helper function instead.
+   *
+   * 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).
+   *
+   * In order to use this function, you must upgrade your mod with `ISCFeature.MODDED_ELEMENT_SETS`.
+   */
+  @Exported
+  public getCardSet(): ReadonlySet<CardType> {
+    this.lazyInitModdedCardTypes();
+    return this.allCardTypesSet;
+  }
+
+  /**
+   * Helper function to get a set of card types matching the `ItemConfigCardType`.
+   *
+   * 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.
+   *
+   * 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).
+   *
+   * In order to use this function, you must upgrade your mod with `ISCFeature.MODDED_ELEMENT_SETS`.
+   */
+  @Exported
+  public getCardTypesOfType(
+    ...itemConfigCardTypes: ItemConfigCardType[]
+  ): Set<CardType> {
+    if (this.itemConfigCardTypeToCardTypeMap.size === 0) {
+      this.lazyInitCardTypes();
+    }
+
+    const matchingCardTypes = new Set<CardType>();
+    for (const itemConfigCardType of itemConfigCardTypes) {
+      const cardTypeSet =
+        this.itemConfigCardTypeToCardTypeMap.get(itemConfigCardType);
+      if (cardTypeSet === undefined) {
+        error(
+          `Failed to get the card type set for item config type: ${itemConfigCardType}`,
+        );
+      }
+
+      for (const cardType of cardTypeSet.values()) {
+        matchingCardTypes.add(cardType);
+      }
+    }
+
+    return matchingCardTypes;
+  }
+
   /**
    * Returns an array containing every valid collectible type in the game, including modded
    * collectibles.
@@ -385,6 +567,10 @@ export class ModdedElementSets extends Feature {
    * const guppyCollectibleTypes = getCollectiblesForTransformation(PlayerForm.GUPPY);
    * ```
    *
+   * 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).
+   *
    * In order to use this function, you must upgrade your mod with `ISCFeature.MODDED_ELEMENT_SETS`.
    */
   @Exported
@@ -409,6 +595,10 @@ export class ModdedElementSets extends Feature {
    * not all collectibles will necessarily be present when a mod first loads (due to mod load
    * order).
    *
+   * 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).
+   *
    * In order to use this function, you must upgrade your mod with `ISCFeature.MODDED_ELEMENT_SETS`.
    */
   @Exported
@@ -435,6 +625,10 @@ export class ModdedElementSets extends Feature {
    * const offensiveCollectibleTypes = getCollectibleTypesWithTag(ItemConfigTag.OFFENSIVE);
    * ```
    *
+   * 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).
+   *
    * In order to use this function, you must upgrade your mod with `ISCFeature.MODDED_ELEMENT_SETS`.
    */
   @Exported
@@ -457,6 +651,10 @@ export class ModdedElementSets extends Feature {
    * Returns a set containing every valid passive item that can be randomly granted to Eden as a
    * starting item.
    *
+   * 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).
+   *
    * In order to use this function, you must upgrade your mod with `ISCFeature.MODDED_ELEMENT_SETS`.
    */
   @Exported
@@ -469,6 +667,10 @@ export class ModdedElementSets extends Feature {
    * Returns a set containing every valid passive item that can be randomly granted to Eden as a
    * starting item.
    *
+   * 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).
+   *
    * In order to use this function, you must upgrade your mod with `ISCFeature.MODDED_ELEMENT_SETS`.
    */
   @Exported
@@ -484,6 +686,10 @@ export class ModdedElementSets extends Feature {
    * Collectibles that only grant flight conditionally are manually pruned. Collectibles such as
    * Empty Vessel should be checked for via the `hasFlyingTemporaryEffect` function.
    *
+   * 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).
+   *
    * In order to use this function, you must upgrade your mod with `ISCFeature.MODDED_ELEMENT_SETS`.
    *
    * @param pruneConditionalItems Whether or not collectibles that only grant flight conditionally
@@ -504,6 +710,9 @@ export class ModdedElementSets extends Feature {
    * Returns a set of all of the trinkets that grant flight. (All trinkets that grant flight do so
    * conditionally, like Bat Wing and Azazel's Stump.)
    *
+   * 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).
+   *
    * In order to use this function, you must upgrade your mod with `ISCFeature.MODDED_ELEMENT_SETS`.
    */
   @Exported
@@ -513,6 +722,40 @@ export class ModdedElementSets extends Feature {
     return this.flyingTrinketTypesSet;
   }
 
+  /**
+   * Returns an array containing every modded card type in the game.
+   *
+   * Use this if you need to iterate over the cards in order. If you need to do O(1) lookups, then
+   * use the `getModdedCardSet` helper function instead.
+   *
+   * 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).
+   *
+   * In order to use this function, you must upgrade your mod with `ISCFeature.MODDED_ELEMENT_SETS`.
+   */
+  @Exported
+  public getModdedCardArray(): readonly CardType[] {
+    this.lazyInitModdedCardTypes();
+    return this.moddedCardTypesArray;
+  }
+
+  /**
+   * Returns a set containing every modded card type in the game.
+   *
+   * Use this if you need to do O(1) lookups. If you need to iterate over the cards in order, then
+   * use the `getModdedCardArray` helper function instead.
+   *
+   * 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).
+   *
+   * In order to use this function, you must upgrade your mod with `ISCFeature.MODDED_ELEMENT_SETS`.
+   */
+  @Exported
+  public getModdedCardSet(): ReadonlySet<CardType> {
+    this.lazyInitModdedCardTypes();
+    return this.moddedCardTypesSet;
+  }
+
   /**
    * Returns an array containing every modded collectible type in the game.
    *
@@ -550,10 +793,10 @@ export class ModdedElementSets extends Feature {
   }
 
   /**
-   * Returns an array containing every valid trinket type in the game, including modded trinkets.
+   * Returns an array containing every modded trinket type in the game.
    *
    * Use this if you need to iterate over the trinkets in order. If you need to do O(1) lookups,
-   * then use the `getTrinketSet` helper function instead.
+   * then use the `getModdedTrinketSet` helper function instead.
    *
    * 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).
@@ -567,10 +810,10 @@ export class ModdedElementSets extends Feature {
   }
 
   /**
-   * Returns a set containing every valid trinket type in the game, including modded trinkets.
+   * Returns a set containing every modded trinket type in the game.
    *
    * Use this if you need to do O(1) lookups. If you need to iterate over the trinkets in order,
-   * then use the `getTrinketArray` helper function instead.
+   * then use the `getModdedTrinketArray` helper function instead.
    *
    * 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).
@@ -754,10 +997,72 @@ export class ModdedElementSets extends Feature {
     return playerTrinkets;
   }
 
+  /**
+   * 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
+   *
+   * @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.
+   */
+  @Exported
+  public getRandomCard(
+    seedOrRNG: Seed | RNG = getRandomSeed(),
+    exceptions: CardType[] = [],
+  ): CardType {
+    return getRandomSetElement(this.cardSet, seedOrRNG, exceptions);
+  }
+
+  /**
+   * @param itemConfigCardType The item config 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.
+   */
+  @Exported
+  public getRandomCardTypeOfType(
+    itemConfigCardType: ItemConfigCardType,
+    seedOrRNG: Seed | RNG = getRandomSeed(),
+    exceptions: CardType[] = [],
+  ): CardType {
+    const cardTypeSet = this.getCardTypesOfType(itemConfigCardType);
+    return getRandomSetElement(cardTypeSet, 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.
+   */
+  @Exported
+  public getRandomRune(
+    seedOrRNG: Seed | RNG = getRandomSeed(),
+    exceptions: CardType[] = [],
+  ): CardType {
+    const runesSet = this.getCardTypesOfType(ItemConfigCardType.RUNE);
+    runesSet.delete(CardType.RUNE_SHARD);
+    return getRandomSetElement(runesSet, seedOrRNG, exceptions);
+  }
+
   /**
    * Returns a random active collectible type that that is a valid starting item for Eden.
    *
+   * 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).
+   *
    * In order to use this function, you must upgrade your mod with `ISCFeature.MODDED_ELEMENT_SETS`.
+   *
+   * @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.
    */
   @Exported
   public getRandomEdenActiveCollectible(
@@ -775,7 +1080,15 @@ export class ModdedElementSets extends Feature {
   /**
    * Returns a random passive collectible type that that is a valid starting item for Eden.
    *
+   * 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).
+   *
    * In order to use this function, you must upgrade your mod with `ISCFeature.MODDED_ELEMENT_SETS`.
+   *
+   * @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.
    */
   @Exported
   public getRandomEdenPassiveCollectible(
@@ -847,6 +1160,34 @@ export class ModdedElementSets extends Feature {
     return trinketsSet;
   }
 
+  /**
+   * Returns an array containing every valid vanilla card type in the game.
+   *
+   * Use this if you need to iterate over the cards in order. If you need to do O(1) lookups, then
+   * use the `getVanillaCardSet` helper function instead.
+   *
+   * In order to use this function, you must upgrade your mod with `ISCFeature.MODDED_ELEMENT_SETS`.
+   */
+  @Exported
+  public getVanillaCardArray(): readonly CardType[] {
+    this.lazyInitVanillaCardTypes();
+    return this.vanillaCardTypesArray;
+  }
+
+  /**
+   * Returns a set containing every valid vanilla card type in the game.
+   *
+   * Use this if you need to do O(1) lookups. If you need to iterate over the cards in order, then
+   * use the `getVanillaCardArray` helper function instead.
+   *
+   * In order to use this function, you must upgrade your mod with `ISCFeature.MODDED_ELEMENT_SETS`.
+   */
+  @Exported
+  public getVanillaCardSet(): ReadonlySet<CardType> {
+    this.lazyInitVanillaCardTypes();
+    return this.vanillaCardTypesSet;
+  }
+
   /**
    * Returns an array containing every valid vanilla collectible type in the game.
    *

package/src/classes/features/other/Pause.ts

@@ -113,6 +113,11 @@ export class Pause extends Feature {
     return 1;
   };
 
+  @Exported
+  public isPaused(): boolean {
+    return this.v.run.isPseudoPaused;
+  }
+
   /**
    * Helper function to emulate what happens when the player pauses the game. Use the `unpause`
    * function to return things back to normal.

package/src/core/constants.ts

@@ -1,6 +1,7 @@
 import {
   Dimension,
   DisplayFlag,
+  ItemConfigCardType,
   ItemPoolType,
   TrinketSlot,
 } from "isaac-typescript-definitions";
@@ -74,6 +75,14 @@ export const FIRST_GLITCHED_COLLECTIBLE_TYPE = asCollectibleType((1 << 32) - 1);
 /** Game frames are what is returned by the `Game.GetFrameCount` method. */
 export const GAME_FRAMES_PER_SECOND = 30;
 
+/** The set of all `ItemConfigCardType` values that are not a rune or special object. */
+export const ITEM_CONFIG_CARD_TYPES_FOR_CARDS = new Set([
+  ItemConfigCardType.TAROT,
+  ItemConfigCardType.SUIT,
+  ItemConfigCardType.SPECIAL,
+  ItemConfigCardType.TAROT_REVERSE,
+]);
+
 /** Render frames are what is returned by the `Isaac.GetFrameCount` method. */
 export const RENDER_FRAMES_PER_SECOND = 60;
 

package/src/core/upgradeMod.ts

@@ -53,6 +53,16 @@ export function upgradeMod<T extends readonly ISCFeature[] = never[]>(
   debug = false,
   timeThreshold?: float,
 ): ModUpgraded<T> {
+  // First, validate that all of the features exist (for Lua users who don't have type-safety).
+  for (const feature of features) {
+    const featureType = type(feature);
+    if (featureType !== "number") {
+      error(
+        `Failed to upgrade the mod due to one of the specified features being of type "${featureType}". (All of the features should be numbers represented by the "ISCFeature" enum.)`,
+      );
+    }
+  }
+
   patchErrorFunction();
 
   const mod = new ModUpgradedBase(modVanilla, debug, timeThreshold);