isaacscript-common 6.6.3 → 6.7.0

package/src/functions/{gridEntity.ts → gridEntities.ts}

@@ -1,4 +1,5 @@
 import {
+  CrawlSpaceVariant,
   GridCollisionClass,
   GridEntityType,
   GridEntityXMLType,
@@ -16,10 +17,12 @@ import {
   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 { getRandomSeed } from "./rng";
 import { roomUpdateSafe } from "./rooms";
-import { clearSprite } from "./sprite";
+import { clearSprite } from "./sprites";
+import { isNumber } from "./types";
 import { erange } from "./utils";
 import { isVector } from "./vector";
 
@@ -127,6 +130,22 @@ export function getCollidingEntitiesWithGridEntity(
   );
 }
 
+/**
+ * Helper function to get all of the crawl spaces in the room.
+ *
+ * @param crawlSpaceVariant Optional. If specified, will only get the crawl spaces that match the
+ *                          variant. Default is -1, which matches every variant.
+ */
+export function getCrawlSpaces(
+  crawlSpaceVariant: CrawlSpaceVariant = -1,
+): GridEntity[] {
+  if ((crawlSpaceVariant as int) === -1) {
+    return getGridEntities(GridEntityType.CRAWL_SPACE);
+  }
+
+  return getMatchingGridEntities(GridEntityType.CRAWL_SPACE, crawlSpaceVariant);
+}
+
 /**
  * Helper function to get every grid entity in the current room.
  *
@@ -245,6 +264,8 @@ export function getGridEntityIDFromConstituents(
 /**
  * Helper function to get all of the grid entities in the room that specifically match the type and
  * variant provided.
+ *
+ * If you want to match every variant, use the `getGridEntities` function instead.
  */
 export function getMatchingGridEntities(
   gridEntityType: GridEntityType,
@@ -329,6 +350,25 @@ export function getTopLeftWallGridIndex(): int {
     : topLeftWallGridIndex;
 }
 
+/**
+ * Helper function to get all of the grid entities of type `GridEntityType.TRAPDOOR` in the room.
+ * Specify a specific trapdoor variant to select only trapdoors of that variant.
+ */
+export function getTrapdoors(trapdoorVariant?: TrapdoorVariant): GridEntity[] {
+  if (trapdoorVariant === undefined) {
+    return getGridEntities(GridEntityType.TRAPDOOR);
+  }
+
+  return getMatchingGridEntities(GridEntityType.TRAPDOOR, trapdoorVariant);
+}
+
+/**
+ * Helper function to see if the provided gridEntity is in its respective broken state. See the
+ * `GRID_ENTITY_TYPE_TO_BROKEN_STATE_MAP` constant for more details.
+ *
+ * Note that in the case of `GridEntityType.LOCK` (11), the state will turn to being broken before
+ * the actual collision for the entity is removed.
+ */
 export function isGridEntityBreakableByExplosion(
   gridEntity: GridEntity,
 ): boolean {
@@ -345,11 +385,9 @@ export function isGridEntityBreakableByExplosion(
 }
 
 /**
- * Helper function to see if the provided gridEntity is in its respective broken state. See the
- * `GRID_ENTITY_TYPE_TO_BROKEN_STATE_MAP` constant for more details.
- *
- * Note that in the case of `GridEntityType.LOCK` (11), the state will turn to being broken before
- * the actual collision for the entity is removed.
+ * Helper function to detect whether a given Void Portal is one that randomly spawns after a boss is
+ * defeated or is one that naturally spawns in the room after Hush. (This is determined by looking
+ * at the VarData of the entity.)
  */
 export function isGridEntityBroken(gridEntity: GridEntity): boolean {
   const gridEntityType = gridEntity.GetType();
@@ -358,9 +396,8 @@ export function isGridEntityBroken(gridEntity: GridEntity): boolean {
 }
 
 /**
- * Helper function to detect whether a given Void Portal is one that randomly spawns after a boss is
- * defeated or is one that naturally spawns in the room after Hush. (This is determined by looking
- * at the VarData of the entity.)
+ * Helper function to determine if all of the pressure plates in the current room are pushed.
+ * Returns true if there are no pressure plates in the room.
  */
 export function isPostBossVoidPortal(gridEntity: GridEntity): boolean {
   // - The VarData of Void Portals that are spawned after bosses will be equal to 1.
@@ -385,7 +422,7 @@ export function isPostBossVoidPortal(gridEntity: GridEntity): boolean {
  * );
  * ```
  *
- * @returns True if one or more grid entities were removed, false otherwise.
+ * @returns The grid entities that were removed.
  */
 export function removeAllGridExcept(
   ...gridEntityTypes: GridEntityType[]
@@ -396,7 +433,7 @@ export function removeAllGridExcept(
   for (const gridEntity of gridEntities) {
     const gridEntityType = gridEntity.GetType();
     if (!gridEntityTypeExceptions.has(gridEntityType)) {
-      removeGrid(gridEntity, false);
+      removeGridEntity(gridEntity, false);
       removedGridEntities.push(gridEntity);
     }
   }
@@ -436,7 +473,7 @@ export function removeAllMatchingGridEntities(
   }
 
   for (const gridEntity of gridEntities) {
-    removeGrid(gridEntity, false);
+    removeGridEntity(gridEntity, false);
   }
 
   roomUpdateSafe();
@@ -444,24 +481,63 @@ export function removeAllMatchingGridEntities(
 }
 
 /**
- * Helper function to remove a grid entity simply by providing the grid entity object. By default,
- * this will also update the room.
+ * Helper function to remove all of the grid entities in the supplied array.
+ *
+ * @param gridEntities The array of grid entities to remove.
+ * @param updateRoom Whether or not to update the room after the grid entities are removed. This is
+ *                   generally a good idea because if the room is not updated, you will be unable to
+ *                   spawn another grid entity on the same tile until a frame has passed. However,
+ *                   doing this is expensive, since it involves a call to `Isaac.GetRoomEntities`,
+ *                   so set this to false if you need to invoke this function multiple times.
+ * @param cap Optional. If specified, will only remove the given amount of entities.
+ * @returns An array of the entities that were removed.
+ */
+export function removeGridEntities<T extends AnyGridEntity>(
+  gridEntities: T[],
+  updateRoom: boolean,
+  cap?: int,
+): T[] {
+  if (gridEntities.length === 0) {
+    return [];
+  }
+
+  const gridEntitiesRemoved: T[] = [];
+  for (const gridEntity of gridEntities) {
+    removeGridEntity(gridEntity, false);
+
+    gridEntitiesRemoved.push(gridEntity);
+    if (cap !== undefined && gridEntitiesRemoved.length >= cap) {
+      break;
+    }
+  }
+
+  if (updateRoom) {
+    roomUpdateSafe();
+  }
+
+  return gridEntitiesRemoved;
+}
+
+/**
+ * Helper function to remove a grid entity by providing the grid entity object or the grid index
+ * inside of the room.
  *
  * @param gridEntityOrGridIndex The grid entity or grid index to remove.
- * @param updateRoom Optional. Whether or not to update the room after the grid entity is removed.
- *                   Default is true. This is generally a good idea because if the room is not
- *                   updated, you will be unable to spawn another grid entity on the same tile until
- *                   a frame has passed. However, doing this is expensive, since it involves a call
- *                   to `Isaac.GetRoomEntities`, so set it to false if you need to invoke this
- *                   function multiple times.
+ * @param updateRoom Whether or not to update the room after the grid entity is removed. This is
+ *                   generally a good idea because if the room is not updated, you will be unable to
+ *                   spawn another grid entity on the same tile until a frame has passed. However,
+ *                   doing this is expensive, since it involves a call to `Isaac.GetRoomEntities`,
+ *                   so set this to false if you need to invoke this function multiple times.
  */
-export function removeGrid(
-  gridEntityOrGridIndex: GridEntity,
-  updateRoom = true,
+export function removeGridEntity(
+  gridEntityOrGridIndex: GridEntity | int,
+  updateRoom: boolean,
 ): void {
   const room = game.GetRoom();
 
-  const gridIndex = gridEntityOrGridIndex.GetGridIndex();
+  const gridIndex = isNumber(gridEntityOrGridIndex)
+    ? gridEntityOrGridIndex
+    : gridEntityOrGridIndex.GetGridIndex();
   room.RemoveGridEntity(gridIndex, 0, false);
 
   if (updateRoom) {
@@ -492,22 +568,22 @@ export function spawnGiantPoop(topLeftGridIndex: int): void {
   const bottomLeftGridIndex = topLeftGridIndex + gridWidth;
   const bottomRightGridIndex = bottomLeftGridIndex + 1;
 
-  spawnGridWithVariant(
+  spawnGridEntityWithVariant(
     GridEntityType.POOP,
     PoopGridEntityVariant.GIGA_TOP_LEFT,
     topLeftGridIndex,
   );
-  spawnGridWithVariant(
+  spawnGridEntityWithVariant(
     GridEntityType.POOP,
     PoopGridEntityVariant.GIGA_TOP_RIGHT,
     topRightGridIndex,
   );
-  spawnGridWithVariant(
+  spawnGridEntityWithVariant(
     GridEntityType.POOP,
     PoopGridEntityVariant.GIGA_BOTTOM_LEFT,
     bottomLeftGridIndex,
   );
-  spawnGridWithVariant(
+  spawnGridEntityWithVariant(
     GridEntityType.POOP,
     PoopGridEntityVariant.GIGA_BOTTOM_RIGHT,
     bottomRightGridIndex,
@@ -518,18 +594,18 @@ export function spawnGiantPoop(topLeftGridIndex: int): void {
  * Helper function to spawn a grid entity.
  *
  * This function assumes you want to give the grid entity a variant of 0. If you want to specify a
- * variant, use the `spawnGridWithVariant` helper function instead.
+ * variant, use the `spawnGridEntityWithVariant` helper function instead.
  *
  * Use this instead of the `Isaac.GridSpawn` method since it:
  * - handles giving pits collision
  * - removes existing grid entities on the same tile, if any
  * - allows you to specify either the grid index or the position
  */
-export function spawnGrid(
+export function spawnGridEntity(
   gridEntityType: GridEntityType,
   gridIndexOrPosition: int | Vector,
 ): GridEntity | undefined {
-  return spawnGridWithVariant(gridEntityType, 0, gridIndexOrPosition);
+  return spawnGridEntityWithVariant(gridEntityType, 0, gridIndexOrPosition);
 }
 
 /**
@@ -540,7 +616,7 @@ export function spawnGrid(
  * - removes existing grid entities on the same tile, if any
  * - allows you to specify the grid index or the position
  */
-export function spawnGridWithVariant(
+export function spawnGridEntityWithVariant(
   gridEntityType: GridEntityType,
   variant: int,
   gridIndexOrPosition: int | Vector,
@@ -551,7 +627,7 @@ export function spawnGridWithVariant(
     ? room.GetGridEntityFromPos(gridIndexOrPosition)
     : room.GetGridEntity(gridIndexOrPosition);
   if (existingGridEntity !== undefined) {
-    removeGrid(existingGridEntity);
+    removeGridEntity(existingGridEntity, true);
   }
 
   const position = isVector(gridIndexOrPosition)
@@ -634,7 +710,7 @@ export function spawnRockAltReward(
  * with the appropriate variant, as the game does not give it the correct sprite automatically.
  */
 export function spawnVoidPortal(gridIndex: int): GridEntity | undefined {
-  const voidPortal = spawnGridWithVariant(
+  const voidPortal = spawnGridEntityWithVariant(
     GridEntityType.TRAPDOOR,
     TrapdoorVariant.VOID_PORTAL,
     gridIndex,