isaacscript-common 6.19.0 → 6.20.0

package/src/functions/rooms.ts

@@ -8,6 +8,7 @@ import {
   GridRoom,
   HomeRoomSubType,
   ItemPoolType,
+  LevelCurse,
   MinibossID,
   RoomDescriptorFlag,
   RoomShape,
@@ -17,14 +18,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 } 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,18 +38,15 @@ import {
   setEntityVelocities,
 } from "./positionVelocity";
 import {
-  getRoomAllowedDoors,
   getRoomData,
-  getRoomDescriptor,
   getRoomDescriptorReadOnly,
   getRoomGridIndex,
   getRoomName,
-  getRoomShape,
   getRoomStageID,
   getRoomSubType,
 } from "./roomData";
-import { getGridIndexDelta } from "./roomShape";
-import { erange, irange } from "./utils";
+import { getGotoCommand } from "./stage";
+import { irange } from "./utils";
 
 /**
  * Helper function for quickly switching to a new room without playing a particular animation. Use
@@ -75,73 +70,53 @@ export function changeRoom(roomGridIndex: int): void {
   game.ChangeRoom(roomGridIndex);
 }
 
-/**
- * Helper function to get an array with every valid `Dimension` (not including `Dimension.CURRENT`).
- */
-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);
-}
-
-/**
- * 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.
- */
-export function getDimension(): Dimension {
-  const level = game.GetLevel();
-  const roomGridIndex = getRoomGridIndex();
-  const roomDescription = level.GetRoomByIdx(roomGridIndex, Dimension.CURRENT);
-  const currentRoomHash = GetPtrHash(roomDescription);
-
-  for (const dimension of getAllDimensions()) {
-    const dimensionRoomDescription = level.GetRoomByIdx(
-      roomGridIndex,
-      dimension,
-    );
-    const dimensionRoomHash = GetPtrHash(dimensionRoomDescription);
-
-    if (dimensionRoomHash === currentRoomHash) {
-      return dimension;
-    }
-  }
-
-  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();
+  const rooms = getRoomsInGrid();
   return rooms.length;
 }
 
 /**
- * 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.
+ * 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.
  *
- * This function is variadic, meaning that you can specify N arguments to get the combined grid
- * indexes for N room types.
+ * @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 +132,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,9 +142,12 @@ 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. (Off-grid rooms will only be included if they the data exists,
+ * which only usually happens once they have been visited at least once.)
+ *
+ * Under the hood, this function uses the `Level.GetRooms` method to accomplish this. Rooms without
+ * data are assumed to be non-existent and are not added to the list.
  *
  * @param includeExtraDimensionalRooms Optional. On some floors (e.g. Downpour 2, Mines 2),
  *                                 extra-dimensional rooms are automatically generated and can be
@@ -215,21 +159,23 @@ export function getRooms(
   const level = game.GetLevel();
   const roomList = level.GetRooms();
 
+  /** Indexed by room safe grid index. We use a map to avoid adding extra dimensional rooms. */
   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);
-      }
+
+  for (let i = 0; i < roomList.Size; i++) {
+    const roomDescriptor = roomList.Get(i);
+    if (roomDescriptor === undefined || roomDescriptor.Data === undefined) {
+      continue;
     }
-  } else {
-    for (const roomGridIndex of irange(MAX_LEVEL_GRID_INDEX)) {
-      const roomDescriptor = level.GetRoomByIdx(roomGridIndex);
-      if (roomDescriptor.Data !== undefined) {
-        roomsMap.set(roomDescriptor.ListIndex, roomDescriptor);
-      }
+
+    if (
+      !includeExtraDimensionalRooms &&
+      roomsMap.has(roomDescriptor.SafeGridIndex)
+    ) {
+      continue;
     }
+
+    roomsMap.set(roomDescriptor.SafeGridIndex, roomDescriptor);
   }
 
   return [...roomsMap.values()];
@@ -237,8 +183,10 @@ export function getRooms(
 
 /**
  * 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.
+ * not on the grid.
+ *
+ * Under the hood, this function uses the `Level.GetRooms` method to accomplish this. Rooms without
+ * data are assumed to be non-existent and are not added to the list.
  *
  * @param includeExtraDimensionalRooms Optional. On some floors (e.g. Downpour 2, Mines 2),
  *                                 extra-dimensional rooms are automatically be generated and can be
@@ -253,15 +201,19 @@ export function getRoomsInGrid(
 
 /**
  * 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.
+ *
+ * Under the hood, this function uses the `Level.GetRooms` method to accomplish this. Rooms without
+ * data are assumed to be non-existent and are not added to the list.
  *
  * @returns A map of room ListIndex to RoomDescriptor.
  */
 export function getRoomsOfDimension(dimension: Dimension): RoomDescriptor[] {
   const level = game.GetLevel();
 
+  /** We use a map instead of an array because room shapes occupy more than one room grid index. */
   const roomsMap = new Map<int, RoomDescriptor>();
+
   for (const roomGridIndex of irange(MAX_LEVEL_GRID_INDEX)) {
     const roomDescriptor = level.GetRoomByIdx(roomGridIndex, dimension);
     if (roomDescriptor.Data !== undefined) {
@@ -361,10 +313,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();
@@ -484,87 +432,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
@@ -635,21 +502,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 +542,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";