isaacscript-common 7.5.0 → 7.6.1

package/src/features/customTrapdoor/init.ts

@@ -4,7 +4,6 @@ import {
   EntityGridCollisionClass,
   ModCallback,
   RoomTransitionAnim,
-  StageType,
 } from "isaac-typescript-definitions";
 import { ModUpgraded } from "../../classes/ModUpgraded";
 import { game } from "../../core/cachedClasses";
@@ -15,7 +14,6 @@ import { getAllPlayers } from "../../functions/playerIndex";
 import { getRoomGridIndex, getRoomListIndex } from "../../functions/roomData";
 import { teleport } from "../../functions/roomTransition";
 import { setStage } from "../../functions/stage";
-import { isString } from "../../functions/types";
 import { disableCustomStage, setCustomStage } from "../customStage/exports";
 import { topStreakTextStart } from "../customStage/streakText";
 import { enableAllInputs } from "../disableInputs";
@@ -119,7 +117,7 @@ function checkPixelationToBlackComplete() {
       StageTravelState.WAITING_FOR_SECOND_PIXELATION_TO_GET_HALF_WAY;
     v.run.stateRenderFrame = futureRenderFrameCount;
 
-    goToCustomDestination();
+    goToCustomTrapdoorDestination();
 
     // Start another pixelation effect. This time, we will keep the screen black with the sprite,
     // and then remove the black sprite once the pixelation effect is halfway complete.
@@ -193,21 +191,24 @@ function checkAllPlayersLayingDownComplete() {
   enableAllInputs(CUSTOM_TRAPDOOR_FEATURE_NAME);
 }
 
-function goToCustomDestination() {
+function goToCustomTrapdoorDestination() {
   if (v.run.destination === null) {
     return;
   }
 
-  const [arg1, arg2] = v.run.destination;
+  const {
+    customStageName,
+    customStageFloorNum,
+    vanillaStage,
+    vanillaStageType,
+  } = v.run.destination;
 
-  if (isString(arg1)) {
-    // A string represents a custom stage.
-    const firstFloor = arg2 === 1;
+  if (customStageName !== undefined && customStageFloorNum !== undefined) {
+    const firstFloor = customStageFloorNum === 1;
     setCustomStage("Slaughterhouse", firstFloor);
-  } else {
-    // A number represents a vanilla `LevelStage`.
+  } else if (vanillaStage !== undefined && vanillaStageType !== undefined) {
     disableCustomStage();
-    setStage(arg1, arg2 as StageType);
+    setStage(vanillaStage, vanillaStageType);
   }
 }
 

package/src/features/customTrapdoor/spawn.ts

@@ -0,0 +1,53 @@
+import { GridCollisionClass } from "isaac-typescript-definitions";
+import { game } from "../../core/cachedClasses";
+import { TrapdoorAnimation } from "../../enums/private/TrapdoorAnimation";
+import { getRoomListIndex } from "../../functions/roomData";
+import { isVector } from "../../functions/vector";
+import { CustomTrapdoorDescription } from "../../interfaces/private/CustomTrapdoorDescription";
+import { CustomTrapdoorDestination } from "../../interfaces/private/CustomTrapdoorDestination";
+import { spawnCustomGridEntity } from "../customGridEntity";
+import { GridEntityTypeCustom } from "./customTrapdoorConstants";
+import { shouldTrapdoorSpawnOpen } from "./openClose";
+import v from "./v";
+
+export function spawnCustomTrapdoorToDestination(
+  gridIndexOrPosition: int | Vector,
+  destination: CustomTrapdoorDestination,
+  anm2Path: string,
+  spawnOpen?: boolean,
+): GridEntity {
+  const room = game.GetRoom();
+  const roomFrameCount = room.GetFrameCount();
+  const roomListIndex = getRoomListIndex();
+  const gridIndex = isVector(gridIndexOrPosition)
+    ? room.GetGridIndex(gridIndexOrPosition)
+    : gridIndexOrPosition;
+
+  const gridEntity = spawnCustomGridEntity(
+    GridEntityTypeCustom.TRAPDOOR_CUSTOM,
+    gridIndexOrPosition,
+    GridCollisionClass.NONE,
+    anm2Path,
+    TrapdoorAnimation.OPENED,
+  );
+
+  const firstSpawn = roomFrameCount !== 0;
+  const open =
+    spawnOpen === undefined
+      ? shouldTrapdoorSpawnOpen(gridEntity, firstSpawn)
+      : spawnOpen;
+
+  const roomTrapdoorMap = v.level.trapdoors.getAndSetDefault(roomListIndex);
+  const customTrapdoorDescription: CustomTrapdoorDescription = {
+    open,
+    destination,
+    firstSpawn,
+  };
+  roomTrapdoorMap.set(gridIndex, customTrapdoorDescription);
+
+  const sprite = gridEntity.GetSprite();
+  const animation = open ? TrapdoorAnimation.OPENED : TrapdoorAnimation.CLOSED;
+  sprite.Play(animation, true);
+
+  return gridEntity;
+}

package/src/features/customTrapdoor/v.ts

@@ -1,7 +1,7 @@
 import { DefaultMap } from "../../classes/DefaultMap";
 import { StageTravelState } from "../../enums/private/StageTravelState";
 import { CustomTrapdoorDescription } from "../../interfaces/private/CustomTrapdoorDescription";
-import { TrapdoorDestination } from "../../types/TrapdoorDestination";
+import { CustomTrapdoorDestination } from "../../interfaces/private/CustomTrapdoorDestination";
 
 const v = {
   run: {
@@ -10,7 +10,7 @@ const v = {
     /** The render frame that this state was reached. */
     stateRenderFrame: null as int | null,
 
-    destination: null as TrapdoorDestination | null,
+    destination: null as CustomTrapdoorDestination | null,
   },
 
   level: {

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

@@ -22,8 +22,8 @@ export { registerCharacterStats } from "./features/characterStats";
 export { getCollectibleItemPoolType } from "./features/collectibleItemPoolType";
 export { initCustomDoor, spawnCustomDoor } from "./features/customDoor";
 export {
-  removeCustomGridEntity as removeCustomGrid,
-  spawnCustomGridEntity as spawnCustomGrid,
+  removeCustomGridEntity,
+  spawnCustomGridEntity,
 } from "./features/customGridEntity";
 export * from "./features/customStage/exports";
 export * from "./features/customTrapdoor/exports";
@@ -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";
@@ -204,5 +204,4 @@ export * from "./types/PickupIndex";
 export * from "./types/PlayerIndex";
 export * from "./types/PossibleStatType";
 export * from "./types/SerializedIsaacAPIClass";
-export * from "./types/TrapdoorDestination";
 export * from "./types/TSTLClass";

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;
 
@@ -29,7 +32,7 @@ export type CustomStageTSConfig = Readonly<{
    * https://isaacscript.github.io/main/custom-stages
    *
    * @minimum 101
-   * @maximum 109
+   * @maximum 999
    */
   roomVariantPrefix: number;
 
@@ -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;
-}>;
+}

package/src/interfaces/GridEntityCustomData.ts

@@ -18,7 +18,7 @@ export interface GridEntityCustomData {
 
   roomListIndex: int;
   gridIndex: int;
-  anm2Path: string;
+  gridCollisionClass?: GridCollisionClass;
+  anm2Path?: string;
   defaultAnimation?: string;
-  gridCollisionClass: GridCollisionClass;
 }

package/src/interfaces/JSONRoomsFile.ts

@@ -1,7 +1,7 @@
 /**
  * The standard library has the feature to deploy a new room on-the-fly with the `deployJSONRoom`
  * helper function. It requires a `JSONRoomsFile` as an argument, which is simply an XML file
- * converted to JSON. (You create XML room files using the Basement Renovator program.)
+ * converted to JSON. (You can create XML room files using the Basement Renovator program.)
  *
  * You can convert your XML files using the following command:
  *
@@ -17,11 +17,12 @@ export interface JSONRoomsFile {
   rooms: JSONRooms;
 }
 
+/** Part of `JSONRoomsFile`. */
 export interface JSONRooms {
   room: JSONRoom[];
 }
 
-/** Part of `JSONRooms`. */
+/** Part of `JSONRoomsFile`. */
 export interface JSONRoom {
   $: {
     /** Needs to be converted to an `int`. */
@@ -55,7 +56,7 @@ export interface JSONRoom {
   spawn: JSONSpawn[];
 }
 
-/** Part of `JSONRooms`. */
+/** Part of `JSONRoomsFile`. */
 export interface JSONDoor {
   $: {
     /** Equal to "True" or "False". Needs to be converted to an `boolean`. */
@@ -69,7 +70,7 @@ export interface JSONDoor {
   };
 }
 
-/** Part of `JSONRooms`. */
+/** Part of `JSONRoomsFile`. */
 export interface JSONSpawn {
   $: {
     /** Needs to be converted to an `int`. */
@@ -82,7 +83,7 @@ export interface JSONSpawn {
   entity: JSONEntity[];
 }
 
-/** Part of `JSONRooms`. */
+/** Part of `JSONRoomsFile`. */
 export interface JSONEntity {
   $: {
     /** Needs to be converted to an `int`. */