isaacscript-common 14.1.3 → 15.0.0

package/src/functions/logMisc.ts

@@ -13,7 +13,7 @@ import {
   UseFlag,
 } from "isaac-typescript-definitions";
 import { game, sfxManager } from "../core/cachedClasses";
-import { arrayToString } from "./array";
+import { arrayToString, isArray } from "./array";
 import { getCollectibleName } from "./collectibles";
 import { getEntityID } from "./entities";
 import { getEnumEntries } from "./enums";
@@ -26,11 +26,17 @@ import { getRoomData, getRoomGridIndex, getRoomListIndex } from "./roomData";
 import { combineSets, getSortedSetValues } from "./set";
 import { iterateTableInOrder } from "./table";
 import { getTrinketName } from "./trinkets";
+import { isDefaultMap, isTSTLMap, isTSTLSet } from "./tstlClass";
 import { isTable, isUserdata } from "./types";
 import { printConsole } from "./utils";
 import { vectorToString } from "./vector";
 
 export function logArray<T>(array: T[] | readonly T[]): void {
+  if (!isArray(array)) {
+    log("Tried to log an array, but the given object was not an array.");
+    return;
+  }
+
   const arrayString = arrayToString(array);
   log(`Array: ${arrayString}`);
 }
@@ -157,7 +163,12 @@ export function logLevelStateFlags(): void {
 }
 
 export function logMap(map: Map<AnyNotNil, unknown>): void {
-  log("Printing out a TSTL Map:");
+  if (!isTSTLMap(map) && !isDefaultMap(map)) {
+    log("Tried to log a TSTL map, but the given object was not a TSTL map.");
+    return;
+  }
+
+  log("Printing out a TSTL map:");
 
   const mapKeys = [...map.keys()];
   mapKeys.sort();
@@ -284,7 +295,12 @@ export function logSeedEffects(): void {
 }
 
 export function logSet(set: Set<AnyNotNil> | ReadonlySet<AnyNotNil>): void {
-  log("Printing out a TSTL Set:");
+  if (!isTSTLSet(set)) {
+    log("Tried to log a TSTL set, but the given object was not a TSTL set.");
+    return;
+  }
+
+  log("Printing out a TSTL set:");
 
   const setValues = getSortedSetValues(set);
   for (const value of setValues) {

package/src/functions/merge.ts

@@ -0,0 +1,239 @@
+import { SAVE_DATA_MANAGER_DEBUG } from "../classes/features/other/saveDataManager/constants";
+import { SerializationBrand } from "../enums/SerializationBrand";
+import { SerializationType } from "../enums/SerializationType";
+import { AnyClass } from "../types/AnyClass";
+import { isArray } from "./array";
+import { deepCopy } from "./deepCopy";
+import { log } from "./log";
+import {
+  deserializeIsaacAPIClass,
+  isSerializationBrand,
+  isSerializedIsaacAPIClass,
+} from "./serialization";
+import { clearTable, iterateTableInOrder } from "./table";
+import { isDefaultMap, isTSTLMap, isTSTLSet } from "./tstlClass";
+import { isTable } from "./types";
+import { getTraversalDescription } from "./utils";
+
+/**
+ * `merge` takes the values from a new table and recursively merges them into an old object (while
+ * performing appropriate deserialization).
+ *
+ * This function is used to merge incoming data from the "save#.dat" file into a mod's variables.
+ * Merging is useful instead of blowing away a table entirely because mod code often relies on the
+ * local table/object references.
+ *
+ * This function always assumes that the new table is serialized data and will attempt to perform
+ * deserialization on the objects within. In other words, unlike the `deepCopy` function, the
+ * `merge` function will always operates in the mode of `SerializationType.DESERIALIZE`. For the
+ * types of objects that will be deserialized, see the documentation for the `deepCopy` function.
+ *
+ * This function does not iterate over the old object, like you would naively expect. This is
+ * because it is common for a variable to have a type of `something | null`. If this is the case,
+ * the key would not appear when iterating over the old object (because a value of null transpiles
+ * to nil, which means the table key does not exist). Thus, we must instead iterate over the new
+ * object and copy the values backwards. The consequence of this is that `merge` 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.
+ *
+ * @param oldObject The old object to merge the values into. This can be either a Lua table, a TSTL
+ *                  map, or a TSTL set.
+ * @param newTable The new table to merge the values from. This must be a Lua table that represents
+ *                 serialized data. In other words, it should be created with the `deepCopy`
+ *                 function using `SerializationType.SERIALIZE`.
+ * @param traversalDescription Used to track the current key that we are operating on for debugging
+ *                             purposes. Use a name that corresponds to the name of the merging
+ *                             table.
+ * @param classConstructors Optional. A Lua table that maps the name of a user-defined TSTL class to
+ *                          its corresponding constructor. If the `deepCopy` function finds any
+ *                          user-defined TSTL classes when recursively iterating through the given
+ *                          object, it will use this map to instantiate a new class. Default is an
+ *                          empty Lua table.
+ */
+export function merge(
+  oldObject:
+    | LuaMap<AnyNotNil, unknown>
+    | Map<AnyNotNil, unknown>
+    | Set<AnyNotNil>,
+  newTable: LuaMap<AnyNotNil, unknown>,
+  traversalDescription: string,
+  classConstructors = new LuaMap<string, AnyClass>(),
+): void {
+  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)) {
+    mergeSerializedArray(
+      oldObject,
+      newTable,
+      traversalDescription,
+      classConstructors,
+    );
+    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) || isDefaultMap(oldObject)) {
+    mergeSerializedTSTLObject(
+      oldObject,
+      newTable,
+      traversalDescription,
+      classConstructors,
+    );
+  } else {
+    mergeSerializedTable(
+      oldObject,
+      newTable,
+      traversalDescription,
+      classConstructors,
+    );
+  }
+}
+
+function mergeSerializedArray(
+  oldArray: LuaMap<AnyNotNil, unknown>,
+  newArray: LuaMap<AnyNotNil, unknown>,
+  traversalDescription: string,
+  classConstructors: LuaMap<string, AnyClass>,
+) {
+  if (SAVE_DATA_MANAGER_DEBUG) {
+    log(`merge encountered an array: ${traversalDescription}`);
+  }
+
+  // Assume that we should blow away all array values with whatever is present in the incoming
+  // array.
+  clearTable(oldArray);
+  iterateTableInOrder(
+    newArray,
+    (key, value) => {
+      const deserializedValue = deepCopy(
+        value,
+        SerializationType.DESERIALIZE,
+        traversalDescription,
+        classConstructors,
+      );
+      oldArray.set(key, deserializedValue);
+    },
+    SAVE_DATA_MANAGER_DEBUG,
+  );
+}
+
+function mergeSerializedTSTLObject(
+  oldObject: Map<AnyNotNil, unknown> | Set<AnyNotNil>,
+  newTable: LuaMap<AnyNotNil, unknown>,
+  traversalDescription: string,
+  classConstructors: LuaMap<string, AnyClass>,
+) {
+  if (SAVE_DATA_MANAGER_DEBUG) {
+    log(`merge encountered a TSTL object: ${traversalDescription}`);
+  }
+
+  // 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) || isDefaultMap(oldObject)) {
+        const deserializedValue = deepCopy(
+          value,
+          SerializationType.DESERIALIZE,
+          traversalDescription,
+          classConstructors,
+        );
+        oldObject.set(keyToUse, deserializedValue);
+      } else if (isTSTLSet(oldObject)) {
+        oldObject.add(keyToUse);
+      }
+    },
+    SAVE_DATA_MANAGER_DEBUG,
+  );
+}
+
+function mergeSerializedTable(
+  oldTable: LuaMap<AnyNotNil, unknown>,
+  newTable: LuaMap<AnyNotNil, unknown>,
+  traversalDescription: string,
+  classConstructors: LuaMap<string, AnyClass>,
+) {
+  if (SAVE_DATA_MANAGER_DEBUG) {
+    log(`merge encountered a Lua table: ${traversalDescription}`);
+  }
+
+  iterateTableInOrder(
+    newTable,
+    (key, value) => {
+      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)) {
+        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 LuaMap<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 LuaMap();
+          oldTable.set(key, oldValue);
+        }
+
+        traversalDescription = getTraversalDescription(
+          key,
+          traversalDescription,
+        );
+        merge(oldValue, value, traversalDescription, classConstructors);
+      } else {
+        // Base case: copy the value
+        oldTable.set(key, value);
+      }
+    },
+    SAVE_DATA_MANAGER_DEBUG,
+  );
+}

