isaacscript-common 6.1.1 → 6.3.0

package/callbacks/reorderedCallbacks.d.ts

@@ -1,3 +1,4 @@
+import { LevelStage, StageType } from "isaac-typescript-definitions";
 /**
  * This is a utility function for users of the `ModCallbackCustom.POST_NEW_LEVEL_REORDERED` custom
  * callback.
@@ -18,3 +19,11 @@ export declare function forceNewLevelCallback(): void;
  * temporarily force the callback to fire.
  */
 export declare function forceNewRoomCallback(): void;
+/**
+ * Helper function to manually set the variable that the reordered callback logic uses to track the
+ * current stage and stage type.
+ *
+ * This is useful because if the stage is changed with the `Game.SetStage` method, the reordered
+ * callbacks will stop working.
+ */
+export declare function reorderedCallbacksSetStage(stage: LevelStage, stageType: StageType): void;

package/callbacks/reorderedCallbacks.lua

@@ -106,4 +106,13 @@ end
 function ____exports.forceNewRoomCallback(self)
     forceNewRoom = true
 end
+--- Helper function to manually set the variable that the reordered callback logic uses to track the
+-- current stage and stage type.
+-- 
+-- This is useful because if the stage is changed with the `Game.SetStage` method, the reordered
+-- callbacks will stop working.
+function ____exports.reorderedCallbacksSetStage(self, stage, stageType)
+    currentStage = stage
+    currentStageType = stageType
+end
 return ____exports

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/constants.d.ts

@@ -85,6 +85,15 @@ export declare const LAST_ROOM_TYPE: RoomType;
  * effect.
  */
 export declare const MAX_SPEED_STAT = 2;
+/** This is in the center of the room. */
+export declare const NEW_FLOOR_STARTING_POSITION_NORMAL_MODE: Vector;
+/** This is near the top door. */
+export declare const NEW_FLOOR_STARTING_POSITION_GREED_MODE: Vector;
+/**
+ * This is next to the bottom door. Presumably, the player does not start in the center of the room
+ * (like they do when getting to a new stage) so that the controls graphic is more visible.
+ */
+export declare const NEW_RUN_PLAYER_STARTING_POSITION: Vector;
 export declare const FIRST_STAGE = LevelStage.BASEMENT_1;
 export declare const LAST_STAGE: LevelStage;
 /** Corresponds to the maximum value for `EntityPlayer.SamsonBerserkCharge`. */

package/constants.lua

@@ -74,6 +74,13 @@ ____exports.LAST_ROOM_TYPE = getLastEnumValue(nil, RoomType)
 --- The maximum speed stat that a player can have. Any additional speed beyond this will not take
 -- effect.
 ____exports.MAX_SPEED_STAT = 2
+--- This is in the center of the room.
+____exports.NEW_FLOOR_STARTING_POSITION_NORMAL_MODE = Vector(320, 280)
+--- This is near the top door.
+____exports.NEW_FLOOR_STARTING_POSITION_GREED_MODE = Vector(320, 280)
+--- This is next to the bottom door. Presumably, the player does not start in the center of the room
+-- (like they do when getting to a new stage) so that the controls graphic is more visible.
+____exports.NEW_RUN_PLAYER_STARTING_POSITION = Vector(320, 380)
 ____exports.FIRST_STAGE = LevelStage.BASEMENT_1
 ____exports.LAST_STAGE = getLastEnumValue(nil, LevelStage)
 --- Corresponds to the maximum value for `EntityPlayer.SamsonBerserkCharge`.

package/enums/CornerType.d.ts

@@ -0,0 +1,6 @@
+export declare enum CornerType {
+    TOP_LEFT = 0,
+    TOP_RIGHT = 1,
+    BOTTOM_LEFT = 2,
+    BOTTOM_RIGHT = 3
+}

package/enums/CornerType.lua

