isaacscript-common 2.3.0 → 2.3.1

package/features/saveDataManager/constants.lua

@@ -0,0 +1,4 @@
+local ____exports = {}
+____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,66 @@
+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
+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
+function ____exports.saveDataManagerLoad(self)
+    errorIfFeaturesNotInitialized(nil, SAVE_DATA_MANAGER_FEATURE_NAME)
+    forceSaveDataManagerLoad(nil)
+end
+function ____exports.saveDataManagerSave(self)
+    errorIfFeaturesNotInitialized(nil, SAVE_DATA_MANAGER_FEATURE_NAME)
+    forceSaveDataManagerSave(nil)
+end
+function ____exports.saveDataManagerSetGlobal(self)
+    g = saveDataMap
+    gd = saveDataDefaultsMap
+end
+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,119 @@
+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
+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
+function ____exports.forceSaveDataManagerSave(self)
+    if mod == nil then
+        return
+    end
+    saveToDisk(nil, mod, saveDataMap, saveDataConditionalFuncMap)
+end
+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,8 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local __TS__New = ____lualib.__TS__New
+local ____exports = {}
+____exports.saveDataMap = {}
+____exports.saveDataDefaultsMap = {}
+____exports.saveDataConditionalFuncMap = __TS__New(Map)
+return ____exports

package/features/saveDataManager/merge.d.ts

