isaacscript-common 6.1.1 → 6.2.0

package/classes/DefaultMap.lua

@@ -120,7 +120,7 @@ function DefaultMap.prototype.getDefaultValue(self, ...)
     if self.defaultValueFactory ~= nil then
         return self:defaultValueFactory(...)
     end
-    return error("A DefaultMap was incorrectly instantiated.")
+    error("A DefaultMap was incorrectly instantiated.")
 end
 function DefaultMap.prototype.getConstructorArg(self)
     if self.defaultValue ~= nil then
@@ -129,6 +129,6 @@ function DefaultMap.prototype.getConstructorArg(self)
     if self.defaultValueFactory ~= nil then
         return self.defaultValueFactory
     end
-    return error("A DefaultMap was incorrectly instantiated.")
+    error("A DefaultMap was incorrectly instantiated.")
 end
 return ____exports

package/features/customStage/exports.d.ts

@@ -1,6 +1,7 @@
 /**
  * Helper function to warp to a custom stage/level.
  *
- * Custom stages/levels must first be registered with the `registerCustomStage` function.
+ * Custom stages/levels must first be defined in the "tsconfig.json" file. See the documentation for
+ * more details: https://isaacscript.github.io/main/custom-stages/
  */
-export declare function setCustomStage(name: string): void;
+export declare function setCustomStage(name: string, verbose?: boolean): void;

package/features/customStage/exports.lua

@@ -1,15 +1,94 @@
 local ____lualib = require("lualib_bundle")
 local Map = ____lualib.Map
 local ____exports = {}
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local Direction = ____isaac_2Dtypescript_2Ddefinitions.Direction
+local GridRoom = ____isaac_2Dtypescript_2Ddefinitions.GridRoom
+local RoomShape = ____isaac_2Dtypescript_2Ddefinitions.RoomShape
+local RoomTransitionAnim = ____isaac_2Dtypescript_2Ddefinitions.RoomTransitionAnim
+local RoomType = ____isaac_2Dtypescript_2Ddefinitions.RoomType
+local StageType = ____isaac_2Dtypescript_2Ddefinitions.StageType
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+local ____log = require("functions.log")
+local logError = ____log.logError
+local ____rng = require("functions.rng")
+local newRNG = ____rng.newRNG
+local ____roomData = require("functions.roomData")
+local getRoomData = ____roomData.getRoomData
+local ____rooms = require("functions.rooms")
+local getRooms = ____rooms.getRooms
+local ____stage = require("functions.stage")
+local getGotoCommand = ____stage.getGotoCommand
+local setStage = ____stage.setStage
+local ____util = require("features.customStage.util")
+local getRandomCustomStageRoom = ____util.getRandomCustomStageRoom
 local ____v = require("features.customStage.v")
+local customStageCachedRoomData = ____v.customStageCachedRoomData
 local customStagesMap = ____v.customStagesMap
 --- Helper function to warp to a custom stage/level.
 -- 
--- Custom stages/levels must first be registered with the `registerCustomStage` function.
-function ____exports.setCustomStage(self, name)
+-- Custom stages/levels must first be defined in the "tsconfig.json" file. See the documentation for
+-- more details: https://isaacscript.github.io/main/custom-stages/
+function ____exports.setCustomStage(self, name, verbose)
+    if verbose == nil then
+        verbose = false
+    end
     local customStage = customStagesMap:get(name)
     if customStage == nil then
-        error(("Failed to set the custom stage of \"" .. name) .. "\" because it was not found in the custom stages map. (This means that you probably forgot to define it in your \"tsconfig.json\" file.) See the website for more details on how to set up custom stages..")
+        error(("Failed to set the custom stage of \"" .. name) .. "\" because it was not found in the custom stages map. (This means that you probably forgot to define it in your \"tsconfig.json\" file.) See the website for more details on how to set up custom stages.")
+    end
+    local level = game:GetLevel()
+    local startingRoomGridIndex = level:GetStartingRoomIndex()
+    local seeds = game:GetSeeds()
+    local startSeed = seeds:GetStartSeed()
+    local rng = newRNG(nil, startSeed)
+    setStage(nil, customStage.baseStage, customStage.baseStageType)
+    for ____, room in ipairs(getRooms(nil)) do
+        do
+            if room.SafeGridIndex == startingRoomGridIndex then
+                goto __continue4
+            end
+            if room.Data == nil then
+                goto __continue4
+            end
+            local roomType = room.Data.Type
+            local roomShapeMap = customStage.roomTypeMap:get(roomType)
+            if roomShapeMap == nil then
+                if roomType == RoomType.DEFAULT then
+                    logError((((("Failed to find any custom rooms for RoomType." .. tostring(RoomType[roomType])) .. " (") .. tostring(roomType)) .. ") for custom stage: ") .. name)
+                end
+                goto __continue4
+            end
+            local roomShape = room.Data.Shape
+            local roomDoorSlotFlagMap = roomShapeMap:get(roomShape)
+            if roomDoorSlotFlagMap == nil then
+                logError((((((((("Failed to find any custom rooms for RoomType." .. tostring(RoomType[roomType])) .. " (") .. tostring(roomType)) .. ") + RoomShape.") .. tostring(RoomShape[roomShape])) .. " (") .. tostring(roomShape)) .. ") for custom stage: ") .. name)
+                goto __continue4
+            end
+            local doorSlotFlags = room.Data.Doors
+            local roomsMetadata = roomDoorSlotFlagMap:get(doorSlotFlags)
+            if roomsMetadata == nil then
+                logError((((((((((("Failed to find any custom rooms for RoomType." .. tostring(RoomType[roomType])) .. " (") .. tostring(roomType)) .. ") + RoomShape.") .. tostring(RoomShape[roomShape])) .. " (") .. tostring(roomShape)) .. ") + DoorSlotFlags ") .. tostring(doorSlotFlags)) .. " for custom stage: ") .. name)
+                goto __continue4
+            end
+            local randomRoom = getRandomCustomStageRoom(nil, roomsMetadata, rng, verbose)
+            local newRoomData = customStageCachedRoomData:get(randomRoom.variant)
+            if newRoomData == nil then
+                local command = getGotoCommand(nil, roomType, randomRoom.variant)
+                Isaac.ExecuteCommand(command)
+                newRoomData = getRoomData(nil, GridRoom.DEBUG)
+                if newRoomData == nil then
+                    logError((("Failed to get the room data for room variant " .. tostring(randomRoom.variant)) .. " for custom stage: ") .. name)
+                    goto __continue4
+                end
+                customStageCachedRoomData:set(randomRoom.variant, newRoomData)
+            end
+            room.Data = newRoomData
+        end
+        ::__continue4::
     end
