isaacscript-common 4.0.0 → 4.0.3

package/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 = "prevent collectible rotation";
+
+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("preventCollectibleRotation", 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/features/runInNFrames.ts

@@ -0,0 +1,148 @@
+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/features/saveDataManager/constants.ts

@@ -0,0 +1,4 @@
+/** 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/features/saveDataManager/exports.ts

@@ -0,0 +1,229 @@
+/* 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 { isString } from "../../functions/types";
+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);
+
+  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}`,
+    );
+  }
+
+  // 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);
+
+  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) 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/features/saveDataManager/load.ts

@@ -0,0 +1,99 @@
+import { jsonDecode } from "../../functions/jsonHelpers";
+import { log, logError } from "../../functions/log";
+import { iterateTableInOrder } from "../../functions/table";
+import { isString, isTable } from "../../functions/types";
+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);
+
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  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.)
+  iterateTableInOrder(
+    newSaveData,
+    (key, value) => {
+      // 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 (!isString(key)) {
+        return;
+      }
+
+      // All elements of loaded save data should be tables that contain fields corresponding to the
+      // SaveData interface. Ignore elements that are not tables.
+      if (!isTable(value)) {
+        return;
+      }
+
+      // Ignore elements that represent subscriptions that no longer exist in the current save data.
+      const oldSaveDataForSubscriber = oldSaveData.get(key);
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      if (oldSaveDataForSubscriber === undefined) {
+        return;
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      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, key);
+    },
+    SAVE_DATA_MANAGER_DEBUG,
+  );
+
+  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;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  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();
+}