isaacscript-common 2.3.1 → 3.1.0

package/features/fastReset.lua

@@ -35,13 +35,23 @@ function checkResetInput(self)
 end
 local FEATURE_NAME = "fast reset"
 enabled = false
+---
+-- @internal
 function ____exports.fastResetInit(self, mod)
     mod:AddCallback(ModCallback.POST_RENDER, postRender)
 end
+--- Enables the fast-reset feature, which allows you to restart the game instantaneously. If this
+-- behavior is desired, call this function once at the beginning of your mod.
+-- 
+-- This is useful for debugging, when you are resetting the game often.
+-- 
+-- You can disable the fast-reset feature with the `disableFastReset` function.
 function ____exports.enableFastReset(self)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     enabled = true
 end
+--- Disables the fast-reset feature. Only useful if you have previously called the `enableFastReset`
+-- function.
 function ____exports.disableFastReset(self)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     enabled = false

package/features/forgottenSwitch.lua

@@ -17,10 +17,14 @@ function isActionTriggered(self, _entity, _inputHook, buttonAction)
 end
 local FEATURE_NAME = "forgotten switcher"
 v = {run = {shouldSwitch = false}}
+---
+-- @internal
 function ____exports.forgottenSwitchInit(self, mod)
     saveDataManager(nil, "forgottenSwitch", v)
     mod:AddCallback(ModCallback.INPUT_ACTION, isActionTriggered, InputHook.IS_ACTION_TRIGGERED)
 end
+--- When used on The Forgotten, switches to The Soul. When used on The Soul, switches to The
+-- Forgotten. This takes 1 game frame to take effect.
 function ____exports.forgottenSwitch(self)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     v.run.shouldSwitch = true

package/features/getCollectibleItemPoolType.lua

@@ -26,10 +26,15 @@ function postPickupInitCollectible(self, pickup)
 end
 local FEATURE_NAME = "get collectible item pool type"
 v = {run = {collectibleItemPoolTypeMap = __TS__New(Map)}}
+---
+-- @internal
 function ____exports.getCollectibleItemPoolTypeInit(self, mod)
     saveDataManager(nil, "getCollectibleItemPoolType", v)
     mod:AddCallback(ModCallback.POST_PICKUP_INIT, postPickupInitCollectible, PickupVariant.COLLECTIBLE)
 end
+--- Helper function to get the item pool type that a given collectible came from. Since there is no
+-- native method in the API to get this, we listen in the PreGetCollectible callback for item pool
+-- types, and then assume that the next spawned collectible will match.
 function ____exports.getCollectibleItemPoolType(self, collectible)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     if not isCollectible(nil, collectible) then

package/features/playerInventory.lua

@@ -94,12 +94,24 @@ v = {run = {
         function() return {} end
     )
 }}
+---
+-- @internal
 function ____exports.playerInventoryInit(self, mod)
     saveDataManager(nil, "playerInventory", v)
     mod:AddCallback(ModCallback.POST_USE_ITEM, useItemD4, CollectibleType.D4)
     mod:AddCallback(ModCallback.POST_GAME_STARTED, postGameStarted)
     mod:AddCallbackCustom(ModCallbackCustom.POST_ITEM_PICKUP, postItemPickup)
 end
+--- Helper function to get all of the collectibles that the player has gotten so far on this run, in
+-- order.
+-- 
+-- Note that this does not include active collectibles that have since been dropped for other
+-- collectibles.
+-- 
+-- In the case of inventory initialization or the case where the player rerolls their build in the
+-- middle of the run (e.g. with D4), the order of the inventory will not correspond to the order
+-- that the items were actually given to the player. In this case, the inventory will be in the
+-- order of the lowest `CollectibleType` to the highest.
 function ____exports.getPlayerInventory(self, player, includeActiveCollectibles)
     if includeActiveCollectibles == nil then
         includeActiveCollectibles = true
@@ -116,6 +128,12 @@ function ____exports.getPlayerInventory(self, player, includeActiveCollectibles)
         function(____, collectibleType) return not isActiveCollectible(nil, collectibleType) end
     )
 end
