isaacscript-common 6.6.4 → 6.7.1

package/src/functions/gridEntitiesSpecific.ts

@@ -0,0 +1,490 @@
+import {
+  DoorVariant,
+  GridEntityType,
+  PitVariant,
+  PoopGridEntityVariant,
+  PressurePlateVariant,
+  RockVariant,
+} from "isaac-typescript-definitions";
+import {
+  getGridEntities,
+  removeGridEntities,
+  spawnGridEntityWithVariant,
+} from "./gridEntities";
+
+// The `getDoors` function is not located here because doors are collected via the `Room.GetDoor`
+// method instead, which is faster.
+
+/**
+ * Helper function to get all of the `GridEntityPit` in the room.
+ *
+ * @param pitVariant Optional. If specified, will only get the pits that match the variant. Default
+ *                   is -1, which matches every variant.
+ */
+export function getPits(pitVariant: PitVariant = -1): GridEntityPit[] {
+  const gridEntities = getGridEntities();
+
+  const pits: GridEntityPit[] = [];
+  for (const gridEntity of gridEntities) {
+    const pit = gridEntity.ToPit();
+    if (pit !== undefined) {
+      const gridEntityVariant = pit.GetVariant();
+      if ((pitVariant as int) === -1 || pitVariant === gridEntityVariant) {
+        pits.push(pit);
+      }
+    }
+  }
+
+  return pits;
+}
+
+/**
+ * Helper function to get all of the `GridEntityPoop` in the room.
+ *
+ * @param poopVariant Optional. If specified, will only get the poops that match the variant.
+ *                    Default is -1, which matches every variant.
+ */
+export function getPoops(
+  poopVariant: PoopGridEntityVariant = -1,
+): GridEntityPoop[] {
+  const gridEntities = getGridEntities();
+
+  const poops: GridEntityPoop[] = [];
+  for (const gridEntity of gridEntities) {
+    const poop = gridEntity.ToPoop();
+    if (poop !== undefined) {
+      const gridEntityVariant = poop.GetVariant();
+      if ((poopVariant as int) === -1 || poopVariant === gridEntityVariant) {
+        poops.push(poop);
+      }
+    }
+  }
+
+  return poops;
+}
+
+/**
+ * Helper function to get all of the `GridEntityPressurePlate` in the room.
+ *
+ * @param pressurePlateVariant Optional. If specified, will only get the pressure plates that match
+ *                             the variant. Default is -1, which matches every variant.
+ */
+export function getPressurePlates(
+  pressurePlateVariant: PressurePlateVariant = -1,
+): GridEntityPressurePlate[] {
+  const gridEntities = getGridEntities();
+
+  const pressurePlates: GridEntityPressurePlate[] = [];
+  for (const gridEntity of gridEntities) {
+    const pressurePlate = gridEntity.ToPressurePlate();
+    if (pressurePlate !== undefined) {
+      const gridEntityVariant = pressurePlate.GetVariant();
+      if (
+        (pressurePlateVariant as int) === -1 ||
+        pressurePlateVariant === gridEntityVariant
+      ) {
+        pressurePlates.push(pressurePlate);
+      }
+    }
+  }
+
+  return pressurePlates;
+}
+
+/**
+ * Helper function to get all of the `GridEntityRock` in the room.
+ *
+ * @param variant Optional. If specified, will only get the rocks that match the variant. Default is
+ *                -1, which matches every variant. Note that this is not the same thing as the
+ *                `RockVariant` enum, since that only applies to `GridEntityType.ROCK`, and other
+ *                types of grid entities can be the `GridEntityRock` class.
+ */
+export function getRocks(variant = -1): GridEntityRock[] {
+  const gridEntities = getGridEntities();
+
+  const rocks: GridEntityRock[] = [];
+  for (const gridEntity of gridEntities) {
+    const rock = gridEntity.ToRock();
+    if (rock !== undefined) {
+      const gridEntityVariant = rock.GetVariant();
+      if (variant === -1 || variant === gridEntityVariant) {
+        rocks.push(rock);
+      }
+    }
+  }
+
+  return rocks;
+}
+
+/** Helper function to get all of the `GridEntitySpikes` in the room. */
+export function getSpikes(variant = -1): GridEntitySpikes[] {
+  const gridEntities = getGridEntities();
+
+  const spikes: GridEntitySpikes[] = [];
+  for (const gridEntity of gridEntities) {
+    const spike = gridEntity.ToSpikes();
+    if (spike !== undefined) {
+      const gridEntityVariant = spike.GetVariant();
+      if (variant === -1 || variant === gridEntityVariant) {
+        spikes.push(spike);
+      }
+    }
+  }
+
+  return spikes;
+}
+
+/** Helper function to get all of the `GridEntityTNT` in the room. */
+export function getTNT(variant = -1): GridEntityTNT[] {
+  const gridEntities = getGridEntities();
+
+  const tntArray: GridEntityTNT[] = [];
+  for (const gridEntity of gridEntities) {
+    const tnt = gridEntity.ToTNT();
+    if (tnt !== undefined) {
+      const gridEntityVariant = tnt.GetVariant();
+      if (variant === -1 || variant === gridEntityVariant) {
+        tntArray.push(tnt);
+      }
+    }
+  }
+
+  return tntArray;
+}
+
+// The `removeAllDoors` function is not located here because doors are removed via the
+// `Room.RemoveDoor` method instead.
+
+/**
+ * Helper function to remove all of the `GridEntityPit` in the room.
+ *
+ * @param pitVariant Optional. If specified, will only remove the pits that match this variant.
+ *                   Default is -1, which matches every variant.
+ * @param updateRoom Optional. Whether or not to update the room after the pits are removed. Default
+ *                   is false. For more information, see the description of the `removeGridEntities`
+ *                   helper function.
+ * @param cap Optional. If specified, will only remove the given amount of pits.
+ * @returns The pits that were removed.
+ */
+export function removeAllPits(
+  pitVariant: PitVariant = -1,
+  updateRoom = false,
+  cap?: int,
+): GridEntityPit[] {
+  const pits = getPits(pitVariant);
+  return removeGridEntities(pits, updateRoom, cap);
+}
+
+/**
+ * Helper function to remove all of the `GridEntityPoop` in the room.
+ *
+ * Note that poops can either be an entity or a grid entity, depending on the situation. This
+ * function will only remove the grid entity poops.
+ *
+ * @param poopVariant Optional. If specified, will only remove the poops that match this variant.
+ *                    Default is -1, which matches every variant.
+ * @param updateRoom Optional. Whether or not to update the room after the poops are removed.
+ *                   Default is false. For more information, see the description of the
+ *                   `removeGridEntities` helper function.
+ * @param cap Optional. If specified, will only remove the given amount of poops.
+ * @returns The poops that were removed.
+ */
+export function removeAllPoops(
+  poopVariant: PoopGridEntityVariant = -1,
+  updateRoom = false,
+  cap?: int,
+): GridEntityPoop[] {
+  const poops = getPoops(poopVariant);
+  return removeGridEntities(poops, updateRoom, cap);
+}
+
+/**
+ * Helper function to remove all of the `GridEntityPressurePlate` in the room.
+ *
+ * @param pressurePlateVariant Optional. If specified, will only remove the pressure plates that
+ *                             match this variant. Default is -1, which matches every variant.
+ * @param updateRoom Optional. Whether or not to update the room after the pressure plates are
+ *                   removed. Default is false. For more information, see the description of the
+ *                   `removeGridEntities` helper function.
+ * @param cap Optional. If specified, will only remove the given amount of pressure plates.
+ * @returns The pressure plates that were removed.
+ */
+export function removeAllPressurePlates(
+  pressurePlateVariant: PressurePlateVariant = -1,
+  updateRoom = false,
+  cap?: int,
+): GridEntityPressurePlate[] {
+  const pressurePlates = getPressurePlates(pressurePlateVariant);
+  return removeGridEntities(pressurePlates, updateRoom, cap);
+}
+
+/**
+ * Helper function to remove all of the `GridEntityRock` in the room.
+ *
+ * @param variant Optional. If specified, will only remove the rocks that match this variant.
+ *                Default is -1, which matches every variant. Note that this is not the same thing
+ *                as the `RockVariant` enum, since that only applies to `GridEntityType.ROCK`, and
+ *                other types of grid entities can be the `GridEntityRock` class.
+ * @param updateRoom Optional. Whether or not to update the room after the rocks are removed.
+ *                   Default is false. For more information, see the description of the
+ *                   `removeGridEntities` helper function.
+ * @param cap Optional. If specified, will only remove the given amount of rocks.
+ * @returns The rocks that were removed.
+ */
+export function removeAllRocks(
+  variant = -1,
+  updateRoom = false,
+  cap?: int,
+): GridEntityRock[] {
+  const rocks = getRocks(variant);
+  return removeGridEntities(rocks, updateRoom, cap);
+}
+
+/**
+ * Helper function to remove all of the `GridEntitySpikes` in the room.
+ *
+ * @param variant Optional. If specified, will only remove the spikes that match this variant.
+ *                Default is -1, which matches every variant.
+ * @param updateRoom Optional. Whether or not to update the room after the spikes are removed.
+ *                   Default is false. For more information, see the description of the
+ *                   `removeGridEntities` helper function.
+ * @param cap Optional. If specified, will only remove the given amount of spikes.
+ * @returns The spikes that were removed.
+ */
+export function removeAllSpikes(
+  variant = -1,
+  updateRoom = false,
+  cap?: int,
+): GridEntitySpikes[] {
+  const spikes = getSpikes(variant);
+  return removeGridEntities(spikes, updateRoom, cap);
+}
+
+/**
+ * Helper function to remove all of the `GridEntityTNT` in the room.
+ *
+ * @param variant Optional. If specified, will only remove the TNTs that match this variant. Default
+ *                is -1, which matches every variant.
+ * @param updateRoom Optional. Whether or not to update the room after the TNTs are removed. Default
+ *                   is false. For more information, see the description of the `removeGridEntities`
+ *                   helper function.
+ * @param cap Optional. If specified, will only remove the given amount of TNTs.
+ * @returns The TNTs that were removed.
+ */
+export function removeAllTNT(
+  variant = -1,
+  updateRoom = false,
+  cap?: int,
+): GridEntityTNT[] {
+  const tnt = getTNT(variant);
+  return removeGridEntities(tnt, updateRoom, cap);
+}
+
+/** Helper function to spawn a `GridEntityType.DOOR` (16). */
+export function spawnDoor(
+  gridIndexOrPosition: int | Vector,
+): GridEntityDoor | undefined {
+  return spawnDoorWithVariant(DoorVariant.UNSPECIFIED, gridIndexOrPosition);
+}
+
+/** Helper function to spawn a `GridEntityType.DOOR` (16) with a specific variant. */
+export function spawnDoorWithVariant(
+  doorVariant: DoorVariant,
+  gridIndexOrPosition: int | Vector,
+): GridEntityDoor | undefined {
+  const gridEntity = spawnGridEntityWithVariant(
+    GridEntityType.DOOR,
+    doorVariant,
+    gridIndexOrPosition,
+  );
+  if (gridEntity === undefined) {
+    return gridEntity;
+  }
+
+  const door = gridEntity.ToDoor();
+  if (door === undefined) {
+    error("Failed to spawn a door.");
+  }
+
+  return door;
+}
+
+/** Helper function to spawn a `GridEntityType.PIT` (7). */
+export function spawnPit(
+  gridIndexOrPosition: int | Vector,
+): GridEntityPit | undefined {
+  return spawnPitWithVariant(PitVariant.NORMAL, gridIndexOrPosition);
+}
+
+/** Helper function to spawn a `GridEntityType.PIT` (7) with a specific variant. */
+export function spawnPitWithVariant(
+  pitVariant: PitVariant,
+  gridIndexOrPosition: int | Vector,
+): GridEntityPit | undefined {
+  const gridEntity = spawnGridEntityWithVariant(
+    GridEntityType.PIT,
+    pitVariant,
+    gridIndexOrPosition,
+  );
+  if (gridEntity === undefined) {
+    return gridEntity;
+  }
+
+  const pit = gridEntity.ToPit();
+  if (pit === undefined) {
+    error("Failed to spawn a pit.");
+  }
+
+  return pit;
+}
+
+/** Helper function to spawn a `GridEntityType.POOP` (14). */
+export function spawnPoop(
+  gridIndexOrPosition: int | Vector,
+): GridEntityPoop | undefined {
+  return spawnPoopWithVariant(
+    PoopGridEntityVariant.NORMAL,
+    gridIndexOrPosition,
+  );
+}
+
+/** Helper function to spawn a `GridEntityType.POOP` (14) with a specific variant. */
+export function spawnPoopWithVariant(
+  poopVariant: PoopGridEntityVariant,
+  gridIndexOrPosition: int | Vector,
+): GridEntityPoop | undefined {
+  const gridEntity = spawnGridEntityWithVariant(
+    GridEntityType.POOP,
+    poopVariant,
+    gridIndexOrPosition,
+  );
+  if (gridEntity === undefined) {
+    return gridEntity;
+  }
+
+  const poop = gridEntity.ToPoop();
+  if (poop === undefined) {
+    error("Failed to spawn a poop.");
+  }
+
+  return poop;
+}
+
+/** Helper function to spawn a `GridEntityType.PRESSURE_PLATE` (20). */
+export function spawnPressurePlate(
+  gridIndexOrPosition: int | Vector,
+): GridEntityPressurePlate | undefined {
+  return spawnPressurePlateWithVariant(
+    PressurePlateVariant.PRESSURE_PLATE,
+    gridIndexOrPosition,
+  );
+}
+
+/** Helper function to spawn a `GridEntityType.PRESSURE_PLATE` (20) with a specific variant. */
+export function spawnPressurePlateWithVariant(
+  pressurePlateVariant: PressurePlateVariant,
+  gridIndexOrPosition: int | Vector,
+): GridEntityPressurePlate | undefined {
+  const gridEntity = spawnGridEntityWithVariant(
+    GridEntityType.PRESSURE_PLATE,
+    pressurePlateVariant,
+    gridIndexOrPosition,
+  );
+  if (gridEntity === undefined) {
+    return gridEntity;
+  }
+
+  const pressurePlate = gridEntity.ToPressurePlate();
+  if (pressurePlate === undefined) {
+    error("Failed to spawn a pressure plate.");
+  }
+
+  return pressurePlate;
+}
+
+/** Helper function to spawn a `GridEntityType.ROCK` (2). */
+export function spawnRock(
+  gridIndexOrPosition: int | Vector,
+): GridEntityRock | undefined {
+  return spawnRockWithVariant(RockVariant.NORMAL, gridIndexOrPosition);
+}
+
+/** Helper function to spawn a `GridEntityType.ROCK` (2) with a specific variant. */
+export function spawnRockWithVariant(
+  rockVariant: RockVariant,
+  gridIndexOrPosition: int | Vector,
+): GridEntityRock | undefined {
+  const gridEntity = spawnGridEntityWithVariant(
+    GridEntityType.ROCK,
+    rockVariant,
+    gridIndexOrPosition,
+  );
+  if (gridEntity === undefined) {
+    return gridEntity;
+  }
+
+  const rock = gridEntity.ToRock();
+  if (rock === undefined) {
+    error("Failed to spawn a rock.");
+  }
+
+  return rock;
+}
+
+/** Helper function to spawn a `GridEntityType.SPIKES` (8). */
+export function spawnSpikes(
+  gridIndexOrPosition: int | Vector,
+): GridEntitySpikes | undefined {
+  return spawnSpikesWithVariant(0, gridIndexOrPosition);
+}
+
+/** Helper function to spawn a `GridEntityType.SPIKES` (8) with a specific variant. */
+export function spawnSpikesWithVariant(
+  variant: int,
+  gridIndexOrPosition: int | Vector,
+): GridEntitySpikes | undefined {
+  const gridEntity = spawnGridEntityWithVariant(
+    GridEntityType.SPIKES,
+    variant,
+    gridIndexOrPosition,
+  );
+  if (gridEntity === undefined) {
+    return gridEntity;
+  }
+
+  const spikes = gridEntity.ToSpikes();
+  if (spikes === undefined) {
+    error("Failed to spawn spikes.");
+  }
+
+  return spikes;
+}
+
+/** Helper function to spawn a `GridEntityType.TNT` (12). */
+export function spawnTNT(
+  gridIndexOrPosition: int | Vector,
+): GridEntityTNT | undefined {
+  return spawnTNTWithVariant(0, gridIndexOrPosition);
+}
+
+/** Helper function to spawn a `GridEntityType.TNT` (12) with a specific variant. */
+export function spawnTNTWithVariant(
+  variant: int,
+  gridIndexOrPosition: int | Vector,
+): GridEntityTNT | undefined {
+  const gridEntity = spawnGridEntityWithVariant(
+    GridEntityType.TNT,
+    variant,
+    gridIndexOrPosition,
+  );
+  if (gridEntity === undefined) {
+    return gridEntity;
+  }
+
+  const tnt = gridEntity.ToTNT();
+  if (tnt === undefined) {
+    error("Failed to spawn TNT.");
+  }
+
+  return tnt;
+}

