isaacscript-common 4.0.2 → 4.0.5

package/features/saveDataManager/main.ts

@@ -1,195 +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, iterateTableInOrder } from "../../functions/table";
-import { SaveData } from "../../interfaces/SaveData";
-import {
-  SAVE_DATA_MANAGER_DEBUG,
-  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) {
-  iterateTableInOrder(
-    saveDataMap,
-    (subscriberName, saveData) => {
-      restoreDefaultSaveData(subscriberName, saveData, saveDataKey);
-    },
-    SAVE_DATA_MANAGER_DEBUG,
-  );
-}
-
-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);
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-  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/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>();

package/features/saveDataManager/merge.ts

@@ -1,194 +0,0 @@
-import { SerializationBrand } from "../../enums/private/SerializationBrand";
-import { SerializationType } from "../../enums/SerializationType";
-import { isArray } from "../../functions/array";
-import { deepCopy } from "../../functions/deepCopy";
-import { log } from "../../functions/log";
-import {
-  deserializeIsaacAPIClass,
-  isSerializedIsaacAPIClass,
-} from "../../functions/serialization";
-import { clearTable, iterateTableInOrder } from "../../functions/table";
-import { isTSTLMap, isTSTLSet } from "../../functions/tstlClass";
-import { isTable } from "../../functions/types";
-import { getTraversalDescription } from "../../functions/utils";
-import { SAVE_DATA_MANAGER_DEBUG } from "./constants";
-import { isSerializationBrand } from "./serializationBrand";
-
-/**
- * `merge` takes the values from a new table and recursively merges them into an old object (while
- * performing appropriate deserialization).
- *
- * It supports the following object types:
- *
- * - `LuaTable` / basic TSTL objects
- * - TSTL `Map`
- * - TSTL `Set`
- * - TSTL classes
- * - `DefaultMap`
- * - Isaac `Color` objects
- * - Isaac `KColor` objects
- * - Isaac `RNG` objects
- * - Isaac `Vector` objects
- *
- * Since it is common for a variable to have a type of `something | null`, we must iterate over the
- * new object and copy over all of the values. (A value of null transpiles to nil, which means the
- * table key does not exist.) The consequence of this is that it can copy over old variables that
- * are no longer used in the code, or copy over old variables of a different type, which can cause
- * run-time errors. In such cases, users will have to manually delete their save data.
- */
-export function merge(
-  oldObject:
-    | LuaTable<AnyNotNil, unknown>
-    | Map<AnyNotNil, unknown>
-    | Set<AnyNotNil>,
-  newTable: LuaTable<AnyNotNil, unknown>,
-  traversalDescription: string,
-): void {
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-  if (SAVE_DATA_MANAGER_DEBUG) {
-    log(`merge is traversing: ${traversalDescription}`);
-  }
-
-  if (!isTable(oldObject)) {
-    error("The first argument given to the merge function is not a table.");
-  }
-
-  if (!isTable(newTable)) {
-    error("The second argument given to the merge function is not a table.");
-  }
-
-  // First, handle the special case of an array with a shallow copy.
-  if (isArray(oldObject) && isArray(newTable)) {
-    mergeArray(oldObject, newTable);
-    return;
-  }
-
-  // Depending on whether we are working on a Lua table or a TypeScriptToLua object, we need to
-  // iterate in a specific way.
-  if (isTSTLMap(oldObject) || isTSTLSet(oldObject)) {
-    mergeTSTLObject(oldObject, newTable, traversalDescription);
-  } else {
-    mergeTable(oldObject, newTable, traversalDescription);
-  }
-}
-
-function mergeArray(
-  oldArray: LuaTable<AnyNotNil, unknown>,
-  newArray: LuaTable<AnyNotNil, unknown>,
-) {
-  // Assume that we should blow away all array values with whatever is present in the incoming
-  // array.
-  clearTable(oldArray);
-  iterateTableInOrder(
-    newArray,
-    (key, value) => {
-      oldArray.set(key, value);
-    },
-    SAVE_DATA_MANAGER_DEBUG,
-  );
-}
-
-function mergeTSTLObject(
-  oldObject: Map<AnyNotNil, unknown> | Set<AnyNotNil>,
-  newTable: LuaTable<AnyNotNil, unknown>,
-  traversalDescription: string,
-) {
-  // We blow away the old object and recursively copy over all of the incoming values.
-  oldObject.clear();
-
-  // During serialization, we brand some Lua tables with a special identifier to signify that it has
-  // keys that should be deserialized to numbers.
-  const convertStringKeysToNumbers = newTable.has(
-    SerializationBrand.OBJECT_WITH_NUMBER_KEYS,
-  );
-
-  iterateTableInOrder(
-    newTable,
-    (key, value) => {
-      if (isSerializationBrand(key)) {
-        return;
-      }
-
-      let keyToUse = key;
-      if (convertStringKeysToNumbers) {
-        const numberKey = tonumber(key);
-        if (numberKey === undefined) {
-          return;
-        }
-        keyToUse = numberKey;
-      }
-
-      if (isTSTLMap(oldObject)) {
-        let valueCopy: unknown;
-        if (isTable(value)) {
-          valueCopy = deepCopy(
-            value,
-            SerializationType.DESERIALIZE,
-            traversalDescription,
-          );
-        } else {
-          valueCopy = value;
-        }
-
-        oldObject.set(keyToUse, valueCopy);
-      } else if (isTSTLSet(oldObject)) {
-        oldObject.add(keyToUse);
-      }
-    },
-    SAVE_DATA_MANAGER_DEBUG,
-  );
-}
-
-function mergeTable(
-  oldTable: LuaTable<AnyNotNil, unknown>,
-  newTable: LuaTable<AnyNotNil, unknown>,
-  traversalDescription: string,
-) {
-  iterateTableInOrder(
-    newTable,
-    (key, value) => {
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-      if (SAVE_DATA_MANAGER_DEBUG) {
-        const valueToPrint = value === "" ? "(empty string)" : `${value}`;
-        log(`merge is merging: ${traversalDescription} --> ${valueToPrint}`);
-      }
-
-      if (isSerializationBrand(key)) {
-        return;
-      }
-
-      // Handle the special case of serialized Isaac API classes.
-      if (isSerializedIsaacAPIClass(value)) {
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        if (SAVE_DATA_MANAGER_DEBUG) {
-          log("merge found a serialized Isaac API class.");
-        }
-
-        const deserializedObject = deserializeIsaacAPIClass(value);
-        oldTable.set(key, deserializedObject);
-        return;
-      }
-
-      if (isTable(value)) {
-        let oldValue = oldTable.get(key) as LuaTable<AnyNotNil, unknown>;
-        if (!isTable(oldValue)) {
-          // The child table does not exist on the old table. However, we still need to copy over
-          // the new table, because we need to handle data types like "Foo | null". Thus, set up a
-          // blank sub-table on the old table, and continue to recursively merge..
-          oldValue = new LuaTable();
-          oldTable.set(key, oldValue);
-        }
-
-        traversalDescription = getTraversalDescription(
-          key,
-          traversalDescription,
-        );
-        merge(oldValue, value, traversalDescription);
-      } else {
-        // Base case: copy the value
-        oldTable.set(key, value);
-      }
-    },
-    SAVE_DATA_MANAGER_DEBUG,
-  );
-}

