isaacscript-common 6.6.1-dev.1 → 6.6.1-dev.5

package/src/features/ponyDetection.ts

@@ -0,0 +1,86 @@
+// Detecting whether or not A Pony or White Pony is active is difficult with the vanilla API.
+// Normally, activation will cause the player to have the respective temporary collectible effect
+// However, this effect is lost if the player enters a new room (but the effect will still be
+// active). When the effect is active, the player will have some specific entity flags. Thus, we can
+// work around the problem by checking to see if the player has these entity flags and has had a
+// collectible effect on a previous frame.
+
+import { CollectibleType, EntityFlag } from "isaac-typescript-definitions";
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import { hasFlag } from "../functions/flag";
+import {
+  setAddPlayer,
+  setDeletePlayer,
+  setHasPlayer,
+} from "../functions/playerDataStructures";
+import { getPlayers } from "../functions/playerIndex";
+import { PlayerIndex } from "../types/PlayerIndex";
+import { saveDataManager } from "./saveDataManager/exports";
+
+const FEATURE_NAME = "ponyDetection";
+
+const FLAGS_WHEN_PONY_IS_ACTIVE: readonly EntityFlag[] = [
+  EntityFlag.NO_KNOCKBACK, // 1 << 26
+  EntityFlag.NO_PHYSICS_KNOCKBACK, // 1 << 30
+  EntityFlag.NO_DAMAGE_BLINK, // 1 << 36
+];
+
+const v = {
+  run: {
+    playersIsPonyActive: new Set<PlayerIndex>(),
+  },
+};
+
+/** @internal */
+export function ponyDetectionInit(mod: ModUpgraded): void {
+  saveDataManager(FEATURE_NAME, v);
+
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED,
+    postPEffectUpdateReordered,
+  );
+}
+
+// ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED
+function postPEffectUpdateReordered(player: EntityPlayer) {
+  const effects = player.GetEffects();
+  const entityFlags = player.GetEntityFlags();
+  const hasPonyCollectibleEffect =
+    effects.HasCollectibleEffect(CollectibleType.PONY) ||
+    effects.HasCollectibleEffect(CollectibleType.WHITE_PONY);
+  const isPonyActiveOnPreviousFrame = setHasPlayer(
+    v.run.playersIsPonyActive,
+    player,
+  );
+  const hasPonyFlags = hasFlag(entityFlags, ...FLAGS_WHEN_PONY_IS_ACTIVE);
+
+  const isPonyActiveNow =
+    hasPonyCollectibleEffect || (isPonyActiveOnPreviousFrame && hasPonyFlags);
+  if (isPonyActiveNow) {
+    setAddPlayer(v.run.playersIsPonyActive, player);
+  } else {
+    setDeletePlayer(v.run.playersIsPonyActive, player);
+  }
+}
+
+/**
+ * Helper function to see if the player is under the effects of A Pony or White Pony charge.
+ * Detecting this is difficult, as the temporary effect will disappear upon entering a new room.
+ */
+export function isPlayerUsingPony(player: EntityPlayer): boolean {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  return setHasPlayer(v.run.playersIsPonyActive, player);
+}
+
+/**
+ * Helper function to see if any player is under the effects of A Pony or White Pony charge.
+ * Detecting this is difficult, as the temporary effect will disappear upon entering a new room.
+ */
+export function anyPlayerUsingPony(): boolean {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  const players = getPlayers();
+  return players.some((player) => isPlayerUsingPony(player));
+}

package/src/features/preventCollectibleRotation.ts

