isaacscript-common 6.6.1-dev.0 → 6.6.1-dev.4

package/src/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 "./saveDataManagerConstants";
+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/src/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 "./saveDataManagerConstants";
+
+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/src/features/saveDataManager/saveDataManagerConstants.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/src/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/src/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 = "sirenHelpers";
+
+const v = {
+  run: {
+    familiarBlacklist: [] as Array<
+      [variant: FamiliarVariant, subType: int | undefined]
+    >,
+  },
+};
+
+/** @internal */
+export function sirenHelpersInit(mod: Mod): void {
+  saveDataManager(FEATURE_NAME, 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,
+  );
+}

package/src/features/stageHistory.ts

@@ -0,0 +1,67 @@
+import { LevelStage, StageType } from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import { saveDataManager } from "./saveDataManager/exports";
+
+const FEATURE_NAME = "stageHistory";
+
+const v = {
+  run: {
+    stageHistory: [] as Array<[stage: LevelStage, stageType: StageType]>,
+  },
+};
+
+/** @internal */
+export function stageHistoryInit(mod: ModUpgraded): void {
+  saveDataManager(FEATURE_NAME, v);
+
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_NEW_LEVEL_REORDERED,
+    postNewLevelReordered,
+  );
+}
+
+// ModCallbackCustom.POST_NEW_LEVEL_REORDERED
+function postNewLevelReordered() {
+  const level = game.GetLevel();
+  const stage = level.GetStage();
+  const stageType = level.GetStageType();
+
+  v.run.stageHistory.push([stage, stageType]);
+}
+
+/** Helper function to get all of the stages that a player has visited thus far on this run. */
+export function getStageHistory(): ReadonlyArray<
+  [stage: LevelStage, stageType: StageType]
+> {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  return v.run.stageHistory;
+}
+
+/**
+ * Helper function to check if a player has previous visited a particular stage (or stage + stage
+ * type combination) on this run.
+ *
+ * @param stage The stage to check for.
+ * @param stageType Optional. If provided, will check for a specific stage and stage type
+ *                  combination.
+ */
+export function hasVisitedStage(
+  stage: LevelStage,
+  stageType?: StageType,
+): boolean {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  if (stageType === undefined) {
+    return v.run.stageHistory.some(
+      ([previousStage]) => previousStage === stage,
+    );
+  }
+
+  return v.run.stageHistory.some(
+    ([previousStage, previousStageType]) =>
+      previousStage === stage && previousStageType === stageType,
+  );
+}

package/src/features/taintedLazarusPlayers.ts

