isaacscript-common 6.2.0 → 6.4.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/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,202 @@
+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
+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 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(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"
+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/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

@@ -3,12 +3,37 @@ local Map = ____lualib.Map
 local __TS__ObjectAssign = ____lualib.__TS__ObjectAssign
 local __TS__New = ____lualib.__TS__New
 local ____exports = {}
-local getRoomTypeMap
+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 metadataJSON = require("features.customStage.metadata")
+local ____streakText = require("features.customStage.streakText")
+local streakTextPostRender = ____streakText.streakTextPostRender
 local ____v = require("features.customStage.v")
+local v = ____v.default
 local customStagesMap = ____v.customStagesMap
+local ____versusScreen = require("features.customStage.versusScreen")
+local playVersusScreenAnimation = ____versusScreen.playVersusScreenAnimation
+local versusScreenPostRender = ____versusScreen.versusScreenPostRender
+function initRoomTypeMaps(self)
+    if not isArray(nil, metadataJSON) 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
+    local customStagesLua = metadataJSON
+    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
@@ -34,15 +59,26 @@ function getRoomTypeMap(self, customStageLua)
     end
     return roomTypeMap
 end
-function ____exports.customStageInit(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.")
+function postRender(self)
+    local customStage = v.run.currentCustomStage
+    if customStage == nil then
+        return
     end
-    for ____, customStageLua in ipairs(customStagesLua) do
-        local roomTypeMap = getRoomTypeMap(nil, customStageLua)
-        local customStage = __TS__ObjectAssign({}, customStageLua, {roomTypeMap = roomTypeMap})
-        customStagesMap:set(customStage.name, customStage)
+    streakTextPostRender(nil, customStage)
+    versusScreenPostRender(nil)
+end
+function postNewRoomReordered(self)
+    local customStage = v.run.currentCustomStage
+    if customStage == nil then
+        return
     end
+    setBackdrop(nil, customStage)
+    playVersusScreenAnimation(nil, customStage)
+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/streakText.d.ts

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

package/features/customStage/streakText.lua

@@ -0,0 +1,22 @@
+local ____exports = {}
+local ____cachedClasses = require("cachedClasses")
+local fonts = ____cachedClasses.fonts
+local ____constants = require("constants")
+local KColorDefault = ____constants.KColorDefault
+local ____ui = require("functions.ui")
+local getScreenBottomCenterPos = ____ui.getScreenBottomCenterPos
+local ____v = require("features.customStage.v")
+local v = ____v.default
+local STREAK_TEXT_BOTTOM_OFFSET = Vector(0, -60)
+function ____exports.streakTextPostRender(self, customStage)
+    if not v.run.showingStreakText then
+        return
+    end
+    local font = fonts.upheaval
+    local length = font:GetStringWidthUTF8(customStage.name)
+    local bottomCenterPos = getScreenBottomCenterPos(nil)
+    local position = bottomCenterPos + STREAK_TEXT_BOTTOM_OFFSET
+    local adjustedX = position.X - length / 2
+    font:DrawString(customStage.name, adjustedX, position.Y, KColorDefault)
+end
+return ____exports

package/features/customStage/v.d.ts

@@ -1,6 +1,16 @@
 /// <reference types="isaac-typescript-definitions" />
 import { CustomStage } from "../../interfaces/CustomStage";
+declare const v: {
+    run: {
+        currentCustomStage: CustomStage | null;
+        showingStreakText: boolean;
+        showingBossVersusScreen: boolean;
+    };
+};
+export default v;
 /** Indexed by custom stage name. */
 export declare const customStagesMap: Map<string, CustomStage>;
 /** Indexed by room variant. */
 export declare const customStageCachedRoomData: Map<number, Readonly<RoomConfig>>;
+/** Indexed by entity ID. */
+export declare const customBossPNGPaths: Map<string, [namePNGPath: string, portraitPNGPath: string]>;