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

@@ -115,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

@@ -97,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/features/customStage/backdrop.lua

@@ -26,6 +26,8 @@ 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)
@@ -44,7 +46,7 @@ function spawnWallEntity(self, customStage, rng, isExtraWall)
     )
     wallEffect:AddEntityFlags(EntityFlag.RENDER_WALL)
     local sprite = wallEffect:GetSprite()
-    sprite:Load("gfx/isaacscript-custom-stage/wall-backdrop.anm2", false)
+    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
@@ -89,7 +91,7 @@ function spawnFloorEntity(self, customStage, rng)
     )
     floorEffect:AddEntityFlags(EntityFlag.RENDER_FLOOR)
     local sprite = floorEffect:GetSprite()
-    sprite:Load("gfx/isaacscript-custom-stage/floor-backdrop.anm2", false)
+    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

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.
  *
@@ -6,3 +7,29 @@
  */
 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

@@ -13,6 +13,8 @@ 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
@@ -29,14 +31,15 @@ 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 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
@@ -116,6 +119,33 @@ function ____exports.setCustomStageDebug(self)
         log("No custom stage is currently loaded.")
         return
     end
-    playBossRoomAnimation(nil, true)
+    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.lua

@@ -14,18 +14,20 @@ 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 ____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)
-    local customStagesLua = metadataJSON
-    if not isArray(nil, customStagesLua) then
+    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})
@@ -58,7 +60,12 @@ function getRoomTypeMap(self, customStageLua)
     return roomTypeMap
 end
 function postRender(self)
-    bossPostRender(nil)
+    local customStage = v.run.currentCustomStage
+    if customStage == nil then
+        return
+    end
+    streakTextPostRender(nil, customStage)
+    versusScreenPostRender(nil)
 end
 function postNewRoomReordered(self)
     local customStage = v.run.currentCustomStage
@@ -66,7 +73,7 @@ function postNewRoomReordered(self)
         return
     end
     setBackdrop(nil, customStage)
-    playBossRoomAnimation(nil)
+    playVersusScreenAnimation(nil, customStage)
 end
 function ____exports.customStageInit(self, mod)
     saveDataManager(nil, "customStage", v)

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

@@ -3,6 +3,7 @@ import { CustomStage } from "../../interfaces/CustomStage";
 declare const v: {
     run: {
         currentCustomStage: CustomStage | null;
+        showingStreakText: boolean;
         showingBossVersusScreen: boolean;
     };
 };
@@ -11,3 +12,5 @@ export default v;
 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]>;

package/features/customStage/v.lua

@@ -2,10 +2,12 @@ local ____lualib = require("lualib_bundle")
 local Map = ____lualib.Map
 local __TS__New = ____lualib.__TS__New
 local ____exports = {}
-local v = {run = {currentCustomStage = nil, showingBossVersusScreen = false}}
+local v = {run = {currentCustomStage = nil, showingStreakText = false, showingBossVersusScreen = false}}
 ____exports.default = v
 --- Indexed by custom stage name.
 ____exports.customStagesMap = __TS__New(Map)
 --- Indexed by room variant.
 ____exports.customStageCachedRoomData = __TS__New(Map)
+--- Indexed by entity ID.
+____exports.customBossPNGPaths = __TS__New(Map)
 return ____exports

package/features/customStage/versusScreen.d.ts

@@ -0,0 +1,3 @@
+import { CustomStage } from "../../interfaces/CustomStage";
+export declare function playVersusScreenAnimation(customStage: CustomStage, force?: boolean): void;
+export declare function versusScreenPostRender(): void;

package/features/customStage/versusScreen.lua