+--- Helper function to add a collectible to a player. Use this instead of the
+-- `EntityPlayer.AddCollectible` method if you want the collectible that is added to be
+-- automatically tracked by the player inventory tracker feature.
+-- 
+-- You only need to use this function if you are using the inventory feature from the standard
+-- library.
 function ____exports.addCollectible(self, player, collectibleType, charge, firstTimePickingUp, activeSlot, varData)
     player:AddCollectible(
         collectibleType,

package/features/ponyDetection.lua

@@ -38,10 +38,14 @@ end
 local FEATURE_NAME = "pony activation detector"
 FLAGS_WHEN_PONY_IS_ACTIVE = {EntityFlag.NO_KNOCKBACK, EntityFlag.NO_PHYSICS_KNOCKBACK, EntityFlag.NO_DAMAGE_BLINK}
 v = {run = {playersIsPonyActive = __TS__New(Set)}}
+---
+-- @internal
 function ____exports.ponyDetectionInit(self, mod)
     saveDataManager(nil, "ponyDetection", v)
     mod:AddCallbackCustom(ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED, postPEffectUpdateReordered)
 end
+--- Helper function to see if the player is under the effects of A Pony or White Pony charge.
+-- Detecting this is difficult, as the temporary effect will disappear upon entering a new room.
 function ____exports.isPonyActive(self, player)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     return setHasPlayer(nil, v.run.playersIsPonyActive, player)

package/features/preventCollectibleRotation.lua

@@ -40,11 +40,20 @@ function getMapIndex(self, collectible)
 end
 local FEATURE_NAME = "prevent collectible rotation"
 v = {room = {trackedCollectibles = __TS__New(Map)}}
+---
+-- @internal
 function ____exports.preventCollectibleRotationInit(self, mod)
     saveDataManager(nil, "preventCollectibleRotation", v)
     mod:AddCallback(ModCallback.POST_USE_CARD, useCardSoulOfIsaac, Card.SOUL_ISAAC)
     mod:AddCallback(ModCallback.POST_PICKUP_UPDATE, postPickupUpdateCollectible, PickupVariant.COLLECTIBLE)
 end
+--- Helper function to prevent a collectible from being affected by Tainted Isaac's rotation
+-- mechanic. (This mechanic also happens from Glitched Crown and Binge Eater.) This is useful
+-- because quest items that are manually spawned by mods will be automatically be affected by this
+-- mechanic.
+-- 
+-- It is required to pass the intended collectible type to this function since it is possible for
+-- collectibles to rotate on the first frame that they are spawned.
 function ____exports.preventCollectibleRotation(self, collectible, collectibleType)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     if not isCollectible(nil, collectible) then

package/features/runInNFrames.lua

@@ -41,6 +41,8 @@ function checkExecuteQueuedFunctions(self, frameCount, functionTuples)
 end
 local FEATURE_NAME = "run in N frames"
 v = {run = {queuedGameFunctionTuples = {}, queuedRenderFunctionTuples = {}}}
+---
+-- @internal
 function ____exports.runInNFramesInit(self, mod)
     saveDataManager(
         nil,
@@ -51,6 +53,14 @@ function ____exports.runInNFramesInit(self, mod)
     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()
@@ -59,6 +69,14 @@ function ____exports.runInNGameFrames(self, func, gameFrames)
     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()
@@ -67,10 +85,42 @@ function ____exports.runInNRenderFrames(self, func, renderFrames)
     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)

package/features/saveDataManager/constants.lua

@@ -1,4 +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.lua

@@ -18,6 +18,89 @@ 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)
@@ -39,18 +122,50 @@ function ____exports.saveDataManager(self, key, v, conditionalFunc)
         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)

package/features/saveDataManager/load.lua

@@ -7,6 +7,8 @@ local jsonDecode = ____jsonHelpers.jsonDecode
 local ____log = require("functions.log")
 local log = ____log.log
 local logError = ____log.logError
+local ____table = require("functions.table")
+local iterateTableDeterministically = ____table.iterateTableDeterministically
 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
@@ -41,26 +43,28 @@ function ____exports.loadFromDisk(self, mod, oldSaveData)
     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
