isaacscript-common 14.1.3 → 15.0.0

package/src/classes/features/other/extraConsoleCommands/subroutines.ts

@@ -0,0 +1,164 @@
+import {
+  Direction,
+  EntityType,
+  GridEntityType,
+  GridRoom,
+  RoomType,
+} from "isaac-typescript-definitions";
+import { game } from "../../../../core/cachedClasses";
+import { HealthType } from "../../../../enums/HealthType";
+import { directionToVector } from "../../../../functions/direction";
+import { spawnGridEntityWithVariant } from "../../../../functions/gridEntities";
+import {
+  getRoomAdjacentGridIndexes,
+  getRoomGridIndexesForType,
+} from "../../../../functions/levelGrid";
+import {
+  logAllEntities,
+  logAllGridEntities,
+} from "../../../../functions/logEntities";
+import { addPlayerHealthType } from "../../../../functions/playerHealth";
+import { getRoomData, getRoomDescriptor } from "../../../../functions/roomData";
+import { changeRoom } from "../../../../functions/rooms";
+import { printConsole } from "../../../../functions/utils";
+import { ROOM_TYPE_NAMES } from "../../../../objects/roomTypeNames";
+
+const DEFAULT_MOVE_UNITS = 0.5;
+
+export function addHeart(params: string, healthType: HealthType): void {
+  let numHearts = healthType === HealthType.MAX_HEARTS ? 2 : 1;
+  if (params !== "") {
+    const num = tonumber(params);
+    if (num === undefined) {
+      printConsole("That is an invalid amount of hearts to add.");
+      return;
+    }
+
+    numHearts = num;
+  }
+
+  const player = Isaac.GetPlayer();
+  addPlayerHealthType(player, healthType, numHearts);
+}
+
+export function devilAngel(useDevil: boolean): void {
+  const level = game.GetLevel();
+
+  const devilAngelRoomData = getRoomData(GridRoom.DEVIL);
+  if (devilAngelRoomData !== undefined) {
+    const roomType = devilAngelRoomData.Type;
+    const conflictingType = useDevil ? RoomType.ANGEL : RoomType.DEVIL;
+    if (roomType === conflictingType) {
+      // Delete the room data, which will allow the `Level.InitializeDevilAngelRoom` method to work.
+      const roomDescriptor = getRoomDescriptor(GridRoom.DEVIL);
+      roomDescriptor.Data = undefined;
+    }
+  }
+
+  if (useDevil) {
+    level.InitializeDevilAngelRoom(false, true);
+  } else {
+    level.InitializeDevilAngelRoom(true, false);
+  }
+
+  changeRoom(GridRoom.DEVIL);
+}
+
+export function listEntities(
+  params: string,
+  includeBackgroundEffects: boolean,
+): void {
+  let entityTypeFilter: EntityType | undefined;
+  if (params !== "") {
+    entityTypeFilter = tonumber(params);
+    if (entityTypeFilter === undefined) {
+      printConsole("That is an invalid entity type to filter by.");
+      return;
+    }
+  }
+
+  logAllEntities(includeBackgroundEffects, entityTypeFilter);
+  printConsole('Logged the entities in the room to the "log.txt" file.');
+}
+
+export function listGridEntities(params: string, includeWalls: boolean): void {
+  let gridEntityTypeFilter: GridEntityType | undefined;
+  if (params !== "") {
+    gridEntityTypeFilter = tonumber(params);
+    if (gridEntityTypeFilter === undefined) {
+      printConsole("That is an invalid grid entity type to filter by.");
+      return;
+    }
+  }
+
+  logAllGridEntities(includeWalls, gridEntityTypeFilter);
+  printConsole('Logged the grid entities in the room to the "log.txt" file.');
+}
+
+export function movePlayer(params: string, direction: Direction): void {
+  let amount = DEFAULT_MOVE_UNITS;
+  if (params !== "") {
+    const num = tonumber(params);
+    if (num === undefined) {
+      printConsole("That is an invalid amount of units to move.");
+      return;
+    }
+
+    amount = num;
+  }
+
+  const player = Isaac.GetPlayer();
+  const vector = directionToVector(direction);
+  const modifiedVector = vector.mul(amount);
+  player.Position = player.Position.add(modifiedVector);
+}
+
+export function spawnTrapdoorOrCrawlSpace(trapdoor: boolean): void {
+  const room = game.GetRoom();
+  const player = Isaac.GetPlayer();
+  const position = room.FindFreeTilePosition(player.Position, 0);
+  const gridIndex = room.GetGridIndex(position);
+  const gridEntityType = trapdoor
+    ? GridEntityType.TRAPDOOR
+    : GridEntityType.CRAWL_SPACE;
+
+  spawnGridEntityWithVariant(gridEntityType, 0, gridIndex);
+}
+
+export function warpToRoomType(roomType: RoomType): void {
+  const roomTypeName = ROOM_TYPE_NAMES[roomType];
+  const gridIndexes = getRoomGridIndexesForType(roomType);
+  const firstGridIndex = gridIndexes[0];
+  if (firstGridIndex === undefined) {
+    printConsole(`There are no ${roomTypeName}s on this floor.`);
+    return;
+  }
+
+  changeRoom(firstGridIndex);
+  printConsole(`Warped to room type: ${roomTypeName} (${roomType})`);
+}
+
+export function warpNextToRoomType(roomType: RoomType): void {
+  const roomTypeName = ROOM_TYPE_NAMES[roomType];
+  const gridIndexes = getRoomGridIndexesForType(roomType);
+  const firstGridIndex = gridIndexes[0];
+  if (firstGridIndex === undefined) {
+    printConsole(`There are no ${roomTypeName}s on this floor.`);
+    return;
+  }
+
+  const adjacentRoomGridIndexes = getRoomAdjacentGridIndexes(firstGridIndex);
+
+  for (const [_doorSlot, roomGridIndex] of adjacentRoomGridIndexes.entries()) {
+    const roomData = getRoomData(roomGridIndex);
+    if (roomData !== undefined && roomData.Type === RoomType.DEFAULT) {
+      changeRoom(roomGridIndex);
+      printConsole(`Warped next to room type: ${roomTypeName} (${roomType})`);
+      return;
+    }
+  }
+
+  printConsole(
+    `Failed to find the room next to room type: ${roomTypeName} (${roomType})`,
+  );
+}

