isaacscript-common 2.3.0 → 3.0.0

package/features/runInNFrames.lua

@@ -0,0 +1,128 @@
+local ____lualib = require("lualib_bundle")
+local __TS__ArrayForEach = ____lualib.__TS__ArrayForEach
+local __TS__ArraySplice = ____lualib.__TS__ArraySplice
+local ____exports = {}
+local postUpdate, postRender, checkExecuteQueuedFunctions, v
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local ModCallback = ____isaac_2Dtypescript_2Ddefinitions.ModCallback
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+local ____featuresInitialized = require("featuresInitialized")
+local errorIfFeaturesNotInitialized = ____featuresInitialized.errorIfFeaturesNotInitialized
+local ____exports = require("features.saveDataManager.exports")
+local saveDataManager = ____exports.saveDataManager
+function postUpdate(self)
+    local gameFrameCount = game:GetFrameCount()
+    checkExecuteQueuedFunctions(nil, gameFrameCount, v.run.queuedGameFunctionTuples)
+end
+function postRender(self)
+    local renderFrameCount = Isaac.GetFrameCount()
+    checkExecuteQueuedFunctions(nil, renderFrameCount, v.run.queuedRenderFunctionTuples)
+end
+function checkExecuteQueuedFunctions(self, frameCount, functionTuples)
+    local functionsToFire = {}
+    local indexesToRemove = {}
+    __TS__ArrayForEach(
+        functionTuples,
+        function(____, functionTuple, i)
+            local frame, func = table.unpack(functionTuple)
+            if frameCount >= frame then
+                functionsToFire[#functionsToFire + 1] = func
+                indexesToRemove[#indexesToRemove + 1] = i
+            end
+        end
+    )
+    for ____, indexToRemove in ipairs(indexesToRemove) do
+        __TS__ArraySplice(functionTuples, indexToRemove, 1)
+    end
+    for ____, func in ipairs(functionsToFire) do
+        func(nil)
+    end
+end
+local FEATURE_NAME = "run in N frames"
+v = {run = {queuedGameFunctionTuples = {}, queuedRenderFunctionTuples = {}}}
+---
+-- @internal
+function ____exports.runInNFramesInit(self, mod)
+    saveDataManager(
+        nil,
+        "runInNFrames",
+        v,
+        function() return false end
+    )
+    mod:AddCallback(ModCallback.POST_UPDATE, postUpdate)
+    mod:AddCallback(ModCallback.POST_RENDER, postRender)
+end
+--- Supply a function to run N game frames from now in the PostUpdate callback.
+-- 
+-- For a usage example, see the documentation for the `runNextGameFrame`, which is used in a similar
+-- way.
+-- 
+-- Note that this function will not handle saving and quitting. If a player saving and quitting
+-- before the deferred function fires would cause a bug in your mod, then you should handle deferred
+-- functions manually using serializable data.
+function ____exports.runInNGameFrames(self, func, gameFrames)
+    errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
+    local gameFrameCount = game:GetFrameCount()
+    local functionFireFrame = gameFrameCount + gameFrames
+    local tuple = {functionFireFrame, func}
+    local ____v_run_queuedGameFunctionTuples_0 = v.run.queuedGameFunctionTuples
+    ____v_run_queuedGameFunctionTuples_0[#____v_run_queuedGameFunctionTuples_0 + 1] = tuple
+end
+--- Supply a function to run N render frames from now in the PostRender callback.
+-- 
+-- For a usage example, see the documentation for the `runNextGameFrame`, which is used in a similar
+-- way.
+-- 
+-- Note that this function will not handle saving and quitting. If a player saving and quitting
+-- before the deferred function fires would cause a bug in your mod, then you should handle deferred
+-- functions manually using serializable data.
+function ____exports.runInNRenderFrames(self, func, renderFrames)
+    errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
+    local renderFrameCount = Isaac.GetFrameCount()
+    local functionFireFrame = renderFrameCount + renderFrames
+    local tuple = {functionFireFrame, func}
+    local ____v_run_queuedRenderFunctionTuples_1 = v.run.queuedRenderFunctionTuples
+    ____v_run_queuedRenderFunctionTuples_1[#____v_run_queuedRenderFunctionTuples_1 + 1] = tuple
+end
+--- Supply a function to run on the next PostUpdate callback.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const NUM_EXPLODER_EXPLOSIONS = 5;
+-- 
+-- function useItemExploder(player: EntityPlayer) {
+--   playSound("exploderBegin");
+--   explode(player, NUM_EXPLODER_EXPLOSIONS);
+-- }
+-- 
+-- function explode(player: EntityPlayer, numFramesLeft: int) {
+--   Isaac.Explode(player, undefined, 1);
+--   numFramesLeft -= 1;
+--   if (numFramesLeft === 0) {
+--     runNextFrame(() => {
+--       explode(player, numFramesLeft);
+--     });
+--   }
+-- }
+-- ```
+-- 
+-- Note that this function will not handle saving and quitting. If a player saving and quitting
+-- before the deferred function fires would cause a bug in your mod, then you should handle deferred
+-- functions manually using serializable data.
+function ____exports.runNextGameFrame(self, func)
+    errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
+    ____exports.runInNGameFrames(nil, func, 1)
+end
+--- Supply a function to run on the next PostRender callback.
+-- 
+-- For a usage example, see the documentation for the `runNextGameFrame`, which is used in a similar
+-- way.
+-- 
+-- Note that this function will not handle saving and quitting.
+function ____exports.runNextRenderFrame(self, func)
+    errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
+    ____exports.runInNRenderFrames(nil, func, 1)
+end
+return ____exports

package/features/saveDataManager/constants.d.ts

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

package/features/saveDataManager/constants.lua

@@ -0,0 +1,5 @@
+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/features/saveDataManager/exports.d.ts

@@ -0,0 +1,131 @@
+import { SaveData } from "../../interfaces/SaveData";
+/**
+ * This is the entry point to the save data manager, a system which provides two major features:
+ *
+ * 1. automatic resetting of variables on a new run, on a new level, or on a new room (as desired)
+ * 2. automatic saving and loading of all tracked data to the "save#.dat" file
+ *
+ * You feed this function with an anonymous object containing your variables, and then it will
+ * automatically manage them for you. (See below for an example.)
+ *
+ * The save data manager is meant to be called once for each feature of your mod. In other words,
+ * you should not put all of the data for your mod on the same object. Instead, scope your variables
+ * locally to a single file that contains a mod feature, and then call this function to register
+ * them. For example:
+ *
+ * ```ts
+ * // in file: feature1.ts
+ * import { saveDataManager } from "isaacscript-common";
+ *
+ * // Declare local variables for this file or feature.
+ * const v = {
+ *   // These variables are never reset; manage them yourself at will.
+ *   persistent: {
+ *     foo1: 0,
+ *   },
+ *
+ *   // These variables are reset at the beginning of every run.
+ *   run: {
+ *     foo2: 0,
+ *   },
+ *
+ *   // These variables are reset at the beginning of every level.
+ *   level: {
+ *     foo3: 0,
+ *   },
+ *
+ *   // These variables are reset at the beginning of every room.
+ *   room: {
+ *     foo4: 0,
+ *   },
+ * };
+ * // Every child object is optional; only create the ones that you need.
+ *
+ * // Register the variables with the save data manager. (We need to provide a string key that
+ * // matches the name of this file.)
+ * function feature1Init() {
+ *   saveDataManager("feature1", v);
+ * }
+ *
+ * // Elsewhere in the file, use your variables.
+ * function feature1Function() {
+ *   if (v.run.foo1 > 0) {
+ *     // Insert code here.
+ *   }
+ * }
+ * ```
+ *
+ * - Save data is loaded from disk in the `POST_PLAYER_INIT` callback (i.e. the first callback that
+ *   can possibly run).
+ * - Save data is recorded to disk in the `PRE_GAME_EXIT` callback.
+ *
+ * Note that before using the save data manager, you must call the `upgradeMod` function. (Upgrade
+ * your mod before registering any of your own callbacks so that the save data manager will run
+ * before any of your code does.)
+ *
+ * If you want the save data manager to load data before the `POST_PLAYER_INIT` callback (i.e. in
+ * the main menu), then you should explicitly call the `saveDataManagerLoad` function. (The save
+ * 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`.
+ *
+ * @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.
+ * @param v An object that corresponds to the `SaveData` interface. The object is conventionally
+ *          called "v" for brevity. ("v" is short for "local variables").
+ * @param conditionalFunc An optional function to run upon saving this key to disk. For example,
+ *                        this allows features to only save data to disk if the feature is enabled.
+ *                        Specify a value of `() => false` to completely disable saving this feature
+ *                        to disk. Disabling saving to disk is useful if you are using data that is
+ *                        not serializable. Alternatively, it could be useful if you want to use the
+ *                        save data manager to automatically reset variables on run/level/room, but
+ *                        not clutter the the "save#.dat" file with unnecessary keys.
+ */
+export declare function saveDataManager(key: string, v: SaveData, conditionalFunc?: () => boolean): void;
+/**
+ * The save data manager will automatically load variables from disk at the appropriate times (i.e.
+ * when a new run is started). Use this function to explicitly force the save data manager to load
+ * all of its variables from disk immediately.
+ *
+ * Obviously, doing this will overwrite the current data, so using this function can potentially
+ * result in lost state.
+ */
+export declare function saveDataManagerLoad(): void;
+/**
+ * The save data manager will automatically save variables to disk at the appropriate times (i.e.
+ * when the run is exited). Use this function to explicitly force the save data manager to write all
+ * of its variables to disk immediately.
+ */
+export declare function saveDataManagerSave(): void;
+/**
+ * - Sets the global variable of "g" equal to all of the save data variables for this mod.
+ * - Sets the global variable of "gd" equal to all of the save data default variables for this mod.
+ *
+ * This can make debugging easier, as you can access the variables from the game's debug console.
+ * e.g. `l print(g.feature1.foo)`
+ */
+export declare function saveDataManagerSetGlobal(): void;
+/**
+ * The save data manager will automatically reset variables at the appropriate times (i.e. when a
+ * player enters a new room). Use this function to explicitly force the save data manager to reset a
+ * specific variable group.
+ *
+ * For example:
+ *
+ * ```ts
+ * const v = {
+ *   room: {
+ *     foo: 123,
+ *   },
+ * };
+ *
+ * saveDataManager("file1", v);
+ *
+ * // Then, later on, to explicit reset all of the "room" variables:
+ * saveDataManagerReset("file1", "room");
+ * ```
+ */
+export declare function saveDataManagerReset(key: string, childObjectKey: string): void;

package/features/saveDataManager/exports.lua

@@ -0,0 +1,181 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local __TS__ObjectKeys = ____lualib.__TS__ObjectKeys
+local ____exports = {}
+local ____SerializationType = require("enums.SerializationType")
+local SerializationType = ____SerializationType.SerializationType
+local ____featuresInitialized = require("featuresInitialized")
+local errorIfFeaturesNotInitialized = ____featuresInitialized.errorIfFeaturesNotInitialized
+local ____deepCopy = require("functions.deepCopy")
+local deepCopy = ____deepCopy.deepCopy
+local ____constants = require("features.saveDataManager.constants")
+local SAVE_DATA_MANAGER_FEATURE_NAME = ____constants.SAVE_DATA_MANAGER_FEATURE_NAME
+local ____main = require("features.saveDataManager.main")
+local forceSaveDataManagerLoad = ____main.forceSaveDataManagerLoad
+local forceSaveDataManagerSave = ____main.forceSaveDataManagerSave
+local restoreDefaultSaveData = ____main.restoreDefaultSaveData
+local ____maps = require("features.saveDataManager.maps")
+local saveDataConditionalFuncMap = ____maps.saveDataConditionalFuncMap
+local saveDataDefaultsMap = ____maps.saveDataDefaultsMap
+local saveDataMap = ____maps.saveDataMap
+--- This is the entry point to the save data manager, a system which provides two major features:
+-- 
+-- 1. automatic resetting of variables on a new run, on a new level, or on a new room (as desired)
+-- 2. automatic saving and loading of all tracked data to the "save#.dat" file
+-- 
+-- You feed this function with an anonymous object containing your variables, and then it will
+-- automatically manage them for you. (See below for an example.)
+-- 
+-- The save data manager is meant to be called once for each feature of your mod. In other words,
+-- you should not put all of the data for your mod on the same object. Instead, scope your variables
+-- locally to a single file that contains a mod feature, and then call this function to register
+-- them. For example:
+-- 
+-- ```ts
+-- // in file: feature1.ts
+-- import { saveDataManager } from "isaacscript-common";
+-- 
+-- // Declare local variables for this file or feature.
+-- const v = {
+--   // These variables are never reset; manage them yourself at will.
+--   persistent: {
+--     foo1: 0,
+--   },
+-- 
+--   // These variables are reset at the beginning of every run.
+--   run: {
+--     foo2: 0,
+--   },
+-- 
+--   // These variables are reset at the beginning of every level.
+--   level: {
+--     foo3: 0,
+--   },
+-- 
+--   // These variables are reset at the beginning of every room.
+--   room: {
+--     foo4: 0,
+--   },
+-- };
+-- // Every child object is optional; only create the ones that you need.
+-- 
+-- // Register the variables with the save data manager. (We need to provide a string key that
+-- // matches the name of this file.)
+-- function feature1Init() {
+--   saveDataManager("feature1", v);
+-- }
+-- 
+-- // Elsewhere in the file, use your variables.
+-- function feature1Function() {
+--   if (v.run.foo1 > 0) {
+--     // Insert code here.
+--   }
+-- }
+-- ```
+-- 
+-- - Save data is loaded from disk in the `POST_PLAYER_INIT` callback (i.e. the first callback that
+--   can possibly run).
+-- - Save data is recorded to disk in the `PRE_GAME_EXIT` callback.
+-- 
+-- Note that before using the save data manager, you must call the `upgradeMod` function. (Upgrade
+-- your mod before registering any of your own callbacks so that the save data manager will run
+-- before any of your code does.)
+-- 
+-- If you want the save data manager to load data before the `POST_PLAYER_INIT` callback (i.e. in
+-- the main menu), then you should explicitly call the `saveDataManagerLoad` function. (The save
+-- 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`.
+-- 
+-- @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.
+-- @param v An object that corresponds to the `SaveData` interface. The object is conventionally
+-- called "v" for brevity. ("v" is short for "local variables").
+-- @param conditionalFunc An optional function to run upon saving this key to disk. For example,
+-- this allows features to only save data to disk if the feature is enabled.
+-- Specify a value of `() => false` to completely disable saving this feature
+-- to disk. Disabling saving to disk is useful if you are using data that is
+-- not serializable. Alternatively, it could be useful if you want to use the
+-- save data manager to automatically reset variables on run/level/room, but
+-- not clutter the the "save#.dat" file with unnecessary keys.
+function ____exports.saveDataManager(self, key, v, conditionalFunc)
+    errorIfFeaturesNotInitialized(nil, SAVE_DATA_MANAGER_FEATURE_NAME)
+    local keyType = type(key)
+    if keyType ~= "string" then
+        error((("The " .. SAVE_DATA_MANAGER_FEATURE_NAME) .. " requires that keys are strings. You tried to use a key of type: ") .. keyType)
+    end
+    if saveDataMap[key] ~= nil then
+        error((("The " .. SAVE_DATA_MANAGER_FEATURE_NAME) .. " is already managing save data for a key of: ") .. key)
+    end
+    saveDataMap[key] = v
+    local saveDataKeys = __TS__ObjectKeys(v)
+    if #saveDataKeys == 1 and saveDataKeys[1] == "room" then
+        conditionalFunc = function() return false end
+    end
+    local saveDataTable = v
+    local saveDataCopy = deepCopy(nil, saveDataTable, SerializationType.NONE, key)
+    saveDataDefaultsMap[key] = saveDataCopy
+    if conditionalFunc ~= nil then
+        saveDataConditionalFuncMap:set(key, conditionalFunc)
+    end
+end
+--- The save data manager will automatically load variables from disk at the appropriate times (i.e.
+-- when a new run is started). Use this function to explicitly force the save data manager to load
+-- all of its variables from disk immediately.
+-- 
+-- Obviously, doing this will overwrite the current data, so using this function can potentially
+-- result in lost state.
+function ____exports.saveDataManagerLoad(self)
+    errorIfFeaturesNotInitialized(nil, SAVE_DATA_MANAGER_FEATURE_NAME)
+    forceSaveDataManagerLoad(nil)
+end
+--- The save data manager will automatically save variables to disk at the appropriate times (i.e.
+-- when the run is exited). Use this function to explicitly force the save data manager to write all
+-- of its variables to disk immediately.
+function ____exports.saveDataManagerSave(self)
+    errorIfFeaturesNotInitialized(nil, SAVE_DATA_MANAGER_FEATURE_NAME)
+    forceSaveDataManagerSave(nil)
+end
+--- - Sets the global variable of "g" equal to all of the save data variables for this mod.
+-- - Sets the global variable of "gd" equal to all of the save data default variables for this mod.
+-- 
+-- This can make debugging easier, as you can access the variables from the game's debug console.
+-- e.g. `l print(g.feature1.foo)`
+function ____exports.saveDataManagerSetGlobal(self)
+    g = saveDataMap
+    gd = saveDataDefaultsMap
+end
+--- The save data manager will automatically reset variables at the appropriate times (i.e. when a
+-- player enters a new room). Use this function to explicitly force the save data manager to reset a
+-- specific variable group.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const v = {
+--   room: {
+--     foo: 123,
+--   },
+-- };
+-- 
+-- saveDataManager("file1", v);
+-- 
+-- // Then, later on, to explicit reset all of the "room" variables:
+-- saveDataManagerReset("file1", "room");
+-- ```
+function ____exports.saveDataManagerReset(self, key, childObjectKey)
+    errorIfFeaturesNotInitialized(nil, SAVE_DATA_MANAGER_FEATURE_NAME)
+    local keyType = type(key)
+    if keyType ~= "string" then
+        error((("The " .. SAVE_DATA_MANAGER_FEATURE_NAME) .. " requires that keys are strings. You tried to use a key of type: ") .. keyType)
+    end
+    local saveData = saveDataMap[key]
+    if saveData == nil then
+        error((("The " .. SAVE_DATA_MANAGER_FEATURE_NAME) .. " is not managing save data for a key of: ") .. key)
+    end
+    restoreDefaultSaveData(nil, key, saveData, childObjectKey)
+end
+return ____exports

package/features/saveDataManager/load.d.ts

@@ -0,0 +1,4 @@
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="typescript-to-lua/language-extensions" />
+import { SaveData } from "../../interfaces/SaveData";
+export declare function loadFromDisk(mod: Mod, oldSaveData: LuaTable<string, SaveData>): void;

package/features/saveDataManager/load.lua

@@ -0,0 +1,66 @@
+local ____lualib = require("lualib_bundle")
+local __TS__StringTrim = ____lualib.__TS__StringTrim
+local ____exports = {}
+local readSaveDatFile, tryLoadModData, DEFAULT_MOD_DATA
+local ____jsonHelpers = require("functions.jsonHelpers")
+local jsonDecode = ____jsonHelpers.jsonDecode
+local ____log = require("functions.log")
+local log = ____log.log
+local logError = ____log.logError
+local ____constants = require("features.saveDataManager.constants")
+local SAVE_DATA_MANAGER_DEBUG = ____constants.SAVE_DATA_MANAGER_DEBUG
+local SAVE_DATA_MANAGER_FEATURE_NAME = ____constants.SAVE_DATA_MANAGER_FEATURE_NAME
+local ____merge = require("features.saveDataManager.merge")
+local merge = ____merge.merge
+function readSaveDatFile(self, mod)
+    local renderFrameCount = Isaac.GetFrameCount()
+    local ok, jsonStringOrErrMsg = pcall(tryLoadModData, mod)
+    if not ok then
+        logError((("Failed to read from the \"save#.dat\" file on render frame " .. tostring(renderFrameCount)) .. ": ") .. jsonStringOrErrMsg)
+        return DEFAULT_MOD_DATA
+    end
+    if jsonStringOrErrMsg == nil then
+        return DEFAULT_MOD_DATA
+    end
+    local jsonStringTrimmed = __TS__StringTrim(jsonStringOrErrMsg)
+    if jsonStringTrimmed == "" then
+        return DEFAULT_MOD_DATA
+    end
+    return jsonStringTrimmed
+end
+function tryLoadModData(mod)
+    return mod:LoadData()
+end
+DEFAULT_MOD_DATA = "{}"
+function ____exports.loadFromDisk(self, mod, oldSaveData)
+    if not mod:HasData() then
+        return
+    end
+    local jsonString = readSaveDatFile(nil, mod)
+    local newSaveData = jsonDecode(nil, jsonString)
+    if SAVE_DATA_MANAGER_DEBUG then
+        log("Converted data from the \"save#.dat\" to a Lua table.")
+    end
+    for key, value in pairs(newSaveData) do
+        do
+            if type(key) ~= "string" then
+                goto __continue5
+            end
+            local valueType = type(value)
+            if valueType ~= "table" then
+                goto __continue5
+            end
+            local oldSaveDataForSubscriber = oldSaveData[key]
+            if oldSaveDataForSubscriber == nil then
+                goto __continue5
+            end
+            if SAVE_DATA_MANAGER_DEBUG then
+                log("Merging in stored data for feature: " .. key)
+            end
+            merge(nil, oldSaveDataForSubscriber, value, key)
+        end
+        ::__continue5::
+    end
+    log(("The " .. SAVE_DATA_MANAGER_FEATURE_NAME) .. " loaded data from the \"save#.dat\" file.")
+end
+return ____exports

package/features/saveDataManager/main.d.ts

@@ -0,0 +1,3 @@
+import { SaveDataKey } from "../../enums/private/SaveDataKey";
+import { SaveData } from "../../interfaces/SaveData";
+export declare function restoreDefaultSaveData(subscriberName: string, saveData: SaveData, saveDataKey: SaveDataKey): void;

package/features/saveDataManager/main.lua

@@ -0,0 +1,125 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local ____exports = {}
+local postPlayerInit, preGameExit, postNewLevel, postNewRoomEarly, restoreDefaultsAll, restoreDefaults, clearAndCopyAllElements, mod, loadedDataOnThisRun
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local ModCallback = ____isaac_2Dtypescript_2Ddefinitions.ModCallback
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+local ____ModCallbackCustom = require("enums.ModCallbackCustom")
+local ModCallbackCustom = ____ModCallbackCustom.ModCallbackCustom
+local ____SaveDataKey = require("enums.private.SaveDataKey")
+local RESETTABLE_SAVE_DATA_KEYS = ____SaveDataKey.RESETTABLE_SAVE_DATA_KEYS
+local SaveDataKey = ____SaveDataKey.SaveDataKey
+local ____SerializationType = require("enums.SerializationType")
+local SerializationType = ____SerializationType.SerializationType
+local ____deepCopy = require("functions.deepCopy")
+local deepCopy = ____deepCopy.deepCopy
+local ____log = require("functions.log")
+local logError = ____log.logError
+local ____table = require("functions.table")
+local clearTable = ____table.clearTable
+local ____constants = require("features.saveDataManager.constants")
+local SAVE_DATA_MANAGER_FEATURE_NAME = ____constants.SAVE_DATA_MANAGER_FEATURE_NAME
+local ____load = require("features.saveDataManager.load")
+local loadFromDisk = ____load.loadFromDisk
+local ____maps = require("features.saveDataManager.maps")
+local saveDataConditionalFuncMap = ____maps.saveDataConditionalFuncMap
+local saveDataDefaultsMap = ____maps.saveDataDefaultsMap
+local saveDataMap = ____maps.saveDataMap
+local ____save = require("features.saveDataManager.save")
+local saveToDisk = ____save.saveToDisk
+function postPlayerInit(self)
+    if mod == nil then
+        error(("The mod for the " .. SAVE_DATA_MANAGER_FEATURE_NAME) .. " was not initialized.")
+    end
+    if loadedDataOnThisRun then
+        return
+    end
+    loadedDataOnThisRun = true
+    loadFromDisk(nil, mod, saveDataMap)
+    local gameFrameCount = game:GetFrameCount()
+    local isContinued = gameFrameCount ~= 0
+    if not isContinued then
+        restoreDefaultsAll(nil)
+    end
+end
+function preGameExit(self)
+    if mod == nil then
+        error(("The mod for the " .. SAVE_DATA_MANAGER_FEATURE_NAME) .. " was not initialized.")
+    end
+    saveToDisk(nil, mod, saveDataMap, saveDataConditionalFuncMap)
+    restoreDefaultsAll(nil)
+    loadedDataOnThisRun = false
+end
+function postNewLevel(self)
+    restoreDefaults(nil, SaveDataKey.LEVEL)
+end
+function postNewRoomEarly(self)
+    restoreDefaults(nil, SaveDataKey.ROOM)
+end
+function restoreDefaultsAll(self)
+    restoreDefaults(nil, SaveDataKey.RUN)
+    restoreDefaults(nil, SaveDataKey.LEVEL)
+    restoreDefaults(nil, SaveDataKey.ROOM)
+end
+function restoreDefaults(self, saveDataKey)
+    for subscriberName, saveData in pairs(saveDataMap) do
+        ____exports.restoreDefaultSaveData(nil, subscriberName, saveData, saveDataKey)
+    end
+end
+function ____exports.restoreDefaultSaveData(self, subscriberName, saveData, saveDataKey)
+    if not RESETTABLE_SAVE_DATA_KEYS:has(saveDataKey) then
+        error("Unknown save data key name of: " .. saveDataKey)
+    end
+    local childTable = saveData[saveDataKey]
+    if childTable == nil then
+        return
+    end
+    local saveDataDefaults = saveDataDefaultsMap[subscriberName]
+    if saveDataDefaults == nil then
+        logError("Failed to find the default copy of the save data for subscriber: " .. subscriberName)
+        return
+    end
+    local childTableDefaults = saveDataDefaults[saveDataKey]
+    if childTableDefaults == nil then
+        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
+    end
+    local childTableDefaultsCopy = deepCopy(nil, childTableDefaults, SerializationType.NONE, (subscriberName .. " --> ") .. saveDataKey)
+    clearAndCopyAllElements(nil, childTable, childTableDefaultsCopy)
+end
+function clearAndCopyAllElements(self, oldTable, newTable)
+    clearTable(nil, oldTable)
+    for key, value in pairs(newTable) do
+        oldTable[key] = value
+    end
+end
+mod = nil
+loadedDataOnThisRun = false
+---
+-- @internal
+function ____exports.saveDataManagerInit(self, incomingMod)
+    mod = incomingMod
+    mod:AddCallback(ModCallback.POST_PLAYER_INIT, postPlayerInit)
+    mod:AddCallback(ModCallback.PRE_GAME_EXIT, preGameExit)
+    mod:AddCallback(ModCallback.POST_NEW_LEVEL, postNewLevel)
+    mod:AddCallbackCustom(ModCallbackCustom.POST_NEW_ROOM_EARLY, postNewRoomEarly)
+end
+---
+-- @internal
+function ____exports.forceSaveDataManagerSave(self)
+    if mod == nil then
+        return
+    end
+    saveToDisk(nil, mod, saveDataMap, saveDataConditionalFuncMap)
+end
+---
+-- @internal
+function ____exports.forceSaveDataManagerLoad(self)
+    if mod == nil then
+        return
+    end
+    loadFromDisk(nil, mod, saveDataMap)
+end
+return ____exports

package/features/saveDataManager/maps.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="typescript-to-lua/language-extensions" />
+import { SaveData } from "../../interfaces/SaveData";
+/**
+ * The save data map is indexed by subscriber name. We use Lua tables instead of TypeScriptToLua
+ * Maps for the master map so that we can access the variables via the in-game console when
+ * debugging. (TSTL Maps don't expose the map keys as normal keys.)
+ */
+export declare const saveDataMap: LuaTable<string, SaveData>;
+export declare const saveDataDefaultsMap: LuaTable<string, SaveData>;
+export declare const saveDataConditionalFuncMap: Map<string, () => boolean>;

package/features/saveDataManager/maps.lua

@@ -0,0 +1,11 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local __TS__New = ____lualib.__TS__New
+local ____exports = {}
+--- The save data map is indexed by subscriber name. We use Lua tables instead of TypeScriptToLua
+-- Maps for the master map so that we can access the variables via the in-game console when
+-- debugging. (TSTL Maps don't expose the map keys as normal keys.)
+____exports.saveDataMap = {}
+____exports.saveDataDefaultsMap = {}
+____exports.saveDataConditionalFuncMap = __TS__New(Map)
+return ____exports