@@ -0,0 +1,193 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local ____exports = {}
+local getPlayerPNGPaths, getBossPNGPaths, DEFAULT_CHARACTER, PNG_PATH_PREFIX, PLAYER_PORTRAIT_PNG_PATH_PREFIX
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local BossID = ____isaac_2Dtypescript_2Ddefinitions.BossID
+local PlayerType = ____isaac_2Dtypescript_2Ddefinitions.PlayerType
+local RoomType = ____isaac_2Dtypescript_2Ddefinitions.RoomType
+local SoundEffect = ____isaac_2Dtypescript_2Ddefinitions.SoundEffect
+local StageID = ____isaac_2Dtypescript_2Ddefinitions.StageID
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+local sfxManager = ____cachedClasses.sfxManager
+local ____array = require("functions.array")
+local arrayRemove = ____array.arrayRemove
+local ____boss = require("functions.boss")
+local getBosses = ____boss.getBosses
+local ____entity = require("functions.entity")
+local getEntityID = ____entity.getEntityID
+local ____utils = require("functions.utils")
+local erange = ____utils.erange
+local ____bossNamePNGFileNames = require("objects.bossNamePNGFileNames")
+local BOSS_NAME_PNG_FILE_NAMES = ____bossNamePNGFileNames.BOSS_NAME_PNG_FILE_NAMES
+local ____bossPortraitPNGFileNames = require("objects.bossPortraitPNGFileNames")
+local BOSS_PORTRAIT_PNG_FILE_NAMES = ____bossPortraitPNGFileNames.BOSS_PORTRAIT_PNG_FILE_NAMES
+local ____playerNamePNGFileNames = require("objects.playerNamePNGFileNames")
+local PLAYER_NAME_PNG_FILE_NAMES = ____playerNamePNGFileNames.PLAYER_NAME_PNG_FILE_NAMES
+local ____playerPortraitPNGFileNames = require("objects.playerPortraitPNGFileNames")
+local PLAYER_PORTRAIT_PNG_FILE_NAMES = ____playerPortraitPNGFileNames.PLAYER_PORTRAIT_PNG_FILE_NAMES
+local ____versusScreenBackgroundColors = require("objects.versusScreenBackgroundColors")
+local VERSUS_SCREEN_BACKGROUND_COLORS = ____versusScreenBackgroundColors.VERSUS_SCREEN_BACKGROUND_COLORS
+local ____versusScreenDirtSpotColors = require("objects.versusScreenDirtSpotColors")
+local VERSUS_SCREEN_DIRT_SPOT_COLORS = ____versusScreenDirtSpotColors.VERSUS_SCREEN_DIRT_SPOT_COLORS
+local ____pause = require("features.pause")
+local pause = ____pause.pause
+local unpause = ____pause.unpause
+local ____customStageConstants = require("features.customStage.customStageConstants")
+local ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH = ____customStageConstants.ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH
+local ____v = require("features.customStage.v")
+local v = ____v.default
+local customBossPNGPaths = ____v.customBossPNGPaths
+function getPlayerPNGPaths(self)
+    local player = Isaac.GetPlayer()
+    local character = player:GetPlayerType()
+    local playerNamePNGFileName = PLAYER_NAME_PNG_FILE_NAMES[character]
+    if playerNamePNGFileName == nil then
+        playerNamePNGFileName = PLAYER_NAME_PNG_FILE_NAMES[DEFAULT_CHARACTER]
+    end
+    local playerNamePNGPath = (PNG_PATH_PREFIX .. "/") .. tostring(playerNamePNGFileName)
+    local playerPortraitFileName = PLAYER_PORTRAIT_PNG_FILE_NAMES[character]
+    if playerNamePNGFileName == nil then
+        playerPortraitFileName = PLAYER_PORTRAIT_PNG_FILE_NAMES[DEFAULT_CHARACTER]
+    end
+    local playerPortraitPNGPath = (PLAYER_PORTRAIT_PNG_PATH_PREFIX .. "/") .. tostring(playerPortraitFileName)
+    return {playerNamePNGPath, playerPortraitPNGPath}
+end
+function getBossPNGPaths(self)
+    local bosses = getBosses(nil)
+    local firstBoss = bosses[1]
+    if firstBoss ~= nil then
+        local entityID = getEntityID(nil, firstBoss)
+        local pngPaths = customBossPNGPaths:get(entityID)
+        if pngPaths ~= nil then
+            return pngPaths
+        end
+    end
+    local bossID = firstBoss == nil and 0 or firstBoss:GetBossID()
+    if bossID == 0 then
+        local questionMarkSprite = (PNG_PATH_PREFIX .. "/") .. BOSS_NAME_PNG_FILE_NAMES[BossID.BLUE_BABY]
+        local bossNamePNGPath = questionMarkSprite
+        local bossPortraitPNGPath = questionMarkSprite
+        return {bossNamePNGPath, bossPortraitPNGPath}
+    end
+    local bossNamePNGFileName = BOSS_NAME_PNG_FILE_NAMES[bossID]
+    local bossNamePNGPath = (PNG_PATH_PREFIX .. "/") .. bossNamePNGFileName
+    local bossPortraitPNGFileName = BOSS_PORTRAIT_PNG_FILE_NAMES[bossID]
+    local bossPortraitPNGPath = (PNG_PATH_PREFIX .. "/") .. bossPortraitPNGFileName
+    return {bossNamePNGPath, bossPortraitPNGPath}
+end
+DEFAULT_CHARACTER = PlayerType.ISAAC
+local DEFAULT_STAGE_ID = StageID.BASEMENT
+local VERSUS_SCREEN_ANIMATION_NAME = "Scene"
+--- The layers range from 0 to 13.
+local NUM_VERSUS_SCREEN_ANM2_LAYERS = 14
+local BACKGROUND_ANM2_LAYER = 0
+local BOSS_DIRT_SPOT_ANM2_LAYER = 2
+local PLAYER_DIRT_SPOT_ANM2_LAYER = 3
+local BOSS_PORTRAIT_ANM2_LAYER = 4
+local PLAYER_PORTRAIT_ANM2_LAYER = 5
+local PLAYER_NAME_ANM2_LAYER = 6
+local BOSS_NAME_ANM2_LAYER = 7
+local OVERLAY_ANM2_LAYER = 11
+--- We only need to render either the normal player portrait layer or the alternate player portrait
+-- layer. Rendering both will cause the player not to shake.
+local PLAYER_PORTRAIT_ALT_ANM2_LAYER = 12
+--- These are the non-special layers that we will render last.
+local OTHER_ANM2_LAYERS = arrayRemove(
+    nil,
+    erange(nil, NUM_VERSUS_SCREEN_ANM2_LAYERS),
+    BACKGROUND_ANM2_LAYER,
+    BOSS_DIRT_SPOT_ANM2_LAYER,
+    PLAYER_DIRT_SPOT_ANM2_LAYER,
+    OVERLAY_ANM2_LAYER,
+    PLAYER_PORTRAIT_ALT_ANM2_LAYER
+)
+PNG_PATH_PREFIX = "gfx/ui/boss"
+PLAYER_PORTRAIT_PNG_PATH_PREFIX = "gfx/ui/stage"
+local VANILLA_VERSUS_PLAYBACK_SPEED = 0.5
+local versusScreenSprite = Sprite()
+versusScreenSprite:Load("gfx/ui/boss/versusscreen.anm2", false)
+versusScreenSprite:ReplaceSpritesheet(OVERLAY_ANM2_LAYER, ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH .. "/overlay.png")
+versusScreenSprite:LoadGraphics()
+--- Unfortunately, we must split the background layer into an entirely different sprite so that we
+-- can color it with the `Color` property.
+local versusScreenBackgroundSprite = Sprite()
+versusScreenBackgroundSprite:Load("gfx/ui/boss/versusscreen.anm2", true)
+--- Unfortunately, we must split the dirt layer into an entirely different sprite so that we can
+-- color it with the `Color` property.
+local versusScreenDirtSpotSprite = Sprite()
+versusScreenDirtSpotSprite:Load("gfx/ui/boss/versusscreen.anm2", true)
+function ____exports.playVersusScreenAnimation(self, customStage, 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)
+    local playerNamePNGPath, playerPortraitPNGPath = table.unpack(getPlayerPNGPaths(nil))
+    versusScreenSprite:ReplaceSpritesheet(PLAYER_NAME_ANM2_LAYER, playerNamePNGPath)
+    versusScreenSprite:ReplaceSpritesheet(PLAYER_PORTRAIT_ANM2_LAYER, playerPortraitPNGPath)
+    local bossNamePNGPath, bossPortraitPNGPath = table.unpack(getBossPNGPaths(nil))
+    versusScreenSprite:ReplaceSpritesheet(BOSS_NAME_ANM2_LAYER, bossNamePNGPath)
+    versusScreenSprite:ReplaceSpritesheet(BOSS_PORTRAIT_ANM2_LAYER, bossPortraitPNGPath)
+    versusScreenSprite:LoadGraphics()
+    local backgroundColor = VERSUS_SCREEN_BACKGROUND_COLORS[DEFAULT_STAGE_ID]
+    if customStage.versusScreenBackgroundColor ~= nil then
+        local ____customStage_versusScreenBackgroundColor_0 = customStage.versusScreenBackgroundColor
+        local r = ____customStage_versusScreenBackgroundColor_0.r
+        local g = ____customStage_versusScreenBackgroundColor_0.g
+        local b = ____customStage_versusScreenBackgroundColor_0.b
+        backgroundColor = Color(r, g, b)
+    end
+    versusScreenBackgroundSprite.Color = backgroundColor
+    local dirtSpotColor = VERSUS_SCREEN_DIRT_SPOT_COLORS[DEFAULT_STAGE_ID]
+    if customStage.versusScreenDirtSpotColor ~= nil then
+        local ____customStage_versusScreenDirtSpotColor_1 = customStage.versusScreenDirtSpotColor
+        local r = ____customStage_versusScreenDirtSpotColor_1.r
+        local g = ____customStage_versusScreenDirtSpotColor_1.g
+        local b = ____customStage_versusScreenDirtSpotColor_1.b
+        dirtSpotColor = Color(r, g, b)
+    end
+    versusScreenDirtSpotSprite.Color = dirtSpotColor
+    for ____, sprite in ipairs({versusScreenBackgroundSprite, versusScreenDirtSpotSprite, versusScreenSprite}) do
+        sprite:Play(VERSUS_SCREEN_ANIMATION_NAME, true)
+        sprite.PlaybackSpeed = VANILLA_VERSUS_PLAYBACK_SPEED
+    end
+end
+local function finishVersusScreenAnimation(self)
+    local hud = game:GetHUD()
+    v.run.showingBossVersusScreen = false
+    unpause(nil)
+    hud:SetVisible(true)
+    sfxManager:Play(SoundEffect.CASTLE_PORTCULLIS)
+end
+function ____exports.versusScreenPostRender(self)
+    if not v.run.showingBossVersusScreen then
+        return
+    end
+    if versusScreenSprite:IsFinished(VERSUS_SCREEN_ANIMATION_NAME) then
+        finishVersusScreenAnimation(nil)
+        return
+    end
+    local room = game:GetRoom()
+    local centerPos = room:GetCenterPos()
+    local position = Isaac.WorldToRenderPosition(centerPos)
+    versusScreenBackgroundSprite:RenderLayer(BACKGROUND_ANM2_LAYER, position)
+    versusScreenBackgroundSprite:Update()
+    versusScreenSprite:RenderLayer(OVERLAY_ANM2_LAYER, position)
+    versusScreenDirtSpotSprite:RenderLayer(BOSS_DIRT_SPOT_ANM2_LAYER, position)
+    versusScreenDirtSpotSprite:RenderLayer(PLAYER_DIRT_SPOT_ANM2_LAYER, position)
+    versusScreenDirtSpotSprite:Update()
+    for ____, layerID in ipairs(OTHER_ANM2_LAYERS) do
+        versusScreenSprite:RenderLayer(layerID, position)
+    end
+    versusScreenSprite:Update()
+end
+return ____exports

