isaacscript-common 6.2.1 → 6.5.0

package/cachedClasses.d.ts

@@ -38,3 +38,18 @@ export declare const musicManager: MusicManager;
  * `Room`) is not safe and can lead to the game crashing in certain situations.
  */
 export declare const sfxManager: SFXManager;
+/**
+ * An object containing all 7 vanilla fonts that are pre-loaded and ready to use.
+ *
+ * For more information on the vanilla fonts and to see what they look like, see:
+ * https://wofsauge.github.io/IsaacDocs/rep/tutorials/Tutorial-Rendertext.html
+ */
+export declare const fonts: {
+    readonly droid: Font;
+    readonly pfTempestaSevenCondensed: Font;
+    readonly teamMeatFont10: Font;
+    readonly teamMeatFont12: Font;
+    readonly teamMeatFont16Bold: Font;
+    readonly terminus: Font;
+    readonly upheaval: Font;
+};

package/cachedClasses.lua

@@ -27,4 +27,24 @@ ____exports.musicManager = MusicManager()
 -- Caching the results of this constructor is safe, but caching other classes (like `Level` or
 -- `Room`) is not safe and can lead to the game crashing in certain situations.
 ____exports.sfxManager = SFXManager()
+--- An object containing all 7 vanilla fonts that are pre-loaded and ready to use.
+-- 
+-- For more information on the vanilla fonts and to see what they look like, see:
+-- https://wofsauge.github.io/IsaacDocs/rep/tutorials/Tutorial-Rendertext.html
+____exports.fonts = {
+    droid = Font(),
+    pfTempestaSevenCondensed = Font(),
+    teamMeatFont10 = Font(),
+    teamMeatFont12 = Font(),
+    teamMeatFont16Bold = Font(),
+    terminus = Font(),
+    upheaval = Font()
+}
+____exports.fonts.droid:Load("font/droid.fnt")
+____exports.fonts.pfTempestaSevenCondensed:Load("font/pftempestasevencondensed.fnt")
+____exports.fonts.teamMeatFont10:Load("font/teammeatfont10.fnt")
+____exports.fonts.teamMeatFont12:Load("font/teammeatfont12.fnt")
+____exports.fonts.teamMeatFont16Bold:Load("font/teammeatfont16bold.fnt")
+____exports.fonts.terminus:Load("font/terminus.fnt")
+____exports.fonts.upheaval:Load("font/upheaval.fnt")
 return ____exports

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/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`. */
@@ -106,12 +115,25 @@ export declare const TAINTED_SAMSON_BERSERK_CHARGE_FROM_TAKING_DAMAGE = 10000;
  */
 export declare const UI_HEART_WIDTH = 12;
 /**
- * This is a safer version of the `Vector.One` constant. (Other mods can mutate this `Vector.One`,
- * so it is not safe to use.)
+ * This is a safer version of the `Vector.One` constant. (Other mods can mutate `Vector.One`, so it
+ * is not safe to use.)
  */
 export declare const VectorOne: Readonly<Vector>;
 /**
- * This is a safer version of the `Vector.Zero` constant. (Other mods can mutate `Vector.Zero`
- * vector, so it is not safe to use.)
+ * This is a safer version of the `Vector.Zero` constant. (Other mods can mutate `Vector.Zero`, so
+ * it is not safe to use.)
  */
 export declare const VectorZero: Readonly<Vector>;
+/**
+ * This is a safer version of the `Color.Default` constant. (Other mods can mutate `Color.Default`,
+ * so it is not safe to use.)
+ *
+ * If you need to mutate this, make a copy first with the `copyColor` helper function.
+ */
+export declare const ColorDefault: Readonly<Color>;
+/**
+ * Equal to `KColor(1, 1, 1, 1)`.
+ *
+ * If you need to mutate this, make a copy first with the `copyKColor` helper function.
+ */
+export declare const KColorDefault: Readonly<KColor>;

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`.
@@ -90,10 +97,19 @@ ____exports.TAINTED_SAMSON_BERSERK_CHARGE_FROM_TAKING_DAMAGE = 10000
 --- This is the number of draw coordinates that each heart spans on the UI in the upper left hand
 -- corner.
 ____exports.UI_HEART_WIDTH = 12
---- This is a safer version of the `Vector.One` constant. (Other mods can mutate this `Vector.One`,
--- so it is not safe to use.)
+--- This is a safer version of the `Vector.One` constant. (Other mods can mutate `Vector.One`, so it
+-- is not safe to use.)
 ____exports.VectorOne = Vector(1, 1)