@@ -0,0 +1,24 @@
+/// <reference types="typescript-to-lua/language-extensions" />
+/**
+ * `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 declare function merge(oldObject: LuaTable<AnyNotNil, unknown> | Map<AnyNotNil, unknown> | Set<AnyNotNil>, newTable: LuaTable<AnyNotNil, unknown>, traversalDescription: string): void;

package/features/saveDataManager/merge.lua

@@ -0,0 +1,124 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local __TS__InstanceOf = ____lualib.__TS__InstanceOf
+local Set = ____lualib.Set
+local ____exports = {}
+local mergeArray, mergeTSTLObject, mergeTable
+local ____SerializationBrand = require("enums.private.SerializationBrand")
+local SerializationBrand = ____SerializationBrand.SerializationBrand
+local ____SerializationType = require("enums.SerializationType")
+local SerializationType = ____SerializationType.SerializationType
+local ____array = require("functions.array")
+local isArray = ____array.isArray
+local ____deepCopy = require("functions.deepCopy")
+local deepCopy = ____deepCopy.deepCopy
+local ____log = require("functions.log")
+local log = ____log.log
+local ____serialization = require("functions.serialization")
+local deserializeIsaacAPIClass = ____serialization.deserializeIsaacAPIClass
+local isSerializedIsaacAPIClass = ____serialization.isSerializedIsaacAPIClass
+local ____table = require("functions.table")
+local clearTable = ____table.clearTable
+local ____utils = require("functions.utils")
+local getTraversalDescription = ____utils.getTraversalDescription
+local ____constants = require("features.saveDataManager.constants")
+local SAVE_DATA_MANAGER_DEBUG = ____constants.SAVE_DATA_MANAGER_DEBUG
+local ____serializationBrand = require("features.saveDataManager.serializationBrand")
+local isSerializationBrand = ____serializationBrand.isSerializationBrand
+function ____exports.merge(self, oldObject, newTable, traversalDescription)
+    if SAVE_DATA_MANAGER_DEBUG then
+        log("merge is traversing: " .. traversalDescription)
+    end
+    local oldObjectType = type(oldObject)
+    if oldObjectType ~= "table" then
+        error("The first argument given to the merge function is not a table.")
+    end
+    local newTableType = type(newTable)
+    if newTableType ~= "table" then
+        error("The second argument given to the merge function is not a table.")
+    end
+    if isArray(nil, oldObject) and isArray(nil, newTable) then
+        local oldTable = oldObject
+        mergeArray(nil, oldTable, newTable)
+        return
+    end
+    if __TS__InstanceOf(oldObject, Map) or __TS__InstanceOf(oldObject, Set) then
+        mergeTSTLObject(nil, oldObject, newTable, traversalDescription)
+    else
+        mergeTable(nil, oldObject, newTable, traversalDescription)
+    end
+end
+function mergeArray(self, oldArray, newArray)
+    clearTable(nil, oldArray)
+    for key, value in pairs(newArray) do
+        oldArray[key] = value
+    end
+end
+function mergeTSTLObject(self, oldObject, newTable, traversalDescription)
+    oldObject:clear()
+    local convertStringKeysToNumbers = newTable[SerializationBrand.OBJECT_WITH_NUMBER_KEYS] ~= nil
+    for key, value in pairs(newTable) do
+        do
+            if isSerializationBrand(nil, key) then
+                goto __continue12
+            end
+            local keyToUse = key
+            if convertStringKeysToNumbers then
+                local numberKey = tonumber(key)
+                if numberKey == nil then
+                    goto __continue12
+                end
+                keyToUse = numberKey
+            end
+            if __TS__InstanceOf(oldObject, Map) then
+                local valueType = type(value)
+                local valueCopy
+                if valueType == "table" then
+                    valueCopy = deepCopy(nil, value, SerializationType.DESERIALIZE, traversalDescription)
+                else
+                    valueCopy = value
+                end
+                oldObject:set(keyToUse, valueCopy)
+            elseif __TS__InstanceOf(oldObject, Set) then
+                oldObject:add(keyToUse)
+            end
+        end
+        ::__continue12::
+    end
+end
+function mergeTable(self, oldTable, newTable, traversalDescription)
+    for key, value in pairs(newTable) do
+        do
+            if SAVE_DATA_MANAGER_DEBUG then
+                local valueToPrint = value == "" and "(empty string)" or tostring(value)
+                log((("merge is merging: " .. traversalDescription) .. " --> ") .. valueToPrint)
+            end
+            if isSerializationBrand(nil, key) then
+                goto __continue21
+            end
+            if isSerializedIsaacAPIClass(nil, value) then
+                if SAVE_DATA_MANAGER_DEBUG then
+                    log("merge found a serialized Isaac API class.")
+                end
+                local deserializedObject = deserializeIsaacAPIClass(nil, value)
+                oldTable[key] = deserializedObject
+                goto __continue21
+            end
+            local valueType = type(value)
+            if valueType == "table" then
+                local oldValue = oldTable[key]
+                local oldValueType = type(oldValue)
+                if oldValueType ~= "table" then
+                    oldValue = {}
+                    oldTable[key] = oldValue
+                end
+                traversalDescription = getTraversalDescription(nil, key, traversalDescription)
+                ____exports.merge(nil, oldValue, value, traversalDescription)
+            else
+                oldTable[key] = value
+            end
+        end
+        ::__continue21::
+    end
+end
+return ____exports

package/features/saveDataManager/save.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 saveToDisk(mod: Mod, saveDataMap: LuaTable<string, SaveData>, saveDataConditionalFuncMap: Map<string, () => boolean>): void;

package/features/saveDataManager/save.lua

@@ -0,0 +1,44 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local __TS__ObjectKeys = ____lualib.__TS__ObjectKeys
+local ____exports = {}
+local getAllSaveDataToWriteToDisk
+local ____SerializationType = require("enums.SerializationType")
+local SerializationType = ____SerializationType.SerializationType
+local ____deepCopy = require("functions.deepCopy")
+local deepCopy = ____deepCopy.deepCopy
+local ____jsonHelpers = require("functions.jsonHelpers")
+local jsonEncode = ____jsonHelpers.jsonEncode
+local ____log = require("functions.log")
+local log = ____log.log
+local ____constants = require("features.saveDataManager.constants")
+local SAVE_DATA_MANAGER_FEATURE_NAME = ____constants.SAVE_DATA_MANAGER_FEATURE_NAME
+function getAllSaveDataToWriteToDisk(self, saveDataMap, saveDataConditionalFuncMap)
+    local allSaveData = {}
+    for subscriberName, saveData in pairs(saveDataMap) do
+        do
+            local conditionalFunc = saveDataConditionalFuncMap:get(subscriberName)
+            if conditionalFunc ~= nil then
+                local shouldSave = conditionalFunc(nil)
+                if not shouldSave then
+                    goto __continue4
+                end
+            end
+            local saveDataWithoutRoom = {persistent = saveData.persistent, run = saveData.run, level = saveData.level}
+            if #__TS__ObjectKeys(saveDataWithoutRoom) == 0 then
+                goto __continue4
+            end
+            local saveDataCopy = deepCopy(nil, saveDataWithoutRoom, SerializationType.SERIALIZE, subscriberName)
+            allSaveData[subscriberName] = saveDataCopy
+        end
+        ::__continue4::
+    end
+    return allSaveData
+end
+function ____exports.saveToDisk(self, mod, saveDataMap, saveDataConditionalFuncMap)
+    local allSaveData = getAllSaveDataToWriteToDisk(nil, saveDataMap, saveDataConditionalFuncMap)
+    local jsonString = jsonEncode(nil, allSaveData)
+    mod:SaveData(jsonString)
+    log(("The " .. SAVE_DATA_MANAGER_FEATURE_NAME) .. " wrote data to the \"save#.dat\" file.")
+end
+return ____exports

package/features/saveDataManager/serializationBrand.d.ts

@@ -0,0 +1 @@
+export declare function isSerializationBrand(key: unknown): boolean;

package/features/saveDataManager/serializationBrand.lua

@@ -0,0 +1,17 @@
+local ____lualib = require("lualib_bundle")
+local Set = ____lualib.Set
+local __TS__New = ____lualib.__TS__New
+local ____exports = {}
+local ____SerializationBrand = require("enums.private.SerializationBrand")
+local SerializationBrand = ____SerializationBrand.SerializationBrand
+local ____enums = require("functions.enums")
+local getEnumValues = ____enums.getEnumValues
+local SERIALIZATION_BRANDS = getEnumValues(nil, SerializationBrand)
+local SERIALIZATION_BRAND_SET = __TS__New(Set, SERIALIZATION_BRANDS)
+function ____exports.isSerializationBrand(self, key)
+    if type(key) ~= "string" then
+        return false
+    end
+    return SERIALIZATION_BRAND_SET:has(key)
+end
+return ____exports

package/features/sirenHelpers.d.ts

@@ -0,0 +1,18 @@
+import { FamiliarVariant } from "isaac-typescript-definitions";
+/**
+ * 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 declare function setFamiliarNoSirenSteal(familiarVariant: FamiliarVariant, familiarSubType?: int): void;
+/**
+ * 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 declare function hasSirenStolenFamiliar(familiar: EntityFamiliar): boolean;