isaacscript-common 2.3.0 → 3.0.0

package/src/features/saveDataManager/merge.ts

@@ -1,182 +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 } from "../../functions/table";
-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 {
-  if (SAVE_DATA_MANAGER_DEBUG) {
-    log(`merge is traversing: ${traversalDescription}`);
-  }
-
-  const oldObjectType = type(oldObject);
-  if (oldObjectType !== "table") {
-    error("The first argument given to the merge function is not a table.");
-  }
-
-  const newTableType = type(newTable);
-  if (newTableType !== "table") {
-    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)) {
-    const oldTable = oldObject as LuaTable<AnyNotNil, unknown>;
-    mergeArray(oldTable, 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 (oldObject instanceof Map || oldObject instanceof Set) {
-    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);
-  for (const [key, value] of pairs(newArray)) {
-    oldArray.set(key, value);
-  }
-}
-
-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,
-  );
-
-  for (const [key, value] of pairs(newTable)) {
-    if (isSerializationBrand(key)) {
-      continue;
-    }
-
-    let keyToUse = key;
-    if (convertStringKeysToNumbers) {
-      const numberKey = tonumber(key);
-      if (numberKey === undefined) {
-        continue;
-      }
-      keyToUse = numberKey;
-    }
-
-    if (oldObject instanceof Map) {
-      const valueType = type(value);
-
-      let valueCopy: unknown;
-      if (valueType === "table") {
-        valueCopy = deepCopy(
-          value as LuaTable,
-          SerializationType.DESERIALIZE,
-          traversalDescription,
-        );
-      } else {
-        valueCopy = value;
-      }
-
-      oldObject.set(keyToUse, valueCopy);
-    } else if (oldObject instanceof Set) {
-      oldObject.add(keyToUse);
-    }
-  }
-}
-
-function mergeTable(
-  oldTable: LuaTable<AnyNotNil, unknown>,
-  newTable: LuaTable<AnyNotNil, unknown>,
-  traversalDescription: string,
-) {
-  for (const [key, value] of pairs(newTable)) {
-    if (SAVE_DATA_MANAGER_DEBUG) {
-      const valueToPrint = value === "" ? "(empty string)" : `${value}`;
-      log(`merge is merging: ${traversalDescription} --> ${valueToPrint}`);
-    }
-
-    if (isSerializationBrand(key)) {
-      continue;
-    }
-
-    // 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);
-      continue;
-    }
-
-    const valueType = type(value);
-    if (valueType === "table") {
-      let oldValue = oldTable.get(key) as LuaTable<AnyNotNil, unknown>;
-      const oldValueType = type(oldValue);
-
-      if (oldValueType !== "table") {
-        // 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 as LuaTable, traversalDescription);
-    } else {
-      // Base case: copy the value
-      oldTable.set(key, value);
-    }
-  }
-}

package/src/features/saveDataManager/save.ts

@@ -1,66 +0,0 @@
-import { SerializationType } from "../../enums/SerializationType";
-import { deepCopy } from "../../functions/deepCopy";
-import { jsonEncode } from "../../functions/jsonHelpers";
-import { log } from "../../functions/log";
-import { SaveData } from "../../interfaces/SaveData";
-import { 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>();
-
-  for (const [subscriberName, saveData] of pairs(saveDataMap)) {
-    // 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) {
-        continue;
-      }
-    }
-
-    // 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) {
-      continue;
-    }
-
-    // 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);
-  }
-
-  return allSaveData;
-}

package/src/features/saveDataManager/serializationBrand.ts

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

package/src/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,
-  );
-}

package/src/features/taintedLazarusPlayers.ts

@@ -1,113 +0,0 @@
-// 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 = "Tainted Lazarus entity finder";
-
-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("taintedLazarusPlayers", 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

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