---- This is a safer version of the `Vector.Zero` constant. (Other mods can mutate `Vector.Zero`
--- vector, so it is not safe to use.)
+--- This is a safer version of the `Vector.Zero` constant. (Other mods can mutate `Vector.Zero`, so
+-- it is not safe to use.)
 ____exports.VectorZero = Vector(0, 0)
+--- This is a safer version of the `Color.Default` constant. (Other mods can mutate `Color.Default`,
+-- so it is not safe to use.)
+-- 
+-- If you need to mutate this, make a copy first with the `copyColor` helper function.
+____exports.ColorDefault = Color(1, 1, 1)
+--- Equal to `KColor(1, 1, 1, 1)`.
+-- 
+-- If you need to mutate this, make a copy first with the `copyKColor` helper function.
+____exports.KColorDefault = KColor(1, 1, 1, 1)
 return ____exports

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

@@ -0,0 +1,9 @@
+export declare enum DecorationVariant {
+    VANILLA_DECORATION = 0,
+    /**
+     * The vanilla game does not support any custom grid entities. Under the hood, IsaacScript allows
+     * for custom grid entities by using decorations with this variant to represent custom grid
+     * entities.
+     */
+    CUSTOM_GRID_ENTITY = 1
+}

package/enums/DecorationVariant.lua

@@ -0,0 +1,7 @@
+local ____exports = {}
+____exports.DecorationVariant = {}
+____exports.DecorationVariant.VANILLA_DECORATION = 0
+____exports.DecorationVariant[____exports.DecorationVariant.VANILLA_DECORATION] = "VANILLA_DECORATION"
+____exports.DecorationVariant.CUSTOM_GRID_ENTITY = 1
+____exports.DecorationVariant[____exports.DecorationVariant.CUSTOM_GRID_ENTITY] = "CUSTOM_GRID_ENTITY"
+return ____exports

package/enums/RockAltType.d.ts

@@ -0,0 +1,7 @@
+export declare enum RockAltType {
+    URN = 0,
+    MUSHROOM = 1,
+    SKULL = 2,
+    POLYP = 3,
+    BUCKET = 4
+}

package/enums/RockAltType.lua

@@ -0,0 +1,13 @@
+local ____exports = {}
+____exports.RockAltType = {}
+____exports.RockAltType.URN = 0
+____exports.RockAltType[____exports.RockAltType.URN] = "URN"
+____exports.RockAltType.MUSHROOM = 1
+____exports.RockAltType[____exports.RockAltType.MUSHROOM] = "MUSHROOM"
+____exports.RockAltType.SKULL = 2
+____exports.RockAltType[____exports.RockAltType.SKULL] = "SKULL"
+____exports.RockAltType.POLYP = 3
+____exports.RockAltType[____exports.RockAltType.POLYP] = "POLYP"
+____exports.RockAltType.BUCKET = 4
+____exports.RockAltType[____exports.RockAltType.BUCKET] = "BUCKET"
+return ____exports

package/features/customGridEntity.d.ts

@@ -3,8 +3,8 @@ import { GridCollisionClass, GridEntityType } from "isaac-typescript-definitions
  * Helper function to spawn a custom grid entity.
  *
  * This is an IsaacScript feature because the vanilla game does not support any custom grid
- * entities. Under the hood, IsaacScript accomplishes this by using decorations to represent custom
- * grid entities.
+ * entities. Under the hood, IsaacScript accomplishes this by using decorations with an arbitrary
+ * non-zero variant to represent custom grid entities.
  *
  * Once a custom grid entity is spawned, you can take advantage of the custom grid callbacks such as
  * `POST_GRID_ENTITY_CUSTOM_UPDATE`.

package/features/customGridEntity.lua

@@ -10,13 +10,15 @@ local ____cachedClasses = require("cachedClasses")
 local game = ____cachedClasses.game
 local ____DefaultMap = require("classes.DefaultMap")
 local DefaultMap = ____DefaultMap.DefaultMap
+local ____DecorationVariant = require("enums.DecorationVariant")
+local DecorationVariant = ____DecorationVariant.DecorationVariant
 local ____ModCallbackCustom = require("enums.ModCallbackCustom")
 local ModCallbackCustom = ____ModCallbackCustom.ModCallbackCustom
 local ____featuresInitialized = require("featuresInitialized")
 local errorIfFeaturesNotInitialized = ____featuresInitialized.errorIfFeaturesNotInitialized
 local ____gridEntity = require("functions.gridEntity")
 local removeGrid = ____gridEntity.removeGrid
-local spawnGrid = ____gridEntity.spawnGrid
+local spawnGridWithVariant = ____gridEntity.spawnGridWithVariant
 local ____roomData = require("functions.roomData")
 local getRoomListIndex = ____roomData.getRoomListIndex
 local ____vector = require("functions.vector")
