isaacscript-common 13.0.0 → 13.1.0

package/src/features/setHotkey.ts

@@ -2,7 +2,6 @@ import { Keyboard, ModCallback } from "isaac-typescript-definitions";
 import { DefaultMap } from "../classes/DefaultMap";
 import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
 import { isKeyboardPressed } from "../functions/input";
-import { isFunction } from "../functions/types";
 
 const FEATURE_NAME = "setHotkey";
 
@@ -61,64 +60,85 @@ function checkIfTriggered(keyboard: Keyboard, triggerFunc: () => void) {
  * This can be used to easily set up custom hotkeys to facilitate custom game features or to assist
  * in debugging.
  *
- * @param keyboardOrFunc Either the key that you want to trigger the hotkey or a function that
- *                       returns the key that will trigger the hotkey. Normally, you would just
- *                       specify the key directly, but you can use a function for situations where
- *                       the key can change (like if end-users can specify a custom hotkey using Mod
- *                       Config Menu).
+ * This is different from the `setHotkey` function in that the keyboard activation key is not
+ * hardcoded and is instead the return value of a provided function. This is useful for situations
+ * where the key can change (like if end-users can specify a custom hotkey using Mod Config Menu).
+ *
+ * @param getKeyFunc The function that returns the key that will trigger the hotkey.
  * @param triggerFunc A function containing the arbitrary code that you want to execute when the
  *                    hotkey is triggered.
  */
-export function setHotkey(
-  keyboardOrFunc: Keyboard | (() => Keyboard | undefined),
+export function setConditionalHotkey(
+  getKeyFunc: () => Keyboard | undefined,
   triggerFunc: () => void,
 ): void {
   errorIfFeaturesNotInitialized(FEATURE_NAME);
 
-  if (isFunction(keyboardOrFunc)) {
-    if (dynamicHotkeyFunctionMap.has(keyboardOrFunc)) {
-      error(
-        "Failed to register a hotkey due to a custom hotkey already being defined for the submitted function.",
-      );
-    }
+  if (dynamicHotkeyFunctionMap.has(getKeyFunc)) {
+    error(
+      "Failed to register a hotkey due to a custom hotkey already being defined for the submitted function.",
+    );
+  }
 
-    dynamicHotkeyFunctionMap.set(keyboardOrFunc, triggerFunc);
-  } else {
-    if (staticHotkeyFunctionMap.has(keyboardOrFunc)) {
-      error(
-        `Failed to register a hotkey due to a hotkey already being defined for key: Keyboard.${Keyboard[keyboardOrFunc]} (${keyboardOrFunc})`,
-      );
-    }
+  dynamicHotkeyFunctionMap.set(getKeyFunc, triggerFunc);
+}
 
-    staticHotkeyFunctionMap.set(keyboardOrFunc, triggerFunc);
+/**
+ * Helper function to run arbitrary code when you press and release a specific keyboard key.
+ *
+ * This can be used to easily set up custom hotkeys to facilitate custom game features or to assist
+ * in debugging.
+ *
+ * @param keyboard The key that you want to trigger the hotkey.
+ * @param triggerFunc A function containing the arbitrary code that you want to execute when the
+ *                    hotkey is triggered.
+ */
+export function setHotkey(keyboard: Keyboard, triggerFunc: () => void): void {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  if (staticHotkeyFunctionMap.has(keyboard)) {
+    error(
+      `Failed to register a hotkey due to a hotkey already being defined for: Keyboard.${Keyboard[keyboard]} (${keyboard})`,
+    );
   }
+
+  staticHotkeyFunctionMap.set(keyboard, triggerFunc);
 }
 
 /**
- * Helper function to remove a hotkey created with the `setHotkey` function.
+ * Helper function to remove a hotkey created with the `setConditionalHotkey` function.
  *
- * @param keyboardOrFunc Equal to the value that you passed when initially registering the hotkey.
+ * @param getKeyFunc Equal to the `getKeyFunc` that you passed when initially registering the
+ *                   hotkey.
  */
-export function unsetHotkey(
-  keyboardOrFunc: Keyboard | (() => Keyboard | undefined),
+export function unsetConditionalHotkey(
+  getKeyFunc: () => Keyboard | undefined,
 ): void {
   errorIfFeaturesNotInitialized(FEATURE_NAME);
 
-  if (isFunction(keyboardOrFunc)) {
-    if (!dynamicHotkeyFunctionMap.has(keyboardOrFunc)) {
-      error(
-        "Failed to unregister a hotkey since there is no existing hotkey defined for the submitted function.",
-      );
-    }
+  if (!dynamicHotkeyFunctionMap.has(getKeyFunc)) {
+    error(
+      "Failed to unregister a hotkey since there is no existing hotkey defined for the submitted function.",
+    );
+  }
 
-    dynamicHotkeyFunctionMap.delete(keyboardOrFunc);
-  } else {
-    if (!staticHotkeyFunctionMap.has(keyboardOrFunc)) {
-      error(
-        `Failed to unregister a hotkey since there is no existing hotkey defined for key: Keyboard.${Keyboard[keyboardOrFunc]} (${keyboardOrFunc})`,
-      );
-    }
+  dynamicHotkeyFunctionMap.delete(getKeyFunc);
+}
 
-    staticHotkeyFunctionMap.delete(keyboardOrFunc);
+/**
+ * Helper function to remove a hotkey created with the `setHotkey` function.
+ *
+ * @param keyboard Equal to the keyboard value that you passed when initially registering the
+ *                 hotkey.
+ */
+export function unsetHotkey(keyboard: Keyboard): void {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  if (!staticHotkeyFunctionMap.has(keyboard)) {
+    error(
+      `Failed to unregister a hotkey since there is no existing hotkey defined for: Keyboard.${Keyboard[keyboard]} (${keyboard})`,
+    );
   }
+
+  staticHotkeyFunctionMap.delete(keyboard);
 }

package/src/functions/array.ts

@@ -1,7 +1,7 @@
 import { getRandomInt } from "./random";
 import { getRandomSeed, isRNG, newRNG } from "./rng";
 import { isNumber, isTable } from "./types";
-import { erange } from "./utils";
+import { eRange } from "./utils";
 
 /**
  * Helper function for determining if two arrays contain the exact same elements. Note that this
@@ -310,7 +310,7 @@ export function getArrayCombinations<T>(
  * For example, an array of `["Apple", "Banana"]` would return an array of `[0, 1]`.
  */
 export function getArrayIndexes<T>(array: T[] | readonly T[]): int[] {
-  return erange(array.length);
+  return eRange(array.length);
 }
 
 /**

package/src/functions/cards.ts

@@ -16,7 +16,7 @@ import {
 import { getEnumValues } from "./enums";
 import { getRandomSeed } from "./rng";
 import { addSetsToSet, getRandomSetElement } from "./set";
-import { irange } from "./utils";
+import { iRange } from "./utils";
 
 const ITEM_CONFIG_CARD_TYPE_TO_CARD_TYPE_MAP = new Map<
   ItemConfigCardType,
@@ -206,7 +206,7 @@ export function getRandomRune(
 
 /** Helper function to get an array with every valid vanilla card sub-type. */
 export function getVanillaCardTypes(): CardType[] {
-  return irange(FIRST_CARD_TYPE, LAST_VANILLA_CARD_TYPE);
+  return iRange(FIRST_CARD_TYPE, LAST_VANILLA_CARD_TYPE);
 }
 
 /**

package/src/functions/collectibles.ts

@@ -32,7 +32,7 @@ import { getEntityID } from "./entities";
 import { isCollectible } from "./pickupVariants";
 import { getRoomListIndex } from "./roomData";
 import { clearSprite, spriteEquals } from "./sprites";
-import { irange } from "./utils";
+import { iRange } from "./utils";
 
 const COLLECTIBLE_ANM2_PATH = "gfx/005.100_collectible.anm2";
 
@@ -400,7 +400,7 @@ export function getCollectibleTags(
  * instead.
  */
 export function getVanillaCollectibleTypeRange(): CollectibleType[] {
-  return irange(FIRST_COLLECTIBLE_TYPE, LAST_VANILLA_COLLECTIBLE_TYPE);
+  return iRange(FIRST_COLLECTIBLE_TYPE, LAST_VANILLA_COLLECTIBLE_TYPE);
 }
 
 /** Returns true if the item type in the item config is equal to `ItemType.ITEM_ACTIVE`. */

package/src/functions/dimensions.ts

@@ -2,13 +2,13 @@ import { Dimension } from "isaac-typescript-definitions";
 import { game } from "../core/cachedClasses";
 import { NUM_DIMENSIONS } from "../core/constants";
 import { getRoomGridIndex } from "./roomData";
-import { erange } from "./utils";
+import { eRange } from "./utils";
 
 /**
  * Helper function to get an array with every valid `Dimension` (not including `Dimension.CURRENT`).
  */
 export function getAllDimensions(): Dimension[] {
-  return erange(NUM_DIMENSIONS);
+  return eRange(NUM_DIMENSIONS);
 }
 
 /**

package/src/functions/emptyRoom.ts

@@ -0,0 +1,85 @@
+import {
+  EntityFlag,
+  EntityType,
+  GridEntityType,
+} from "isaac-typescript-definitions";
+import { game } from "../core/cachedClasses";
+import { getEntities } from "./entities";
+import { getGridEntities, removeGridEntity } from "./gridEntities";
+import { roomUpdateSafe } from "./rooms";
+
+const EMPTY_ROOM_BLACKLIST_ENTITY_SET: ReadonlySet<EntityType> = new Set([
+  EntityType.PLAYER, // 1
+  EntityType.TEAR, // 2
+  EntityType.FAMILIAR, // 3
+  EntityType.LASER, // 7
+  EntityType.KNIFE, // 8
+  EntityType.PROJECTILE, // 9
+  EntityType.DARK_ESAU, // 866
+]);
+
+const EMPTY_ROOM_BLACKLIST_GRID_ENTITY_SET: ReadonlySet<GridEntityType> =
+  new Set([
+    GridEntityType.WALL, // 15
+    GridEntityType.DOOR, // 16
+  ]);
+
+/**
+ * Helper function to remove all naturally spawning entities and grid entities from a room. Notably,
+ * this will not remove players (1), tears (2), familiars (3), lasers (7), knives (8), projectiles
+ * (9), blacklisted NPCs such as Dark Esau, charmed NPCs, friendly NPCs, persistent NPCs, most
+ * effects (1000), doors, and walls.
+ */
+export function emptyRoom(): void {
+  emptyRoomEntities();
+  emptyRoomGridEntities();
+}
+
+/**
+ * We remove entities in the `POST_NEW_ROOM` callback instead of in the `PRE_ROOM_ENTITY_SPAWN`
+ * callback so that they will not re-appear when we re-enter the room.
+ */
+function emptyRoomEntities() {
+  const room = game.GetRoom();
+
+  for (const entity of getEntities()) {
+    if (EMPTY_ROOM_BLACKLIST_ENTITY_SET.has(entity.Type)) {
+      continue;
+    }
+
+    if (
+      entity.HasEntityFlags(EntityFlag.CHARM) ||
+      entity.HasEntityFlags(EntityFlag.FRIENDLY) ||
+      entity.HasEntityFlags(EntityFlag.PERSISTENT)
+    ) {
+      continue;
+    }
+
+    entity.ClearEntityFlags(EntityFlag.APPEAR);
+    entity.Remove();
+
+    // When fire places are removed, they will leave behind a "path" that will prevent future grid
+    // entities from being spawned on the same tile. Thus, reset the path for this tile if this is a
+    // fire place.
+    if (entity.Type === EntityType.FIREPLACE) {
+      const gridIndex = room.GetGridIndex(entity.Position);
+      room.SetGridPath(gridIndex, 0);
+    }
+  }
+}
+
+function emptyRoomGridEntities() {
+  let removedOneOrMoreGridEntities = false;
+  for (const gridEntity of getGridEntities()) {
+    const gridEntityType = gridEntity.GetType();
+    if (EMPTY_ROOM_BLACKLIST_GRID_ENTITY_SET.has(gridEntityType)) {
+      continue;
+    }
+
+    removeGridEntity(gridEntity, false);
+    removedOneOrMoreGridEntities = true;
+  }
+  if (removedOneOrMoreGridEntities) {
+    roomUpdateSafe();
+  }
+}

package/src/functions/enums.ts

@@ -1,7 +1,7 @@
 import { getRandomArrayElement } from "./array";
 import { getRandomSeed } from "./rng";
 import { isString } from "./types";
-import { irange } from "./utils";
+import { iRange } from "./utils";
 
 /**
  * TypeScriptToLua will transpile TypeScript enums to Lua tables that have a double mapping. Thus,
@@ -165,7 +165,6 @@ export function validateEnumContiguous<T>(
   transpiledEnum: T,
 ): void {
   const values = getEnumValues(transpiledEnum);
-  const valuesSet = new Set(values);
   const lastValue = values[values.length - 1];
   if (lastValue === undefined) {
     error(
@@ -177,7 +176,9 @@ export function validateEnumContiguous<T>(
       "Failed to validate that an enum was contiguous, since the last value was not a number.",
     );
   }
-  for (const value of irange(lastValue)) {
+
+  const valuesSet = new Set(values);
+  for (const value of iRange(lastValue)) {
     if (!valuesSet.has(value as unknown as T[keyof T])) {
       error(
         `Failed to find a custom enum value of ${value} for: ${transpiledEnumName}`,

package/src/functions/gridEntities.ts

@@ -22,7 +22,7 @@ import { isCircleIntersectingRectangle } from "./math";
 import { roomUpdateSafe } from "./rooms";
 import { clearSprite } from "./sprites";
 import { asNumber, isNumber } from "./types";
-import { erange } from "./utils";
+import { eRange } from "./utils";
 import { isVector, vectorEquals } from "./vector";
 
 const BREAKABLE_GRID_ENTITY_TYPES_BY_EXPLOSIONS: ReadonlySet<GridEntityType> =
@@ -87,7 +87,7 @@ export function getAllGridIndexes(): int[] {
   const room = game.GetRoom();
   const gridSize = room.GetGridSize();
 
-  return erange(gridSize);
+  return eRange(gridSize);
 }
 
 /**

package/src/functions/gridIndex.ts

@@ -0,0 +1,40 @@
+import { RoomShape } from "isaac-typescript-definitions";
+import { getRoomShapeWidth } from "./roomShape";
+import { iRange } from "./utils";
+
+/**
+ * Helper function to get all of the grid indexes between two grid indexes on either a horizontal or
+ * vertical line, inclusive on both ends.
+ *
+ * This function will throw a run-time error if the two provided grid indexes are not on the same
+ * horizontal or vertical line.
+ */
+export function getGridIndexesBetween(
+  gridIndex1: int,
+  gridIndex2: int,
+  roomShape: RoomShape,
+): int[] {
+  if (gridIndex1 > gridIndex2) {
+    const oldGridIndex1 = gridIndex1;
+    const oldGridIndex2 = gridIndex2;
+    gridIndex1 = oldGridIndex2;
+    gridIndex2 = oldGridIndex1;
+  }
+
+  const delta = gridIndex2 - gridIndex1;
+  const gridWidth = getRoomShapeWidth(roomShape);
+
+  const isOnHorizontalLine = delta <= gridWidth;
+  if (isOnHorizontalLine) {
+    return iRange(gridIndex1, gridIndex2);
+  }
+
+  const isOnVerticalLine = delta % gridWidth === 0;
+  if (isOnVerticalLine) {
+    return iRange(gridIndex1, gridIndex2, gridWidth);
+  }
+
+  error(
+    `Failed to get the grid indexes between ${gridIndex1} and ${gridIndex2} for RoomShape.${RoomShape[roomShape]} (${roomShape}) since they are not on the same horizontal or vertical line.`,
+  );
+}

package/src/functions/log.ts

@@ -277,27 +277,26 @@ export function logRoom(): void {
   const roomListIndex = getRoomListIndex();
   const roomData = getRoomData();
 
+  log("Current room information:");
   if (roomData === undefined) {
-    log("Current room data is undefined.");
+    log("- Room data is undefined.");
   } else {
-    log(`Current room stage ID: ${roomData.StageID}`);
+    log(`- Room stage ID: ${roomData.StageID}`);
     log(
-      `Current room type/variant/sub-type: ${roomData.Type}.${roomData.Variant}.${roomData.Subtype}`,
+      `- Type/variant/sub-type: ${roomData.Type}.${roomData.Variant}.${roomData.Subtype}`,
     );
-    log(`Current room name: ${roomData.Name}`);
+    log(`- Name: ${roomData.Name}`);
   }
 
   const roomGridIndexName = GridRoom[roomGridIndex];
   if (roomGridIndexName === undefined) {
-    log(`Current room grid index: ${roomGridIndex}`);
+    log(`- Grid index: ${roomGridIndex}`);
   } else {
-    log(
-      `Current room grid index: ${roomGridIndex} (GridRoom.${roomGridIndexName})`,
-    );
+    log(`- Grid index: GridRoom.${roomGridIndexName} (${roomGridIndex})`);
   }
 
-  log(`Current room list index: ${roomListIndex}`);
-  log(`Current room boss ID: ${bossID}`);
+  log(`- List index: ${roomListIndex}`);
+  log(`- Boss ID: ${bossID}`);
 }
 
 /**

package/src/functions/logEntities.ts

@@ -1,7 +1,15 @@
 import {
+  BombVariant,
   EffectVariant,
   EntityType,
+  FamiliarVariant,
   GridEntityType,
+  KnifeVariant,
+  LaserVariant,
+  PickupVariant,
+  PlayerVariant,
+  ProjectileVariant,
+  TearVariant,
 } from "isaac-typescript-definitions";
 import { getEntities, getEntityFromPtrHash, getEntityID } from "./entities";
 import { getGridEntities, getGridEntityID } from "./gridEntities";
@@ -137,27 +145,31 @@ function getEntityLogLine(entity: Entity, num?: int): string {
 
   const bomb = entity.ToBomb();
   if (bomb !== undefined) {
-    msg += " (bomb)";
+    msg += ` (bomb - BombVariant.${BombVariant[bomb.Variant]})`;
   }
 
   const effect = entity.ToEffect();
   if (effect !== undefined) {
-    msg += ` (effect) (State: ${effect.State})`;
+    msg += ` (effect - EffectVariant.${
+      EffectVariant[effect.Variant]
+    }) (State: ${effect.State})`;
   }
 
   const familiar = entity.ToFamiliar();
   if (familiar !== undefined) {
-    msg += ` (familiar) (State: ${familiar.State})`;
+    msg += ` (familiar - FamiliarVariant.${
+      FamiliarVariant[familiar.Variant]
+    }) (State: ${familiar.State})`;
   }
 
   const knife = entity.ToKnife();
   if (knife !== undefined) {
-    msg += " (knife)";
+    msg += ` (knife - KnifeVariant.${KnifeVariant[knife.Variant]})`;
   }
 
   const laser = entity.ToLaser();
   if (laser !== undefined) {
-    msg += " (laser)";
+    msg += ` (laser - LaserVariant.${LaserVariant[laser.Variant]})`;
   }
 
   const npc = entity.ToNPC();
@@ -167,22 +179,26 @@ function getEntityLogLine(entity: Entity, num?: int): string {
 
   const pickup = entity.ToPickup();
   if (pickup !== undefined) {
-    msg += ` (pickup) (State: ${pickup.State})`;
+    msg += ` (pickup - PickupVariant.${
+      PickupVariant[pickup.Variant]
+    }) (State: ${pickup.State})`;
   }
 
   const player = entity.ToPlayer();
   if (player !== undefined) {
-    msg += " (player)";
+    msg += ` (player - PlayerVariant.${PlayerVariant[player.Variant]})`;
   }
 
   const projectile = entity.ToProjectile();
   if (projectile !== undefined) {
-    msg += " (projectile)";
+    msg += ` (projectile - ProjectileVariant.${
+      ProjectileVariant[projectile.Variant]
+    }))`;
   }
 
   const tear = entity.ToTear();
   if (tear !== undefined) {
-    msg += " (tear)";
+    msg += ` (tear - TearVariant.${TearVariant[tear.Variant]}))`;
   }
 
   msg += "\n";

package/src/functions/pills.ts

@@ -29,7 +29,7 @@ import {
 } from "../objects/pillEffectTypes";
 import { getEnumValues } from "./enums";
 import { asNumber, asPillColor } from "./types";
-import { irange } from "./utils";
+import { iRange } from "./utils";
 
 /**
  * Add this to a `PillColor` to get the corresponding giant pill color.
@@ -71,7 +71,7 @@ export function getHorsePillColor(pillColor: PillColor): PillColor {
 
 /** Helper function to get an array with every non-gold horse pill color. */
 export function getHorsePillColors(): PillColor[] {
-  return irange(FIRST_HORSE_PILL_COLOR, LAST_HORSE_PILL_COLOR);
+  return iRange(FIRST_HORSE_PILL_COLOR, LAST_HORSE_PILL_COLOR);
 }
 
 /**
@@ -91,7 +91,7 @@ export function getNormalPillColorFromHorse(pillColor: PillColor): PillColor {
 
 /** Helper function to get an array with every non-gold and non-horse pill color. */
 export function getNormalPillColors(): PillColor[] {
-  return irange(FIRST_PILL_COLOR, LAST_NORMAL_PILL_COLOR);
+  return iRange(FIRST_PILL_COLOR, LAST_NORMAL_PILL_COLOR);
 }
 
 /**
@@ -172,7 +172,7 @@ export function getPillEffectType(
 
 /** Helper function to get an array with every vanilla pill effect. */
 export function getVanillaPillEffects(): PillEffect[] {
-  return irange(FIRST_PILL_EFFECT, LAST_VANILLA_PILL_EFFECT);
+  return iRange(FIRST_PILL_EFFECT, LAST_VANILLA_PILL_EFFECT);
 }
 
 export function isHorsePill(pillColor: PillColor): boolean {

package/src/functions/roomShape.ts

@@ -60,7 +60,12 @@ export function getRoomShapeCharges(roomShape: RoomShape): int {
   return isRoomShapeDoubleCharge(roomShape) ? 2 : 1;
 }
 
-/** Helper function to get the corners that exist in the given room shape. */
+/**
+ * Helper function to get the corners that exist in the given room shape.
+ *
+ * Note that these corner locations are not accurate for the Mother Boss Room and the Home closet
+ * rooms. (Those rooms have custom shapes.)
+ */
 export function getRoomShapeCorners(roomShape: RoomShape): readonly Corner[] {
   return ROOM_SHAPE_CORNERS[roomShape];
 }