isaacscript-common 13.0.0 → 13.1.0

package/src/functions/roomShapeWalls.ts

@@ -0,0 +1,359 @@
+import { BossID, RoomShape } from "isaac-typescript-definitions";
+import { game } from "../core/cachedClasses";
+import { CornerType } from "../enums/CornerType";
+import { Corner } from "../interfaces/Corner";
+import { getEnumValues } from "./enums";
+import { getGridIndexesBetween } from "./gridIndex";
+import { inBossRoomOf, inHomeCloset } from "./rooms";
+import { getRoomShapeCorners, isLRoom } from "./roomShape";
+
+const ROOM_SHAPE_TO_WALL_GRID_INDEX_SET = getRoomShapeToWallGridIndexSet();
+
+function getRoomShapeToWallGridIndexSet(): ReadonlyMap<
+  RoomShape,
+  ReadonlySet<int>
+> {
+  const roomShapeToWallGridIndexSet = new Map<RoomShape, ReadonlySet<int>>();
+
+  for (const roomShape of getEnumValues(RoomShape)) {
+    const gridIndexSet = getVanillaWallGridIndexSetForRoomShape(roomShape);
+    roomShapeToWallGridIndexSet.set(roomShape, gridIndexSet);
+  }
+
+  return roomShapeToWallGridIndexSet;
+}
+
+function getVanillaWallGridIndexSetForRoomShape(
+  roomShape: RoomShape,
+): ReadonlySet<int> {
+  const corners = getRoomShapeCorners(roomShape);
+  const lRoom = isLRoom(roomShape);
+
+  if (lRoom && corners.length !== 6) {
+    error(
+      `Failed to get the correct amount of corners for: RoomShape.${RoomShape[roomShape]} (${roomShape})`,
+    );
+  }
+
+  switch (roomShape) {
+    // 9
+    case RoomShape.LTL: {
+      const [topMiddle, topRight, middleLeft, middle, bottomLeft, bottomRight] =
+        corners as [Corner, Corner, Corner, Corner, Corner, Corner];
+      return new Set([
+        // Horizontal
+        ...getGridIndexesBetween(
+          topMiddle.gridIndex,
+          topRight.gridIndex,
+          roomShape,
+        ),
+        ...getGridIndexesBetween(
+          middleLeft.gridIndex,
+          middle.gridIndex,
+          roomShape,
+        ),
+        ...getGridIndexesBetween(
+          bottomLeft.gridIndex,
+          bottomRight.gridIndex,
+          roomShape,
+        ),
+
+        // Vertical
+        ...getGridIndexesBetween(
+          middleLeft.gridIndex,
+          bottomLeft.gridIndex,
+          roomShape,
+        ),
+        ...getGridIndexesBetween(
+          topMiddle.gridIndex,
+          middle.gridIndex,
+          roomShape,
+        ),
+        ...getGridIndexesBetween(
+          topRight.gridIndex,
+          bottomRight.gridIndex,
+          roomShape,
+        ),
+      ]);
+    }
+
+    // 10
+    case RoomShape.LTR: {
+      const [topLeft, topMiddle, middle, middleRight, bottomLeft, bottomRight] =
+        corners as [Corner, Corner, Corner, Corner, Corner, Corner];
+      return new Set([
+        // Horizontal
+        ...getGridIndexesBetween(
+          topLeft.gridIndex,
+          topMiddle.gridIndex,
+          roomShape,
+        ),
+        ...getGridIndexesBetween(
+          middle.gridIndex,
+          middleRight.gridIndex,
+          roomShape,
+        ),
+        ...getGridIndexesBetween(
+          bottomLeft.gridIndex,
+          bottomRight.gridIndex,
+          roomShape,
+        ),
+
+        // Vertical
+        ...getGridIndexesBetween(
+          topLeft.gridIndex,
+          bottomLeft.gridIndex,
+          roomShape,
+        ),
+        ...getGridIndexesBetween(
+          topMiddle.gridIndex,
+          middle.gridIndex,
+          roomShape,
+        ),
+        ...getGridIndexesBetween(
+          middleRight.gridIndex,
+          bottomRight.gridIndex,
+          roomShape,
+        ),
+      ]);
+    }
+
+    // 11
+    case RoomShape.LBL: {
+      const [topLeft, topRight, middleLeft, middle, bottomMiddle, bottomRight] =
+        corners as [Corner, Corner, Corner, Corner, Corner, Corner];
+      return new Set([
+        // Horizontal
+        ...getGridIndexesBetween(
+          topLeft.gridIndex,
+          topRight.gridIndex,
+          roomShape,
+        ),
+        ...getGridIndexesBetween(
+          middleLeft.gridIndex,
+          middle.gridIndex,
+          roomShape,
+        ),
+        ...getGridIndexesBetween(
+          bottomMiddle.gridIndex,
+          bottomRight.gridIndex,
+          roomShape,
+        ),
+
+        // Vertical
+        ...getGridIndexesBetween(
+          topLeft.gridIndex,
+          middleLeft.gridIndex,
+          roomShape,
+        ),
+        ...getGridIndexesBetween(
+          middle.gridIndex,
+          bottomMiddle.gridIndex,
+          roomShape,
+        ),
+        ...getGridIndexesBetween(
+          topRight.gridIndex,
+          bottomRight.gridIndex,
+          roomShape,
+        ),
+      ]);
+    }
+
+    // 12
+    case RoomShape.LBR: {
+      const [topLeft, topRight, middle, middleRight, bottomLeft, bottomMiddle] =
+        corners as [Corner, Corner, Corner, Corner, Corner, Corner];
+      return new Set([
+        // Horizontal
+        ...getGridIndexesBetween(
+          topLeft.gridIndex,
+          topRight.gridIndex,
+          roomShape,
+        ),
+        ...getGridIndexesBetween(
+          middle.gridIndex,
+          middleRight.gridIndex,
+          roomShape,
+        ),
+        ...getGridIndexesBetween(
+          bottomLeft.gridIndex,
+          bottomMiddle.gridIndex,
+          roomShape,
+        ),
+
+        // Vertical
+        ...getGridIndexesBetween(
+          topLeft.gridIndex,
+          bottomLeft.gridIndex,
+          roomShape,
+        ),
+        ...getGridIndexesBetween(
+          middle.gridIndex,
+          bottomMiddle.gridIndex,
+          roomShape,
+        ),
+        ...getGridIndexesBetween(
+          topRight.gridIndex,
+          middleRight.gridIndex,
+          roomShape,
+        ),
+      ]);
+    }
+
+    default: {
+      return getWallGridIndexSetForRectangleRoomShape(roomShape, corners);
+    }
+  }
+}
+
+/**
+ * Providing the room shape is necessary so that the `getGridIndexesBetween` function can use the
+ * corresponding grid width.
+ */
+function getWallGridIndexSetForRectangleRoomShape(
+  roomShape: RoomShape,
+  corners: readonly Corner[],
+): ReadonlySet<int> {
+  if (corners.length !== 4) {
+    error(
+      "Failed to get the correct amount of corners for rectangular room shape.",
+    );
+  }
+
+  const [topLeft, topRight, bottomLeft, bottomRight] = corners as [
+    Corner,
+    Corner,
+    Corner,
+    Corner,
+  ];
+
+  return new Set([
+    // Horizontal
+    ...getGridIndexesBetween(topLeft.gridIndex, topRight.gridIndex, roomShape),
+    ...getGridIndexesBetween(
+      bottomLeft.gridIndex,
+      bottomRight.gridIndex,
+      roomShape,
+    ),
+
+    // Vertical
+    ...getGridIndexesBetween(
+      topLeft.gridIndex,
+      bottomLeft.gridIndex,
+      roomShape,
+    ),
+    ...getGridIndexesBetween(
+      topRight.gridIndex,
+      bottomRight.gridIndex,
+      roomShape,
+    ),
+  ]);
+}
+
+/** The Home closet is is 9x3, which is different from `RoomShape.IH` (which is 13x3). */
+const HOME_CLOSET_CORNERS = [
+  {
+    type: CornerType.TOP_LEFT,
+    gridIndex: 30,
+    position: Vector(60, 220),
+  },
+  {
+    type: CornerType.TOP_RIGHT,
+    gridIndex: 38,
+    position: Vector(340, 220),
+  },
+  {
+    type: CornerType.BOTTOM_LEFT,
+    gridIndex: 90,
+    position: Vector(60, 340),
+  },
+  {
+    type: CornerType.BOTTOM_RIGHT,
+    gridIndex: 98,
+    position: Vector(340, 340),
+  },
+] as const;
+
+const HOME_CLOSET_CORNERS_SET = getWallGridIndexSetForRectangleRoomShape(
+  RoomShape.IH,
+  HOME_CLOSET_CORNERS,
+);
+
+/**
+ * The Mother Boss Room is 15x11, which is different from `RoomShape.SHAPE_1x2` (which is 15x16).
+ */
+const MOTHER_ROOM_CORNERS = [
+  {
+    type: CornerType.TOP_LEFT,
+    gridIndex: 0,
+    position: Vector(60, 140),
+  },
+  {
+    type: CornerType.TOP_RIGHT,
+    gridIndex: 14,
+    position: Vector(580, 140),
+  },
+  {
+    type: CornerType.BOTTOM_LEFT,
+    gridIndex: 150,
+    position: Vector(60, 500),
+  },
+  {
+    type: CornerType.BOTTOM_RIGHT,
+    gridIndex: 164,
+    position: Vector(580, 500),
+  },
+] as const;
+
+const MOTHER_ROOM_CORNERS_SET = getWallGridIndexSetForRectangleRoomShape(
+  RoomShape.SHAPE_1x2,
+  MOTHER_ROOM_CORNERS,
+);
+
+/**
+ * Helper function to determine if a given wall is a "real" wall generated by the vanilla game. This
+ * is useful because mods can use custom spawned walls as a stand-in for custom grid entities.
+ *
+ * This function checks for identity via a combination of `StageAPI.IsCustomGrid` and the
+ * `isVanillaWallGridIndex` function.
+ */
+export function isVanillaWall(gridEntity: GridEntity): boolean {
+  const gridIndex = gridEntity.GetGridIndex();
+
+  if (StageAPI !== undefined && StageAPI.IsCustomGrid(gridIndex)) {
+    return false;
+  }
+
+  return isVanillaWallGridIndex(gridIndex);
+}
+
+/**
+ * Helper function to determine if a given grid index should have a wall generated by the vanilla
+ * game. This is useful as a mechanism to distinguish between real walls and custom walls spawned by
+ * mods.
+ *
+ * This function properly handles the special cases of the Mother boss room and the Home closet
+ * rooms, which are both non-standard room shapes.
+ */
+export function isVanillaWallGridIndex(gridIndex: int): boolean {
+  const room = game.GetRoom();
+  const roomShape = room.GetRoomShape();
+
+  // Handle the special cases of non-standard room shapes.
+  let wallGridIndexSet: ReadonlySet<int> | undefined;
+  if (inHomeCloset()) {
+    wallGridIndexSet = HOME_CLOSET_CORNERS_SET;
+  } else if (inBossRoomOf(BossID.MOTHER)) {
+    wallGridIndexSet = MOTHER_ROOM_CORNERS_SET;
+  } else {
+    wallGridIndexSet = ROOM_SHAPE_TO_WALL_GRID_INDEX_SET.get(roomShape);
+  }
+
+  if (wallGridIndexSet === undefined) {
+    error(
+      `Failed to find the wall grid index set for: RoomShape.${RoomShape[roomShape]} (${roomShape})`,
+    );
+  }
+
+  return wallGridIndexSet.has(gridIndex);
+}

