isaacscript-common 30.12.11 → 31.0.1

package/dist/src/functions/rooms.lua

@@ -7,9 +7,9 @@ local Map = ____lualib.Map
 local __TS__Spread = ____lualib.__TS__Spread
 local __TS__ArrayFilter = ____lualib.__TS__ArrayFilter
 local __TS__ArrayMap = ____lualib.__TS__ArrayMap
+local __TS__ArrayEvery = ____lualib.__TS__ArrayEvery
 local __TS__StringIncludes = ____lualib.__TS__StringIncludes
 local __TS__ArrayIncludes = ____lualib.__TS__ArrayIncludes
-local __TS__ArrayEvery = ____lualib.__TS__ArrayEvery
 local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local AngelRoomSubType = ____isaac_2Dtypescript_2Ddefinitions.AngelRoomSubType
@@ -19,7 +19,6 @@ local DownpourRoomSubType = ____isaac_2Dtypescript_2Ddefinitions.DownpourRoomSub
 local DungeonSubType = ____isaac_2Dtypescript_2Ddefinitions.DungeonSubType
 local GridRoom = ____isaac_2Dtypescript_2Ddefinitions.GridRoom
 local HomeRoomSubType = ____isaac_2Dtypescript_2Ddefinitions.HomeRoomSubType
-local LevelStage = ____isaac_2Dtypescript_2Ddefinitions.LevelStage
 local RoomDescriptorFlag = ____isaac_2Dtypescript_2Ddefinitions.RoomDescriptorFlag
 local RoomShape = ____isaac_2Dtypescript_2Ddefinitions.RoomShape
 local RoomType = ____isaac_2Dtypescript_2Ddefinitions.RoomType
@@ -58,9 +57,8 @@ local getRoomData = ____roomData.getRoomData
 local getRoomDescriptor = ____roomData.getRoomDescriptor
 local getRoomDescriptorReadOnly = ____roomData.getRoomDescriptorReadOnly
 local getRoomGridIndex = ____roomData.getRoomGridIndex
-local getRoomName = ____roomData.getRoomName
-local getRoomStageID = ____roomData.getRoomStageID
-local getRoomSubType = ____roomData.getRoomSubType
+local ____roomShape = require("src.functions.roomShape")
+local isLRoomShape = ____roomShape.isLRoomShape
 local ____roomTransition = require("src.functions.roomTransition")
 local reloadRoom = ____roomTransition.reloadRoom
 local ____stage = require("src.functions.stage")
@@ -136,6 +134,105 @@ function ____exports.getRoomsOutsideGrid(self)
         function(____, readOnlyRoomDescriptor) return getRoomDescriptor(nil, readOnlyRoomDescriptor.SafeGridIndex) end
     )
 end