@@ -0,0 +1,115 @@
+// Keep specific items from being affected by the Glitched Crown, Binge Eater, and the Tainted Isaac
+// switching mechanic.
+
+import {
+  Card,
+  CollectibleType,
+  ModCallback,
+  PickupVariant,
+} from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import { setCollectibleSubType } from "../functions/collectibles";
+import { getEntityID } from "../functions/entity";
+import { isCollectible } from "../functions/pickupVariants";
+import { saveDataManager } from "./saveDataManager/exports";
+
+const FEATURE_NAME = "preventCollectibleRotation";
+
+const v = {
+  room: {
+    /**
+     * Index is a string containing the grid index and the InitSeed of the collectible.
+     * (e.g. "12,1123579202")
+     *
+     * (We cannot simply use the InitSeed of the collectible because Diplopia can cause multiple
+     * collectibles in the room to have the same InitSeed. However, no two collectibles should ever
+     * be on the same grid index.)
+     *
+     * (We cannot use PtrHash as an index because that stays the same when the item is rolled.)
+     */
+    trackedCollectibles: new Map<string, CollectibleType>(),
+  },
+};
+
+/** @internal */
+export function preventCollectibleRotationInit(mod: Mod): void {
+  saveDataManager(FEATURE_NAME, v);
+
+  mod.AddCallback(
+    ModCallback.POST_USE_CARD,
+    useCardSoulOfIsaac,
+    Card.SOUL_ISAAC,
+  ); // 5
+
+  mod.AddCallback(
+    ModCallback.POST_PICKUP_UPDATE,
+    postPickupUpdateCollectible,
+    PickupVariant.COLLECTIBLE,
+  ); // 35
+}
+
+// ModCallback.POST_USE_CARD (5)
+// Card.SOUL_ISAAC (81)
+function useCardSoulOfIsaac() {
+  // Soul of Isaac causes items to flip. Delete all tracked items (assuming that the player
+  // deliberately wants to roll a quest item).
+  v.room.trackedCollectibles.clear();
+}
+
+// ModCallback.POST_PICKUP_UPDATE (35)
+// PickupVariant.COLLECTIBLE (100)
+function postPickupUpdateCollectible(pickup: EntityPickup) {
+  const collectible = pickup as EntityPickupCollectible;
+
+  // Ignore empty pedestals (i.e. items that have already been taken by the player).
+  if (collectible.SubType === CollectibleType.NULL) {
+    return;
+  }
+
+  const index = getMapIndex(collectible);
+  const trackedCollectibleType = v.room.trackedCollectibles.get(index);
+  if (
+    trackedCollectibleType !== undefined &&
+    collectible.SubType !== trackedCollectibleType
+  ) {
+    // This item has switched, so restore it back to the way it was.
+    setCollectibleSubType(collectible, trackedCollectibleType);
+  }
+}
+
+/**
+ * Helper function to prevent a collectible from being affected by Tainted Isaac's rotation
+ * mechanic. (This mechanic also happens from Glitched Crown and Binge Eater.) This is useful
+ * because quest items that are manually spawned by mods will be automatically be affected by this
+ * mechanic.
+ *
+ * It is required to pass the intended collectible type to this function since it is possible for
+ * collectibles to rotate on the first frame that they are spawned.
+ */
+export function preventCollectibleRotation(
+  collectible: EntityPickup,
+  collectibleType: CollectibleType,
+): void {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  if (!isCollectible(collectible)) {
+    const entityID = getEntityID(collectible);
+    error(
+      `The "preventCollectibleRotate" function was given a non-collectible: ${entityID}`,
+    );
+  }
+
+  const index = getMapIndex(collectible);
+  v.room.trackedCollectibles.set(index, collectibleType);
+
+  // The item might have already shifted on the first frame that it spawns, so change it back if
+  // necessary.
+  postPickupUpdateCollectible(collectible);
+}
+
+function getMapIndex(collectible: EntityPickup) {
+  const room = game.GetRoom();
+  const gridIndex = room.GetGridIndex(collectible.Position);
+  return `${gridIndex},${collectible.InitSeed}`;
+}

package/src/features/registerHotkey.ts