package/src/functions/rooms.ts

@@ -9,6 +9,7 @@ import {
   GridRoom,
   HomeRoomSubType,
   ItemPoolType,
+  LevelStage,
   MinibossID,
   RoomDescriptorFlag,
   RoomShape,
@@ -47,7 +48,7 @@ import {
 import { reloadRoom } from "./roomTransition";
 import { getGotoCommand } from "./stage";
 import { asNumber } from "./types";
-import { irange } from "./utils";
+import { iRange } from "./utils";
 
 /**
  * Helper function for quickly switching to a new room without playing a particular animation. Use
@@ -216,7 +217,7 @@ export function getRoomsInsideGrid(
   const roomDescriptorMap = new Map<PtrHash, RoomDescriptor>();
 
   for (const dimension of dimensions) {
-    for (const roomGridIndex of irange(MAX_LEVEL_GRID_INDEX)) {
+    for (const roomGridIndex of iRange(MAX_LEVEL_GRID_INDEX)) {
       const roomDescriptor = level.GetRoomByIdx(roomGridIndex, dimension);
       if (roomDescriptor.Data !== undefined) {
         const ptrHash = GetPtrHash(roomDescriptor);
@@ -240,7 +241,7 @@ export function getRoomsOfDimension(dimension: Dimension): 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)) {
+  for (const roomGridIndex of iRange(MAX_LEVEL_GRID_INDEX)) {
     const roomDescriptor = level.GetRoomByIdx(roomGridIndex, dimension);
     if (roomDescriptor.Data !== undefined) {
       const ptrHash = GetPtrHash(roomDescriptor);
@@ -375,6 +376,24 @@ export function inGenesisRoom(): boolean {
   return roomGridIndex === asNumber(GridRoom.GENESIS);
 }
 
+/**
+ * Helper function to check if the current room is either the left Home closet (behind the red door)
+ * or the right Home closet (with one random pickup).
+ *
+ * Home closets have a unique shape that is different from any other room in the game.
+ */
+export function inHomeCloset(): boolean {
+  const level = game.GetLevel();
+  const stage = level.GetStage();
+  const roomSubType = getRoomSubType();
+
+  return (
+    stage === LevelStage.HOME &&
+    (roomSubType === asNumber(HomeRoomSubType.CLOSET_LEFT) ||
+      roomSubType === asNumber(HomeRoomSubType.CLOSET_RIGHT))
+  );
+}
+
 /** Helper function to determine if the current room shape is one of the four L room shapes. */
 export function inLRoom(): boolean {
   const room = game.GetRoom();

package/src/functions/set.ts

@@ -136,6 +136,18 @@ export function getSortedSetValues<T>(set: Set<T> | ReadonlySet<T>): T[] {
   return array;
 }
 
+/**
+ * Helper function to add one or more elements to a set at once without having to repeatedly call
+ * the `Set.add` method.
+ *
+ * This function is variadic, meaning that you can pass as many things as you want to add.
+ */
+export function setAdd<T>(set: Set<T>, ...elements: T[]): void {
+  for (const element of elements) {
+    set.add(element);
+  }
+}
+
 /** Helper function to sum every value in a set together. */
 export function sumSet(set: Set<number> | ReadonlySet<number>): number {
   const values = [...set.values()];

package/src/functions/sprites.ts

@@ -1,6 +1,6 @@
 import { EMPTY_PNG_PATH, VectorZero } from "../core/constants";
 import { kColorEquals } from "./kColor";
-import { erange } from "./utils";
+import { eRange } from "./utils";
 
 /**
  * Helper function to clear all layers or specific layers from a sprite.
@@ -17,7 +17,7 @@ import { erange } from "./utils";
 export function clearSprite(sprite: Sprite, ...layerIDs: int[]): void {
   if (layerIDs.length === 0) {
     const numLayers = sprite.GetLayerCount();
-    layerIDs = erange(numLayers);
+    layerIDs = eRange(numLayers);
   }
 
   for (const layerID of layerIDs) {

package/src/functions/trinkets.ts

@@ -22,7 +22,7 @@ import { isTrinket } from "./pickupVariants";
 import { isCharacter } from "./players";
 import { clearSprite } from "./sprites";
 import { asNumber } from "./types";
-import { irange } from "./utils";
+import { iRange } from "./utils";
 
 /**
  * Add this to a `TrinketType` to get the corresponding golden trinket type.
@@ -145,7 +145,7 @@ export function getTrinketName(trinketType: TrinketType): string {
 
 /** Helper function to get an array that represents every vanilla trinket type. */
 export function getVanillaTrinketTypes(): TrinketType[] {
-  return irange(FIRST_TRINKET_TYPE, LAST_VANILLA_TRINKET_TYPE);
+  return iRange(FIRST_TRINKET_TYPE, LAST_VANILLA_TRINKET_TYPE);
 }
 
 /**

package/src/functions/utils.ts

@@ -3,22 +3,25 @@ import { game } from "../core/cachedClasses";
 import { CONSOLE_COMMANDS_SET } from "../sets/consoleCommandsSet";
 
 /**
- * Helper function to return an array with the elements from start to end. It is inclusive at the
- * start and exclusive at the end. (The "e" stands for exclusive.)
+ * Helper function to return an array of integers with the specified range, inclusive on the lower
+ * end and exclusive on the high end. (The "e" stands for exclusive.)
  *
- * If only one argument is specified, then it will assume that the start is 0.
+ * - For example, `eRange(1, 3)` will return `[1, 2]`.
+ * - For example, `eRange(2)` will return `[0, 1]`.
  *
- * - For example, `erange(1, 3)` will return `[1, 2]`.
- * - For example, `erange(2)` will return `[0, 1]`.
+ * @param start The number to start at.
+ * @param end Optional. The number to end at. If not specified, then the start will be 0 and the
+ *            first argument will be the end.
+ * @param increment Optional. The increment to use. Default is 1.
  */
-export function erange(start: int, end?: int): int[] {
+export function eRange(start: int, end?: int, increment = 1): int[] {
   if (end === undefined) {
     end = start;
     start = 0;
   }
 
   const array: int[] = [];
-  for (let i = start; i < end; i++) {
+  for (let i = start; i < end; i += increment) {
     array.push(i);
   }
 
@@ -43,22 +46,25 @@ export function getTraversalDescription(
 }
 
 /**
- * Helper function to return an array with the elements from start to end, inclusive. (The "i"
- * stands for inclusive.)
+ * Helper function to return an array of integers with the specified range, inclusive on both ends.
+ * (The "i" stands for inclusive.)
  *
- * If only one argument is specified, then it will assume that the start is 0.
+ * - For example, `iRange(1, 3)` will return `[1, 2, 3]`.
+ * - For example, `iRange(2)` will return `[0, 1, 2]`.
  *
- * - For example, `irange(1, 3)` will return `[1, 2, 3]`.
- * - For example, `irange(2)` will return `[0, 1, 2]`.
+ * @param start The number to start at.
+ * @param end Optional. The number to end at. If not specified, then the start will be 0 and the
+ *            first argument will be the end.
+ * @param increment Optional. The increment to use. Default is 1.
  */
-export function irange(start: int, end?: int): int[] {
+export function iRange(start: int, end?: int, increment = 1): int[] {
   if (end === undefined) {
     end = start;
     start = 0;
   }
 
   const array: int[] = [];
-  for (let i = start; i <= end; i++) {
+  for (let i = start; i <= end; i += increment) {
     array.push(i);
   }
 

package/src/index.ts

@@ -74,6 +74,7 @@ export * from "./functions/doors";
 export * from "./functions/easing";
 export * from "./functions/eden";
 export * from "./functions/effects";
+export * from "./functions/emptyRoom";
 export * from "./functions/entities";
 export * from "./functions/entitiesSpecific";
 export * from "./functions/entityTypes";
@@ -84,6 +85,7 @@ export * from "./functions/flying";
 export * from "./functions/globals";
 export * from "./functions/gridEntities";
 export * from "./functions/gridEntitiesSpecific";
+export * from "./functions/gridIndex";
 export * from "./functions/hex";
 export * from "./functions/initArray";
 export * from "./functions/input";
@@ -126,6 +128,7 @@ export * from "./functions/roomData";
 export * from "./functions/roomGrid";
 export * from "./functions/rooms";
 export * from "./functions/roomShape";
+export * from "./functions/roomShapeWalls";
 export * from "./functions/roomTransition";
 export * from "./functions/run";
 export * from "./functions/saveFile";

package/src/interfaces/Corner.ts

@@ -7,5 +7,14 @@ import { CornerType } from "../enums/CornerType";
  */
 export interface Corner {
   readonly type: CornerType;
+
+  /** The grid index of the corresponding wall tile. */
+  readonly gridIndex: int;
+
+  /**
+   * The position is not the same as the center of the corresponding grid index. Rather, it is the
+   * exact position of the corner, which will be offset from the grid index position by half of a
+   * grid tile.
+   */
   readonly position: Readonly<Vector>;
 }