+--- Helper function to determine if the provided room is equal to `RoomShape.1x2` or `RoomShape.2x1`.
+function ____exports.is2x1Room(self, roomData)
+    return roomData.Shape == RoomShape.SHAPE_1x2 or roomData.Shape == RoomShape.SHAPE_2x1
+end
+function ____exports.isAngelShop(self, roomData)
+    return roomData.Type == RoomType.ANGEL and roomData.Subtype == asNumber(nil, AngelRoomSubType.SHOP)
+end
+function ____exports.isBeastRoom(self, roomData)
+    return roomData.Type == RoomType.DUNGEON and roomData.Subtype == asNumber(nil, DungeonSubType.BEAST_ROOM)
+end
+--- Helper function to check if the provided room is a boss room for a particular boss. This will
+-- only work for bosses that have dedicated boss rooms in the "00.special rooms.stb" file.
+function ____exports.isBossRoomOf(self, roomData, bossID)
+    return roomData.Type == RoomType.BOSS and roomData.StageID == StageID.SPECIAL_ROOMS and roomData.Subtype == asNumber(nil, bossID)
+end
+--- Helper function for determining whether the provided room is a crawl space. Use this function
+-- over comparing to `RoomType.DUNGEON` or `GridRoom.DUNGEON_IDX` since there is a special case of
+-- the player being in a boss fight that takes place in a dungeon.
+function ____exports.isCrawlSpace(self, roomData)
+    return roomData.Type == RoomType.DUNGEON and roomData.Subtype == asNumber(nil, DungeonSubType.NORMAL)
+end
+--- Helper function to detect if the provided room is one of the rooms in the Death Certificate area.
+function ____exports.isDeathCertificateArea(self, roomData)
+    return roomData.StageID == StageID.HOME and (roomData.Subtype == asNumber(nil, HomeRoomSubType.DEATH_CERTIFICATE_ENTRANCE) or roomData.Subtype == asNumber(nil, HomeRoomSubType.DEATH_CERTIFICATE_ITEMS))
+end
+--- Helper function to detect if the provided room is a Treasure Room created when entering with a
+-- Devil's Crown trinket.
+-- 
+-- Under the hood, this checks for `RoomDescriptorFlag.DEVIL_TREASURE`.
+function ____exports.isDevilsCrownTreasureRoom(self, roomDescriptor)
+    return hasFlag(nil, roomDescriptor.Flags, RoomDescriptorFlag.DEVIL_TREASURE)
+end
+--- Helper function to detect if the provided room is a Double Trouble Boss Room.
+-- 
+-- This is performed by checking for the string "Double Trouble" inside of the room name. The
+-- vanilla game uses this convention for every Double Trouble Boss Room. Note that this method might
+-- fail for mods that add extra Double Trouble rooms but do not follow the convention.
+-- 
+-- Internally, the game is coded to detect Double Trouble Boss Rooms by checking for the variant
+-- range of 3700 through 3850. We intentionally do not use this method since it may not work as well
+-- with modded rooms.
+function ____exports.isDoubleTrouble(self, roomData)
+    return roomData.Type == RoomType.BOSS and __TS__StringIncludes(roomData.Name, "Double Trouble")
+end
+--- Helper function to determine if the index of the provided room is equal to `GridRoom.GENESIS`.
+function ____exports.isGenesisRoom(self, roomDescriptor)
+    return roomDescriptor.GridIndex == asNumber(nil, GridRoom.GENESIS)
+end
+--- Helper function to check if the provided 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.
+function ____exports.isHomeCloset(self, roomData)
+    return roomData.StageID == StageID.HOME and (roomData.Subtype == asNumber(nil, HomeRoomSubType.CLOSET_LEFT) or roomData.Subtype == asNumber(nil, HomeRoomSubType.CLOSET_RIGHT))
+end
+--- Helper function to determine if the provided room is one of the four L room shapes.
+function ____exports.isLRoom(self, roomData)
+    return isLRoomShape(nil, roomData.Shape)
+end
+--- Helper function to determine if the index of the provided room is equal to `GridRoom.MEGA_SATAN`.
+function ____exports.isMegaSatanRoom(self, roomDescriptor)
+    return roomDescriptor.GridIndex == asNumber(nil, GridRoom.MEGA_SATAN)
+end
+--- Helper function to determine if the provided room is part of the Repentance "escape sequence" in
+-- the Mines/Ashpit.
+function ____exports.isMineShaft(self, roomData)
+    return (roomData.StageID == StageID.MINES or roomData.StageID == StageID.ASHPIT) and MINE_SHAFT_ROOM_SUB_TYPE_SET:has(roomData.Subtype)
+end
+--- Helper function to check if the provided room is a miniboss room for a particular miniboss. This
+-- will only work for mini-bosses that have dedicated boss rooms in the "00.special rooms.stb" file.
+function ____exports.isMinibossRoomOf(self, roomData, minibossID)
+    return roomData.Type == RoomType.MINI_BOSS and roomData.StageID == StageID.SPECIAL_ROOMS and roomData.Subtype == asNumber(nil, minibossID)
+end
+--- Helper function to check if the provided room is a "mirror room" in Downpour or Dross. (These
+-- rooms are marked with a specific sub-type.)
+function ____exports.isMirrorRoom(self, roomData)
+    return roomData.Type == RoomType.DEFAULT and (roomData.StageID == StageID.DOWNPOUR or roomData.StageID == StageID.DROSS) and roomData.Subtype == asNumber(nil, DownpourRoomSubType.MIRROR)
+end
+--- Helper function to check if the provided room matches one of the given room types.
+-- 
+-- This function is variadic, which means you can pass as many room types as you want to match for.
+function ____exports.isRoomType(self, roomData, ...)
+    local roomTypes = {...}
+    return __TS__ArrayIncludes(roomTypes, roomData.Type)
+end
+--- Helper function for checking if the provided room is a secret exit that leads to a Repentance
+-- floor.
+function ____exports.isSecretExit(self, roomDescriptor)
+    return roomDescriptor.GridIndex == asNumber(nil, GridRoom.SECRET_EXIT)
+end
+--- Helper function for checking if the provided room is a secret shop (from the Member Card
+-- collectible).
+-- 
+-- Secret shops are simply copies of normal shops, but with the backdrop of a secret room. In other
+-- words, they will have the same room type, room variant, and room sub-type of a normal shop. Thus,
+-- the only way to detect them is by using the grid index.
+function ____exports.isSecretShop(self, roomDescriptor)
+    return roomDescriptor.GridIndex == asNumber(nil, GridRoom.SECRET_SHOP)
+end
 local SECRET_ROOM_TYPES = __TS__New(ReadonlySet, {RoomType.SECRET, RoomType.SUPER_SECRET, RoomType.ULTRA_SECRET})
 --- Helper function for quickly switching to a new room without playing a particular animation. Use
 -- this helper function over invoking the `Game.ChangeRoom` method directly to ensure that you do
