isaacscript-common 30.12.10 → 31.0.0

package/src/functions/levelGrid.ts

@@ -10,9 +10,7 @@
 import type { DoorSlot, RoomShape } from "isaac-typescript-definitions";
 import {
   DisplayFlag,
-  DownpourRoomSubType,
   LevelStateFlag,
-  MinesRoomSubType,
   RoomDescriptorFlag,
   RoomType,
 } from "isaac-typescript-definitions";
@@ -36,8 +34,13 @@ import {
   getRoomShape,
 } from "./roomData";
 import { getGridIndexDelta } from "./roomShape";
-import { getRooms, getRoomsInsideGrid, isSecretRoomType } from "./rooms";
-import { asNumber } from "./types";
+import {
+  getRooms,
+  getRoomsInsideGrid,
+  isMineShaft,
+  isMirrorRoom,
+  isSecretRoomType,
+} from "./rooms";
 
 const LEFT = -1;
 const UP = -LEVEL_GRID_ROW_WIDTH;
@@ -123,17 +126,23 @@ export function getAllRoomGridIndexes(): readonly int[] {
  *
  * @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()`.
+ * @param ensureDeadEnd Optional. Whether to pick a valid dead end attached to a normal room. If
+ *                      false, the function will randomly pick from any valid location that would
+ *                      have a red door.
  * @returns Either a tuple of adjacent room grid index, `DoorSlot`, and new room grid index, or
  *          undefined.
  */
-export function getNewRoomCandidate(seedOrRNG: Seed | RNG = getRandomSeed()):
+export function getNewRoomCandidate(
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+  ensureDeadEnd = true,
+):
   | {
       readonly adjacentRoomGridIndex: int;
       readonly doorSlot: DoorSlot;
       readonly newRoomGridIndex: int;
     }
   | undefined {
-  const newRoomCandidatesForLevel = getNewRoomCandidatesForLevel();
+  const newRoomCandidatesForLevel = getNewRoomCandidatesForLevel(ensureDeadEnd);
   if (newRoomCandidatesForLevel.length === 0) {
     return undefined;
   }
@@ -143,14 +152,17 @@ export function getNewRoomCandidate(seedOrRNG: Seed | RNG = getRandomSeed()):
 
 /**
  * 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. (Any potential new rooms cannot be
- * connected to any other existing rooms on the floor.)
+ * a valid spot to insert a brand new room on the floor.
  *
  * @param roomGridIndex Optional. Default is the current room index.
+ * @param ensureDeadEnd Optional. Whether to only include doors that lead to a valid dead end
+ *                      attached to a normal room. If false, the function will include all doors
+ *                      that would have a red door.
  * @returns A array of tuples of `DoorSlot` and room grid index.
  */
 export function getNewRoomCandidatesBesideRoom(
   roomGridIndex?: int,
+  ensureDeadEnd = true,
 ): ReadonlyArray<{ readonly doorSlot: DoorSlot; readonly roomGridIndex: int }> {
   const roomDescriptor = getRoomDescriptor(roomGridIndex);
 
@@ -189,7 +201,7 @@ export function getNewRoomCandidatesBesideRoom(
     // 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(adjacentRoomGridIndex)) {
+    if (ensureDeadEnd && !isDeadEnd(adjacentRoomGridIndex)) {
       continue;
     }
 
@@ -203,13 +215,17 @@ export function getNewRoomCandidatesBesideRoom(
 }
 
 /**
- * Helper function to search through all of the rooms on the floor for a spot to insert a brand new
- * room.
+ * Helper function to get all of the spots on the floor to insert a brand new room.
  *
+ * @param ensureDeadEnd Optional. Whether to only include spots that are a valid dead end attached
+ *                      to a normal room. If false, the function will include all valid spots that
+ *                      have a red door.
  * @returns A array of tuples containing the adjacent room grid index, the `DoorSlot`, and the new
  *          room grid index.
  */
-export function getNewRoomCandidatesForLevel(): ReadonlyArray<{
+export function getNewRoomCandidatesForLevel(
+  ensureDeadEnd = true,
+): ReadonlyArray<{
   readonly adjacentRoomGridIndex: int;
   readonly doorSlot: DoorSlot;
   readonly newRoomGridIndex: int;
@@ -222,21 +238,22 @@ export function getNewRoomCandidatesForLevel(): ReadonlyArray<{
     (room) =>
       room.Data !== undefined &&
       room.Data.Type === RoomType.DEFAULT &&
-      // The mirror room and the mineshaft entrance count as normal rooms, but those are supposed to
-      // be dead ends as well.
-      room.Data.Subtype !== asNumber(DownpourRoomSubType.MIRROR) &&
-      room.Data.Subtype !== asNumber(MinesRoomSubType.MINESHAFT_ENTRANCE),
+      !isMirrorRoom(room.Data) && // Mirror rooms do not count as special rooms.
+      !isMineShaft(room.Data), // Mineshaft rooms do not count as special rooms.
   );
 
+  const roomsToLookThrough = ensureDeadEnd ? normalRooms : rooms;
+
   const newRoomCandidates: Array<{
     readonly adjacentRoomGridIndex: int;
     readonly doorSlot: DoorSlot;
     readonly newRoomGridIndex: int;
   }> = [];
 
-  for (const room of normalRooms) {
+  for (const room of roomsToLookThrough) {
     const newRoomCandidatesBesideRoom = getNewRoomCandidatesBesideRoom(
       room.SafeGridIndex,
+      ensureDeadEnd,
     );
     for (const { doorSlot, roomGridIndex } of newRoomCandidatesBesideRoom) {
       newRoomCandidates.push({
@@ -489,23 +506,29 @@ export function isRoomInsideGrid(roomGridIndex?: int): boolean {
 }
 
 /**
- * Helper function to generate a new room on the floor at a valid dead end attached to a normal
- * room.
+ * Helper function to generate a new room on the floor.
  *
  * 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.
- *
  * @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 `Level.GetDungeonPlacementSeed`.
  *                  Note that the RNG is only used to select the random location to put the room on
  *                  the floor; it does not influence the randomly chosen room contents. (That is
  *                  performed by the game and can not be manipulated prior to its generation.)
+ * @param ensureDeadEnd Optional. Whether to place the room at a valid dead end attached to a normal
+ *                      room. If false, it will randomly appear at any valid location that would
+ *                      have a red door.
+ * @param customRoomData Optional. By default, the newly created room will have data corresponding
+ *                       to the game's randomly generated red room. If you provide this function
+ *                       with room data, it will be used to override the vanilla data.
  * @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(seedOrRNG?: Seed | RNG): int | undefined {
+export function newRoom(
+  seedOrRNG?: Seed | RNG,
+  ensureDeadEnd = true,
+  customRoomData?: RoomConfig,
+): int | undefined {
   const level = game.GetLevel();
 
   if (seedOrRNG === undefined) {
@@ -513,7 +536,7 @@ export function newRoom(seedOrRNG?: Seed | RNG): int | undefined {
   }
   const rng = isRNG(seedOrRNG) ? seedOrRNG : newRNG(seedOrRNG);
 
-  const newRoomCandidate = getNewRoomCandidate(rng);
+  const newRoomCandidate = getNewRoomCandidate(rng, ensureDeadEnd);
   if (newRoomCandidate === undefined) {
     return undefined;
   }
@@ -530,6 +553,10 @@ export function newRoom(seedOrRNG?: Seed | RNG): int | undefined {
     RoomDescriptorFlag.RED_ROOM,
   );
 
+  if (customRoomData !== undefined) {
+    roomDescriptor.Data = customRoomData;
+  }
+
   // By default, the new room will not appear on the map, even if the player has The Mind. Thus, we
   // must manually alter the `DisplayFlags` of the room descriptor.
   const roomData = roomDescriptor.Data;

package/src/functions/logMisc.ts

@@ -328,15 +328,11 @@ export function logRoom(this: void): void {
   const roomData = getRoomData();
 
   log("Logging room information:");
-  if (roomData === undefined) {
-    log("- Room data is undefined.");
-  } else {
-    log(`- Room stage ID: ${roomData.StageID}`);
-    log(
-      `- Type/variant/sub-type: ${roomData.Type}.${roomData.Variant}.${roomData.Subtype}`,
-    );
-    log(`- Name: ${roomData.Name}`);
-  }
+  log(`- Room stage ID: ${roomData.StageID}`);
+  log(
+    `- Type/variant/sub-type: ${roomData.Type}.${roomData.Variant}.${roomData.Subtype}`,
+  );
+  log(`- Name: ${roomData.Name}`);
 
   const roomGridIndexName = GridRoom[roomGridIndex];
   if (roomGridIndexName === undefined) {

package/src/functions/roomData.ts

@@ -31,6 +31,10 @@ export function getRoomAllowedDoors(roomGridIndex?: int): Set<DoorSlot> {
   return allowedDoors;
 }
 
+// We provide an overload because the current room is guaranteed to have data.
+export function getRoomData(): RoomConfig;
+export function getRoomData(roomGridIndex?: int): RoomConfig | undefined;
+
 /**
  * Helper function to get the room data for the provided room.
  *

package/src/functions/roomGrid.ts

@@ -14,7 +14,7 @@ import {
   getRoomShapeBottomRightPosition,
   getRoomShapeTopLeftPosition,
   getRoomShapeWidth,
-  isLRoom,
+  isLRoomShape,
 } from "./roomShape";
 
 /**
@@ -70,7 +70,7 @@ export function isValidGridPosition(
   gridPosition: Vector,
   roomShape: RoomShape,
 ): boolean {
-  return isLRoom(roomShape)
+  return isLRoomShape(roomShape)
     ? isValidGridPositionLRoom(gridPosition, roomShape)
     : isValidGridPositionNormal(gridPosition, roomShape);
 }

package/src/functions/roomShape.ts

@@ -109,7 +109,7 @@ export function getRoomShapeWidth(roomShape: RoomShape): int {
   return ROOM_SHAPE_TO_GRID_WIDTH[roomShape];
 }
 
-export function isLRoom(roomShape: RoomShape): boolean {
+export function isLRoomShape(roomShape: RoomShape): boolean {
   return L_ROOM_SHAPES_SET.has(roomShape);
 }
 

package/src/functions/roomShapeWalls.ts

@@ -5,7 +5,7 @@ import { CornerType } from "../enums/CornerType";
 import type { Corner } from "../interfaces/Corner";
 import { ReadonlySet } from "../types/ReadonlySet";
 import { getGridIndexesBetween } from "./gridIndex";
-import { getRoomShapeCorners, isLRoom } from "./roomShape";
+import { getRoomShapeCorners, isLRoomShape } from "./roomShape";
 import { inBossRoomOf, inHomeCloset } from "./rooms";
 
 const ROOM_SHAPE_TO_WALL_GRID_INDEX_SET: ReadonlyMap<
@@ -26,7 +26,7 @@ function getVanillaWallGridIndexSetForRoomShape(
   roomShape: RoomShape,
 ): ReadonlySet<int> {
   const corners = getRoomShapeCorners(roomShape);
-  const lRoom = isLRoom(roomShape);
+  const lRoom = isLRoomShape(roomShape);
 
   if (lRoom && corners.length !== 6) {
     error(