isaacscript-common 6.19.0 → 6.20.2

package/src/functions/rooms.ts

@@ -1,5 +1,6 @@
 import {
   AngelRoomSubType,
+  BackdropType,
   BossID,
   Dimension,
   Direction,
@@ -8,6 +9,7 @@ import {
   GridRoom,
   HomeRoomSubType,
   ItemPoolType,
+  LevelCurse,
   MinibossID,
   RoomDescriptorFlag,
   RoomShape,
@@ -17,14 +19,11 @@ import {
   StageID,
 } from "isaac-typescript-definitions";
 import { game, sfxManager } from "../cachedClasses";
-import {
-  LEVEL_GRID_ROW_WIDTH,
-  MAX_LEVEL_GRID_INDEX,
-  NUM_DIMENSIONS,
-} from "../constants";
-import { ROOM_SHAPE_TO_DOOR_SLOTS_TO_GRID_INDEX_DELTA } from "../objects/roomShapeToDoorSlotsToGridIndexDelta";
+import { MAX_LEVEL_GRID_INDEX, NUM_DIMENSIONS } from "../constants";
 import { ROOM_TYPE_NAMES } from "../objects/roomTypeNames";
 import { MINE_SHAFT_ROOM_SUB_TYPE_SET } from "../sets/mineShaftRoomSubTypesSet";
+import { hasCurse } from "./curses";
+import { inDimension } from "./dimensions";
 import {
   closeAllDoors,
   getDoors,
@@ -40,17 +39,15 @@ import {
   setEntityVelocities,
 } from "./positionVelocity";
 import {
-  getRoomAllowedDoors,
   getRoomData,
   getRoomDescriptor,
   getRoomDescriptorReadOnly,
   getRoomGridIndex,
   getRoomName,
-  getRoomShape,
   getRoomStageID,
   getRoomSubType,
 } from "./roomData";
-import { getGridIndexDelta } from "./roomShape";
+import { getGotoCommand } from "./stage";
 import { erange, irange } from "./utils";
 
 /**
@@ -76,72 +73,85 @@ export function changeRoom(roomGridIndex: int): void {
 }
 
 /**
- * Helper function to get an array with every valid `Dimension` (not including `Dimension.CURRENT`).
+ * Helper function to get the number of rooms that are currently on the floor layout. This does not
+ * include off-grid rooms, like the Devil Room.
  */
-export function getAllDimensions(): Dimension[] {
-  return erange(NUM_DIMENSIONS) as Dimension[];
-}
-
-/** Helper function to get the grid index for every room on the entire floor. */
-export function getAllRoomGridIndexes(): int[] {
-  const rooms = getRooms();
-  return rooms.map((roomDescriptor) => roomDescriptor.SafeGridIndex);
+export function getNumRooms(): int {
+  const rooms = getRoomsInGrid();
+  return rooms.length;
 }
 
 /**
- * Helper function to get the current dimension. Most of the time, this will be `Dimension.MAIN`,
- * but it can change if e.g. the player is in the mirror world of Downpour/Dross.
+ * Helper function to get a read-only copy of the room descriptor for every room on the level. This
+ * includes off-grid rooms, such as the Devil Room, and extra-dimensional rooms, if they are
+ * generated and exist.
+ *
+ * Room descriptors without any data are assumed to be non-existent and are not included.
+ *
+ * Under the hood, this is performed by iterating over the `RoomList` from the `Level.GetRooms`
+ * method. This is the best way to see if off-grid rooms have been initialized, since it is possible
+ * for mods to insert room data at non-official negative room grid indexes.
  */
-export function getDimension(): Dimension {
+export function getReadOnlyRooms(): Array<Readonly<RoomDescriptor>> {
   const level = game.GetLevel();
-  const roomGridIndex = getRoomGridIndex();
-  const roomDescription = level.GetRoomByIdx(roomGridIndex, Dimension.CURRENT);
-  const currentRoomHash = GetPtrHash(roomDescription);
+  const roomList = level.GetRooms();
 
-  for (const dimension of getAllDimensions()) {
-    const dimensionRoomDescription = level.GetRoomByIdx(
-      roomGridIndex,
-      dimension,
-    );
-    const dimensionRoomHash = GetPtrHash(dimensionRoomDescription);
+  const readOnlyRoomDescriptors: Array<Readonly<RoomDescriptor>> = [];
 
-    if (dimensionRoomHash === currentRoomHash) {
-      return dimension;
+  for (let i = 0; i < roomList.Size; i++) {
+    const readOnlyRoomDescriptor = roomList.Get(i);
+    if (
+      readOnlyRoomDescriptor !== undefined &&
+      readOnlyRoomDescriptor.Data !== undefined
+    ) {
+      readOnlyRoomDescriptors.push(readOnlyRoomDescriptor);
     }
   }
 
-  error("Failed to get the current dimension.");
-}
-
-/**
- * Helper function to get the number of rooms that are currently on the floor layout. This does not
- * include off-grid rooms, like the Devil Room.
- */
-export function getNumRooms(): int {
-  const rooms = getRooms();
-  return rooms.length;
+  return readOnlyRoomDescriptors;
 }
 
 /**
- * Helper function to get an array of all of the safe grid indexes for rooms that match the
- * specified room type.
+ * Helper function to get the room data for a specific room type and variant combination. This is
+ * accomplished by using the "goto" console command to load the specified room into the
+ * `GridRoom.DEBUG` slot.
  *
- * This function only searches through rooms in the current dimension.
+ * Returns undefined if the provided room type and variant combination were not found. (A warning
+ * message will also appear on the console, since the "goto" command will fail.)
  *
- * This function is variadic, meaning that you can specify N arguments to get the combined grid
- * indexes for N room types.
+ * Note that the side effect of using the "goto" console command is that it will trigger a room
+ * transition after a short delay. By default, this function cancels the incoming room transition by
+ * using the `Game.StartRoomTransition` method to travel to the same room.
+ *
+ * @param roomType The type of room to retrieve.
+ * @param roomVariant The room variant to retrieve. (The room variant is the "ID" of the room in
+ *                    Basement Renovator.)
+ * @param cancelRoomTransition Optional. Whether to cancel the room transition by using the
+ *                             `Game.StartRoomTransition` method to travel to the same room. Default
+ *                             is true. Set this to false if you are getting the data for many rooms
+ *                             at the same time, and then use the `teleport` helper function when
+ *                             you are finished.
  */
-export function getRoomGridIndexesForType(...roomTypes: RoomType[]): int[] {
-  const roomTypesSet = new Set<RoomType>([...roomTypes]);
-
-  const rooms = getRooms();
-  const matchingRooms = rooms.filter(
-    (roomDescriptor) =>
-      roomDescriptor.Data !== undefined &&
-      roomTypesSet.has(roomDescriptor.Data.Type),
-  );
+export function getRoomDataForTypeVariant(
+  roomType: RoomType,
+  roomVariant: int,
+  cancelRoomTransition = true,
+): Readonly<RoomConfig> | undefined {
+  const command = getGotoCommand(roomType, roomVariant);
+  Isaac.ExecuteCommand(command);
+  const newRoomData = getRoomData(GridRoom.DEBUG);
+
+  if (cancelRoomTransition) {
+    const roomGridIndex = getRoomGridIndex();
+    teleport(
+      roomGridIndex,
+      Direction.NO_DIRECTION,
+      RoomTransitionAnim.FADE,
+      true,
+    );
+  }
 
-  return matchingRooms.map((roomDescriptor) => roomDescriptor.SafeGridIndex);
+  return newRoomData;
 }
 
 /**
@@ -157,40 +167,6 @@ export function getRoomItemPoolType(): ItemPoolType {
   return itemPool.GetPoolForRoom(roomType, roomSeed);
 }
 
-/**
- * Helper function to get the grid indexes of all the rooms connected to the given room index.
- *
- * @param roomGridIndex Optional. Default is the current room index.
- */
-export function getRoomNeighbors(roomGridIndex?: int): int[] {
-  const roomDescriptor = getRoomDescriptor(roomGridIndex);
-
-  if (
-    roomDescriptor.SafeGridIndex < 0 ||
-    roomDescriptor.SafeGridIndex > MAX_LEVEL_GRID_INDEX
-  ) {
-    return [];
-  }
-
-  const roomData = roomDescriptor.Data;
-  if (roomData === undefined) {
-    return [];
-  }
-
-  const roomShape = roomData.Shape;
-  const gridIndexDeltas = getRoomShapeNeighborGridIndexDeltas(roomShape);
-  const gridIndexes = gridIndexDeltas.map(
-    (gridIndexDelta) => roomDescriptor.SafeGridIndex + gridIndexDelta,
-  );
-  return gridIndexes.filter((gridIndex) => roomExists(gridIndex));
-}
-
-export function getRoomShapeNeighborGridIndexDeltas(
-  roomShape: RoomShape,
-): int[] {
-  return [...ROOM_SHAPE_TO_DOOR_SLOTS_TO_GRID_INDEX_DELTA[roomShape].values()];
-}
-
 /**
  * Helper function to get the proper name of a room type.
  *
@@ -201,77 +177,106 @@ export function getRoomTypeName(roomType: RoomType): string {
 }
 
 /**
- * Helper function to get the room descriptor for every room on the level, including off-grid rooms.
- * Uses the `Level.GetRooms` method to accomplish this. Rooms without data are assumed to be
- * non-existent and are not added to the list.
+ * Helper function to get the room descriptor for every room on the level. This includes off-grid
+ * rooms, such as the Devil Room.
+ *
+ * Room descriptors without any data are assumed to be non-existent and are not included.
+ *
+ * - If you want just the rooms inside of the grid, use the `getRoomsInGrid` helper function.
+ * - If you want just the rooms outside of the grid, use the `getRoomsOutsideGrid` helper function.
  *
  * @param includeExtraDimensionalRooms Optional. On some floors (e.g. Downpour 2, Mines 2),
- *                                 extra-dimensional rooms are automatically generated and can be
- *                                 seen when you iterate over the `RoomList`. Default is false.
+ *                                 extra-dimensional rooms are automatically generated. Default is
+ *                                 false.
  */
 export function getRooms(
   includeExtraDimensionalRooms = false,
 ): RoomDescriptor[] {
-  const level = game.GetLevel();
-  const roomList = level.GetRooms();
-
-  const roomsMap = new Map<int, RoomDescriptor>();
-  if (includeExtraDimensionalRooms) {
-    for (let i = 0; i < roomList.Size; i++) {
-      const roomDescriptor = roomList.Get(i);
-      if (roomDescriptor !== undefined && roomDescriptor.Data !== undefined) {
-        roomsMap.set(roomDescriptor.ListIndex, roomDescriptor);
-      }
-    }
-  } else {
-    for (const roomGridIndex of irange(MAX_LEVEL_GRID_INDEX)) {
-      const roomDescriptor = level.GetRoomByIdx(roomGridIndex);
-      if (roomDescriptor.Data !== undefined) {
-        roomsMap.set(roomDescriptor.ListIndex, roomDescriptor);
-      }
-    }
-  }
-
-  return [...roomsMap.values()];
+  // The obvious way to get all of the rooms would be to iterate over the `RoomList` from the
+  // `Level.GetRooms` method. However, this results in read-only data, and we want to return a
+  // writable object. Instead, we let the heavy lifting be handled by other functions.
+  const roomsInGrid = getRoomsInGrid(includeExtraDimensionalRooms);
+  const roomsOutsideGrid = getRoomsOutsideGrid();
+  return [...roomsInGrid, ...roomsOutsideGrid];
 }
 
 /**
- * Helper function to get the room descriptor for every room on the level except for rooms that are
- * not on the grid. Uses the `Level.GetRooms` method to accomplish this. Rooms without data are
- * assumed to be non-existent and are not added to the list.
+ * Helper function to get the room descriptor for every room on the level that is on the grid. (For
+ * example, Devil Rooms are excluded.)
+ *
+ * Room descriptors without any data are assumed to be non-existent and are not included.
  *
  * @param includeExtraDimensionalRooms Optional. On some floors (e.g. Downpour 2, Mines 2),
- *                                 extra-dimensional rooms are automatically be generated and can be
- *                                 seen when you iterate over the `RoomList`. Default is false.
+ *                                 extra-dimensional rooms are automatically be generated. Default
+ *                                 is false.
  */
 export function getRoomsInGrid(
   includeExtraDimensionalRooms = false,
 ): RoomDescriptor[] {
-  const rooms = getRooms(includeExtraDimensionalRooms);
-  return rooms.filter((roomDescriptor) => roomDescriptor.SafeGridIndex >= 0);
+  const level = game.GetLevel();
+
+  const dimensions = includeExtraDimensionalRooms
+    ? (erange(NUM_DIMENSIONS) as Dimension[])
+    : [Dimension.CURRENT];
+
+  /** We use a map instead of an array because room shapes occupy more than one room grid index. */
+  const roomDescriptorMap = new Map<PtrHash, RoomDescriptor>();
+
+  for (const dimension of dimensions) {
+    for (const roomGridIndex of irange(MAX_LEVEL_GRID_INDEX)) {
+      const roomDescriptor = level.GetRoomByIdx(roomGridIndex, dimension);
+      if (roomDescriptor.Data !== undefined) {
+        const ptrHash = GetPtrHash(roomDescriptor);
+        roomDescriptorMap.set(ptrHash, roomDescriptor);
+      }
+    }
+  }
+
+  return [...roomDescriptorMap.values()];
 }
 
 /**
  * Helper function to get the room descriptor for every room on the level in a specific dimension.
- * Uses the `Level.GetRooms` method to accomplish this. Rooms without data are assumed to be
- * non-existent and are not added to the list.
+ * This will not include any off-grid rooms, such as the Devil Room.
  *
- * @returns A map of room ListIndex to RoomDescriptor.
+ * Room descriptors without any data are assumed to be non-existent and are not included.
  */
 export function getRoomsOfDimension(dimension: Dimension): RoomDescriptor[] {
   const level = game.GetLevel();
 
-  const roomsMap = new Map<int, RoomDescriptor>();
+  /** We use a map instead of an array because room shapes occupy more than one room grid index. */
+  const roomsMap = new Map<PtrHash, RoomDescriptor>();
+
   for (const roomGridIndex of irange(MAX_LEVEL_GRID_INDEX)) {
     const roomDescriptor = level.GetRoomByIdx(roomGridIndex, dimension);
     if (roomDescriptor.Data !== undefined) {
-      roomsMap.set(roomDescriptor.ListIndex, roomDescriptor);
+      const ptrHash = GetPtrHash(roomDescriptor);
+      roomsMap.set(ptrHash, roomDescriptor);
     }
   }
 
   return [...roomsMap.values()];
 }
 
+/**
+ * Helper function to get the room descriptor for every room on the level that is outside of the
+ * grid (like a Devil Room).
+ *
+ * Room descriptors without any data are assumed to be non-existent and are not included.
+ */
+export function getRoomsOutsideGrid(): RoomDescriptor[] {
+  // We filter an array of all rooms instead of iterating over the `GridRoom` enum because it is
+  // possible for mods to insert data at arbitrary negative room grid indexes.
+  const readOnlyRooms = getReadOnlyRooms();
+  const readOnlyRoomsOffGrid = readOnlyRooms.filter(
+    (readOnlyRoomDescriptor) => readOnlyRoomDescriptor.SafeGridIndex < 0,
+  );
+
+  return readOnlyRoomsOffGrid.map((readOnlyRoomDescriptor) =>
+    getRoomDescriptor(readOnlyRoomDescriptor.SafeGridIndex),
+  );
+}
+
 /**
  * Helper function to determine if the current room shape is equal to `RoomShape.1x2` or
  * `RoomShape.2x1`.
@@ -361,10 +366,6 @@ export function inDevilsCrownTreasureRoom(): boolean {
   return hasFlag(roomDescriptor.Flags, RoomDescriptorFlag.DEVIL_TREASURE);
 }
 
-export function inDimension(dimension: Dimension): boolean {
-  return dimension === getDimension();
-}
-
 export function inDoubleTrouble(): boolean {
   const room = game.GetRoom();
   const roomType = room.GetType();
@@ -462,7 +463,7 @@ export function inStartingRoom(): boolean {
 /**
  * Helper function to loop through every room on the floor and see if it has been cleared.
  *
- * This function will only check rooms in the current dimension.
+ * This function will only check rooms inside the gird and inside the current dimension.
  *
  * @param onlyCheckRoomTypes Optional. A whitelist of room types. If specified, room types not in
  *                           the array will be ignored. If not specified, then all rooms will be
@@ -471,7 +472,7 @@ export function inStartingRoom(): boolean {
 export function isAllRoomsClear(onlyCheckRoomTypes?: RoomType[]): boolean {
   const roomTypeWhitelist =
     onlyCheckRoomTypes === undefined ? null : new Set(onlyCheckRoomTypes);
-  const rooms = getRooms();
+  const rooms = getRoomsInGrid();
   const matchingRooms =
     roomTypeWhitelist === null
       ? rooms
@@ -484,87 +485,6 @@ export function isAllRoomsClear(onlyCheckRoomTypes?: RoomType[]): boolean {
   return matchingRooms.every((roomDescriptor) => roomDescriptor.Clear);
 }
 
-export function isDoorSlotValidAtGridIndex(
-  doorSlot: DoorSlot,
-  roomGridIndex: int,
-): boolean {
-  const allowedDoors = getRoomAllowedDoors(roomGridIndex);
-  return allowedDoors.has(doorSlot);
-}
-
-export function isDoorSlotValidAtGridIndexForRedRoom(
-  doorSlot: DoorSlot,
-  roomGridIndex: int,
-): boolean {
-  const doorSlotValidAtGridIndex = isDoorSlotValidAtGridIndex(
-    doorSlot,
-    roomGridIndex,
-  );
-  if (!doorSlotValidAtGridIndex) {
-    return false;
-  }
-
-  const roomShape = getRoomShape(roomGridIndex);
-  if (roomShape === undefined) {
-    return false;
-  }
-
-  const delta = getGridIndexDelta(roomShape, doorSlot);
-  if (delta === undefined) {
-    return false;
-  }
-
-  const redRoomGridIndex = roomGridIndex + delta;
-  return (
-    !roomExists(redRoomGridIndex) &&
-    redRoomGridIndex >= 0 &&
-    redRoomGridIndex <= MAX_LEVEL_GRID_INDEX
-  );
-}
-
-/**
- * Helper function to detect if the provided room was created by the Red Key item. Under the hood,
- * this checks for the `RoomDescriptorFlag.FLAG_RED_ROOM` flag.
- *
- * @param roomGridIndex Optional. Default is the current room index.
- */
-export function isRedKeyRoom(roomGridIndex?: int): boolean {
-  const roomDescriptor = getRoomDescriptor(roomGridIndex);
-  return hasFlag(roomDescriptor.Flags, RoomDescriptorFlag.RED_ROOM);
-}
-
-/**
- * Helper function to determine if the provided room is part of the floor layout. For example, Devil
- * Rooms and the Mega Satan room are not considered to be inside the map.
- *
- * @param roomGridIndex Optional. Default is the current room index.
- */
-export function isRoomInsideMap(roomGridIndex?: int): boolean {
-  if (roomGridIndex === undefined) {
-    roomGridIndex = getRoomGridIndex();
-  }
-
-  return roomGridIndex >= 0;
-}
-
-/** Helper function to check if a room exists at the given room grid index. */
-export function roomExists(roomGridIndex: int): boolean {
-  const roomData = getRoomData(roomGridIndex);
-  return roomData !== undefined;
-}
-
-/**
- * Helper function to get the coordinates of a given grid index. The floor is represented by a 13x13
- * grid. For example, since the starting room is in the center, the starting room grid index of 84
- * be equal to coordinates of (?, ?).
- */
-export function roomGridIndexToXY(roomGridIndex: int): [x: int, y: int] {
-  const x = roomGridIndex % LEVEL_GRID_ROW_WIDTH;
-  const y = Math.floor(roomGridIndex / LEVEL_GRID_ROW_WIDTH);
-
-  return [x, y];
-}
-
 /**
  * If the `Room.Update` method is called in a `POST_NEW_ROOM` callback, then some entities will
  * slide around (such as the player). Since those entity velocities are already at zero, setting
@@ -584,6 +504,11 @@ export function roomUpdateSafe(): void {
   setEntityVelocities(entityVelocities, entities);
 }
 
+/** Helper function to set the backdrop of the current room. */
+export function setBackdrop(backdropType: BackdropType): void {
+  game.ShowHallucination(0, backdropType);
+}
+
 /**
  * Helper function to convert an uncleared room to a cleared room in the `POST_NEW_ROOM` callback.
  * This is useful because if enemies are removed in this callback, a room drop will be awarded and
@@ -635,21 +560,34 @@ export function setRoomUncleared(): void {
 /**
  * Helper function to change the current room. It can be used for both teleportation and "normal"
  * room transitions, depending on what is passed for the `direction` and `roomTransitionAnim`
- * arguments. Use this function instead of invoking the `Game.StartRoomTransition` method directly
- * so that you do not forget to set `Level.LeaveDoor` property and to prevent crashing on invalid
- * room grid indexes.
+ * arguments.
+ *
+ * Use this function instead of invoking the `Game.StartRoomTransition` method directly so that:
+ * - you do not forget to set `Level.LeaveDoor` property
+ * - to prevent crashing on invalid room grid indexes
+ * - to automatically handle Curse of the Maze
  *
  * @param roomGridIndex The room grid index of the destination room.
  * @param direction Optional. Default is `Direction.NO_DIRECTION`.
  * @param roomTransitionAnim Optional. Default is `RoomTransitionAnim.TELEPORT`.
+ * @param force Optional. Whether to temporarily disable Curse of the Maze. Default is false. If set
+ *              to false, then this function may not go to the provided room grid index.
  */
 export function teleport(
   roomGridIndex: int,
   direction = Direction.NO_DIRECTION,
   roomTransitionAnim = RoomTransitionAnim.TELEPORT,
+  force = false,
 ): void {
   const level = game.GetLevel();
 
+  // Before starting a room transition, we must ensure that Curse of the Maze is not in effect, or
+  // else the room transition might send us to the wrong room.
+  const shouldTempDisableCurse = force && hasCurse(LevelCurse.MAZE);
+  if (shouldTempDisableCurse) {
+    level.RemoveCurses(LevelCurse.MAZE);
+  }
+
   const roomData = getRoomData(roomGridIndex);
   if (roomData === undefined) {
     error(
@@ -662,4 +600,8 @@ export function teleport(
   level.LeaveDoor = DoorSlot.NO_DOOR_SLOT;
 
   game.StartRoomTransition(roomGridIndex, direction, roomTransitionAnim);
+
+  if (shouldTempDisableCurse) {
+    level.AddCurse(LevelCurse.MAZE, false);
+  }
 }

package/src/index.ts

@@ -97,9 +97,11 @@ export * from "./functions/collectibles";
 export * from "./functions/collectibleSet";
 export * from "./functions/collectibleTag";
 export * from "./functions/color";
+export * from "./functions/curses";
 export * from "./functions/debug";
 export * from "./functions/deepCopy";
 export * from "./functions/deepCopyTests";
+export * from "./functions/dimensions";
 export * from "./functions/direction";
 export * from "./functions/doors";
 export * from "./functions/easing";
@@ -123,6 +125,7 @@ export * from "./functions/jsonRoom";
 export * from "./functions/kColor";
 export * from "./functions/language";
 export * from "./functions/level";
+export * from "./functions/levelGrid";
 export * from "./functions/log";
 export * from "./functions/map";
 export * from "./functions/math";