isaacscript-common 14.1.3 → 15.0.0

package/dist/src/functions/logEntities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logEntities.d.ts","sourceRoot":"","sources":["../../../src/functions/logEntities.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,UAAU,EAEV,cAAc,EAOf,MAAM,8BAA8B,CAAC;AAiBtC,8FAA8F;AAC9F,wBAAgB,cAAc,CAC5B,wBAAwB,EAAE,OAAO,EACjC,gBAAgB,CAAC,EAAE,UAAU,GAC5B,IAAI,CAuCN;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,OAAO,EACrB,oBAAoB,CAAC,EAAE,cAAc,GACpC,IAAI,CA6CN;AAED,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAIpD;AAED,kEAAkE;AAClE,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAG9C;AAmFD,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,YAAY,EAAE,UAAU,EAAE,GAAG,IAAI,CAIhE;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAG1D;AA2DD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAQjD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,IAAI,CAIvD"}
+{"version":3,"file":"logEntities.d.ts","sourceRoot":"","sources":["../../../src/functions/logEntities.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,UAAU,EAEV,cAAc,EAOf,MAAM,8BAA8B,CAAC;AAiBtC,8FAA8F;AAC9F,wBAAgB,cAAc,CAC5B,wBAAwB,EAAE,OAAO,EACjC,gBAAgB,CAAC,EAAE,UAAU,GAC5B,IAAI,CA0CN;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,UAAQ,EACpB,oBAAoB,CAAC,EAAE,cAAc,GACpC,IAAI,CAgDN;AAED,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAIpD;AAED,kEAAkE;AAClE,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAG9C;AAmFD,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,YAAY,EAAE,UAAU,EAAE,GAAG,IAAI,CAIhE;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAG1D;AA2DD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAQjD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,IAAI,CAIvD"}

package/dist/src/functions/logEntities.lua

@@ -2,6 +2,8 @@ local ____lualib = require("lualib_bundle")
 local Set = ____lualib.Set
 local __TS__New = ____lualib.__TS__New
 local __TS__ArrayForEach = ____lualib.__TS__ArrayForEach
+local __TS__StringTrim = ____lualib.__TS__StringTrim
+local __TS__StringSplit = ____lualib.__TS__StringSplit
 local ____exports = {}
 local getEntityLogLine, getGridEntityLogLine
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
@@ -179,10 +181,22 @@ function ____exports.logAllEntities(self, includeBackgroundEffects, entityTypeFi
     else
         msg = msg .. ((("(" .. tostring(numMatchedEntities)) .. " total ") .. (numMatchedEntities == 1 and "entity" or "entities")) .. ")\n"
     end
-    log(nil, msg)
+    for ____, line in ipairs(__TS__StringSplit(
+        __TS__StringTrim(msg),
+        "\n"
+    )) do
+        log(nil, line)
+    end
 end
 --- Helper function for printing out every grid entity (or filtered grid entity) in the current room.
+-- 
+-- @param includeWalls Optional. Whether or not to log the walls. Default is false.
+-- @param gridEntityTypeFilter Optional. If specified, will only log the given `GridEntityType`.
+-- Default is undefined.
 function ____exports.logAllGridEntities(self, includeWalls, gridEntityTypeFilter)
+    if includeWalls == nil then
+        includeWalls = false
+    end
     local msg = "Grid entities in the room"
     if gridEntityTypeFilter ~= nil then
         msg = msg .. (" (filtered to grid entity type " .. tostring(gridEntityTypeFilter)) .. ")"
@@ -212,7 +226,12 @@ function ____exports.logAllGridEntities(self, includeWalls, gridEntityTypeFilter
     else
         msg = msg .. ((("(" .. tostring(numMatchedEntities)) .. " total grid ") .. (numMatchedEntities == 1 and "entity" or "entities")) .. ")\n"
     end
-    log(nil, msg)
+    for ____, line in ipairs(__TS__StringSplit(
+        __TS__StringTrim(msg),
+        "\n"
+    )) do
+        log(nil, line)
+    end
 end
 --- Helper function for logging an array of specific entities.
 function ____exports.logEntities(self, entities)

package/dist/src/functions/logMisc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logMisc.d.ts","sourceRoot":"","sources":["../../../src/functions/logMisc.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"logMisc.d.ts","sourceRoot":"","sources":["../../../src/functions/logMisc.ts"],"names":[],"mappings":"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"}

package/dist/src/functions/logMisc.lua

@@ -3,9 +3,9 @@ local Map = ____lualib.Map
 local __TS__Spread = ____lualib.__TS__Spread
 local __TS__ArraySort = ____lualib.__TS__ArraySort
 local __TS__ArrayForEach = ____lualib.__TS__ArrayForEach
+local Set = ____lualib.Set
 local __TS__TypeOf = ____lualib.__TS__TypeOf
 local __TS__ObjectKeys = ____lualib.__TS__ObjectKeys
-local Set = ____lualib.Set
 local __TS__New = ____lualib.__TS__New
 local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
@@ -25,6 +25,7 @@ local game = ____cachedClasses.game
 local sfxManager = ____cachedClasses.sfxManager
 local ____array = require("src.functions.array")
 local arrayToString = ____array.arrayToString
+local isArray = ____array.isArray
 local ____collectibles = require("src.functions.collectibles")
 local getCollectibleName = ____collectibles.getCollectibleName
 local ____entities = require("src.functions.entities")
@@ -53,6 +54,10 @@ local ____table = require("src.functions.table")
 local iterateTableInOrder = ____table.iterateTableInOrder
 local ____trinkets = require("src.functions.trinkets")
 local getTrinketName = ____trinkets.getTrinketName
+local ____tstlClass = require("src.functions.tstlClass")
+local isDefaultMap = ____tstlClass.isDefaultMap
+local isTSTLMap = ____tstlClass.isTSTLMap
+local isTSTLSet = ____tstlClass.isTSTLSet
 local ____types = require("src.functions.types")
 local isTable = ____types.isTable
 local isUserdata = ____types.isUserdata
@@ -89,6 +94,10 @@ function ____exports.logFlags(self, flags, flagEnum, description)
     end
 end
 function ____exports.logArray(self, array)
+    if not isArray(nil, array) then
+        log(nil, "Tried to log an array, but the given object was not an array.")
+        return
+    end
     local arrayString = arrayToString(nil, array)
     log(nil, "Array: " .. arrayString)
 end
@@ -181,7 +190,11 @@ function ____exports.logLevelStateFlags(self)
     end
 end
 function ____exports.logMap(self, map)
-    log(nil, "Printing out a TSTL Map:")
+    if not isTSTLMap(nil, map) and not isDefaultMap(nil, map) then
+        log(nil, "Tried to log a TSTL map, but the given object was not a TSTL map.")
+        return
+    end
+    log(nil, "Printing out a TSTL map:")
     local mapKeys = {__TS__Spread(map:keys())}
     __TS__ArraySort(mapKeys)
     for ____, key in ipairs(mapKeys) do
@@ -347,7 +360,11 @@ function ____exports.logSeedEffects(self)
     end
 end
 function ____exports.logSet(self, set)
-    log(nil, "Printing out a TSTL Set:")
+    if not isTSTLSet(nil, set) then
+        log(nil, "Tried to log a TSTL set, but the given object was not a TSTL set.")
+        return
+    end
+    log(nil, "Printing out a TSTL set:")
     local setValues = getSortedSetValues(nil, set)
     for ____, value in ipairs(setValues) do
         log(

package/dist/src/functions/merge.d.ts

@@ -0,0 +1,40 @@
+/// <reference types="@typescript-to-lua/language-extensions" />
+import { AnyClass } from "../types/AnyClass";
+/**
+ * `merge` takes the values from a new table and recursively merges them into an old object (while
+ * performing appropriate deserialization).
+ *
+ * This function is used to merge incoming data from the "save#.dat" file into a mod's variables.
+ * Merging is useful instead of blowing away a table entirely because mod code often relies on the
+ * local table/object references.
+ *
+ * This function always assumes that the new table is serialized data and will attempt to perform
+ * deserialization on the objects within. In other words, unlike the `deepCopy` function, the
+ * `merge` function will always operates in the mode of `SerializationType.DESERIALIZE`. For the
+ * types of objects that will be deserialized, see the documentation for the `deepCopy` function.
+ *
+ * This function does not iterate over the old object, like you would naively expect. This is
+ * because it is common for a variable to have a type of `something | null`. If this is the case,
+ * the key would not appear when iterating over the old object (because a value of null transpiles
+ * to nil, which means the table key does not exist). Thus, we must instead iterate over the new
+ * object and copy the values backwards. The consequence of this is that `merge` 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.
+ *
+ * @param oldObject The old object to merge the values into. This can be either a Lua table, a TSTL
+ *                  map, or a TSTL set.
+ * @param newTable The new table to merge the values from. This must be a Lua table that represents
+ *                 serialized data. In other words, it should be created with the `deepCopy`
+ *                 function using `SerializationType.SERIALIZE`.
+ * @param traversalDescription Used to track the current key that we are operating on for debugging
+ *                             purposes. Use a name that corresponds to the name of the merging
+ *                             table.
+ * @param classConstructors Optional. A Lua table that maps the name of a user-defined TSTL class to
+ *                          its corresponding constructor. If the `deepCopy` function finds any
+ *                          user-defined TSTL classes when recursively iterating through the given
+ *                          object, it will use this map to instantiate a new class. Default is an
+ *                          empty Lua table.
+ */
+export declare function merge(oldObject: LuaMap<AnyNotNil, unknown> | Map<AnyNotNil, unknown> | Set<AnyNotNil>, newTable: LuaMap<AnyNotNil, unknown>, traversalDescription: string, classConstructors?: LuaMap<string, AnyClass>): void;
+//# sourceMappingURL=merge.d.ts.map

package/dist/src/functions/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../../src/functions/merge.ts"],"names":[],"mappings":";AAGA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAc7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,KAAK,CACnB,SAAS,EACL,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,GAC1B,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,GACvB,GAAG,CAAC,SAAS,CAAC,EAClB,QAAQ,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACpC,oBAAoB,EAAE,MAAM,EAC5B,iBAAiB,2BAAiC,GACjD,IAAI,CAyCN"}

package/dist/src/functions/merge.lua

@@ -0,0 +1,210 @@
+local ____lualib = require("lualib_bundle")
+local Set = ____lualib.Set
+local Map = ____lualib.Map
+local ____exports = {}
+local mergeSerializedArray, mergeSerializedTSTLObject, mergeSerializedTable
+local ____constants = require("src.classes.features.other.saveDataManager.constants")
+local SAVE_DATA_MANAGER_DEBUG = ____constants.SAVE_DATA_MANAGER_DEBUG
+local ____SerializationBrand = require("src.enums.SerializationBrand")
+local SerializationBrand = ____SerializationBrand.SerializationBrand
+local ____SerializationType = require("src.enums.SerializationType")
+local SerializationType = ____SerializationType.SerializationType
+local ____array = require("src.functions.array")
+local isArray = ____array.isArray
+local ____deepCopy = require("src.functions.deepCopy")
+local deepCopy = ____deepCopy.deepCopy
+local ____log = require("src.functions.log")
+local log = ____log.log
+local ____serialization = require("src.functions.serialization")
+local deserializeIsaacAPIClass = ____serialization.deserializeIsaacAPIClass
+local isSerializationBrand = ____serialization.isSerializationBrand
+local isSerializedIsaacAPIClass = ____serialization.isSerializedIsaacAPIClass
+local ____table = require("src.functions.table")
+local clearTable = ____table.clearTable
+local iterateTableInOrder = ____table.iterateTableInOrder
+local ____tstlClass = require("src.functions.tstlClass")
+local isDefaultMap = ____tstlClass.isDefaultMap
+local isTSTLMap = ____tstlClass.isTSTLMap
+local isTSTLSet = ____tstlClass.isTSTLSet
+local ____types = require("src.functions.types")
+local isTable = ____types.isTable
+local ____utils = require("src.functions.utils")
+local getTraversalDescription = ____utils.getTraversalDescription
+--- `merge` takes the values from a new table and recursively merges them into an old object (while
+-- performing appropriate deserialization).
+-- 
+-- This function is used to merge incoming data from the "save#.dat" file into a mod's variables.
+-- Merging is useful instead of blowing away a table entirely because mod code often relies on the
+-- local table/object references.
+-- 
+-- This function always assumes that the new table is serialized data and will attempt to perform
+-- deserialization on the objects within. In other words, unlike the `deepCopy` function, the
+-- `merge` function will always operates in the mode of `SerializationType.DESERIALIZE`. For the
+-- types of objects that will be deserialized, see the documentation for the `deepCopy` function.
+-- 
+-- This function does not iterate over the old object, like you would naively expect. This is
+-- because it is common for a variable to have a type of `something | null`. If this is the case,
+-- the key would not appear when iterating over the old object (because a value of null transpiles
+-- to nil, which means the table key does not exist). Thus, we must instead iterate over the new
+-- object and copy the values backwards. The consequence of this is that `merge` 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.
+-- 
+-- @param oldObject The old object to merge the values into. This can be either a Lua table, a TSTL
+-- map, or a TSTL set.
+-- @param newTable The new table to merge the values from. This must be a Lua table that represents
+-- serialized data. In other words, it should be created with the `deepCopy`
+-- function using `SerializationType.SERIALIZE`.
+-- @param traversalDescription Used to track the current key that we are operating on for debugging
+-- purposes. Use a name that corresponds to the name of the merging
+-- table.
+-- @param classConstructors Optional. A Lua table that maps the name of a user-defined TSTL class to
+-- its corresponding constructor. If the `deepCopy` function finds any
+-- user-defined TSTL classes when recursively iterating through the given
+-- object, it will use this map to instantiate a new class. Default is an
+-- empty Lua table.
+function ____exports.merge(self, oldObject, newTable, traversalDescription, classConstructors)
+    if classConstructors == nil then
+        classConstructors = {}
+    end
+    if SAVE_DATA_MANAGER_DEBUG then
+        log(nil, "merge is traversing: " .. traversalDescription)
+    end
+    if not isTable(nil, oldObject) then
+        error("The first argument given to the merge function is not a table.")
+    end
+    if not isTable(nil, newTable) then
+        error("The second argument given to the merge function is not a table.")
+    end
+    if isArray(nil, oldObject) and isArray(nil, newTable) then
+        mergeSerializedArray(
+            nil,
+            oldObject,
+            newTable,
+            traversalDescription,
+            classConstructors
+        )
+        return
+    end
+    if isTSTLMap(nil, oldObject) or isTSTLSet(nil, oldObject) or isDefaultMap(nil, oldObject) then
+        mergeSerializedTSTLObject(
+            nil,
+            oldObject,
+            newTable,
+            traversalDescription,
+            classConstructors
+        )
+    else
+        mergeSerializedTable(
+            nil,
+            oldObject,
+            newTable,
+            traversalDescription,
+            classConstructors
+        )
+    end
+end
+function mergeSerializedArray(self, oldArray, newArray, traversalDescription, classConstructors)
+    if SAVE_DATA_MANAGER_DEBUG then
+        log(nil, "merge encountered an array: " .. traversalDescription)
+    end
+    clearTable(nil, oldArray)
+    iterateTableInOrder(
+        nil,
+        newArray,
+        function(____, key, value)
+            local deserializedValue = deepCopy(
+                nil,
+                value,
+                SerializationType.DESERIALIZE,
+                traversalDescription,
+                classConstructors
+            )
+            oldArray[key] = deserializedValue
+        end,
+        SAVE_DATA_MANAGER_DEBUG
+    )
+end
+function mergeSerializedTSTLObject(self, oldObject, newTable, traversalDescription, classConstructors)
+    if SAVE_DATA_MANAGER_DEBUG then
+        log(nil, "merge encountered a TSTL object: " .. traversalDescription)
+    end
+    oldObject:clear()
+    local convertStringKeysToNumbers = newTable[SerializationBrand.OBJECT_WITH_NUMBER_KEYS] ~= nil
+    iterateTableInOrder(
+        nil,
+        newTable,
+        function(____, key, value)
+            if isSerializationBrand(nil, key) then
+                return
+            end
+            local keyToUse = key
+            if convertStringKeysToNumbers then
+                local numberKey = tonumber(key)
+                if numberKey == nil then
+                    return
+                end
+                keyToUse = numberKey
+            end
+            if isTSTLMap(nil, oldObject) or isDefaultMap(nil, oldObject) then
+                local deserializedValue = deepCopy(
+                    nil,
+                    value,
+                    SerializationType.DESERIALIZE,
+                    traversalDescription,
+                    classConstructors
+                )
+                oldObject:set(keyToUse, deserializedValue)
+            elseif isTSTLSet(nil, oldObject) then
+                oldObject:add(keyToUse)
+            end
+        end,
+        SAVE_DATA_MANAGER_DEBUG
+    )
+end
+function mergeSerializedTable(self, oldTable, newTable, traversalDescription, classConstructors)
+    if SAVE_DATA_MANAGER_DEBUG then
+        log(nil, "merge encountered a Lua table: " .. traversalDescription)
+    end
+    iterateTableInOrder(
+        nil,
+        newTable,
+        function(____, key, value)
+            if SAVE_DATA_MANAGER_DEBUG then
+                local valueToPrint = value == "" and "(empty string)" or tostring(value)
+                log(nil, (("merge is merging: " .. traversalDescription) .. " --> ") .. valueToPrint)
+            end
+            if isSerializationBrand(nil, key) then
+                return
+            end
+            if isSerializedIsaacAPIClass(nil, value) then
+                if SAVE_DATA_MANAGER_DEBUG then
+                    log(nil, "merge found a serialized Isaac API class.")
+                end
+                local deserializedObject = deserializeIsaacAPIClass(nil, value)
+                oldTable[key] = deserializedObject
+                return
+            end
+            if isTable(nil, value) then
+                local oldValue = oldTable[key]
+                if not isTable(nil, oldValue) then
+                    oldValue = {}
+                    oldTable[key] = oldValue
+                end
+                traversalDescription = getTraversalDescription(nil, key, traversalDescription)
+                ____exports.merge(
+                    nil,
+                    oldValue,
+                    value,
+                    traversalDescription,
+                    classConstructors
+                )
+            else
+                oldTable[key] = value
+            end
+        end,
+        SAVE_DATA_MANAGER_DEBUG
+    )
+end
+return ____exports

package/dist/src/functions/mergeTests.d.ts

@@ -1,6 +1,5 @@
 /**
- * Run the suite of tests that prove that the "merge" function works properly. (This function is not
- * exported but is used internally in the save data manager.)
+ * Run the suite of tests that prove that the "merge" function works properly.
  *
  * This function is only useful if you are troubleshooting the save data manager.
  */

package/dist/src/functions/mergeTests.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mergeTests.d.ts","sourceRoot":"","sources":["../../../src/functions/mergeTests.ts"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAkBpC"}
+{"version":3,"file":"mergeTests.d.ts","sourceRoot":"","sources":["../../../src/functions/mergeTests.ts"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAkBpC"}

package/dist/src/functions/mergeTests.lua

@@ -7,12 +7,12 @@ local ____DefaultMap = require("src.classes.DefaultMap")
 local DefaultMap = ____DefaultMap.DefaultMap
 local ____SerializationType = require("src.enums.SerializationType")
 local SerializationType = ____SerializationType.SerializationType
-local ____merge = require("src.features.saveDataManager.merge")
-local merge = ____merge.merge
 local ____deepCopy = require("src.functions.deepCopy")
 local deepCopy = ____deepCopy.deepCopy
 local ____log = require("src.functions.log")
 local log = ____log.log
+local ____merge = require("src.functions.merge")
+local merge = ____merge.merge
 local ____rng = require("src.functions.rng")
 local isRNG = ____rng.isRNG
 local newRNG = ____rng.newRNG
@@ -238,8 +238,7 @@ function oldTableHasRNGSerialized(self)
         error("The old table's seed not match: " .. tostring(seed))
     end
 end
---- Run the suite of tests that prove that the "merge" function works properly. (This function is not
--- exported but is used internally in the save data manager.)
+--- Run the suite of tests that prove that the "merge" function works properly.
 -- 
 -- This function is only useful if you are troubleshooting the save data manager.
 function ____exports.runMergeTests(self)

package/dist/src/functions/nextStage.d.ts

@@ -3,15 +3,19 @@ import { LevelStage, StageType } from "isaac-typescript-definitions";
  * Helper function to get the stage that a trapdoor or heaven door would take the player to, based
  * on the current stage, room, and game state flags.
  *
- * Note that in non-upgraded mods, this function will not account for the player having visited
- * Repentance floors in The Ascent. (Handling this requires stateful tracking as the player
- * progresses through the run.)
+ * If you want to account for the player having visited Repentance floors in The Ascent, use the
+ * `getNextStageUsingHistory` helper function instead (from the stage history feature). Handling
+ * this requires stateful tracking as the player progresses through the run.
  */
 export declare function getNextStage(): LevelStage;
 /**
  * Helper function to get the stage type that a trapdoor or heaven door would take the player to,
  * based on the current stage, room, and game state flags.
  *
+ * If you want to account for previous floors visited on The Ascent, use the
+ * `getNextStageTypeUsingHistory` helper function instead (from the stage history feature). Handling
+ * this requires stateful tracking as the player progresses through the run.
+ *
  * @param upwards Whether or not the player should go up to Cathedral in the case of being on Womb
  *                2. Default is false.
  */

package/dist/src/functions/nextStage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nextStage.d.ts","sourceRoot":"","sources":["../../../src/functions/nextStage.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,UAAU,EACV,SAAS,EACV,MAAM,8BAA8B,CAAC;AAYtC;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,UAAU,CAwFzC;AA+HD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,UAAQ,GAAG,SAAS,CAiF3D"}
+{"version":3,"file":"nextStage.d.ts","sourceRoot":"","sources":["../../../src/functions/nextStage.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,UAAU,EACV,SAAS,EACV,MAAM,8BAA8B,CAAC;AAUtC;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,UAAU,CAwFzC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,UAAQ,GAAG,SAAS,CAiF3D"}

package/dist/src/functions/nextStage.lua

@@ -1,5 +1,4 @@
 local ____exports = {}
-local getNextStageBackwardsPath, getStageTypeBackwardsPath
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local GameStateFlag = ____isaac_2Dtypescript_2Ddefinitions.GameStateFlag
 local GridRoom = ____isaac_2Dtypescript_2Ddefinitions.GridRoom
@@ -7,10 +6,6 @@ local LevelStage = ____isaac_2Dtypescript_2Ddefinitions.LevelStage
 local StageType = ____isaac_2Dtypescript_2Ddefinitions.StageType
 local ____cachedClasses = require("src.core.cachedClasses")
 local game = ____cachedClasses.game
-local ____stageHistory = require("src.features.stageHistory")
-local hasVisitedStage = ____stageHistory.hasVisitedStage
-local ____featuresInitialized = require("src.featuresInitialized")
-local areFeaturesInitialized = ____featuresInitialized.areFeaturesInitialized
 local ____roomData = require("src.functions.roomData")
 local getRoomGridIndex = ____roomData.getRoomGridIndex
 local ____stage = require("src.functions.stage")
@@ -19,125 +14,12 @@ local calculateStageTypeRepentance = ____stage.calculateStageTypeRepentance
 local onRepentanceStage = ____stage.onRepentanceStage
 local ____types = require("src.functions.types")
 local asNumber = ____types.asNumber
-function getNextStageBackwardsPath(self, stage, repentanceStage)
-    if not areFeaturesInitialized(nil) then
-        return asNumber(nil, stage) - 1
-    end
-    local visitedDownpour1 = hasVisitedStage(nil, LevelStage.BASEMENT_1, StageType.REPENTANCE)
-    local visitedDross1 = hasVisitedStage(nil, LevelStage.BASEMENT_1, StageType.REPENTANCE_B)
-    local visitedDownpour2 = hasVisitedStage(nil, LevelStage.BASEMENT_2, StageType.REPENTANCE)
-    local visitedDross2 = hasVisitedStage(nil, LevelStage.BASEMENT_2, StageType.REPENTANCE_B)
-    local visitedMines1 = hasVisitedStage(nil, LevelStage.CAVES_1, StageType.REPENTANCE)
-    local visitedAshpit1 = hasVisitedStage(nil, LevelStage.CAVES_1, StageType.REPENTANCE_B)
-    local visitedMines2 = hasVisitedStage(nil, LevelStage.DEPTHS_2, StageType.REPENTANCE)
-    local visitedAshpit2 = hasVisitedStage(nil, LevelStage.DEPTHS_2, StageType.REPENTANCE_B)
-    if stage == LevelStage.BASEMENT_1 then
-        if repentanceStage then
-            return LevelStage.BASEMENT_1
-        end
-        return LevelStage.HOME
-    end
-    if stage == LevelStage.BASEMENT_2 then
-        if repentanceStage then
-            if visitedDownpour1 or visitedDross1 then
-                return LevelStage.BASEMENT_1
-            end
-            return LevelStage.BASEMENT_2
-        end
-        return LevelStage.BASEMENT_1
-    end
-    if stage == LevelStage.CAVES_1 then
-        if repentanceStage then
-            if visitedDownpour2 or visitedDross2 then
-                return LevelStage.BASEMENT_2
-            end
-            return LevelStage.CAVES_1
-        end
-        return LevelStage.BASEMENT_2
-    end
-    if stage == LevelStage.CAVES_2 then
-        if repentanceStage then
-            if visitedMines1 or visitedAshpit1 then
-                return LevelStage.CAVES_1
-            end
-            return LevelStage.CAVES_2
-        end
-        return LevelStage.CAVES_1
-    end
-    if stage == LevelStage.DEPTHS_1 then
-        if repentanceStage then
-            if visitedMines2 or visitedAshpit2 then
-                return LevelStage.CAVES_2
-            end
-            return LevelStage.DEPTHS_1
-        end
-        return LevelStage.CAVES_2
-    end
-    if stage == LevelStage.DEPTHS_2 then
-        if repentanceStage then
-            return LevelStage.DEPTHS_2
-        end
-        return LevelStage.DEPTHS_1
-    end
-    return asNumber(nil, stage) - 1
-end
-function getStageTypeBackwardsPath(self, stage, nextStage, repentanceStage)
-    local visitedDownpour1 = hasVisitedStage(nil, LevelStage.BASEMENT_1, StageType.REPENTANCE)
-    local visitedDross1 = hasVisitedStage(nil, LevelStage.BASEMENT_1, StageType.REPENTANCE_B)
-    local visitedDownpour2 = hasVisitedStage(nil, LevelStage.BASEMENT_2, StageType.REPENTANCE)
-    local visitedDross2 = hasVisitedStage(nil, LevelStage.BASEMENT_2, StageType.REPENTANCE_B)
-    local visitedMines1 = hasVisitedStage(nil, LevelStage.CAVES_1, StageType.REPENTANCE)
-    local visitedAshpit1 = hasVisitedStage(nil, LevelStage.CAVES_1, StageType.REPENTANCE_B)
-    local visitedMines2 = hasVisitedStage(nil, LevelStage.DEPTHS_2, StageType.REPENTANCE)
-    local visitedAshpit2 = hasVisitedStage(nil, LevelStage.DEPTHS_2, StageType.REPENTANCE_B)
-    if stage == LevelStage.BASEMENT_2 and repentanceStage then
-        if visitedDownpour1 then
-            return StageType.REPENTANCE
-        end
-        if visitedDross1 then
-            return StageType.REPENTANCE_B
-        end
-    end
-    if stage == LevelStage.CAVES_1 and repentanceStage then
-        if visitedDownpour2 then
-            return StageType.REPENTANCE
-        end
-        if visitedDross2 then
-            return StageType.REPENTANCE_B
-        end
-    end
-    if stage == LevelStage.CAVES_2 and not repentanceStage then
-        if visitedDownpour2 then
-            return StageType.REPENTANCE
-        end
-        if visitedDross2 then
-            return StageType.REPENTANCE_B
-        end
-    end
-    if stage == LevelStage.CAVES_2 and repentanceStage then
-        if visitedMines1 then
-            return StageType.REPENTANCE
-        end
-        if visitedAshpit1 then
-            return StageType.REPENTANCE_B
-        end
-    end
-    if stage == LevelStage.DEPTHS_2 and not repentanceStage then
-        if visitedAshpit2 then
-            return StageType.REPENTANCE_B
-        end
-        if visitedMines2 then
-            return StageType.REPENTANCE
-        end
-    end
-    return calculateStageType(nil, nextStage)
-end
 --- Helper function to get the stage that a trapdoor or heaven door would take the player to, based
 -- on the current stage, room, and game state flags.
 -- 
--- Note that in non-upgraded mods, this function will not account for the player having visited
--- Repentance floors in The Ascent. (Handling this requires stateful tracking as the player
--- progresses through the run.)
+-- If you want to account for the player having visited Repentance floors in The Ascent, use the
+-- `getNextStageUsingHistory` helper function instead (from the stage history feature). Handling
+-- this requires stateful tracking as the player progresses through the run.
 function ____exports.getNextStage(self)
     local level = game:GetLevel()
     local backwardsPath = game:GetStateFlag(GameStateFlag.BACKWARDS_PATH)
@@ -146,7 +28,7 @@ function ____exports.getNextStage(self)
     local repentanceStage = onRepentanceStage(nil)
     local roomGridIndex = getRoomGridIndex(nil)
     if backwardsPath then
-        return getNextStageBackwardsPath(nil, stage, repentanceStage)
+        return asNumber(nil, stage) - 1
     end
     repeat
         local ____switch4 = roomGridIndex
@@ -201,6 +83,10 @@ end
 --- Helper function to get the stage type that a trapdoor or heaven door would take the player to,
 -- based on the current stage, room, and game state flags.
 -- 
+-- If you want to account for previous floors visited on The Ascent, use the
+-- `getNextStageTypeUsingHistory` helper function instead (from the stage history feature). Handling
+-- this requires stateful tracking as the player progresses through the run.
+-- 
 -- @param upwards Whether or not the player should go up to Cathedral in the case of being on Womb
 -- 2. Default is false.
 function ____exports.getNextStageType(self, upwards)
@@ -216,7 +102,7 @@ function ____exports.getNextStageType(self, upwards)
     local roomGridIndex = getRoomGridIndex(nil)
     local nextStage = ____exports.getNextStage(nil)
     if backwardsPath then
-        return getStageTypeBackwardsPath(nil, stage, nextStage, repentanceStage)
+        return calculateStageType(nil, nextStage)
     end
     if roomGridIndex == asNumber(nil, GridRoom.SECRET_EXIT) then
         return calculateStageTypeRepentance(nil, nextStage)

package/dist/src/functions/players.d.ts

@@ -66,13 +66,6 @@ export declare function getPlayerCloserThan(position: Vector, distance: float):
  * Note that this will filter out non-real collectibles like Lilith's Incubus.
  */
 export declare function getPlayerCollectibleCount(player: EntityPlayer, ...collectibleTypes: CollectibleType[]): int;
-/**
- * Iterates over every item in the game and returns a map containing the number of each item that
- * the player has.
- *
- * Note that this will filter out non-real collectibles like Lilith's Incubus.
- */
-export declare function getPlayerCollectibleMap(player: EntityPlayer): Map<CollectibleType, int>;
 /**
  * Helper function to get the player from a tear, laser, bomb, etc. Returns undefined if the entity
  * does not correspond to any particular player.
@@ -202,6 +195,13 @@ export declare function isKeeper(player: EntityPlayer): boolean;
 /** Helper function for detecting when a player is The Lost or Tainted Lost. */
 export declare function isLost(player: EntityPlayer): boolean;
 export declare function isModdedPlayer(player: EntityPlayer): boolean;
+/**
+ * Helper function for determining if a player is able to turn their head by pressing the shooting
+ * buttons.
+ *
+ * Under the hood, this function uses the `EntityPlayer.IsExtraAnimationFinished` method.
+ */
+export declare function isPlayerAbleToAim(player: EntityPlayer): boolean;
 /** Helper function for detecting if a player is one of the Tainted characters. */
 export declare function isTainted(player: EntityPlayer): boolean;
 /** Helper function for detecting when a player is Tainted Lazarus or Dead Tainted Lazarus. */