+    iterateTableDeterministically(
+        nil,
+        newSaveData,
+        function(____, key, value)
             if type(key) ~= "string" then
-                goto __continue5
+                return
             end
             local valueType = type(value)
             if valueType ~= "table" then
-                goto __continue5
+                return
             end
             local oldSaveDataForSubscriber = oldSaveData[key]
             if oldSaveDataForSubscriber == nil then
-                goto __continue5
+                return
             end
             if SAVE_DATA_MANAGER_DEBUG then
                 log("Merging in stored data for feature: " .. key)
             end
             merge(nil, oldSaveDataForSubscriber, value, key)
-        end
-        ::__continue5::
-    end
+        end,
+        SAVE_DATA_MANAGER_DEBUG
+    )
     log(("The " .. SAVE_DATA_MANAGER_FEATURE_NAME) .. " loaded data from the \"save#.dat\" file.")
 end
 return ____exports

package/features/saveDataManager/main.lua

@@ -19,7 +19,9 @@ local ____log = require("functions.log")
 local logError = ____log.logError
 local ____table = require("functions.table")
 local clearTable = ____table.clearTable
+local iterateTableDeterministically = ____table.iterateTableDeterministically
 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 ____load = require("features.saveDataManager.load")
 local loadFromDisk = ____load.loadFromDisk
@@ -64,9 +66,14 @@ function restoreDefaultsAll(self)
     restoreDefaults(nil, SaveDataKey.ROOM)
 end
 function restoreDefaults(self, saveDataKey)
-    for subscriberName, saveData in pairs(saveDataMap) do
-        ____exports.restoreDefaultSaveData(nil, subscriberName, saveData, saveDataKey)
-    end
+    iterateTableDeterministically(
+        nil,
+        saveDataMap,
+        function(____, subscriberName, saveData)
+            ____exports.restoreDefaultSaveData(nil, subscriberName, saveData, saveDataKey)
+        end,
+        SAVE_DATA_MANAGER_DEBUG
+    )
 end
 function ____exports.restoreDefaultSaveData(self, subscriberName, saveData, saveDataKey)
     if not RESETTABLE_SAVE_DATA_KEYS:has(saveDataKey) then
@@ -97,6 +104,8 @@ function clearAndCopyAllElements(self, oldTable, newTable)
 end
 mod = nil
 loadedDataOnThisRun = false
+---
+-- @internal
 function ____exports.saveDataManagerInit(self, incomingMod)
     mod = incomingMod
     mod:AddCallback(ModCallback.POST_PLAYER_INIT, postPlayerInit)
@@ -104,12 +113,16 @@ function ____exports.saveDataManagerInit(self, incomingMod)
     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

package/features/saveDataManager/maps.lua

@@ -2,6 +2,9 @@ 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)

package/features/saveDataManager/merge.lua

@@ -1,6 +1,5 @@
 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
@@ -19,12 +18,36 @@ local deserializeIsaacAPIClass = ____serialization.deserializeIsaacAPIClass
 local isSerializedIsaacAPIClass = ____serialization.isSerializedIsaacAPIClass
 local ____table = require("functions.table")
 local clearTable = ____table.clearTable
+local iterateTableDeterministically = ____table.iterateTableDeterministically
+local ____tstlClass = require("functions.tstlClass")
+local isTSTLMap = ____tstlClass.isTSTLMap
+local isTSTLSet = ____tstlClass.isTSTLSet
 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