package/src/functions/log.ts

@@ -16,13 +16,13 @@ import {
 import { game, sfxManager } from "../cachedClasses";
 import { arrayToString } from "./array";
 import { getCollectibleName } from "./collectibles";
-import { getEntities, getEntityID } from "./entity";
+import { getEntities, getEntityID } from "./entities";
 import { getEnumEntries } from "./enums";
 import { hasFlag } from "./flag";
-import { getGridEntities } from "./gridEntity";
+import { getGridEntities } from "./gridEntities";
 import { getIsaacAPIClassName } from "./isaacAPIClass";
-import { getEffectsList, getPlayerName } from "./player";
 import { getPlayerHealth } from "./playerHealth";
+import { getEffectsList, getPlayerName } from "./players";
 import { getRoomData, getRoomGridIndex, getRoomListIndex } from "./roomData";
 import { combineSets, getSortedSetValues } from "./set";
 import { iterateTableInOrder } from "./table";
@@ -228,7 +228,7 @@ export function logEntities(
       msg += `  - CanShutDoors: ${npc.CanShutDoors}\n`;
     }
 
-    numMatchedEntities += 1;
+    numMatchedEntities++;
   });
 
   if (numMatchedEntities === 0) {
@@ -404,7 +404,7 @@ export function logGridEntities(
       msg += `  - TargetRoomType: ${door.TargetRoomType}\n`;
     }
 
-    numMatchedEntities += 1;
+    numMatchedEntities++;
   });
 
   if (numMatchedEntities === 0) {
@@ -572,7 +572,7 @@ export function logSounds(this: void): void {
  * recursively call itself if it counters a table within a table.
  *
  * This function will only work on tables that have string keys (because it logs the keys in order,
- * instead of randomly). It will throw a runtime error if it encounters a non-string key.
+ * instead of randomly). It will throw a run-time error if it encounters a non-string key.
  */
 export function logTable(
   this: void,

package/src/functions/{npc.ts → npcs.ts}

@@ -16,8 +16,8 @@ import {
   VisVariant,
 } from "isaac-typescript-definitions";
 import { EGGY_STATE_FRAME_OF_FINAL_SPIDER } from "../constants";
-import { getFilteredNewEntities } from "./entity";
-import { getNPCs, getProjectiles } from "./entitySpecific";
+import { getFilteredNewEntities } from "./entities";
+import { getNPCs, getProjectiles } from "./entitiesSpecific";
 
 /**
  * Used to filter out certain NPCs when determining of an NPC is "alive" and/or should keep the
@@ -78,19 +78,22 @@ export function fireProjectiles(
  *
  * This function will not include NPCs on an internal blacklist, such as Death's scythes or Big Horn
  * holes.
+ *
+ * @param entityType Optional. If specified, will only get the NPCs that match the type. Default is
+ *                   -1, which matches every type.
+ * @param variant Optional. If specified, will only get the NPCs that match the variant. Default is
+ *                -1, which matches every variant.
+ * @param subType Optional. If specified, will only get the NPCs that match the sub-type. Default is
+ *                -1, which matches every sub-type.
+ * @param ignoreFriendly Optional. Default is false.
  */
 export function getAliveNPCs(
-  matchingEntityType?: EntityType,
-  matchingVariant?: int,
-  matchingSubType?: int,
+  entityType: EntityType = -1,
+  variant = -1,
+  subType = -1,
   ignoreFriendly = false,
 ): EntityNPC[] {
-  const npcs = getNPCs(
-    matchingEntityType,
-    matchingVariant,
-    matchingSubType,
-    ignoreFriendly,
-  );
+  const npcs = getNPCs(entityType, variant, subType, ignoreFriendly);
   return npcs.filter((npc) => !npc.IsDead() && !isAliveExceptionNPC(npc));
 }
 
@@ -146,3 +149,31 @@ 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 invokes 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;
+}