@@ -0,0 +1,124 @@
+import { Keyboard, ModCallback } from "isaac-typescript-definitions";
+import { DefaultMap } from "../classes/DefaultMap";
+import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import { isKeyboardPressed } from "../functions/input";
+import { isFunction } from "../functions/types";
+
+const FEATURE_NAME = "registerHotkeys";
+
+/**
+ * The keys are the keyboard keys that trigger the hotkey. The values are the functions that contain
+ * the arbitrary code to run.
+ */
+const staticHotkeyFunctionMap = new Map<Keyboard, () => void>();
+
+/**
+ * The keys are the functions that determine what the hotkey key is. The values are the functions
+ * that contain the arbitrary code to run.
+ */
+const dynamicHotkeyFunctionMap = new Map<
+  () => Keyboard | undefined,
+  () => void
+>();
+
+const keyPressedMap = new DefaultMap<Keyboard, boolean>(false);
+
+/** @internal */
+export function registerHotkeyInit(mod: Mod): void {
+  mod.AddCallback(ModCallback.POST_RENDER, postRender); // 2
+}
+
+// ModCallback.POST_RENDER (2)
+function postRender() {
+  for (const [keyboard, triggerFunc] of staticHotkeyFunctionMap.entries()) {
+    checkIfTriggered(keyboard, triggerFunc);
+  }
+
+  for (const [
+    keyboardFunc,
+    triggerFunc,
+  ] of dynamicHotkeyFunctionMap.entries()) {
+    const keyboard = keyboardFunc();
+    if (keyboard !== undefined) {
+      checkIfTriggered(keyboard, triggerFunc);
+    }
+  }
+}
+
+function checkIfTriggered(keyboard: Keyboard, triggerFunc: () => void) {
+  const isPressed = isKeyboardPressed(keyboard);
+  const wasPreviouslyPressed = keyPressedMap.getAndSetDefault(keyboard);
+  keyPressedMap.set(keyboard, isPressed);
+
+  if (isPressed && !wasPreviouslyPressed) {
+    triggerFunc();
+  }
+}
+
+/**
+ * Helper function to run arbitrary code when you press and release a specific keyboard key.
+ *
+ * This can be used to easily set up custom hotkeys to facilitate custom game features or to assist
+ * in debugging.
+ *
+ * @param keyboardOrFunc Either the key that you want to trigger the hotkey or a function that
+ *                       returns the key that will trigger the hotkey. Normally, you would just
+ *                       specify the key directly, but you can use a function for situations where
+ *                       the key can change (like if end-users can specify a custom hotkey using Mod
+ *                       Config Menu).
+ * @param triggerFunc A function containing the arbitrary code that you want to execute when the
+ *                    hotkey is triggered.
+ */
+export function registerHotkey(
+  keyboardOrFunc: Keyboard | (() => Keyboard | undefined),
+  triggerFunc: () => void,
+): void {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  if (isFunction(keyboardOrFunc)) {
+    if (dynamicHotkeyFunctionMap.has(keyboardOrFunc)) {
+      error(
+        "Failed to register a hotkey due to a custom hotkey already being defined for the submitted function.",
+      );
+    }
+
+    dynamicHotkeyFunctionMap.set(keyboardOrFunc, triggerFunc);
+  } else {
+    if (staticHotkeyFunctionMap.has(keyboardOrFunc)) {
+      error(
+        `Failed to register a hotkey due to a hotkey already being defined for key: Keyboard.${Keyboard[keyboardOrFunc]} (${keyboardOrFunc})`,
+      );
+    }
+
+    staticHotkeyFunctionMap.set(keyboardOrFunc, triggerFunc);
+  }
+}
+
+/**
+ * Helper function to remove a hotkey created with the `registerHotkey` function.
+ *
+ * @param keyboardOrFunc Equal to the value that you passed when initially registering the hotkey.
+ */
+export function unregisterHotkey(
+  keyboardOrFunc: Keyboard | (() => Keyboard | undefined),
+): void {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  if (isFunction(keyboardOrFunc)) {
+    if (!dynamicHotkeyFunctionMap.has(keyboardOrFunc)) {
+      error(
+        "Failed to unregister a hotkey since there is no existing hotkey defined for the submitted function.",
+      );
+    }
+
+    dynamicHotkeyFunctionMap.delete(keyboardOrFunc);
+  } else {
+    if (!staticHotkeyFunctionMap.has(keyboardOrFunc)) {
+      error(
+        `Failed to unregister a hotkey since there is no existing hotkey defined for key: Keyboard.${Keyboard[keyboardOrFunc]} (${keyboardOrFunc})`,
+      );
+    }
+
+    staticHotkeyFunctionMap.delete(keyboardOrFunc);
+  }
+}

