isaacscript-common 2.3.2 → 3.1.1

package/functions/deepCopy.lua

@@ -1,11 +1,9 @@
 local ____lualib = require("lualib_bundle")
 local Set = ____lualib.Set
 local __TS__New = ____lualib.__TS__New
-local __TS__InstanceOf = ____lualib.__TS__InstanceOf
 local Map = ____lualib.Map
-local WeakMap = ____lualib.WeakMap
-local WeakSet = ____lualib.WeakSet
 local __TS__Iterator = ____lualib.__TS__Iterator
+local __TS__ArraySort = ____lualib.__TS__ArraySort
 local __TS__ArraySome = ____lualib.__TS__ArraySome
 local ____exports = {}
 local deepCopyTable, deepCopyDefaultMap, deepCopyMap, deepCopySet, deepCopyTSTLClass, deepCopyArray, deepCopyNormalLuaTable, getCopiedEntries, checkMetatable, deepCopyUserdata, COPYABLE_ISAAC_API_CLASS_TYPES_SET
@@ -26,19 +24,50 @@ local isArray = ____array.isArray
 local ____enums = require("functions.enums")
 local getEnumValues = ____enums.getEnumValues
 local ____isaacAPIClass = require("functions.isaacAPIClass")
-local getIsaacAPIClassType = ____isaacAPIClass.getIsaacAPIClassType
+local getIsaacAPIClassName = ____isaacAPIClass.getIsaacAPIClassName
 local ____log = require("functions.log")
 local log = ____log.log
+local logTable = ____log.logTable
 local ____serialization = require("functions.serialization")
 local copyIsaacAPIClass = ____serialization.copyIsaacAPIClass
 local deserializeIsaacAPIClass = ____serialization.deserializeIsaacAPIClass
 local isSerializedIsaacAPIClass = ____serialization.isSerializedIsaacAPIClass
 local ____tstlClass = require("functions.tstlClass")
+local getTSTLClassName = ____tstlClass.getTSTLClassName
+local isDefaultMap = ____tstlClass.isDefaultMap
+local isTSTLMap = ____tstlClass.isTSTLMap
+local isTSTLSet = ____tstlClass.isTSTLSet
 local isUserDefinedTSTLClass = ____tstlClass.isUserDefinedTSTLClass
 local newTSTLClass = ____tstlClass.newTSTLClass
 local ____utils = require("functions.utils")
 local ensureAllCases = ____utils.ensureAllCases
 local getTraversalDescription = ____utils.getTraversalDescription
+local twoDimensionalSort = ____utils.twoDimensionalSort
+--- `deepCopy` is a semi-generic deep cloner. It will recursively copy all of the values so that none
+-- of the nested references remain.
+-- 
+-- It supports the following object types:
+-- 
+-- - Primitives (i.e. strings, numbers, and booleans)
+-- - `LuaTable` / basic TSTL objects
+-- - TSTL `Map`
+-- - TSTL `Set`
+-- - TSTL classes
+-- - `DefaultMap`
+-- - Isaac `Color` objects
+-- - Isaac `KColor` objects
+-- - Isaac `RNG` objects
+-- - Isaac `Vector` objects
+-- 
+-- It does not support:
+-- - objects with values of `null` (since that transpiles to `nil`)
+-- - other Isaac API objects such as `EntityPtr` (that have a type of "userdata")
+-- 
+-- @param value The primitive or object to copy.
+-- @param serializationType Has 3 possible values. Can leave objects as-is, or can serialize objects
+-- to Lua tables, or can deserialize Lua tables to objects. Default is
+-- `SerializationType.NONE`.
+-- @param traversalDescription Used to track the current key that we are operating on.
 function ____exports.deepCopy(self, value, serializationType, traversalDescription)
     if serializationType == nil then
         serializationType = SerializationType.NONE
