isaacscript-common 11.2.3 → 12.0.0

package/src/features/customStage/versusScreen.ts

@@ -24,7 +24,7 @@ import { runNextGameFrame } from "../runInNFrames";
 import {
   CUSTOM_STAGE_FEATURE_NAME,
   ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH,
-} from "./customStageConstants";
+} from "./constants";
 import {
   CUSTOM_FLOOR_STAGE,
   CUSTOM_FLOOR_STAGE_TYPE,

package/src/features/customTrapdoor/exports.ts

@@ -2,7 +2,7 @@ import { LevelStage, StageType } from "isaac-typescript-definitions";
 import { errorIfFeaturesNotInitialized } from "../../featuresInitialized";
 import { getNextStage, getNextStageType } from "../../functions/nextStage";
 import { CustomTrapdoorDestination } from "../../interfaces/private/CustomTrapdoorDestination";
-import { CUSTOM_TRAPDOOR_FEATURE_NAME } from "./customTrapdoorConstants";
+import { CUSTOM_TRAPDOOR_FEATURE_NAME } from "./constants";
 import { spawnCustomTrapdoorToDestination } from "./spawn";
 
 /**

package/src/features/customTrapdoor/init.ts

@@ -25,7 +25,7 @@ import {
   CUSTOM_TRAPDOOR_FEATURE_NAME,
   GridEntityTypeCustom,
   PIXELATION_TO_BLACK_FRAMES,
-} from "./customTrapdoorConstants";
+} from "./constants";
 import { checkCustomTrapdoorOpenClose } from "./openClose";
 import { checkCustomTrapdoorPlayerTouched } from "./touched";
 import v from "./v";

package/src/features/customTrapdoor/openClose.ts

@@ -8,7 +8,7 @@ import {
   TRAPDOOR_BOSS_REACTION_FRAMES,
   TRAPDOOR_OPEN_DISTANCE,
   TRAPDOOR_OPEN_DISTANCE_AFTER_BOSS,
-} from "./customTrapdoorConstants";
+} from "./constants";
 
 export function checkCustomTrapdoorOpenClose(
   gridEntity: GridEntity,

package/src/features/customTrapdoor/spawn.ts

@@ -6,7 +6,7 @@ import { isVector } from "../../functions/vector";
 import { CustomTrapdoorDescription } from "../../interfaces/private/CustomTrapdoorDescription";
 import { CustomTrapdoorDestination } from "../../interfaces/private/CustomTrapdoorDestination";
 import { spawnCustomGridEntity } from "../customGridEntity";
-import { GridEntityTypeCustom } from "./customTrapdoorConstants";
+import { GridEntityTypeCustom } from "./constants";
 import { shouldTrapdoorSpawnOpen } from "./openClose";
 import v from "./v";
 

package/src/features/customTrapdoor/touched.ts

@@ -24,7 +24,7 @@ import {
   OTHER_PLAYER_TRAPDOOR_JUMP_DELAY_GAME_FRAMES,
   OTHER_PLAYER_TRAPDOOR_JUMP_DURATION_GAME_FRAMES,
   TRAPDOOR_TOUCH_DISTANCE,
-} from "./customTrapdoorConstants";
+} from "./constants";
 import v from "./v";
 
 export function checkCustomTrapdoorPlayerTouched(

package/src/features/saveDataManager/constants.ts

@@ -0,0 +1,15 @@
+import { SaveDataKey } from "../../enums/SaveDataKey";
+
+/** Set this to true to enable more verbosity in the save data manger. */
+export const SAVE_DATA_MANAGER_DEBUG = false as boolean;
+
+export const SAVE_DATA_MANAGER_FEATURE_NAME = "save data manager";
+
+/**
+ * When the Glowing Hour Glass is used, certain save data keys will automatically be restored to a
+ * backup.
+ */
+export const SAVE_DATA_MANAGER_GLOWING_HOUR_GLASS_BACKUP_KEYS = [
+  SaveDataKey.RUN,
+  SaveDataKey.LEVEL,
+];

package/src/features/saveDataManager/exports.ts

@@ -4,6 +4,7 @@ import { errorIfFeaturesNotInitialized } from "../../featuresInitialized";
 import { deepCopy } from "../../functions/deepCopy";
 import { isString } from "../../functions/types";
 import { SaveData } from "../../interfaces/SaveData";
+import { SAVE_DATA_MANAGER_FEATURE_NAME } from "./constants";
 import {
   forceSaveDataManagerLoad,
   forceSaveDataManagerSave,
@@ -14,7 +15,6 @@ import {
   saveDataDefaultsMap,
   saveDataMap,
 } from "./maps";
-import { SAVE_DATA_MANAGER_FEATURE_NAME } from "./saveDataManagerConstants";
 
 /**
  * This is the entry point to the save data manager, a system which provides two major features:
@@ -88,9 +88,14 @@ import { SAVE_DATA_MANAGER_FEATURE_NAME } from "./saveDataManagerConstants";
  * data manager cannot do this on its own because it cannot know when your mod features are finished
  * initializing.)
  *
- * Finally, some features may have variables that need to be automatically reset per run/level, but
- * not saved to disk on game exit. (For example, if they contain functions or other non-serializable
- * data.) For these cases, set the second argument to `() => false`.
+ * Some features may have variables that need to be automatically reset per run/level, but not saved
+ * to disk on game exit. (For example, if they contain functions or other non-serializable data.)
+ * For these cases, set the second argument to `() => false`.
+ *
+ * Note that when the player uses Glowing Hour Glass, the save data manager will automatically
+ * restore any variables on a "run" or "level" object with a backup that was created when the room
+ * was entered. Thus, you should not have to explicitly program support for Glowing Hour Glass into
+ * your mod features that use the save data manager.
  *
  * @param key The name of the file or feature that is submitting data to be managed by the save data
  *            manager. The save data manager will throw an error if the key is already registered.

package/src/features/saveDataManager/load.ts

@@ -3,11 +3,11 @@ import { log, logError } from "../../functions/log";
 import { iterateTableInOrder } from "../../functions/table";
 import { isString, isTable } from "../../functions/types";
 import { SaveData } from "../../interfaces/SaveData";
-import { merge } from "./merge";
 import {
   SAVE_DATA_MANAGER_DEBUG,
   SAVE_DATA_MANAGER_FEATURE_NAME,
-} from "./saveDataManagerConstants";
+} from "./constants";
+import { merge } from "./merge";
 
 const DEFAULT_MOD_DATA = "{}";
 
@@ -31,33 +31,37 @@ export function loadFromDisk(
   // Second, iterate over all the fields of the new table.)
   iterateTableInOrder(
     newSaveData,
-    (key, value) => {
+    (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(key)) {
+      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(value)) {
+      // `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(key);
+      const oldSaveDataForSubscriber = oldSaveData.get(subscriberName);
       if (oldSaveDataForSubscriber === undefined) {
         return;
       }
 
       if (SAVE_DATA_MANAGER_DEBUG) {
-        log(`Merging in stored data for feature: ${key}`);
+        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>, value, key);
+      merge(
+        oldSaveDataForSubscriber as LuaMap<AnyNotNil, unknown>,
+        saveData,
+        subscriberName,
+      );
     },
     SAVE_DATA_MANAGER_DEBUG,
   );

package/src/features/saveDataManager/main.ts

@@ -9,17 +9,20 @@ import { logError } from "../../functions/log";
 import { onFirstFloor } from "../../functions/stage";
 import { clearTable, iterateTableInOrder } from "../../functions/table";
 import { SaveData } from "../../interfaces/SaveData";
+import {
+  SAVE_DATA_MANAGER_DEBUG,
+  SAVE_DATA_MANAGER_FEATURE_NAME,
+  SAVE_DATA_MANAGER_GLOWING_HOUR_GLASS_BACKUP_KEYS,
+} from "./constants";
 import { loadFromDisk } from "./load";
 import {
   saveDataConditionalFuncMap,
   saveDataDefaultsMap,
+  saveDataGlowingHourGlassMap,
   saveDataMap,
 } from "./maps";
+import { merge } from "./merge";
 import { saveToDisk } from "./save";
-import {
-  SAVE_DATA_MANAGER_DEBUG,
-  SAVE_DATA_MANAGER_FEATURE_NAME,
-} from "./saveDataManagerConstants";
 
 const RESETTABLE_SAVE_DATA_KEYS: ReadonlySet<SaveDataKey> = new Set([
   SaveDataKey.RUN,
@@ -29,6 +32,7 @@ const RESETTABLE_SAVE_DATA_KEYS: ReadonlySet<SaveDataKey> = new Set([
 
 let mod: ModUpgraded | null = null;
 let loadedDataOnThisRun = false;
+let restoreGlowingHourGlassDataOnNextRoom = false;
 
 export function saveDataManagerInit(incomingMod: ModUpgraded): void {
   mod = incomingMod;
@@ -50,6 +54,7 @@ export function saveDataManagerInit(incomingMod: ModUpgraded): void {
 // ModCallback.POST_USE_ITEM (3)
 // CollectibleType.GLOWING_HOUR_GLASS (422)
 function postUseItemGlowingHourGlass() {
+  restoreGlowingHourGlassDataOnNextRoom = true;
   return undefined;
 }
 
@@ -118,6 +123,75 @@ function postNewLevel() {
 // ModCallbackCustom.POST_NEW_ROOM_EARLY
 function postNewRoomEarly() {
   restoreDefaults(SaveDataKey.ROOM);
+
+  // Handle the Glowing Hour Glass.
+  if (restoreGlowingHourGlassDataOnNextRoom) {
+    restoreGlowingHourGlassDataOnNextRoom = false;
+    restoreGlowingHourGlassBackup();
+  } else {
+    makeGlowingHourGlassBackup();
+  }
+}
+
+function makeGlowingHourGlassBackup() {
+  iterateTableInOrder(
+    saveDataMap,
+    (subscriberName, saveData) => {
+      for (const saveDataKey of SAVE_DATA_MANAGER_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;
+        }
+
+        let saveDataGlowingHourGlass =
+          saveDataGlowingHourGlassMap.get(subscriberName);
+        if (saveDataGlowingHourGlass === undefined) {
+          saveDataGlowingHourGlass = new LuaMap<string, unknown>() as SaveData;
+        }
+
+        const copiedChildTable = deepCopy(childTable);
+        saveDataGlowingHourGlass[saveDataKey] = copiedChildTable;
+      }
+    },
+    SAVE_DATA_MANAGER_DEBUG,
+  );
+}
+
+function restoreGlowingHourGlassBackup() {
+  iterateTableInOrder(
+    saveDataMap,
+    (subscriberName, saveData) => {
+      for (const saveDataKey of SAVE_DATA_MANAGER_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;
+        }
+
+        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`,
+        );
+      }
+    },
+    SAVE_DATA_MANAGER_DEBUG,
+  );
 }
 
 function restoreDefaultsAll() {

package/src/features/saveDataManager/maps.ts

@@ -9,3 +9,9 @@ export const saveDataMap = new LuaMap<string, SaveData>();
 
 export const saveDataDefaultsMap = new LuaMap<string, SaveData>();
 export const saveDataConditionalFuncMap = new LuaMap<string, () => boolean>();
+
+/**
+ * We backup some save data keys on every new room for the purposes of restoring it when Glowing
+ * Hour Glass is used.
+ */
+export const saveDataGlowingHourGlassMap = new LuaMap<string, SaveData>();

package/src/features/saveDataManager/merge.ts

@@ -11,7 +11,7 @@ import { clearTable, iterateTableInOrder } from "../../functions/table";
 import { isDefaultMap, isTSTLMap, isTSTLSet } from "../../functions/tstlClass";
 import { isTable } from "../../functions/types";
 import { getTraversalDescription } from "../../functions/utils";
-import { SAVE_DATA_MANAGER_DEBUG } from "./saveDataManagerConstants";
+import { SAVE_DATA_MANAGER_DEBUG } from "./constants";
 import { isSerializationBrand } from "./serializationBrands";
 
 /**

package/src/features/saveDataManager/save.ts

@@ -7,7 +7,7 @@ import { SaveData } from "../../interfaces/SaveData";
 import {
   SAVE_DATA_MANAGER_DEBUG,
   SAVE_DATA_MANAGER_FEATURE_NAME,
-} from "./saveDataManagerConstants";
+} from "./constants";
 
 export function saveToDisk(
   mod: Mod,

package/src/functions/charge.ts

@@ -40,8 +40,12 @@ export function addCharge(
 ): int {
   const hud = game.GetHUD();
 
-  // Ensure that there is enough space on the active item to store these amount of charges.
-  const chargesToAdd = getClampedChargesToAdd(player, activeSlot, numCharges);
+  // Ensure that there is enough space on the active item to store these amount of charges. (If we
+  // add too many charges, it will grant orange "battery" charges, even if the player does not have
+  // The Battery.)
+  const chargesAwayFromMax = getChargesAwayFromMax(player, activeSlot);
+  const chargesToAdd =
+    numCharges > chargesAwayFromMax ? chargesAwayFromMax : numCharges;
 
   // The AAA Battery trinket might grant an additional charge.
   const modifiedChargesToAdd = getChargesToAddWithAAAModifier(
@@ -139,46 +143,18 @@ export function addRoomClearChargeToSlot(
   const room = game.GetRoom();
   const roomShape = room.GetRoomShape();
 
-  const numCharges = bigRoomDoubleCharge ? getRoomShapeCharges(roomShape) : 1;
-  addCharge(player, activeSlot, numCharges, playSoundEffect);
-}
+  // Big rooms grant two charges and normal rooms grant one charge.
+  let numCharges = bigRoomDoubleCharge ? getRoomShapeCharges(roomShape) : 1;
 
-/**
- * We don't want to add more charges than is normally possible, so we must check to see if the
- * player can hold the specified amount of charges in the given slot.
- */
-function getClampedChargesToAdd(
-  player: EntityPlayer,
-  activeSlot: ActiveSlot,
-  numCharges: int,
-) {
-  const activeItem = player.GetActiveItem(activeSlot);
-  const activeCharge = player.GetActiveCharge(activeSlot);
-  const batteryCharge = player.GetBatteryCharge(activeSlot);
-  const hasBattery = player.HasCollectible(CollectibleType.BATTERY);
-  const maxCharges = getCollectibleMaxCharges(activeItem);
-
-  if (!hasBattery && activeCharge === maxCharges) {
-    return 0;
-  }
-
-  if (hasBattery && batteryCharge === maxCharges) {
-    return 0;
+  // Handle the special case of a timed item. When clearing a room with a timed item, it should
+  // become fully charged.
+  if (chargeType === ItemConfigChargeType.TIMED) {
+    // The charges will become clamped to the proper amount in the `addCharge` function. (If the
+    // item is at 50% charge and the player has The Battery, it should go to 150% charged.)
+    numCharges = getCollectibleMaxCharges(activeItem);
   }
 
-  if (!hasBattery && activeCharge + 1 === maxCharges) {
-    // We are only 1 charge away from a full charge, so only add one charge to avoid an overcharge.
-    // (It is possible to set orange charges without the player actually having The Battery.)
-    return 1;
-  }
-
-  if (hasBattery && batteryCharge + 1 === maxCharges) {
-    // We are only 1 charge away from a full double-charge, so only add one charge to avoid an
-    // overcharge.
-    return 1;
-  }
-
-  return numCharges;
+  addCharge(player, activeSlot, numCharges, playSoundEffect);
 }
 
 /**
@@ -190,26 +166,14 @@ function getChargesToAddWithAAAModifier(
   activeSlot: ActiveSlot,
   chargesToAdd: int,
 ) {
-  const activeItem = player.GetActiveItem(activeSlot);
-  const activeCharge = player.GetActiveCharge(activeSlot);
-  const batteryCharge = player.GetBatteryCharge(activeSlot);
-  const hasBattery = player.HasCollectible(CollectibleType.BATTERY);
   const hasAAABattery = player.HasTrinket(TrinketType.AAA_BATTERY);
-  const maxCharges = getCollectibleMaxCharges(activeItem);
-
   if (!hasAAABattery) {
     return chargesToAdd;
   }
 
-  if (!hasBattery && activeCharge + chargesToAdd === maxCharges - 1) {
-    return chargesToAdd + 1;
-  }
-
-  if (hasBattery && batteryCharge + chargesToAdd === maxCharges - 1) {
-    return chargesToAdd + 1;
-  }
-
-  return chargesToAdd;
+  const chargesAwayFromMax = getChargesAwayFromMax(player, activeSlot);
+  const AAABatteryShouldApply = chargesToAdd === chargesAwayFromMax - 1;
+  return AAABatteryShouldApply ? chargesToAdd + 1 : chargesToAdd;
 }
 
 /**
@@ -231,6 +195,27 @@ export function addRoomClearCharges(bigRoomDoubleCharge = true): void {
   }
 }
 
+/**
+ * Helper function to get the amount of charges away from the maximum charge that a particular
+ * player is.
+ *
+ * This function accounts for The Battery. For example, if the player has 2/6 charges on a D6, this
+ * function will return 10 (because there are 4 charges remaining on the base charge and 6 charges
+ * remaining on The Battery charge).
+ */
+export function getChargesAwayFromMax(
+  player: EntityPlayer,
+  activeSlot: ActiveSlot,
+): int {
+  const totalCharge = getTotalCharge(player, activeSlot);
+  const activeItem = player.GetActiveItem(activeSlot);
+  const hasBattery = player.HasCollectible(CollectibleType.BATTERY);
+  const maxCharges = getCollectibleMaxCharges(activeItem);
+  const effectiveMaxCharges = hasBattery ? maxCharges * 2 : maxCharges;
+
+  return effectiveMaxCharges - totalCharge;
+}
+
 /**
  * Helper function to get the combined normal charge and the battery charge for the player's active
  * item. This is useful because you have to add these two values together when setting the active

package/src/functions/deepCopy.ts

@@ -1,7 +1,7 @@
 import { DefaultMap } from "../classes/DefaultMap";
 import { SerializationBrand } from "../enums/private/SerializationBrand";
 import { SerializationType } from "../enums/SerializationType";
-import { SAVE_DATA_MANAGER_DEBUG } from "../features/saveDataManager/saveDataManagerConstants";
+import { SAVE_DATA_MANAGER_DEBUG } from "../features/saveDataManager/constants";
 import { isSerializationBrand } from "../features/saveDataManager/serializationBrands";
 import { TSTLClass } from "../types/TSTLClass";
 import { isArray } from "./array";

package/dist/src/features/customStage/customStageConstants.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"customStageConstants.d.ts","sourceRoot":"","sources":["../../../../src/features/customStage/customStageConstants.ts"],"names":[],"mappings":";AAAA,eAAO,MAAM,yBAAyB,gBAAgB,CAAC;AAEvD,eAAO,MAAM,iCAAiC,iCAAiC,CAAC;AAEhF,uCAAuC;AACvC,oBAAY,iBAAiB;IAC3B,IAAI,IAAA;IACJ,IAAI,IAAA;IACJ,SAAS,IAAA;CACV;AAED,uCAAuC;AACvC,eAAO,MAAM,8BAA8B,EAAE;IAC3C,QAAQ,EAAE,GAAG,IAAI,iBAAiB,GAAG,GAAG;CAKhC,CAAC"}

package/dist/src/features/customTrapdoor/customTrapdoorConstants.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"customTrapdoorConstants.d.ts","sourceRoot":"","sources":["../../../../src/features/customTrapdoor/customTrapdoorConstants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAE9D,eAAO,MAAM,4BAA4B,mBAAmB,CAAC;AAE7D,eAAO,MAAM,oBAAoB;IAC/B;;;OAGG;;CAEK,CAAC;AAEX,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,eAAO,MAAM,iCAAiC,QAA+B,CAAC;AAC9E,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C,eAAO,MAAM,oCAAoC,EAAE,WAAW,CAAC,MAAM,CAClC,CAAC;AAEpC,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C,eAAO,MAAM,4CAA4C,IAAI,CAAC;AAC9D,eAAO,MAAM,+CAA+C,IAAI,CAAC"}

package/dist/src/features/saveDataManager/saveDataManagerConstants.d.ts

@@ -1,4 +0,0 @@
-/** Set this to true to enable more verbosity in the save data manger. */
-export declare const SAVE_DATA_MANAGER_DEBUG: boolean;
-export declare const SAVE_DATA_MANAGER_FEATURE_NAME = "save data manager";
-//# sourceMappingURL=saveDataManagerConstants.d.ts.map

package/dist/src/features/saveDataManager/saveDataManagerConstants.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"saveDataManagerConstants.d.ts","sourceRoot":"","sources":["../../../../src/features/saveDataManager/saveDataManagerConstants.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,eAAO,MAAM,uBAAuB,SAAmB,CAAC;AAExD,eAAO,MAAM,8BAA8B,sBAAsB,CAAC"}

package/dist/src/features/saveDataManager/saveDataManagerConstants.lua

@@ -1,5 +0,0 @@
-local ____exports = {}
---- Set this to true to enable more verbosity in the save data manger.
-____exports.SAVE_DATA_MANAGER_DEBUG = false
-____exports.SAVE_DATA_MANAGER_FEATURE_NAME = "save data manager"
-return ____exports

package/src/features/saveDataManager/saveDataManagerConstants.ts

@@ -1,4 +0,0 @@
-/** Set this to true to enable more verbosity in the save data manger. */
-export const SAVE_DATA_MANAGER_DEBUG = false as boolean;
-
-export const SAVE_DATA_MANAGER_FEATURE_NAME = "save data manager";