package/features/deployJSONRoom.lua

@@ -28,6 +28,7 @@ local errorIfFeaturesNotInitialized = ____featuresInitialized.errorIfFeaturesNot
 local ____array = require("functions.array")
 local emptyArray = ____array.emptyArray
 local ____entity = require("functions.entity")
+local getEntityIDFromConstituents = ____entity.getEntityIDFromConstituents
 local removeAllMatchingEntities = ____entity.removeAllMatchingEntities
 local spawn = ____entity.spawn
 local spawnWithSeed = ____entity.spawnWithSeed
@@ -39,6 +40,7 @@ local ____gridEntity = require("functions.gridEntity")
 local convertXMLGridEntityType = ____gridEntity.convertXMLGridEntityType
 local getAllGridIndexes = ____gridEntity.getAllGridIndexes
 local getGridEntities = ____gridEntity.getGridEntities
+local getGridEntityIDFromConstituents = ____gridEntity.getGridEntityIDFromConstituents
 local removeAllGridExcept = ____gridEntity.removeAllGridExcept
 local removeGrid = ____gridEntity.removeGrid
 local setGridEntityInvisible = ____gridEntity.setGridEntityInvisible
@@ -239,7 +241,8 @@ function spawnAllEntities(self, jsonRoom, rng, verbose)
         end
         if entityType >= 1000 then
             if verbose then