package/src/classes/features/other/extraConsoleCommands/v.ts

@@ -0,0 +1,27 @@
+export const v = {
+  persistent: {
+    // Curses
+    darkness: false, // 1
+    labyrinth: false, // 2
+    lost: false, // 3
+    unknown: false, // 4
+    cursed: false, // 5
+    maze: false, // 6
+    blind: false, // 7
+    giant: false, // 8
+    disableCurses: false,
+
+    // Stats
+    damage: false,
+    damageAmount: 500,
+    speed: false,
+    speedAmount: 2.0,
+    tears: false,
+    tearsAmount: 1, // In tear delay, not tears stat
+    flight: false,
+
+    // Other
+    chaosCardTears: false,
+    spamBloodRights: false,
+  },
+};

package/src/classes/features/other/saveDataManager/constants.ts

@@ -0,0 +1 @@
+export const SAVE_DATA_MANAGER_DEBUG = false as boolean;

package/src/classes/features/other/saveDataManager/glowingHourGlass.ts

@@ -0,0 +1,138 @@
+// The save data manager has a feature where certain variables will automatically be rolled back
+// when the Glowing Hour Glass is used.
+
+import { SaveDataKey } from "../../../../enums/SaveDataKey";
+import { SerializationType } from "../../../../enums/SerializationType";
+import { deepCopy } from "../../../../functions/deepCopy";
+import { merge } from "../../../../functions/merge";
+import { iterateTableInOrder } from "../../../../functions/table";
+import { SaveData } from "../../../../interfaces/SaveData";
+import { AnyClass } from "../../../../types/AnyClass";
+import { SAVE_DATA_MANAGER_DEBUG } from "./constants";
+
+/**
+ * When the Glowing Hour Glass is used, certain save data keys will automatically be restored to a
+ * backup.
+ */
+const GLOWING_HOUR_GLASS_BACKUP_KEYS: readonly SaveDataKey[] = [
+  SaveDataKey.RUN,
+  SaveDataKey.LEVEL,
+];
+
+const IGNORE_GLOWING_HOUR_GLASS_KEY = "__ignoreGlowingHourGlass";
+
+export function makeGlowingHourGlassBackup(
+  saveDataMap: LuaMap<string, SaveData>,
+  saveDataConditionalFuncMap: LuaMap<string, () => boolean>,
+  saveDataGlowingHourGlassMap: LuaMap<string, SaveData>,
+): void {
+  iterateTableInOrder(
+    saveDataMap,
+    (subscriberName, saveData) => {
+      // We make the Glowing Hour Glass backup using `SerializationType.SERIALIZE`, which means that
+      // we cannot operate on unserializable data, such as functions. Save data that utilizes
+      // unserializable data will typically be marked using a conditional function that evaluates to
+      // false, so we skip all save data that matches this criteria.
+      const conditionalFunc = saveDataConditionalFuncMap.get(subscriberName);
+      if (conditionalFunc !== undefined) {
+        const shouldSave = conditionalFunc();
+        if (!shouldSave) {
+          return;
+        }
+      }
+
+      for (const saveDataKey of GLOWING_HOUR_GLASS_BACKUP_KEYS) {
+        const childTable = saveData[saveDataKey];
+        if (childTable === undefined) {
+          // This feature does not happen to store any variables on this particular child table.
+          continue;
+        }
+
+        // Ignore child tables that the end-user has explicitly annotated.
+        const childTableLuaMap = childTable as LuaMap<AnyNotNil, unknown>;
+        if (childTableLuaMap.has(IGNORE_GLOWING_HOUR_GLASS_KEY)) {
+          continue;
+        }
+
+        let saveDataGlowingHourGlass =
+          saveDataGlowingHourGlassMap.get(subscriberName);
+        if (saveDataGlowingHourGlass === undefined) {
+          saveDataGlowingHourGlass = new LuaMap<string, unknown>() as SaveData;
+          saveDataGlowingHourGlassMap.set(
+            subscriberName,
+            saveDataGlowingHourGlass,
+          );
+        }
+
+        // We serialize the table so that we can use the `merge` function later on with no other
+        // modifications.
+        const copiedChildTable = deepCopy(
+          childTable,
+          SerializationType.SERIALIZE,
+        ) as Record<string, unknown>;
+        saveDataGlowingHourGlass[saveDataKey] = copiedChildTable;
+      }
+    },
+    SAVE_DATA_MANAGER_DEBUG,
+  );
+}
+
+export function restoreGlowingHourGlassBackup(
+  saveDataMap: LuaMap<string, SaveData>,
+  saveDataConditionalFuncMap: LuaMap<string, () => boolean>,
+  saveDataGlowingHourGlassMap: LuaMap<string, SaveData>,
+  classConstructors: LuaMap<string, AnyClass>,
+): void {
+  iterateTableInOrder(
+    saveDataMap,
+    (subscriberName, saveData) => {
+      // We make the Glowing Hour Glass backup using `SerializationType.SERIALIZE`, which means that
+      // we cannot operate on unserializable data, such as functions. Save data that utilizes
+      // unserializable data will typically be marked using a conditional function that evaluates to
+      // false, so we skip all save data that matches this criteria.
+      const conditionalFunc = saveDataConditionalFuncMap.get(subscriberName);
+      if (conditionalFunc !== undefined) {
+        const shouldSave = conditionalFunc();
+        if (!shouldSave) {
+          return;
+        }
+      }
+
+      for (const saveDataKey of GLOWING_HOUR_GLASS_BACKUP_KEYS) {
+        const childTable = saveData[saveDataKey];
+        if (childTable === undefined) {
+          // This feature does not happen to store any variables on this particular child table.
+          continue;
+        }
+
+        // Ignore child tables that the end-user has explicitly annotated.
+        const childTableLuaMap = childTable as LuaMap<AnyNotNil, unknown>;
+        if (childTableLuaMap.has(IGNORE_GLOWING_HOUR_GLASS_KEY)) {
+          continue;
+        }
+
+        const saveDataGlowingHourGlass =
+          saveDataGlowingHourGlassMap.get(subscriberName);
+        if (saveDataGlowingHourGlass === undefined) {
+          // This should never happen.
+          continue;
+        }
+
+        const childTableBackup = saveDataGlowingHourGlass[saveDataKey];
+        if (childTableBackup === undefined) {
+          // This should never happen.
+          continue;
+        }
+
+        merge(
+          childTable as LuaMap<AnyNotNil, unknown>,
+          childTableBackup as LuaMap<AnyNotNil, unknown>,
+          // Append an arbitrary suffix for better error messages.
+          `${subscriberName}__glowingHourGlass`,
+          classConstructors,
+        );
+      }
+    },
+    SAVE_DATA_MANAGER_DEBUG,
+  );
+}

