isaacscript-common 6.6.5 → 6.8.0

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, getGridEntityID } 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";
@@ -83,6 +83,106 @@ export function log(this: void, msg: string): void {
   Isaac.DebugString(debugMsg);
 }
 
+/** Helper function for printing out every entity (or filtered entity) in the current room. */
+export function logAllEntities(
+  this: void,
+  includeBackgroundEffects: boolean,
+  entityTypeFilter?: EntityType,
+): void {
+  let msg = "Entities in the room";
+  if (entityTypeFilter !== undefined) {
+    msg += ` (filtered to entity type ${entityTypeFilter})`;
+  } else if (!includeBackgroundEffects) {
+    msg += " (not including background effects)";
+  }
+  msg += ":\n";
+
+  const entities = getEntities();
+  let numMatchedEntities = 0;
+  entities.forEach((entity, i) => {
+    // If a filter was specified, exclude all entities outside of the filter.
+    if (entityTypeFilter !== undefined && entity.Type !== entityTypeFilter) {
+      return;
+    }
+
+    const effect = entity.ToEffect();
+    if (
+      !includeBackgroundEffects &&
+      effect !== undefined &&
+      IGNORE_EFFECT_VARIANTS.has(effect.Variant)
+    ) {
+      return;
+    }
+
+    msg += getEntityLogLine(entity, i + 1);
+    numMatchedEntities++;
+  });
+
+  if (numMatchedEntities === 0) {
+    msg += "(no entities matched)\n";
+  } else {
+    msg += `(${numMatchedEntities} total ${
+      numMatchedEntities === 1 ? "entity" : "entities"
+    })\n`;
+  }
+
+  log(msg);
+}
+
+/**
+ * Helper function for printing out every grid entity (or filtered grid entity) in the current room.
+ */
+export function logAllGridEntities(
+  this: void,
+  includeWalls: boolean,
+  gridEntityTypeFilter?: GridEntityType,
+): void {
+  let msg = "Grid entities in the room";
+  if (gridEntityTypeFilter !== undefined) {
+    msg += ` (filtered to grid entity type ${gridEntityTypeFilter})`;
+  } else if (!includeWalls) {
+    msg += " (not including walls)";
+  }
+  msg += ":\n";
+
+  const gridEntities = getGridEntities();
+  let numMatchedEntities = 0;
+  gridEntities.forEach((gridEntity) => {
+    const gridEntityIndex = gridEntity.GetGridIndex();
+    const gridEntityType = gridEntity.GetType();
+
+    // If a filter was specified, exclude all entities outside of the filter.
+    if (
+      gridEntityTypeFilter !== undefined &&
+      gridEntityType !== gridEntityTypeFilter
+    ) {
+      return;
+    }
+
+    if (
+      !includeWalls &&
+      gridEntityType === GridEntityType.WALL &&
+      gridEntityTypeFilter !== GridEntityType.WALL
+    ) {
+      return;
+    }
+
+    msg += getGridEntityLogLine(gridEntity, gridEntityIndex);
+
+    numMatchedEntities++;
+  });
+
+  if (numMatchedEntities === 0) {
+    msg += "(no grid entities matched)\n";
+  } else {
+    msg += `(${numMatchedEntities} total grid ${
+      numMatchedEntities === 1 ? "entity" : "entities"
+    })\n`;
+  }
+
+  log(msg);
+}
+
 export function logArray<T>(this: void, array: T[] | readonly T[]): void {
   const arrayString = arrayToString(array);
   log(`Array: ${arrayString}`);
@@ -130,116 +230,90 @@ export function logEffects(this: void, player: EntityPlayer): void {
   });
 }
 