package/features/saveDataManager/save.ts

@@ -1,74 +0,0 @@
-import { SerializationType } from "../../enums/SerializationType";
-import { deepCopy } from "../../functions/deepCopy";
-import { jsonEncode } from "../../functions/jsonHelpers";
-import { log } from "../../functions/log";
-import { iterateTableInOrder } from "../../functions/table";
-import { SaveData } from "../../interfaces/SaveData";
-import {
-  SAVE_DATA_MANAGER_DEBUG,
-  SAVE_DATA_MANAGER_FEATURE_NAME,
-} from "./constants";
-
-export function saveToDisk(
-  mod: Mod,
-  saveDataMap: LuaTable<string, SaveData>,
-  saveDataConditionalFuncMap: Map<string, () => boolean>,
-): void {
-  const allSaveData = getAllSaveDataToWriteToDisk(
-    saveDataMap,
-    saveDataConditionalFuncMap,
-  );
-  const jsonString = jsonEncode(allSaveData);
-  mod.SaveData(jsonString); // Write it to the "save#.dat" file
-  log(
-    `The ${SAVE_DATA_MANAGER_FEATURE_NAME} wrote data to the "save#.dat" file.`,
-  );
-}
-
-function getAllSaveDataToWriteToDisk(
-  saveDataMap: LuaTable<string, SaveData>,
-  saveDataConditionalFuncMap: Map<string, () => boolean>,
-) {
-  const allSaveData = new LuaTable<AnyNotNil, unknown>();
-
-  iterateTableInOrder(
-    saveDataMap,
-    (subscriberName, saveData) => {
-      // Handle the feature of the save data manager where certain mod features can conditionally
-      // write their data to disk.
-      const conditionalFunc = saveDataConditionalFuncMap.get(subscriberName);
-      if (conditionalFunc !== undefined) {
-        const shouldSave = conditionalFunc();
-        if (!shouldSave) {
-          return;
-        }
-      }
-
-      // Strip out the room part of the save data.
-      const saveDataWithoutRoom: SaveData = {
-        persistent: saveData.persistent,
-        run: saveData.run,
-        level: saveData.level,
-      };
-
-      // If there is no data, then we can move on to the next feature.
-      if (Object.keys(saveDataWithoutRoom).length === 0) {
-        return;
-      }
-
-      // If we encode TypeScriptToLua Maps into JSON, it will result in a lot of extraneous data
-      // that is unnecessary. Make a copy of the data and recursively convert all TypeScriptToLua
-      // Maps into Lua tables.
-      const saveDataCopy = deepCopy(
-        saveDataWithoutRoom as LuaTable,
-        SerializationType.SERIALIZE,
-        subscriberName,
-      );
-
-      allSaveData.set(subscriberName, saveDataCopy);
-    },
-    SAVE_DATA_MANAGER_DEBUG,
-  );
-
-  return allSaveData;
-}