@@ -251,45 +348,34 @@ end
 --- Helper function to determine if the current room shape is equal to `RoomShape.1x2` or
 -- `RoomShape.2x1`.
 function ____exports.in2x1Room(self)
-    local room = game:GetRoom()
-    local roomShape = room:GetRoomShape()
-    return roomShape == RoomShape.SHAPE_1x2 or roomShape == RoomShape.SHAPE_2x1
+    local roomData = getRoomData(nil)
+    return ____exports.is2x1Room(nil, roomData)
 end
 function ____exports.inAngelShop(self)
-    local room = game:GetRoom()
-    local roomType = room:GetType()
-    local roomSubType = getRoomSubType(nil)
-    return roomType == RoomType.ANGEL and roomSubType == asNumber(nil, AngelRoomSubType.SHOP)
+    local roomData = getRoomData(nil)
+    return ____exports.isAngelShop(nil, roomData)
 end
 function ____exports.inBeastRoom(self)
-    local room = game:GetRoom()
-    local roomType = room:GetType()
-    local roomSubType = getRoomSubType(nil)
-    return roomType == RoomType.DUNGEON and roomSubType == asNumber(nil, DungeonSubType.BEAST_ROOM)
+    local roomData = getRoomData(nil)
+    return ____exports.isBeastRoom(nil, roomData)
 end
 --- Helper function to check if the current room is a boss room for a particular boss. This will only
 -- work for bosses that have dedicated boss rooms in the "00.special rooms.stb" file.
 function ____exports.inBossRoomOf(self, bossID)
-    local room = game:GetRoom()
-    local roomType = room:GetType()
-    local roomStageID = getRoomStageID(nil)
-    local roomSubType = getRoomSubType(nil)
-    return roomType == RoomType.BOSS and roomStageID == StageID.SPECIAL_ROOMS and roomSubType == asNumber(nil, bossID)
+    local roomData = getRoomData(nil)
+    return ____exports.isBossRoomOf(nil, roomData, bossID)
 end
 --- Helper function for determining whether the current room is a crawl space. Use this function over
 -- comparing to `RoomType.DUNGEON` or `GridRoom.DUNGEON_IDX` since there is a special case of the
--- player being in a boss fight that take place in a dungeon.
+-- player being in a boss fight that takes place in a dungeon.
 function ____exports.inCrawlSpace(self)
-    local room = game:GetRoom()
-    local roomType = room:GetType()
-    local roomSubType = getRoomSubType(nil)
-    return roomType == RoomType.DUNGEON and roomSubType == asNumber(nil, DungeonSubType.NORMAL)
+    local roomData = getRoomData(nil)
+    return ____exports.isCrawlSpace(nil, roomData)
 end
 --- Helper function to detect if the current room is one of the rooms in the Death Certificate area.
 function ____exports.inDeathCertificateArea(self)
-    local roomStageID = getRoomStageID(nil)
-    local roomSubType = getRoomSubType(nil)
-    return roomStageID == StageID.HOME and (roomSubType == asNumber(nil, HomeRoomSubType.DEATH_CERTIFICATE_ENTRANCE) or roomSubType == asNumber(nil, HomeRoomSubType.DEATH_CERTIFICATE_ITEMS))
+    local roomData = getRoomData(nil)
+    return ____exports.isDeathCertificateArea(nil, roomData)
 end
 --- Helper function to detect if the current room is a Treasure Room created when entering with a
 -- Devil's Crown trinket.