@@ -0,0 +1,11 @@
+local ____exports = {}
+____exports.CornerType = {}
+____exports.CornerType.TOP_LEFT = 0
+____exports.CornerType[____exports.CornerType.TOP_LEFT] = "TOP_LEFT"
+____exports.CornerType.TOP_RIGHT = 1
+____exports.CornerType[____exports.CornerType.TOP_RIGHT] = "TOP_RIGHT"
+____exports.CornerType.BOTTOM_LEFT = 2
+____exports.CornerType[____exports.CornerType.BOTTOM_LEFT] = "BOTTOM_LEFT"
+____exports.CornerType.BOTTOM_RIGHT = 3
+____exports.CornerType[____exports.CornerType.BOTTOM_RIGHT] = "BOTTOM_RIGHT"
+return ____exports

package/features/customStage/backdrop.d.ts

@@ -0,0 +1,2 @@
+import { CustomStage } from "../../interfaces/CustomStage";
+export declare function setBackdrop(customStage: CustomStage): void;

package/features/customStage/backdrop.lua

@@ -0,0 +1,200 @@
+local ____lualib = require("lualib_bundle")
+local Set = ____lualib.Set
+local __TS__New = ____lualib.__TS__New
+local ____exports = {}
+local getBackdropPNGPath, spawnWallEntity, spawnSecondWallEntity, spawnFloorEntity, getNumFloorLayers, BackdropKind, BackdropEntitySubType, ROOM_SHAPE_WALL_ANM2_LAYERS, ROOM_SHAPE_WALL_EXTRA_ANM2_LAYERS, WALL_OFFSET, BACKDROP_EFFECT_VARIANT
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local EffectVariant = ____isaac_2Dtypescript_2Ddefinitions.EffectVariant
+local EntityFlag = ____isaac_2Dtypescript_2Ddefinitions.EntityFlag
+local RoomShape = ____isaac_2Dtypescript_2Ddefinitions.RoomShape
+local RoomType = ____isaac_2Dtypescript_2Ddefinitions.RoomType
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+local ____constants = require("constants")
+local VectorZero = ____constants.VectorZero
+local ____array = require("functions.array")
+local getRandomArrayElement = ____array.getRandomArrayElement
+local ____entitySpecific = require("functions.entitySpecific")
+local spawnEffectWithSeed = ____entitySpecific.spawnEffectWithSeed
+local ____rng = require("functions.rng")
+local newRNG = ____rng.newRNG
+local ____roomShape = require("functions.roomShape")
+local isLRoom = ____roomShape.isLRoom
+local isNarrowRoom = ____roomShape.isNarrowRoom
+local ____string = require("functions.string")
+local trimPrefix = ____string.trimPrefix
+local ____utils = require("functions.utils")
+local erange = ____utils.erange
+local irange = ____utils.irange
+function getBackdropPNGPath(self, customStage, backdropKind, rng)
+    local pathArray = customStage.backdrop[backdropKind]
+    local path = getRandomArrayElement(nil, pathArray, rng)
+    return (customStage.backdrop.prefix .. path) .. customStage.backdrop.suffix
+end
+function spawnWallEntity(self, customStage, rng, isExtraWall)
+    local room = game:GetRoom()
+    local roomShape = room:GetRoomShape()
+    local subType = isExtraWall and BackdropEntitySubType.WALL_EXTRA or BackdropEntitySubType.WALL
+    local wallEffect = spawnEffectWithSeed(
+        nil,
+        BACKDROP_EFFECT_VARIANT,
+        subType,
+        VectorZero,
+        1
+    )
+    wallEffect:AddEntityFlags(EntityFlag.RENDER_WALL)
+    local sprite = wallEffect:GetSprite()
+    sprite:Load("gfx/isaacscript-custom-stage/wall-backdrop.anm2", false)
+    local wallLayersArray = isExtraWall and ROOM_SHAPE_WALL_EXTRA_ANM2_LAYERS or ROOM_SHAPE_WALL_ANM2_LAYERS
+    local numWallLayers = wallLayersArray[roomShape]
+    if numWallLayers == nil then
+        error("Failed to get the layers when creating the backdrop for custom stage: " .. customStage.name)
+    end
+    if isLRoom(nil, roomShape) then
+        local cornerPNGPath = getBackdropPNGPath(nil, customStage, BackdropKind.CORNER, rng)
+        sprite:ReplaceSpritesheet(0, cornerPNGPath)
+    end
+    for ____, layerID in ipairs(irange(nil, 1, numWallLayers)) do
+        local wallPNGPath = getBackdropPNGPath(nil, customStage, BackdropKind.WALL, rng)
+        sprite:ReplaceSpritesheet(layerID, wallPNGPath)
+    end
+    local topLeftPos = room:GetTopLeftPos()
+    local renderPos = topLeftPos + WALL_OFFSET
+    local modifiedOffset = renderPos / 40 * 26
+    wallEffect.SpriteOffset = modifiedOffset
+    sprite:LoadGraphics()
+    local roomShapeName = RoomShape[roomShape]
+    local animation = trimPrefix(nil, roomShapeName, "SHAPE_")
+    local modifiedAnimation = isExtraWall and animation .. "X" or animation
+    sprite:Play(modifiedAnimation, true)
+end
+function spawnSecondWallEntity(self, customStage, rng)
+    local room = game:GetRoom()
+    local roomShape = room:GetRoomShape()
+    local extraLayers = ROOM_SHAPE_WALL_EXTRA_ANM2_LAYERS[roomShape]
+    local roomShapeHasExtraLayers = extraLayers ~= nil
+    if roomShapeHasExtraLayers then
+        spawnWallEntity(nil, customStage, rng, true)
+    end
+end
+function spawnFloorEntity(self, customStage, rng)
+    local room = game:GetRoom()
+    local roomShape = room:GetRoomShape()
+    local floorEffect = spawnEffectWithSeed(
+        nil,
+        BACKDROP_EFFECT_VARIANT,
+        BackdropEntitySubType.FLOOR,
+        VectorZero,
+        1
+    )
+    floorEffect:AddEntityFlags(EntityFlag.RENDER_FLOOR)
+    local sprite = floorEffect:GetSprite()
+    sprite:Load("gfx/isaacscript-custom-stage/floor-backdrop.anm2", false)
+    local numFloorLayers = getNumFloorLayers(nil, roomShape)
+    if numFloorLayers ~= nil then
+        for ____, layerID in ipairs(erange(nil, 0, numFloorLayers)) do
+            local wallPNGPath = getBackdropPNGPath(nil, customStage, BackdropKind.WALL, rng)
+            sprite:ReplaceSpritesheet(layerID, wallPNGPath)
+        end
+    end
+    if isLRoom(nil, roomShape) then
+        for ____, layerID in ipairs({16, 17}) do
+            local LFloorPNGPath = getBackdropPNGPath(nil, customStage, BackdropKind.L_FLOOR, rng)
+            sprite:ReplaceSpritesheet(layerID, LFloorPNGPath)
+        end
+    end
+    if isNarrowRoom(nil, roomShape) then
+        for ____, layerID in ipairs({18, 19}) do
+            local NFloorPNGPath = getBackdropPNGPath(nil, customStage, BackdropKind.N_FLOOR, rng)
+            sprite:ReplaceSpritesheet(layerID, NFloorPNGPath)
+        end
+    end
+    local topLeftPos = room:GetTopLeftPos()
+    local renderPos = topLeftPos
+    local modifiedOffset = renderPos / 40 * 26
+    floorEffect.SpriteOffset = modifiedOffset
+    sprite:LoadGraphics()
+    local roomShapeName = RoomShape[roomShape]
+    local animation = trimPrefix(nil, roomShapeName, "SHAPE_")
+    sprite:Play(animation, true)
+end
+function getNumFloorLayers(self, roomShape)
+    repeat
+        local ____switch23 = roomShape
+        local ____cond23 = ____switch23 == RoomShape.SHAPE_1x1
+        if ____cond23 then
+            do
+                return 4
+            end
+        end
+        ____cond23 = ____cond23 or (____switch23 == RoomShape.SHAPE_1x2 or ____switch23 == RoomShape.SHAPE_2x1)
+        if ____cond23 then
+            do
+                return 8
+            end
+        end
+        ____cond23 = ____cond23 or ____switch23 == RoomShape.SHAPE_2x2
+        if ____cond23 then
+            do
+                return 16
+            end
+        end
+        do
+            do
+                return nil
+            end
+        end
+    until true
+end
+BackdropKind = BackdropKind or ({})
+BackdropKind.N_FLOOR = "nFloors"
+BackdropKind.L_FLOOR = "lFloors"
+BackdropKind.WALL = "walls"
+BackdropKind.CORNER = "corners"
+BackdropEntitySubType = BackdropEntitySubType or ({})
+BackdropEntitySubType.VANILLA_LADDER = 0
+BackdropEntitySubType[BackdropEntitySubType.VANILLA_LADDER] = "VANILLA_LADDER"
+BackdropEntitySubType.WALL = 1
+BackdropEntitySubType[BackdropEntitySubType.WALL] = "WALL"
+BackdropEntitySubType.WALL_EXTRA = 2
+BackdropEntitySubType[BackdropEntitySubType.WALL_EXTRA] = "WALL_EXTRA"
+BackdropEntitySubType.FLOOR = 3
+BackdropEntitySubType[BackdropEntitySubType.FLOOR] = "FLOOR"
+ROOM_SHAPE_WALL_ANM2_LAYERS = {
+    [RoomShape.SHAPE_1x1] = 44,
+    [RoomShape.IH] = 36,
+    [RoomShape.IV] = 28,
+    [RoomShape.SHAPE_1x2] = 58,
+    [RoomShape.IIV] = 42,
+    [RoomShape.SHAPE_2x1] = 63,
+    [RoomShape.IIH] = 62,
+    [RoomShape.SHAPE_2x2] = 63,
+    [RoomShape.LTL] = 63,
+    [RoomShape.LTR] = 63,
+    [RoomShape.LBL] = 63,
+    [RoomShape.LBR] = 63
+}
+ROOM_SHAPE_WALL_EXTRA_ANM2_LAYERS = {
+    [RoomShape.SHAPE_2x1] = 7,
+    [RoomShape.SHAPE_2x2] = 21,
+    [RoomShape.LTL] = 19,
+    [RoomShape.LTR] = 19,
+    [RoomShape.LBL] = 19,
+    [RoomShape.LBR] = 19
+}
+WALL_OFFSET = Vector(-80, -80)
+BACKDROP_EFFECT_VARIANT = EffectVariant.LADDER
+local BACKDROP_ROOM_TYPE_SET = __TS__New(Set, {RoomType.DEFAULT, RoomType.BOSS, RoomType.MINI_BOSS})
+function ____exports.setBackdrop(self, customStage)
+    local room = game:GetRoom()
+    local roomType = room:GetType()
+    local decorationSeed = room:GetDecorationSeed()
+    local rng = newRNG(nil, decorationSeed)
+    if not BACKDROP_ROOM_TYPE_SET:has(roomType) then
+        return
+    end
+    spawnWallEntity(nil, customStage, rng, false)
+    spawnSecondWallEntity(nil, customStage, rng)
+    spawnFloorEntity(nil, customStage, rng)
+end
+return ____exports