package/src/features/roomClearFrame.ts

@@ -0,0 +1,54 @@
+import { game } from "../cachedClasses";
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import { saveDataManager } from "./saveDataManager/exports";
+
+const FEATURE_NAME = "roomClearFrame";
+
+const v = {
+  room: {
+    roomClearGameFrame: undefined as int | undefined,
+    roomClearRoomFrame: undefined as int | undefined,
+  },
+};
+
+/** @internal */
+export function roomClearFrameInit(mod: ModUpgraded): void {
+  saveDataManager(FEATURE_NAME, v);
+
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_ROOM_CLEAR_CHANGED,
+    postRoomClearChangedTrue,
+    true,
+  );
+}
+
+// ModCallbackCustom.POST_ROOM_CLEAR_CHANGED
+// true
+function postRoomClearChangedTrue() {
+  const gameFrameCount = game.GetFrameCount();
+  const room = game.GetRoom();
+  const roomFrameCount = room.GetFrameCount();
+
+  v.room.roomClearGameFrame = gameFrameCount;
+  v.room.roomClearRoomFrame = roomFrameCount;
+}
+
+/**
+ * Helper function to get the game frame (i.e. `Game.GetFrameCount`) of the last time that this room
+ * was cleared. Returns undefined if the room has never been cleared.
+ */
+export function getRoomClearGameFrame(): int | undefined {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  return v.room.roomClearGameFrame;
+}
+
+/**
+ * Helper function to get the room frame (i.e. `Room.GetFrameCount`) of the last time that this room
+ * was cleared. Returns undefined if the room has never been cleared.
+ */
+export function getRoomClearRoomFrame(): int | undefined {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  return v.room.roomClearGameFrame;
+}

package/src/features/runInNFrames.ts

