isaacscript-common 4.0.0 → 4.0.3

package/features/saveDataManager/main.ts

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

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

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

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

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

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