isaacscript-common 6.14.0 → 6.16.1

package/src/functions/gridEntities.ts

@@ -9,14 +9,12 @@ import {
 } from "isaac-typescript-definitions";
 import { game } from "../cachedClasses";
 import { DISTANCE_OF_GRID_TILE } from "../constants";
-import { RockAltType } from "../enums/RockAltType";
 import { GRID_ENTITY_TYPE_TO_BROKEN_STATE_MAP } from "../maps/gridEntityTypeToBrokenStateMap";
 import { GRID_ENTITY_XML_MAP } from "../maps/gridEntityXMLMap";
 import {
   DEFAULT_TOP_LEFT_WALL_GRID_INDEX,
   ROOM_SHAPE_TO_TOP_LEFT_WALL_GRID_INDEX_MAP,
 } from "../maps/roomShapeToTopLeftWallGridIndexMap";
-import { BACKDROP_TYPE_TO_ROCK_ALT_TYPE } from "../objects/backdropTypeToRockAltType";
 import { AnyGridEntity } from "../types/AnyGridEntity";
 import { isCircleIntersectingRectangle } from "./math";
 import { roomUpdateSafe } from "./rooms";
@@ -276,27 +274,6 @@ export function getMatchingGridEntities(
   );
 }
 
-/**
- * Helper function to get the alternate rock type (i.e. urn, mushroom, etc.) that the current room
- * will have.
- *
- * The rock type is based on the backdrop of the room.
- *
- * For example, if you change the backdrop of the starting room of the run to `BackdropType.CAVES`,
- * and then spawn `GridEntityType.ROCK_ALT`, it will be a mushroom instead of an urn. Additionally,
- * if it is destroyed, it will generate mushroom-appropriate rewards.
- *
- * On the other hand, if an urn is spawned first before the backdrop is changed to
- * `BackdropType.CAVES`, the graphic of the urn will not switch to a mushroom. However, when
- * destroyed, the urn will still generate mushroom-appropriate rewards.
- */
-export function getRockAltType(): RockAltType {
-  const room = game.GetRoom();
-  const backdropType = room.GetBackdropType();
-
-  return BACKDROP_TYPE_TO_ROCK_ALT_TYPE[backdropType];
-}
-
 export function getSurroundingGridEntities(
   gridEntity: GridEntity,
 ): GridEntity[] {

package/src/functions/isaacAPIClass.ts

@@ -1,4 +1,4 @@
-import { IsaacAPIClass } from "../types/private/IsaacAPIClass";
+import { IsaacAPIClass } from "../types/IsaacAPIClass";
 import { trimPrefix } from "./string";
 import { isString, isUserdata } from "./types";
 

package/src/functions/itemPool.ts

@@ -0,0 +1,153 @@
+import {
+  CollectibleType,
+  ItemConfigTag,
+  ItemPoolType,
+  PlayerType,
+  TrinketType,
+} from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { PlayerIndex } from "../types/PlayerIndex";
+import { getCollectibleSet } from "./collectibleSet";
+import { collectibleHasTag } from "./collectibleTag";
+import { mapGetPlayer, mapSetPlayer } from "./playerDataStructures";
+import { getPlayers } from "./playerIndex";
+import { getPlayersOfType } from "./players";
+import { repeat } from "./utils";
+
+const COLLECTIBLES_THAT_AFFECT_ITEM_POOLS: readonly CollectibleType[] = [
+  CollectibleType.CHAOS, // 402
+  CollectibleType.SACRED_ORB, // 691
+  CollectibleType.TMTRAINER, // 721
+];
+
+const TRINKETS_THAT_AFFECT_ITEM_POOLS: readonly TrinketType[] = [
+  TrinketType.NO,
+];
+
+/**
+ * Helper function to see if the given collectible is still present in the given item pool.
+ *
+ * If the collectible is non-offensive, any Tainted Losts will be temporarily changed to Isaac and
+ * then changed back. (This is because Tainted Lost is not able to retrieve non-offensive
+ * collectibles from item pools).
+ */
+export function isCollectibleInItemPool(
+  collectibleType: CollectibleType,
+  itemPoolType: ItemPoolType,
+): boolean {
+  // On Tainted Lost, it is impossible to retrieve non-offensive collectibles from pools, so we
+  // temporarily change the character to Isaac.
+  const taintedLosts = getPlayersOfType(PlayerType.THE_LOST_B);
+  const isOffensive = collectibleHasTag(
+    collectibleType,
+    ItemConfigTag.OFFENSIVE,
+  );
+  let changedPlayerTypes = false;
+  if (!isOffensive) {
+    changedPlayerTypes = true;
+    for (const player of taintedLosts) {
+      player.ChangePlayerType(PlayerType.ISAAC);
+    }
+  }
+
+  const [removedItemsMap, removedTrinketsMap] =
+    removeItemsAndTrinketsThatAffectItemPools();
+
+  // Blacklist every collectible in the game except for the provided collectible.
+  const itemPool = game.GetItemPool();
+  const collectibleSet = getCollectibleSet();
+  for (const collectibleTypeInSet of collectibleSet.values()) {
+    if (collectibleTypeInSet !== collectibleType) {
+      itemPool.AddRoomBlacklist(collectibleTypeInSet);
+    }
+  }
+
+  // Get a collectible from the pool and see if it is the intended collectible. (We can use any
+  // arbitrary value as the seed since it should not influence the result.)
+  const retrievedCollectibleType = itemPool.GetCollectible(
+    itemPoolType,
+    false,
+    1 as Seed,
+  );
+
+  const collectibleUnlocked = retrievedCollectibleType === collectibleType;
+
+  // Reset the blacklist
+  itemPool.ResetRoomBlacklist();
+
+  restoreItemsAndTrinketsThatAffectItemPools(
+    removedItemsMap,
+    removedTrinketsMap,
+  );
+
+  // Change any players back to Tainted Lost, if necessary.
+  if (changedPlayerTypes) {
+    for (const player of taintedLosts) {
+      player.ChangePlayerType(PlayerType.THE_LOST_B);
+    }
+  }
+
+  return collectibleUnlocked;
+}
+
+/**
+ * Before checking the item pools, remove any collectibles or trinkets that would affect the
+ * retrieved collectible types.
+ */
+function removeItemsAndTrinketsThatAffectItemPools(): [
+  removedItemsMap: Map<PlayerIndex, CollectibleType[]>,
+  removedTrinketsMap: Map<PlayerIndex, TrinketType[]>,
+] {
+  const removedItemsMap = new Map<PlayerIndex, CollectibleType[]>();
+  const removedTrinketsMap = new Map<PlayerIndex, TrinketType[]>();
+  for (const player of getPlayers()) {
+    const removedItems: CollectibleType[] = [];
+    for (const itemToRemove of COLLECTIBLES_THAT_AFFECT_ITEM_POOLS) {
+      if (player.HasCollectible(itemToRemove)) {
+        const numCollectibles = player.GetCollectibleNum(itemToRemove);
+        repeat(numCollectibles, () => {
+          player.RemoveCollectible(itemToRemove);
+          removedItems.push(itemToRemove);
+        });
+      }
+    }
+
+    mapSetPlayer(removedItemsMap, player, removedItems);
+
+    const removedTrinkets: TrinketType[] = [];
+    for (const trinketToRemove of TRINKETS_THAT_AFFECT_ITEM_POOLS) {
+      if (player.HasTrinket(trinketToRemove)) {
+        const numTrinkets = player.GetTrinketMultiplier(trinketToRemove);
+        repeat(numTrinkets, () => {
+          player.TryRemoveTrinket(trinketToRemove);
+          removedTrinkets.push(trinketToRemove);
+        });
+      }
+    }
+
+    mapSetPlayer(removedTrinketsMap, player, removedTrinkets);
+  }
+
+  return [removedItemsMap, removedTrinketsMap];
+}
+
+function restoreItemsAndTrinketsThatAffectItemPools(
+  removedItemsMap: Map<PlayerIndex, CollectibleType[]>,
+  removedTrinketsMap: Map<PlayerIndex, TrinketType[]>,
+) {
+  for (const player of getPlayers()) {
+    const removedItems = mapGetPlayer(removedItemsMap, player);
+    if (removedItems !== undefined) {
+      for (const collectibleType of removedItems) {
+        player.AddCollectible(collectibleType, 0, false); // Prevent Chaos from spawning pickups
+      }
+    }
+
+    const removedTrinkets = mapGetPlayer(removedTrinketsMap, player);
+    if (removedTrinkets !== undefined) {
+      for (const trinketType of removedTrinkets) {
+        player.AddTrinket(trinketType, false);
+      }
+    }
+  }
+}

package/src/functions/kColor.ts

@@ -1,103 +1,67 @@
 import { SerializationBrand } from "../enums/private/SerializationBrand";
-import { SerializationType } from "../enums/SerializationType";
 import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
 import { getRandom } from "./random";
 import { getRandomSeed, isRNG, newRNG } from "./rng";
 import { copyValuesToTable, getNumbersFromTable, tableHasKeys } from "./table";
 import { isTable } from "./types";
 
-type SerializedKColor = LuaMap<string, unknown> & {
+export type SerializedKColor = LuaMap<string, unknown> & {
   readonly __serializedKColorBrand: symbol;
 };
 
-interface CopyKColorReturn {
-  [SerializationType.NONE]: KColor;
-  [SerializationType.SERIALIZE]: SerializedKColor;
-  [SerializationType.DESERIALIZE]: KColor;
-}
-
 const KEYS = ["Red", "Green", "Blue", "Alpha"];
 const OBJECT_NAME = "KColor";
 
+/** Helper function to copy a `KColor` Isaac API class. */
+export function copyKColor(kColor: KColor): KColor {
+  if (!isKColor(kColor)) {
+    error(
+      `Failed to copy a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`,
+    );
+  }
+
+  return KColor(kColor.Red, kColor.Green, kColor.Blue, kColor.Alpha);
+}
+
 /**
- * Helper function to copy a `KColor` object.
- *
- * @param kColor The KColor object to copy. In the case of deserialization, this will actually be a
- *               Lua table instead of an instantiated KColor class.
- * @param serializationType Default is `SerializationType.NONE`.
+ * Helper function to convert a `SerializedKColor` object to a normal `KColor` object. (This is used
+ * by the save data manager when reading data from the "save#.dat" file.)
  */
-export function copyKColor<
-  K extends KColor | SerializedKColor,
-  S extends SerializationType,
->(kColor: K, serializationType: S): CopyKColorReturn[S];
-export function copyKColor<K extends KColor | SerializedKColor>(
-  kColor: K,
-): CopyKColorReturn[SerializationType.NONE];
-export function copyKColor(
-  kColor: KColor | SerializedKColor,
-  serializationType = SerializationType.NONE,
-): CopyKColorReturn[keyof CopyKColorReturn] {
-  switch (serializationType) {
-    case SerializationType.NONE: {
-      if (!isKColor(kColor)) {
-        error(
-          `Failed to copy a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`,
-        );
-      }
-
-      return KColor(kColor.Red, kColor.Green, kColor.Blue, kColor.Alpha);
-    }
-
-    case SerializationType.SERIALIZE: {
-      if (!isKColor(kColor)) {
-        error(
-          `Failed to serialize a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`,
-        );
-      }
-
-      const kColorTable = new LuaMap<string, unknown>();
-      copyValuesToTable(kColor, KEYS, kColorTable);
-      kColorTable.set(SerializationBrand.K_COLOR, "");
-      return kColorTable as SerializedKColor;
-    }
-
-    case SerializationType.DESERIALIZE: {
-      if (!isTable(kColor)) {
-        error(
-          `Failed to deserialize a ${OBJECT_NAME} object since the provided object was not a Lua table.`,
-        );
-      }
-
-      const [r, g, b, a] = getNumbersFromTable(
-        kColor as LuaMap<string, unknown>,
-        OBJECT_NAME,
-        ...KEYS,
-      );
-
-      if (r === undefined) {
-        error(
-          `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: r`,
-        );
-      }
-      if (g === undefined) {
-        error(
-          `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: g`,
-        );
-      }
-      if (b === undefined) {
-        error(
-          `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: b`,
-        );
-      }
-      if (a === undefined) {
-        error(
-          `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: a`,
-        );
-      }
-
-      return KColor(r, g, b, a);
-    }
+export function deserializeKColor(kColor: SerializedKColor): KColor {
+  if (!isTable(kColor)) {
+    error(
+      `Failed to deserialize a ${OBJECT_NAME} object since the provided object was not a Lua table.`,
+    );
+  }
+
+  const [r, g, b, a] = getNumbersFromTable(
+    kColor as LuaMap<string, unknown>,
+    OBJECT_NAME,
+    ...KEYS,
+  );
+
+  if (r === undefined) {
+    error(
+      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Red`,
+    );
   }
+  if (g === undefined) {
+    error(
+      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Green`,
+    );
+  }
+  if (b === undefined) {
+    error(
+      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Blue`,
+    );
+  }
+  if (a === undefined) {
+    error(
+      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Alpha`,
+    );
+  }
+
+  return KColor(r, g, b, a);
 }
 
 /**
@@ -144,3 +108,20 @@ export function isSerializedKColor(
 export function kColorEquals(kColor1: KColor, kColor2: KColor): boolean {
   return isaacAPIClassEquals(kColor1, kColor2, KEYS);
 }
+
+/**
+ * Helper function to convert a `KColor` object to a `SerializedKColor` object. (This is used by the
+ * save data manager when writing data from the "save#.dat" file.)
+ */
+export function serializeKColor(kColor: KColor): SerializedKColor {
+  if (!isKColor(kColor)) {
+    error(
+      `Failed to serialize a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`,
+    );
+  }
+
+  const kColorTable = new LuaMap<string, unknown>();
+  copyValuesToTable(kColor, KEYS, kColorTable);
+  kColorTable.set(SerializationBrand.K_COLOR, "");
+  return kColorTable as SerializedKColor;
+}

package/src/functions/mergeTests.ts

@@ -5,7 +5,7 @@ import { deepCopy } from "./deepCopy";
 import { log } from "./log";
 import { isRNG, newRNG } from "./rng";
 import { isSerializedIsaacAPIClass } from "./serialization";
-import { copyVector, isVector } from "./vector";
+import { isVector, serializeVector } from "./vector";
 
 /**
  * Run the suite of tests that prove that the "merge" function works properly. (This function is not
@@ -92,7 +92,7 @@ function oldTableHasSerializedIsaacAPIClass() {
   const y = 60;
   const vector = Vector(x, y);
 
-  const vectorSerialized = copyVector(vector, SerializationType.SERIALIZE);
+  const vectorSerialized = serializeVector(vector);
   if (!isSerializedIsaacAPIClass(vectorSerialized)) {
     error(
       'The "isSerializedIsaacAPIClass" function says that a serialized vector is not serialized.',

package/src/functions/npcs.ts

@@ -11,13 +11,11 @@ import {
   MotherVariant,
   NpcState,
   PeepVariant,
-  ProjectilesMode,
   RaglingVariant,
   VisVariant,
 } from "isaac-typescript-definitions";
 import { EGGY_STATE_FRAME_OF_FINAL_SPIDER } from "../constants";
-import { getFilteredNewEntities } from "./entities";
-import { getNPCs, getProjectiles } from "./entitiesSpecific";
+import { getNPCs } from "./entitiesSpecific";
 
 /**
  * Used to filter out certain NPCs when determining of an NPC is "alive" and/or should keep the
@@ -46,33 +44,6 @@ const NON_ALIVE_NPCS_TYPE_VARIANT_SUBTYPE: ReadonlySet<string> = new Set([
   `${EntityType.MOTHER}.${MotherVariant.MOTHER_1}.${MotherSubType.PHASE_2}`, // 912
 ]);
 
-/**
- * Helper function to make an NPC fire a projectile. Returns the fired projectile. Use this function
- * instead of the `EntityNPC.FireProjectiles` method, since that returns void.
- *
- * @param npc The NPC to fire the projectile from.
- * @param position The staring position of the projectile.
- * @param velocity The starting velocity of the projectile.
- * @param projectilesMode The mode of the projectile. Optional. Default is
- *                        `ProjectilesMode.ONE_PROJECTILE`.
- * @param projectileParams The parameters of the projectile. Optional. Default is
- *                         `ProjectileParams()`.
- * @returns The fired projectile.
- */
-export function fireProjectiles(
-  npc: EntityNPC,
-  position: Vector,
-  velocity: Vector,
-  projectilesMode: ProjectilesMode = ProjectilesMode.ONE_PROJECTILE,
-  projectileParams: ProjectileParams = ProjectileParams(),
-): EntityProjectile[] {
-  const oldProjectiles = getProjectiles(projectileParams.Variant);
-  npc.FireProjectiles(position, velocity, projectilesMode, projectileParams);
-  const newProjectiles = getProjectiles(projectileParams.Variant);
-
-  return getFilteredNewEntities(oldProjectiles, newProjectiles);
-}
-
 /**
  * Helper function to get all of the non-dead NPCs in the room.
  *
@@ -149,31 +120,3 @@ export function isRaglingDeathPatch(npc: EntityNPC): boolean {
     npc.State === NpcState.SPECIAL
   );
 }
-
-/**
- * The base game `EntityNPC.FireProjectiles` method does not return anything, which is a problem in
- * situations where you need to work with the fired projectiles. This function runs that method, and
- * then returns the projectiles that were spawned.
- *
- * @param npc The EntityNPC firing projectiles.
- * @param position The starting position of the projectiles.
- * @param velocity The starting velocity of the projectiles.
- * @param projectilesMode A ProjectilesMode enum value defining how to fire the projectiles.
- * @param projectileParams A ProjectileParams object containing various parameters for the
- *                         projectiles.
- * @returns An array of EntityProjectiles containing all fired projectiles.
- */
-export function npcFireProjectiles(
-  npc: EntityNPC,
-  position: Vector,
-  velocity: Vector,
-  projectilesMode: ProjectilesMode,
-  projectileParams: ProjectileParams,
-): EntityProjectile[] {
-  const oldEntities = getProjectiles();
-  npc.FireProjectiles(position, velocity, projectilesMode, projectileParams);
-  const newEntities = getProjectiles();
-  const filteredNewEntities = getFilteredNewEntities(oldEntities, newEntities);
-
-  return filteredNewEntities;
-}

package/src/functions/projectiles.ts

@@ -0,0 +1,78 @@
+import {
+  EntityFlag,
+  EntityType,
+  ProjectilesMode,
+} from "isaac-typescript-definitions";
+import { getFilteredNewEntities } from "./entities";
+import { getProjectiles, spawnNPC } from "./entitiesSpecific";
+
+/**
+ * Helper function to make an NPC fire one or more projectiles. Returns the fired projectile(s).
+ *
+ * Use this function instead of the `EntityNPC.FireProjectiles` method if you need to modify or
+ * access the `EntityProjectile` objects after they are fired, since this function returns the
+ * objects in an array.
+ *
+ * @param npc The NPC to fire the projectile(s) from. You can also pass undefined if you do not want
+ *            the projectile(s) to come from anything in particular.
+ * @param position The staring position of the projectile(s).
+ * @param velocity The starting velocity of the projectile(s).
+ * @param projectilesMode Optional. The mode of the projectile(s). Default is
+ *                        `ProjectilesMode.ONE_PROJECTILE`.
+ * @param projectileParams Optional. The parameters of the projectile(s). Default is
+ *                         `ProjectileParams()`.
+ * @returns The fired projectile(s).
+ */
+export function fireProjectiles(
+  npc: EntityNPC | undefined,
+  position: Vector,
+  velocity: Vector,
+  projectilesMode: ProjectilesMode = ProjectilesMode.ONE_PROJECTILE,
+  projectileParams: ProjectileParams = ProjectileParams(),
+): EntityProjectile[] {
+  const oldProjectiles = getProjectiles(projectileParams.Variant);
+
+  let spawnedFly = false;
+  if (npc === undefined) {
+    // Since the `EntityNPC.FireProjectiles` method is not static, we arbitrarily spawn a fly.
+    spawnedFly = true;
+    npc = spawnNPC(EntityType.FLY, 0, 0, position);
+    npc.Visible = false;
+    npc.ClearEntityFlags(EntityFlag.APPEAR);
+  }
+
+  npc.FireProjectiles(position, velocity, projectilesMode, projectileParams);
+  const newProjectiles = getProjectiles(projectileParams.Variant);
+
+  if (spawnedFly) {
+    npc.Remove();
+  }
+
+  return getFilteredNewEntities(oldProjectiles, newProjectiles);
+}
+
+/**
+ * Helper function to spawn projectiles in a circle around a position. Under the hood, this
+ * leverages `ProjectileMode.N_PROJECTILES_IN_CIRCLE`.
+ *
+ * @param npc The NPC to fire the projectile(s) from. You can also pass undefined if you do not want
+ *            the projectile(s) to come from anything in particular.
+ * @param position The staring position of the projectile(s).
+ * @param speed The speed of the projectile(s).
+ * @param numProjectiles The amount of projectiles to spawn.
+ * @returns The fired projectile(s).
+ */
+export function fireProjectilesInCircle(
+  npc: EntityNPC | undefined,
+  position: Vector,
+  speed: float,
+  numProjectiles: int,
+): EntityProjectile[] {
+  const velocity = Vector(speed, numProjectiles);
+  return fireProjectiles(
+    npc,
+    position,
+    velocity,
+    ProjectilesMode.N_PROJECTILES_IN_CIRCLE,
+  );
+}