isaacscript-common 2.3.0 → 3.0.0

package/src/features/runInNFrames.ts

@@ -1,148 +0,0 @@
-import { ModCallback } from "isaac-typescript-definitions";
-import { game } from "../cachedClasses";
-import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
-import { saveDataManager } from "./saveDataManager/exports";
-
-const FEATURE_NAME = "run in N frames";
-
-/** The frame count to fire, paired with the corresponding function. */
-type FunctionTuple = [int, () => void];
-
-const v = {
-  run: {
-    queuedGameFunctionTuples: [] as FunctionTuple[],
-    queuedRenderFunctionTuples: [] as FunctionTuple[],
-  },
-};
-
-/** @internal */
-export function runInNFramesInit(mod: Mod): void {
-  saveDataManager("runInNFrames", v, () => false);
-
-  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);
-}
-
-// ModCallback.POST_RENDER (2)
-function postRender() {
-  const renderFrameCount = Isaac.GetFrameCount();
-
-  checkExecuteQueuedFunctions(
-    renderFrameCount,
-    v.run.queuedRenderFunctionTuples,
-  );
-}
-
-function checkExecuteQueuedFunctions(
-  frameCount: int,
-  functionTuples: FunctionTuple[],
-) {
-  const functionsToFire: Array<() => void> = [];
-  const indexesToRemove: int[] = [];
-  functionTuples.forEach((functionTuple, i) => {
-    const [frame, func] = functionTuple;
-    if (frameCount >= frame) {
-      functionsToFire.push(func);
-      indexesToRemove.push(i);
-    }
-  });
-
-  for (const indexToRemove of indexesToRemove) {
-    functionTuples.splice(indexToRemove, 1);
-  }
-
-  for (const func of functionsToFire) {
-    func();
-  }
-}
-
-/**
- * Supply a function to run N game frames from now in the PostUpdate 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: [int, () => void] = [functionFireFrame, func];
-  v.run.queuedGameFunctionTuples.push(tuple);
-}
-
-/**
- * Supply a function to run N render frames from now in the PostRender 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: [int, () => void] = [functionFireFrame, func];
-  v.run.queuedRenderFunctionTuples.push(tuple);
-}
-
-/**
- * Supply a function to run on the next PostUpdate 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 PostRender 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);
-}

package/src/features/saveDataManager/constants.ts

@@ -1,4 +0,0 @@
-/** Set this to true to enable more verbosity in the save data manger. */
-export const SAVE_DATA_MANAGER_DEBUG = false;
-
-export const SAVE_DATA_MANAGER_FEATURE_NAME = "save data manager";

package/src/features/saveDataManager/exports.ts

