isaacscript-common 14.2.0 → 15.0.0

package/src/features/runInNFrames.ts

@@ -1,255 +0,0 @@
-import { ModCallback } from "isaac-typescript-definitions";
-import { game } from "../core/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

@@ -1,44 +0,0 @@
-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);
-}

package/src/features/saveDataManager/constants.ts

@@ -1,18 +0,0 @@
-import { SaveDataKey } from "../../enums/SaveDataKey";
-
-/** Set this to true to enable more verbosity in the save data manger. */
-export const SAVE_DATA_MANAGER_DEBUG = false as boolean;
-
-export const SAVE_DATA_MANAGER_FEATURE_NAME = "save data manager";
-
-/**
- * When the Glowing Hour Glass is used, certain save data keys will automatically be restored to a
- * backup.
- */
-export const SAVE_DATA_MANAGER_GLOWING_HOUR_GLASS_BACKUP_KEYS = [
-  SaveDataKey.RUN,
-  SaveDataKey.LEVEL,
-] as const;
-
-export const SAVE_DATA_MANAGER_GLOWING_HOUR_GLASS_IGNORE_KEY =
-  "__ignoreGlowingHourGlass";

package/src/features/saveDataManager/exports.ts

@@ -1,340 +0,0 @@
-import { SaveDataKey } from "../../enums/SaveDataKey";
-import { SerializationType } from "../../enums/SerializationType";
-import { errorIfFeaturesNotInitialized } from "../../featuresInitialized";
-import { deepCopy } from "../../functions/deepCopy";
-import { getTSTLClassName } from "../../functions/tstlClass";
-import { isString, isTable } from "../../functions/types";
-import { SaveData } from "../../interfaces/SaveData";
-import { AnyClass } from "../../types/AnyClass";
-import { SAVE_DATA_MANAGER_FEATURE_NAME } from "./constants";
-import {
-  forceSaveDataManagerLoad,
-  forceSaveDataManagerSave,
-  restoreDefaultSaveData,
-} from "./main";
-import {
-  saveDataConditionalFuncMap,
-  saveDataDefaultsMap,
-  saveDataGlowingHourGlassMap,
-  saveDataManagerClassConstructors,
-  saveDataMap,
-} from "./maps";
-
-const NON_USER_DEFINED_CLASS_NAMES: ReadonlySet<string> = new Set([
-  "Map",
-  "Set",
-  "DefaultMap",
-]);
-
-/**
- * This is the entry point to the save data manager, a system which provides two major features:
- *
- * 1. automatic resetting of variables on a new run, on a new level, or on a new room (as desired)
- * 2. automatic saving and loading of all tracked data to the "save#.dat" file
- *
- * You feed this function with an object containing your variables, and then it will automatically
- * manage them for you. (See below for an example.)
- *
- * The save data manager is meant to be called once for each feature of your mod. In other words,
- * you should not put all of the data for your mod on the same object. Instead, scope your variables
- * locally to a single file that contains a mod feature, and then call this function to register
- * them. For example:
- *
- * ```ts
- * // in file: feature1.ts
- * import { saveDataManager } from "isaacscript-common";
- *
- * // Declare local variables for this file or feature.
- * const v = {
- *   // These variables are never reset; manage them yourself at will.
- *   persistent: {
- *     foo1: 0,
- *   },
- *
- *   // These variables are reset at the beginning of every run.
- *   run: {
- *     foo2: 0,
- *   },
- *
- *   // These variables are reset at the beginning of every level.
- *   level: {
- *     foo3: 0,
- *   },
- *
- *   // These variables are reset at the beginning of every room.
- *   room: {
- *     foo4: 0,
- *   },
- * };
- * // Every child object is optional; only create the ones that you need.
- *
- * // Register the variables with the save data manager. (We need to provide a string key that
- * // matches the name of this file.)
- * function feature1Init() {
- *   saveDataManager("feature1", v);
- * }
- *
- * // Elsewhere in the file, use your variables.
- * function feature1Function() {
- *   if (v.run.foo1 > 0) {
- *     // Insert code here.
- *   }
- * }
- * ```
- *
- * - Save data is loaded from disk in the `POST_PLAYER_INIT` callback (i.e. the first callback that
- *   can possibly run).
- * - Save data is recorded to disk in the `PRE_GAME_EXIT` callback.
- *
- * You can put lots of data types on your variable objects, but not everything is supported. For the
- * specific things that are supported, see the documentation for the `deepCopy` helper function.
- *
- * Note that before using the save data manager, you must call the `upgradeMod` function. (Upgrade
- * your mod before registering any of your own callbacks so that the save data manager will run
- * before any of your code does.)
- *
- * If you want the save data manager to load data before the `POST_PLAYER_INIT` callback (i.e. in
- * the main menu), then you should explicitly call the `saveDataManagerLoad` function. (The save
- * data manager cannot do this on its own because it cannot know when your mod features are finished
- * initializing.)
- *
- * Some features may have variables that need to be automatically reset per run/level, but not saved
- * to disk on game exit. (For example, if they contain functions or other non-serializable data.)
- * For these cases, set the second argument to `false`.
- *
- * Note that when the player uses Glowing Hour Glass, the save data manager will automatically
- * restore any variables on a "run" or "level" object with a backup that was created when the room
- * was entered. Thus, you should not have to explicitly program support for Glowing Hour Glass into
- * your mod features that use the save data manager. If this is undesired for your specific
- * use-case, then add a key of `__ignoreGlowingHourGlass: true` to your "run" or "level" object.
- *
- * @param key The name of the file or feature that is submitting data to be managed by the save data
- *            manager. The save data manager will throw an error if the key is already registered.
- * @param v An object that corresponds to the `SaveData` interface. The object is conventionally
- *          called "v" for brevity. ("v" is short for "local variables").
- * @param conditionalFunc Optional. A function to run to check if this save data should be written
- *                        to disk. Default is `() => true`, meaning that this save data will always
- *                        be written to disk. Use a conditional function for the situations when the
- *                        local variables are for a feature that the end-user can disable. (If the
- *                        feature is disabled, then there would be no point in writing any of the
- *                        variables to the "save#.dat" file.) You can also specify `false` to this
- *                        argument in order to completely disable saving data. (Specifying `false`
- *                        will allow you to use non-serializable objects in your save data, such as
- *                        `EntityPtr`.
- */
-export function saveDataManager<Persistent, Run, Level>(
-  // This is the overload for the standard case with serializable data.
-  key: string,
-  v: SaveData<Persistent, Run, Level>,
-  conditionalFunc?: () => boolean,
-): void;
-export function saveDataManager(
-  // This is the overload for the case when saving data is disabled.
-  key: string,
-  v: SaveData,
-  conditionalFunc: false,
-): void;
-export function saveDataManager<Persistent, Run, Level>(
-  key: string,
-  v: SaveData<Persistent, Run, Level>,
-  conditionalFunc?: (() => boolean) | false,
-): void {
-  errorIfFeaturesNotInitialized(SAVE_DATA_MANAGER_FEATURE_NAME);
-
-  if (!isString(key)) {
-    error(
-      `The ${SAVE_DATA_MANAGER_FEATURE_NAME} requires that keys are strings. You tried to use a key of type: ${typeof key}`,
-    );
-  }
-
-  if (saveDataMap.has(key)) {
-    error(
-      `The ${SAVE_DATA_MANAGER_FEATURE_NAME} is already managing save data for a key of: ${key}`,
-    );
-  }
-
-  // First, recursively look through the new save data for any classes, so we can register them with
-  // the save data manager.
-  storeClassConstructorsFromObject(v as LuaMap);
-
-  // Add the new save data to the map.
-  saveDataMap.set(key, v);
-
-  // Convert the boolean to a function, if necessary. (Having the argument be a boolean is necessary
-  // in order for the overloads to work properly.)
-  if (conditionalFunc === false) {
-    conditionalFunc = () => false;
-  }
-
-  // If the only key in the save data is "room", then we don't have to worry about saving this data
-  // to disk (because the room would be reloaded upon resuming a continued run).
-  const saveDataKeys = Object.keys(v);
-  if (saveDataKeys.length === 1 && saveDataKeys[0] === "room") {
-    conditionalFunc = () => false;
-  }
-
-  // Make a copy of the initial save data so that we can use it to restore the default values later
-  // on.
-  const saveDataCopy = deepCopy(v, SerializationType.NONE, key);
-  saveDataDefaultsMap.set(key, saveDataCopy);
-
-  // Store the conditional function for later, if present.
-  if (conditionalFunc !== undefined) {
-    saveDataConditionalFuncMap.set(key, conditionalFunc);
-  }
-}
-
-/** Recursively traverses an object, collecting all of the class constructors that it encounters. */
-function storeClassConstructorsFromObject(luaMap: LuaMap<AnyNotNil, unknown>) {
-  const tstlClassName = getTSTLClassName(luaMap);
-  if (
-    tstlClassName !== undefined &&
-    !NON_USER_DEFINED_CLASS_NAMES.has(tstlClassName)
-  ) {
-    saveDataManagerClassConstructors.set(
-      tstlClassName,
-      luaMap as unknown as AnyClass,
-    );
-  }
-
-  for (const [_key, value] of luaMap) {
-    if (isTable(value)) {
-      storeClassConstructorsFromObject(value);
-    }
-  }
-}
-
-/**
- * The save data manager will automatically load variables from disk at the appropriate times (i.e.
- * when a new run is started). Use this function to explicitly force the save data manager to load
- * all of its variables from disk immediately.
- *
- * Obviously, doing this will overwrite the current data, so using this function can potentially
- * result in lost state.
- */
-export function saveDataManagerLoad(): void {
-  errorIfFeaturesNotInitialized(SAVE_DATA_MANAGER_FEATURE_NAME);
-  forceSaveDataManagerLoad();
-}
-
-/**
- * The save data manager will automatically save variables to disk at the appropriate times (i.e.
- * when the run is exited). Use this function to explicitly force the save data manager to write all
- * of its variables to disk immediately.
- */
-export function saveDataManagerSave(): void {
-  errorIfFeaturesNotInitialized(SAVE_DATA_MANAGER_FEATURE_NAME);
-  forceSaveDataManagerSave();
-}
-
-/** "g" stands for "globals". */
-declare let g: LuaMap<string, SaveData>; // eslint-disable-line @typescript-eslint/no-unused-vars
-
-/** "gd" stands for "globals defaults". */
-declare let gd: LuaMap<string, SaveData>; // eslint-disable-line @typescript-eslint/no-unused-vars
-
-/**
- * - Sets the global variable of "g" equal to all of the save data variables for this mod.
- * - Sets the global variable of "gd" equal to all of the save data default variables for this mod.
- *
- * This can make debugging easier, as you can access the variables from the game's debug console.
- * e.g. `l print(g.feature1.foo)`
- */
-export function saveDataManagerSetGlobal(): void {
-  errorIfFeaturesNotInitialized(SAVE_DATA_MANAGER_FEATURE_NAME);
-
-  g = saveDataMap;
-  gd = saveDataDefaultsMap;
-}
-
-/**
- * The save data manager will automatically reset variables at the appropriate times (i.e. when a
- * player enters a new room). Use this function to explicitly force the save data manager to reset a
- * specific variable group.
- *
- * For example:
- *
- * ```ts
- * const v = {
- *   room: {
- *     foo: 123,
- *   },
- * };
- *
- * saveDataManager("file1", v);
- *
- * // Then, later on, to explicit reset all of the "room" variables:
- * saveDataManagerReset("file1", "room");
- * ```
- */
-export function saveDataManagerReset(
-  key: string,
-  childObjectKey: SaveDataKey,
-): void {
-  errorIfFeaturesNotInitialized(SAVE_DATA_MANAGER_FEATURE_NAME);
-
-  if (!isString(key)) {
-    error(
-      `The ${SAVE_DATA_MANAGER_FEATURE_NAME} requires that keys are strings. You tried to use a key of type: ${typeof key}`,
-    );
-  }
-
-  const saveData = saveDataMap.get(key);
-  if (saveData === undefined) {
-    error(
-      `The ${SAVE_DATA_MANAGER_FEATURE_NAME} is not managing save data for a key of: ${key}`,
-    );
-  }
-
-  restoreDefaultSaveData(key, saveData, childObjectKey);
-}
-
-/**
- * Removes a previously registered key from the save data manager. This is the opposite of the
- * "saveDataManager" function.
- */
-export function saveDataManagerRemove(key: string): void {
-  errorIfFeaturesNotInitialized(SAVE_DATA_MANAGER_FEATURE_NAME);
-
-  if (!isString(key)) {
-    error(
-      `The ${SAVE_DATA_MANAGER_FEATURE_NAME} requires that keys are strings. You tried to use a key of type: ${typeof key}`,
-    );
-  }
-
-  if (!saveDataMap.has(key)) {
-    error(
-      `The ${SAVE_DATA_MANAGER_FEATURE_NAME} is not managing save data for a key of: ${key}`,
-    );
-  }
-
-  // Delete the save data from the map.
-  saveDataMap.delete(key);
-  saveDataDefaultsMap.delete(key);
-  saveDataConditionalFuncMap.delete(key);
-  saveDataGlowingHourGlassMap.delete(key);
-}
-
-/**
- * By default, the save data manager will not be able to serialize classes that are nested inside of
- * maps, sets, and arrays, because it does not have access to the corresponding class constructor.
- * If you want to use nested classes in this way, then use this function to register a class
- * constructor with the save data manager. If the save data manager finds a registered class of the
- * same name when deserializing, it will automatically run the registered constructor (in addition
- * to copying over the data fields).
- *
- * This function is variadic, which means you can pass as many classes as you want to register.
- */
-export function saveDataManagerRegisterClass(...tstlClasses: AnyClass[]): void {
-  for (const tstlClass of tstlClasses) {
-    const { name } = tstlClass;
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    if (name === undefined) {
-      error(
-        "Failed to register a class with the save data manager due to not being able to derive the name of the class.",
-      );
-    }
-
-    saveDataManagerClassConstructors.set(name, tstlClass);
-  }
-}