isaacscript-common 16.1.7 → 17.0.1

package/dist/index.d.ts

@@ -10,6 +10,7 @@ import { BombVariant } from 'isaac-typescript-definitions';
 import { BossID } from 'isaac-typescript-definitions';
 import { ButtonAction } from 'isaac-typescript-definitions';
 import { CacheFlag } from 'isaac-typescript-definitions';
+import { CallbackPriority } from 'isaac-typescript-definitions/dist/src/enums/CallbackPriority';
 import { CardType } from 'isaac-typescript-definitions';
 import { Challenge } from 'isaac-typescript-definitions';
 import { CoinSubType } from 'isaac-typescript-definitions';
@@ -4168,14 +4169,6 @@ export declare function getCardName(cardType: CardType): string;
  */
 export declare function getCards(cardType?: CardType): EntityPickupCard[];
 
-/**
- * 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.
- */
-export declare function getCardTypesOfType(...itemConfigCardTypes: ItemConfigCardType[]): Set<CardType>;
-
 /** Get the proper name for a `Challenge` enum. This will only work for vanilla challenges. */
 export declare function getChallengeName(challenge: Challenge): string;
 
@@ -4906,7 +4899,13 @@ export declare function getHUDOffsetVector(): Vector;
  */
 export declare function getIsaacAPIClassName(object: unknown): string | undefined;
 
-export declare function getItemConfigCardType(cardType: CardType): ItemConfigCardType;
+/**
+ * Helper function to get the item config card type of a particular card, rune, or object. For
+ * example, the item config card type of `CardType.FOOL` is equal to `ItemConfigCardType.TAROT`.
+ *
+ * Returns undefined if the provided card type was not valid.
+ */
+export declare function getItemConfigCardType(cardType: CardType): ItemConfigCardType | undefined;
 
 /**
  * Helper function to calculate what the resulting `BitFlags<DoorSlotFlag>` value would be for a
@@ -5604,30 +5603,6 @@ export declare function getRandomArrayElementAndRemove<T>(array: T[], seedOrRNG?
  */
 export declare function getRandomArrayIndex<T>(array: T[] | readonly T[], seedOrRNG?: Seed | RNG, exceptions?: int[] | readonly int[]): int;
 
-/**
- * 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 declare function getRandomCard(seedOrRNG?: Seed | RNG, exceptions?: CardType[]): CardType;
-
-/**
- * @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.
- */
-export declare function getRandomCardTypeOfType(itemConfigCardType: ItemConfigCardType, seedOrRNG?: Seed | RNG, exceptions?: CardType[]): CardType;
-
 /**
  * Helper function to get a random color.
  *
@@ -5744,16 +5719,6 @@ export declare function getRandomJSONRoom(jsonRooms: JSONRoom[], seedOrRNG?: See
  */
 export declare function getRandomKColor(seedOrRNG?: Seed | RNG, alpha?: number): KColor;
 
-/**
- * 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 declare function getRandomRune(seedOrRNG?: Seed | RNG, exceptions?: CardType[]): CardType;
-
 /**
  * Helper function to get a random `Seed` value to be used in spawning entities and so on. Use this
  * instead of calling the `Random` function directly since that can return a value of 0 and crash
@@ -6486,7 +6451,12 @@ export declare function getTSTLClassName(object: unknown): string | undefined;
  */
 export declare function getUnusedDoorSlots(): DoorSlot[];
 
-/** Helper function to get an array with every valid vanilla card sub-type. */
+/**
+ * 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 declare function getVanillaCardTypes(): CardType[];
 
 /**
@@ -7917,6 +7887,9 @@ export declare function isVanillaWallGridIndex(gridIndex: int): boolean;
 /** Helper function to check if something is an instantiated `Vector` object. */
 export declare function isVector(object: unknown): object is Vector;
 
+/** The set of all `ItemConfigCardType` values that are not a rune or special object. */
+export declare const ITEM_CONFIG_CARD_TYPES_FOR_CARDS: Set<ItemConfigCardType>;
+
 /**
  * A cached version of the class returned from the `Isaac.GetItemConfig()` constructor.
  *
@@ -10519,6 +10492,12 @@ declare class ModdedElementSets extends Feature {
     private vanillaTrinketTypesSet;
     private moddedTrinketTypesArray;
     private moddedTrinketTypesSet;
+    private allCardTypesArray;
+    private allCardTypesSet;
+    private vanillaCardTypesArray;
+    private vanillaCardTypesSet;
+    private moddedCardTypesArray;
+    private moddedCardTypesSet;
     private tagToCollectibleTypesMap;
     private cacheFlagToCollectibleTypesMap;
     private cacheFlagToTrinketTypesMap;
@@ -10527,17 +10506,64 @@ declare class ModdedElementSets extends Feature {
     private flyingTrinketTypesSet;
     private edenActiveCollectibleTypesSet;
     private edenPassiveCollectibleTypesSet;
+    private itemConfigCardTypeToCardTypeMap;
+    /**
+     * The set of cards that are not:
+     *
+     * - ItemConfigCardType.RUNE
+     * - ItemConfigCardType.SPECIAL_OBJECT
+     */
+    private cardSet;
     private moddedElementDetection;
     private lazyInitVanillaCollectibleTypes;
     private lazyInitModdedCollectibleTypes;
     private lazyInitVanillaTrinketTypes;
     private lazyInitModdedTrinketTypes;
+    private lazyInitVanillaCardTypes;
+    private lazyInitModdedCardTypes;
     private lazyInitTagToCollectibleTypesMap;
     private lazyInitCacheFlagToCollectibleTypesMap;
     private lazyInitCacheFlagToTrinketTypesMap;
     private lazyInitFlyingCollectibleTypesSet;
     private lazyInitFlyingTrinketTypesSet;
     private lazyInitEdenCollectibleTypesSet;
