isaacscript-common 6.19.0 → 6.20.0

package/src/features/extraConsoleCommands/listCommands.ts

@@ -63,6 +63,7 @@ import { getNPCs } from "../../functions/entitiesSpecific";
 import { getEnumValues } from "../../functions/enums";
 import { addFlag } from "../../functions/flag";
 import { spawnGridEntity } from "../../functions/gridEntities";
+import { getRoomGridIndexesForType } from "../../functions/levelGrid";
 import {
   logPlayerEffects,
   logRoom,
@@ -85,7 +86,7 @@ import {
   useActiveItemTemp,
 } from "../../functions/players";
 import { gridCoordinatesToWorldPosition } from "../../functions/roomGrid";
-import { changeRoom, getRoomGridIndexesForType } from "../../functions/rooms";
+import { changeRoom } from "../../functions/rooms";
 import { onSetSeed, restart, setUnseeded } from "../../functions/run";
 import { getGoldenTrinketType } from "../../functions/trinkets";
 import { irange, printConsole, printEnabled } from "../../functions/utils";

package/src/functions/curses.ts

@@ -0,0 +1,9 @@
+import { LevelCurse } from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { hasFlag } from "./flag";
+
+export function hasCurse(curse: LevelCurse): boolean {
+  const level = game.GetLevel();
+  const curses = level.GetCurses();
+  return hasFlag(curses, curse);
+}

package/src/functions/dimensions.ts

@@ -0,0 +1,41 @@
+import { Dimension } from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { NUM_DIMENSIONS } from "../constants";
+import { getRoomGridIndex } from "./roomData";
+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) as Dimension[];
+}
+
+/**
+ * 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.");
+}
+
+export function inDimension(dimension: Dimension): boolean {
+  return dimension === getDimension();
+}

package/src/functions/level.ts

@@ -1,21 +1,18 @@
 import { DoorSlot } from "isaac-typescript-definitions";
 import { game } from "../cachedClasses";
 import { getEnumValues } from "./enums";
-import {
-  getNumRooms,
-  getRooms,
-  isDoorSlotValidAtGridIndexForRedRoom,
-} from "./rooms";
+import { isDoorSlotValidAtGridIndexForRedRoom } from "./levelGrid";
+import { getNumRooms, getRoomsInGrid } from "./rooms";
 
 export function fillLevelWithRedRooms(): void {
   const level = game.GetLevel();
 
-  let numRooms: int;
+  let numRoomsInGrid: int;
   do {
-    const rooms = getRooms();
-    numRooms = rooms.length;
+    const roomsInGrid = getRoomsInGrid();
+    numRoomsInGrid = roomsInGrid.length;
 
-    for (const roomDescriptor of rooms) {
+    for (const roomDescriptor of roomsInGrid) {
       for (const doorSlot of getEnumValues(DoorSlot)) {
         if (
           isDoorSlotValidAtGridIndexForRedRoom(
@@ -27,5 +24,5 @@ export function fillLevelWithRedRooms(): void {
         }
       }
     }
-  } while (numRooms !== getNumRooms());
+  } while (numRoomsInGrid !== getNumRooms());
 }

package/src/functions/levelGrid.ts

@@ -0,0 +1,424 @@
+/**
+ * These functions have to do with the room grid index for the level (i.e. the position that the
+ * room is on the grid that represents the map for the level).
+ *
+ * For functions having to do with the grid index inside of the room, see the "Room Grid" functions.
+ *
+ * @module
+ */
+
+import {
+  DoorSlot,
+  DownpourRoomSubType,
+  MinesRoomSubType,
+  RoomDescriptorFlag,
+  RoomShape,
+  RoomType,
+} from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { LEVEL_GRID_ROW_WIDTH, MAX_LEVEL_GRID_INDEX } from "../constants";
+import { ROOM_SHAPE_TO_DOOR_SLOTS_TO_GRID_INDEX_DELTA } from "../objects/roomShapeToDoorSlotsToGridIndexDelta";
+import { getRandomArrayElement } from "./array";
+import { doorSlotToDoorSlotFlag } from "./doors";
+import { hasFlag } from "./flag";
+import { getRandomSeed } from "./rng";
+import {
+  getRoomAllowedDoors,
+  getRoomData,
+  getRoomDescriptor,
+  getRoomGridIndex,
+  getRoomShape,
+} from "./roomData";
+import { getRooms, getRoomsInGrid } from "./rooms";
+import { getGridIndexDelta } from "./roomShape";
+
+const LEFT = -1;
+const UP = -LEVEL_GRID_ROW_WIDTH;
+const RIGHT = 1;
+const DOWN = LEVEL_GRID_ROW_WIDTH;
+
+const ADJACENT_ROOM_GRID_INDEX_DELTAS: readonly int[] = [LEFT, UP, RIGHT, DOWN];
+
+/**
+ * Helper function to get the room grid indexes that are adjacent to a given room grid index.
+ *
+ * Adjacent room grid indexes that are outside of the grid will not be included in the returned
+ * array.
+ *
+ * If a room grid index is provided that is outside of the grid, then an empty array will be
+ * returned.
+ *
+ * Note that this function does not take the shape of the room into account; it only looks at a
+ * single room grid index.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ */
+export function getAdjacentRoomGridIndexes(roomGridIndex?: int): int[] {
+  const roomGridIndexToUse =
+    roomGridIndex === undefined ? getRoomGridIndex() : roomGridIndex;
+
+  if (!isRoomGridIndexInBounds(roomGridIndexToUse)) {
+    return [];
+  }
+
+  const adjacentRoomGridIndexes = ADJACENT_ROOM_GRID_INDEX_DELTAS.map(
+    (delta) => roomGridIndexToUse + delta,
+  );
+
+  return adjacentRoomGridIndexes.filter((adjacentRoomGridIndex) =>
+    isRoomGridIndexInBounds(adjacentRoomGridIndex),
+  );
+}
+
+/** Helper function to get the room safe 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 pick a random valid spot on the floor to insert a brand new room. Note that
+ * some floors will not have any valid spots. If this is the case, this function will return
+ * undefined.
+ *
+ * @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. Default is `getRandomSeed()`.
+ * @returns Either a tuple of adjacent room grid index, `DoorSlot`, and new room grid index, or
+ *          undefined.
+ */
+export function getNewRoomCandidate(
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+):
+  | [adjacentRoomGridIndex: int, doorSlot: DoorSlot, newRoomGridIndex: int]
+  | undefined {
+  const newRoomCandidatesForFloor = getNewRoomCandidatesForFloor();
+  if (newRoomCandidatesForFloor.length === 0) {
+    return undefined;
+  }
+
+  return getRandomArrayElement(newRoomCandidatesForFloor, seedOrRNG);
+}
+
+/**
+ * Helper function to iterate through the possible doors for a room and see if any of them would be
+ * a valid spot to insert a brand new room on the floor.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ * @returns A array of tuples of `DoorSlot` and room grid index.
+ */
+export function getNewRoomCandidatesBesideRoom(
+  roomGridIndex?: int,
+): Array<[doorSlot: DoorSlot, roomGridIndex: int]> {
+  const roomDescriptor = getRoomDescriptor(roomGridIndex);
+
+  if (!isRoomGridIndexInBounds(roomDescriptor.SafeGridIndex)) {
+    return [];
+  }
+
+  const roomData = roomDescriptor.Data;
+  if (roomData === undefined) {
+    return [];
+  }
+
+  const doorSlotToRoomGridIndexes = getRoomShapeNeighborGridIndexes(
+    roomDescriptor.SafeGridIndex,
+    roomData.Shape,
+  );
+
+  const roomCandidates: Array<[DoorSlot, int]> = [];
+
+  for (const [
+    doorSlot,
+    neighborRoomGridIndex,
+  ] of doorSlotToRoomGridIndexes.entries()) {
+    // The "getRoomShapeNeighborGridIndexes" returns grid indexes for every possible door, but the
+    // real room we are examining will only have a subset of these doors.
+    const doorSlotFlag = doorSlotToDoorSlotFlag(doorSlot);
+    if (!hasFlag(roomData.Doors, doorSlotFlag)) {
+      continue;
+    }
+
+    // If the room already exists, then it is not a possible candidate for a new room.
+    if (roomExists(neighborRoomGridIndex)) {
+      continue;
+    }
+
+    // Check to see if hypothetically creating a room at the given room grid index would be a dead
+    // end. In other words, if we created the room, we would only want it to connect to one other
+    // room (this one).
+    if (!isDeadEnd(neighborRoomGridIndex)) {
+      continue;
+    }
+
+    roomCandidates.push([doorSlot, neighborRoomGridIndex]);
+  }
+
+  return roomCandidates;
+}
+
+/**
+ * Helper function to search through all of the rooms on the floor for a spot to insert a brand new
+ * room.
+ *
+ * @returns A array of tuples of adjacent room grid index, `DoorSlot`, and new room grid index.
+ */
+export function getNewRoomCandidatesForFloor(): Array<
+  [adjacentRoomGridIndex: int, doorSlot: DoorSlot, newRoomGridIndex: int]
+> {
+  const rooms = getRoomsInGrid();
+  const normalRooms = rooms.filter(
+    (room) =>
+      room.Data !== undefined &&
+      room.Data.Type === RoomType.DEFAULT &&
+      room.Data.Subtype !== (DownpourRoomSubType.MIRROR as int) &&
+      room.Data.Subtype !== (MinesRoomSubType.MINESHAFT_ENTRANCE as int),
+  );
+
+  const newRoomCandidates: Array<[int, DoorSlot, int]> = [];
+
+  for (const room of normalRooms) {
+    const newRoomCandidatesBesideRoom = getNewRoomCandidatesBesideRoom(
+      room.SafeGridIndex,
+    );
+    for (const [doorSlot, newRoomGridIndex] of newRoomCandidatesBesideRoom) {
+      newRoomCandidates.push([room.SafeGridIndex, doorSlot, newRoomGridIndex]);
+    }
+  }
+
+  return newRoomCandidates;
+}
+
+/**
+ * Helper function to get an array of all of the safe grid indexes for rooms that match the
+ * specified room type.
+ *
+ * This function only searches through rooms in the current dimension.
+ *
+ * This function is variadic, meaning that you can specify N arguments to get the combined grid
+ * indexes for N room types.
+ */
+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),
+  );
+
+  return matchingRooms.map((roomDescriptor) => roomDescriptor.SafeGridIndex);
+}
+
+/**
+ * Helper function to get the grid indexes of all the rooms connected to the given room index,
+ * taking the shape of the room into account. (This will only include rooms with valid data.)
+ *
+ * Returns an empty map if the provided room grid index is out of bounds or has no associated room
+ * data.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ * @returns A map of `DoorSlot` to the corresponding room grid index.
+ */
+export function getRoomNeighbors(roomGridIndex?: int): Map<DoorSlot, int> {
+  const roomDescriptor = getRoomDescriptor(roomGridIndex);
+
+  if (!isRoomGridIndexInBounds(roomDescriptor.SafeGridIndex)) {
+    return new Map();
+  }
+
+  const roomData = roomDescriptor.Data;
+  if (roomData === undefined) {
+    return new Map();
+  }
+
+  const doorSlotToRoomGridIndexes = getRoomShapeNeighborGridIndexes(
+    roomDescriptor.SafeGridIndex,
+    roomData.Shape,
+  );
+
+  // The "getRoomShapeNeighborGridIndexes" returns grid indexes for every possible door, but the
+  // real room we are examining will only have a subset of these doors. However, we do not have to
+  // worry about filtering the map, since we perform a room existence check below.
+  const roomNeighbors = new Map<DoorSlot, int>();
+  for (const [
+    doorSlot,
+    neighborRoomGridIndex,
+  ] of doorSlotToRoomGridIndexes.entries()) {
+    if (roomExists(neighborRoomGridIndex)) {
+      roomNeighbors.set(doorSlot, neighborRoomGridIndex);
+    }
+  }
+
+  return roomNeighbors;
+}
+
+/**
+ * Helper function to get the room grid index delta that each hypothetical door in a given room
+ * shape would go to.
+ *
+ * This is used by the `getRoomShapeNeighborGridIndexes` function.
+ *
+ * @returns A map of `DoorSlot` to the corresponding room grid index delta.
+ */
+export function getRoomShapeNeighborGridIndexDeltas(
+  roomShape: RoomShape,
+): Map<DoorSlot, int> {
+  return ROOM_SHAPE_TO_DOOR_SLOTS_TO_GRID_INDEX_DELTA[roomShape];
+}
+
+/**
+ * Helper function to get the room grid index that each hypothetical door in a given room shape
+ * would go to. (This will not include room grid indexes that are outside of the grid.)
+ *
+ * @param safeRoomGridIndex This must be the room safe grid index (i.e. the top-left room grid index
+ *                          for the respective room).
+ * @param roomShape The shape of the room.
+ * @returns A map of `DoorSlot` to the corresponding room grid index.
+ */
+export function getRoomShapeNeighborGridIndexes(
+  safeRoomGridIndex: int,
+  roomShape: RoomShape,
+): Map<DoorSlot, int> {
+  const roomShapeNeighborGridIndexDeltas =
+    getRoomShapeNeighborGridIndexDeltas(roomShape);
+
+  const neighborGridIndexes = new Map<DoorSlot, int>();
+  for (const [doorSlot, delta] of roomShapeNeighborGridIndexDeltas.entries()) {
+    const roomGridIndex = safeRoomGridIndex + delta;
+    if (isRoomGridIndexInBounds(roomGridIndex)) {
+      neighborGridIndexes.set(doorSlot, roomGridIndex);
+    }
+  }
+
+  return neighborGridIndexes;
+}
+
+/**
+ * Helper function to check if the given room grid index is a dead end. Specifically, this is
+ * defined as having only one adjacent room that exists.
+ *
+ * Note that this function does not take the shape of the room into account; it only looks at a
+ * single room grid index.
+ *
+ * This function does not care if the given room grid index actually exists, so you can use it to
+ * check if a hypothetical room would be a dead end.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ */
+export function isDeadEnd(roomGridIndex?: int): boolean {
+  const adjacentRoomGridIndexes = getAdjacentRoomGridIndexes(roomGridIndex);
+  const adjacentRoomData = adjacentRoomGridIndexes.map(
+    (adjacentRoomGridIndex) => getRoomData(adjacentRoomGridIndex),
+  );
+  const existingRoomData = adjacentRoomData.filter(
+    (data): data is RoomConfig => data !== undefined,
+  );
+
+  return existingRoomData.length === 1;
+}
+
+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) && isRoomGridIndexInBounds(redRoomGridIndex)
+  );
+}
+
+/**
+ * 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 a given room grid index is inside of the normal 13x13 level grid.
+ *
+ * For example, Devil Rooms and the Mega Satan room are not considered to be inside the grid.
+ */
+export function isRoomGridIndexInBounds(roomGridIndex: int): boolean {
+  return roomGridIndex >= 0 && roomGridIndex <= MAX_LEVEL_GRID_INDEX;
+}
+
+/**
+ * Helper function to generate a new room on the floor at a valid dead end attached to a normal
+ * room.
+ *
+ * Under the hood, this function uses the `Level.MakeRedRoomDoor` method to create the room.
+ *
+ * The newly created room will have data corresponding to the game's randomly generated red room. If
+ * you want to modify this, use the `setRoomData` helper function.
+ *
+ * @returns The room grid index of the new room or undefined if the floor had no valid dead ends to
+ *          place a room.
+ */
+export function newRoom(): int | undefined {
+  const newRoomCandidate = getNewRoomCandidate();
+  if (newRoomCandidate === undefined) {
+    return undefined;
+  }
+  const [adjacentRoomGridIndex, doorSlot, newRoomGridIndex] = newRoomCandidate;
+
+  const level = game.GetLevel();
+  level.MakeRedRoomDoor(adjacentRoomGridIndex, doorSlot);
+
+  return newRoomGridIndex;
+}
+
+/** 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.
+ *
+ * - Since the starting room is in the center, the starting room grid index of 84 is equal to
+ *   coordinates of (6, 6).
+ * - The top-left grid index of 0 is equal to coordinates of: (12, 0)
+ * - The top-right grid index of 12 is equal to coordinates of: (0, 0)
+ * - The bottom-left grid index of 156 is equal to coordinates of: (0, 12)
+ * - The bottom-right grid index of 168 is equal to coordinates of: (12, 12)
+ */
+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];
+}

package/src/functions/roomData.ts

@@ -198,3 +198,15 @@ export function getRoomVisitedCount(roomGridIndex?: int): int {
   const roomDescriptor = getRoomDescriptor(roomGridIndex);
   return roomDescriptor.VisitedCount;
 }
+
+/**
+ * Helper function to set the data for a given room. This will change the room type, contents, and
+ * so on.
+ */
+export function setRoomData(
+  roomGridIndex: int,
+  data: Readonly<RoomConfig>,
+): void {
+  const roomDescriptor = getRoomDescriptor(roomGridIndex);
+  roomDescriptor.Data = data;
+}

package/src/functions/roomGrid.ts

@@ -1,3 +1,12 @@
+/**
+ * These functions have to do with the grid index inside of a room (i.e. the grid index that grid
+ * entities use).
+ *
+ * For functions having to do with the room grid index of the level, see the "Level Grid" functions.
+ *
+ * @module
+ */
+
 import { RoomShape } from "isaac-typescript-definitions";
 import { L_ROOM_SHAPE_TO_RECTANGLES } from "../objects/LRoomShapeToRectangles";
 import { inRectangle } from "./math";