package/src/functions/mergeTests.ts

@@ -1,16 +1,15 @@
 import { DefaultMap } from "../classes/DefaultMap";
 import { SerializationType } from "../enums/SerializationType";
-import { merge } from "../features/saveDataManager/merge";
 import { deepCopy } from "./deepCopy";
 import { log } from "./log";
+import { merge } from "./merge";
 import { isRNG, newRNG } from "./rng";
 import { isSerializedIsaacAPIClass } from "./serialization";
 import { printConsole } from "./utils";
 import { isVector, serializeVector } from "./vector";
 
 /**
- * Run the suite of tests that prove that the "merge" function works properly. (This function is not
- * exported but is used internally in the save data manager.)
+ * Run the suite of tests that prove that the "merge" function works properly.
  *
  * This function is only useful if you are troubleshooting the save data manager.
  */

package/src/functions/nextStage.ts

@@ -5,8 +5,6 @@ import {
   StageType,
 } from "isaac-typescript-definitions";
 import { game } from "../core/cachedClasses";
-import { hasVisitedStage } from "../features/stageHistory";
-import { areFeaturesInitialized } from "../featuresInitialized";
 import { getRoomGridIndex } from "./roomData";
 import {
   calculateStageType,
@@ -19,9 +17,9 @@ import { asNumber } from "./types";
  * Helper function to get the stage that a trapdoor or heaven door would take the player to, based
  * on the current stage, room, and game state flags.
  *
- * Note that in non-upgraded mods, this function will not account for the player having visited
- * Repentance floors in The Ascent. (Handling this requires stateful tracking as the player
- * progresses through the run.)
+ * If you want to account for the player having visited Repentance floors in The Ascent, use the
+ * `getNextStageUsingHistory` helper function instead (from the stage history feature). Handling
+ * this requires stateful tracking as the player progresses through the run.
  */
 export function getNextStage(): LevelStage {
   const level = game.GetLevel();
@@ -35,7 +33,7 @@ export function getNextStage(): LevelStage {
 
   // First, handle the special case of being on the backwards path.
   if (backwardsPath) {
-    return getNextStageBackwardsPath(stage, repentanceStage);
+    return asNumber(stage) - 1;
   }
 
   // Second, handle the special case of being in a specific off-grid room.
@@ -113,135 +111,14 @@ export function getNextStage(): LevelStage {
   return asNumber(stage) + 1;
 }
 
-function getNextStageBackwardsPath(
-  stage: LevelStage,
-  repentanceStage: boolean,
-): LevelStage {
-  // If we have no stage history to work with, then default to the previous stage.
-  if (!areFeaturesInitialized()) {
-    return asNumber(stage) - 1;
-  }
-
-  const visitedDownpour1 = hasVisitedStage(
-    LevelStage.BASEMENT_1,
-    StageType.REPENTANCE,
-  );
-  const visitedDross1 = hasVisitedStage(
-    LevelStage.BASEMENT_1,
-    StageType.REPENTANCE_B,
-  );
-  const visitedDownpour2 = hasVisitedStage(
-    LevelStage.BASEMENT_2,
-    StageType.REPENTANCE,
-  );
-  const visitedDross2 = hasVisitedStage(
-    LevelStage.BASEMENT_2,
-    StageType.REPENTANCE_B,
-  );
-  const visitedMines1 = hasVisitedStage(
-    LevelStage.CAVES_1,
-    StageType.REPENTANCE,
-  );
-  const visitedAshpit1 = hasVisitedStage(
-    LevelStage.CAVES_1,
-    StageType.REPENTANCE_B,
-  );
-  const visitedMines2 = hasVisitedStage(
-    LevelStage.DEPTHS_2,
-    StageType.REPENTANCE,
-  );
-  const visitedAshpit2 = hasVisitedStage(
-    LevelStage.DEPTHS_2,
-    StageType.REPENTANCE_B,
-  );
-
-  if (stage === LevelStage.BASEMENT_1) {
-    if (repentanceStage) {
-      // From Downpour 1 to Basement 1.
-      return LevelStage.BASEMENT_1;
-    }
-
-    // From Basement 1 to Home.
-    return LevelStage.HOME;
-  }
-
-  if (stage === LevelStage.BASEMENT_2) {
-    if (repentanceStage) {
-      if (visitedDownpour1 || visitedDross1) {
-        // From Downpour 2 to Downpour 1.
-        return LevelStage.BASEMENT_1;
-      }
-
-      // From Downpour 2 to Basement 2.
-      return LevelStage.BASEMENT_2;
-    }
-
-    // From Basement 2 to Basement 1.
-    return LevelStage.BASEMENT_1;
-  }
-
-  if (stage === LevelStage.CAVES_1) {
-    if (repentanceStage) {
-      if (visitedDownpour2 || visitedDross2) {
-        // From Mines 1 to Downpour 1.
-        return LevelStage.BASEMENT_2;
-      }
-
-      // From Mines 1 to Caves 1.
-      return LevelStage.CAVES_1;
-    }
-
-    // From Caves 1 to Basement 2.
-    return LevelStage.BASEMENT_2;
-  }
-
-  if (stage === LevelStage.CAVES_2) {
-    if (repentanceStage) {
-      if (visitedMines1 || visitedAshpit1) {
-        // From Mines 2 to Mines 1.
-        return LevelStage.CAVES_1;
-      }
-
-      // From Mines 2 to Caves 2.
-      return LevelStage.CAVES_2;
-    }
-
-    // From Caves 2 to Caves 1.
-    return LevelStage.CAVES_1;
-  }
-
-  if (stage === LevelStage.DEPTHS_1) {
-    if (repentanceStage) {
-      if (visitedMines2 || visitedAshpit2) {
-        // From Mausoleum 1 to Mines 2.
-        return LevelStage.CAVES_2;
-      }
-
-      // From Mausoleum 1 to Depths 1.
-      return LevelStage.DEPTHS_1;
-    }
-
-    // From Depths 1 to Caves 2.
-    return LevelStage.CAVES_2;
-  }
-
-  if (stage === LevelStage.DEPTHS_2) {
-    if (repentanceStage) {
-      // From Mausoleum 2 to Depths 2.
-      return LevelStage.DEPTHS_2;
-    }
-
-    // From Depths 2 to Depths 1.
-    return LevelStage.DEPTHS_1;
-  }
-
-  return asNumber(stage) - 1;
-}
-
 /**
  * Helper function to get the stage type that a trapdoor or heaven door would take the player to,
  * based on the current stage, room, and game state flags.
  *
+ * If you want to account for previous floors visited on The Ascent, use the
+ * `getNextStageTypeUsingHistory` helper function instead (from the stage history feature). Handling
+ * this requires stateful tracking as the player progresses through the run.
+ *
  * @param upwards Whether or not the player should go up to Cathedral in the case of being on Womb
  *                2. Default is false.
  */
@@ -259,7 +136,7 @@ export function getNextStageType(upwards = false): StageType {
 
   // First, handle the special case of being on the backwards path.
   if (backwardsPath) {
-    return getStageTypeBackwardsPath(stage, nextStage, repentanceStage);
+    return calculateStageType(nextStage);
   }
 
   // Second, handle the special case of being in a specific off-grid room.
@@ -327,94 +204,3 @@ export function getNextStageType(upwards = false): StageType {
 
   return calculateStageType(nextStage);
 }
-
-function getStageTypeBackwardsPath(
-  stage: LevelStage,
-  nextStage: LevelStage,
-  repentanceStage: boolean,
-): StageType {
-  const visitedDownpour1 = hasVisitedStage(
-    LevelStage.BASEMENT_1,
-    StageType.REPENTANCE,
-  );
-  const visitedDross1 = hasVisitedStage(
-    LevelStage.BASEMENT_1,
-    StageType.REPENTANCE_B,
-  );
-  const visitedDownpour2 = hasVisitedStage(
-    LevelStage.BASEMENT_2,
-    StageType.REPENTANCE,
-  );
-  const visitedDross2 = hasVisitedStage(
-    LevelStage.BASEMENT_2,
-    StageType.REPENTANCE_B,
-  );
-  const visitedMines1 = hasVisitedStage(
-    LevelStage.CAVES_1,
-    StageType.REPENTANCE,
-  );
-  const visitedAshpit1 = hasVisitedStage(
-    LevelStage.CAVES_1,
-    StageType.REPENTANCE_B,
-  );
-  const visitedMines2 = hasVisitedStage(
-    LevelStage.DEPTHS_2,
-    StageType.REPENTANCE,
-  );
-  const visitedAshpit2 = hasVisitedStage(
-    LevelStage.DEPTHS_2,
-    StageType.REPENTANCE_B,
-  );
-
-  if (stage === LevelStage.BASEMENT_2 && repentanceStage) {
-    if (visitedDownpour1) {
-      return StageType.REPENTANCE;
-    }
-
-    if (visitedDross1) {
-      return StageType.REPENTANCE_B;
-    }
-  }
-
-  if (stage === LevelStage.CAVES_1 && repentanceStage) {
-    if (visitedDownpour2) {
-      return StageType.REPENTANCE;
-    }
-
-    if (visitedDross2) {
-      return StageType.REPENTANCE_B;
-    }
-  }
-
-  if (stage === LevelStage.CAVES_2 && !repentanceStage) {
-    if (visitedDownpour2) {
-      return StageType.REPENTANCE;
-    }
-
-    if (visitedDross2) {
-      return StageType.REPENTANCE_B;
-    }
-  }
-
-  if (stage === LevelStage.CAVES_2 && repentanceStage) {
-    if (visitedMines1) {
-      return StageType.REPENTANCE;
-    }
-
-    if (visitedAshpit1) {
-      return StageType.REPENTANCE_B;
-    }
-  }
-
-  if (stage === LevelStage.DEPTHS_2 && !repentanceStage) {
-    if (visitedAshpit2) {
-      return StageType.REPENTANCE_B;
-    }
-
-    if (visitedMines2) {
-      return StageType.REPENTANCE;
-    }
-  }
-
-  return calculateStageType(nextStage);
-}

package/src/functions/players.ts

@@ -13,7 +13,6 @@ import { game, itemConfig } from "../core/cachedClasses";
 import { getLastElement, sumArray } from "./array";
 import { getCharacterName, isVanillaCharacter } from "./characters";
 import { getCollectibleMaxCharges } from "./collectibles";
-import { getCollectibleArray } from "./collectibleSet";
 import { getEnumValues } from "./enums";
 import {
   getAllPlayers,
@@ -232,38 +231,13 @@ export function getPlayerCollectibleCount(
 ): int {
   let numCollectibles = 0;
   for (const collectibleType of collectibleTypes) {
-    // We need to specify "true" as the second argument here to filter out things like Lilith's
-    // Incubus.
+    // We specify "true" as the second argument to filter out things like Lilith's Incubus.
     numCollectibles += player.GetCollectibleNum(collectibleType, true);
   }
 
   return numCollectibles;
 }
 
-/**
- * Iterates over every item in the game and returns a map containing the number of each item that
- * the player has.
- *
- * Note that this will filter out non-real collectibles like Lilith's Incubus.
- */
-export function getPlayerCollectibleMap(
-  player: EntityPlayer,
-): Map<CollectibleType, int> {
-  const collectibleArray = getCollectibleArray();
-
-  const collectibleMap = new Map<CollectibleType, int>();
-  for (const collectibleType of collectibleArray) {
-    // We need to specify "true" as the second argument here to filter out things like Lilith's
-    // Incubus.
-    const collectibleNum = player.GetCollectibleNum(collectibleType, true);
-    if (collectibleNum > 0) {
-      collectibleMap.set(collectibleType, collectibleNum);
-    }
-  }
-
-  return collectibleMap;
-}
-
 /**
  * Helper function to get the player from a tear, laser, bomb, etc. Returns undefined if the entity
  * does not correspond to any particular player.
@@ -435,8 +409,7 @@ export function getTotalPlayerCollectibles(
 ): int {
   const players = getPlayers();
   const numCollectiblesArray = players.map((player) =>
-    // We need to specify "true" as the second argument here to filter out things like Lilith's
-    // Incubus.
+    // We specify "true" as the second argument to filter out things like Lilith's Incubus.
     player.GetCollectibleNum(collectibleType, true),
   );
 
@@ -574,6 +547,16 @@ export function isModdedPlayer(player: EntityPlayer): boolean {
   return !isVanillaPlayer(player);
 }
 
+/**
+ * Helper function for determining if a player is able to turn their head by pressing the shooting
+ * buttons.
+ *
+ * Under the hood, this function uses the `EntityPlayer.IsExtraAnimationFinished` method.
+ */
+export function isPlayerAbleToAim(player: EntityPlayer): boolean {
+  return player.IsExtraAnimationFinished();
+}
+
 /** Helper function for detecting if a player is one of the Tainted characters. */
 export function isTainted(player: EntityPlayer): boolean {
   const character = player.GetPlayerType();

package/src/functions/rng.ts

@@ -1,6 +1,6 @@
 import { CopyableIsaacAPIClassType } from "isaac-typescript-definitions";
 import { game } from "../core/cachedClasses";
-import { SerializationBrand } from "../enums/private/SerializationBrand";
+import { SerializationBrand } from "../enums/SerializationBrand";
 import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
 import { getNumbersFromTable, tableHasKeys } from "./table";
 import { isTable } from "./types";
@@ -71,8 +71,8 @@ export function isRNG(object: unknown): object is RNG {
 }
 
 /**
- * Used to determine is the given table is a serialized `RNG` object created by the save data
- * manager and/or the `deepCopy` function.
+ * Used to determine is the given table is a serialized `RNG` object created by the `deepCopy`
+ * function.
  */
 export function isSerializedRNG(object: unknown): object is SerializedRNG {
   if (!isTable(object)) {