@@ -1,230 +0,0 @@
-/* eslint-disable sort-exports/sort-exports */
-
-import { SaveDataKey } from "../../enums/private/SaveDataKey";
-import { SerializationType } from "../../enums/SerializationType";
-import { errorIfFeaturesNotInitialized } from "../../featuresInitialized";
-import { deepCopy } from "../../functions/deepCopy";
-import { SaveData } from "../../interfaces/SaveData";
-import { SAVE_DATA_MANAGER_FEATURE_NAME } from "./constants";
-import {
-  forceSaveDataManagerLoad,
-  forceSaveDataManagerSave,
-  restoreDefaultSaveData,
-} from "./main";
-import {
-  saveDataConditionalFuncMap,
-  saveDataDefaultsMap,
-  saveDataMap,
-} from "./maps";
-
-/**
- * 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 anonymous 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.
- *
- * 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.)
- *
- * Finally, 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`.
- *
- * @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 An optional function to run upon saving this key to disk. For example,
- *                        this allows features to only save data to disk if the feature is enabled.
- *                        Specify a value of `() => false` to completely disable saving this feature
- *                        to disk. Disabling saving to disk is useful if you are using data that is
- *                        not serializable. Alternatively, it could be useful if you want to use the
- *                        save data manager to automatically reset variables on run/level/room, but
- *                        not clutter the the "save#.dat" file with unnecessary keys.
- */
-export function saveDataManager(
-  key: string,
-  v: SaveData,
-  conditionalFunc?: () => boolean,
-): void {
-  errorIfFeaturesNotInitialized(SAVE_DATA_MANAGER_FEATURE_NAME);
-
-  const keyType = type(key);
-  if (keyType !== "string") {
-    error(
-      `The ${SAVE_DATA_MANAGER_FEATURE_NAME} requires that keys are strings. You tried to use a key of type: ${keyType}`,
-    );
-  }
-
-  if (saveDataMap.has(key)) {
-    error(
-      `The ${SAVE_DATA_MANAGER_FEATURE_NAME} is already managing save data for a key of: ${key}`,
-    );
-  }
-
-  // Add the new save data to the map.
-  saveDataMap.set(key, v);
-
-  // 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 saveDataTable = v as LuaTable<AnyNotNil, unknown>;
-  const saveDataCopy = deepCopy(
-    saveDataTable,
-    SerializationType.NONE,
-    key,
-  ) as SaveData;
-  saveDataDefaultsMap.set(key, saveDataCopy);
-
-  // Store the conditional function for later, if present.
-  if (conditionalFunc !== undefined) {
-    saveDataConditionalFuncMap.set(key, conditionalFunc);
-  }
-}
-
-/**
- * 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();
-}
-
-declare let g: LuaTable<string, SaveData>; // Globals
-declare let gd: LuaTable<string, SaveData>; // Globals defaults
-
-/**
- * - 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 {
-  g = saveDataMap; // eslint-disable-line @typescript-eslint/no-unused-vars
-  gd = saveDataDefaultsMap; // eslint-disable-line @typescript-eslint/no-unused-vars
-}
-
-/**
- * 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: string,
-): void {
-  errorIfFeaturesNotInitialized(SAVE_DATA_MANAGER_FEATURE_NAME);
-
-  const keyType = type(key);
-  if (keyType !== "string") {
-    error(
-      `The ${SAVE_DATA_MANAGER_FEATURE_NAME} requires that keys are strings. You tried to use a key of type: ${keyType}`,
-    );
-  }
-
-  const saveData = saveDataMap.get(key) as Record<string, unknown> | undefined;
-  if (saveData === undefined) {
-    error(
-      `The ${SAVE_DATA_MANAGER_FEATURE_NAME} is not managing save data for a key of: ${key}`,
-    );
-  }
-
-  restoreDefaultSaveData(key, saveData, childObjectKey as SaveDataKey);
-}

package/src/features/saveDataManager/load.ts

@@ -1,90 +0,0 @@
-import { jsonDecode } from "../../functions/jsonHelpers";
-import { log, logError } from "../../functions/log";
-import { SaveData } from "../../interfaces/SaveData";
-import {
-  SAVE_DATA_MANAGER_DEBUG,
-  SAVE_DATA_MANAGER_FEATURE_NAME,
-} from "./constants";
-import { merge } from "./merge";
-
-const DEFAULT_MOD_DATA = "{}";
-
-export function loadFromDisk(
-  mod: Mod,
-  oldSaveData: LuaTable<string, SaveData>,
-): void {
-  if (!mod.HasData()) {
-    // There is no "save#.dat" file for this save slot.
-    return;
-  }
-
-  // First, read the "save#.dat" file into a Lua table.
-  const jsonString = readSaveDatFile(mod);
-  const newSaveData = jsonDecode(jsonString);
-
-  if (SAVE_DATA_MANAGER_DEBUG) {
-    log('Converted data from the "save#.dat" to a Lua table.');
-  }
-
-  // Second, iterate over all the fields of the new table.
-  for (const [key, value] of pairs(newSaveData)) {
-    // All elements of loaded save data should have keys that are strings equal to the name of the
-    // subscriber/feature. Ignore elements with other types of keys.
-    if (typeof key !== "string") {
-      continue;
-    }
-
-    // All elements of loaded save data should be tables that contain fields corresponding to the
-    // SaveData interface. Ignore elements that are not tables.
-    const valueType = type(value);
-    if (valueType !== "table") {
-      continue;
-    }
-
-    // Ignore elements that represent subscriptions that no longer exist in the current save data.
-    const oldSaveDataForSubscriber = oldSaveData.get(key);
-    if (oldSaveDataForSubscriber === undefined) {
-      continue;
-    }
-
-    if (SAVE_DATA_MANAGER_DEBUG) {
-      log(`Merging in stored data for feature: ${key}`);
-    }
-
-    // We do not want to blow away the child tables of the existing map, because save data could
-    // contain out-of-date fields. Instead, merge it one field at a time in a recursive way (and
-    // convert Lua tables back to TypeScriptToLua Maps, if necessary).
-    merge(oldSaveDataForSubscriber as LuaTable, value as LuaTable, key);
-  }
-
-  log(
-    `The ${SAVE_DATA_MANAGER_FEATURE_NAME} loaded data from the "save#.dat" file.`,
-  );
-}
-
-function readSaveDatFile(mod: Mod) {
-  const renderFrameCount = Isaac.GetFrameCount();
-
-  const [ok, jsonStringOrErrMsg] = pcall(tryLoadModData, mod);
-  if (!ok) {
-    logError(
-      `Failed to read from the "save#.dat" file on render frame ${renderFrameCount}: ${jsonStringOrErrMsg}`,
-    );
-    return DEFAULT_MOD_DATA;
-  }
-
-  if (jsonStringOrErrMsg === undefined) {
-    return DEFAULT_MOD_DATA;
-  }
-
-  const jsonStringTrimmed = jsonStringOrErrMsg.trim();
-  if (jsonStringTrimmed === "") {
-    return DEFAULT_MOD_DATA;
-  }
-
-  return jsonStringTrimmed;
-}
-
-function tryLoadModData(this: void, mod: Mod) {
-  return mod.LoadData();
-}

package/src/features/saveDataManager/main.ts

@@ -1,187 +0,0 @@
-/* eslint-disable sort-exports/sort-exports */
-
-import { ModCallback } from "isaac-typescript-definitions";
-import { game } from "../../cachedClasses";
-import { ModUpgraded } from "../../classes/ModUpgraded";
-import { ModCallbackCustom } from "../../enums/ModCallbackCustom";
-import {
-  RESETTABLE_SAVE_DATA_KEYS,
-  SaveDataKey,
-} from "../../enums/private/SaveDataKey";
-import { SerializationType } from "../../enums/SerializationType";
-import { deepCopy } from "../../functions/deepCopy";
-import { logError } from "../../functions/log";
-import { clearTable } from "../../functions/table";
-import { SaveData } from "../../interfaces/SaveData";
-import { SAVE_DATA_MANAGER_FEATURE_NAME } from "./constants";
-import { loadFromDisk } from "./load";
-import {
-  saveDataConditionalFuncMap,
-  saveDataDefaultsMap,
-  saveDataMap,
-} from "./maps";
-import { saveToDisk } from "./save";
-
-let mod: ModUpgraded | null = null;
-let loadedDataOnThisRun = false;
-
-/** @internal */
-export function saveDataManagerInit(incomingMod: ModUpgraded): void {
-  mod = incomingMod;
-
-  mod.AddCallback(ModCallback.POST_PLAYER_INIT, postPlayerInit); // 9
-  mod.AddCallback(ModCallback.PRE_GAME_EXIT, preGameExit); // 17
-  mod.AddCallback(ModCallback.POST_NEW_LEVEL, postNewLevel); // 18
-  mod.AddCallbackCustom(
-    ModCallbackCustom.POST_NEW_ROOM_EARLY,
-    postNewRoomEarly,
-  ); // 19
-}
-
-// ModCallback.POST_PLAYER_INIT (9)
-function postPlayerInit() {
-  if (mod === null) {
-    error(
-      `The mod for the ${SAVE_DATA_MANAGER_FEATURE_NAME} was not initialized.`,
-    );
-  }
-
-  if (loadedDataOnThisRun) {
-    return;
-  }
-  loadedDataOnThisRun = true;
-
-  // We want to unconditionally load save data on every new run since there might be persistent data
-  // that is not tied to an individual run.
-  loadFromDisk(mod, saveDataMap);
-
-  const gameFrameCount = game.GetFrameCount();
-  const isContinued = gameFrameCount !== 0;
-  if (!isContinued) {
-    restoreDefaultsAll();
-  }
-
-  // On continued runs, the PostNewLevel callback will not fire, so we do not have to worry about
-  // saved data based on level getting overwritten.
-}
-
-// ModCallback.PRE_GAME_EXIT (17)
-function preGameExit() {
-  if (mod === null) {
-    error(
-      `The mod for the ${SAVE_DATA_MANAGER_FEATURE_NAME} was not initialized.`,
-    );
-  }
-
-  // We unconditionally save variables to disk (because regardless of a save & quit or a death,
-  // persistent variables should be recorded).
-  saveToDisk(mod, saveDataMap, saveDataConditionalFuncMap);
-
-  restoreDefaultsAll();
-  loadedDataOnThisRun = false;
-}
-
-// ModCallback.POST_NEW_LEVEL (18)
-function postNewLevel() {
-  restoreDefaults(SaveDataKey.LEVEL);
-}
-
-// ModCallbackCustom.POST_NEW_ROOM_EARLY
-function postNewRoomEarly() {
-  restoreDefaults(SaveDataKey.ROOM);
-}
-
-function restoreDefaultsAll() {
-  restoreDefaults(SaveDataKey.RUN);
-  restoreDefaults(SaveDataKey.LEVEL);
-  restoreDefaults(SaveDataKey.ROOM);
-}
-
-function restoreDefaults(saveDataKey: SaveDataKey) {
-  for (const [subscriberName, saveData] of pairs(saveDataMap)) {
-    restoreDefaultSaveData(subscriberName, saveData, saveDataKey);
-  }
-}
-
-export function restoreDefaultSaveData(
-  subscriberName: string,
-  saveData: SaveData,
-  saveDataKey: SaveDataKey,
-): void {
-  // Only allow certain save data keys to be reset.
-  if (!RESETTABLE_SAVE_DATA_KEYS.has(saveDataKey)) {
-    error(`Unknown save data key name of: ${saveDataKey}`);
-  }
-
-  const childTable = saveData[saveDataKey];
-  if (childTable === undefined) {
-    // This feature does not happen to store any variables on this particular child table.
-    return;
-  }
-
-  // Get the default values for this feature.
-  const saveDataDefaults = saveDataDefaultsMap.get(subscriberName);
-  if (saveDataDefaults === undefined) {
-    logError(
-      `Failed to find the default copy of the save data for subscriber: ${subscriberName}`,
-    );
-    return;
-  }
-
-  // Get the default values for the specific sub-table of this feature.
-  const childTableDefaults = saveDataDefaults[saveDataKey];
-  if (childTableDefaults === undefined) {
-    logError(
-      `Failed to find the default copy of the child table "${saveDataKey}" for subscriber "${subscriberName}". This error usually means that your save data is out of date. You can try purging all of your save data by deleting the following directory: C:\\Program Files (x86)\\Steam\\steamapps\\common\\The Binding of Isaac Rebirth\\data`,
-    );
-    return;
-  }
-
-  // Make a new copy of the default child table.
-  const childTableDefaultsCopy = deepCopy(
-    childTableDefaults,
-    SerializationType.NONE,
-    `${subscriberName} --> ${saveDataKey}`,
-  ) as LuaTable<AnyNotNil, unknown>;
-
-  // We do not want to blow away the existing child table because we don't want to break any
-  // existing references. Instead, empty the table and copy all of the elements from the copy of the
-  // defaults table.
-  clearAndCopyAllElements(
-    childTable as unknown as LuaTable,
-    childTableDefaultsCopy,
-  );
-}
-
-/**
- * Will empty the old table of all elements, and then shallow copy all the elements from the new
- * table to the old table.
- */
-function clearAndCopyAllElements(
-  oldTable: LuaTable<AnyNotNil, unknown>,
-  newTable: LuaTable<AnyNotNil, unknown>,
-) {
-  clearTable(oldTable);
-
-  for (const [key, value] of pairs(newTable)) {
-    oldTable.set(key, value);
-  }
-}
-
-/** @internal */
-export function forceSaveDataManagerSave(): void {
-  if (mod === null) {
-    return;
-  }
-
-  saveToDisk(mod, saveDataMap, saveDataConditionalFuncMap);
-}
-
-/** @internal */
-export function forceSaveDataManagerLoad(): void {
-  if (mod === null) {
-    return;
-  }
-
-  loadFromDisk(mod, saveDataMap);
-}

package/src/features/saveDataManager/maps.ts

@@ -1,13 +0,0 @@
-/* eslint-disable sort-exports/sort-exports */
-
-import { SaveData } from "../../interfaces/SaveData";
-
-/**
- * The save data map is indexed by subscriber name. We use Lua tables instead of TypeScriptToLua
- * Maps for the master map so that we can access the variables via the in-game console when
- * debugging. (TSTL Maps don't expose the map keys as normal keys.)
- */
-export const saveDataMap = new LuaTable<string, SaveData>();
-
-export const saveDataDefaultsMap = new LuaTable<string, SaveData>();
-export const saveDataConditionalFuncMap = new Map<string, () => boolean>();