isaacscript-common 4.0.1-dev.0 → 4.0.4

package/features/preventCollectibleRotation.ts

@@ -1,115 +0,0 @@
-// 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

@@ -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/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/features/saveDataManager/exports.ts

@@ -1,229 +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 { 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

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