@@ -297,83 +383,74 @@ end
 -- Under the hood, this checks for `RoomDescriptorFlag.DEVIL_TREASURE`.
 function ____exports.inDevilsCrownTreasureRoom(self)
     local roomDescriptor = getRoomDescriptorReadOnly(nil)
-    return hasFlag(nil, roomDescriptor.Flags, RoomDescriptorFlag.DEVIL_TREASURE)
+    return ____exports.isDevilsCrownTreasureRoom(nil, roomDescriptor)
 end
 --- Helper function to detect if the current room is a Double Trouble Boss Room.
 -- 
 -- This is performed by checking for the string "Double Trouble" inside of the room name. The
 -- vanilla game uses this convention for every Double Trouble Boss Room. Note that this method might
 -- fail for mods that add extra Double Trouble rooms but do not follow the convention.
+-- 
+-- Internally, the game is coded to detect Double Trouble Boss Rooms by checking for the variant
+-- range of 3700 through 3850. We intentionally do not use this method since it may not work as well
+-- with modded rooms.
 function ____exports.inDoubleTrouble(self)
-    local room = game:GetRoom()
-    local roomType = room:GetType()
-    local roomName = getRoomName(nil)
-    return roomType == RoomType.BOSS and __TS__StringIncludes(roomName, "Double Trouble")
+    local roomData = getRoomData(nil)
+    return ____exports.isDoubleTrouble(nil, roomData)
 end
+--- Helper function to determine if the current room index is equal to `GridRoom.GENESIS`.
 function ____exports.inGenesisRoom(self)
-    local roomGridIndex = getRoomGridIndex(nil)
-    return roomGridIndex == asNumber(nil, GridRoom.GENESIS)
+    local roomDescriptor = getRoomDescriptorReadOnly(nil)
+    return ____exports.isGenesisRoom(nil, roomDescriptor)
 end
 --- 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.
 function ____exports.inHomeCloset(self)
-    local level = game:GetLevel()
-    local stage = level:GetStage()
-    local roomSubType = getRoomSubType(nil)
-    return stage == LevelStage.HOME and (roomSubType == asNumber(nil, HomeRoomSubType.CLOSET_LEFT) or roomSubType == asNumber(nil, HomeRoomSubType.CLOSET_RIGHT))
+    local roomData = getRoomData(nil)
+    return ____exports.isHomeCloset(nil, roomData)
 end
 --- Helper function to determine if the current room shape is one of the four L room shapes.
 function ____exports.inLRoom(self)
-    local room = game:GetRoom()
-    local roomShape = room:GetRoomShape()
-    return roomShape == RoomShape.LTL or roomShape == RoomShape.LTR or roomShape == RoomShape.LBL or roomShape == RoomShape.LBR
+    local roomData = getRoomData(nil)
+    return ____exports.isLRoom(nil, roomData)
 end
 --- Helper function to determine if the current room index is equal to `GridRoom.MEGA_SATAN`.
 function ____exports.inMegaSatanRoom(self)
-    local roomGridIndex = getRoomGridIndex(nil)
-    return roomGridIndex == asNumber(nil, GridRoom.MEGA_SATAN)
+    local roomDescriptor = getRoomDescriptorReadOnly(nil)
+    return ____exports.isMegaSatanRoom(nil, roomDescriptor)
 end
 --- Helper function to determine if the current room is part of the Repentance "escape sequence" in
 -- the Mines/Ashpit.
 function ____exports.inMineShaft(self)
-    local roomStageID = getRoomStageID(nil)
-    local roomSubType = getRoomSubType(nil)
-    return (roomStageID == StageID.MINES or roomStageID == StageID.ASHPIT) and MINE_SHAFT_ROOM_SUB_TYPE_SET:has(roomSubType)
+    local roomData = getRoomData(nil)
+    return ____exports.isMineShaft(nil, roomData)
 end
 --- Helper function to check if the current room is a miniboss room for a particular miniboss. This
 -- will only work for mini-bosses that have dedicated boss rooms in the "00.special rooms.stb" file.
 function ____exports.inMinibossRoomOf(self, minibossID)
-    local room = game:GetRoom()
-    local roomType = room:GetType()
-    local roomStageID = getRoomStageID(nil)
-    local roomSubType = getRoomSubType(nil)
-    return roomType == RoomType.MINI_BOSS and roomStageID == StageID.SPECIAL_ROOMS and roomSubType == asNumber(nil, minibossID)
+    local roomData = getRoomData(nil)
+    return ____exports.isMinibossRoomOf(nil, roomData, minibossID)
 end
 --- Helper function to check if the current room is a "mirror room" in Downpour or Dross. (These
 -- rooms are marked with a specific sub-type.)
 function ____exports.inMirrorRoom(self)