@@ -60,8 +62,8 @@ end
 --- Helper function to spawn a custom grid entity.
 -- 
 -- This is an IsaacScript feature because the vanilla game does not support any custom grid
--- entities. Under the hood, IsaacScript accomplishes this by using decorations to represent custom
--- grid entities.
+-- entities. Under the hood, IsaacScript accomplishes this by using decorations with an arbitrary
+-- non-zero variant to represent custom grid entities.
 -- 
 -- Once a custom grid entity is spawned, you can take advantage of the custom grid callbacks such as
 -- `POST_GRID_ENTITY_CUSTOM_UPDATE`.
@@ -84,8 +86,8 @@ function ____exports.spawnCustomGrid(self, gridEntityTypeCustom, gridIndexOrPosi
     local roomListIndex = getRoomListIndex(nil)
     local gridIndex = isVector(nil, gridIndexOrPosition) and room:GetGridIndex(gridIndexOrPosition) or gridIndexOrPosition
     local existingGridEntity = room:GetGridEntity(gridIndex)
-    local isExistingDecoration = existingGridEntity ~= nil and existingGridEntity:GetType() == GridEntityType.DECORATION
-    local decoration = isExistingDecoration and existingGridEntity or spawnGrid(nil, GridEntityType.DECORATION, gridIndexOrPosition)
+    local isExistingDecoration = existingGridEntity ~= nil and existingGridEntity:GetType() == GridEntityType.DECORATION and existingGridEntity:GetVariant() == DecorationVariant.CUSTOM_GRID_ENTITY
+    local decoration = isExistingDecoration and existingGridEntity or spawnGridWithVariant(nil, GridEntityType.DECORATION, DecorationVariant.CUSTOM_GRID_ENTITY, gridIndexOrPosition)
     if decoration == nil then
         error("Failed to spawn a decoration for a custom grid entity.")
     end

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,211 @@
+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, DEFAULT_BACKDROP, 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
+local ____customStageConstants = require("features.customStage.customStageConstants")
+local ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH = ____customStageConstants.ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH
+function getBackdropPNGPath(self, customStage, backdropKind, rng)
+    local backdrop = customStage.backdrop == nil and DEFAULT_BACKDROP or customStage.backdrop
+    local pathArray = backdrop[backdropKind]
+    local path = getRandomArrayElement(nil, pathArray, rng)
+    return (backdrop.prefix .. path) .. 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(ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH .. "/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(ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH .. "/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"
+DEFAULT_BACKDROP = {
+    prefix = ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH .. "/backdrop",
+    suffix = ".png",
+    nFloors = {"nfloor"},
+    lFloors = {"lfloor"},
+    walls = {"wall"},
+    corners = {"corner"}
+}
+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/customStageConstants.d.ts

@@ -0,0 +1 @@
+export declare const ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH = "gfx/isaacscript-custom-stage";

package/features/customStage/customStageConstants.lua

@@ -0,0 +1,3 @@
+local ____exports = {}
+____exports.ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH = "gfx/isaacscript-custom-stage"
+return ____exports

package/features/customStage/exports.d.ts

@@ -1,3 +1,4 @@
+import { EntityType } from "isaac-typescript-definitions";
 /**
  * Helper function to warp to a custom stage/level.
  *
@@ -5,3 +6,30 @@
  * more details: https://isaacscript.github.io/main/custom-stages/
  */
 export declare function setCustomStage(name: string, verbose?: boolean): void;
+export declare function setCustomStageDebug(): void;
+/**
+ * By default, unknown bosses will be drawn on the boss "versus" screen as "???". If your custom
+ * stage has custom bosses, you can use this function to register the corresponding graphic file
+ * files for them.
+ *
+ * For reference:
+ * - The vanilla name sprite for Monstro is located at "C:\Program Files
+ *   (x86)\Steam\steamapps\common\The Binding of Isaac
+ *   Rebirth\resources\gfx\ui\boss\bossname_20.0_monstro.png".
+ * - The vanilla portrait sprite for Monstro is located at "C:\Program Files
+ *   (x86)\Steam\steamapps\common\The Binding of Isaac
+ *   Rebirth\resources\gfx\ui\boss\portrait_20.0_monstro.png".
+ *
+ * (Note that boss metadata like this cannot be specified with the rest of the custom stage metadata
+ * in the "tsconfig.json" file because there is not a way to retrieve the name of an entity at
+ * run-time.)
+ *
+ * @param entityType The entity type of the custom boss.
+ * @param variant The variant of the custom boss.
+ * @param subType The sub-type of the custom boss.
+ * @param namePNGPath The full path to the PNG file that contains the name of the boss that will be
+ *                    displayed on the top of the boss "versus" screen.
+ * @param portraitPNGPath The full path to the PNG file that contains the portrait of the boss that
+ *                        will be displayed on the right side of the boss "versus" screen.
+ */
+export declare function registerCustomBoss(entityType: EntityType, variant: int, subType: int, namePNGPath: string, portraitPNGPath: string): void;

package/features/customStage/exports.lua

@@ -1,6 +1,7 @@
 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
@@ -10,8 +11,15 @@ 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 ____entity = require("functions.entity")
+local getEntityIDFromConstituents = ____entity.getEntityIDFromConstituents
 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")
@@ -21,11 +29,20 @@ 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 ____util = require("features.customStage.util")
 local getRandomCustomStageRoom = ____util.getRandomCustomStageRoom
 local ____v = require("features.customStage.v")
+local v = ____v.default
+local customBossPNGPaths = ____v.customBossPNGPaths
 local customStageCachedRoomData = ____v.customStageCachedRoomData
 local customStagesMap = ____v.customStagesMap
+local ____versusScreen = require("features.customStage.versusScreen")
+local playVersusScreenAnimation = ____versusScreen.playVersusScreenAnimation
+function postRoomTransition(self)
+    movePlayersToCenter(nil)
+end
 --- Helper function to warp to a custom stage/level.
 -- 
 -- Custom stages/levels must first be defined in the "tsconfig.json" file. See the documentation for
@@ -43,6 +60,7 @@ function ____exports.setCustomStage(self, name, verbose)
     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
@@ -88,7 +106,46 @@ function ____exports.setCustomStage(self, name, verbose)
         end
         ::__continue4::
     end
-    level:SetStage(-1, StageType.ORIGINAL)
+    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
+    playVersusScreenAnimation(nil, customStage, true)
+end
+--- By default, unknown bosses will be drawn on the boss "versus" screen as "???". If your custom
+-- stage has custom bosses, you can use this function to register the corresponding graphic file
+-- files for them.
+-- 
+-- For reference:
+-- - The vanilla name sprite for Monstro is located at "C:\Program Files
+--   (x86)\Steam\steamapps\common\The Binding of Isaac
+--   Rebirth\resources\gfx\ui\boss\bossname_20.0_monstro.png".
+-- - The vanilla portrait sprite for Monstro is located at "C:\Program Files
+--   (x86)\Steam\steamapps\common\The Binding of Isaac
+--   Rebirth\resources\gfx\ui\boss\portrait_20.0_monstro.png".
+-- 
+-- (Note that boss metadata like this cannot be specified with the rest of the custom stage metadata
+-- in the "tsconfig.json" file because there is not a way to retrieve the name of an entity at
+-- run-time.)
+-- 
+-- @param entityType The entity type of the custom boss.
+-- @param variant The variant of the custom boss.
+-- @param subType The sub-type of the custom boss.
+-- @param namePNGPath The full path to the PNG file that contains the name of the boss that will be
+-- displayed on the top of the boss "versus" screen.
+-- @param portraitPNGPath The full path to the PNG file that contains the portrait of the boss that
+-- will be displayed on the right side of the boss "versus" screen.
+function ____exports.registerCustomBoss(self, entityType, variant, subType, namePNGPath, portraitPNGPath)
+    local entityID = getEntityIDFromConstituents(nil, entityType, variant, subType)
+    customBossPNGPaths:set(entityID, {namePNGPath, portraitPNGPath})
 end
 return ____exports

package/features/customStage/gridEntities.d.ts

@@ -0,0 +1,18 @@
+/// <reference types="isaac-typescript-definitions" />
+import { CustomStage } from "../../interfaces/CustomStage";
+/** For `GridEntityType.DECORATION` (1) */
+export declare function setCustomDecorationGraphics(customStage: CustomStage, gridEntity: GridEntity): void;
+/** For `GridEntityType.ROCK` (2) */
+export declare function setCustomRockGraphics(customStage: CustomStage, gridEntity: GridEntity): void;
+/** For `GridEntityType.PIT` (7) */
+export declare function setCustomPitGraphics(customStage: CustomStage, gridEntity: GridEntity): void;
+/** For GridEntityType.DOOR (16) */
+export declare function setCustomDoorGraphics(customStage: CustomStage, gridEntity: GridEntity): void;
+/**
+ * The rewards are based on the ones from the wiki:
+ * https://bindingofisaacrebirth.fandom.com/wiki/Rocks#Urns
+ *
+ * On the bugged stage of -1, only urns will spawn, so we do not have to handle the case of mushroom
+ * rewards, skull rewards, and so on.
+ */
+export declare function removeUrnRewards(customStage: CustomStage, gridEntity: GridEntity): void;