package/src/classes/features/other/saveDataManager/loadFromDisk.ts

@@ -0,0 +1,99 @@
+import { jsonDecode } from "../../../../functions/jsonHelpers";
+import { log } from "../../../../functions/log";
+import { logError } from "../../../../functions/logMisc";
+import { merge } from "../../../../functions/merge";
+import { iterateTableInOrder } from "../../../../functions/table";
+import { isString, isTable } from "../../../../functions/types";
+import { SaveData } from "../../../../interfaces/SaveData";
+import { AnyClass } from "../../../../types/AnyClass";
+import { SAVE_DATA_MANAGER_DEBUG } from "./constants";
+
+const DEFAULT_MOD_DATA = "{}";
+
+export function loadFromDisk(
+  mod: Mod,
+  oldSaveData: LuaMap<string, SaveData>,
+  classConstructors: LuaMap<string, AnyClass>,
+): void {
+  if (!mod.HasData()) {
+    // There is no "save#.dat" file for this save slot.
+    return;
+  }
+
+  // First, read the "save#.dat" file into a Lua table.
+  const jsonString = readSaveDatFile(mod);
+  const newSaveData = jsonDecode(jsonString);
+
+  if (SAVE_DATA_MANAGER_DEBUG) {
+    log('Converted data from the "save#.dat" to a Lua table.');
+  }
+
+  // Second, iterate over all the fields of the new table.)
+  iterateTableInOrder(
+    newSaveData,
+    (subscriberName, saveData) => {
+      // All elements of loaded save data should have keys that are strings equal to the name of the
+      // subscriber/feature. Ignore elements with other types of keys.
+      if (!isString(subscriberName)) {
+        return;
+      }
+
+      // All elements of loaded save data should be tables that contain fields corresponding to the
+      // `SaveData` interface. Ignore elements that are not tables.
+      if (!isTable(saveData)) {
+        return;
+      }
+
+      // Ignore elements that represent subscriptions that no longer exist in the current save data.
+      const oldSaveDataForSubscriber = oldSaveData.get(subscriberName);
+      if (oldSaveDataForSubscriber === undefined) {
+        return;
+      }
+
+      if (SAVE_DATA_MANAGER_DEBUG) {
+        log(`Merging in stored data for feature: ${subscriberName}`);
+      }
+
+      // We do not want to blow away the child tables of the existing map, because save data could
+      // contain out-of-date fields. Instead, merge it one field at a time in a recursive way (and
+      // convert Lua tables back to TypeScriptToLua Maps, if necessary).
+      merge(
+        oldSaveDataForSubscriber as LuaMap<AnyNotNil, unknown>,
+        saveData,
+        subscriberName,
+        classConstructors,
+      );
+    },
+    SAVE_DATA_MANAGER_DEBUG,
+  );
+
+  log('The save data manager loaded data from the "save#.dat" file.');
+}
+
+function readSaveDatFile(mod: Mod) {
+  const renderFrameCount = Isaac.GetFrameCount();
+
+  const [ok, jsonStringOrErrMsg] = pcall(tryLoadModData, mod);
+  if (!ok) {
+    logError(
+      `Failed to read from the "save#.dat" file on render frame ${renderFrameCount}: ${jsonStringOrErrMsg}`,
+    );
+    return DEFAULT_MOD_DATA;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (jsonStringOrErrMsg === undefined) {
+    return DEFAULT_MOD_DATA;
+  }
+
+  const jsonStringTrimmed = jsonStringOrErrMsg.trim();
+  if (jsonStringTrimmed === "") {
+    return DEFAULT_MOD_DATA;
+  }
+
+  return jsonStringTrimmed;
+}
+
+function tryLoadModData(this: void, mod: Mod) {
+  return mod.LoadData();
+}

package/src/classes/features/other/saveDataManager/restoreDefaults.ts

@@ -0,0 +1,116 @@
+// The save data manager has a feature where certain variables are automatically restored to default
+// values at certain times.
+
+import { SaveDataKey } from "../../../../enums/SaveDataKey";
+import { SerializationType } from "../../../../enums/SerializationType";
+import { deepCopy } from "../../../../functions/deepCopy";
+import { logError } from "../../../../functions/logMisc";
+import { clearTable, iterateTableInOrder } from "../../../../functions/table";
+import { SaveData } from "../../../../interfaces/SaveData";
+import { SAVE_DATA_MANAGER_DEBUG } from "./constants";
+
+const RESETTABLE_SAVE_DATA_KEYS: ReadonlySet<SaveDataKey> = new Set([
+  SaveDataKey.RUN,
+  SaveDataKey.LEVEL,
+  SaveDataKey.ROOM,
+]);
+
+export function restoreDefaultsForAllFeaturesAndKeys(
+  saveDataMap: LuaMap<string, SaveData>,
+  saveDataDefaultsMap: LuaMap<string, SaveData>,
+): void {
+  for (const saveDataKey of RESETTABLE_SAVE_DATA_KEYS.values()) {
+    restoreDefaultsForAllFeaturesKey(
+      saveDataMap,
+      saveDataDefaultsMap,
+      saveDataKey,
+    );
+  }
+}
+
+export function restoreDefaultsForAllFeaturesKey(
+  saveDataMap: LuaMap<string, SaveData>,
+  saveDataDefaultsMap: LuaMap<string, SaveData>,
+  saveDataKey: SaveDataKey,
+): void {
+  iterateTableInOrder(
+    saveDataMap,
+    (subscriberName, saveData) => {
+      restoreDefaultForFeatureKey(
+        saveDataDefaultsMap,
+        subscriberName,
+        saveData,
+        saveDataKey,
+      );
+    },
+    SAVE_DATA_MANAGER_DEBUG,
+  );
+}
+
+export function restoreDefaultForFeatureKey(
+  saveDataDefaultsMap: LuaMap<string, SaveData>,
+  subscriberName: string,
+  saveData: SaveData,
+  saveDataKey: SaveDataKey,
+): void {
+  // Only allow certain save data keys to be reset.
+  if (!RESETTABLE_SAVE_DATA_KEYS.has(saveDataKey)) {
+    error(
+      `Failed to restore default values for a save data key of "${saveDataKey}", since it is not on the allowed list of resettable save data keys.`,
+    );
+  }
+
+  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);
+  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 LuaMap<AnyNotNil, unknown>;
+
+  // We do not want to blow away the existing child table because we do not 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 LuaMap<AnyNotNil, unknown>,
+    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: LuaMap<AnyNotNil, unknown>,
+  newTable: LuaMap<AnyNotNil, unknown>,
+) {
+  clearTable(oldTable);
+
+  for (const [key, value] of newTable) {
+    oldTable.set(key, value);
+  }
+}