package/features/saveDataManager/serializationBrand.ts

@@ -1,16 +0,0 @@
-import { SerializationBrand } from "../../enums/private/SerializationBrand";
-import { getEnumValues } from "../../functions/enums";
-import { isString } from "../../functions/types";
-
-const SERIALIZATION_BRANDS = getEnumValues(SerializationBrand);
-const SERIALIZATION_BRAND_SET: ReadonlySet<string> = new Set(
-  SERIALIZATION_BRANDS,
-);
-
-export function isSerializationBrand(key: unknown): boolean {
-  if (!isString(key)) {
-    return false;
-  }
-
-  return SERIALIZATION_BRAND_SET.has(key);
-}

package/features/sirenHelpers.ts

@@ -1,129 +0,0 @@
-import {
-  EntityType,
-  FamiliarVariant,
-  ModCallback,
-} from "isaac-typescript-definitions";
-import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
-import { getEntities } from "../functions/entity";
-import { saveDataManager } from "./saveDataManager/exports";
-
-const FEATURE_NAME = "siren helpers";
-
-const v = {
-  run: {
-    familiarBlacklist: [] as Array<
-      [variant: FamiliarVariant, subType: int | undefined]
-    >,
-  },
-};
-
-/** @internal */
-export function sirenHelpersInit(mod: Mod): void {
-  saveDataManager("sirenHelpers", v);
-
-  mod.AddCallback(
-    ModCallback.POST_NPC_INIT,
-    postNPCInitSirenHelper,
-    EntityType.SIREN_HELPER,
-  );
-}
-
-// ModCallback.POST_NPC_INIT (27)
-// EntityType.SIREN_HELPER (966)
-function postNPCInitSirenHelper(npc: EntityNPC) {
-  checkReturnFamiliarToPlayer(npc);
-}
-
-function checkReturnFamiliarToPlayer(npc: EntityNPC) {
-  if (npc.Target === undefined) {
-    return;
-  }
-
-  const familiar = npc.Target.ToFamiliar();
-  if (familiar === undefined) {
-    return;
-  }
-
-  if (blacklistEntryExists(familiar.Variant, familiar.SubType)) {
-    npc.Remove();
-    familiar.AddToFollowers();
-  }
-}
-
-function blacklistEntryExists(
-  incomingFamiliarVariant: FamiliarVariant,
-  incomingFamiliarSubType: int | undefined,
-): boolean {
-  for (const [familiarVariant, familiarSubType] of v.run.familiarBlacklist) {
-    if (
-      incomingFamiliarVariant === familiarVariant &&
-      familiarSubType === incomingFamiliarSubType
-    ) {
-      // There is an entry that matches the variant and sub-type exactly.
-      return true;
-    }
-
-    if (
-      incomingFamiliarVariant === familiarVariant &&
-      familiarSubType === undefined
-    ) {
-      // There is an entry that matches all sub-types for this variant.
-      return true;
-    }
-  }
-
-  return false;
-}
-
-/**
- * Blacklists a familiar from being stolen by The Siren boss. This should be called once at the
- * beginning of every run.
- *
- * @param familiarVariant The familiar variant to blacklist.
- * @param familiarSubType The sub-type to blacklist. Optional. The default is to blacklist all
- *                        sub-types of the given variant.
- */
-export function setFamiliarNoSirenSteal(
-  familiarVariant: FamiliarVariant,
-  familiarSubType?: int,
-): void {
-  errorIfFeaturesNotInitialized(FEATURE_NAME);
-
-  if (blacklistEntryExists(familiarVariant, familiarSubType)) {
-    return;
-  }
-
-  v.run.familiarBlacklist.push([familiarVariant, familiarSubType]);
-}
-
-/**
- * Helper function to check if the Siren boss has stolen a familiar. Some familiars may need to
- * behave differently when under The Siren's control (e.g. if they auto-target enemies).
- *
- * @param familiar The familiar to be checked.
- * @returns Returns whether the familiar has been stolen by The Siren.
- */
-export function hasSirenStolenFamiliar(familiar: EntityFamiliar): boolean {
-  errorIfFeaturesNotInitialized(FEATURE_NAME);
-  return getSirenHelper(familiar) !== undefined;
-}
-
-/**
- * When The Siren boss "steals" your familiars, a hidden "Siren Helper" entity is spawned to control
- * each familiar stolen. (Checking for this entity seems to be the only way to detect when the Siren
- * steals a familiar.)
- *
- * @param familiar The familiar to be checked.
- * @returns Returns the hidden "Siren Helper" entity corresponding to the given familiar, if it
- *          exists. Returns undefined otherwise.
- */
-function getSirenHelper(familiar: EntityFamiliar): Entity | undefined {
-  const familiarPtrHash = GetPtrHash(familiar);
-
-  const sirenHelpers = getEntities(EntityType.SIREN_HELPER);
-  return sirenHelpers.find(
-    (sirenHelper) =>
-      sirenHelper.Target !== undefined &&
-      GetPtrHash(sirenHelper.Target) === familiarPtrHash,
-  );
-}