isaacscript-common 6.20.1 → 6.22.0

package/src/features/customStage/exports.ts

@@ -8,55 +8,111 @@ import {
 import { game } from "../../cachedClasses";
 import { reorderedCallbacksSetStage } from "../../callbacks/reorderedCallbacks";
 import { getEntityIDFromConstituents } from "../../functions/entities";
-import { log, logError } from "../../functions/log";
+import { logError } from "../../functions/log";
 import { newRNG } from "../../functions/rng";
-import { getRoomDataForTypeVariant, getRooms } from "../../functions/rooms";
+import {
+  getRoomDataForTypeVariant,
+  getRoomsInGrid,
+} from "../../functions/rooms";
 import { setStage } from "../../functions/stage";
+import { CustomStage } from "../../interfaces/CustomStage";
 import { getRandomCustomStageRoom } from "./customStageUtils";
-import { topStreakTextStart } from "./streakText";
 import v, {
   customBossPNGPaths,
   customStageCachedRoomData,
   customStagesMap,
 } from "./v";
 
-const DEFAULT_BASE_STAGE = LevelStage.BASEMENT_2;
-const DEFAULT_BASE_STAGE_TYPE = StageType.ORIGINAL;
+export const DEFAULT_BASE_STAGE = LevelStage.BASEMENT_2;
+export const DEFAULT_BASE_STAGE_TYPE = StageType.ORIGINAL;
+
+export const INVALID_STAGE_VALUE = -1 as LevelStage;
 
 /**
  * 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
  * more details: https://isaacscript.github.io/main/custom-stages/
+ *
+ * @param name The name of the custom stage, corresponding to what is in the "tsconfig.json" file.
+ * @param firstFloor Optional. Whether to go to the first floor or the second floor. For example, if
+ *                   you have a custom stage emulating Caves, then the first floor would be Caves 1,
+ *                   and the second floor would be Caves 2. Default is true.
+ * @param verbose Optional. Whether to log additional information about the rooms that are chosen.
+ *                Default is false.
  */
-export function setCustomStage(name: string, verbose = false): void {
+export function setCustomStage(
+  name: string,
+  firstFloor = true,
+  verbose = false,
+): void {
   const customStage = customStagesMap.get(name);
   if (customStage === undefined) {
     error(
-      `Failed to set the custom stage of "${name}" because it was not found in the custom stages map. (Try restarting IsaacScript / recompiling the mod, and try again. If that does not work, you probably forgot to define it in your "tsconfig.json" file.) See the website for more details on how to set up custom stages.`,
+      `Failed to set the custom stage of "${name}" because it was not found in the custom stages map. (Try restarting IsaacScript / recompiling the mod / restarting the game, and try again. If that does not work, you probably forgot to define it in your "tsconfig.json" file.) See the website for more details on how to set up custom stages.`,
     );
   }
 
   const level = game.GetLevel();
-  const startingRoomGridIndex = level.GetStartingRoomIndex();
+  const stage = level.GetStage();
   const seeds = game.GetSeeds();
   const startSeed = seeds.GetStartSeed();
   const rng = newRNG(startSeed);
 
   v.run.currentCustomStage = customStage;
+  v.run.firstFloor = firstFloor;
 
-  const baseStage =
+  // Before changing the stage, we have to revert the bugged stage, if necessary. This prevents the
+  // bug where the backdrop will not spawn.
+  if (stage === INVALID_STAGE_VALUE) {
+    level.SetStage(LevelStage.BASEMENT_1, StageType.ORIGINAL);
+  }
+
+  let baseStage: int =
     customStage.baseStage === undefined
       ? DEFAULT_BASE_STAGE
-      : (customStage.baseStage as LevelStage);
+      : customStage.baseStage;
+  if (!firstFloor) {
+    baseStage++;
+  }
+
   const baseStageType =
     customStage.baseStageType === undefined
       ? DEFAULT_BASE_STAGE_TYPE
       : (customStage.baseStageType as StageType);
-  setStage(baseStage, baseStageType);
 
-  // Now, we need to pick a custom room for each vanilla room.
-  for (const room of getRooms()) {
+  const reseed = (stage as int) >= baseStage;
+
+  setStage(baseStage as LevelStage, baseStageType, reseed);
+
+  setStageRoomsData(customStage, rng, verbose);
+
+  // Set the stage to an invalid value, which will prevent the walls and floors from loading.
+  // Furthermore, we must use `StageType.WRATH_OF_THE_LAMB` instead of `StageType.ORIGINAL` or else
+  // the walls will not render properly. DeadInfinity suspects that this might be because it is
+  // trying to use the Dark Room's backdrop (instead of The Chest).
+  const targetStage = INVALID_STAGE_VALUE;
+  const targetStageType = StageType.WRATH_OF_THE_LAMB;
+  level.SetStage(targetStage, targetStageType);
+  reorderedCallbacksSetStage(targetStage, targetStageType);
+
+  // We must reload the current room in order for the `Level.SetStage` method to take effect.
+  // Furthermore, we need to cancel the queued warp to the `GridRoom.DEBUG` room. We can accomplish
+  // both of these things by initiating a room transition to an arbitrary room. However, we rely on
+  // the parent function to do this, since for normal purposes, we need to initiate a room
+  // transition for the pixelation effect.
+}
+
+/** Pick a custom room for each vanilla room. */
+function setStageRoomsData(
+  customStage: CustomStage,
+  rng: RNG,
+  verbose: boolean,
+) {
+  const level = game.GetLevel();
+  const startingRoomGridIndex = level.GetStartingRoomIndex();
+
+  for (const room of getRoomsInGrid()) {
     // The starting floor of each room should stay empty.
     if (room.SafeGridIndex === startingRoomGridIndex) {
       continue;
@@ -73,7 +129,7 @@ export function setCustomStage(name: string, verbose = false): void {
       // special rooms.)
       if (roomType === RoomType.DEFAULT) {
         logError(
-          `Failed to find any custom rooms for RoomType.${RoomType[roomType]} (${roomType}) for custom stage: ${name}`,
+          `Failed to find any custom rooms for RoomType.${RoomType[roomType]} (${roomType}) for custom stage: ${customStage.name}`,
         );
       }
       continue;
@@ -83,7 +139,7 @@ export function setCustomStage(name: string, verbose = false): void {
     const roomDoorSlotFlagMap = roomShapeMap.get(roomShape);
     if (roomDoorSlotFlagMap === undefined) {
       logError(
-        `Failed to find any custom rooms for RoomType.${RoomType[roomType]} (${roomType}) + RoomShape.${RoomShape[roomShape]} (${roomShape}) for custom stage: ${name}`,
+        `Failed to find any custom rooms for RoomType.${RoomType[roomType]} (${roomType}) + RoomShape.${RoomShape[roomShape]} (${roomShape}) for custom stage: ${customStage.name}`,
       );
       continue;
     }
@@ -92,7 +148,7 @@ export function setCustomStage(name: string, verbose = false): void {
     const roomsMetadata = roomDoorSlotFlagMap.get(doorSlotFlags);
     if (roomsMetadata === undefined) {
       logError(
-        `Failed to find any custom rooms for RoomType.${RoomType[roomType]} (${roomType}) + RoomShape.${RoomShape[roomShape]} (${roomShape}) + DoorSlotFlags ${doorSlotFlags} for custom stage: ${name}`,
+        `Failed to find any custom rooms for RoomType.${RoomType[roomType]} (${roomType}) + RoomShape.${RoomShape[roomShape]} (${roomShape}) + DoorSlotFlags ${doorSlotFlags} for custom stage: ${customStage.name}`,
       );
       continue;
     }
@@ -109,7 +165,7 @@ export function setCustomStage(name: string, verbose = false): void {
       );
       if (newRoomData === undefined) {
         logError(
-          `Failed to get the room data for room variant ${randomRoom.variant} for custom stage: ${name}`,
+          `Failed to get the room data for room variant ${randomRoom.variant} for custom stage: ${customStage.name}`,
         );
         continue;
       }
@@ -119,31 +175,6 @@ export function setCustomStage(name: string, verbose = false): void {
 
     room.Data = newRoomData;
   }
-
-  // Set the stage to an invalid value, which will prevent the walls and floors from loading. We
-  // must use `StageType.WRATH_OF_THE_LAMB` instead of `StageType.ORIGINAL` or else the walls will
-  // not render properly. DeadInfinity suspects that this might be because it is trying to use the
-  // Dark Room's backdrop (instead of The Chest).
-  const stage = -1 as LevelStage;
-  const stageType = StageType.WRATH_OF_THE_LAMB;
-  level.SetStage(stage, stageType);
-  reorderedCallbacksSetStage(stage, stageType);
-
-  // We must reload the current room in order for the `Level.SetStage` method to take effect.
-  // Furthermore, we need to cancel the queued warp to the `GridRoom.DEBUG` room. We can accomplish
-  // both of these things by initiating a room transition to an arbitrary room. However, we rely on
-  // the parent function to do this, since for normal purposes, we need to initiate a room
-  // transition for the pixelation effect.
-}
-
-export function setCustomStageDebug(): void {
-  const customStage = v.run.currentCustomStage;
-  if (customStage === null) {
-    log("No custom stage is currently loaded.");
-    return;
-  }
-
-  topStreakTextStart();
 }
 
 /**
@@ -181,3 +212,11 @@ export function registerCustomBoss(
   const entityID = getEntityIDFromConstituents(entityType, variant, subType);
   customBossPNGPaths.set(entityID, [namePNGPath, portraitPNGPath]);
 }
+
+/**
+ * Helper function to disable the custom stage. This is typically called before taking the player to
+ * a vanilla floor.
+ */
+export function disableCustomStage(): void {
+  v.run.currentCustomStage = null;
+}

package/src/features/customStage/init.ts

@@ -18,6 +18,7 @@ import {
 import { saveDataManager } from "../saveDataManager/exports";
 import { setBackdrop } from "./backdrop";
 import {
+  convertVanillaTrapdoors,
   removeUrnRewards,
   setCustomDecorationGraphics,
   setCustomDoorGraphics,
@@ -26,12 +27,7 @@ import {
 } from "./customStageGridEntities";
 import * as metadataJSON from "./metadata.json"; // This will correspond to "metadata.lua" at run-time.
 import { setShadows } from "./shadows";
-import {
-  streakTextGetShaderParams,
-  streakTextInit,
-  streakTextPostGameStarted,
-  streakTextPostRender,
-} from "./streakText";
+import { streakTextGetShaderParams, streakTextPostRender } from "./streakText";
 import v, { customStagesMap } from "./v";
 import {
   playVersusScreenAnimation,
@@ -47,12 +43,10 @@ export function customStageInit(mod: ModUpgraded): void {
   }
 
   saveDataManager("customStage", v);
-  streakTextInit();
   versusScreenInit();
 
   mod.AddCallback(ModCallback.POST_RENDER, postRender); // 2
   mod.AddCallback(ModCallback.POST_CURSE_EVAL, postCurseEval); // 12
-  mod.AddCallback(ModCallback.POST_GAME_STARTED, postGameStarted); // 15
   mod.AddCallback(ModCallback.GET_SHADER_PARAMS, getShaderParams); // 21
   mod.AddCallbackCustom(
     ModCallbackCustom.POST_GRID_ENTITY_BROKEN,
@@ -61,7 +55,7 @@ export function customStageInit(mod: ModUpgraded): void {
   );
   mod.AddCallbackCustom(
     ModCallbackCustom.POST_GRID_ENTITY_INIT,
-    postGridEntityBrokenInit,
+    postGridEntityInit,
   );
   mod.AddCallbackCustom(
     ModCallbackCustom.POST_NEW_ROOM_REORDERED,
@@ -150,19 +144,13 @@ function postCurseEval(
   }
 
   // Prevent XL floors on custom stages, since the streak text will not work properly.
-  if (hasFlag(curses, LevelCurse.MAZE)) {
-    return removeFlag(curses, LevelCurse.MAZE);
+  if (hasFlag(curses, LevelCurse.LABYRINTH)) {
+    return removeFlag(curses, LevelCurse.LABYRINTH);
   }
 
   return undefined;
 }
 
-// ModCallback.POST_GAME_STARTED (15)
-function postGameStarted() {
-  // We don't early return here because we need to unconditionally reset the sprites.
-  streakTextPostGameStarted();
-}
-
 // ModCallback.GET_SHADER_PARAMS (22)
 function getShaderParams(
   shaderName: string,
@@ -188,7 +176,7 @@ function postGridEntityBrokenRockAlt(gridEntity: GridEntity) {
 }
 
 // ModCallbackCustom.POST_GRID_ENTITY_INIT
-function postGridEntityBrokenInit(gridEntity: GridEntity) {
+function postGridEntityInit(gridEntity: GridEntity) {
   const customStage = v.run.currentCustomStage;
   if (customStage === null) {
     return;
@@ -198,6 +186,7 @@ function postGridEntityBrokenInit(gridEntity: GridEntity) {
   setCustomRockGraphics(customStage, gridEntity);
   setCustomPitGraphics(customStage, gridEntity);
   setCustomDoorGraphics(customStage, gridEntity);
+  convertVanillaTrapdoors(customStage, gridEntity);
 }
 
 // ModCallbackCustom.POST_NEW_ROOM_REORDERED

package/src/features/customStage/shadows.ts

@@ -17,6 +17,7 @@ type ShadowAnimation = "1x1" | "1x2" | "2x1" | "2x2";
  * time passes, like most other effects.
  */
 const SHADOW_EFFECT_VARIANT = EffectVariant.LADDER;
+const SHADOW_EFFECT_SUBTYPE = 102;
 
 /** The animation comes from StageAPI. */
 const ROOM_SHAPE_TO_SHADOW_ANIMATION: {
@@ -57,7 +58,7 @@ export function setShadows(customStage: CustomStage): void {
   // rendering throughout this animation.)
   const shadowEffect = spawnEffectWithSeed(
     SHADOW_EFFECT_VARIANT,
-    0,
+    SHADOW_EFFECT_SUBTYPE,
     centerPos,
     1 as Seed,
   );

package/src/features/customStage/streakText.ts

@@ -7,15 +7,12 @@ import {
   getScreenTopCenterPos,
 } from "../../functions/ui";
 import { CustomStage } from "../../interfaces/CustomStage";
+import {
+  UIStreakAnimation,
+  UI_STREAK_ANIMATION_END_FRAMES,
+} from "./customStageConstants";
 import v from "./v";
 
-enum UIStreakAnimation {
-  TEXT = "Text",
-  TEXT_IN = "TextIn",
-  TEXT_OUT = "TextOut",
-  TEXT_STAY = "TextStay",
-}
-
 /** This must match the name of the shader in "shaders.xml". */
 const EMPTY_SHADER_NAME = "IsaacScript-RenderAboveHUD";
 
@@ -29,7 +26,7 @@ const TEXT_STAY_FRAME = 8;
 const TEXT_OUT_FRAME = 60;
 
 /** This matches the offset that the vanilla game uses; determined via trial and error. */
-const STREAK_SPRITE_TOP_OFFSET = Vector(0, 48.25);
+const STREAK_SPRITE_TOP_OFFSET = Vector(0, 47);
 
 /** This matches the offset that the vanilla game uses; determined via trial and error. */
 const STREAK_SPRITE_BOTTOM_OFFSET = Vector(0, -48.25);
@@ -47,9 +44,6 @@ const STREAK_TEXT_BOTTOM_Y_OFFSET = -9;
  */
 const NUM_RENDER_FRAMES_MAP_HELD_BEFORE_STREAK_TEXT = 11;
 
-/** Corresponds to the vanilla value; determined through trial and error. */
-const TEXT_PLAYBACK_SPEED = 0.5;
-
 /** Taken from StageAPI. */
 const TEXT_IN_ADJUSTMENTS = [-800, -639, -450, -250, -70, 10, 6, 3];
 
@@ -82,33 +76,6 @@ const TEXT_OUT_SCALES = [
   Vector(3, 0.2),
 ];
 
-/**
- * We do not actually need to render this sprite at all. It's only purpose is to be an invisible
- * reference for when and where we need to render the stage's name. Thus, we specify "false" for
- * "loadGraphics", but still manage playing its animations in the code below.
- */
-const topStreakSprite = Sprite();
-
-/**
- * We do not actually need to render this sprite at all. It's only purpose is to be an invisible
- * reference for when and where we need to render the stage's name. Thus, we specify "false" for
- * "loadGraphics", but still manage playing its animations in the code below.
- */
-const bottomStreakSprite = Sprite();
-
-/**
- * We must load the sprites in an init function to prevent issues with mods that replace the vanilla
- * files. (For some reason, loading the sprites will cause the overwrite to no longer apply on the
- * second and subsequent runs.)
- */
-export function streakTextInit(): void {
-  topStreakSprite.Load("resources/gfx/ui/ui_streak.anm2", false);
-  topStreakSprite.PlaybackSpeed = TEXT_PLAYBACK_SPEED;
-
-  bottomStreakSprite.Load("resources/gfx/ui/ui_streak.anm2", false);
-  bottomStreakSprite.PlaybackSpeed = TEXT_PLAYBACK_SPEED;
-}
-
 // ModCallback.POST_RENDER (2)
 export function streakTextPostRender(): void {
   // The top streak only plays when the player arrives on the floor (or continues a game from the
@@ -124,7 +91,7 @@ export function streakTextPostRender(): void {
 function checkEndTopStreakText() {
   if (
     v.run.topStreakTextStartedRenderFrame === null ||
-    !topStreakSprite.IsPlaying(UIStreakAnimation.TEXT_STAY)
+    v.run.topStreakText.animation !== UIStreakAnimation.TEXT_STAY
   ) {
     return;
   }
@@ -133,7 +100,10 @@ function checkEndTopStreakText() {
   const elapsedFrames =
     renderFrameCount - v.run.topStreakTextStartedRenderFrame;
   if (elapsedFrames >= 115) {
-    playTextOut(topStreakSprite);
+    v.run.topStreakText.animation = UIStreakAnimation.TEXT;
+    // We adjust by the frame backwards by an arbitrary amount to roughly align with the speed of
+    // the vanilla animation.
+    v.run.topStreakText.frame = TEXT_OUT_FRAME - 2;
   }
 }
 
@@ -165,7 +135,7 @@ function trackMapInputPressed() {
  * slides in from the left.
  */
 function checkStartBottomStreakText() {
-  if (bottomStreakSprite.IsPlaying()) {
+  if (v.run.bottomStreakText.animation !== UIStreakAnimation.NONE) {
     return;
   }
 
@@ -180,7 +150,8 @@ function checkStartBottomStreakText() {
   const gameFrameCount = game.GetFrameCount();
   const elapsedFrames = gameFrameCount - earliestFrame;
   if (elapsedFrames >= NUM_RENDER_FRAMES_MAP_HELD_BEFORE_STREAK_TEXT) {
-    bottomStreakSprite.Play(UIStreakAnimation.TEXT, true);
+    v.run.bottomStreakText.animation = UIStreakAnimation.TEXT;
+    v.run.bottomStreakText.frame = 0;
   }
 }
 
@@ -189,7 +160,7 @@ function checkStartBottomStreakText() {
  * right.
  */
 function checkEndBottomStreakText() {
-  if (!bottomStreakSprite.IsPlaying(UIStreakAnimation.TEXT_STAY)) {
+  if (v.run.bottomStreakText.animation !== UIStreakAnimation.TEXT_STAY) {
     return;
   }
 
@@ -197,16 +168,13 @@ function checkEndBottomStreakText() {
     ...v.run.controllerIndexPushingMapRenderFrame.values(),
   ];
   if (pushedMapFrames.length === 0) {
-    playTextOut(bottomStreakSprite);
+    v.run.bottomStreakText.animation = UIStreakAnimation.TEXT;
+    // We adjust by the frame backwards by an arbitrary amount to roughly align with the speed of
+    // the vanilla animation.
+    v.run.bottomStreakText.frame = TEXT_OUT_FRAME - 2;
   }
 }
 
-// ModCallback.POST_GAME_STARTED (15)
-export function streakTextPostGameStarted(): void {
-  topStreakSprite.Stop();
-  bottomStreakSprite.Stop();
-}
-
 // ModCallback.GET_SHADER_PARAMS (22)
 export function streakTextGetShaderParams(
   customStage: CustomStage,
@@ -218,27 +186,44 @@ export function streakTextGetShaderParams(
 
   const topCenterPos = getScreenTopCenterPos();
   const topStreakPosition = topCenterPos.add(STREAK_SPRITE_TOP_OFFSET);
-  renderSprite(customStage, topStreakSprite, topStreakPosition);
+  renderStreakText(customStage, v.run.topStreakText, topStreakPosition);
 
   const bottomCenterPos = getScreenBottomCenterPos();
   const bottomStreakPosition = bottomCenterPos.add(STREAK_SPRITE_BOTTOM_OFFSET);
-  renderSprite(customStage, bottomStreakSprite, bottomStreakPosition);
+  renderStreakText(customStage, v.run.bottomStreakText, bottomStreakPosition);
 }
 
-function renderSprite(
+function renderStreakText(
   customStage: CustomStage,
-  sprite: Sprite,
+  streakText: { animation: UIStreakAnimation; frame: int; pauseFrame: boolean },
   position: Vector,
 ) {
-  sprite.Update();
-  if (!sprite.IsPlaying()) {
+  if (streakText.animation === UIStreakAnimation.NONE) {
+    return;
+  }
+
+  if (streakText.animation !== UIStreakAnimation.TEXT_STAY) {
+    const { pauseFrame } = streakText;
+    streakText.pauseFrame = !streakText.pauseFrame;
+
+    if (!pauseFrame) {
+      streakText.frame++;
+    }
+  }
+
+  const endFrame = UI_STREAK_ANIMATION_END_FRAMES[streakText.animation];
+  if (streakText.frame > endFrame) {
+    streakText.animation = UIStreakAnimation.NONE;
+    streakText.frame = 0;
     return;
   }
 
-  const animation = sprite.GetAnimation() as UIStreakAnimation;
-  const frame = sprite.GetFrame();
-  if (animation === UIStreakAnimation.TEXT && frame === TEXT_STAY_FRAME) {
-    sprite.Play(UIStreakAnimation.TEXT_STAY, true);
+  if (
+    streakText.animation === UIStreakAnimation.TEXT &&
+    streakText.frame === TEXT_STAY_FRAME
+  ) {
+    streakText.animation = UIStreakAnimation.TEXT_STAY;
+    streakText.frame = 0;
   }
 
   const isPaused = game.IsPaused();
@@ -248,39 +233,22 @@ function renderSprite(
 
   const font = fonts.upheaval;
   const { name } = customStage;
-  const length = font.GetStringWidthUTF8(name);
+  const numberSuffix = v.run.firstFloor ? "I" : "II";
+  const nameWithNumberSuffix = `${name} ${numberSuffix}`;
+  const length = font.GetStringWidthUTF8(nameWithNumberSuffix);
   const centeredX = position.X - length / 2;
 
   let adjustment = 0;
   let scale = VectorOne;
-  switch (animation) {
-    case UIStreakAnimation.TEXT: {
-      if (frame < TEXT_STAY_FRAME) {
-        adjustment = TEXT_IN_ADJUSTMENTS[frame] ?? 0;
-        scale = TEXT_IN_SCALES[frame] ?? VectorOne;
-      } else {
-        const adjustedFrame = frame - TEXT_OUT_FRAME;
-        adjustment = TEXT_OUT_ADJUSTMENTS[adjustedFrame] ?? 0;
-        scale = TEXT_OUT_SCALES[adjustedFrame] ?? VectorOne;
-      }
 
-      break;
-    }
-
-    case UIStreakAnimation.TEXT_IN: {
-      adjustment = TEXT_IN_ADJUSTMENTS[frame] ?? 0;
-      scale = TEXT_IN_SCALES[frame] ?? VectorOne;
-      break;
-    }
-
-    case UIStreakAnimation.TEXT_OUT: {
-      adjustment = TEXT_OUT_ADJUSTMENTS[frame] ?? 0;
-      scale = TEXT_OUT_SCALES[frame] ?? VectorOne;
-      break;
-    }
-
-    default: {
-      break;
+  if (streakText.animation === UIStreakAnimation.TEXT) {
+    if (streakText.frame < TEXT_STAY_FRAME) {
+      adjustment = TEXT_IN_ADJUSTMENTS[streakText.frame] ?? 0;
+      scale = TEXT_IN_SCALES[streakText.frame] ?? VectorOne;
+    } else {
+      const adjustedFrame = streakText.frame - TEXT_OUT_FRAME;
+      adjustment = TEXT_OUT_ADJUSTMENTS[adjustedFrame] ?? 0;
+      scale = TEXT_OUT_SCALES[adjustedFrame] ?? VectorOne;
     }
   }
 
@@ -288,7 +256,7 @@ function renderSprite(
   const adjustedY = position.Y + STREAK_TEXT_BOTTOM_Y_OFFSET;
 
   font.DrawStringScaled(
-    name,
+    nameWithNumberSuffix,
     adjustedX,
     adjustedY,
     scale.X,
@@ -297,12 +265,6 @@ function renderSprite(
   );
 }
 
-function playTextOut(sprite: Sprite) {
-  sprite.Play(UIStreakAnimation.TEXT, true);
-  // We adjust by 2 to roughly align with the speed of the vanilla animation.
-  sprite.SetFrame(TEXT_OUT_FRAME - 2);
-}
-
 export function topStreakTextStart(): void {
   const level = game.GetLevel();
   const renderFrameCount = Isaac.GetFrameCount();
@@ -311,6 +273,7 @@ export function topStreakTextStart(): void {
   level.ShowName(false);
 
   // Initiate the animation for the custom text.
+  v.run.topStreakText.animation = UIStreakAnimation.TEXT;
+  v.run.topStreakText.frame = 0;
   v.run.topStreakTextStartedRenderFrame = renderFrameCount;
-  topStreakSprite.Play(UIStreakAnimation.TEXT, true);
 }

package/src/features/customStage/v.ts

@@ -1,15 +1,32 @@
 import { ControllerIndex } from "isaac-typescript-definitions";
 import { CustomStage } from "../../interfaces/CustomStage";
+import { UIStreakAnimation } from "./customStageConstants";
 
 const v = {
   run: {
     currentCustomStage: null as CustomStage | null,
+
+    /** Whether we are on e.g. Caves 1 or Caves 2. */
+    firstFloor: true,
+
     showingBossVersusScreen: false,
 
     /** Values are the render frame that the controller first pressed the map button. */
     controllerIndexPushingMapRenderFrame: new Map<ControllerIndex, int>(),
 
     topStreakTextStartedRenderFrame: null as int | null,
+
+    topStreakText: {
+      animation: UIStreakAnimation.NONE,
+      frame: 0,
+      pauseFrame: false,
+    },
+
+    bottomStreakText: {
+      animation: UIStreakAnimation.NONE,
+      frame: 0,
+      pauseFrame: false,
+    },
   },
 
   room: {

package/src/features/customStage/versusScreen.ts

@@ -4,6 +4,7 @@ import {
   RoomType,
   SoundEffect,
   StageID,
+  StageType,
 } from "isaac-typescript-definitions";
 import { game, sfxManager } from "../../cachedClasses";
 import { arrayRemove } from "../../functions/array";
@@ -18,7 +19,13 @@ import { PLAYER_PORTRAIT_PNG_FILE_NAMES } from "../../objects/playerPortraitPNGF
 import { VERSUS_SCREEN_BACKGROUND_COLORS } from "../../objects/versusScreenBackgroundColors";
 import { VERSUS_SCREEN_DIRT_SPOT_COLORS } from "../../objects/versusScreenDirtSpotColors";
 import { pause, unpause } from "../pause";
+import { runNextGameFrame } from "../runInNFrames";
 import { ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH } from "./customStageConstants";
+import {
+  DEFAULT_BASE_STAGE,
+  DEFAULT_BASE_STAGE_TYPE,
+  INVALID_STAGE_VALUE,
+} from "./exports";
 import v, { customBossPNGPaths } from "./v";
 
 const DEFAULT_CHARACTER = PlayerType.ISAAC;
@@ -102,12 +109,29 @@ export function versusScreenInit(): void {
 export function playVersusScreenAnimation(customStage: CustomStage): void {
   const room = game.GetRoom();
   const roomType = room.GetType();
+  const roomCleared = room.IsClear();
   const hud = game.GetHUD();
 
   if (roomType !== RoomType.BOSS) {
     return;
   }
 
+  if (roomCleared) {
+    return;
+  }
+
+  if (willVanillaVersusScreenPlay()) {
+    // Since we are on an invalid stage, the versus screen will have a completely black background.
+    // Revert to using the background from the default stage.
+    const level = game.GetLevel();
+    level.SetStage(DEFAULT_BASE_STAGE, DEFAULT_BASE_STAGE_TYPE);
+    runNextGameFrame(() => {
+      const futureLevel = game.GetLevel();
+      futureLevel.SetStage(INVALID_STAGE_VALUE, StageType.ORIGINAL);
+    });
+    return;
+  }
+
   v.run.showingBossVersusScreen = true;
 
   pause();
@@ -156,6 +180,11 @@ export function playVersusScreenAnimation(customStage: CustomStage): void {
   }
 }
 
+function willVanillaVersusScreenPlay() {
+  const bosses = getBosses();
+  return bosses.some((boss) => boss.GetBossID() !== 0);
+}
+
 /** Use the character of the 0th player. */
 function getPlayerPNGPaths(): [
   playerNamePNGPath: string,