package/features/customStage/boss.d.ts

@@ -0,0 +1,2 @@
+export declare function playBossRoomAnimation(force?: boolean): void;
+export declare function bossPostRender(): void;

package/features/customStage/boss.lua

@@ -0,0 +1,74 @@
+local ____exports = {}
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local RoomType = ____isaac_2Dtypescript_2Ddefinitions.RoomType
+local SoundEffect = ____isaac_2Dtypescript_2Ddefinitions.SoundEffect
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+local sfxManager = ____cachedClasses.sfxManager
+local ____pause = require("features.pause")
+local pause = ____pause.pause
+local unpause = ____pause.unpause
+local ____v = require("features.customStage.v")
+local v = ____v.default
+local VERSUS_SCREEN_ANIMATION = "Scene"
+--- Taken from StageAPI. I do not know why rendering in a certain order is necessary, but otherwise
+-- the overlay layer will be on top of everything else and will hide the other elements.
+local VERSUS_SCREEN_LAYER_RENDER_ORDER = {
+    0,
+    1,
+    2,
+    3,
+    9,
+    14,
+    13,
+    4,
+    5,
+    12,
+    11,
+    6,
+    7,
+    8,
+    10
+}
+local versusScreenSprite = Sprite()
+versusScreenSprite:Load("gfx/ui/boss/versusscreen.anm2", true)
+function ____exports.playBossRoomAnimation(self, force)
+    if force == nil then
+        force = false
+    end
+    local room = game:GetRoom()
+    local roomType = room:GetType()
+    local hud = game:GetHUD()
+    if roomType ~= RoomType.BOSS and not force then
+        return
+    end
+    v.run.showingBossVersusScreen = true
+    pause(nil)
+    hud:SetVisible(false)
+    versusScreenSprite:Play(VERSUS_SCREEN_ANIMATION, true)
+    versusScreenSprite.PlaybackSpeed = 0.5
+end
+local function finishBossRoomAnimation(self)
+    local hud = game:GetHUD()
+    v.run.showingBossVersusScreen = false
+    unpause(nil)
+    hud:SetVisible(true)
+    sfxManager:Play(SoundEffect.CASTLE_PORTCULLIS)
+end
+function ____exports.bossPostRender(self)
+    if not v.run.showingBossVersusScreen then
+        return
+    end
+    if versusScreenSprite:IsFinished(VERSUS_SCREEN_ANIMATION) then
+        finishBossRoomAnimation(nil)
+        return
+    end
+    local room = game:GetRoom()
+    local centerPos = room:GetCenterPos()
+    local position = Isaac.WorldToRenderPosition(centerPos)
+    for ____, layerID in ipairs(VERSUS_SCREEN_LAYER_RENDER_ORDER) do
+        versusScreenSprite:RenderLayer(layerID, position)
+    end
+    versusScreenSprite:Update()
+end
+return ____exports