+--- `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.
 function ____exports.merge(self, oldObject, newTable, traversalDescription)
     if SAVE_DATA_MANAGER_DEBUG then
         log("merge is traversing: " .. traversalDescription)
@@ -42,7 +65,7 @@ function ____exports.merge(self, oldObject, newTable, traversalDescription)
         mergeArray(nil, oldTable, newTable)
         return
     end
-    if __TS__InstanceOf(oldObject, Map) or __TS__InstanceOf(oldObject, Set) then
+    if isTSTLMap(nil, oldObject) or isTSTLSet(nil, oldObject) then
         mergeTSTLObject(nil, oldObject, newTable, traversalDescription)
     else
         mergeTable(nil, oldObject, newTable, traversalDescription)
@@ -50,27 +73,34 @@ function ____exports.merge(self, oldObject, newTable, traversalDescription)
 end
 function mergeArray(self, oldArray, newArray)
     clearTable(nil, oldArray)
-    for key, value in pairs(newArray) do
-        oldArray[key] = value
-    end
+    iterateTableDeterministically(
+        nil,
+        newArray,
+        function(____, key, value)
+            oldArray[key] = value
+        end,
+        SAVE_DATA_MANAGER_DEBUG
+    )
 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
+    iterateTableDeterministically(
+        nil,
+        newTable,
+        function(____, key, value)
             if isSerializationBrand(nil, key) then
-                goto __continue12
+                return
             end
             local keyToUse = key
             if convertStringKeysToNumbers then
                 local numberKey = tonumber(key)
                 if numberKey == nil then
-                    goto __continue12
+                    return
                 end
                 keyToUse = numberKey
             end
-            if __TS__InstanceOf(oldObject, Map) then
+            if isTSTLMap(nil, oldObject) then
                 local valueType = type(value)
                 local valueCopy
                 if valueType == "table" then
@@ -79,22 +109,24 @@ function mergeTSTLObject(self, oldObject, newTable, traversalDescription)
                     valueCopy = value
                 end
                 oldObject:set(keyToUse, valueCopy)
-            elseif __TS__InstanceOf(oldObject, Set) then
+            elseif isTSTLSet(nil, oldObject) then
                 oldObject:add(keyToUse)
             end
-        end
-        ::__continue12::
-    end
+        end,
+        SAVE_DATA_MANAGER_DEBUG
+    )
 end
 function mergeTable(self, oldTable, newTable, traversalDescription)
-    for key, value in pairs(newTable) do
-        do
+    iterateTableDeterministically(
+        nil,
+        newTable,
+        function(____, key, value)
             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
+                return
             end
             if isSerializedIsaacAPIClass(nil, value) then
                 if SAVE_DATA_MANAGER_DEBUG then
@@ -102,7 +134,7 @@ function mergeTable(self, oldTable, newTable, traversalDescription)
                 end
                 local deserializedObject = deserializeIsaacAPIClass(nil, value)
                 oldTable[key] = deserializedObject
-                goto __continue21
+                return
             end
             local valueType = type(value)
             if valueType == "table" then
@@ -117,8 +149,8 @@ function mergeTable(self, oldTable, newTable, traversalDescription)
             else
                 oldTable[key] = value
             end
-        end
-        ::__continue21::
-    end
+        end,
+        SAVE_DATA_MANAGER_DEBUG
+    )
 end
 return ____exports

package/features/saveDataManager/save.lua

@@ -11,28 +11,33 @@ local ____jsonHelpers = require("functions.jsonHelpers")
 local jsonEncode = ____jsonHelpers.jsonEncode
 local ____log = require("functions.log")
 local log = ____log.log
+local ____table = require("functions.table")
+local iterateTableDeterministically = ____table.iterateTableDeterministically
 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
 function getAllSaveDataToWriteToDisk(self, saveDataMap, saveDataConditionalFuncMap)
     local allSaveData = {}
-    for subscriberName, saveData in pairs(saveDataMap) do
-        do
+    iterateTableDeterministically(
+        nil,
+        saveDataMap,
+        function(____, subscriberName, saveData)
             local conditionalFunc = saveDataConditionalFuncMap:get(subscriberName)
             if conditionalFunc ~= nil then
                 local shouldSave = conditionalFunc(nil)
                 if not shouldSave then
-                    goto __continue4
+                    return
                 end
             end
             local saveDataWithoutRoom = {persistent = saveData.persistent, run = saveData.run, level = saveData.level}
             if #__TS__ObjectKeys(saveDataWithoutRoom) == 0 then
-                goto __continue4
+                return
             end
             local saveDataCopy = deepCopy(nil, saveDataWithoutRoom, SerializationType.SERIALIZE, subscriberName)
             allSaveData[subscriberName] = saveDataCopy
-        end
-        ::__continue4::
-    end
+        end,
+        SAVE_DATA_MANAGER_DEBUG
+    )
     return allSaveData
 end
 function ____exports.saveToDisk(self, mod, saveDataMap, saveDataConditionalFuncMap)