-    local room = game:GetRoom()
-    local roomType = room:GetType()
-    local roomStageID = getRoomStageID(nil)
-    local roomSubType = getRoomSubType(nil)
-    return roomType == RoomType.DEFAULT and (roomStageID == StageID.DOWNPOUR or roomStageID == StageID.DROSS) and roomSubType == asNumber(nil, DownpourRoomSubType.MIRROR)
+    local roomData = getRoomData(nil)
+    return ____exports.isMirrorRoom(nil, roomData)
 end
 --- Helper function to check if the current room matches one of the given room types.
 -- 
 -- This function is variadic, which means you can pass as many room types as you want to match for.
 function ____exports.inRoomType(self, ...)
-    local roomTypes = {...}
-    local room = game:GetRoom()
-    local thisRoomType = room:GetType()
-    return __TS__ArrayIncludes(roomTypes, thisRoomType)
+    local roomData = getRoomData(nil)
+    return ____exports.isRoomType(nil, roomData, ...)
 end
 --- Helper function for checking if the current room is a secret exit that leads to a Repentance
 -- floor.
 function ____exports.inSecretExit(self)
-    local roomGridIndex = getRoomGridIndex(nil)
-    return roomGridIndex == asNumber(nil, GridRoom.SECRET_EXIT)
+    local roomDescriptor = getRoomDescriptorReadOnly(nil)
+    return ____exports.isSecretExit(nil, roomDescriptor)
 end
 --- Helper function for checking if the current room is a secret shop (from the Member Card
 -- collectible).
@@ -382,8 +459,8 @@ end
 -- words, they will have the same room type, room variant, and room sub-type of a normal shop. Thus,
 -- the only way to detect them is by using the grid index.
 function ____exports.inSecretShop(self)