@@ -0,0 +1,113 @@
+// This feature provides a way for end-users to get the `EntityPlayer` object for the other Tainted
+// Lazarus.
+
+import { ModCallback, PlayerType } from "isaac-typescript-definitions";
+import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import { saveDataManager } from "./saveDataManager/exports";
+
+const FEATURE_NAME = "taintedLazarusPlayers";
+
+const v = {
+  run: {
+    queuedTaintedLazarus: [] as EntityPtr[],
+    queuedDeadTaintedLazarus: [] as EntityPtr[],
+
+    /**
+     * The PostPlayerInit callback fires for Dead Tainted Lazarus at the beginning of the run.
+     * However, the player index for the Dead Tainted Lazarus player object at that time does not
+     * actually correspond to the player index for the real player once Flip has been used. Thus, we
+     * revert to using PtrHash as an index for our map, which is consistent between the Dead Tainted
+     * Lazarus object in the PostPlayerInit callback and the "real" Dead Tainted Lazarus.
+     */
+    subPlayerMap: new Map<PtrHash, EntityPtr>(),
+  },
+};
+
+/** @internal */
+export function taintedLazarusPlayersInit(mod: Mod): void {
+  saveDataManager(FEATURE_NAME, v, () => false);
+
+  mod.AddCallback(ModCallback.POST_PLAYER_INIT, postPlayerInit);
+}
+
+// ModCallback.POST_PLAYER_INIT (9)
+function postPlayerInit(player: EntityPlayer) {
+  const entityPtr = EntityPtr(player);
+  const character = player.GetPlayerType();
+
+  if (character === PlayerType.LAZARUS_B) {
+    v.run.queuedTaintedLazarus.push(entityPtr);
+  } else if (character === PlayerType.LAZARUS_2_B) {
+    v.run.queuedDeadTaintedLazarus.push(entityPtr);
+  } else {
+    return;
+  }
+
+  checkDequeue();
+}
+
+/**
+ * When starting a run, the PostPlayerInit callback will fire first for Dead Tainted Lazarus, then
+ * for Tainted Lazarus. When continuing a run, the PostPlayerInit callback will fire first for the
+ * character that is currently active. Thus, since the order of the characters is not certain, we
+ * insert each of their pointers into a queue, and then only populate the map when we have one
+ * Tainted Lazarus and one Dead Tainted Lazarus.
+ */
+function checkDequeue() {
+  if (
+    v.run.queuedTaintedLazarus.length === 0 ||
+    v.run.queuedDeadTaintedLazarus.length === 0
+  ) {
+    return;
+  }
+
+  const taintedLazarusPtr = v.run.queuedTaintedLazarus.shift();
+  const deadTaintedLazarusPtr = v.run.queuedDeadTaintedLazarus.shift();
+
+  if (taintedLazarusPtr === undefined || deadTaintedLazarusPtr === undefined) {
+    return;
+  }
+
+  const taintedLazarus = taintedLazarusPtr.Ref;
+  const deadTaintedLazarus = deadTaintedLazarusPtr.Ref;
+
+  if (taintedLazarus === undefined || deadTaintedLazarus === undefined) {
+    return;
+  }
+
+  const taintedLazarusPtrHash = GetPtrHash(taintedLazarus);
+  const deadTaintedLazarusPtrHash = GetPtrHash(deadTaintedLazarus);
+
+  v.run.subPlayerMap.set(taintedLazarusPtrHash, deadTaintedLazarusPtr);
+  v.run.subPlayerMap.set(deadTaintedLazarusPtrHash, taintedLazarusPtr);
+}
+
+/**
+ * Helper function to get the other version of Tainted Lazarus.
+ *
+ * - On Tainted Lazarus, returns the player object for Dead Tainted Lazarus.
+ * - On Dead Tainted Lazarus, returns the player object for Tainted Lazarus.
+ * - Returns undefined if player object retrieval failed for any reason.
+ *
+ * If you call the `EntityPlayer.Exists` method on the returned object, it will return false.
+ * However, you can still call the other methods like you normally would (e.g.
+ * `EntityPlayer.AddCollectible`).
+ */
+export function getTaintedLazarusSubPlayer(
+  player: EntityPlayer,
+): EntityPlayer | undefined {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  const ptrHash = GetPtrHash(player);
+  const entityPtr = v.run.subPlayerMap.get(ptrHash);
+  if (entityPtr === undefined) {
+    return undefined;
+  }
+
+  const entity = entityPtr.Ref;
+  if (entity === undefined) {
+    return undefined;
+  }
+
+  return entity.ToPlayer();
+}

package/src/featuresInitialized.ts

@@ -0,0 +1,20 @@
+let featuresInitialized = false;
+
+/** @internal */
+export function areFeaturesInitialized(): boolean {
+  return featuresInitialized;
+}
+
+/** @internal */
+export function errorIfFeaturesNotInitialized(featureName: string): void {
+  if (!areFeaturesInitialized()) {
+    error(
+      `The "${featureName}" feature is not initialized. You must first upgrade your mod object by calling the "upgradeMod" function.`,
+    );
+  }
+}
+
+/** @internal */
+export function setFeaturesInitialized(): void {
+  featuresInitialized = true;
+}

package/src/functions/ambush.ts

@@ -0,0 +1,45 @@
+import { SackSubType } from "isaac-typescript-definitions";
+import { runNextGameFrame } from "../features/runInNFrames";
+import { removeEntities } from "./entity";
+import { getCoins, spawnSackWithSeed } from "./pickups";
+
+/** Hard-coding this makes it easier to clean up the pickups afterwards. */
+const SACK_SEED_THAT_SPAWNS_TWO_COINS = 6 as Seed;
+
+/**
+ * Helper function to start a Challenge Room or the Boss Rush.
+ *
+ * Specifically, this is performed by spawning a sack on top of the player, waiting a game frame,
+ * and then removing the sack and the pickups that the sack dropped.
+ */
+export function startAmbush(): void {
+  const player = Isaac.GetPlayer();
+  const sack = spawnSackWithSeed(
+    SackSubType.NULL,
+    player.Position,
+    SACK_SEED_THAT_SPAWNS_TWO_COINS,
+  );
+
+  // The sack will play the "Appear" animation and the player will not be able to interact with it
+  // while this is occurring. By stopping the animation, it will transition to the "Idle" animation
+  // and be interactable on the next game frame.
+  const sprite = sack.GetSprite();
+  sprite.Stop();
+  const sackPtr = EntityPtr(sack);
+  runNextGameFrame(() => {
+    const futureSack = sackPtr.Ref;
+    if (futureSack === undefined) {
+      return;
+    }
+
+    futureSack.Remove();
+    const sackPtrHash = GetPtrHash(futureSack);
+    const coins = getCoins();
+    const coinsFromSack = coins.filter(
+      (pickup) =>
+        pickup.SpawnerEntity !== undefined &&
+        GetPtrHash(pickup.SpawnerEntity) === sackPtrHash,
+    );
+    removeEntities(coinsFromSack);
+  });
+}