+    level:SetStage(-1, StageType.ORIGINAL)
+    game:StartRoomTransition(startingRoomGridIndex, Direction.NO_DIRECTION, RoomTransitionAnim.FADE)
 end
 return ____exports

package/features/customStage/init.lua

@@ -1,17 +1,47 @@
 local ____lualib = require("lualib_bundle")
 local Map = ____lualib.Map
+local __TS__ObjectAssign = ____lualib.__TS__ObjectAssign
+local __TS__New = ____lualib.__TS__New
 local ____exports = {}
+local getRoomTypeMap
 local ____array = require("functions.array")
 local isArray = ____array.isArray
 local metadataJSON = require("features.customStage.metadata")
 local ____v = require("features.customStage.v")
 local customStagesMap = ____v.customStagesMap
+function getRoomTypeMap(self, customStageLua)
+    local roomTypeMap = __TS__New(Map)
+    for ____, roomMetadata in ipairs(customStageLua.roomsMetadata) do
+        local roomType = roomMetadata.type
+        local roomShapeMap = roomTypeMap:get(roomType)
+        if roomShapeMap == nil then
+            roomShapeMap = __TS__New(Map)
+            roomTypeMap:set(roomType, roomShapeMap)
+        end
+        local roomShape = roomMetadata.shape
+        local roomDoorSlotFlagMap = roomShapeMap:get(roomShape)
+        if roomDoorSlotFlagMap == nil then
+            roomDoorSlotFlagMap = __TS__New(Map)
+            roomShapeMap:set(roomShape, roomDoorSlotFlagMap)
+        end
+        local doorSlotFlags = roomMetadata.doorSlotFlags
+        local rooms = roomDoorSlotFlagMap:get(doorSlotFlags)
+        if rooms == nil then
+            rooms = {}
+            roomDoorSlotFlagMap:set(doorSlotFlags, rooms)
+        end
+        rooms[#rooms + 1] = roomMetadata
+    end
+    return roomTypeMap
+end
 function ____exports.customStageInit(self)
-    local customStages = metadataJSON
-    if not isArray(nil, customStages) then
+    local customStagesLua = metadataJSON
+    if not isArray(nil, customStagesLua) then
         error("The IsaacScript standard library attempted to read the custom stage metadata from the \"metadata.lua\" file, but it was not an array.")
     end
-    for ____, customStage in ipairs(customStages) do
+    for ____, customStageLua in ipairs(customStagesLua) do
+        local roomTypeMap = getRoomTypeMap(nil, customStageLua)
+        local customStage = __TS__ObjectAssign({}, customStageLua, {roomTypeMap = roomTypeMap})
         customStagesMap:set(customStage.name, customStage)
     end
 end

package/features/customStage/util.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+import { CustomStageRoomMetadata } from "../../interfaces/CustomStageLua";
+/**
+ * Helper function to get a random custom stage room from an array of custom stage rooms.
+ *
+ * Note that this function does not simply choose a random element in the provided array; it will
+ * properly account for each room weight using the algorithm from:
+ * https://stackoverflow.com/questions/1761626/weighted-random-numbers
+ */
+export declare function getRandomCustomStageRoom(roomsMetadata: readonly CustomStageRoomMetadata[], seedOrRNG?: Seed | RNG, verbose?: boolean): CustomStageRoomMetadata;

package/features/customStage/util.lua

@@ -0,0 +1,51 @@
+local ____lualib = require("lualib_bundle")
+local __TS__ArrayMap = ____lualib.__TS__ArrayMap
+local ____exports = {}
+local getTotalWeightOfCustomStageRooms, getCustomStageRoomWithChosenWeight
+local ____array = require("functions.array")
+local sumArray = ____array.sumArray
+local ____log = require("functions.log")
+local log = ____log.log
+local ____random = require("functions.random")
+local getRandomFloat = ____random.getRandomFloat
+local ____rng = require("functions.rng")
+local getRandomSeed = ____rng.getRandomSeed
+function getTotalWeightOfCustomStageRooms(self, roomsMetadata)
+    local weights = __TS__ArrayMap(
+        roomsMetadata,
+        function(____, roomMetadata) return roomMetadata.weight end
+    )
+    return sumArray(nil, weights)
+end
+function getCustomStageRoomWithChosenWeight(self, roomsMetadata, chosenWeight)
+    for ____, roomMetadata in ipairs(roomsMetadata) do
+        if chosenWeight < roomMetadata.weight then
+            return roomMetadata
+        end
+        chosenWeight = chosenWeight - roomMetadata.weight
+    end
+    error("Failed to get a custom stage room with chosen weight: " .. tostring(chosenWeight))
+end
+--- Helper function to get a random custom stage room from an array of custom stage rooms.
+-- 
+-- Note that this function does not simply choose a random element in the provided array; it will
+-- properly account for each room weight using the algorithm from:
+-- https://stackoverflow.com/questions/1761626/weighted-random-numbers
+function ____exports.getRandomCustomStageRoom(self, roomsMetadata, seedOrRNG, verbose)
+    if seedOrRNG == nil then
+        seedOrRNG = getRandomSeed(nil)
+    end
+    if verbose == nil then
+        verbose = false
+    end
+    local totalWeight = getTotalWeightOfCustomStageRooms(nil, roomsMetadata)
+    if verbose then
+        log("Total weight of the custom stage rooms provided: " .. tostring(totalWeight))
+    end
+    local chosenWeight = getRandomFloat(nil, 0, totalWeight, seedOrRNG)
+    if verbose then
+        log("Randomly chose weight for custom stage room: " .. tostring(chosenWeight))
+    end
+    return getCustomStageRoomWithChosenWeight(nil, roomsMetadata, chosenWeight)
+end
+return ____exports

package/features/customStage/v.d.ts

@@ -1,2 +1,6 @@
+/// <reference types="isaac-typescript-definitions" />
 import { CustomStage } from "../../interfaces/CustomStage";
+/** Indexed by custom stage name. */
 export declare const customStagesMap: Map<string, CustomStage>;
+/** Indexed by room variant. */
+export declare const customStageCachedRoomData: Map<number, Readonly<RoomConfig>>;

package/features/customStage/v.lua

@@ -2,5 +2,8 @@ local ____lualib = require("lualib_bundle")
 local Map = ____lualib.Map
 local __TS__New = ____lualib.__TS__New
 local ____exports = {}
+--- Indexed by custom stage name.
 ____exports.customStagesMap = __TS__New(Map)
+--- Indexed by room variant.
+____exports.customStageCachedRoomData = __TS__New(Map)
 return ____exports

package/functions/doors.d.ts

@@ -53,6 +53,10 @@ export declare function getDoors(...roomTypes: RoomType[]): GridEntityDoor[];
 export declare function getDoorsToRoomIndex(...roomGridIndex: int[]): GridEntityDoor[];
 export declare function getOppositeDoorSlot(doorSlot: DoorSlot): DoorSlot | undefined;
 export declare function getRepentanceDoor(): GridEntityDoor | undefined;
+/**
+ * Helper function to get the corresponding door slot for a given room shape and grid coordinates.
+ */
+export declare function getRoomShapeDoorSlot(roomShape: RoomShape, x: int, y: int): DoorSlot | undefined;
 /**
  * Helper function to get the room grid coordinates for a specific room shape and door slot
  * combination.

package/functions/doors.lua

@@ -5,6 +5,7 @@ local __TS__ArrayMap = ____lualib.__TS__ArrayMap
 local __TS__New = ____lualib.__TS__New
 local __TS__ArrayFilter = ____lualib.__TS__ArrayFilter
 local __TS__ArrayFind = ____lualib.__TS__ArrayFind
+local __TS__Iterator = ____lualib.__TS__Iterator
 local ____exports = {}
 local ROOM_ENTRY_OFFSET_FROM_DOOR
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
@@ -193,6 +194,19 @@ function ____exports.getRepentanceDoor(self)
         function(____, door) return ____exports.isRepentanceDoor(nil, door) end
     )
 end
+--- Helper function to get the corresponding door slot for a given room shape and grid coordinates.
+function ____exports.getRoomShapeDoorSlot(self, roomShape, x, y)
+    local coordinatesMap = ROOM_SHAPE_TO_DOOR_SLOT_COORDINATES[roomShape]
+    for ____, ____value in __TS__Iterator(coordinatesMap:entries()) do
+        local doorSlot = ____value[1]
+        local doorX = ____value[2][1]
+        local doorY = ____value[2][2]
+        if x == doorX and y == doorY then
+            return doorSlot
+        end
+    end
+    return nil
+end
 --- Helper function to get the room grid coordinates for a specific room shape and door slot
 -- combination.
 function ____exports.getRoomShapeDoorSlotCoordinates(self, roomShape, doorSlot)

package/functions/familiars.d.ts

@@ -57,4 +57,6 @@ export declare function checkFamiliar(player: EntityPlayer, collectibleType: Col
  *                        spawn new familiars with a sub-type of 0.
  */
 export declare function checkFamiliarFromCollectibles(player: EntityPlayer, collectibleType: CollectibleType, familiarVariant: FamiliarVariant, familiarSubType?: int): void;
+/** Helper function to get only the familiars that belong to a specific player. */
+export declare function getPlayerFamiliars(player: EntityPlayer): EntityFamiliar[];
 export declare function isFamiliarThatShootsPlayerTears(familiar: EntityFamiliar): boolean;

package/functions/familiars.lua

@@ -1,8 +1,12 @@
+local ____lualib = require("lualib_bundle")
+local __TS__ArrayFilter = ____lualib.__TS__ArrayFilter
 local ____exports = {}
 local ____cachedClasses = require("cachedClasses")
 local itemConfig = ____cachedClasses.itemConfig
 local ____familiarsThatShootPlayerTearsSet = require("sets.familiarsThatShootPlayerTearsSet")
 local FAMILIARS_THAT_SHOOT_PLAYER_TEARS_SET = ____familiarsThatShootPlayerTearsSet.FAMILIARS_THAT_SHOOT_PLAYER_TEARS_SET
+local ____entitySpecific = require("functions.entitySpecific")
+local getFamiliars = ____entitySpecific.getFamiliars
 --- Helper function to add and remove familiars based on a target amount that you specify.
 -- 
 -- This is a convenience wrapper around the `EntityPlayer.CheckFamiliar` method. Use this helper
@@ -79,6 +83,18 @@ function ____exports.checkFamiliarFromCollectibles(self, player, collectibleType
         familiarSubType
     )
 end
+--- Helper function to get only the familiars that belong to a specific player.
+function ____exports.getPlayerFamiliars(self, player)
+    local playerPtrHash = GetPtrHash(player)
+    local familiars = getFamiliars(nil)
+    return __TS__ArrayFilter(
+        familiars,
+        function(____, familiar)
+            local familiarPlayerPtrHash = GetPtrHash(familiar.Player)
+            return familiarPlayerPtrHash == playerPtrHash
+        end
+    )
+end
 function ____exports.isFamiliarThatShootsPlayerTears(self, familiar)
     return FAMILIARS_THAT_SHOOT_PLAYER_TEARS_SET:has(familiar.Variant)
 end

package/functions/jsonRoom.d.ts

@@ -1,8 +1,24 @@
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
+import { DoorSlotFlag } from "isaac-typescript-definitions";
 import { JSONRoom } from "../interfaces/JSONRoomsFile";
+/**
+ * Helper function to calculate what the resulting `BitFlags<DoorSlotFlag>` value would be for a
+ * given JSON room.
+ */
+export declare function getJSONRoomDoorSlotFlags(jsonRoom: JSONRoom): BitFlags<DoorSlotFlag>;
+/**
+ * Helper function to find a specific room from an array of JSON rooms.
+ *
+ * @param jsonRooms The array of rooms to search through.
+ * @param variant The room variant to select. (The room variant can be thought of as the ID of the
+ *                room.)
+ */
 export declare function getJSONRoomOfVariant(jsonRooms: JSONRoom[] | readonly JSONRoom[], variant: int): JSONRoom | undefined;
+/**
+ * Helper function to find all of the JSON rooms that match the sub-type provided.
+ *
+ * @param jsonRooms The array of rooms to search through.
+ * @param subType The sub-type to match.
+ */
 export declare function getJSONRoomsOfSubType(jsonRooms: JSONRoom[] | readonly JSONRoom[], subType: int): JSONRoom[];
 /**
  * Helper function to get a random JSON room from an array of JSON rooms.
@@ -10,5 +26,11 @@ export declare function getJSONRoomsOfSubType(jsonRooms: JSONRoom[] | readonly J
  * Note that this function does not simply choose a random element in the provided array; it will
  * properly account for each room weight using the algorithm from:
  * https://stackoverflow.com/questions/1761626/weighted-random-numbers
+ *
+ * @param jsonRooms The array of rooms to random choose between.
+ * @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 verbose Optional. If specified, will write entries to the "log.txt" file that describe
+ *                what the function is doing. Default is false.
  */
 export declare function getRandomJSONRoom(jsonRooms: JSONRoom[] | readonly JSONRoom[], seedOrRNG?: Seed | RNG, verbose?: boolean): JSONRoom;

package/functions/jsonRoom.lua

@@ -3,8 +3,15 @@ local __TS__ArrayFilter = ____lualib.__TS__ArrayFilter
 local __TS__ArrayMap = ____lualib.__TS__ArrayMap
 local ____exports = {}
 local getTotalWeightOfJSONRooms, getJSONRoomWithChosenWeight
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local DoorSlotFlagZero = ____isaac_2Dtypescript_2Ddefinitions.DoorSlotFlagZero
 local ____array = require("functions.array")
 local sumArray = ____array.sumArray
+local ____doors = require("functions.doors")
+local doorSlotToDoorSlotFlag = ____doors.doorSlotToDoorSlotFlag
+local getRoomShapeDoorSlot = ____doors.getRoomShapeDoorSlot
+local ____flag = require("functions.flag")
+local addFlag = ____flag.addFlag
 local ____log = require("functions.log")
 local log = ____log.log
 local ____random = require("functions.random")
@@ -37,8 +44,53 @@ function getJSONRoomWithChosenWeight(self, jsonRooms, chosenWeight)
         end
         chosenWeight = chosenWeight - roomWeight
     end
-    return error("Failed to get a JSON room with chosen weight: " .. tostring(chosenWeight))
+    error("Failed to get a JSON room with chosen weight: " .. tostring(chosenWeight))
 end
+--- Helper function to calculate what the resulting `BitFlags<DoorSlotFlag>` value would be for a
+-- given JSON room.
+function ____exports.getJSONRoomDoorSlotFlags(self, jsonRoom)
+    local roomShapeString = jsonRoom["$"].shape
+    local roomShapeNumber = tonumber(roomShapeString)
+    if roomShapeNumber == nil then
+        error("Failed to parse the \"shape\" property of a JSON room: " .. roomShapeString)
+    end
+    local roomShape = roomShapeNumber
+    local doorSlotFlags = DoorSlotFlagZero
+    for ____, door in ipairs(jsonRoom.door) do
+        do
+            local existsString = door["$"].exists
+            if existsString ~= "True" and existsString ~= "False" then
+                error("Failed to parse the \"exists\" property of a JSON room door: " .. existsString)
+            end
+            if existsString == "False" then
+                goto __continue4
+            end
+            local xString = door["$"].x
+            local x = tonumber(xString)
+            if x == nil then
+                error("Failed to parse the \"x\" property of a JSON room door: " .. xString)
+            end
+            local yString = door["$"].y
+            local y = tonumber(yString)
+            if y == nil then
+                error("Failed to parse the \"y\" property of a JSON room door: " .. yString)
+            end
+            local doorSlot = getRoomShapeDoorSlot(nil, roomShape, x, y)
+            if doorSlot == nil then
+                error(((("Failed to retrieve the door slot for a JSON room door at coordinates: [" .. tostring(x)) .. ", ") .. tostring(y)) .. "]")
+            end
+            local doorSlotFlag = doorSlotToDoorSlotFlag(nil, doorSlot)
+            doorSlotFlags = addFlag(nil, doorSlotFlags, doorSlotFlag)
+        end
+        ::__continue4::
+    end
+    return doorSlotFlags
+end
+--- Helper function to find a specific room from an array of JSON rooms.
+-- 
+-- @param jsonRooms The array of rooms to search through.
+-- @param variant The room variant to select. (The room variant can be thought of as the ID of the
+-- room.)
 function ____exports.getJSONRoomOfVariant(self, jsonRooms, variant)
     local jsonRoomsOfVariant = __TS__ArrayFilter(
         jsonRooms,
@@ -54,8 +106,12 @@ function ____exports.getJSONRoomOfVariant(self, jsonRooms, variant)
     if #jsonRoomsOfVariant == 1 then
         return jsonRoomsOfVariant[1]
     end
-    return error(((("Found " .. tostring(#jsonRoomsOfVariant)) .. " JSON rooms with a variant of ") .. tostring(variant)) .. ", when there should only be 1.")
+    error(((("Found " .. tostring(#jsonRoomsOfVariant)) .. " JSON rooms with a variant of ") .. tostring(variant)) .. ", when there should only be 1.")
 end
+--- Helper function to find all of the JSON rooms that match the sub-type provided.
+-- 
+-- @param jsonRooms The array of rooms to search through.
+-- @param subType The sub-type to match.
 function ____exports.getJSONRoomsOfSubType(self, jsonRooms, subType)
     return __TS__ArrayFilter(
         jsonRooms,
@@ -71,6 +127,12 @@ end
 -- Note that this function does not simply choose a random element in the provided array; it will
 -- properly account for each room weight using the algorithm from:
 -- https://stackoverflow.com/questions/1761626/weighted-random-numbers
+-- 
+-- @param jsonRooms The array of rooms to random choose between.
+-- @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 verbose Optional. If specified, will write entries to the "log.txt" file that describe
+-- what the function is doing. Default is false.
 function ____exports.getRandomJSONRoom(self, jsonRooms, seedOrRNG, verbose)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)

package/functions/playerCenter.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Helper function to move all of the players to the center of the room.
+ *
+ * This function emulates what happens in the vanilla game when you travel to a new floor.
+ */
+export declare function movePlayersToCenter(): void;

package/functions/playerCenter.lua

@@ -0,0 +1,57 @@
+local ____exports = {}
+local movePlayerAndTheirFamiliars
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local Direction = ____isaac_2Dtypescript_2Ddefinitions.Direction
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+local ____familiars = require("functions.familiars")
+local getPlayerFamiliars = ____familiars.getPlayerFamiliars
+local ____math = require("functions.math")
+local getCircleDiscretizedPoints = ____math.getCircleDiscretizedPoints
+local ____playerIndex = require("functions.playerIndex")
+local getPlayers = ____playerIndex.getPlayers
+function movePlayerAndTheirFamiliars(self, player, position)
+    player.Position = position
+    local familiars = getPlayerFamiliars(nil, player)
+    for ____, familiar in ipairs(familiars) do
+        familiar.Position = position
+    end
+end
+local CIRCLE_RADIUS_BETWEEN_PLAYERS = 50
+--- Helper function to move all of the players to the center of the room.
+-- 
+-- This function emulates what happens in the vanilla game when you travel to a new floor.
+function ____exports.movePlayersToCenter(self)
+    local room = game:GetRoom()
+    local centerPos = room:GetCenterPos()
+    local players = getPlayers(nil)
+    local firstPlayer = players[1]
+    if firstPlayer == nil then
+        return
+    end
+    if #players == 1 then
+        movePlayerAndTheirFamiliars(nil, firstPlayer, centerPos)
+        return
+    end
+    local circlePoints = getCircleDiscretizedPoints(
+        nil,
+        centerPos,
+        CIRCLE_RADIUS_BETWEEN_PLAYERS,
+        #players,
+        1,
+        1,
+        Direction.LEFT
+    )
+    do
+        local i = 0
+        while i < #players do
+            local player = players[i + 1]
+            local position = circlePoints[i + 1]
+            if player ~= nil and position ~= nil then
+                player.Position = position
+            end
+            i = i + 1
+        end
+    end
+end
+return ____exports

package/functions/rooms.d.ts

@@ -55,7 +55,7 @@ export declare function getRoomTypeName(roomType: RoomType): string;
  * non-existent and are not added to the list.
  *
  * @param includeExtraDimensionalRooms Optional. On some floors (e.g. Downpour 2, Mines 2),
- *                                 extra-dimensional rooms are automatically be generated and can be
+ *                                 extra-dimensional rooms are automatically generated and can be
  *                                 seen when you iterate over the `RoomList`. Default is false.
  */
 export declare function getRooms(includeExtraDimensionalRooms?: boolean): RoomDescriptor[];

package/functions/rooms.lua

@@ -72,7 +72,7 @@ end
 -- non-existent and are not added to the list.
 -- 
 -- @param includeExtraDimensionalRooms Optional. On some floors (e.g. Downpour 2, Mines 2),
--- extra-dimensional rooms are automatically be generated and can be
+-- extra-dimensional rooms are automatically generated and can be
 -- seen when you iterate over the `RoomList`. Default is false.
 function ____exports.getRooms(self, includeExtraDimensionalRooms)
     if includeExtraDimensionalRooms == nil then
@@ -145,7 +145,7 @@ function ____exports.getDimension(self)
             return dimension
         end
     end
-    return error("Failed to get the current dimension.")
+    error("Failed to get the current dimension.")
 end
 --- Helper function to get the number of rooms that are currently on the floor layout. This does not
 -- include off-grid rooms, like the Devil Room.

package/functions/stage.d.ts

@@ -16,10 +16,10 @@ export declare function calculateStageTypeRepentance(stage: LevelStage): StageTy
  */
 export declare function getEffectiveStage(): int;
 /**
- * Helper function to get the prefix to use with the "goto" console command that would correspond to
- * the provided room type.
+ * Helper function to get the corresponding "goto" console command that would correspond to the
+ * provided room type and room variant.
  */
-export declare function getGotoCommandPrefix(roomType: RoomType): string;
+export declare function getGotoCommand(roomType: RoomType, roomVariant: int): string;
 /** Alias for the `Level.GetStage` method. */
 export declare function getStage(): LevelStage;
 /** Alias for the `Level.GetStageType` method. */

package/functions/stage.lua

@@ -64,10 +64,11 @@ function ____exports.getEffectiveStage(self)
     end
     return stage
 end
---- Helper function to get the prefix to use with the "goto" console command that would correspond to
--- the provided room type.
-function ____exports.getGotoCommandPrefix(self, roomType)
-    return ROOM_TYPE_GOTO_PREFIXES[roomType]
+--- Helper function to get the corresponding "goto" console command that would correspond to the
+-- provided room type and room variant.
+function ____exports.getGotoCommand(self, roomType, roomVariant)
+    local prefix = ROOM_TYPE_GOTO_PREFIXES[roomType]
+    return (("goto " .. prefix) .. ".") .. tostring(roomVariant)
 end
 --- Alias for the `Level.GetStage` method.
 function ____exports.getStage(self)

package/functions/trinkets.lua

@@ -76,7 +76,7 @@ function ____exports.getOpenTrinketSlot(self, player)
         end
         return trinketType2 == TrinketType.NULL and 1 or nil
     end
-    return error("The player has an unknown number of trinket slots: " .. tostring(maxTrinkets))
+    error("The player has an unknown number of trinket slots: " .. tostring(maxTrinkets))
 end
 --- Helper function to get the in-game description for a trinket. Returns "Unknown" if the provided
 -- trinket type was not valid.

package/interfaces/CustomStage.d.ts

@@ -1,51 +1,10 @@
-/**
- * This is the format of a custom stage in the "isaacscript" section of the "tsconfig.json" file.
- *
- * The contents of this interface are used to create a "tsconfig-isaacscript-section-schema.json"
- * schema with the "ts-json-schema-generator" library.
- *
- * The contents of this interface are validated at run-time against the schema using the Ajv
- * library.
- *
- * The `CustomStage` interface extends this, adding room metadata.
- */
-export interface CustomStageTSConfig {
-    /** The name of the custom stage. */
-    name: string;
-    /**
-     * Path to the XML file that contains the rooms for the custom stage (created with Basement
-     * Renovator).
-     */
-    xmlPath: string;
-    /** An arbitrarily chosen prefix in the range of 101-999. */
-    roomVariantPrefix: number;
-    /**
-     * An integer between 1 and 13, corresponding to the `LevelStage` enum. This is the number of the
-     * stage that will be warped to and used as a basis for the stage by the level generation
-     * algorithm.
-     */
-    baseStage: number;
-    /**
-     * An integer between 0 and 5, corresponding to the `StageType` enum. This is the number of the
-     * stage type that will be warped to and used as a basis for the stage by the level generation
-     * algorithm.
-     */
-    baseStageType: number;
-}
-/**
- * An object that represents a custom stage. The "metadata.lua" file contains an array of these
- * objects. Besides the room metadata, the data is the same as what is specified inside the
- * "tsconfig.json" file.
- */
-export interface CustomStage extends CustomStageTSConfig {
-    roomsMetadata: CustomStageRoomMetadata[];
-}
-/**
- * Metadata about a custom stage room. Each custom stage object contains an array with metadata for
- * each room.
- */
-export interface CustomStageRoomMetadata {
-    variant: number;
-    shape: number;
-    weight: number;
+import { DoorSlotFlag, RoomShape, RoomType } from "isaac-typescript-definitions";
+import { CustomStageLua, CustomStageRoomMetadata } from "./CustomStageLua";
+export interface CustomStage extends CustomStageLua {
+    /** A map that makes it easier to select certain room type/shape/door combinations. */
+    readonly roomTypeMap: RoomTypeMap;
 }
+export declare type RoomTypeMap = ReadonlyMap<RoomType, RoomShapeMap>;
+declare type RoomShapeMap = ReadonlyMap<RoomShape, RoomDoorSlotMap>;
+declare type RoomDoorSlotMap = ReadonlyMap<DoorSlotFlag, CustomStageRoomMetadata[]>;
+export {};

package/interfaces/CustomStageLua.d.ts

@@ -0,0 +1,118 @@
+/**
+ * This is the format of a custom stage in the "isaacscript" section of the "tsconfig.json" file.
+ *
+ * The contents of this interface are used to create a "tsconfig-isaacscript-section-schema.json"
+ * schema with the "ts-json-schema-generator" library.
+ *
+ * The contents of this interface are validated at run-time against the schema using the Ajv
+ * library.
+ *
+ * The `CustomStageLua` interface extends this, adding room metadata.
+ */
+export interface CustomStageTSConfig {
+    /** The name of the custom stage. Mandatory. */
+    readonly name: string;
+    /**
+     * Path to the XML file that contains the rooms for the custom stage (created with Basement
+     * Renovator). Mandatory.
+     */
+    readonly xmlPath: string;
+    /** An arbitrarily chosen prefix in the range of 101-999. Mandatory. */
+    readonly roomVariantPrefix: number;
+    /**
+     * An integer between 2 and 13, corresponding to the `LevelStage` enum. This is the number of the
+     * stage that will be warped to and used as a basis for the stage by the level generation
+     * algorithm. Mandatory.
+     *
+     * (It is not possible to use Basement 1 as a base due to conflicts with the `Game.SetStage`
+     * method.)
+     */
+    readonly baseStage: number;
+    /**
+     * An integer between 0 and 5, corresponding to the `StageType` enum. This is the number of the
+     * stage type that will be warped to and used as a basis for the stage by the level generation
+     * algorithm. Mandatory.
+     */
+    readonly baseStageType: number;
+    /**
+     * An object containing the paths to the backdrop for the stage. (A backdrop is the graphics for
+     * the walls and floor.) Mandatory.
+     */
+    readonly backdrop: CustomStageBackdrop;
+}
+interface CustomStageBackdrop {
+    /**
+     * The beginning of the path that leads to the backdrop graphics. For example:
+     *
+     * ```sh
+     * gfx/backdrop/revelations/revelations_
+     * ```
+     */
+    prefix: string;
+    /**
+     * The end of the path that leads to the backdrop graphics. In most cases, this will be ".png".
+     */
+    suffix: string;
+    /**
+     * An array of strings that represent the graphic files for the stage's "nFloor". You must have at
+     * least one string in this array, but you can specify more than one to randomly add extra variety
+     * (like the vanilla stages do).
+     *
+     * For an example of this, see the vanilla file "resources/gfx/backdrop/01_basement_nfloor.png".
+     */
+    nFloors: string[];
+    /**
+     * An array of strings that represent the graphic files for the stage's "lFloor". You must have at
+     * least one in the array, but you can specify more than one to randomly add extra variety (like
+     * the vanilla stages do).
+     *
+     * For an example of this, see the vanilla file "resources/gfx/backdrop/01_lbasementfloor.png".
+     */
+    lFloors: string[];
+    /**
+     * An array of strings that represent the graphic files for the stage's walls. You must have at
+     * least one string in this array, but you can specify more than one to randomly add extra variety
+     * (like the vanilla stages do).
+     *
+     * For an example of this, see the vanilla file "resources/gfx/backdrop/01_basement.png". (In the
+     * vanilla file, they concatenate all four variations together into one PNG file. However, for the
+     * custom stages feature, you must separate each wall variation into a separate file.)
+     */
+    walls: string[];
+    /**
+     * An array of strings that represent the graphic files for the stage's corners. You must have at
+     * least one string in this array, but you can specify more than one to randomly add extra variety
+     * (like the vanilla stages do).
+     *
+     * For an example of this, see the vanilla file "resources/gfx/backdrop/01_basement.png". (In the
+     * vanilla file, they concatenate both variations together into one PNG file and put it in the top
+     * right hand corner. The corners are shown in the top right hand corner of the file, with two
+     * different variations concatenated together. However, for the custom stages feature, you must
+     * separate each corner variation into a separate file (and put it in a different file from the
+     * walls).
+     */
+    corners: string[];
+}
+/**
+ * An object that represents a custom stage. The "metadata.lua" file contains an array of these
+ * objects. Besides the room metadata, the data is the same as what is specified inside the
+ * "tsconfig.json" file.
+ *
+ * The `CustomStage` interface extends this, adding more data.
+ */
+export interface CustomStageLua extends CustomStageTSConfig {
+    readonly roomsMetadata: readonly CustomStageRoomMetadata[];
+}
+/**
+ * Metadata about a custom stage room. Each custom stage object contains an array with metadata for
+ * each room.
+ */
+export interface CustomStageRoomMetadata {
+    readonly type: number;
+    readonly variant: number;
+    readonly subType: number;
+    readonly shape: number;
+    readonly doorSlotFlags: number;
+    readonly weight: number;
+}
+export {};

package/interfaces/CustomStageLua.lua

@@ -0,0 +1,2 @@
+local ____exports = {}
+return ____exports

package/objects/roomTypeGotoPrefixes.lua

@@ -2,34 +2,34 @@ local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local RoomType = ____isaac_2Dtypescript_2Ddefinitions.RoomType
 ____exports.ROOM_TYPE_GOTO_PREFIXES = {
-    [RoomType.DEFAULT] = "d.",
-    [RoomType.SHOP] = "s.shop.",
-    [RoomType.ERROR] = "s.error.",
-    [RoomType.TREASURE] = "s.treasure.",
-    [RoomType.BOSS] = "s.boss.",
-    [RoomType.MINI_BOSS] = "s.miniboss.",
-    [RoomType.SECRET] = "s.secret.",
-    [RoomType.SUPER_SECRET] = "s.supersecret.",
-    [RoomType.ARCADE] = "s.arcade.",
-    [RoomType.CURSE] = "s.curse.",
-    [RoomType.CHALLENGE] = "s.challenge.",
-    [RoomType.LIBRARY] = "s.library.",
-    [RoomType.SACRIFICE] = "s.sacrifice.",
-    [RoomType.DEVIL] = "s.devil.",
-    [RoomType.ANGEL] = "s.angel.",
-    [RoomType.DUNGEON] = "s.itemdungeon.",
-    [RoomType.BOSS_RUSH] = "s.bossrush.",
-    [RoomType.CLEAN_BEDROOM] = "s.isaacs.",
-    [RoomType.DIRTY_BEDROOM] = "s.barren.",
-    [RoomType.CHEST] = "s.chest.",
-    [RoomType.DICE] = "s.dice.",
-    [RoomType.BLACK_MARKET] = "s.blackmarket.",
-    [RoomType.GREED_EXIT] = "s.greedexit.",
-    [RoomType.PLANETARIUM] = "s.planetarium.",
-    [RoomType.TELEPORTER] = "s.teleporter.",
-    [RoomType.TELEPORTER_EXIT] = "s.teleporterexit.",
-    [RoomType.SECRET_EXIT] = "s.secretexit.",
-    [RoomType.BLUE] = "s.blue.",
-    [RoomType.ULTRA_SECRET] = "s.ultrasecret."
+    [RoomType.DEFAULT] = "s.default",
+    [RoomType.SHOP] = "s.shop",
+    [RoomType.ERROR] = "s.error",
+    [RoomType.TREASURE] = "s.treasure",
+    [RoomType.BOSS] = "s.boss",
+    [RoomType.MINI_BOSS] = "s.miniboss",
+    [RoomType.SECRET] = "s.secret",
+    [RoomType.SUPER_SECRET] = "s.supersecret",
+    [RoomType.ARCADE] = "s.arcade",
+    [RoomType.CURSE] = "s.curse",
+    [RoomType.CHALLENGE] = "s.challenge",
+    [RoomType.LIBRARY] = "s.library",
+    [RoomType.SACRIFICE] = "s.sacrifice",
+    [RoomType.DEVIL] = "s.devil",
+    [RoomType.ANGEL] = "s.angel",
+    [RoomType.DUNGEON] = "s.itemdungeon",
+    [RoomType.BOSS_RUSH] = "s.bossrush",
+    [RoomType.CLEAN_BEDROOM] = "s.isaacs",
+    [RoomType.DIRTY_BEDROOM] = "s.barren",
+    [RoomType.CHEST] = "s.chest",
+    [RoomType.DICE] = "s.dice",
+    [RoomType.BLACK_MARKET] = "s.blackmarket",
+    [RoomType.GREED_EXIT] = "s.greedexit",
+    [RoomType.PLANETARIUM] = "s.planetarium",
+    [RoomType.TELEPORTER] = "s.teleporter",
+    [RoomType.TELEPORTER_EXIT] = "s.teleporterexit",
+    [RoomType.SECRET_EXIT] = "s.secretexit",
+    [RoomType.BLUE] = "s.blue",
+    [RoomType.ULTRA_SECRET] = "s.ultrasecret"
 }
 return ____exports

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "6.1.1",
+  "version": "6.2.0",
   "description": "Helper functions and features for IsaacScript mods.",
   "keywords": [
     "isaac",