isaacscript-common 7.5.0 → 7.6.1

package/src/features/customStage/customStageGridEntities.ts

@@ -16,9 +16,11 @@ import {
 import { calculateStageType } from "../../functions/stage";
 import { vectorEquals } from "../../functions/vector";
 import { CustomStage } from "../../interfaces/private/CustomStage";
-import { TrapdoorDestination } from "../../types/TrapdoorDestination";
 import { isCustomGridEntity } from "../customGridEntity";
-import { spawnCustomTrapdoor } from "../customTrapdoor/exports";
+import {
+  spawnCustomTrapdoor,
+  spawnCustomTrapdoorToVanilla,
+} from "../customTrapdoor/exports";
 import { DEFAULT_BASE_STAGE } from "./exports";
 import v from "./v";
 
@@ -203,20 +205,22 @@ export function convertVanillaTrapdoors(
 
   removeGridEntity(gridEntity, true);
 
-  // - If we are on the first floor of a custom stage, then the destination will be the second floor
-  //   of the custom stage. (e.g. Caves 1 to Caves 2)
-  // - If we are on the second floor of a custom stage, then the destination will be the vanilla
-  //   floor equivalent to 2 floors after the floor used as a basis for the custom stage.
-  const baseStage =
-    customStage.baseStage === undefined
-      ? DEFAULT_BASE_STAGE
-      : customStage.baseStage;
-  const vanillaNextStage = (baseStage + 2) as LevelStage;
-  const vanillaNextStageType = calculateStageType(vanillaNextStage);
-  const destination: TrapdoorDestination = v.run.firstFloor
-    ? [customStage.name, 2]
-    : [vanillaNextStage, vanillaNextStageType];
-  spawnCustomTrapdoor(gridEntity.Position, destination);
+  if (v.run.firstFloor) {
+    // If we are on the first floor of a custom stage, then the destination will be the second floor
+    // of the custom stage. (e.g. Caves 1 to Caves 2)
+    spawnCustomTrapdoor(gridEntity.Position, customStage.name, 2);
+  } else {
+    // If we are on the second floor of a custom stage, then the destination will be the vanilla
+    // floor equivalent to 2 floors after the floor used as a basis for the custom stage.
+    const baseStage =
+      customStage.baseStage === undefined
+        ? DEFAULT_BASE_STAGE
+        : customStage.baseStage;
+    const stage = (baseStage + 2) as LevelStage;
+    const stageType = calculateStageType(stage);
+
+    spawnCustomTrapdoorToVanilla(gridEntity.Position, stage, stageType);
+  }
 }
 
 /**

package/src/features/customStage/customStageUtils.ts

@@ -2,7 +2,10 @@ import { sumArray } from "../../functions/array";
 import { log } from "../../functions/log";
 import { getRandomFloat } from "../../functions/random";
 import { getRandomSeed } from "../../functions/rng";
-import { CustomStageRoomMetadata } from "../../interfaces/CustomStageLua";
+import {
+  CustomStageBossPoolEntry,
+  CustomStageRoomMetadata,
+} from "../../interfaces/CustomStageTSConfig";
 
 /**
  * Helper function to get a random custom stage room from an array of custom stage rooms.
@@ -52,3 +55,51 @@ function getCustomStageRoomWithChosenWeight(
     `Failed to get a custom stage room with chosen weight: ${chosenWeight}`,
   );
 }
+
+export function getRandomBossRoomFromPool(
+  roomsMetadata: readonly CustomStageRoomMetadata[],
+  bossPool: readonly CustomStageBossPoolEntry[],
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+  verbose = false,
+): CustomStageRoomMetadata {
+  const totalWeight = getTotalWeightOfBossPool(bossPool);
+  if (verbose) {
+    log(`Total weight of the custom stage boss pool provided: ${totalWeight}`);
+  }
+
+  const chosenWeight = getRandomFloat(0, totalWeight, seedOrRNG);
+  if (verbose) {
+    log(`Randomly chose weight for custom stage boss pool: ${chosenWeight}`);
+  }
+
+  const bossEntry = getBossEntryWithChosenWeight(bossPool, chosenWeight);
+
+  const roomsMetadataForBoss = roomsMetadata.filter(
+    (roomMetadata) => roomMetadata.subType === bossEntry.subType,
+  );
+  return getRandomCustomStageRoom(roomsMetadataForBoss, seedOrRNG, verbose);
+}
+
+function getTotalWeightOfBossPool(
+  bossPool: readonly CustomStageBossPoolEntry[],
+): float {
+  const weights = bossPool.map((bossEntry) => bossEntry.weight);
+  return sumArray(weights);
+}
+
+function getBossEntryWithChosenWeight(
+  bossPool: readonly CustomStageBossPoolEntry[],
+  chosenWeight: float,
+): CustomStageBossPoolEntry {
+  for (const bossEntry of bossPool) {
+    if (chosenWeight < bossEntry.weight) {
+      return bossEntry;
+    }
+
+    chosenWeight -= bossEntry.weight;
+  }
+
+  error(
+    `Failed to get a custom stage boss entry with chosen weight: ${chosenWeight}`,
+  );
+}

package/src/features/customStage/exports.ts

@@ -8,7 +8,7 @@
  */
 
 import {
-  EntityType,
+  DoorSlot,
   LevelStage,
   RoomShape,
   RoomType,
@@ -16,7 +16,7 @@ import {
 } from "isaac-typescript-definitions";
 import { reorderedCallbacksSetStageInternal } from "../../callbacks/reorderedCallbacks";
 import { game } from "../../core/cachedClasses";
-import { getEntityIDFromConstituents } from "../../functions/entities";
+import { doorSlotFlagsToDoorSlots } from "../../functions/doors";
 import { logError } from "../../functions/log";
 import { newRNG } from "../../functions/rng";
 import {
@@ -25,13 +25,13 @@ import {
 } from "../../functions/rooms";
 import { setStage } from "../../functions/stage";
 import { asNumber } from "../../functions/types";
+import { CustomStageRoomMetadata } from "../../interfaces/CustomStageTSConfig";
 import { CustomStage } from "../../interfaces/private/CustomStage";
-import { getRandomCustomStageRoom } from "./customStageUtils";
-import v, {
-  customBossPNGPaths,
-  customStageCachedRoomData,
-  customStagesMap,
-} from "./v";
+import {
+  getRandomBossRoomFromPool,
+  getRandomCustomStageRoom,
+} from "./customStageUtils";
+import v, { customStageCachedRoomData, customStagesMap } from "./v";
 
 export const DEFAULT_BASE_STAGE = LevelStage.BASEMENT_2;
 export const DEFAULT_BASE_STAGE_TYPE = StageType.ORIGINAL;
@@ -135,8 +135,8 @@ function setStageRoomsData(
     const roomType = room.Data.Type;
     const roomShapeMap = customStage.roomTypeMap.get(roomType);
     if (roomShapeMap === undefined) {
-      // Only show errors for non-default room types. (By default, we won't replace shops and other
-      // special rooms.)
+      // Only show errors for non-default room types. (We do not require that end-users provide
+      // custom rooms for shops and other special rooms inside of their XML file.)
       if (roomType === RoomType.DEFAULT) {
         logError(
           `Failed to find any custom rooms for RoomType.${RoomType[roomType]} (${roomType}) for custom stage: ${customStage.name}`,
@@ -160,10 +160,32 @@ function setStageRoomsData(
       logError(
         `Failed to find any custom rooms for RoomType.${RoomType[roomType]} (${roomType}) + RoomShape.${RoomShape[roomShape]} (${roomShape}) + DoorSlotFlags ${doorSlotFlags} for custom stage: ${customStage.name}`,
       );
+
+      const header = `For reference, a DoorSlotFlags of ${doorSlotFlags} is equal to the following doors being enabled:\n`;
+      const doorSlots = doorSlotFlagsToDoorSlots(doorSlotFlags);
+      const doorSlotLines = doorSlots.map(
+        (doorSlot) => `- DoorSlot.${DoorSlot[doorSlot]} (${doorSlot})`,
+      );
+      const explanation = header + doorSlotLines.join("\n");
+      logError(explanation);
       continue;
     }
 
-    const randomRoom = getRandomCustomStageRoom(roomsMetadata, rng, verbose);
+    let randomRoom: CustomStageRoomMetadata;
+    if (roomType === RoomType.BOSS) {
+      if (customStage.bossPool === undefined) {
+        continue;
+      }
+
+      randomRoom = getRandomBossRoomFromPool(
+        roomsMetadata,
+        customStage.bossPool,
+        rng,
+        verbose,
+      );
+    } else {
+      randomRoom = getRandomCustomStageRoom(roomsMetadata, rng, verbose);
+    }
 
     let newRoomData = customStageCachedRoomData.get(randomRoom.variant);
     if (newRoomData === undefined) {
@@ -187,40 +209,6 @@ function setStageRoomsData(
   }
 }
 
-/**
- * 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:
- *   `resources/gfx/ui/boss/bossname_20.0_monstro.png`
- * - The vanilla portrait sprite for Monstro is located at:
- *   `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 function registerCustomBoss(
-  entityType: EntityType,
-  variant: int,
-  subType: int,
-  namePNGPath: string,
-  portraitPNGPath: string,
-): void {
-  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.

package/src/features/customStage/init.ts

@@ -13,10 +13,11 @@ import { hasFlag, removeFlag } from "../../functions/flag";
 import {
   CustomStageLua,
   CustomStageRoomMetadata,
-} from "../../interfaces/CustomStageLua";
+} from "../../interfaces/CustomStageTSConfig";
 import { CustomStage, RoomTypeMap } from "../../interfaces/private/CustomStage";
 import { saveDataManager } from "../saveDataManager/exports";
 import { setCustomStageBackdrop } from "./backdrop";
+import { CUSTOM_STAGE_FEATURE_NAME } from "./customStageConstants";
 import {
   convertVanillaTrapdoors,
   removeUrnRewards,
@@ -42,7 +43,7 @@ export function customStageInit(mod: ModUpgraded): void {
     return;
   }
 
-  saveDataManager("customStage", v);
+  saveDataManager(CUSTOM_STAGE_FEATURE_NAME, v);
   versusScreenInit();
 
   mod.AddCallback(ModCallback.POST_RENDER, postRender); // 2

package/src/features/customStage/v.ts

@@ -40,9 +40,3 @@ export const customStagesMap = new Map<string, CustomStage>();
 
 /** Indexed by room variant. */
 export const customStageCachedRoomData = new Map<int, Readonly<RoomConfig>>();
-
-/** Indexed by entity ID. */
-export const customBossPNGPaths = new Map<
-  string,
-  [namePNGPath: string, portraitPNGPath: string]
->();

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";
@@ -18,15 +18,19 @@ import { PLAYER_NAME_PNG_FILE_NAMES } from "../../objects/playerNamePNGFileNames
 import { PLAYER_PORTRAIT_PNG_FILE_NAMES } from "../../objects/playerPortraitPNGFileNames";
 import { VERSUS_SCREEN_BACKGROUND_COLORS } from "../../objects/versusScreenBackgroundColors";
 import { VERSUS_SCREEN_DIRT_SPOT_COLORS } from "../../objects/versusScreenDirtSpotColors";
+import { disableAllSound, enableAllSound } from "../disableAllSound";
 import { pause, unpause } from "../pause";
 import { runNextGameFrame } from "../runInNFrames";
-import { ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH } from "./customStageConstants";
+import {
+  CUSTOM_STAGE_FEATURE_NAME,
+  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";
+import v from "./v";
 
 const DEFAULT_CHARACTER = PlayerType.ISAAC;
 const DEFAULT_STAGE_ID = StageID.BASEMENT;
@@ -136,23 +140,27 @@ export function playVersusScreenAnimation(customStage: CustomStage): void {
 
   pause();
   hud.SetVisible(false);
+  disableAllSound(CUSTOM_STAGE_FEATURE_NAME);
+
+  // Player
+  {
+    const { namePNGPath, portraitPNGPath } = getPlayerPNGPaths();
+    versusScreenSprite.ReplaceSpritesheet(PLAYER_NAME_ANM2_LAYER, namePNGPath);
+    versusScreenSprite.ReplaceSpritesheet(
+      PLAYER_PORTRAIT_ANM2_LAYER,
+      portraitPNGPath,
+    );
+  }
 
-  const [playerNamePNGPath, playerPortraitPNGPath] = getPlayerPNGPaths();
-  versusScreenSprite.ReplaceSpritesheet(
-    PLAYER_NAME_ANM2_LAYER,
-    playerNamePNGPath,
-  );
-  versusScreenSprite.ReplaceSpritesheet(
-    PLAYER_PORTRAIT_ANM2_LAYER,
-    playerPortraitPNGPath,
-  );
-
-  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 +194,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 portraitPNGFileName = BOSS_PORTRAIT_PNG_FILE_NAMES[bossID];
+  const portraitPNGPath = `${PNG_PATH_PREFIX}/${portraitPNGFileName}`;
+
+  return { namePNGPath, portraitPNGPath };
+}
 
-  const bossPortraitPNGFileName = BOSS_PORTRAIT_PNG_FILE_NAMES[bossID];
-  const bossPortraitPNGPath = `${PNG_PATH_PREFIX}/${bossPortraitPNGFileName}`;
+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 [bossNamePNGPath, bossPortraitPNGPath];
+  return matchingBossEntry.versusScreen;
 }
 
 function finishVersusScreenAnimation() {
@@ -256,6 +278,7 @@ function finishVersusScreenAnimation() {
 
   unpause();
   hud.SetVisible(true);
+  enableAllSound(CUSTOM_STAGE_FEATURE_NAME);
 
   // The sound effect only plays once the versus cutscene is over.
   sfxManager.Play(SoundEffect.CASTLE_PORTCULLIS);
@@ -267,10 +290,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/features/customTrapdoor/exports.ts

@@ -1,45 +1,28 @@
-import {
-  GridCollisionClass,
-  LevelStage,
-  StageType,
-} from "isaac-typescript-definitions";
-import { game } from "../../core/cachedClasses";
-import { TrapdoorAnimation } from "../../enums/private/TrapdoorAnimation";
+import { LevelStage, StageType } from "isaac-typescript-definitions";
 import { errorIfFeaturesNotInitialized } from "../../featuresInitialized";
 import { getNextStage, getNextStageType } from "../../functions/nextStage";
-import { getRoomListIndex } from "../../functions/roomData";
-import { isVector } from "../../functions/vector";
-import { CustomTrapdoorDescription } from "../../interfaces/private/CustomTrapdoorDescription";
-import { TrapdoorDestination } from "../../types/TrapdoorDestination";
-import { spawnCustomGridEntity } from "../customGridEntity";
-import {
-  CUSTOM_TRAPDOOR_FEATURE_NAME,
-  GridEntityTypeCustom,
-} from "./customTrapdoorConstants";
-import { shouldTrapdoorSpawnOpen } from "./openClose";
-import v from "./v";
+import { CustomTrapdoorDestination } from "../../interfaces/private/CustomTrapdoorDestination";
+import { CUSTOM_TRAPDOOR_FEATURE_NAME } from "./customTrapdoorConstants";
+import { spawnCustomTrapdoorToDestination } from "./spawn";
 
 /**
- * Helper function to spawn a trapdoor grid entity that will have one or more of the following
- * attributes:
+ * Helper function to spawn a trapdoor grid entity that will take a player to a custom stage. If you
+ * want to create a custom trapdoor that goes to a vanilla stage instead, use the
+ * `spawnCustomTrapdoorToVanilla` helper function.
+ *
+ * Custom trapdoors can have one or more of the following attributes:
  *
  * - custom destination (or custom logic for after the player enters)
  * - custom graphics
  * - custom logic for opening/closing
  *
- * You can use this function to take the player to your custom stage.
- *
  * Under the hood, the custom trapdoor is represented by a decoration grid entity and is manually
  * respawned every time the player re-enters the room.
  *
  * @param gridIndexOrPosition The location in the room to spawn the trapdoor.
- * @param destination Optional. Used to specify where the player will go after jumping into the
- *                    trapdoor. Can either be a vanilla stage tuple, a custom stage tuple, or
- *                    undefined. For example, a destination of `[LevelStage.CAVES_1,
- *                    StageType.ORIGINAL]` corresponds to Caves 1, and a destination of
- *                    `["Slaughterhouse", 1]` corresponds to a custom stage of Slaughterhouse 1. If
- *                    the destination is undefined, then the "normal" destination corresponding to
- *                    the current stage and room will be used (e.g. the next floor, in most cases).
+ * @param customStageName The name of the custom stage.
+ * @param customStageFloorNum The floor of the custom stage. For most purposes, you should use 1 or
+ *                            2.
  * @param anm2Path Optional. The path to the anm2 file to use. By default, the vanilla trapdoor anm2
  *                 of "gfx/grid/door_11_trapdoor.anm2" will be used. The specified anm2 file must
  *                 have animations called "Opened", "Closed", and "Open Animation".
@@ -48,54 +31,65 @@ import v from "./v";
  */
 export function spawnCustomTrapdoor(
   gridIndexOrPosition: int | Vector,
-  destination?: TrapdoorDestination,
+  customStageName: string,
+  customStageFloorNum: int,
   anm2Path = "gfx/grid/door_11_trapdoor.anm2",
   spawnOpen?: boolean,
 ): GridEntity {
   errorIfFeaturesNotInitialized(CUSTOM_TRAPDOOR_FEATURE_NAME);
 
-  const room = game.GetRoom();
-  const roomFrameCount = room.GetFrameCount();
-  const roomListIndex = getRoomListIndex();
-  const gridIndex = isVector(gridIndexOrPosition)
-    ? room.GetGridIndex(gridIndexOrPosition)
-    : gridIndexOrPosition;
+  const destination: CustomTrapdoorDestination = {
+    customStageName,
+    customStageFloorNum,
+  };
 
-  const gridEntity = spawnCustomGridEntity(
-    GridEntityTypeCustom.TRAPDOOR_CUSTOM,
+  return spawnCustomTrapdoorToDestination(
     gridIndexOrPosition,
-    GridCollisionClass.NONE,
+    destination,
     anm2Path,
-    TrapdoorAnimation.OPENED,
+    spawnOpen,
   );
+}
 
-  const firstSpawn = roomFrameCount !== 0;
-  const open =
-    spawnOpen === undefined
-      ? shouldTrapdoorSpawnOpen(gridEntity, firstSpawn)
-      : spawnOpen;
-  const destinationToUse =
-    destination === undefined ? getDefaultDestination() : destination;
-
-  const roomTrapdoorMap = v.level.trapdoors.getAndSetDefault(roomListIndex);
-  const customTrapdoorDescription: CustomTrapdoorDescription = {
-    open,
-    destination: destinationToUse,
-    firstSpawn,
-  };
-  roomTrapdoorMap.set(gridIndex, customTrapdoorDescription);
-
-  if (!open) {
-    const sprite = gridEntity.GetSprite();
-    sprite.Play(TrapdoorAnimation.CLOSED, true);
-  }
+/**
+ * This is the same thing as the `spawnCustomTrapdoor` function, but instead of having a destination
+ * of a custom stage, it has a destination of a vanilla stage.
+ *
+ * For more information, see the `spawnCustomTrapdoor` function.
+ *
+ * @param gridIndexOrPosition The location in the room to spawn the trapdoor.
+ * @param stage Optional. The number of the vanilla stage to go to. If not provided, the "normal"
+ *              next stage will be selected.
+ * @param stageType The stage type of the vanilla stage to go to. If not provided, the "normal" next
+ *                  stage type will be selected.
+ * @param anm2Path Optional. The path to the anm2 file to use. By default, the vanilla trapdoor anm2
+ *                 of "gfx/grid/door_11_trapdoor.anm2" will be used. The specified anm2 file must
+ *                 have animations called "Opened", "Closed", and "Open Animation".
+ * @param spawnOpen Optional. Whether or not to spawn the trapdoor in an open state. By default,
+ *                  behavior will be used that emulates a vanilla trapdoor.
+ */
+export function spawnCustomTrapdoorToVanilla(
+  gridIndexOrPosition: int | Vector,
+  stage?: LevelStage,
+  stageType?: StageType,
+  anm2Path = "gfx/grid/door_11_trapdoor.anm2",
+  spawnOpen?: boolean,
+): GridEntity {
+  errorIfFeaturesNotInitialized(CUSTOM_TRAPDOOR_FEATURE_NAME);
 
-  return gridEntity;
-}
+  const vanillaStage = stage === undefined ? getNextStage() : stage;
+  const vanillaStageType =
+    stageType === undefined ? getNextStageType() : stageType;
 
-function getDefaultDestination(): [stage: LevelStage, stageType: StageType] {
-  const nextStage = getNextStage();
-  const nextStageType = getNextStageType();
+  const destination: CustomTrapdoorDestination = {
+    vanillaStage,
+    vanillaStageType,
+  };
 
-  return [nextStage, nextStageType];
+  return spawnCustomTrapdoorToDestination(
+    gridIndexOrPosition,
+    destination,
+    anm2Path,
+    spawnOpen,
+  );
 }