-                log(((((((("Spawning grid entity " .. tostring(entityType)) .. ".") .. tostring(variant)) .. " at: (") .. tostring(x)) .. ", ") .. tostring(y)) .. ")")
+                local gridEntityID = getGridEntityIDFromConstituents(nil, entityType, variant)
+                log(((((("Spawning grid entity " .. gridEntityID) .. " at: (") .. tostring(x)) .. ", ") .. tostring(y)) .. ")")
             end
             spawnGridEntityForJSONRoom(
                 nil,
@@ -250,7 +253,8 @@ function spawnAllEntities(self, jsonRoom, rng, verbose)
             )
         else
             if verbose then
-                log(((((((((("Spawning normal entity " .. tostring(entityType)) .. ".") .. tostring(variant)) .. ".") .. tostring(subType)) .. " at: (") .. tostring(x)) .. ", ") .. tostring(y)) .. ")")
+                local entityID = getEntityIDFromConstituents(nil, entityType, variant, subType)
+                log(((((("Spawning normal entity " .. entityID) .. " at: (") .. tostring(x)) .. ", ") .. tostring(y)) .. ")")
             end
             local entity = spawnNormalEntityForJSONRoom(
                 nil,

package/features/saveDataManager/exports.lua

@@ -11,8 +11,6 @@ local ____deepCopy = require("functions.deepCopy")
 local deepCopy = ____deepCopy.deepCopy
 local ____types = require("functions.types")
 local isString = ____types.isString
-local ____constants = require("features.saveDataManager.constants")
-local SAVE_DATA_MANAGER_FEATURE_NAME = ____constants.SAVE_DATA_MANAGER_FEATURE_NAME
 local ____main = require("features.saveDataManager.main")
 local forceSaveDataManagerLoad = ____main.forceSaveDataManagerLoad
 local forceSaveDataManagerSave = ____main.forceSaveDataManagerSave
@@ -21,6 +19,8 @@ local ____maps = require("features.saveDataManager.maps")
 local saveDataConditionalFuncMap = ____maps.saveDataConditionalFuncMap
 local saveDataDefaultsMap = ____maps.saveDataDefaultsMap
 local saveDataMap = ____maps.saveDataMap
+local ____saveDataManagerConstants = require("features.saveDataManager.saveDataManagerConstants")
+local SAVE_DATA_MANAGER_FEATURE_NAME = ____saveDataManagerConstants.SAVE_DATA_MANAGER_FEATURE_NAME
 --- This is the entry point to the save data manager, a system which provides two major features:
 -- 
 -- 1. automatic resetting of variables on a new run, on a new level, or on a new room (as desired)

package/features/saveDataManager/load.lua

@@ -12,11 +12,11 @@ local iterateTableInOrder = ____table.iterateTableInOrder
 local ____types = require("functions.types")
 local isString = ____types.isString
 local isTable = ____types.isTable
-local ____constants = require("features.saveDataManager.constants")
-local SAVE_DATA_MANAGER_DEBUG = ____constants.SAVE_DATA_MANAGER_DEBUG
-local SAVE_DATA_MANAGER_FEATURE_NAME = ____constants.SAVE_DATA_MANAGER_FEATURE_NAME
 local ____merge = require("features.saveDataManager.merge")
 local merge = ____merge.merge
+local ____saveDataManagerConstants = require("features.saveDataManager.saveDataManagerConstants")
+local SAVE_DATA_MANAGER_DEBUG = ____saveDataManagerConstants.SAVE_DATA_MANAGER_DEBUG
+local SAVE_DATA_MANAGER_FEATURE_NAME = ____saveDataManagerConstants.SAVE_DATA_MANAGER_FEATURE_NAME
 function readSaveDatFile(self, mod)
     local renderFrameCount = Isaac.GetFrameCount()
     local ok, jsonStringOrErrMsg = pcall(tryLoadModData, mod)

package/features/saveDataManager/main.lua

@@ -21,9 +21,6 @@ local logError = ____log.logError
 local ____table = require("functions.table")
 local clearTable = ____table.clearTable
 local iterateTableInOrder = ____table.iterateTableInOrder
-local ____constants = require("features.saveDataManager.constants")
-local SAVE_DATA_MANAGER_DEBUG = ____constants.SAVE_DATA_MANAGER_DEBUG
-local SAVE_DATA_MANAGER_FEATURE_NAME = ____constants.SAVE_DATA_MANAGER_FEATURE_NAME
 local ____load = require("features.saveDataManager.load")
 local loadFromDisk = ____load.loadFromDisk
 local ____maps = require("features.saveDataManager.maps")
@@ -32,6 +29,9 @@ local saveDataDefaultsMap = ____maps.saveDataDefaultsMap
 local saveDataMap = ____maps.saveDataMap
 local ____save = require("features.saveDataManager.save")
 local saveToDisk = ____save.saveToDisk
+local ____saveDataManagerConstants = require("features.saveDataManager.saveDataManagerConstants")
+local SAVE_DATA_MANAGER_DEBUG = ____saveDataManagerConstants.SAVE_DATA_MANAGER_DEBUG
+local SAVE_DATA_MANAGER_FEATURE_NAME = ____saveDataManagerConstants.SAVE_DATA_MANAGER_FEATURE_NAME
 function postPlayerInit(self)
     if mod == nil then
         error(("The mod for the " .. SAVE_DATA_MANAGER_FEATURE_NAME) .. " was not initialized.")

package/features/saveDataManager/merge.lua

@@ -26,8 +26,8 @@ local ____types = require("functions.types")
 local isTable = ____types.isTable
 local ____utils = require("functions.utils")
 local getTraversalDescription = ____utils.getTraversalDescription
-local ____constants = require("features.saveDataManager.constants")
-local SAVE_DATA_MANAGER_DEBUG = ____constants.SAVE_DATA_MANAGER_DEBUG
+local ____saveDataManagerConstants = require("features.saveDataManager.saveDataManagerConstants")
+local SAVE_DATA_MANAGER_DEBUG = ____saveDataManagerConstants.SAVE_DATA_MANAGER_DEBUG
 local ____serializationBrand = require("features.saveDataManager.serializationBrand")
 local isSerializationBrand = ____serializationBrand.isSerializationBrand
 --- `merge` takes the values from a new table and recursively merges them into an old object (while