isaacscript-common 2.3.2 → 3.0.0

package/functions/collectibles.lua

@@ -44,6 +44,16 @@ function initQuestionMarkSprite(self)
     sprite:LoadGraphics()
     return sprite
 end
+--- Helper function to change the sprite of a collectible pedestal entity.
+-- 
+-- For more information about removing the collectible sprite, see the documentation for the
+-- "clearSprite" helper function.
+-- 
+-- @param collectible The collectible whose sprite you want to modify.
+-- @param pngPath Equal to either the spritesheet path to load (e.g.
+-- "gfx/items/collectibles/collectibles_001_thesadonion.png") or undefined. If
+-- undefined, the sprite will be removed, making it appear like the collectible has
+-- already been taken by the player.
 function ____exports.setCollectibleSprite(self, collectible, pngPath)
     if not isCollectible(nil, collectible) then
         local entityID = getEntityID(nil, collectible)
@@ -64,6 +74,7 @@ local questionMarkSprite = initQuestionMarkSprite(nil)
 function ____exports.clearCollectibleSprite(self, collectible)
     ____exports.setCollectibleSprite(nil, collectible, nil)
 end
+--- Helper function to check if two collectible sprites have the same sprite sheet loaded.
 function ____exports.collectibleSpriteEquals(self, sprite1, sprite2)
     local xStart = -1
     local xFinish = 1
@@ -84,6 +95,8 @@ function ____exports.collectibleSpriteEquals(self, sprite1, sprite2)
         yIncrement
     )
 end
+--- Helper function to get the in-game description for a collectible. Returns "Unknown" if the
+-- provided collectible type was not valid.
 function ____exports.getCollectibleDescription(self, collectibleType)
     local collectibleDescription = COLLECTIBLE_DESCRIPTION_MAP:get(collectibleType)
     if collectibleDescription ~= nil then
@@ -95,6 +108,8 @@ function ____exports.getCollectibleDescription(self, collectibleType)
     end
     return DEFAULT_COLLECTIBLE_DESCRIPTION
 end
+--- Helper function to get the heart cost that a collectible item would be if it were being offered
+-- in a Devil Room deal. Returns 0 if passed CollectibleType.NULL.
 function ____exports.getCollectibleDevilHeartPrice(self, collectibleType, player)
     local maxHearts = player:GetMaxHearts()
     if collectibleType == CollectibleType.NULL then