package/src/classes/features/other/saveDataManager/saveToDisk.ts

@@ -0,0 +1,70 @@
+import { SerializationType } from "../../../../enums/SerializationType";
+import { deepCopy } from "../../../../functions/deepCopy";
+import { jsonEncode } from "../../../../functions/jsonHelpers";
+import { log } from "../../../../functions/log";
+import { isTableEmpty, iterateTableInOrder } from "../../../../functions/table";
+import { SaveData } from "../../../../interfaces/SaveData";
+import { SAVE_DATA_MANAGER_DEBUG } from "./constants";
+
+export function saveToDisk(
+  mod: Mod,
+  saveDataMap: LuaMap<string, SaveData>,
+  saveDataConditionalFuncMap: LuaMap<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 wrote data to the "save#.dat" file.');
+}
+
+function getAllSaveDataToWriteToDisk(
+  saveDataMap: LuaMap<string, SaveData>,
+  saveDataConditionalFuncMap: LuaMap<string, () => boolean>,
+) {
+  const allSaveData = new LuaMap<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 (and any other arbitrary fields that they might
+      // have added).
+      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 (isTableEmpty(saveDataWithoutRoom as LuaTable<AnyNotNil, unknown>)) {
+        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,
+        SerializationType.SERIALIZE,
+        subscriberName,
+      );
+
+      allSaveData.set(subscriberName, saveDataCopy);
+    },
+    SAVE_DATA_MANAGER_DEBUG,
+  );
+
+  return allSaveData;
+}