@@ -95,19 +124,20 @@ function ____exports.deepCopy(self, value, serializationType, traversalDescripti
     until true
 end
 function deepCopyTable(self, ____table, serializationType, traversalDescription)
-    if __TS__InstanceOf(____table, DefaultMap) or ____table[SerializationBrand.DEFAULT_MAP] ~= nil then
+    if isDefaultMap(nil, ____table) or ____table[SerializationBrand.DEFAULT_MAP] ~= nil then
         return deepCopyDefaultMap(nil, ____table, serializationType, traversalDescription)
     end
-    if __TS__InstanceOf(____table, Map) or ____table[SerializationBrand.MAP] ~= nil then
+    if isTSTLMap(nil, ____table) or ____table[SerializationBrand.MAP] ~= nil then
         return deepCopyMap(nil, ____table, serializationType, traversalDescription)
     end
-    if __TS__InstanceOf(____table, Set) or ____table[SerializationBrand.SET] ~= nil then
+    if isTSTLSet(nil, ____table) or ____table[SerializationBrand.SET] ~= nil then
         return deepCopySet(nil, ____table, serializationType, traversalDescription)
     end
-    if __TS__InstanceOf(____table, WeakMap) then
+    local className = getTSTLClassName(nil, ____table)
+    if className == "WeakMap" then
         error("The deep copy function does not support copying the \"WeakMap\" class for: " .. traversalDescription)
     end
-    if __TS__InstanceOf(____table, WeakSet) then
+    if className == "WeakSet" then
         error("The deep copy function does not support copying the \"WeakSet\" class for: " .. traversalDescription)
     end
     if isUserDefinedTSTLClass(nil, ____table) then
@@ -123,13 +153,13 @@ function deepCopyTable(self, ____table, serializationType, traversalDescription)
     return deepCopyNormalLuaTable(nil, ____table, serializationType, traversalDescription)
 end
 function deepCopyDefaultMap(self, defaultMap, serializationType, traversalDescription)
-    local ____temp_0
-    if __TS__InstanceOf(defaultMap, DefaultMap) then
-        ____temp_0 = defaultMap:getConstructorArg()
+    local ____isDefaultMap_result_0
+    if isDefaultMap(nil, defaultMap) then
+        ____isDefaultMap_result_0 = defaultMap:getConstructorArg()
     else
-        ____temp_0 = nil
+        ____isDefaultMap_result_0 = nil
     end
-    local constructorArg = ____temp_0
+    local constructorArg = ____isDefaultMap_result_0
     local newDefaultMap
     repeat
         local ____switch23 = serializationType
@@ -155,7 +185,7 @@ function deepCopyDefaultMap(self, defaultMap, serializationType, traversalDescri
         ____cond23 = ____cond23 or ____switch23 == SerializationType.DESERIALIZE
         if ____cond23 then
             do
-                if __TS__InstanceOf(defaultMap, DefaultMap) then
+                if isDefaultMap(nil, defaultMap) then
                     error(("The deep copy function failed to deserialize a default map of \"" .. traversalDescription) .. "\", since it was not a Lua table.")
                 end
                 local defaultMapValue = defaultMap[SerializationBrand.DEFAULT_MAP_VALUE]
@@ -176,7 +206,7 @@ function deepCopyDefaultMap(self, defaultMap, serializationType, traversalDescri
     local entries = ____getCopiedEntries_result_1.entries
     local convertedNumberKeysToStrings = ____getCopiedEntries_result_1.convertedNumberKeysToStrings
     if convertedNumberKeysToStrings then
-        if __TS__InstanceOf(newDefaultMap, DefaultMap) then
+        if isDefaultMap(nil, newDefaultMap) then
             newDefaultMap:set(SerializationBrand.OBJECT_WITH_NUMBER_KEYS, "")
         else
             newDefaultMap[SerializationBrand.OBJECT_WITH_NUMBER_KEYS] = ""
@@ -185,7 +215,7 @@ function deepCopyDefaultMap(self, defaultMap, serializationType, traversalDescri
     for ____, ____value in ipairs(entries) do
         local key = ____value[1]
         local value = ____value[2]
-        if __TS__InstanceOf(newDefaultMap, DefaultMap) then
+        if isDefaultMap(nil, newDefaultMap) then
             newDefaultMap:set(key, value)
         else
             newDefaultMap[key] = value
@@ -205,7 +235,7 @@ function deepCopyMap(self, map, serializationType, traversalDescription)
     local entries = ____getCopiedEntries_result_2.entries
     local convertedNumberKeysToStrings = ____getCopiedEntries_result_2.convertedNumberKeysToStrings
     if convertedNumberKeysToStrings then
-        if __TS__InstanceOf(newMap, Map) then
+        if isTSTLMap(nil, newMap) then
             newMap:set(SerializationBrand.OBJECT_WITH_NUMBER_KEYS, "")
         else
             newMap[SerializationBrand.OBJECT_WITH_NUMBER_KEYS] = ""
@@ -214,7 +244,7 @@ function deepCopyMap(self, map, serializationType, traversalDescription)
     for ____, ____value in ipairs(entries) do
         local key = ____value[1]
         local value = ____value[2]
-        if __TS__InstanceOf(newMap, Map) then
+        if isTSTLMap(nil, newMap) then
             newMap:set(key, value)
         else
             newMap[key] = value
@@ -234,7 +264,7 @@ function deepCopySet(self, set, serializationType, traversalDescription)
     local entries = ____getCopiedEntries_result_3.entries
     local convertedNumberKeysToStrings = ____getCopiedEntries_result_3.convertedNumberKeysToStrings
     if convertedNumberKeysToStrings then
-        if __TS__InstanceOf(newSet, Set) then
+        if isTSTLSet(nil, newSet) then
             error("The deep copy function cannot convert number keys to strings for a Set.")
         else
             newSet[SerializationBrand.OBJECT_WITH_NUMBER_KEYS] = ""
@@ -242,7 +272,7 @@ function deepCopySet(self, set, serializationType, traversalDescription)
     end
     for ____, ____value in ipairs(entries) do
         local key = ____value[1]
-        if __TS__InstanceOf(newSet, Set) then
+        if isTSTLSet(nil, newSet) then
             newSet:add(key)
         else
             newSet[key] = ""
@@ -295,7 +325,7 @@ function deepCopyNormalLuaTable(self, ____table, serializationType, traversalDes
 end
 function getCopiedEntries(self, object, serializationType, traversalDescription)
     local entries = {}
-    if __TS__InstanceOf(object, Map) or __TS__InstanceOf(object, Set) then
+    if isTSTLMap(nil, object) or isTSTLSet(nil, object) or isDefaultMap(nil, object) then
         for ____, ____value in __TS__Iterator(object:entries()) do
             local key = ____value[1]
             local value = ____value[2]
@@ -306,6 +336,10 @@ function getCopiedEntries(self, object, serializationType, traversalDescription)
             entries[#entries + 1] = {key, value}
         end
     end
+    if SAVE_DATA_MANAGER_DEBUG then
+        logTable(entries)
+        __TS__ArraySort(entries, twoDimensionalSort)
+    end
     local hasNumberKeys = __TS__ArraySome(
         entries,
         function(____, ____bindingPattern0)
@@ -321,14 +355,14 @@ function getCopiedEntries(self, object, serializationType, traversalDescription)
         local value = ____value[2]
         do
             if isSerializationBrand(nil, key) then
-                goto __continue78
+                goto __continue79
             end
             traversalDescription = getTraversalDescription(nil, key, traversalDescription)
             local newValue = ____exports.deepCopy(nil, value, serializationType, traversalDescription)
             local keyToUse = convertNumberKeysToStrings and tostring(key) or key
             copiedEntries[#copiedEntries + 1] = {keyToUse, newValue}
         end
-        ::__continue78::
+        ::__continue79::
     end
     return {entries = copiedEntries, convertedNumberKeysToStrings = convertNumberKeysToStrings}
 end
@@ -338,10 +372,10 @@ function checkMetatable(self, ____table, traversalDescription)
         return
     end
     local tableDescription = traversalDescription == "" and "the table to copy" or ("\"" .. traversalDescription) .. "\""
-    error(("The deepCopy function detected that \"" .. tableDescription) .. "\" has a metatable. Copying tables with metatables is not supported, unless they are explicitly handled by the save data manager. (e.g. TypeScriptToLua Maps, TypeScriptToLua Sets, etc.)")
+    error(("The deepCopy function detected that " .. tableDescription) .. " has a metatable. Copying tables with metatables is not supported, unless they are explicitly handled by the save data manager. (e.g. TypeScriptToLua Maps, TypeScriptToLua Sets, etc.)")
 end
 function deepCopyUserdata(self, value, serializationType, traversalDescription)
-    local classType = getIsaacAPIClassType(nil, value)
+    local classType = getIsaacAPIClassName(nil, value)
     if classType == nil then
         error("The deep copy function was not able to derive the Isaac API class type for: " .. traversalDescription)
     end

package/functions/deepCopyTests.lua

@@ -1,7 +1,6 @@
 local ____lualib = require("lualib_bundle")
 local Map = ____lualib.Map
 local __TS__New = ____lualib.__TS__New
-local __TS__InstanceOf = ____lualib.__TS__InstanceOf
 local Set = ____lualib.Set
 local ____exports = {}
 local copiedObjectIsTable, copiedObjectHasKeyAndValueString, copiedTableHasKeyAndValueNumber, copiedTableDoesNotCoerceTypes, copiedObjectHasNoReferencesForPrimitivesForward, copiedObjectHasNoReferencesForPrimitivesBackward, copiedObjectHasNoReferencesForArray, copiedObjectHasChildObject, copiedMapIsMap, copiedMapHasValue, copiedSetIsSet, copiedSetHasValue, copiedMapHasChildMap, copiedDefaultMapHasChildDefaultMap, copiedDefaultMapHasBrand
@@ -17,6 +16,10 @@ local ____deepCopy = require("functions.deepCopy")
 local deepCopy = ____deepCopy.deepCopy
 local ____log = require("functions.log")
 local log = ____log.log
+local ____tstlClass = require("functions.tstlClass")
+local isDefaultMap = ____tstlClass.isDefaultMap
+local isTSTLMap = ____tstlClass.isTSTLMap
+local isTSTLSet = ____tstlClass.isTSTLSet
 function copiedObjectIsTable(self)
     local oldObject = {abc = "def"}
     local newObject = deepCopy(nil, oldObject)
@@ -173,7 +176,7 @@ function copiedMapIsMap(self)
     if newMapType ~= "table" then
         error("The copied Map was not a table.")
     end
-    if not __TS__InstanceOf(newMap, Map) then
+    if not isTSTLMap(nil, newMap) then
         error("The copied Map was not a Map.")
     end
 end
@@ -202,7 +205,7 @@ function copiedSetIsSet(self)
     if newSetType ~= "table" then
         error("The copied Set was not a table.")
     end
-    if not __TS__InstanceOf(newSet, Set) then
+    if not isTSTLSet(nil, newSet) then
         error("The copied Set was not a Map.")
     end
 end
@@ -235,7 +238,7 @@ function copiedMapHasChildMap(self)
     if newChildMapType ~= "table" then
         error("The copied child Map had a type of: " .. newChildMapType)
     end
-    if not __TS__InstanceOf(newChildMap, Map) then
+    if not isTSTLMap(nil, newChildMap) then
         error("The copied child Map was not a Map.")
     end
     local value = newChildMap:get(childMapKey)
@@ -269,7 +272,7 @@ function copiedDefaultMapHasChildDefaultMap(self)
     if newChildMapType ~= "table" then
         error("The copied child DefaultMap had a type of: " .. newChildMapType)
     end
-    if not __TS__InstanceOf(newChildMap, DefaultMap) then
+    if not isDefaultMap(nil, newChildMap) then
         error("The copied child DefaultMap was not a DefaultMap.")
     end
     local newChildMapValue1 = newChildMap:get(childMapKey1)

package/functions/direction.d.ts

@@ -1,4 +1,12 @@
 import { Direction } from "isaac-typescript-definitions";
+/**
+ * Helper function to convert the degrees of an angle to the `Direction` enum.
+ *
+ * Note that this function considers 0 degrees to be pointing to the right, which is unusual because
+ * 0 normally corresponds to up. (This corresponds to how the `Vector.GetAngleDegrees` method
+ * works.)
+ */
+export declare function angleToDirection(angleDegrees: int): Direction;
 export declare function directionToDegrees(direction: Direction): int;
 export declare function directionToVector(direction: Direction): Vector;
 export declare function getDirectionName(direction: Direction): string | undefined;

package/functions/direction.lua

@@ -1,10 +1,37 @@
 local ____exports = {}
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local Direction = ____isaac_2Dtypescript_2Ddefinitions.Direction
 local ____directionNames = require("objects.directionNames")
 local DIRECTION_NAMES = ____directionNames.DIRECTION_NAMES
 local ____directionToDegrees = require("objects.directionToDegrees")
 local DIRECTION_TO_DEGREES = ____directionToDegrees.DIRECTION_TO_DEGREES
 local ____directionToVector = require("objects.directionToVector")
 local DIRECTION_TO_VECTOR = ____directionToVector.DIRECTION_TO_VECTOR
+--- Helper function to convert the degrees of an angle to the `Direction` enum.
+-- 
+-- Note that this function considers 0 degrees to be pointing to the right, which is unusual because
+-- 0 normally corresponds to up. (This corresponds to how the `Vector.GetAngleDegrees` method
+-- works.)
+function ____exports.angleToDirection(self, angleDegrees)
+    local positiveDegrees = angleDegrees
+    while positiveDegrees < 0 do
+        positiveDegrees = positiveDegrees + 360
+    end
+    local normalizedDegrees = positiveDegrees % 360
+    if normalizedDegrees < 45 then
+        return Direction.RIGHT
+    end
+    if normalizedDegrees < 135 then
+        return Direction.DOWN
+    end
+    if normalizedDegrees < 225 then
+        return Direction.LEFT
+    end
+    if normalizedDegrees < 315 then
+        return Direction.UP
+    end
+    return Direction.RIGHT
+end
 function ____exports.directionToDegrees(self, direction)
     return DIRECTION_TO_DEGREES[direction]
 end

package/functions/doors.d.ts

@@ -45,6 +45,7 @@ export declare function getDoors(...roomTypes: RoomType[]): GridEntityDoor[];
  * that match any of the N room grid indexes.
  */
 export declare function getDoorsToRoomIndex(...roomGridIndex: int[]): GridEntityDoor[];
+export declare function getOppositeDoorSlot(doorSlot: DoorSlot): DoorSlot | undefined;
 export declare function getRepentanceDoor(): GridEntityDoor | undefined;
 /** Helper function to find unused door slots in the room that can be used to make custom doors. */
 export declare function getUnusedDoorSlots(): DoorSlot[];

package/functions/doors.lua

@@ -18,6 +18,8 @@ local DEFAULT_DOOR_SLOT = ____doorSlotFlagToDoorSlot.DEFAULT_DOOR_SLOT
 local DOOR_SLOT_FLAG_TO_DOOR_SLOT = ____doorSlotFlagToDoorSlot.DOOR_SLOT_FLAG_TO_DOOR_SLOT
 local ____doorSlotToDirection = require("objects.doorSlotToDirection")
 local DOOR_SLOT_TO_DIRECTION = ____doorSlotToDirection.DOOR_SLOT_TO_DIRECTION
+local ____oppositeDoorSlots = require("objects.oppositeDoorSlots")
+local OPPOSITE_DOOR_SLOTS = ____oppositeDoorSlots.OPPOSITE_DOOR_SLOTS
 local ____roomShapeToDoorSlots = require("objects.roomShapeToDoorSlots")
 local ROOM_SHAPE_TO_DOOR_SLOTS = ____roomShapeToDoorSlots.ROOM_SHAPE_TO_DOOR_SLOTS
 local ____direction = require("functions.direction")
@@ -27,11 +29,19 @@ local getEnumValues = ____enums.getEnumValues
 function ____exports.doorSlotToDirection(self, doorSlot)
     return DOOR_SLOT_TO_DIRECTION[doorSlot]
 end
+--- Helper function to help calculate the position that a player will enter a room at.
+-- 
+-- When players enter a room, they do not appear exactly on the location of the door, because then
+-- they would immediately collide with the loading zone. Instead, they are offset by a certain
+-- amount of units.
 function ____exports.getDoorEnterPositionOffset(self, doorSlot)
     local direction = ____exports.doorSlotToDirection(nil, doorSlot)
     local vector = directionToVector(nil, direction)
     return vector * ROOM_ENTRY_OFFSET_FROM_DOOR
 end
+--- Helper function to get all of the doors in the room. By default, it will return every door. You
+-- can optionally specify one or more room types to return only the doors that match the specified
+-- room types.
 function ____exports.getDoors(self, ...)
     local roomTypes = {...}
     local room = game:GetRoom()
@@ -60,10 +70,14 @@ function ____exports.isSecretRoomDoor(self, door)
     local filename = sprite:GetFilename()
     return filename == "gfx/grid/Door_08_HoleInWall.anm2"
 end
+--- Helper function to remove a single door.
 function ____exports.removeDoor(self, door)
     local room = game:GetRoom()
     room:RemoveDoor(door.Slot)
 end
+--- Helper function to remove the doors provided.
+-- 
+-- This function is variadic, meaning that you can specify as many doors as you want to remove.
 function ____exports.removeDoors(self, ...)
     local doors = {...}
     for ____, door in ipairs(doors) do
@@ -76,6 +90,8 @@ function ____exports.closeAllDoors(self)
         door:Close(true)
     end
 end
+--- Use this instead of the `GridEntityDoor.Close` method if you want the door to immediately close
+-- without an animation.
 function ____exports.closeDoorFast(self, door)
     door.State = DoorState.CLOSED
     local sprite = door:GetSprite()
@@ -105,6 +121,8 @@ function ____exports.getDevilRoomDoor(self)
     end
     return ____temp_1
 end
+--- If there is both a Devil Room and an Angel Room door, this function will return door with the
+-- lowest slot number.
 function ____exports.getDevilRoomOrAngelRoomDoor(self)
     local devilRoomOrAngelRoomDoors = ____exports.getDoors(nil, RoomType.DEVIL, RoomType.ANGEL)
     local ____temp_2
@@ -115,14 +133,24 @@ function ____exports.getDevilRoomOrAngelRoomDoor(self)
     end
     return ____temp_2
 end
+--- Helper function to get the position that a player will enter a room at.
+-- 
+-- When players enter a room, they do not appear exactly on the location of the door, because then
+-- they would immediately collide with the loading zone. Instead, they are offset by a certain
+-- amount of units.
 function ____exports.getDoorEnterPosition(self, door)
     local offset = ____exports.getDoorEnterPositionOffset(nil, door.Slot)
     return door.Position + offset
 end
+--- Helper function to get the possible door slots that can exist for a given room shape.
 function ____exports.getDoorSlotsForRoomShape(self, roomShape)
     local doorSlots = ROOM_SHAPE_TO_DOOR_SLOTS[roomShape]
     return doorSlots == nil and __TS__New(Set) or doorSlots
 end
+--- Helper function to get all of the doors in the room that lead to the provided room index.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to return all of the doors
+-- that match any of the N room grid indexes.
 function ____exports.getDoorsToRoomIndex(self, ...)
     local roomGridIndex = {...}
     local roomGridIndexesSet = __TS__New(Set, roomGridIndex)
@@ -132,6 +160,9 @@ function ____exports.getDoorsToRoomIndex(self, ...)
         function(____, door) return roomGridIndexesSet:has(door.TargetRoomIndex) end
     )
 end
+function ____exports.getOppositeDoorSlot(self, doorSlot)
+    return OPPOSITE_DOOR_SLOTS[doorSlot]
+end
 function ____exports.getRepentanceDoor(self)
     local doors = ____exports.getDoors(nil)
     return __TS__ArrayFind(
@@ -139,6 +170,7 @@ function ____exports.getRepentanceDoor(self)
         function(____, door) return ____exports.isRepentanceDoor(nil, door) end
     )
 end
+--- Helper function to find unused door slots in the room that can be used to make custom doors.
 function ____exports.getUnusedDoorSlots(self)
     local room = game:GetRoom()
     local doorSlots = getEnumValues(nil, DoorSlot)
@@ -153,10 +185,13 @@ end
 function ____exports.isDevilRoomDoor(self, door)
     return door.TargetRoomType == RoomType.DEVIL
 end
+--- Helper function to see if a door slot could exist for a given room shape.
 function ____exports.isDoorSlotInRoomShape(self, doorSlot, roomShape)
     local doorSlots = ____exports.getDoorSlotsForRoomShape(nil, roomShape)
     return doorSlots:has(doorSlot)
 end
+--- This refers to the Repentance door that spawns in a boss room after defeating the boss. You have
+-- to spend one key to open it. It has a sprite filename of "gfx/grid/Door_Downpour.anm2".
 function ____exports.isDoorToDownpour(self, door)
     if not ____exports.isRepentanceDoor(nil, door) then
         return false
@@ -165,6 +200,8 @@ function ____exports.isDoorToDownpour(self, door)
     local filename = sprite:GetFilename()
     return filename == "gfx/grid/Door_Downpour.anm2"
 end
+--- This refers to the Repentance door that spawns in a boss room after defeating the boss. You have
+-- to spend two hearts to open it. It has a sprite filename of "gfx/grid/Door_Mausoleum.anm2".
 function ____exports.isDoorToMausoleum(self, door)
     if not ____exports.isRepentanceDoor(nil, door) then
         return false
@@ -173,6 +210,8 @@ function ____exports.isDoorToMausoleum(self, door)
     local filename = sprite:GetFilename()
     return filename == "gfx/grid/Door_Mausoleum.anm2"
 end
+--- This refers to the "strange door" located on the first room of Depths 2. You open it with either
+-- a Polaroid or a Negative. It has a sprite filename of "gfx/grid/Door_Mausoleum_Alt.anm2".
 function ____exports.isDoorToMausoleumAscent(self, door)
     if not ____exports.isRepentanceDoor(nil, door) then
         return false
@@ -181,6 +220,8 @@ function ____exports.isDoorToMausoleumAscent(self, door)
     local filename = sprite:GetFilename()
     return filename == "gfx/grid/Door_Mausoleum_Alt.anm2"
 end
+--- This refers to the Repentance door that spawns in a boss room after defeating the boss. You have
+-- to spend two bombs to open it. It has a sprite filename of "gfx/grid/Door_Mines.anm2".
 function ____exports.isDoorToMines(self, door)
     if not ____exports.isRepentanceDoor(nil, door) then
         return false
@@ -189,6 +230,8 @@ function ____exports.isDoorToMines(self, door)
     local filename = sprite:GetFilename()
     return filename == "gfx/grid/Door_Mines.anm2"
 end
+--- This refers to the Repentance door that spawns after defeating Mom. You open it with the
+-- completed knife. It has a sprite filename of "gfx/grid/Door_MomsHeart.anm2".
 function ____exports.isDoorToMomsHeart(self, door)
     if not ____exports.isRepentanceDoor(nil, door) then
         return false
@@ -202,6 +245,12 @@ function ____exports.isHiddenSecretRoomDoor(self, door)
     local animation = sprite:GetAnimation()
     return ____exports.isSecretRoomDoor(nil, door) and animation == "Hidden"
 end
+--- Helper function to reset an unlocked door back to a locked state. Doing this is non-trivial
+-- because in addition to calling the `GridEntityDoor.SetLocked` method, you must also:
+-- 
+-- - Set the `VisitedCount` of the room's `RoomDescription` to 0.
+-- - Set the variant to `DoorVariant.DOOR_LOCKED`.
+-- - Close the door.
 function ____exports.lockDoor(self, door)
     local level = game:GetLevel()
     local roomDescriptor = level:GetRoomByIdx(door.TargetRoomIndex)
@@ -210,16 +259,25 @@ function ____exports.lockDoor(self, door)
     door:SetLocked(true)
     door:Close(true)
 end
+--- For the purposes of this function, doors to Secret Rooms or Super Secret Rooms that have not been
+-- discovered yet will not be opened.
 function ____exports.openAllDoors(self)
     for ____, door in ipairs(____exports.getDoors(nil)) do
         door:Open()
     end
 end
+--- Use this instead of the `GridEntityDoor.Open` method if you want the door to immediately open
+-- without an animation.
 function ____exports.openDoorFast(self, door)
     door.State = DoorState.OPEN
     local sprite = door:GetSprite()
     sprite:Play("Opened", true)
 end
+--- Helper function to remove all of the doors in the room. By default, it will remove every door.
+-- You can optionally specify one or more room types to remove only the doors that match the
+-- specified room types.
+-- 
+-- @returns The number of doors removed.
 function ____exports.removeAllDoors(self, ...)
     local doors = ____exports.getDoors(nil, ...)
     ____exports.removeDoors(

package/functions/entity.d.ts

@@ -96,17 +96,17 @@ export declare function parseEntityTypeVariantString(entityTypeVariantString: st
  * @param entityVariant Optional. The variant to match. Default is -1. -1 matches every variant.
  * @param entitySubType Optional. The sub-type to match. Default is -1. -1 matches every sub-type.
  * @param cap Optional. If specified, will only remove the given amount of collectibles.
- * @returns True if one or more entities were removed, false otherwise.
+ * @returns An array of the entities that were removed.
  */
-export declare function removeAllMatchingEntities(entityType: EntityType, entityVariant?: number, entitySubType?: number, cap?: int | undefined): boolean;
+export declare function removeAllMatchingEntities(entityType: EntityType, entityVariant?: number, entitySubType?: number, cap?: int | undefined): Entity[];
 /**
  * Helper function to remove all of the entities in the supplied array.
  *
  * @param entities The array of entities to remove.
  * @param cap Optional. If specified, will only remove the given amount of entities.
- * @returns True if one or more entities were removed, false otherwise.
+ * @returns An array of the entities that were removed.
  */
-export declare function removeEntities(entities: Entity[], cap?: int): boolean;
+export declare function removeEntities<T extends AnyEntity>(entities: T[], cap?: int): T[];
 /**
  * Helper function to reroll an enemy. Use this instead of the vanilla "Game.RerollEnemy" function
  * if you want the rerolled enemy to be returned.