package/features/customStage/exports.d.ts

@@ -1,6 +1,8 @@
 /**
  * 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;
+export declare function setCustomStageDebug(): void;

package/features/customStage/exports.lua

@@ -1,15 +1,121 @@
 local ____lualib = require("lualib_bundle")
 local Map = ____lualib.Map
 local ____exports = {}
+local postRoomTransition
+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 ____reorderedCallbacks = require("callbacks.reorderedCallbacks")
+local reorderedCallbacksSetStage = ____reorderedCallbacks.reorderedCallbacksSetStage
+local ____log = require("functions.log")
+local log = ____log.log
+local logError = ____log.logError
+local ____playerCenter = require("functions.playerCenter")
+local movePlayersToCenter = ____playerCenter.movePlayersToCenter
+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 ____runNextRoom = require("features.runNextRoom")
+local runNextRoom = ____runNextRoom.runNextRoom
+local ____boss = require("features.customStage.boss")
+local playBossRoomAnimation = ____boss.playBossRoomAnimation
+local ____util = require("features.customStage.util")
+local getRandomCustomStageRoom = ____util.getRandomCustomStageRoom
 local ____v = require("features.customStage.v")
+local v = ____v.default
+local customStageCachedRoomData = ____v.customStageCachedRoomData
 local customStagesMap = ____v.customStagesMap
+function postRoomTransition(self)
+    movePlayersToCenter(nil)
+end
 --- 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)
+    v.run.currentCustomStage = customStage
+    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
+    local stage = -1
+    local stageType = StageType.WRATH_OF_THE_LAMB
+    level:SetStage(stage, stageType)
+    reorderedCallbacksSetStage(nil, stage, stageType)
+    game:StartRoomTransition(startingRoomGridIndex, Direction.NO_DIRECTION, RoomTransitionAnim.FADE)
+    runNextRoom(nil, postRoomTransition)
+end
+function ____exports.setCustomStageDebug(self)
+    local customStage = v.run.currentCustomStage
+    if customStage == nil then
+        log("No custom stage is currently loaded.")
+        return
     end
+    playBossRoomAnimation(nil, true)
 end
 return ____exports

package/features/customStage/init.d.ts

@@ -1 +1,2 @@
-export declare function customStageInit(): void;
+import { ModUpgraded } from "../../classes/ModUpgraded";
+export declare function customStageInit(mod: ModUpgraded): void;

package/features/customStage/init.lua

@@ -1,18 +1,77 @@
 local ____lualib = require("lualib_bundle")
 local Map = ____lualib.Map
+local __TS__ObjectAssign = ____lualib.__TS__ObjectAssign
+local __TS__New = ____lualib.__TS__New
 local ____exports = {}
+local initRoomTypeMaps, getRoomTypeMap, postRender, postNewRoomReordered
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local ModCallback = ____isaac_2Dtypescript_2Ddefinitions.ModCallback
+local ____ModCallbackCustom = require("enums.ModCallbackCustom")
+local ModCallbackCustom = ____ModCallbackCustom.ModCallbackCustom
 local ____array = require("functions.array")
 local isArray = ____array.isArray
+local ____exports = require("features.saveDataManager.exports")
+local saveDataManager = ____exports.saveDataManager
+local ____backdrop = require("features.customStage.backdrop")
+local setBackdrop = ____backdrop.setBackdrop
+local ____boss = require("features.customStage.boss")
+local bossPostRender = ____boss.bossPostRender
+local playBossRoomAnimation = ____boss.playBossRoomAnimation
 local metadataJSON = require("features.customStage.metadata")
 local ____v = require("features.customStage.v")
+local v = ____v.default
 local customStagesMap = ____v.customStagesMap
-function ____exports.customStageInit(self)
-    local customStages = metadataJSON
-    if not isArray(nil, customStages) then
+function initRoomTypeMaps(self)
+    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
+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 postRender(self)
+    bossPostRender(nil)
+end
+function postNewRoomReordered(self)
+    local customStage = v.run.currentCustomStage
+    if customStage == nil then
+        return
+    end
+    setBackdrop(nil, customStage)
+    playBossRoomAnimation(nil)
+end
+function ____exports.customStageInit(self, mod)
+    saveDataManager(nil, "customStage", v)
+    initRoomTypeMaps(nil)
+    mod:AddCallback(ModCallback.POST_RENDER, postRender)
+    mod:AddCallbackCustom(ModCallbackCustom.POST_NEW_ROOM_REORDERED, postNewRoomReordered)
+end
 return ____exports

package/features/customStage/stageAPIBoss.d.ts

@@ -0,0 +1,29 @@
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+interface ParamTable {
+    BossPortrait?: string;
+    BossPortraitTwo?: string;
+    BossName?: string;
+    BossSpot?: string;
+    PlayerPortrait?: string;
+    PlayerName?: string;
+    PlayerSpot?: string;
+    Unskippable?: boolean;
+    BackgroundColor?: Color;
+    DirtColor?: Color;
+    NoShake?: boolean;
+    Animation?: string;
+    Sprite?: Sprite;
+    NoLoadGraphics?: boolean;
+    BossOffset?: Vector;
+}
+declare const StageAPILocal: {
+    BossSprite: Sprite | undefined;
+    BossSpriteBg: Sprite | undefined;
+    BossSpriteDirt: Sprite | undefined;
+    PlayingBossSprite: Sprite | undefined;
+    PlayingBossSpriteBg: Sprite | undefined;
+    PlayingBossSpriteDirt: Sprite | undefined;
+    BossOffset: Vector | undefined;
+};

package/features/customStage/stageAPIBoss.lua

@@ -0,0 +1,9 @@
+local StageAPILocal = {
+    BossSprite = nil,
+    BossSpriteBg = nil,
+    BossSpriteDirt = nil,
+    PlayingBossSprite = nil,
+    PlayingBossSpriteBg = nil,
+    PlayingBossSpriteDirt = nil,
+    BossOffset = nil
+}

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;