isaacscript-common 7.5.0 → 7.5.1

package/src/features/customStage/versusScreen.ts

@@ -9,7 +9,7 @@ import {
 import { game, sfxManager } from "../../core/cachedClasses";
 import { arrayRemove } from "../../functions/array";
 import { getBosses } from "../../functions/bosses";
-import { getEntityID } from "../../functions/entities";
+import { getRoomSubType } from "../../functions/roomData";
 import { erange } from "../../functions/utils";
 import { CustomStage } from "../../interfaces/private/CustomStage";
 import { BOSS_NAME_PNG_FILE_NAMES } from "../../objects/bossNamePNGFileNames";
@@ -26,7 +26,7 @@ import {
   DEFAULT_BASE_STAGE_TYPE,
   INVALID_STAGE_VALUE,
 } from "./exports";
-import v, { customBossPNGPaths } from "./v";
+import v from "./v";
 
 const DEFAULT_CHARACTER = PlayerType.ISAAC;
 const DEFAULT_STAGE_ID = StageID.BASEMENT;
@@ -137,22 +137,25 @@ export function playVersusScreenAnimation(customStage: CustomStage): void {
   pause();
   hud.SetVisible(false);
 
-  const [playerNamePNGPath, playerPortraitPNGPath] = getPlayerPNGPaths();
-  versusScreenSprite.ReplaceSpritesheet(
-    PLAYER_NAME_ANM2_LAYER,
-    playerNamePNGPath,
-  );
-  versusScreenSprite.ReplaceSpritesheet(
-    PLAYER_PORTRAIT_ANM2_LAYER,
-    playerPortraitPNGPath,
-  );
+  // Player
+  {
+    const { namePNGPath, portraitPNGPath } = getPlayerPNGPaths();
+    versusScreenSprite.ReplaceSpritesheet(PLAYER_NAME_ANM2_LAYER, namePNGPath);
+    versusScreenSprite.ReplaceSpritesheet(
+      PLAYER_PORTRAIT_ANM2_LAYER,
+      portraitPNGPath,
+    );
+  }
 
-  const [bossNamePNGPath, bossPortraitPNGPath] = getBossPNGPaths();
-  versusScreenSprite.ReplaceSpritesheet(BOSS_NAME_ANM2_LAYER, bossNamePNGPath);
-  versusScreenSprite.ReplaceSpritesheet(
-    BOSS_PORTRAIT_ANM2_LAYER,
-    bossPortraitPNGPath,
-  );
+  // Boss
+  {
+    const { namePNGPath, portraitPNGPath } = getBossPNGPaths(customStage);
+    versusScreenSprite.ReplaceSpritesheet(BOSS_NAME_ANM2_LAYER, namePNGPath);
+    versusScreenSprite.ReplaceSpritesheet(
+      BOSS_PORTRAIT_ANM2_LAYER,
+      portraitPNGPath,
+    );
+  }
 
   versusScreenSprite.LoadGraphics();
 
@@ -186,67 +189,81 @@ function willVanillaVersusScreenPlay() {
 }
 
 /** Use the character of the 0th player. */
-function getPlayerPNGPaths(): [
-  playerNamePNGPath: string,
-  playerPortraitPNGPath: string,
-] {
+function getPlayerPNGPaths(): {
+  namePNGPath: string;
+  portraitPNGPath: string;
+} {
   const player = Isaac.GetPlayer();
   const character = player.GetPlayerType();
 
-  let playerNamePNGFileName = PLAYER_NAME_PNG_FILE_NAMES[character];
-  if (playerNamePNGFileName === undefined) {
-    playerNamePNGFileName = PLAYER_NAME_PNG_FILE_NAMES[DEFAULT_CHARACTER];
+  let namePNGFileName = PLAYER_NAME_PNG_FILE_NAMES[character];
+  if (namePNGFileName === undefined) {
+    namePNGFileName = PLAYER_NAME_PNG_FILE_NAMES[DEFAULT_CHARACTER];
   }
 
-  const playerNamePNGPath = `${PNG_PATH_PREFIX}/${playerNamePNGFileName}`;
+  const namePNGPath = `${PNG_PATH_PREFIX}/${namePNGFileName}`;
 
-  let playerPortraitFileName = PLAYER_PORTRAIT_PNG_FILE_NAMES[character];
-  if (playerNamePNGFileName === undefined) {
-    playerPortraitFileName = PLAYER_PORTRAIT_PNG_FILE_NAMES[DEFAULT_CHARACTER];
+  let portraitFileName = PLAYER_PORTRAIT_PNG_FILE_NAMES[character];
+  if (namePNGFileName === undefined) {
+    portraitFileName = PLAYER_PORTRAIT_PNG_FILE_NAMES[DEFAULT_CHARACTER];
   }
 
-  const playerPortraitPNGPath = `${PLAYER_PORTRAIT_PNG_PATH_PREFIX}/${playerPortraitFileName}`;
+  const portraitPNGPath = `${PLAYER_PORTRAIT_PNG_PATH_PREFIX}/${portraitFileName}`;
 
-  return [playerNamePNGPath, playerPortraitPNGPath];
+  return { namePNGPath, portraitPNGPath };
 }
 
 /** Use the boss of the first boss found. */
-function getBossPNGPaths(): [
-  bossNamePNGPath: string,
-  bossPortraitPNGPath: string,
-] {
-  const bosses = getBosses();
-  const firstBoss = bosses[0];
-
+function getBossPNGPaths(customStage: CustomStage): {
+  namePNGPath: string;
+  portraitPNGPath: string;
+} {
   // Prefer the PNG paths specified by the end-user, if any.
-  if (firstBoss !== undefined) {
-    const entityID = getEntityID(firstBoss);
-    const pngPaths = customBossPNGPaths.get(entityID);
-    if (pngPaths !== undefined) {
-      return pngPaths;
-    }
+  const paths = getBossPNGPathsCustom(customStage);
+  if (paths !== undefined) {
+    return paths;
   }
 
   // If this is not a vanilla boss, default to showing question marks.
+  const bosses = getBosses();
+  const firstBoss = bosses[0];
   const bossID = firstBoss === undefined ? 0 : firstBoss.GetBossID();
   if (bossID === 0) {
     const questionMarkSprite = `${PNG_PATH_PREFIX}/${
       BOSS_NAME_PNG_FILE_NAMES[BossID.BLUE_BABY]
     }`;
-    const bossNamePNGPath = questionMarkSprite;
-    const bossPortraitPNGPath = questionMarkSprite;
-    return [bossNamePNGPath, bossPortraitPNGPath];
+    const namePNGPath = questionMarkSprite;
+    const portraitPNGPath = questionMarkSprite;
+    return { namePNGPath, portraitPNGPath };
   }
 
   // If this is a vanilla boss, it will have a boss ID, and we can use the corresponding vanilla
   // files.
-  const bossNamePNGFileName = BOSS_NAME_PNG_FILE_NAMES[bossID];
-  const bossNamePNGPath = `${PNG_PATH_PREFIX}/${bossNamePNGFileName}`;
+  const namePNGFileName = BOSS_NAME_PNG_FILE_NAMES[bossID];
+  const namePNGPath = `${PNG_PATH_PREFIX}/${namePNGFileName}`;
 
-  const bossPortraitPNGFileName = BOSS_PORTRAIT_PNG_FILE_NAMES[bossID];
-  const bossPortraitPNGPath = `${PNG_PATH_PREFIX}/${bossPortraitPNGFileName}`;
+  const portraitPNGFileName = BOSS_PORTRAIT_PNG_FILE_NAMES[bossID];
+  const portraitPNGPath = `${PNG_PATH_PREFIX}/${portraitPNGFileName}`;
 
-  return [bossNamePNGPath, bossPortraitPNGPath];
+  return { namePNGPath, portraitPNGPath };
+}
+
+function getBossPNGPathsCustom(
+  customStage: CustomStage,
+): { namePNGPath: string; portraitPNGPath: string } | undefined {
+  if (customStage.bossPool === undefined) {
+    return undefined;
+  }
+
+  const roomSubType = getRoomSubType();
+  const matchingBossEntry = customStage.bossPool.find(
+    (bossEntry) => bossEntry.subType === roomSubType,
+  );
+  if (matchingBossEntry === undefined) {
+    return undefined;
+  }
+
+  return matchingBossEntry.versusScreen;
 }
 
 function finishVersusScreenAnimation() {
@@ -267,10 +284,8 @@ export function versusScreenPostRender(): void {
     return;
   }
 
-  const isPaused = game.IsPaused();
-  if (isPaused) {
-    return;
-  }
+  // We do not want to early return when the game is paused because we need to start displaying the
+  // black screen as soon as the slide animation starts.
 
   if (versusScreenSprite.IsFinished(VERSUS_SCREEN_ANIMATION_NAME)) {
     finishVersusScreenAnimation();

package/src/functions/doors.ts

@@ -21,6 +21,7 @@ import { ROOM_SHAPE_TO_DOOR_SLOTS } from "../objects/roomShapeToDoorSlots";
 import { arrayToBitFlags } from "./bitwise";
 import { directionToVector } from "./direction";
 import { getEnumValues } from "./enums";
+import { hasFlag } from "./flag";
 import { isTSTLSet } from "./tstlClass";
 import { asNumber } from "./types";
 
@@ -53,6 +54,21 @@ export function doorSlotFlagToDoorSlot(doorSlotFlag: DoorSlotFlag): DoorSlot {
   return doorSlot === undefined ? DEFAULT_DOOR_SLOT : doorSlot;
 }
 
+export function doorSlotFlagsToDoorSlots(
+  doorSlotFlags: BitFlags<DoorSlotFlag>,
+): DoorSlot[] {
+  const doorSlots: DoorSlot[] = [];
+
+  for (const doorSlotFlag of getEnumValues(DoorSlotFlag)) {
+    if (hasFlag(doorSlotFlags, doorSlotFlag)) {
+      const doorSlot = doorSlotFlagToDoorSlot(doorSlotFlag);
+      doorSlots.push(doorSlot);
+    }
+  }
+
+  return doorSlots;
+}
+
 export function doorSlotToDirection(doorSlot: DoorSlot): Direction {
   return DOOR_SLOT_TO_DIRECTION[doorSlot];
 }
@@ -61,6 +77,27 @@ export function doorSlotToDoorSlotFlag(doorSlot: DoorSlot): DoorSlotFlag {
   return DOOR_SLOT_TO_DOOR_SLOT_FLAG[doorSlot];
 }
 
+/**
+ * Helper function to convert an array of door slots or a set of door slots to the resulting bit
+ * flag number.
+ */
+export function doorSlotsToDoorSlotFlags(
+  doorSlots:
+    | DoorSlot[]
+    | readonly DoorSlot[]
+    | Set<DoorSlot>
+    | ReadonlySet<DoorSlot>,
+): BitFlags<DoorSlotFlag> {
+  const doorSlotArray = isTSTLSet(doorSlots)
+    ? [...doorSlots.values()]
+    : (doorSlots as DoorSlot[]);
+  const doorSlotFlagArray = doorSlotArray.map((doorSlot) =>
+    doorSlotToDoorSlotFlag(doorSlot),
+  );
+
+  return arrayToBitFlags(doorSlotFlagArray);
+}
+
 export function getAngelRoomDoor(): GridEntityDoor | undefined {
   const angelRoomDoors = getDoors(RoomType.ANGEL);
   return angelRoomDoors.length === 0 ? undefined : angelRoomDoors[0];
@@ -113,27 +150,6 @@ export function getDoorSlotEnterPositionOffset(
   return oppositeVector.mul(ROOM_ENTRY_OFFSET_FROM_DOOR);
 }
 
-/**
- * Helper function to convert an array of door slots or a set of door slots to the resulting bit
- * flag number.
- */
-export function getDoorSlotFlags(
-  doorSlots:
-    | DoorSlot[]
-    | readonly DoorSlot[]
-    | Set<DoorSlot>
-    | ReadonlySet<DoorSlot>,
-): BitFlags<DoorSlotFlag> {
-  const doorSlotArray = isTSTLSet(doorSlots)
-    ? [...doorSlots.values()]
-    : (doorSlots as DoorSlot[]);
-  const doorSlotFlagArray = doorSlotArray.map((doorSlot) =>
-    doorSlotToDoorSlotFlag(doorSlot),
-  );
-
-  return arrayToBitFlags(doorSlotFlagArray);
-}
-
 /** Helper function to get the possible door slots that can exist for a given room shape. */
 export function getDoorSlotsForRoomShape(
   roomShape: RoomShape,

package/src/functions/enums.ts

@@ -18,7 +18,7 @@ import { irange } from "./utils";
  * Also see the `getEnumKeys` and `getEnumValues` helper functions.
  *
  * For a more in depth explanation, see:
- * https://isaacscript.github.io/gotchas#iterating-over-enums
+ * https://isaacscript.github.io/main/gotchas#iterating-over-enums
  */
 export function getEnumEntries<T>(
   transpiledEnum: T,
@@ -57,7 +57,7 @@ export function getEnumEntries<T>(
  * Also see the `getEnumEntries` and `getEnumValues` helper functions.
  *
  * For a more in depth explanation, see:
- * https://isaacscript.github.io/gotchas#iterating-over-enums
+ * https://isaacscript.github.io/main/gotchas#iterating-over-enums
  */
 export function getEnumKeys<T>(transpiledEnum: T): string[] {
   const enumEntries = getEnumEntries(transpiledEnum);
@@ -84,7 +84,7 @@ export function getEnumLength<T>(transpiledEnum: T): int {
  * Also see the `getEnumEntries` and `getEnumKeys` helper functions.
  *
  * For a more in depth explanation, see:
- * https://isaacscript.github.io/gotchas#iterating-over-enums
+ * https://isaacscript.github.io/main/gotchas#iterating-over-enums
  */
 export function getEnumValues<T>(transpiledEnum: T): Array<T[keyof T]> {
   const enumEntries = getEnumEntries(transpiledEnum);

package/src/functions/players.ts

@@ -21,7 +21,11 @@ import {
 import { getCollectibleMaxCharges } from "./collectibles";
 import { getCollectibleArray } from "./collectibleSet";
 import { getEnumValues } from "./enums";
-import { getPlayerIndexVanilla, getPlayers } from "./playerIndex";
+import {
+  getAllPlayers,
+  getPlayerIndexVanilla,
+  getPlayers,
+} from "./playerIndex";
 import { addTearsStat } from "./tears";
 import { isNumber } from "./types";
 import { repeat } from "./utils";
@@ -127,12 +131,12 @@ export function addTrinketCostume(
 export function anyPlayerHasCollectible(
   collectibleType: CollectibleType,
 ): boolean {
-  const players = getPlayers();
+  const players = getAllPlayers();
   return players.some((player) => player.HasCollectible(collectibleType));
 }
 
 export function anyPlayerHasTrinket(trinketType: TrinketType): boolean {
-  const players = getPlayers();
+  const players = getAllPlayers();
   return players.some((player) => player.HasTrinket(trinketType));
 }
 

package/src/index.ts

@@ -181,7 +181,7 @@ export * from "./functions/utils";
 export * from "./functions/vector";
 export * from "./interfaces/ChargeBarSprites";
 export * from "./interfaces/Corner";
-export * from "./interfaces/CustomStageLua";
+export * from "./interfaces/CustomStageTSConfig";
 export * from "./interfaces/GridEntityCustomData";
 export * from "./interfaces/JSONRoomsFile";
 export * from "./interfaces/PlayerHealth";

package/src/interfaces/{CustomStageLua.ts → CustomStageTSConfig.ts}

@@ -9,8 +9,11 @@
  *
  * The `CustomStageLua` interface extends this, adding room metadata.
  */
+
+import { Immutable } from "../types/Immutable";
+
 // ts-prune-ignore-next
-export type CustomStageTSConfig = Readonly<{
+export interface CustomStageTSConfig {
   /** Mandatory. The name of the custom stage. */
   name: string;
 
@@ -38,8 +41,14 @@ export type CustomStageTSConfig = Readonly<{
    * number of the stage that will be warped to and used as a basis for the stage by the level
    * generation algorithm.
    *
-   * (It is not possible to use Basement 1 as a base stage due to conflicts with the `Game.SetStage`
-   * method.)
+   * For example, if you wanted to have a custom stage with a small amount of rooms per floor, then
+   * you should choose 2 as a base. (This would copy the number of rooms that would appear in
+   * Basement 2.) And if you wanted to have a custom stage with the maximum amount of rooms, then
+   * you should choose 13 as a base. (This would copy the number of rooms that would appear on The
+   * Void.)
+   *
+   * It is not possible to use Basement 1 as a base stage due to conflicts with the `Game.SetStage`
+   * method.
    *
    * If not specified, `LevelStage.BASEMENT_2` (2) will be used.
    *
@@ -65,7 +74,7 @@ export type CustomStageTSConfig = Readonly<{
    * the graphics for the walls and floor.) If not specified, the graphics for Basement will be
    * used.
    */
-  backdropPNGPaths?: Readonly<{
+  backdropPNGPaths?: {
     /**
      * An array that contains the full paths to the graphic files that are used for the floor in
      * narrow rooms. (The "n" stands for "narrow").
@@ -75,7 +84,7 @@ export type CustomStageTSConfig = Readonly<{
      *
      * For an example of this, see the vanilla file "resources/gfx/backdrop/01_basement_nfloor.png".
      */
-    nFloors: readonly string[];
+    nFloors: string[];
 
     /**
      * An array that contains the full paths to the graphic files that are used for the floor in L
@@ -86,7 +95,7 @@ export type CustomStageTSConfig = Readonly<{
      *
      * For an example of this, see the vanilla file "resources/gfx/backdrop/01_lbasementfloor.png".
      */
-    lFloors: readonly string[];
+    lFloors: string[];
 
     /**
      * An array that contains the full paths to the graphic files that are used for the walls of the
@@ -99,7 +108,7 @@ export type CustomStageTSConfig = Readonly<{
      * the vanilla file, they concatenate all four variations together into one PNG file. However,
      * for the custom stages feature, you must separate each wall variation into a separate file.)
      */
-    walls: readonly string[];
+    walls: string[];
 
     /**
      * An array that contains the full paths to the graphic files for the stage's corners.
@@ -114,8 +123,8 @@ export type CustomStageTSConfig = Readonly<{
      * you must separate each corner variation into a separate file (and put it in a different file
      * from the walls).
      */
-    corners: readonly string[];
-  }>;
+    corners: string[];
+  };
 
   /**
    * Optional. The full path to the spritesheet that contains the graphics of the decorations for
@@ -153,7 +162,7 @@ export type CustomStageTSConfig = Readonly<{
    * Optional. A collection of paths that contain graphics for the doors of the floor. If not
    * specified, the doors for Basement will be used.
    */
-  doorPNGPaths?: Readonly<{
+  doorPNGPaths?: {
     /**
      * Optional. The full path to the spritesheet that contains the graphics of the normal doors for
      * the floor.
@@ -261,7 +270,7 @@ export type CustomStageTSConfig = Readonly<{
      * located at: `resources/gfx/grid/door_02b_chestroomdoor.png`
      */
     chestRoom?: string; // RoomType.CHEST (20)
-  }>;
+  };
 
   /**
    * Optional. An array of shadow objects that describe the graphics for the custom shadows of the
@@ -269,7 +278,7 @@ export type CustomStageTSConfig = Readonly<{
    * Basement, a shadow of a sideways V is used, among others.) If not specified, no extra shadows
    * will be drawn.
    */
-  shadows?: Readonly<{
+  shadows?: {
     /**
      * Optional. An array containing the shadows that will be used in rooms of shape
      * `RoomShape.SHAPE_1x1` (1), `RoomShape.IH` (2), and `RoomShape.IV` (3).
@@ -278,7 +287,7 @@ export type CustomStageTSConfig = Readonly<{
      *
      * If not specified, no extra shadows will be drawn in these room shapes.
      */
-    "1x1"?: readonly CustomStageShadow[];
+    "1x1"?: CustomStageShadow[];
 
     /**
      * Optional. An array containing the shadows that will be used in rooms of shape
@@ -288,7 +297,7 @@ export type CustomStageTSConfig = Readonly<{
      *
      * If not specified, no extra shadows will be drawn in these room shapes.
      */
-    "1x2"?: readonly CustomStageShadow[];
+    "1x2"?: CustomStageShadow[];
 
     /**
      * Optional. An array containing the shadows that will be used in rooms of shape
@@ -298,7 +307,7 @@ export type CustomStageTSConfig = Readonly<{
      *
      * If not specified, no extra shadows will be drawn in these room shapes.
      */
-    "2x1"?: readonly CustomStageShadow[];
+    "2x1"?: CustomStageShadow[];
 
     /**
      * Optional. An array containing the shadows that will be used in rooms of shape
@@ -309,14 +318,22 @@ export type CustomStageTSConfig = Readonly<{
      *
      * If not specified, no extra shadows will be drawn in these room shapes.
      */
-    "2x2"?: readonly CustomStageShadow[];
-  }>;
+    "2x2"?: CustomStageShadow[];
+  };
 
-  /** Optional. An array containing the bosses that should be used for the stage. */
-  bossPool?: readonly CustomStageBossPoolEntry[];
+  /**
+   * Optional. An array containing the bosses that should be used for the stage. This can include
+   * both vanilla bosses and modded bosses.
+   */
+  bossPool?: CustomStageBossPoolEntry[];
 
-  /** Optional. A collection of colors used in the boss "versus" screen. */
-  versusScreen?: Readonly<{
+  /**
+   * Optional. A collection of colors used for in the boss "versus" screen for all of the bosses.
+   *
+   * Note that these graphics will only be applied if one or more bosses are specified in the
+   * `bossPool` field.
+   */
+  versusScreen?: {
     /**
      * Optional. An object representing the color to use for the background of the boss "versus"
      * screen. If not specified, the color for Basement 1 will be used.
@@ -324,7 +341,7 @@ export type CustomStageTSConfig = Readonly<{
      * For a list of the colors that correspond to the vanilla stages, see
      * `versusScreenBackgroundColors.ts`.
      */
-    backgroundColor?: Readonly<{
+    backgroundColor?: {
       /**
        * @minimum 0
        * @maximum 1
@@ -348,7 +365,7 @@ export type CustomStageTSConfig = Readonly<{
        * @maximum 1
        */
       a: number;
-    }>;
+    };
 
     /**
      * Optional. An object representing the color to use for the dirt spots in the boss "versus"
@@ -358,7 +375,7 @@ export type CustomStageTSConfig = Readonly<{
      * For a list of the colors that correspond to the vanilla stages, see
      * `versusScreenDirtSpotColors.ts`.
      */
-    dirtSpotColor?: Readonly<{
+    dirtSpotColor?: {
       /**
        * @minimum 0
        * @maximum 1
@@ -382,16 +399,16 @@ export type CustomStageTSConfig = Readonly<{
        * @maximum 1
        */
       a: number;
-    }>;
-  }>;
-}>;
+    };
+  };
+}
 
 /**
  * A description of a custom stage shadow. (In this context, "shadows" are the outlines from things
  * on the roof. For example, in Basement, a shadow of a sideways V is used, among others.)
  */
 // ts-prune-ignore-next
-export type CustomStageShadow = Readonly<{
+export interface CustomStageShadow {
   /**
    * The full path to the shadow overlay PNG file.
    *
@@ -406,7 +423,7 @@ export type CustomStageShadow = Readonly<{
    * If not specified, an object of `{ r: 0, g: 0, b: 0, a: 0.25 }` will be used (which corresponds
    * to 75% faded black).
    */
-  color?: Readonly<{
+  color?: {
     /**
      * @minimum 0
      * @maximum 1
@@ -430,27 +447,66 @@ export type CustomStageShadow = Readonly<{
      * @maximum 1
      */
     a: number;
-  }>;
-}>;
+  };
+}
 
-/** An object that represents a possible boss for a custom stage. */
+/**
+ * An object that represents a possible boss for a custom stage. This can be for a vanilla boss or a
+ * custom boss.
+ */
 // ts-prune-ignore-next
 export interface CustomStageBossPoolEntry {
   /**
-   * The name of the boss. This must correspond to the entry in "entities2.xml".
-   *
-   * Note that since there is no way to determine the corresponding `EntityType` of the boss during
-   * compile-time, you must specify the `EntityType` at run-time when your mod first loads using the
-   * `registerCustomBoss` helper function.
+   * The name of the boss. This should correspond to the entry for the boss in the "entities2.xml"
+   * file.
    */
   name: string;
 
+  /**
+   * The arbitrary sub-type chosen for this boss, ranging between 1 and 999. You must set the boss
+   * rooms for this boss to this sub-type in Basement Renovator by right-clicking on the room on the
+   * right-hand-side.
+   *
+   * It does not matter if the arbitrary sub-type overlaps with any of the vanilla `BossID` values
+   * (e.g. vanilla Boss Room sub-types in "00.special_rooms.stb"). It also does not matter if this
+   * value overlaps with the values from other mods.
+   *
+   * If you are creating an entry for a vanilla boss, it is recommended that you match the sub-type
+   * with the corresponding vanilla `BossID` value. This will make things a bit easier to understand
+   * for people working on your mod, but is not a hard requirement.
+   *
+   * @minimum 1
+   * @maximum 999
+   */
+  subType: number;
+
   /**
    * The weight of the boss. This is used when randomly selecting which boss to use for the floor.
    * For example, use a value of 1 if you want this boss to be equally likely as any other boss, 0.5
    * if you want it to be half as likely, 2 if you want it to be twice as likely, and so on.
    */
   weight: number;
+
+  /** Optional. A collection of sprites used for the boss on the "versus" screen. */
+  versusScreen?: {
+    // eslint-disable-next-line isaacscript/complete-sentences-jsdoc
+    /**
+     * Mandatory. The full path to the spritesheet that contains the graphics of the name of the
+     * boss that will be displayed on the top of the boss "versus" screen.
+     *
+     * If not specified, a sprite showing "???" will be used.
+     */
+    namePNGPath: string;
+
+    // eslint-disable-next-line isaacscript/complete-sentences-jsdoc
+    /**
+     * Mandatory. The full path to the spritesheet that contains the portrait of the boss that will
+     * be displayed on the right side of the boss "versus" screen.
+     *
+     * If not specified, a sprite showing "???" will be used.
+     */
+    portraitPNGPath: string;
+  };
 }
 
 /**
@@ -460,19 +516,29 @@ export interface CustomStageBossPoolEntry {
  *
  * The `CustomStage` interface extends this, adding more data.
  */
-export interface CustomStageLua extends CustomStageTSConfig {
-  readonly roomsMetadata: readonly CustomStageRoomMetadata[];
+interface CustomStageLuaUnsafe extends CustomStageTSConfig {
+  /**
+   * This contains metadata about each room in a custom stage, which is used at run-time.
+   * (Internally, the IsaacScript standard library uses this as a basis for determining which rooms
+   * should randomly appear on the floor.)
+   */
+  roomsMetadata: CustomStageRoomMetadata[];
 }
 
+/** @internal */
+export type CustomStageLua = Immutable<CustomStageLuaUnsafe>;
+
 /**
  * Metadata about a custom stage room. Each custom stage object contains an array with metadata for
  * each room.
+ *
+ * @internal
  */
-export type CustomStageRoomMetadata = Readonly<{
+export interface CustomStageRoomMetadata {
   type: number;
   variant: number;
   subType: number;
   shape: number;
   doorSlotFlags: number;
   weight: number;
-}>;
+}