+    private lazyInitCardTypes;
+    /**
+     * 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`.
+     */
+    getCardArray(): readonly CardType[];
+    /**
+     * 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`.
+     */
+    getCardSet(): ReadonlySet<CardType>;
+    /**
+     * 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`.
+     */
+    getCardTypesOfType(...itemConfigCardTypes: ItemConfigCardType[]): Set<CardType>;
     /**
      * Returns an array containing every valid collectible type in the game, including modded
      * collectibles.
@@ -10576,6 +10602,10 @@ declare 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`.
      */
     getCollectiblesForTransformation(playerForm: PlayerForm): ReadonlySet<CollectibleType>;
@@ -10587,6 +10617,10 @@ declare 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`.
      */
     getCollectiblesWithCacheFlag(cacheFlag: CacheFlag): ReadonlySet<CollectibleType>;
@@ -10600,6 +10634,10 @@ declare 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`.
      */
     getCollectiblesWithTag(itemConfigTag: ItemConfigTag): ReadonlySet<CollectibleType>;
@@ -10607,6 +10645,10 @@ declare 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`.
      */
     getEdenActiveCollectibles(): ReadonlySet<CollectibleType>;
@@ -10614,6 +10656,10 @@ declare 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`.
      */
     getEdenPassiveCollectibles(): ReadonlySet<CollectibleType>;
@@ -10624,6 +10670,10 @@ declare 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
@@ -10634,9 +10684,36 @@ declare 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`.
      */
     getFlyingTrinkets(): ReadonlySet<TrinketType>;
+    /**
+     * 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`.
+     */
+    getModdedCardArray(): readonly CardType[];
+    /**
+     * 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`.
+     */
+    getModdedCardSet(): ReadonlySet<CardType>;
     /**
      * Returns an array containing every modded collectible type in the game.
      *
@@ -10664,10 +10741,10 @@ declare class ModdedElementSets extends Feature {
      */
     getModdedCollectibleSet(): ReadonlySet<CollectibleType>;
     /**
-     * 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).
@@ -10676,10 +10753,10 @@ declare class ModdedElementSets extends Feature {
      */
     getModdedTrinketArray(): readonly TrinketType[];
     /**
-     * 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).
@@ -10743,16 +10820,61 @@ declare class ModdedElementSets extends Feature {
      * In order to use this function, you must upgrade your mod with `ISCFeature.MODDED_ELEMENT_SETS`.
      */
     getPlayerTrinketsWithCacheFlag(player: EntityPlayer, cacheFlag: CacheFlag): Map<TrinketType, int>;
+    /**
+     * 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.
+     */
+    getRandomCard(seedOrRNG?: Seed | RNG, exceptions?: CardType[]): CardType;
+    /**
+     * @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.
+     */
+    getRandomCardTypeOfType(itemConfigCardType: ItemConfigCardType, seedOrRNG?: Seed | RNG, exceptions?: CardType[]): CardType;
+    /**
+     * 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.
+     */
+    getRandomRune(seedOrRNG?: Seed | RNG, exceptions?: CardType[]): CardType;
     /**
      * 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.
      */
     getRandomEdenActiveCollectible(seedOrRNG?: Seed | RNG, exceptions?: CollectibleType[] | readonly CollectibleType[]): CollectibleType;
     /**
      * 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.
      */
     getRandomEdenPassiveCollectible(seedOrRNG?: Seed | RNG, exceptions?: CollectibleType[] | readonly CollectibleType[]): CollectibleType;
     /**
@@ -10789,6 +10911,24 @@ declare class ModdedElementSets extends Feature {
      * In order to use this function, you must upgrade your mod with `ISCFeature.MODDED_ELEMENT_SETS`.
      */
     getTrinketsWithCacheFlag(cacheFlag: CacheFlag): ReadonlySet<TrinketType>;
+    /**
+     * 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`.
+     */
+    getVanillaCardArray(): readonly CardType[];
+    /**
+     * 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`.
+     */
+    getVanillaCardSet(): ReadonlySet<CardType>;
     /**
      * Returns an array containing every valid vanilla collectible type in the game.
      *
@@ -10924,7 +11064,8 @@ export declare class ModUpgradedBase implements Mod {
      * `ModCallback.POST_UPDATE` event corresponds to being executed once at the end of every game
      * logic frame.
      */
-    AddCallback<T extends ModCallback>(modCallback: T, ...args: AddCallbackParameters[T]): void;
+    AddCallback<T extends ModCallback | string>(modCallback: T, ...args: T extends ModCallback ? AddCallbackParameters[T] : unknown[]): void;
+    AddPriorityCallback<T extends ModCallback | string>(modCallback: T, priority: CallbackPriority | int, ...args: T extends ModCallback ? AddCallbackParameters[T] : unknown[]): void;
     /** Returns whether or not a corresponding "save#.dat" file exists for the current mod. */
     HasData(): boolean;
     /**
@@ -11222,6 +11363,7 @@ declare class Pause extends Feature {
     private postUpdate;
     private stopTearsAndProjectilesFromMoving;
     private inputActionGetActionValue;
+    isPaused(): boolean;
     /**
      * Helper function to emulate what happens when the player pauses the game. Use the `unpause`
      * function to return things back to normal.
@@ -11245,7 +11387,6 @@ declare class Pause extends Feature {
 declare class PersistentEntities extends Feature {
     private roomHistory;
     private postEntityRemove;
-    private checkDespawningFromPlayerLeavingRoom;
     /**
      * The persistent entity is despawning because the player is in the process of leaving the room.
      * Keep track of the position for later.