-    local roomGridIndex = getRoomGridIndex(nil)
-    return roomGridIndex == asNumber(nil, GridRoom.SECRET_SHOP)
+    local roomDescriptor = getRoomDescriptorReadOnly(nil)
+    return ____exports.isSecretShop(nil, roomDescriptor)
 end
 --- Helper function to determine whether or not the current room is the starting room of a floor. It
 -- only returns true for the starting room of the primary dimension (meaning that being in the
@@ -477,12 +554,12 @@ function ____exports.setRoomCleared(self)
     for ____, door in ipairs(getDoors(nil)) do
         do
             if isHiddenSecretRoomDoor(nil, door) then
-                goto __continue59
+                goto __continue77
             end
             openDoorFast(nil, door)
             door.ExtraVisible = false
         end
-        ::__continue59::
+        ::__continue77::
     end
     sfxManager:Stop(SoundEffect.DOOR_HEAVY_OPEN)
     game:ShakeScreen(0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "30.12.11",
+  "version": "31.0.1",
   "description": "Helper functions and features for IsaacScript mods.",
   "keywords": [
     "isaac",
@@ -25,6 +25,6 @@
   "main": "dist/src/index",
   "types": "dist/index.rollup.d.ts",
   "dependencies": {
-    "isaac-typescript-definitions": "^13.0.23"
+    "isaac-typescript-definitions": "^13.0.24"
   }
 }

package/src/classes/features/other/ItemPoolDetection.ts

@@ -99,7 +99,7 @@ export class ItemPoolDetection extends Feature {
       }
     }
 
-    const [removedItemsMap, removedTrinketsMap] =
+    const { removedItemsMap, removedTrinketsMap } =
       removeItemsAndTrinketsThatAffectItemPools();
 
     // Blacklist every collectible in the game except for the provided collectible.
@@ -173,10 +173,10 @@ export class ItemPoolDetection extends Feature {
  * Before checking the item pools, remove any collectibles or trinkets that would affect the
  * retrieved collectible types.
  */
-function removeItemsAndTrinketsThatAffectItemPools(): [
-  removedItemsMap: Map<PlayerIndex, CollectibleType[]>,
-  removedTrinketsMap: Map<PlayerIndex, TrinketType[]>,
-] {
+function removeItemsAndTrinketsThatAffectItemPools(): {
+  removedItemsMap: Map<PlayerIndex, CollectibleType[]>;
+  removedTrinketsMap: Map<PlayerIndex, TrinketType[]>;
+} {
   const removedItemsMap = new Map<PlayerIndex, CollectibleType[]>();
   const removedTrinketsMap = new Map<PlayerIndex, TrinketType[]>();
   for (const player of getAllPlayers()) {
@@ -207,7 +207,7 @@ function removeItemsAndTrinketsThatAffectItemPools(): [
     mapSetPlayer(removedTrinketsMap, player, removedTrinkets);
   }
 
-  return [removedItemsMap, removedTrinketsMap];
+  return { removedItemsMap, removedTrinketsMap };
 }
 
 function restoreItemsAndTrinketsThatAffectItemPools(

package/src/classes/features/other/customStages/backdrop.ts

@@ -14,7 +14,7 @@ import { LadderSubTypeCustom } from "../../../../enums/LadderSubTypeCustom";
 import { getRandomArrayElement } from "../../../../functions/array";
 import { spawnEffectWithSeed } from "../../../../functions/entitiesSpecific";
 import { newRNG } from "../../../../functions/rng";
-import { isLRoom, isNarrowRoom } from "../../../../functions/roomShape";
+import { isLRoomShape, isNarrowRoom } from "../../../../functions/roomShape";
 import {
   removeCharactersBefore,
   trimPrefix,
@@ -155,7 +155,7 @@ function spawnWallEntity(
     );
   }
 
-  if (isLRoom(roomShape)) {
+  if (isLRoomShape(roomShape)) {
     const cornerPNGPath = getBackdropPNGPath(
       customStage,
       BackdropKind.CORNER,
@@ -223,7 +223,7 @@ function spawnFloorEntity(customStage: CustomStage, rng: RNG) {
       );
       sprite.ReplaceSpritesheet(layerID, wallPNGPath);
     }
-  } else if (isLRoom(roomShape)) {
+  } else if (isLRoomShape(roomShape)) {
     for (const layerID of L_FLOOR_ANM2_LAYERS) {
       const LFloorPNGPath = getBackdropPNGPath(
         customStage,

package/src/functions/hex.ts

@@ -9,7 +9,7 @@ const HEX_STRING_LENGTH = 6;
  * @param alpha Optional. Range is from 0 to 1. Default is 1. (The same as the `Color` constructor.)
  */
 export function hexToColor(hexString: string, alpha = 1): Readonly<Color> {
-  const [r, g, b] = hexToRGB(hexString);
+  const { r, g, b } = hexToRGB(hexString);
 
   // Color values should be between 0 and 1.
   const base = 255;
@@ -23,40 +23,40 @@ export function hexToColor(hexString: string, alpha = 1): Readonly<Color> {
  * @param alpha Range is from 0 to 1. Default is 1.
  */
 export function hexToKColor(hexString: string, alpha = 1): Readonly<KColor> {
-  const [r, g, b] = hexToRGB(hexString);
+  const { r, g, b } = hexToRGB(hexString);
 
   // KColor values should be between 0 and 1.
   const base = 255;
   return KColor(r / base, g / base, b / base, alpha);
 }
 
-function hexToRGB(hexString: string): [r: float, g: float, b: float] {
+function hexToRGB(hexString: string): { r: float; g: float; b: float } {
   hexString = hexString.replace("#", "");
   if (hexString.length !== HEX_STRING_LENGTH) {
     logError(`Hex strings must be of length: ${HEX_STRING_LENGTH}`);
-    return [0, 0, 0];
+    return { r: 0, g: 0, b: 0 };
   }
 
   const rString = hexString.slice(0, 2);
   const r = tonumber(`0x${rString}`);
   if (r === undefined) {
     logError(`Failed to convert \`0x${rString}\` to a number.`);
-    return [0, 0, 0];
+    return { r: 0, g: 0, b: 0 };
   }
 
   const gString = hexString.slice(2, 4);
   const g = tonumber(`0x${gString}`);
   if (g === undefined) {
     logError(`Failed to convert \`0x${gString}\` to a number.`);
-    return [0, 0, 0];
+    return { r: 0, g: 0, b: 0 };
   }
 
   const bString = hexString.slice(4, 6);
   const b = tonumber(`0x${bString}`);
   if (b === undefined) {
     logError(`Failed to convert \`0x${bString}\` to a number.`);
-    return [0, 0, 0];
+    return { r: 0, g: 0, b: 0 };
   }
 
-  return [r, g, b];
+  return { r, g, b };
 }

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;