@@ -0,0 +1,255 @@
+import { ModCallback } from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import { arrayRemoveInPlace } from "../functions/array";
+import { saveDataManager } from "./saveDataManager/exports";
+
+const FEATURE_NAME = "runInNFrames";
+
+/** Used for `runInNFrames` functions. */
+type QueuedFunctionTuple = [frameCountToFire: int, func: () => void];
+
+/**
+ * Used for `setInterval` functions.
+ *
+ * The return value is whether or not to continue the function from firing.
+ */
+type IntervalFunctionTuple = [
+  frameCountToFire: int,
+  func: () => boolean,
+  numIntervalFrames: int,
+];
+
+const v = {
+  run: {
+    queuedGameFunctionTuples: [] as QueuedFunctionTuple[],
+    queuedRenderFunctionTuples: [] as QueuedFunctionTuple[],
+
+    intervalGameFunctionTuples: [] as IntervalFunctionTuple[],
+    intervalRenderFunctionTuples: [] as IntervalFunctionTuple[],
+  },
+};
+
+/** @internal */
+export function runInNFramesInit(mod: Mod): void {
+  saveDataManager(FEATURE_NAME, v, () => false); // Functions are not serializable.
+
+  mod.AddCallback(ModCallback.POST_UPDATE, postUpdate); // 1
+  mod.AddCallback(ModCallback.POST_RENDER, postRender); // 2
+}
+
+// ModCallback.POST_UPDATE (1)
+function postUpdate() {
+  const gameFrameCount = game.GetFrameCount();
+
+  checkExecuteQueuedFunctions(gameFrameCount, v.run.queuedGameFunctionTuples);
+  checkExecuteIntervalFunctions(
+    gameFrameCount,
+    v.run.intervalGameFunctionTuples,
+  );
+}
+
+// ModCallback.POST_RENDER (2)
+function postRender() {
+  const renderFrameCount = Isaac.GetFrameCount();
+
+  checkExecuteQueuedFunctions(
+    renderFrameCount,
+    v.run.queuedRenderFunctionTuples,
+  );
+  checkExecuteIntervalFunctions(
+    renderFrameCount,
+    v.run.intervalRenderFunctionTuples,
+  );
+}
+
+function checkExecuteQueuedFunctions(
+  frameCount: int,
+  functionTuples: QueuedFunctionTuple[],
+) {
+  const firingFunctions = functionTuples.filter(
+    ([frameCountToFire]) => frameCount >= frameCountToFire,
+  );
+
+  for (const tuple of firingFunctions) {
+    const [_frameCountToFire, func] = tuple;
+    func();
+    arrayRemoveInPlace(functionTuples, tuple);
+  }
+}
+
+function checkExecuteIntervalFunctions(
+  frameCount: int,
+  functionTuples: IntervalFunctionTuple[],
+) {
+  const firingFunctions = functionTuples.filter(
+    ([frameCountToFire]) => frameCount >= frameCountToFire,
+  );
+
+  for (const tuple of firingFunctions) {
+    const [_frameCountToFire, func, numIntervalFrames] = tuple;
+    const returnValue = func();
+    arrayRemoveInPlace(functionTuples, tuple);
+
+    // Queue the next interval (as long as the function did not return false).
+    if (returnValue) {
+      const nextFireFrame = frameCount + numIntervalFrames;
+      const newTuple: IntervalFunctionTuple = [
+        nextFireFrame,
+        func,
+        numIntervalFrames,
+      ];
+      functionTuples.push(newTuple);
+    }
+  }
+}
+
+/**
+ * Supply a function to run N game frames from now in the `POST_UPDATE` callback.
+ *
+ * For a usage example, see the documentation for the `runNextGameFrame`, which is used in a similar
+ * way.
+ *
+ * Note that this function will not handle saving and quitting. If a player saving and quitting
+ * before the deferred function fires would cause a bug in your mod, then you should handle deferred
+ * functions manually using serializable data.
+ */
+export function runInNGameFrames(func: () => void, gameFrames: int): void {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  const gameFrameCount = game.GetFrameCount();
+  const functionFireFrame = gameFrameCount + gameFrames;
+  const tuple: QueuedFunctionTuple = [functionFireFrame, func];
+  v.run.queuedGameFunctionTuples.push(tuple);
+}
+
+/**
+ * Supply a function to run N render frames from now in the `POST_RENDER` callback.
+ *
+ * For a usage example, see the documentation for the `runNextGameFrame`, which is used in a similar
+ * way.
+ *
+ * Note that this function will not handle saving and quitting. If a player saving and quitting
+ * before the deferred function fires would cause a bug in your mod, then you should handle deferred
+ * functions manually using serializable data.
+ */
+export function runInNRenderFrames(func: () => void, renderFrames: int): void {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  const renderFrameCount = Isaac.GetFrameCount();
+  const functionFireFrame = renderFrameCount + renderFrames;
+  const tuple: QueuedFunctionTuple = [functionFireFrame, func];
+  v.run.queuedRenderFunctionTuples.push(tuple);
+}
+
+/**
+ * Supply a function to run on the next `POST_UPDATE` callback.
+ *
+ * For example:
+ *
+ * ```ts
+ * const NUM_EXPLODER_EXPLOSIONS = 5;
+ *
+ * function useItemExploder(player: EntityPlayer) {
+ *   playSound("exploderBegin");
+ *   explode(player, NUM_EXPLODER_EXPLOSIONS);
+ * }
+ *
+ * function explode(player: EntityPlayer, numFramesLeft: int) {
+ *   Isaac.Explode(player, undefined, 1);
+ *   numFramesLeft -= 1;
+ *   if (numFramesLeft === 0) {
+ *     runNextFrame(() => {
+ *       explode(player, numFramesLeft);
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * Note that this function will not handle saving and quitting. If a player saving and quitting
+ * before the deferred function fires would cause a bug in your mod, then you should handle deferred
+ * functions manually using serializable data.
+ */
+export function runNextGameFrame(func: () => void): void {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  runInNGameFrames(func, 1);
+}
+
+/**
+ * Supply a function to run on the next `POST_RENDER` callback.
+ *
+ * For a usage example, see the documentation for the `runNextGameFrame`, which is used in a similar
+ * way.
+ *
+ * Note that this function will not handle saving and quitting.
+ */
+export function runNextRenderFrame(func: () => void): void {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  runInNRenderFrames(func, 1);
+}
+
+/**
+ * Supply a function to be repeatedly run on an interval of N game frames in the `POST_UPDATE`
+ * callback. The function will continue to be fired until `false` is returned from the function.
+ *
+ * This is similar to the `setInterval` vanilla JavaScript function, except there is no
+ * corresponding `clearInterval` function. (Instead, the return value from the supplied function is
+ * used to stop the interval.)
+ *
+ * Note that this function will not handle saving and quitting. You must manually restart any
+ * intervals if the player saves and quits in the middle of a run.
+ *
+ * @param func The function to repeatedly run on an interval.
+ * @param gameFrames The amount of game frames to wait between each run.
+ * @param runImmediately Whether or not to execute the function right now before waiting for the
+ *                       interval.
+ */
+export function setIntervalGameFrames(
+  func: () => boolean,
+  gameFrames: int,
+  runImmediately: boolean,
+): void {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  const gameFrameCount = game.GetFrameCount();
+  const functionFireFrame = gameFrameCount + gameFrames;
+  const tuple: IntervalFunctionTuple = [functionFireFrame, func, gameFrames];
+  v.run.intervalGameFunctionTuples.push(tuple);
+
+  if (runImmediately) {
+    func();
+  }
+}
+
+/**
+ * Supply a function to be repeatedly run on an interval of N render frames in the `POST_RENDER`
+ * callback. The function will continue to be fired until `false` is returned from the function.
+ *
+ * This is similar to the `setInterval` vanilla JavaScript function, except there is no
+ * corresponding `clearInterval` function. (Instead, the return value from the supplied function is
+ * used to stop the interval.)
+ *
+ * Note that this function will not handle saving and quitting. You must manually restart any
+ * intervals if the player saves and quits in the middle of a run.
+ *
+ * @param func The function to repeatedly run on an interval.
+ * @param renderFrames The amount of game frames to wait between each run.
+ * @param runImmediately Whether or not to execute the function right now before waiting for the
+ *                       interval.
+ */
+export function setIntervalRenderFrames(
+  func: () => boolean,
+  renderFrames: int,
+  runImmediately: boolean,
+): void {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  const renderFrameCount = Isaac.GetFrameCount();
+  const functionFireFrame = renderFrameCount + renderFrames;
+  const tuple: IntervalFunctionTuple = [functionFireFrame, func, renderFrames];
+  v.run.intervalGameFunctionTuples.push(tuple);
+
+  if (runImmediately) {
+    func();
+  }
+}

package/src/features/runNextRoom.ts

@@ -0,0 +1,44 @@
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import { emptyArray } from "../functions/array";
+import { saveDataManager } from "./saveDataManager/exports";
+
+const FEATURE_NAME = "runNextRoom";
+
+const v = {
+  run: {
+    queuedFunctions: [] as Array<() => void>,
+  },
+};
+
+/** @internal */
+export function runNextRoomInit(mod: ModUpgraded): void {
+  saveDataManager(FEATURE_NAME, v, () => false); // Functions are not serializable.
+
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_NEW_ROOM_REORDERED,
+    postNewRoomReordered,
+  );
+}
+
+// ModCallbackCustom.POST_NEW_ROOM_REORDERED
+function postNewRoomReordered() {
+  for (const func of v.run.queuedFunctions) {
+    func();
+  }
+
+  emptyArray(v.run.queuedFunctions);
+}
+
+/**
+ * Supply a function to run on the next `POST_NEW_ROOM` callback.
+ *
+ * Note that this function will not handle saving and quitting. If a player saving and quitting
+ * before the deferred function fires would cause a bug in your mod, then you should handle deferred
+ * functions manually using serializable data.
+ */
+export function runNextRoom(func: () => void): void {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  v.run.queuedFunctions.push(func);
+}