-/** Helper function for printing out every entity (or filtered entity) in the current room. */
-export function logEntities(
-  this: void,
-  includeBackgroundEffects: boolean,
-  entityTypeFilter?: EntityType,
-): void {
-  let msg = "Entities in the room";
-  if (entityTypeFilter !== undefined) {
-    msg += ` (filtered to entity type ${entityTypeFilter})`;
-  } else if (!includeBackgroundEffects) {
-    msg += " (not including background effects)";
+/** Helper function for logging an array of specific entities. */
+export function logEntities(this: void, entities: Entity[]): void {
+  for (const entity of entities) {
+    logEntity(entity);
   }
-  msg += ":\n";
-
-  const entities = getEntities();
-  let numMatchedEntities = 0;
-  entities.forEach((entity, i) => {
-    // If a filter was specified, exclude all entities outside of the filter.
-    if (entityTypeFilter !== undefined && entity.Type !== entityTypeFilter) {
-      return;
-    }
-
-    const effect = entity.ToEffect();
-    if (
-      !includeBackgroundEffects &&
-      effect !== undefined &&
-      IGNORE_EFFECT_VARIANTS.has(effect.Variant)
-    ) {
-      return;
-    }
+}
 
-    const entityID = getEntityID(entity);
-    msg += `${i + 1}) ${entityID}`;
+/** Helper function to log information about a specific entity. */
+export function logEntity(this: void, entity: Entity): void {
+  const msg = getEntityLogLine(entity);
+  log(msg);
+}
 
-    const bomb = entity.ToBomb();
-    if (bomb !== undefined) {
-      msg += " (bomb)";
-    }
+function getEntityLogLine(entity: Entity, num?: int): string {
+  let msg = num === undefined ? "" : `${num}) `;
 
-    if (effect !== undefined) {
-      msg += ` (effect) (State: ${effect.State})`;
-    }
+  msg += getEntityID(entity);
 
-    const familiar = entity.ToFamiliar();
-    if (familiar !== undefined) {
-      msg += ` (familiar) (State: ${familiar.State})`;
-    }
+  const bomb = entity.ToBomb();
+  if (bomb !== undefined) {
+    msg += " (bomb)";
+  }
 
-    const knife = entity.ToKnife();
-    if (knife !== undefined) {
-      msg += " (knife)";
-    }
+  const effect = entity.ToEffect();
+  if (effect !== undefined) {
+    msg += ` (effect) (State: ${effect.State})`;
+  }
 
-    const laser = entity.ToLaser();
-    if (laser !== undefined) {
-      msg += " (laser)";
-    }
+  const familiar = entity.ToFamiliar();
+  if (familiar !== undefined) {
+    msg += ` (familiar) (State: ${familiar.State})`;
+  }
 
-    const npc = entity.ToNPC();
-    if (npc !== undefined) {
-      msg += ` (NPC) (State: ${npc.State})`;
-    }
+  const knife = entity.ToKnife();
+  if (knife !== undefined) {
+    msg += " (knife)";
+  }
 
-    const pickup = entity.ToPickup();
-    if (pickup !== undefined) {
-      msg += ` (pickup) (State: ${pickup.State})`;
-    }
+  const laser = entity.ToLaser();
+  if (laser !== undefined) {
+    msg += " (laser)";
+  }
 
-    const player = entity.ToPlayer();
-    if (player !== undefined) {
-      msg += " (player)";
-    }
+  const npc = entity.ToNPC();
+  if (npc !== undefined) {
+    msg += ` (NPC) (State: ${npc.State})`;
+  }
 
-    const projectile = entity.ToProjectile();
-    if (projectile !== undefined) {
-      msg += " (projectile)";
-    }
+  const pickup = entity.ToPickup();
+  if (pickup !== undefined) {
+    msg += ` (pickup) (State: ${pickup.State})`;
+  }
 
-    const tear = entity.ToTear();
-    if (tear !== undefined) {
-      msg += " (tear)";
-    }
+  const player = entity.ToPlayer();
+  if (player !== undefined) {
+    msg += " (player)";
+  }
 
-    msg += "\n";
-    msg += `  - Index: ${entity.Index}\n`;
-    msg += `  - InitSeed: ${entity.InitSeed}\n`;
-    msg += `  - DropSeed: ${entity.DropSeed}\n`;
-    msg += `  - Position: (${entity.Position.X}, ${entity.Position.Y})\n`;
-    msg += `  - Velocity: (${entity.Velocity.X}, ${entity.Velocity.Y})\n`;
-    msg += `  - HP: ${entity.HitPoints} / ${entity.MaxHitPoints}\n`;
-    msg += `  - Parent: ${entity.Parent}\n`;
-    msg += `  - Child: ${entity.Child}\n`;
-    msg += `  - SpawnerEntity: ${entity.SpawnerEntity}\n`;
-    msg += `  - SpawnerType / SpawnerVariant: ${entity.SpawnerType}.${entity.SpawnerVariant}\n`;
-    if (npc !== undefined) {
-      msg += `  - CanShutDoors: ${npc.CanShutDoors}\n`;
-    }
+  const projectile = entity.ToProjectile();
+  if (projectile !== undefined) {
+    msg += " (projectile)";
+  }
 
-    numMatchedEntities++;
-  });
+  const tear = entity.ToTear();
+  if (tear !== undefined) {
+    msg += " (tear)";
+  }
 
-  if (numMatchedEntities === 0) {
-    msg += "(no entities matched)\n";
-  } else {
-    msg += `(${numMatchedEntities} total ${
-      numMatchedEntities === 1 ? "entity" : "entities"
-    })\n`;
+  msg += "\n";
+  msg += `  - Index: ${entity.Index}\n`;
+  msg += `  - InitSeed: ${entity.InitSeed}\n`;
+  msg += `  - DropSeed: ${entity.DropSeed}\n`;
+  msg += `  - Position: (${entity.Position.X}, ${entity.Position.Y})\n`;
+  msg += `  - Velocity: (${entity.Velocity.X}, ${entity.Velocity.Y})\n`;
+  msg += `  - HP: ${entity.HitPoints} / ${entity.MaxHitPoints}\n`;
+  msg += `  - Parent: ${entity.Parent}\n`;
+  msg += `  - Child: ${entity.Child}\n`;
+  msg += `  - SpawnerEntity: ${entity.SpawnerEntity}\n`;
+  msg += `  - SpawnerType / SpawnerVariant: ${entity.SpawnerType}.${entity.SpawnerVariant}\n`;
+  if (npc !== undefined) {
+    msg += `  - CanShutDoors: ${npc.CanShutDoors}\n`;
   }
 
-  log(msg);
+  return msg;
 }
 
 /** Helper function for printing out every entity flag that is turned on. Useful when debugging. */
@@ -316,106 +390,74 @@ export function logGameStateFlags(this: void): void {
   }
 }
 
-/**
- * Helper function for printing out every grid entity (or filtered grid entity) in the current room.
- */
-export function logGridEntities(
-  this: void,
-  includeWalls: boolean,
-  gridEntityTypeFilter?: GridEntityType,
-): void {
-  let msg = "Grid entities in the room";
-  if (gridEntityTypeFilter !== undefined) {
-    msg += ` (filtered to grid entity type ${gridEntityTypeFilter})`;
-  } else if (!includeWalls) {
-    msg += " (not including walls)";
+/** Helper function for logging an array of specific grid entities. */
+export function logGridEntities(this: void, gridEntities: GridEntity[]): void {
+  for (const gridEntity of gridEntities) {
+    logGridEntity(gridEntity);
   }
-  msg += ":\n";
-
-  const gridEntities = getGridEntities();
-  let numMatchedEntities = 0;
-  gridEntities.forEach((gridEntity) => {
-    const gridEntityIndex = gridEntity.GetGridIndex();
-    const gridEntityType = gridEntity.GetType();
-    const gridEntityVariant = gridEntity.GetVariant();
-    const gridEntityDesc = gridEntity.GetSaveState();
-
-    // If a filter was specified, exclude all entities outside of the filter.
-    if (
-      gridEntityTypeFilter !== undefined &&
-      gridEntityType !== gridEntityTypeFilter
-    ) {
-      return;
-    }
+}
 
-    if (
-      !includeWalls &&
-      gridEntityType === GridEntityType.WALL &&
-      gridEntityTypeFilter !== GridEntityType.WALL
-    ) {
-      return;
-    }
+/** Helper function for log information about a specific grid entity. */
+export function logGridEntity(this: void, gridEntity: GridEntity): void {
+  const msg = getGridEntityLogLine(gridEntity);
+  log(msg);
+}
 
-    msg += `${gridEntityIndex}) ${gridEntityType}.${gridEntityVariant}.${gridEntity.State}`;
+function getGridEntityLogLine(gridEntity: GridEntity, num?: int): string {
+  const gridEntityDesc = gridEntity.GetSaveState();
 
-    const door = gridEntity.ToDoor();
-    if (door !== undefined) {
-      msg += " (door)";
-    }
+  let msg = num === undefined ? "" : `${num}) `;
 
-    const pit = gridEntity.ToPit();
-    if (pit !== undefined) {
-      msg += " (pit)";
-    }
+  msg += getGridEntityID(gridEntity);
 
-    const poop = gridEntity.ToPoop();
-    if (poop !== undefined) {
-      msg += " (poop)";
-    }
+  const door = gridEntity.ToDoor();
+  if (door !== undefined) {
+    msg += " (door)";
+  }
 
-    const pressurePlate = gridEntity.ToPressurePlate();
-    if (pressurePlate !== undefined) {
-      msg += " (pressurePlate)";
-    }
+  const pit = gridEntity.ToPit();
+  if (pit !== undefined) {
+    msg += " (pit)";
+  }
 
-    const rock = gridEntity.ToRock();
-    if (rock !== undefined) {
-      msg += " (rock)";
-    }
+  const poop = gridEntity.ToPoop();
+  if (poop !== undefined) {
+    msg += " (poop)";
+  }
 
-    const spikes = gridEntity.ToSpikes();
-    if (spikes !== undefined) {
-      msg += " (spikes)";
-    }
+  const pressurePlate = gridEntity.ToPressurePlate();
+  if (pressurePlate !== undefined) {
+    msg += " (pressurePlate)";
+  }
 
-    const tnt = gridEntity.ToTNT();
-    if (tnt !== undefined) {
-      msg += " (TNT)";
-    }
+  const rock = gridEntity.ToRock();
+  if (rock !== undefined) {
+    msg += " (rock)";
+  }
 
-    msg += `  - VarData: ${gridEntity.VarData}\n`;
-    msg += `  - Position: (${gridEntity.Position.X}, ${gridEntity.Position.Y})\n`;
-    msg += `  - SpawnSeed: ${gridEntityDesc.SpawnSeed}\n`;
-    msg += `  - VariableSeed: ${gridEntityDesc.VariableSeed})\n`;
-    if (door !== undefined) {
-      msg += `  - Slot: ${door.Slot}\n`;
-      msg += `  - Direction: ${door.Direction}\n`;
-      msg += `  - TargetRoomIndex: ${door.TargetRoomIndex}\n`;
-      msg += `  - TargetRoomType: ${door.TargetRoomType}\n`;
-    }
+  const spikes = gridEntity.ToSpikes();
+  if (spikes !== undefined) {
+    msg += " (spikes)";
+  }
 
-    numMatchedEntities++;
-  });
+  const tnt = gridEntity.ToTNT();
+  if (tnt !== undefined) {
+    msg += " (TNT)";
+  }
 
-  if (numMatchedEntities === 0) {
-    msg += "(no grid entities matched)\n";
-  } else {
-    msg += `(${numMatchedEntities} total grid ${
-      numMatchedEntities === 1 ? "entity" : "entities"
-    })\n`;
+  msg += `  - State: ${gridEntity.State}\n`;
+  msg += `  - VarData: ${gridEntity.VarData}\n`;
+  msg += `  - Position: (${gridEntity.Position.X}, ${gridEntity.Position.Y})\n`;
+  msg += `  - SpawnSeed: ${gridEntityDesc.SpawnSeed}\n`;
+  msg += `  - VariableSeed: ${gridEntityDesc.VariableSeed})\n`;
+  if (door !== undefined) {
+    msg += `  - Slot: ${door.Slot}\n`;
+    msg += `  - Direction: ${door.Direction}\n`;
+    msg += `  - TargetRoomIndex: ${door.TargetRoomIndex}\n`;
+    msg += `  - TargetRoomType: ${door.TargetRoomType}\n`;
   }
 
-  log(msg);
+  return msg;
 }
 
 export function logKColor(this: void, kColor: KColor): void {
@@ -714,17 +756,21 @@ export function setLogFunctionsGlobal(): void {
   const globals = _G as Record<string, unknown>;
 
   globals["log"] = log;
+  globals["logAllEntities"] = logAllEntities;
+  globals["logAllGridEntities"] = logAllGridEntities;
   globals["logArray"] = logArray;
   globals["logColor"] = logColor;
   globals["logDamageFlags"] = logDamageFlags;
   globals["logEffects"] = logEffects;
   globals["logEntities"] = logEntities;
+  globals["logEntity"] = logEntity;
   globals["logEntityID"] = logEntityID;
   globals["logEntityFlags"] = logEntityFlags;
   globals["logError"] = logError;
   globals["logFlags"] = logFlags;
   globals["logGameStateFlags"] = logGameStateFlags;
   globals["logGridEntities"] = logGridEntities;
+  globals["logGridEntity"] = logGridEntity;
   globals["logKColor"] = logKColor;
   globals["logLevelStateFlags"] = logLevelStateFlags;
   globals["logMap"] = logMap;

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;
+}