isaacscript-common 8.4.6 → 8.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "8.4.6",
+  "version": "8.7.0",
   "description": "Helper functions and features for IsaacScript mods.",
   "keywords": [
     "isaac",

package/src/enums/ModCallbackCustom.ts

@@ -959,7 +959,7 @@ export enum ModCallbackCustom {
 
   /**
    * Fires from the `POST_PEFFECT_UPDATE` callback when a player's collectible count is higher than
-   * what it was on the previous frame.
+   * what it was on the previous frame or when a new active collectible is acquired.
    *
    * When registering the callback, takes an optional second argument that will make the callback
    * only fire if the collectible matches the `CollectibleType` provided.
@@ -975,7 +975,7 @@ export enum ModCallbackCustom {
 
   /**
    * Fires from the `POST_PEFFECT_UPDATE` callback when a player's collectible count is lower than
-   * what it was on the previous frame.
+   * what it was on the previous frame or when an active collectible is no longer present.
    *
    * When registering the callback, takes an optional second argument that will make the callback
    * only fire if the collectible matches the `CollectibleType` provided.

package/src/features/characterStats.ts

@@ -10,8 +10,7 @@ import {
   PlayerType,
 } from "isaac-typescript-definitions";
 import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
-import { addStat } from "../functions/players";
-import { getDefaultPlayerStat } from "../functions/stats";
+import { addStat, getDefaultPlayerStat } from "../functions/stats";
 
 const FEATURE_NAME = "characterStats";
 

package/src/features/firstLast.ts

@@ -95,11 +95,11 @@ export function getLastCollectibleType(): CollectibleType {
 /**
  * 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 only useful when building collectible type objects. For most purposes, you
+ * should use the `getModdedCollectibleArray` or `getModdedCollectibleSet` helper function instead.
+ *
  * (This function is named differently from the `getVanillaCollectibleTypeRange` function because
  * all modded collectible types are contiguous. Thus, each value represents a real
  * `CollectibleType`.)
@@ -189,6 +189,9 @@ export function getLastTrinketType(): TrinketType {
  *
  * Returns an empty array if there are no modded trinket types.
  *
+ * This function is only useful when building collectible type objects. For most purposes, you
+ * should use the `getModdedCollectibleArray` or `getModdedCollectibleSet` 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).
  */

package/src/features/playerInventory.ts

@@ -3,7 +3,11 @@ import { DefaultMap } from "../classes/DefaultMap";
 import { ModUpgraded } from "../classes/ModUpgraded";
 import { ModCallbackCustom } from "../enums/ModCallbackCustom";
 import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
-import { arrayRemoveInPlace, copyArray } from "../functions/array";
+import {
+  arrayRemoveInPlace,
+  copyArray,
+  getLastElement,
+} from "../functions/array";
 import { isActiveCollectible } from "../functions/collectibles";
 import { getCollectibleArray } from "../functions/collectibleSet";
 import {
@@ -31,10 +35,16 @@ function newPlayerInventory(player: EntityPlayer) {
   const inventory: CollectibleType[] = [];
 
   for (const collectibleType of getCollectibleArray()) {
-    const numCollectibles = player.GetCollectibleNum(collectibleType, true);
-    repeat(numCollectibles, () => {
-      inventory.push(collectibleType);
-    });
+    // We have to use the `EntityPlayer.HasCollectible` method in addition to the
+    // `EntityPlayer.GetCollectibleNum` method in order to mitigate situations like Lilith's Incubus
+    // counting as a collectible. (The former method will return false for her innate Incubus, but
+    // the latter method will return 1.)
+    if (player.HasCollectible(collectibleType)) {
+      const numCollectibles = player.GetCollectibleNum(collectibleType, true);
+      repeat(numCollectibles, () => {
+        inventory.push(collectibleType);
+      });
+    }
   }
 
   return inventory;
@@ -68,6 +78,9 @@ function useItemD4(
   _rng: RNG,
   player: EntityPlayer,
 ): boolean | undefined {
+  // This function is also triggered when the player uses D100, D Infinity, a 1-pip dice room, or a
+  // 6-pip dice room. (Genesis should be automatically handled by the
+  // `POST_PLAYER_COLLECTIBLE_REMOVED` callback.)
   resetInventory(player);
 
   return undefined;
@@ -107,9 +120,6 @@ function postCollectibleRemoved(
  * Helper function to get all of the collectibles that the player has gotten so far on this run, in
  * order.
  *
- * Note that this does not include active collectibles that have since been dropped for other
- * collectibles.
- *
  * In the case of inventory initialization or the case where the player rerolls their build in the
  * middle of the run (e.g. with D4), the order of the inventory will not correspond to the order
  * that the items were actually given to the player. In this case, the inventory will be in the
@@ -121,6 +131,10 @@ function postCollectibleRemoved(
  * would not be updated. In vanilla, this situation would never happen, but another mod might do
  * this for some reason. (With that said, the next time that a collectible is normally added or
  * removed, it would trigger a re-scan, and the previous changes would be picked up.)
+ *
+ * @param player The player to get the inventory for.
+ * @param includeActiveCollectibles Optional. If true, will include all active collectibles. Default
+ *                                 is true.
  */
 export function getPlayerInventory(
   player: EntityPlayer,
@@ -139,3 +153,18 @@ export function getPlayerInventory(
     (collectibleType) => !isActiveCollectible(collectibleType),
   );
 }
+
+/**
+ * Helper function to get the last passive collectible that the player picked up. In most cases,
+ * this will be the passive that is removed when the player would use Clicker.
+ *
+ * Returns undefined if the player does not have any passive collectibles.
+ */
+export function getPlayerLastPassiveCollectible(
+  player: EntityPlayer,
+): CollectibleType | undefined {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  const inventory = getPlayerInventory(player, false);
+  return getLastElement(inventory);
+}

package/src/functions/bosses.ts

@@ -5,6 +5,7 @@ import {
 } from "isaac-typescript-definitions";
 import { VectorZero } from "../core/constants";
 import {
+  ALL_BOSSES_EXCLUDING_STORY_BOSSES_SET,
   ALL_BOSSES_SET,
   STAGE_TO_COMBINED_BOSS_SET_MAP,
   STAGE_TO_STAGE_TYPE_TO_BOSS_SET_MAP,
@@ -13,7 +14,6 @@ import { SIN_ENTITY_TYPES_SET } from "../sets/sinEntityTypesSet";
 import { getNPCs, spawnNPC } from "./entitiesSpecific";
 import { getAliveNPCs } from "./npcs";
 import { isRNG } from "./rng";
-import { copySet } from "./set";
 import { asNumber } from "./types";
 import { repeat } from "./utils";
 
@@ -56,10 +56,20 @@ export function getAliveBosses(
  *
  * The set contains strings with the entity type and variant, separated by a period.
  *
+ * Note that this set does not include bosses that do not appear in Boss Rooms (e.g. Krampus, Uriel,
+ * and Gabriel.).
+ *
  * Also see the `getBossSet` and `getCombinedBossSet` functions.
+ *
+ * @param includeStoryBosses Optional. Whether to include "story" bosses like Mom and It Lives!
+ *                           Default is true.
  */
-export function getAllBossesSet(): Set<string> {
-  return copySet(ALL_BOSSES_SET);
+export function getAllBossesSet(
+  includeStoryBosses = true,
+): ReadonlySet<string> {
+  return includeStoryBosses
+    ? ALL_BOSSES_SET
+    : ALL_BOSSES_EXCLUDING_STORY_BOSSES_SET;
 }
 
 /**
@@ -84,7 +94,7 @@ export function getBossSet(
     return undefined;
   }
 
-  return copySet(bossSet);
+  return bossSet;
 }
 
 /**
@@ -117,13 +127,15 @@ export function getBosses(
  *
  * Also see the `getAllBossesSet` and `getBossSet` functions.
  */
-export function getCombinedBossSet(stage: int): Set<string> | undefined {
+export function getCombinedBossSet(
+  stage: int,
+): ReadonlySet<string> | undefined {
   const bossSet = STAGE_TO_COMBINED_BOSS_SET_MAP.get(stage);
   if (bossSet === undefined) {
     return undefined;
   }
 
-  return copySet(bossSet);
+  return bossSet;
 }
 
 /** Helper function to check if the provided NPC is a Sin miniboss, such as Sloth or Lust. */

package/src/functions/collectibleCacheFlag.ts

@@ -3,7 +3,7 @@ import { itemConfig } from "../core/cachedClasses";
 import { getCollectibleArray } from "./collectibleSet";
 import { getEnumValues } from "./enums";
 import { hasFlag } from "./flag";
-import { copySet, getSortedSetValues } from "./set";
+import { getSortedSetValues } from "./set";
 import { repeat } from "./utils";
 
 const CACHE_FLAG_TO_COLLECTIBLES_MAP = new Map<
@@ -51,7 +51,7 @@ export function collectibleHasCacheFlag(
  */
 export function getCollectiblesForCacheFlag(
   cacheFlag: CacheFlag,
-): Set<CollectibleType> {
+): ReadonlySet<CollectibleType> {
   lazyInitCacheFlagMap();
 
   const collectiblesSet = CACHE_FLAG_TO_COLLECTIBLES_MAP.get(cacheFlag);
@@ -59,7 +59,7 @@ export function getCollectiblesForCacheFlag(
     return new Set();
   }
 
-  return copySet(collectiblesSet);
+  return collectiblesSet;
 }
 
 /**

package/src/functions/collectibleSet.ts

@@ -3,17 +3,17 @@ import { itemConfig } from "../core/cachedClasses";
 import { getModdedCollectibleTypes } from "../features/firstLast";
 import { getVanillaCollectibleTypeRange } from "./collectibles";
 
-const ALL_COLLECTIBLES_ARRAY: CollectibleType[] = [];
-const ALL_COLLECTIBLES_SET = new Set<CollectibleType>();
+const ALL_COLLECTIBLE_TYPES_ARRAY: CollectibleType[] = [];
+const ALL_COLLECTIBLE_TYPES_SET = new Set<CollectibleType>();
 
-const VANILLA_COLLECTIBLES_ARRAY: CollectibleType[] = [];
-const VANILLA_COLLECTIBLES_SET = new Set<CollectibleType>();
+const VANILLA_COLLECTIBLE_TYPES_ARRAY: CollectibleType[] = [];
+const VANILLA_COLLECTIBLE_TYPES_SET = new Set<CollectibleType>();
 
-const MODDED_COLLECTIBLES_ARRAY: CollectibleType[] = [];
-const MODDED_COLLECTIBLES_SET = new Set<CollectibleType>();
+const MODDED_COLLECTIBLE_TYPES_ARRAY: CollectibleType[] = [];
+const MODDED_COLLECTIBLE_TYPES_SET = new Set<CollectibleType>();
 
-function lazyInitVanillaCollectibles() {
-  if (VANILLA_COLLECTIBLES_ARRAY.length > 0) {
+function lazyInitVanillaCollectibleTypes() {
+  if (VANILLA_COLLECTIBLE_TYPES_ARRAY.length > 0) {
     return;
   }
 
@@ -22,22 +22,22 @@ function lazyInitVanillaCollectibles() {
     // Vanilla collectible types are not contiguous, so we must check every value.
     const itemConfigItem = itemConfig.GetCollectible(collectibleType);
     if (itemConfigItem !== undefined) {
-      VANILLA_COLLECTIBLES_ARRAY.push(collectibleType);
-      VANILLA_COLLECTIBLES_SET.add(collectibleType);
+      VANILLA_COLLECTIBLE_TYPES_ARRAY.push(collectibleType);
+      VANILLA_COLLECTIBLE_TYPES_SET.add(collectibleType);
     }
   }
 }
 
-function lazyInitModdedCollectibles() {
-  if (MODDED_COLLECTIBLES_ARRAY.length > 0) {
+function lazyInitModdedCollectibleTypes() {
+  if (MODDED_COLLECTIBLE_TYPES_ARRAY.length > 0) {
     return;
   }
 
-  lazyInitVanillaCollectibles();
+  lazyInitVanillaCollectibleTypes();
 
-  for (const collectibleType of VANILLA_COLLECTIBLES_ARRAY) {
-    ALL_COLLECTIBLES_ARRAY.push(collectibleType);
-    ALL_COLLECTIBLES_SET.add(collectibleType);
+  for (const collectibleType of VANILLA_COLLECTIBLE_TYPES_ARRAY) {
+    ALL_COLLECTIBLE_TYPES_ARRAY.push(collectibleType);
+    ALL_COLLECTIBLE_TYPES_SET.add(collectibleType);
   }
 
   const moddedCollectibleTypes = getModdedCollectibleTypes();
@@ -45,11 +45,11 @@ function lazyInitModdedCollectibles() {
     // Modded collectible types are contiguous, but we check every value just in case.
     const itemConfigItem = itemConfig.GetCollectible(collectibleType);
     if (itemConfigItem !== undefined) {
-      MODDED_COLLECTIBLES_ARRAY.push(collectibleType);
-      MODDED_COLLECTIBLES_SET.add(collectibleType);
+      MODDED_COLLECTIBLE_TYPES_ARRAY.push(collectibleType);
+      MODDED_COLLECTIBLE_TYPES_SET.add(collectibleType);
 
-      ALL_COLLECTIBLES_ARRAY.push(collectibleType);
-      ALL_COLLECTIBLES_SET.add(collectibleType);
+      ALL_COLLECTIBLE_TYPES_ARRAY.push(collectibleType);
+      ALL_COLLECTIBLE_TYPES_SET.add(collectibleType);
     }
   }
 }
@@ -65,8 +65,8 @@ function lazyInitModdedCollectibles() {
  * all collectibles will necessarily be present when a mod first loads (due to mod load order).
  */
 export function getCollectibleArray(): readonly CollectibleType[] {
-  lazyInitModdedCollectibles();
-  return ALL_COLLECTIBLES_ARRAY;
+  lazyInitModdedCollectibleTypes();
+  return ALL_COLLECTIBLE_TYPES_ARRAY;
 }
 
 /**
@@ -79,8 +79,8 @@ export function getCollectibleArray(): readonly CollectibleType[] {
  * all collectibles will necessarily be present when a mod first loads (due to mod load order).
  */
 export function getCollectibleSet(): ReadonlySet<CollectibleType> {
-  lazyInitModdedCollectibles();
-  return ALL_COLLECTIBLES_SET;
+  lazyInitModdedCollectibleTypes();
+  return ALL_COLLECTIBLE_TYPES_SET;
 }
 
 /**
@@ -93,8 +93,8 @@ export function getCollectibleSet(): ReadonlySet<CollectibleType> {
  * all collectibles will necessarily be present when a mod first loads (due to mod load order).
  */
 export function getModdedCollectibleArray(): readonly CollectibleType[] {
-  lazyInitModdedCollectibles();
-  return MODDED_COLLECTIBLES_ARRAY;
+  lazyInitModdedCollectibleTypes();
+  return MODDED_COLLECTIBLE_TYPES_ARRAY;
 }
 
 /**
@@ -107,8 +107,8 @@ export function getModdedCollectibleArray(): readonly CollectibleType[] {
  * all collectibles will necessarily be present when a mod first loads (due to mod load order).
  */
 export function getModdedCollectibleSet(): ReadonlySet<CollectibleType> {
-  lazyInitModdedCollectibles();
-  return MODDED_COLLECTIBLES_SET;
+  lazyInitModdedCollectibleTypes();
+  return MODDED_COLLECTIBLE_TYPES_SET;
 }
 
 /**
@@ -118,8 +118,8 @@ export function getModdedCollectibleSet(): ReadonlySet<CollectibleType> {
  * then use the `getVanillaCollectibleSet` helper function instead.
  */
 export function getVanillaCollectibleArray(): readonly CollectibleType[] {
-  lazyInitVanillaCollectibles();
-  return VANILLA_COLLECTIBLES_ARRAY;
+  lazyInitVanillaCollectibleTypes();
+  return VANILLA_COLLECTIBLE_TYPES_ARRAY;
 }
 
 /**
@@ -129,6 +129,6 @@ export function getVanillaCollectibleArray(): readonly CollectibleType[] {
  * then use the `getVanillaCollectibleArray` helper function instead.
  */
 export function getVanillaCollectibleSet(): ReadonlySet<CollectibleType> {
-  lazyInitVanillaCollectibles();
-  return VANILLA_COLLECTIBLES_SET;
+  lazyInitVanillaCollectibleTypes();
+  return VANILLA_COLLECTIBLE_TYPES_SET;
 }

package/src/functions/collectibleTag.ts

@@ -4,7 +4,6 @@ import { getCollectibleArray } from "./collectibleSet";
 import { getEnumValues } from "./enums";
 import { getFlagName } from "./flag";
 import { getPlayerCollectibleCount } from "./players";
-import { copySet } from "./set";
 
 const TAG_TO_COLLECTIBLE_TYPES_MAP = new Map<
   ItemConfigTag,
@@ -59,7 +58,7 @@ export function collectibleHasTag(
  */
 export function getCollectibleTypesWithTag(
   itemConfigTag: ItemConfigTag,
-): Set<CollectibleType> {
+): ReadonlySet<CollectibleType> {
   // Lazy initialize the map.
   if (TAG_TO_COLLECTIBLE_TYPES_MAP.size === 0) {
     initTagMap();
@@ -72,7 +71,7 @@ export function getCollectibleTypesWithTag(
     );
   }
 
-  return copySet(collectibleTypes);
+  return collectibleTypes;
 }
 
 /** Returns the number of items that a player has towards a particular transformation. */

package/src/functions/collectibles.ts

@@ -31,6 +31,7 @@ import { getRoomListIndex } from "./roomData";
 import { clearSprite, spriteEquals } from "./sprites";
 import { irange } from "./utils";
 
+const COLLECTIBLE_ANM2_PATH = "gfx/005.100_collectible.anm2";
 const COLLECTIBLE_SPRITE_LAYER = 1;
 const COLLECTIBLE_SHADOW_LAYER = 4;
 
@@ -159,8 +160,12 @@ export function getCollectibleDevilHeartPrice(
 }
 
 /**
- * Helper function to get the path to a collectible's sprite. Returns the path to the question mark
+ * Helper function to get the path to a collectible PNG file. Returns the path to the question mark
  * sprite (i.e. from Curse of the Blind) if the provided collectible type was not valid.
+ *
+ * Note that this does not return the file name, but the full path to the collectible's PNG file.
+ * The function is named "GfxFilename" to correspond to the associated `ItemConfigItem.GfxFileName`
+ * field.
  */
 export function getCollectibleGfxFilename(
   collectibleType: CollectibleType,
@@ -469,6 +474,25 @@ export function isVanillaCollectibleType(
   return collectibleType <= LAST_VANILLA_COLLECTIBLE_TYPE;
 }
 
+/**
+ * Helper function to generate a new sprite based on a collectible. If the provided collectible type
+ * is invalid, a sprite with a Curse of the Blind question mark will be returned.
+ */
+export function newCollectibleSprite(collectibleType: CollectibleType): Sprite {
+  const sprite = Sprite();
+  sprite.Load(COLLECTIBLE_ANM2_PATH, false);
+
+  // We want to clear the pedestal layers so that the returned sprite only has the collectible
+  // image.
+  clearSprite(sprite);
+
+  const gfxFileName = getCollectibleGfxFilename(collectibleType);
+  sprite.ReplaceSpritesheet(COLLECTIBLE_SPRITE_LAYER, gfxFileName);
+  sprite.LoadGraphics();
+
+  return sprite;
+}
+
 /**
  * Helper function to put a message in the log.txt file to let the Rebirth Item Tracker know that it
  * should remove an item.

package/src/functions/eden.ts

@@ -3,7 +3,7 @@ import { isHiddenCollectible, isPassiveCollectible } from "./collectibles";
 import { getCollectibleArray } from "./collectibleSet";
 import { collectibleHasTag } from "./collectibleTag";
 import { getRandomSeed } from "./rng";
-import { copySet, getRandomSetElement } from "./set";
+import { getRandomSetElement } from "./set";
 
 const EDEN_PASSIVE_COLLECTIBLES_SET = new Set<CollectibleType>();
 
@@ -19,13 +19,13 @@ function initCollectibleSet() {
   }
 }
 
-export function getEdenPassives(): Set<CollectibleType> {
+export function getEdenPassives(): ReadonlySet<CollectibleType> {
   // Lazy initialize the set.
   if (EDEN_PASSIVE_COLLECTIBLES_SET.size === 0) {
     initCollectibleSet();
   }
 
-  return copySet(EDEN_PASSIVE_COLLECTIBLES_SET);
+  return EDEN_PASSIVE_COLLECTIBLES_SET;
 }
 
 export function getRandomEdenPassive(

package/src/functions/flying.ts

@@ -47,11 +47,11 @@ const CONDITIONAL_FLYING_COLLECTIBLE_TYPES: readonly CollectibleType[] = [
  */
 export function getFlyingCollectibles(
   pruneConditionalItems: boolean,
-): Set<CollectibleType> {
+): ReadonlySet<CollectibleType> {
   // Instead of manually compiling a list of collectibles that grant flying, we can instead
   // dynamically look for collectibles that have `CacheFlag.FLYING`.
-  const collectiblesWithFlyingCacheFlag = getCollectiblesForCacheFlag(
-    CacheFlag.FLYING,
+  const collectiblesWithFlyingCacheFlag = copySet(
+    getCollectiblesForCacheFlag(CacheFlag.FLYING),
   );
 
   // None of the collectibles with a cache of "all" grant flying, so we can safely remove them from
@@ -80,7 +80,7 @@ export function getFlyingCollectibles(
 export function getFlyingTrinkets(): ReadonlySet<TrinketType> {
   // We use a different algorithm than the "getFlyingCollectibles" function because Azazel's Stump
   // has a cache of "all".
-  return copySet(FLYING_TRINKETS);
+  return FLYING_TRINKETS;
 }
 
 export function hasFlyingTemporaryEffect(player: EntityPlayer): boolean {

package/src/functions/input.ts

@@ -6,7 +6,6 @@ import {
 } from "isaac-typescript-definitions";
 import { KEYBOARD_TO_STRING } from "../maps/keyboardToString";
 import { getEnumValues } from "./enums";
-import { copySet } from "./set";
 import { trimPrefix } from "./string";
 
 const MODIFIER_KEYS: readonly Keyboard[] = [
@@ -52,12 +51,12 @@ export function controllerToString(controller: Controller): string | undefined {
   return trimPrefix(key, "BUTTON_");
 }
 
-export function getMoveActions(): Set<ButtonAction> {
-  return copySet(MOVEMENT_ACTIONS_SET);
+export function getMoveActions(): ReadonlySet<ButtonAction> {
+  return MOVEMENT_ACTIONS_SET;
 }
 
-export function getShootActions(): Set<ButtonAction> {
-  return copySet(SHOOTING_ACTIONS_SET);
+export function getShootActions(): ReadonlySet<ButtonAction> {
+  return SHOOTING_ACTIONS_SET;
 }
 
 /** Iterates over all inputs to determine if a particular button is pressed (i.e. held down). */