isaacscript-common 6.20.1 → 6.22.0

package/src/functions/rooms.ts

@@ -1,27 +1,24 @@
 import {
   AngelRoomSubType,
+  BackdropType,
   BossID,
   Dimension,
-  Direction,
   DoorSlot,
   DungeonSubType,
   GridRoom,
   HomeRoomSubType,
   ItemPoolType,
-  LevelCurse,
   MinibossID,
   RoomDescriptorFlag,
   RoomShape,
-  RoomTransitionAnim,
   RoomType,
   SoundEffect,
   StageID,
 } from "isaac-typescript-definitions";
 import { game, sfxManager } from "../cachedClasses";
-import { MAX_LEVEL_GRID_INDEX } from "../constants";
+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,
@@ -39,14 +36,16 @@ import {
 } from "./positionVelocity";
 import {
   getRoomData,
+  getRoomDescriptor,
   getRoomDescriptorReadOnly,
   getRoomGridIndex,
   getRoomName,
   getRoomStageID,
   getRoomSubType,
 } from "./roomData";
+import { reloadRoom } from "./roomTransition";
 import { getGotoCommand } from "./stage";
-import { irange } from "./utils";
+import { erange, irange } from "./utils";
 
 /**
  * Helper function for quickly switching to a new room without playing a particular animation. Use
@@ -79,6 +78,36 @@ export function getNumRooms(): int {
   return rooms.length;
 }
 
+/**
+ * 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 getReadOnlyRooms(): Array<Readonly<RoomDescriptor>> {
+  const level = game.GetLevel();
+  const roomList = level.GetRooms();
+
+  const readOnlyRoomDescriptors: Array<Readonly<RoomDescriptor>> = [];
+
+  for (let i = 0; i < roomList.Size; i++) {
+    const readOnlyRoomDescriptor = roomList.Get(i);
+    if (
+      readOnlyRoomDescriptor !== undefined &&
+      readOnlyRoomDescriptor.Data !== undefined
+    ) {
+      readOnlyRoomDescriptors.push(readOnlyRoomDescriptor);
+    }
+  }
+
+  return readOnlyRoomDescriptors;
+}
+
 /**
  * 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
@@ -110,13 +139,7 @@ export function getRoomDataForTypeVariant(
   const newRoomData = getRoomData(GridRoom.DEBUG);
 
   if (cancelRoomTransition) {
-    const roomGridIndex = getRoomGridIndex();
-    teleport(
-      roomGridIndex,
-      Direction.NO_DIRECTION,
-      RoomTransitionAnim.FADE,
-      true,
-    );
+    reloadRoom();
   }
 
   return newRoomData;
@@ -146,87 +169,105 @@ export function getRoomTypeName(roomType: RoomType): string {
 
 /**
  * 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.)
+ * 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.
+ * 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();
-
-  /** Indexed by room safe grid index. We use a map to avoid adding extra dimensional rooms. */
-  const roomsMap = new Map<int, RoomDescriptor>();
-
-  for (let i = 0; i < roomList.Size; i++) {
-    const roomDescriptor = roomList.Get(i);
-    if (roomDescriptor === undefined || roomDescriptor.Data === undefined) {
-      continue;
-    }
-
-    if (
-      !includeExtraDimensionalRooms &&
-      roomsMap.has(roomDescriptor.SafeGridIndex)
-    ) {
-      continue;
-    }
-
-    roomsMap.set(roomDescriptor.SafeGridIndex, 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.
+ * Helper function to get the room descriptor for every room on the level that is on the grid. (For
+ * example, Devil Rooms are excluded.)
  *
- * 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.
+ * 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.
  * 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.
+ * 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();
 
   /** We use a map instead of an array because room shapes occupy more than one room grid index. */
-  const roomsMap = new Map<int, RoomDescriptor>();
+  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`.
@@ -413,7 +454,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
@@ -422,7 +463,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
@@ -454,6 +495,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
@@ -501,52 +547,3 @@ export function setRoomUncleared(): void {
   room.SetClear(false);
   closeAllDoors();
 }
-
-/**
- * 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
- * - 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(
-      `Failed to change the room to grid index ${roomGridIndex} because that room does not exist.`,
-    );
-  }
-
-  // This must be set before every `Game.StartRoomTransition` method invocation or else the function
-  // can send you to the wrong room.
-  level.LeaveDoor = DoorSlot.NO_DOOR_SLOT;
-
-  game.StartRoomTransition(roomGridIndex, direction, roomTransitionAnim);
-
-  if (shouldTempDisableCurse) {
-    level.AddCurse(LevelCurse.MAZE, false);
-  }
-}

package/src/index.ts

@@ -127,6 +127,7 @@ export * from "./functions/language";
 export * from "./functions/level";
 export * from "./functions/levelGrid";
 export * from "./functions/log";
+export * from "./functions/logEntities";
 export * from "./functions/map";
 export * from "./functions/math";
 export * from "./functions/mergeTests";

package/src/interfaces/private/CustomTrapdoorDescription.ts

@@ -1,7 +1,7 @@
-import { LevelStage, StageType } from "isaac-typescript-definitions";
+import { TrapdoorDestination } from "../../types/TrapdoorDestination";
 
 export interface CustomTrapdoorDescription {
   open: boolean;
-  destination: [stage: LevelStage, stageType: StageType] | string;
+  destination: TrapdoorDestination;
   firstSpawn: boolean;
 }

package/src/objects/backdropTypeToRockAltType.ts

@@ -35,12 +35,12 @@ export const BACKDROP_TYPE_TO_ROCK_ALT_TYPE: {
   [BackdropType.GREED_SHOP]: RockAltType.URN, // 28
   [BackdropType.DUNGEON]: RockAltType.URN, // 29
   [BackdropType.SACRIFICE]: RockAltType.SKULL, // 30
-  [BackdropType.DOWNPOUR]: RockAltType.BUCKET, // 31
+  [BackdropType.DOWNPOUR]: RockAltType.BUCKET_DOWNPOUR, // 31
   [BackdropType.MINES]: RockAltType.MUSHROOM, // 32
   [BackdropType.MAUSOLEUM]: RockAltType.SKULL, // 33
   [BackdropType.CORPSE]: RockAltType.POLYP, // 34
   [BackdropType.PLANETARIUM]: RockAltType.URN, // 35
-  [BackdropType.DOWNPOUR_ENTRANCE]: RockAltType.BUCKET, // 36
+  [BackdropType.DOWNPOUR_ENTRANCE]: RockAltType.BUCKET_DOWNPOUR, // 36
   [BackdropType.MINES_ENTRANCE]: RockAltType.MUSHROOM, // 37
   [BackdropType.MAUSOLEUM_ENTRANCE]: RockAltType.SKULL, // 38
   [BackdropType.CORPSE_ENTRANCE]: RockAltType.SKULL, // 39
@@ -49,7 +49,7 @@ export const BACKDROP_TYPE_TO_ROCK_ALT_TYPE: {
   [BackdropType.MAUSOLEUM_4]: RockAltType.SKULL, // 42
   [BackdropType.CORPSE_2]: RockAltType.POLYP, // 43
   [BackdropType.CORPSE_3]: RockAltType.POLYP, // 44
-  [BackdropType.DROSS]: RockAltType.BUCKET, // 45
+  [BackdropType.DROSS]: RockAltType.BUCKET_DROSS, // 45
   [BackdropType.ASHPIT]: RockAltType.MUSHROOM, // 46
   [BackdropType.GEHENNA]: RockAltType.SKULL, // 47
   [BackdropType.MORTIS]: RockAltType.POLYP, // 48

package/src/types/TrapdoorDestination.ts

@@ -0,0 +1,5 @@
+import { LevelStage, StageType } from "isaac-typescript-definitions";
+
+export type TrapdoorDestination =
+  | [stage: LevelStage, stageType: StageType]
+  | [customStageName: string, floorNum: int];