@@ -111,6 +126,8 @@ function ____exports.getCollectibleDevilHeartPrice(self, collectibleType, player
     local twoHeartPrice = maxHearts == 2 and PickupPrice.ONE_HEART_AND_TWO_SOUL_HEARTS or PickupPrice.TWO_HEARTS
     return itemConfigItem.DevilPrice == 2 and twoHeartPrice or PickupPrice.ONE_HEART
 end
+--- Helper function to get the path to a collectible's sprite. Returns the path to the question mark
+-- sprite (i.e. from Curse of the Blind) if the provided collectible type was not valid.
 function ____exports.getCollectibleGfxFilename(self, collectibleType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     if itemConfigItem == nil then
@@ -118,6 +135,41 @@ function ____exports.getCollectibleGfxFilename(self, collectibleType)
     end
     return itemConfigItem.GfxFileName
 end
+--- Mods often have to track variables relating to a collectible. Finding an index for these kinds of
+-- data structures is difficult, since collectibles are respawned every time a player re-enters a
+-- room, so the `PtrHash` will change. Instead, we use a 4-tuple of the room list index, the grid
+-- index of the collectible in the room, the collectible's SubType, and the collectible's InitSeed.
+-- 
+-- Collectibles that are shifted by Tainted Isaac's mechanic will have unique collectible indexes
+-- because the SubType is different. (The collectible entities share the same InitSeed.)
+-- 
+-- Collectibles that are rolled (with e.g. a D6) will have unique collectible indexes because the
+-- SubType and InitSeed are different. If you want to track collectibles independently of any
+-- rerolls, then you can use the `PtrHash` as an index instead. (The `PtrHash` will not persist
+-- between rooms, however.)
+-- 
+-- Note that:
+-- - The grid index is a necessary part of the collectible index because Diplopia and Crooked Penny
+--   can cause two or more collectibles with the same SubType and InitSeed to exist in the same
+--   room.
+-- - This index will fail in the case where the player uses Diplopia or a successful Crooked Penny
+--   seven or more times in the same room, since that will cause two or more collectibles with the
+--   same grid index, SubType, and InitSeed to exist.
+-- - The SubType is a necessary part of the collectible index because Tainted Isaac will
+--   continuously cause collectibles to morph into new sub-types with the same InitSeed.
+-- - Using a collectible's position as part of the index is problematic, since players can push a
+--   pedestal. (Even using the grid index does not solve this problem, since it is possible in
+--   certain cases for collectibles to be spawned at a position that is not aligned with the grid,
+--   and the pedestal pushed to an adjacent tile, but this case should be extremely rare.)
+-- - Mega Chests spawn two collectibles on the exact same position. However, both of them will have
+--   different InitSeeds, so this is not a problem for this indexing scheme.
+-- - The indexing scheme used is different for collectibles that are inside of a Treasure Room, in
+--   order to handle the case of the player seeing the same collectible again in a post-Ascent
+--   Treasure Room. A 5-tuple of stage, stage type, grid index, SubType, and InitSeed is used in
+--   this case. (Using the room list index or the room grid index is not suitable for this purpose,
+--   since both of these values can change in the post-Ascent Treasure Room.) Even though there can
+--   be two Treasure Rooms on an XL floor, both Treasure Rooms should not have collectibles with the
+--   same grid index, Subtype, and InitSeed.
 function ____exports.getCollectibleIndex(self, collectible)
     if not isCollectible(nil, collectible) then
         local entityID = getEntityID(nil, collectible)
@@ -135,6 +187,8 @@ function ____exports.getCollectibleIndex(self, collectible)
     end
     return (((((tostring(roomListIndex) .. ",") .. tostring(gridIndex)) .. ",") .. tostring(collectible.SubType)) .. ",") .. tostring(collectible.InitSeed)
 end
+--- Helper function to get the initial amount of charges that a collectible has. Returns 0 if the
+-- provided collectible type was not valid.
 function ____exports.getCollectibleInitCharge(self, collectibleType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     if itemConfigItem == nil then
@@ -142,6 +196,8 @@ function ____exports.getCollectibleInitCharge(self, collectibleType)
     end
     return itemConfigItem.InitCharge
 end
+--- Helper function to get the `ItemType` of a collectible. Returns `ItemType.ITEM_NULL` if the
+-- provided collectible type was not valid.
 function ____exports.getCollectibleItemType(self, collectibleType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     if itemConfigItem == nil then
@@ -149,6 +205,8 @@ function ____exports.getCollectibleItemType(self, collectibleType)
     end
     return itemConfigItem.Type
 end
+--- Helper function to get the maximum amount of charges that a collectible has. Returns 0 if the
+-- provided collectible type was not valid.
 function ____exports.getCollectibleMaxCharges(self, collectibleType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     if itemConfigItem == nil then
@@ -156,6 +214,15 @@ function ____exports.getCollectibleMaxCharges(self, collectibleType)
     end
     return itemConfigItem.MaxCharges
 end
+--- Helper function to get the name of a collectible. Returns "Unknown" if the provided collectible
+-- type is not valid.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const collectibleType = CollectibleType.SAD_ONION;
+-- const collectibleName = getCollectibleName(collectibleType); // collectibleName is "Sad Onion"
+-- ```
 function ____exports.getCollectibleName(self, collectibleType)
     local collectibleName = COLLECTIBLE_NAME_MAP:get(collectibleType)
     if collectibleName ~= nil then
@@ -175,6 +242,8 @@ function ____exports.getCollectiblePedestalType(self, collectible)
     local sprite = collectible:GetSprite()
     return sprite:GetOverlayFrame()
 end
+--- Helper function to get the path to a collectible's quality. Returns 0 if the provided collectible
+-- type was not valid.
 function ____exports.getCollectibleQuality(self, collectibleType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     if itemConfigItem == nil then
@@ -182,26 +251,59 @@ function ____exports.getCollectibleQuality(self, collectibleType)
     end
     return itemConfigItem.Quality
 end
+--- Helper function to get the tags of a collectible (which is the composition of zero or more
+-- `ItemConfigTag`). Returns 0 if the provided collectible type is not valid.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const collectibleType = CollectibleType.SAD_ONION;
+-- const itemConfigTags = getCollectibleTags(collectibleType); // itemConfigTags is "18350080"
+-- ```
 function ____exports.getCollectibleTags(self, collectibleType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     return itemConfigItem == nil and ItemConfigTagZero or itemConfigItem.Tags
 end
+--- Helper function to get an array that represents the range from the first collectible type to the
+-- last collectible type. This will include integers that do not represent any valid collectible
+-- types.
+-- 
+-- This function is only useful when building collectible type objects. For most purposes, you
+-- should use the `getCollectibleSet` helper function instead.
 function ____exports.getCollectibleTypeRange(self)
     return irange(nil, FIRST_COLLECTIBLE_TYPE, LAST_COLLECTIBLE_TYPE)
 end
+--- Helper function to get an array that represents the all modded collectible types.
+-- 
+-- This function is only useful when building collectible type objects. For most purposes, you
+-- should use the `getModdedCollectibleSet` helper function instead.
+-- 
+-- Returns an empty array if there are no modded collectible types.
+-- 
+-- (This function is named differently from the `getVanillaCollectibleTypeRange` function because
+-- all modded collectible types are contiguous. Thus, each value represents a real
+-- `CollectibleType`.)
 function ____exports.getModdedCollectibleTypes(self)
     if LAST_VANILLA_COLLECTIBLE_TYPE == LAST_COLLECTIBLE_TYPE then
         return {}
     end
     return irange(nil, FIRST_MODDED_COLLECTIBLE_TYPE, LAST_COLLECTIBLE_TYPE)
 end
+--- Helper function to get an array that represents the range from the first collectible type to the
+-- last vanilla collectible type. This will include integers that do not represent any valid
+-- collectible types.
+-- 
+-- This function is only useful when building collectible type objects. For most purposes, you
+-- should use the `getVanillaCollectibleSet` helper function instead.
 function ____exports.getVanillaCollectibleTypeRange(self)
     return irange(nil, FIRST_COLLECTIBLE_TYPE, LAST_VANILLA_COLLECTIBLE_TYPE)
 end
+--- Returns true if the item type in the item config is equal to `ItemType.ITEM_ACTIVE`.
 function ____exports.isActiveCollectible(self, collectibleType)
     local itemType = ____exports.getCollectibleItemType(nil, collectibleType)
     return itemType == ItemType.ACTIVE
 end
+--- Returns true if the collectible has a red question mark sprite.
 function ____exports.isBlindCollectible(self, collectible)
     if not isCollectible(nil, collectible) then
         local entityID = getEntityID(nil, collectible)
@@ -213,17 +315,28 @@ function ____exports.isBlindCollectible(self, collectible)
     questionMarkSprite:SetFrame(animation, frame)
     return ____exports.collectibleSpriteEquals(nil, sprite, questionMarkSprite)
 end
+--- Returns whether or not the given collectible is a "glitched" item. All items are replaced by
+-- glitched items once a player has TMTRAINER. However, glitched items can also "naturally" appear
+-- in secret rooms and I AM ERROR rooms if the "Corrupted Data" achievement is unlocked.
 function ____exports.isGlitchedCollectible(self, pickup)
     return pickup.Variant == PickupVariant.COLLECTIBLE and pickup.SubType > GLITCHED_ITEM_THRESHOLD
 end
+--- Returns true if the collectible has the "Hidden" attribute in the item config.
+-- 
+-- Hidden collectibles will not show up in any pools and Eden will not start with them.
 function ____exports.isHiddenCollectible(self, collectibleType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     return itemConfigItem ~= nil and itemConfigItem.Hidden
 end
+--- Returns true if the item type in the item config is equal to `ItemType.ITEM_PASSIVE` or
+-- `ItemType.ITEM_FAMILIAR`.
 function ____exports.isPassiveCollectible(self, collectibleType)
     local itemType = ____exports.getCollectibleItemType(nil, collectibleType)
     return itemType == ItemType.PASSIVE or itemType == ItemType.FAMILIAR
 end
+--- Helper function to determine if a particular collectible will disappear from the player's
+-- inventory upon use. Note that this will not work will modded items, as there is no way to
+-- dynamically know if a modded item will disappear.
 function ____exports.isSingleUseCollectible(self, collectibleType)
     return SINGLE_USE_ACTIVE_COLLECTIBLE_TYPES_SET:has(collectibleType)
 end
@@ -231,10 +344,17 @@ function ____exports.isValidCollectibleType(self, collectibleType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     return itemConfigItem ~= nil
 end
+--- Helper function to put a message in the log.txt file to let the Rebirth Item Tracker know that it
+-- should remove an item.
+-- 
+-- The "item tracker" in this function does not refer to the in-game item tracker, but rather to the
+-- Python program located at: https://github.com/Rchardon/RebirthItemTracker
 function ____exports.removeCollectibleFromItemTracker(self, collectibleType)
     local collectibleName = ____exports.getCollectibleName(nil, collectibleType)
     Isaac.DebugString(((("Removing collectible " .. tostring(collectibleType)) .. " (") .. collectibleName) .. ") on player 0 (Player)")
 end
+--- Helper function to remove all pickup delay on a collectible. By default, collectibles have a 20
+-- frame delay before they can be picked up by a player.
 function ____exports.removeCollectiblePickupDelay(self, collectible)
     if not isCollectible(nil, collectible) then
         local entityID = getEntityID(nil, collectible)
@@ -242,6 +362,8 @@ function ____exports.removeCollectiblePickupDelay(self, collectible)
     end
     collectible.Wait = 0
 end
+--- Helper function to set a collectible sprite to a question mark (i.e. how collectibles look when
+-- the player has Curse of the Blind).
 function ____exports.setCollectibleBlind(self, collectible)
     if not isCollectible(nil, collectible) then
         local entityID = getEntityID(nil, collectible)
@@ -249,6 +371,11 @@ function ____exports.setCollectibleBlind(self, collectible)
     end
     ____exports.setCollectibleSprite(nil, collectible, BLIND_ITEM_PNG_PATH)
 end
+--- Helper function to remove the collectible from a collectible pedestal and make it appear as if a
+-- player has already taken the item. This is accomplished by changing the sub-type to
+-- `CollectibleType.NULL` and then setting the sprite to an empty/missing PNG file.
+-- 
+-- For more information, see the documentation for the "clearSprite" helper function.
 function ____exports.setCollectibleEmpty(self, collectible)
     if not isCollectible(nil, collectible) then
         local entityID = getEntityID(nil, collectible)
@@ -257,6 +384,8 @@ function ____exports.setCollectibleEmpty(self, collectible)
     collectible.SubType = CollectibleType.NULL
     ____exports.clearCollectibleSprite(nil, collectible)
 end
+--- Helper function to change the collectible on a pedestal. Simply updating the `SubType` property
+-- is not sufficient because the sprite will not change.
 function ____exports.setCollectibleSubType(self, collectible, newCollectibleType)
     if not isCollectible(nil, collectible) then
         local entityID = getEntityID(nil, collectible)
@@ -275,6 +404,8 @@ function ____exports.setCollectibleSubType(self, collectible, newCollectibleType
         true
     )
 end
+--- Helper function to put a message in the log.txt file to let the Rebirth Item Tracker know that
+-- the build has been rerolled.
 function ____exports.setCollectiblesRerolledForItemTracker(self)
     Isaac.DebugString("Added 3 Collectibles")
 end

package/functions/color.lua

@@ -13,6 +13,9 @@ local getNumbersFromTable = ____table.getNumbersFromTable
 local tableHasKeys = ____table.tableHasKeys
 local ____utils = require("functions.utils")
 local ensureAllCases = ____utils.ensureAllCases
+--- Helper function to check if something is an instantiated Color object.
+-- 
+-- @category color
 function ____exports.isColor(self, object)
     return isIsaacAPIClassOfType(nil, object, OBJECT_NAME)
 end
@@ -26,9 +29,17 @@ local KEYS = {
     "BO"
 }
 OBJECT_NAME = "Color"
+---
+-- @category color
 function ____exports.colorEquals(self, color1, color2)
     return isaacAPIClassEquals(nil, color1, color2, KEYS)
 end
+--- Helper function to copy a `Color` object.
+-- 
+-- @param color The Color object to copy. In the case of deserialization, this will actually be a
+-- Lua table instead of an instantiated Color class.
+-- @param serializationType Default is `SerializationType.NONE`.
+-- @category color
 function ____exports.copyColor(self, color, serializationType)
     if serializationType == nil then
         serializationType = SerializationType.NONE
@@ -104,9 +115,16 @@ function ____exports.copyColor(self, color, serializationType)
         end
     until true
 end
+--- Returns `Color(1, 1, 1)`.
+-- 
+-- @category color
 function ____exports.getDefaultColor(self)
     return Color(1, 1, 1)
 end
+--- Used to determine is the given table is a serialized `Color` object created by the save data
+-- manager and/or the `deepCopy` function.
+-- 
+-- @category color
 function ____exports.isSerializedColor(self, object)
     local objectType = type(object)
     if objectType ~= "table" then

package/functions/debug.lua

@@ -1,6 +1,10 @@
 local ____exports = {}
 local ____log = require("functions.log")
 local log = ____log.log
+--- Helper function to get a stack trace.
+-- 
+-- This will only work if the `--luadebug` launch option is enabled or the Racing+ sandbox is
+-- enabled.
 function ____exports.getTraceback(self)
     if debug ~= nil then
         return debug.traceback()
@@ -10,9 +14,23 @@ function ____exports.getTraceback(self)
     end
     return "stack traceback:\n(the \"--luadebug\" flag is not enabled)"
 end
+--- Players can boot the game with an launch option called "--luadebug", which will enable additional
+-- functionality that is considered to be unsafe. For more information about this flag, see the
+-- wiki: https://bindingofisaacrebirth.fandom.com/wiki/Launch_Options
+-- 
+-- When this flag is enabled, the global environment will be slightly different. The differences are
+-- documented here: https://wofsauge.github.io/IsaacDocs/rep/Globals.html
+-- 
+-- This function uses the `package` global variable as a proxy to determine if the "--luadebug" flag
+-- is enabled or not.
 function ____exports.isLuaDebugEnabled(self)
     return package ~= nil
 end
+--- Helper function to print a stack trace to the "log.txt" file, similar to JavaScript's
+-- `console.trace` function.
+-- 
+-- This will only work if the `--luadebug` launch option is enabled or the Racing+ sandbox is
+-- enabled.
 function ____exports.traceback(self)
     local tracebackOutput = ____exports.getTraceback(nil)
     log(tracebackOutput)

package/functions/deepCopy.lua

@@ -39,6 +39,31 @@ local newTSTLClass = ____tstlClass.newTSTLClass
 local ____utils = require("functions.utils")
 local ensureAllCases = ____utils.ensureAllCases
 local getTraversalDescription = ____utils.getTraversalDescription
+--- `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

package/functions/doors.lua

@@ -27,11 +27,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 +68,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 +88,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 +119,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 +131,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)
@@ -139,6 +165,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 +180,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 +195,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 +205,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 +215,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 +225,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 +240,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 +254,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(