isaacscript-common 2.3.2 → 3.1.1

package/functions/roomData.lua

@@ -12,14 +12,22 @@ local ____enums = require("functions.enums")
 local getEnumValues = ____enums.getEnumValues
 local ____flag = require("functions.flag")
 local hasFlag = ____flag.hasFlag
+--- Alias for the `Level.GetCurrentRoomDesc` method. Use this to make it more clear what type of
+-- `RoomDescriptor` object that you are retrieving.
 function ____exports.getCurrentRoomDescriptorReadOnly(self)
     local level = game:GetLevel()
     return level:GetCurrentRoomDesc()
 end
+--- Helper function to get the room data for the provided room.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
 function ____exports.getRoomData(self, roomGridIndex)
     local roomDescriptor = ____exports.getRoomDescriptor(nil, roomGridIndex)
     return roomDescriptor.Data
 end
+--- Helper function to get the descriptor for a room.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
 function ____exports.getRoomDescriptor(self, roomGridIndex)
     local level = game:GetLevel()
     if roomGridIndex == nil then
@@ -27,6 +35,20 @@ function ____exports.getRoomDescriptor(self, roomGridIndex)
     end
     return level:GetRoomByIdx(roomGridIndex)
 end
+--- Helper function to get the grid index of the current room.
+-- 
+-- - If the current room is inside of the grid, this function will return the `SafeGridIndex` from
+--   the room descriptor. (The safe grid index is defined as the top-left 1x1 section that the room
+--   overlaps with, or the top-right 1x1 section of a `RoomType.SHAPE_LTL` room.)
+-- - If the current room is outside of the grid, it will return the index from the
+--   `Level.GetCurrentRoomIndex` method (since `SafeGridIndex` is bugged for these cases).
+-- 
+-- Use this function instead of the `Level.GetCurrentRoomIndex` method directly because the latter
+-- will return the specific 1x1 quadrant that the player entered the room at. For most situations,
+-- using the safe grid index is more reliable than this.
+-- 
+-- Data structures that store data per room should use the room's `ListIndex` instead of
+-- `SafeGridIndex`, since the former is unique across different dimensions.
 function ____exports.getRoomGridIndex(self)
     local level = game:GetLevel()
     local currentRoomIndex = level:GetCurrentRoomIndex()
@@ -36,6 +58,8 @@ function ____exports.getRoomGridIndex(self)
     local roomDescriptor = ____exports.getCurrentRoomDescriptorReadOnly(nil)
     return roomDescriptor.SafeGridIndex
 end
+--- Helper function to get the set of allowed door slots for the room at the supplied grid index.
+-- This corresponds to the doors that are enabled in the STB/XML file for the room.
 function ____exports.getRoomAllowedDoors(self, roomGridIndex)
     local allowedDoors = __TS__New(Set)
     local roomData = ____exports.getRoomData(nil, roomGridIndex)
@@ -51,14 +75,30 @@ function ____exports.getRoomAllowedDoors(self, roomGridIndex)
     end
     return allowedDoors
 end
+--- Helper function to get the list grid index of the provided room, which is equal to the index in
+-- the `RoomList.Get` method. In other words, this is equal to the order that the room was created
+-- by the floor generation algorithm.
+-- 
+-- Use this as an index for data structures that store data per room, since it is unique across
+-- different dimensions.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
 function ____exports.getRoomListIndex(self, roomGridIndex)
     local roomDescriptor = ____exports.getRoomDescriptor(nil, roomGridIndex)
     return roomDescriptor.ListIndex
 end
+--- Helper function to get the name of the room as it appears in the STB/XML data.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
+-- @returns The room name. Returns "Unknown" if the type was not found.
 function ____exports.getRoomName(self, roomGridIndex)
     local roomData = ____exports.getRoomData(nil, roomGridIndex)
     return roomData == nil and "Unknown" or roomData.Name
 end
+--- Helper function to get the name of the room as it appears in the STB/XML data.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
+-- @returns The room name. Returns "Unknown" if the type was not found.
 function ____exports.getRoomShape(self, roomGridIndex)
     local roomData = ____exports.getRoomData(nil, roomGridIndex)
     local ____temp_0
@@ -69,22 +109,50 @@ function ____exports.getRoomShape(self, roomGridIndex)
     end
     return ____temp_0
 end
+--- Helper function to get the stage ID for a room from the XML/STB data. The room stage ID will
+-- correspond to the first number in the filename of the XML/STB file. For example, a Depths room
+-- would have a stage ID of 7.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
+-- @returns The room stage ID. Returns -1 if the stage ID was not found.
 function ____exports.getRoomStageID(self, roomGridIndex)
     local roomData = ____exports.getRoomData(nil, roomGridIndex)
     return roomData == nil and -1 or roomData.StageID
 end
+--- Helper function to get the sub-type for a room from the XML/STB data. The room sub-type will
+-- correspond to different things depending on what XML/STB file it draws from. For example, in the
+-- "00.special rooms.stb" file, an Angel Room with a sub-type of 0 will correspond to a normal Angel
+-- Room and a sub-type of 1 will correspond to an Angel Room shop for The Stairway.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
+-- @returns The room sub-type. Returns -1 if the sub-type was not found.
 function ____exports.getRoomSubType(self, roomGridIndex)
     local roomData = ____exports.getRoomData(nil, roomGridIndex)
     return roomData == nil and -1 or roomData.Subtype
 end
+--- Helper function for getting the type of the room with the given grid index.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
+-- @returns The room data type. Returns -1 if the type was not found.
 function ____exports.getRoomType(self, roomGridIndex)
     local roomData = ____exports.getRoomData(nil, roomGridIndex)
     return roomData == nil and -1 or roomData.Type
 end
+--- Helper function to get the variant for a room from the XML/STB data. You can think of a room
+-- variant as its identifier. For example, to go to Basement room #123, you would use a console
+-- command of `goto d.123` while on the Basement.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
+-- @returns The room variant. Returns -1 if the variant was not found.
 function ____exports.getRoomVariant(self, roomGridIndex)
     local roomData = ____exports.getRoomData(nil, roomGridIndex)
     return roomData == nil and -1 or roomData.Variant
 end
+--- Note that the room visited count will be inaccurate during the period before the PostNewRoom
+-- callback has fired (i.e. when entities are initializing and performing their first update). This
+-- is because the variable is only incremented immediately before the PostNewRoom callback fires.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
 function ____exports.getRoomVisitedCount(self, roomGridIndex)
     local roomDescriptor = ____exports.getRoomDescriptor(nil, roomGridIndex)
     return roomDescriptor.VisitedCount

package/functions/roomGrid.lua

@@ -9,6 +9,9 @@ local getRoomShapeBottomRightPosition = ____roomShape.getRoomShapeBottomRightPos
 local getRoomShapeTopLeftPosition = ____roomShape.getRoomShapeTopLeftPosition
 local getRoomShapeWidth = ____roomShape.getRoomShapeWidth
 local isLRoom = ____roomShape.isLRoom
+--- Helper function to convert a grid position `Vector` to a world position `Vector`.
+-- 
+-- For example, the coordinates of (0, 0) are equal to `Vector(80, 160)`.
 function ____exports.gridPositionToWorldPosition(self, gridPosition)
     local x = (gridPosition.X + 2) * 40
     local y = (gridPosition.Y + 4) * 40
@@ -27,16 +30,26 @@ function isValidGridPositionLRoom(self, gridPosition, roomShape)
     local verticalTopLeft, verticalBottomRight, horizontalTopLeft, horizontalBottomRight = table.unpack(rectangles)
     return inRectangle(nil, gridPosition, verticalTopLeft, verticalBottomRight) or inRectangle(nil, gridPosition, horizontalTopLeft, horizontalBottomRight)
 end
+--- Helper function to convert grid coordinates to a world position `Vector`.
+-- 
+-- For example, the coordinates of (0, 0) are equal to `Vector(80, 160)`.
 function ____exports.gridCoordinatesToWorldPosition(self, x, y)
     local gridPosition = Vector(x, y)
     return ____exports.gridPositionToWorldPosition(nil, gridPosition)
 end
+--- Helper function to convert a grid index to a grid position.
+-- 
+-- For example, in a 1x1 room, grid index 0 is equal to "Vector(-1, -1) and grid index 16 is equal
+-- to "Vector(0, 0)".
 function ____exports.gridIndexToGridPosition(self, gridIndex, roomShape)
     local gridWidth = getRoomShapeWidth(nil, roomShape)
     local x = gridIndex % gridWidth - 1
     local y = math.floor(gridIndex / gridWidth) - 1
     return Vector(x, y)
 end
+--- Test if a grid position is actually in the given `RoomShape`.
+-- 
+-- In this context, the grid position of the top-left wall is "Vector(-1, -1)".
 function ____exports.isValidGridPosition(self, gridPosition, roomShape)
     local ____isLRoom_result_0
     if isLRoom(nil, roomShape) then
@@ -46,11 +59,19 @@ function ____exports.isValidGridPosition(self, gridPosition, roomShape)
     end
     return ____isLRoom_result_0
 end
+--- Helper function to convert a world position `Vector` to a grid position `Vector`.
+-- 
+-- In this context, the grid position of the top-left wall is "Vector(-1, -1)".
 function ____exports.worldPositionToGridPosition(self, worldPos)
     local x = math.floor(worldPos.X / 40 - 2 + 0.5)
     local y = math.floor(worldPos.Y / 40 - 4 + 0.5)
     return Vector(x, y)
 end
+--- Helper function to convert a world position `Vector` to a grid position `Vector`.
+-- 
+-- In this context, the grid position of the top-left wall is "Vector(-1, -1)".
+-- 
+-- This is similar to the `worldPositionToGridPosition` function, but the values are not rounded.
 function ____exports.worldPositionToGridPositionFast(self, worldPos)
     local x = worldPos.X / 40 - 2
     local y = worldPos.Y / 40 - 4

package/functions/roomShape.lua

@@ -17,22 +17,44 @@ local ____roomShapeVolumes = require("objects.roomShapeVolumes")
 local ROOM_SHAPE_VOLUMES = ____roomShapeVolumes.ROOM_SHAPE_VOLUMES
 local ____LRoomShapesSet = require("sets.LRoomShapesSet")
 local L_ROOM_SHAPES_SET = ____LRoomShapesSet.L_ROOM_SHAPES_SET
+--- Helper function to get the grid index delta that a door out of the given room shape would lead
+-- to. For example, if you went through the bottom door in a room of `RoomShape.SHAPE_1x2`, you
+-- would end up in a room with a grid index that is +26 units from the `SafeGridIndex` of where you
+-- started.
 function ____exports.getGridIndexDelta(self, roomShape, doorSlot)
     local doorSlotToGridIndexMap = ROOM_SHAPE_TO_DOOR_SLOTS_TO_GRID_INDEX_DELTA[roomShape]
     return doorSlotToGridIndexMap:get(doorSlot)
 end
+--- Helper function to get the grid position of the bottom-right tile of a given room shape.
+-- 
+-- "Vector(0, 0)" corresponds to the top left tile of a room, not including the walls. (The top-left
+-- wall would be at "Vector(-1, -1)".)
 function ____exports.getRoomShapeBottomRightPosition(self, roomShape)
     return ROOM_SHAPE_TO_BOTTOM_RIGHT_POSITION[roomShape]
 end
+--- Helper function to get the bounds of a room shape, which are a box representing its contents.
+-- This does not include the tiles that the walls are on. L rooms use the same bounds as a 2x2 room.
 function ____exports.getRoomShapeBounds(self, roomShape)
     return ROOM_SHAPE_BOUNDS[roomShape]
 end
+--- Helper function to get the dimensions of a room shape's layout. This is NOT the size of the
+-- room's actual contents! For that, use the `getRoomShapeBounds` function.
+-- 
+-- For example, a horizontal narrow room has a layout size of equal to that of a 1x1 room.
 function ____exports.getRoomShapeLayoutSize(self, roomShape)
     return ROOM_SHAPE_LAYOUT_SIZES[roomShape]
 end
+--- Helper function to get the grid position of the top-left tile of a given room shape.
+-- 
+-- "Vector(0, 0)" corresponds to the top left tile of a room, not including the walls. (The top-left
+-- wall would be at "Vector(-1, -1)".)
 function ____exports.getRoomShapeTopLeftPosition(self, roomShape)
     return ROOM_SHAPE_TO_TOP_LEFT_POSITION[roomShape]
 end
+--- Helper function to get the volume of a room shape, which is the amount of tiles that are inside
+-- the room.
+-- 
+-- (This cannot be directly calculated from the bounds since L rooms are a special case.)
 function ____exports.getRoomShapeVolume(self, roomShape)
     return ROOM_SHAPE_VOLUMES[roomShape]
 end

package/functions/rooms.lua

@@ -68,6 +68,13 @@ local irange = ____utils.irange
 function ____exports.getRoomShapeNeighborGridIndexDeltas(self, roomShape)
     return {__TS__Spread(ROOM_SHAPE_TO_DOOR_SLOTS_TO_GRID_INDEX_DELTA[roomShape]:values())}
 end
+--- Helper function to get the room descriptor for every room on the level. Uses the `Level.GetRooms`
+-- method to accomplish this. Rooms without data are assumed to be non-existent and are not added to
+-- the list.
+-- 
+-- @param includeExtraDimensionalRooms Optional. On some floors (e.g. Downpour 2, Mines 2),
+-- extra-dimensional rooms are automatically be generated and can be
+-- seen when you iterate over the `RoomList`. Default is false.
 function ____exports.getRooms(self, includeExtraDimensionalRooms)
     if includeExtraDimensionalRooms == nil then
         includeExtraDimensionalRooms = false
@@ -96,15 +103,21 @@ function ____exports.getRooms(self, includeExtraDimensionalRooms)
     end
     return {__TS__Spread(roomsMap:values())}
 end
+--- We cannot use the standard code in the `inDimension` function for this purpose since it is bugged
+-- with the Death Certificate area.
 function ____exports.inDeathCertificateArea(self)
     local roomStageID = getRoomStageID(nil)
     local roomSubType = getRoomSubType(nil)
     return roomStageID == StageID.HOME and (roomSubType == HomeRoomSubType.DEATH_CERTIFICATE_ENTRANCE or roomSubType == HomeRoomSubType.DEATH_CERTIFICATE_ITEMS)
 end
+--- Helper function to check if a room exists at the given room grid index.
 function ____exports.roomExists(self, roomGridIndex)
     local roomData = getRoomData(nil, roomGridIndex)
     return roomData ~= nil
 end
+--- Helper function for quickly switching to a new room without playing a particular animation. Use
+-- this helper function over invoking the `Game.ChangeRoom` method directly to ensure that you do
+-- not forget to set the `LeaveDoor` property and to prevent crashing on invalid room grid indexes.
 function ____exports.changeRoom(self, roomGridIndex)
     local level = game:GetLevel()
     local roomData = getRoomData(nil, roomGridIndex)
@@ -114,6 +127,7 @@ function ____exports.changeRoom(self, roomGridIndex)
     level.LeaveDoor = DoorSlot.NO_DOOR_SLOT
     game:ChangeRoom(roomGridIndex)
 end
+--- Helper function to get an array with every valid `Dimension` (not including `Dimension.CURRENT`).
 function ____exports.getAllDimensions(self)
     return erange(nil, NUM_DIMENSIONS)
 end
@@ -124,6 +138,11 @@ function ____exports.getAllRoomGridIndexes(self)
         function(____, roomDescriptor) return roomDescriptor.SafeGridIndex end
     )
 end
+--- Helper function to get the current dimension. Most of the time, this will be `Dimension.MAIN`,
+-- but it can change if e.g. the player is in the mirror world of Downpour/Dross.
+-- 
+-- Note that this function correctly handles detecting the Death Certificate dimension, which is
+-- tricky to properly detect.
 function ____exports.getCurrentDimension(self)
     local level = game:GetLevel()
     if ____exports.inDeathCertificateArea(nil) then
@@ -141,10 +160,19 @@ function ____exports.getCurrentDimension(self)
     end
     return error("Failed to get the current dimension using the starting room index of: " .. tostring(startingRoomGridIndex))
 end
+--- Helper function to get the number of rooms that are currently on the floor layout. This does not
+-- include off-grid rooms, like the Devil Room.
 function ____exports.getNumRooms(self)
     local rooms = ____exports.getRooms(nil)
     return #rooms
 end
+--- Helper function to get an array of all of the safe grid indexes for rooms that match the
+-- specified room type.
+-- 
+-- This function only searches through rooms in the current dimension.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to get the combined grid
+-- indexes for N room types.
 function ____exports.getRoomGridIndexesForType(self, ...)
     local roomTypesSet = __TS__New(Set, {...})
     local rooms = ____exports.getRooms(nil)
@@ -157,6 +185,8 @@ function ____exports.getRoomGridIndexesForType(self, ...)
         function(____, roomDescriptor) return roomDescriptor.SafeGridIndex end
     )
 end
+--- Helper function to get the item pool type for the current room. For example, this returns
+-- `ItemPoolType.ItemPoolType.POOL_ANGEL` if you are in an Angel Room.
 function ____exports.getRoomItemPoolType(self)
     local itemPool = game:GetItemPool()
     local room = game:GetRoom()
@@ -164,6 +194,9 @@ function ____exports.getRoomItemPoolType(self)
     local roomSeed = room:GetSpawnSeed()
     return itemPool:GetPoolForRoom(roomType, roomSeed)
 end
+--- Helper function to get the grid indexes of all the rooms connected to the given room index.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
 function ____exports.getRoomNeighbors(self, roomGridIndex)
     local roomDescriptor = getRoomDescriptor(nil, roomGridIndex)
     if roomDescriptor.SafeGridIndex < 0 or roomDescriptor.SafeGridIndex > MAX_LEVEL_GRID_INDEX then
@@ -184,10 +217,18 @@ function ____exports.getRoomNeighbors(self, roomGridIndex)
         function(____, gridIndex) return ____exports.roomExists(nil, gridIndex) end
     )
 end
+--- Helper function to get the proper name of a room type.
+-- 
+-- For example, `RoomType.TREASURE` will return "Treasure Room".
 function ____exports.getRoomTypeName(self, roomType)
     local roomTypeName = ROOM_TYPE_NAMES[roomType]
     return roomTypeName == nil and DEFAULT_ROOM_TYPE_NAME or roomTypeName
 end
+--- Helper function to get the room descriptor for every room on the level in a specific dimension.
+-- Uses the `Level.GetRooms` method to accomplish this. Rooms without data are assumed to be
+-- non-existent and are not added to the list.
+-- 
+-- @returns A map of room ListIndex to RoomDescriptor.
 function ____exports.getRoomsOfDimension(self, dimension)
     local level = game:GetLevel()
     local roomsMap = __TS__New(Map)
@@ -199,6 +240,8 @@ function ____exports.getRoomsOfDimension(self, dimension)
     end
     return {__TS__Spread(roomsMap:values())}
 end
+--- Helper function to determine if the current room shape is equal to `RoomShape.1x2` or
+-- `RoomShape.2x1`.
 function ____exports.in2x1Room(self)
     local room = game:GetRoom()
     local roomShape = room:GetRoomShape()
@@ -216,6 +259,8 @@ function ____exports.inBeastRoom(self)
     local roomSubType = getRoomSubType(nil)
     return roomType == RoomType.DUNGEON and roomSubType == DungeonSubType.BEAST_ROOM
 end
+--- Helper function to check if the current room is a boss room for a particular boss. This will only
+-- work for bosses that have dedicated boss rooms in the "00.special rooms.stb" file.
 function ____exports.inBossRoomOf(self, bossID)
     local room = game:GetRoom()
     local roomType = room:GetType()
@@ -223,12 +268,18 @@ function ____exports.inBossRoomOf(self, bossID)
     local roomSubType = getRoomSubType(nil)
     return roomType == RoomType.BOSS and roomStageID == StageID.SPECIAL_ROOMS and roomSubType == bossID
 end
+--- Helper function for determining whether the current room is a crawlspace. Use this function over
+-- comparing to `RoomType.DUNGEON` or `GridRoom.DUNGEON_IDX` since there is a special case of the
+-- player being in a boss fight that take place in a dungeon.
 function ____exports.inCrawlspace(self)
     local room = game:GetRoom()
     local roomType = room:GetType()
     local roomSubType = getRoomSubType(nil)
     return roomType == RoomType.DUNGEON and roomSubType == DungeonSubType.NORMAL
 end
+--- Helper function to detect if the current room is a Treasure Room created when entering with a
+-- Devil's Crown trinket. Under the hood, this checks for the `RoomDescriptorFlag.DEVIL_TREASURE`
+-- flag.
 function ____exports.inDevilsCrownTreasureRoom(self)
     local roomDescriptor = getCurrentRoomDescriptorReadOnly(nil)
     return hasFlag(nil, roomDescriptor.Flags, RoomDescriptorFlag.DEVIL_TREASURE)
@@ -246,6 +297,7 @@ function ____exports.inGenesisRoom(self)
     local roomGridIndex = getRoomGridIndex(nil)
     return roomGridIndex == GridRoom.GENESIS
 end
+--- Helper function to determine if the current room shape is one of the four L room shapes.
 function ____exports.inLRoom(self)
     local room = game:GetRoom()
     local roomShape = room:GetRoomShape()
@@ -255,11 +307,15 @@ function ____exports.inMegaSatanRoom(self)
     local roomGridIndex = getRoomGridIndex(nil)
     return roomGridIndex == GridRoom.MEGA_SATAN
 end
+--- Helper function to determine if the current room is part of the Repentance "escape sequence" in
+-- the Mines/Ashpit.
 function ____exports.inMineShaft(self)
     local roomStageID = getRoomStageID(nil)
     local roomSubType = getRoomSubType(nil)
     return (roomStageID == StageID.MINES or roomStageID == StageID.ASHPIT) and MINE_SHAFT_ROOM_SUB_TYPE_SET:has(roomSubType)
 end
+--- Helper function to check if the current room is a miniboss room for a particular miniboss. This
+-- will only work for mini-bosses that have dedicated boss rooms in the "00.special rooms.stb" file.
 function ____exports.inMinibossRoomOf(self, minibossID)
     local room = game:GetRoom()
     local roomType = room:GetType()
@@ -267,16 +323,31 @@ function ____exports.inMinibossRoomOf(self, minibossID)
     local roomSubType = getRoomSubType(nil)
     return roomType == RoomType.MINI_BOSS and roomStageID == StageID.SPECIAL_ROOMS and roomSubType == minibossID
 end
+--- Helper function for checking if the room is a secret shop (from the Member Card collectible).
+-- 
+-- Secret shops are simply copies of normal shops, but with the backdrop of a secret room. In other
+-- words, they will have the same room type, room variant, and room sub-type of a normal shop. Thus,
+-- the only way to detect them is by using the grid index.
 function ____exports.inSecretShop(self)
     local roomGridIndex = getRoomGridIndex(nil)
     return roomGridIndex == GridRoom.SECRET_SHOP
 end
+--- Helper function to determine whether or not the current room is the starting room of a floor. It
+-- only returns true for the starting room of the primary dimension (meaning that being in the
+-- starting room of the mirror world does not count).
 function ____exports.inStartingRoom(self)
     local level = game:GetLevel()
     local startingRoomGridIndex = level:GetStartingRoomIndex()
     local roomGridIndex = getRoomGridIndex(nil)
     return roomGridIndex == startingRoomGridIndex and ____exports.inDimension(nil, Dimension.MAIN)
 end
+--- Helper function to loop through every room on the floor and see if it has been cleared.
+-- 
+-- This function will only check rooms in the current dimension.
+-- 
+-- @param onlyCheckRoomTypes Optional. A whitelist of room types. If specified, room types not in
+-- the array will be ignored. If not specified, then all rooms will be
+-- checked. Undefined by default.
 function ____exports.isAllRoomsClear(self, onlyCheckRoomTypes)
     local ____temp_0
     if onlyCheckRoomTypes == nil then
@@ -315,21 +386,36 @@ function ____exports.isDoorSlotValidAtGridIndexForRedRoom(self, doorSlot, roomGr
     local redRoomGridIndex = roomGridIndex + delta
     return not ____exports.roomExists(nil, redRoomGridIndex) and redRoomGridIndex >= 0 and redRoomGridIndex <= MAX_LEVEL_GRID_INDEX
 end
+--- Helper function to detect if the provided room was created by the Red Key item. Under the hood,
+-- this checks for the `RoomDescriptorFlag.FLAG_RED_ROOM` flag.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
 function ____exports.isRedKeyRoom(self, roomGridIndex)
     local roomDescriptor = getRoomDescriptor(nil, roomGridIndex)
     return hasFlag(nil, roomDescriptor.Flags, RoomDescriptorFlag.RED_ROOM)
 end
+--- Helper function to determine if the provided room is part of the floor layout. For example, Devil
+-- Rooms and the Mega Satan room are not considered to be inside the map.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
 function ____exports.isRoomInsideMap(self, roomGridIndex)
     if roomGridIndex == nil then
         roomGridIndex = getRoomGridIndex(nil)
     end
     return roomGridIndex >= 0
 end
+--- Helper function to get the coordinates of a given grid index. The floor is represented by a 13x13
+-- grid. For example, since the starting room is in the center, the starting room grid index of 84
+-- be equal to coordinates of (?, ?).
 function ____exports.roomGridIndexToXY(self, roomGridIndex)
     local x = roomGridIndex % LEVEL_GRID_ROW_WIDTH
     local y = math.floor(roomGridIndex / LEVEL_GRID_ROW_WIDTH)
     return {x, y}
 end
+--- If the `Room.Update` method is called in a PostNewRoom callback, then some entities will slide
+-- around (such as the player). Since those entity velocities are already at zero, setting them to
+-- zero will have no effect. Thus, a generic solution is to record all of the entity
+-- positions/velocities before updating the room, and then restore those positions/velocities.
 function ____exports.roomUpdateSafe(self)
     local room = game:GetRoom()
     local entities = getEntities(nil)
@@ -339,6 +425,9 @@ function ____exports.roomUpdateSafe(self)
     setEntityPositions(nil, entityPositions, entities)
     setEntityVelocities(nil, entityVelocities, entities)
 end
+--- Helper function to convert an uncleared room to a cleared room in the PostNewRoom callback. This
+-- is useful because if enemies are removed in this callback, a room drop will be awarded and the
+-- doors will start closed and then open.
 function ____exports.setRoomCleared(self)
     local room = game:GetRoom()
     local roomClear = room:IsClear()
@@ -359,11 +448,22 @@ function ____exports.setRoomCleared(self)
     sfxManager:Stop(SoundEffect.DOOR_HEAVY_OPEN)
     game:ShakeScreen(0)
 end
+--- Helper function to emulate what happens when you bomb an Angel Statue or push a Reward Plate that
+-- spawns an NPC.
 function ____exports.setRoomUncleared(self)
     local room = game:GetRoom()
     room:SetClear(false)
     closeAllDoors(nil)
 end
+--- Helper function to change the current room. It can be used for both teleportation and "normal"
+-- room transitions, depending on what is passed for the `direction` and `roomTransitionAnim`
+-- arguments. Use this function instead of invoking the `Game.StartRoomTransition` method directly
+-- so that you do not forget to set `Level.LeaveDoor` property and to prevent crashing on invalid
+-- room grid indexes.
+-- 
+-- @param roomGridIndex The room grid index of the destination room.
+-- @param direction Optional. Default is `Direction.NO_DIRECTION`.
+-- @param roomTransitionAnim Optional. Default is `RoomTransitionAnim.TELEPORT`.
 function ____exports.teleport(self, roomGridIndex, direction, roomTransitionAnim)
     if direction == nil then
         direction = Direction.NO_DIRECTION

package/functions/run.lua

@@ -7,12 +7,17 @@ local ____constantsFirstLast = require("constantsFirstLast")
 local FIRST_CHARACTER = ____constantsFirstLast.FIRST_CHARACTER
 local ____log = require("functions.log")
 local log = ____log.log
+--- Whether or not the player is playing on a set seed (i.e. that they entered in a specific seed by
+-- pressing tab on the character selection screen). When the player resets the game on a set seed,
+-- the game will not switch to a different seed.
 function ____exports.onSetSeed(self)
     local seeds = game:GetSeeds()
     local customRun = seeds:IsCustomRun()
     local challenge = Isaac.GetChallenge()
     return challenge == Challenge.NULL and customRun
 end
+--- Helper function to restart the game using the console command of "restart". You can optionally
+-- specify a `PlayerType` to restart the game as that character.
 function ____exports.restart(self, character)
     if character == nil then
         log("Restarting.")

package/functions/seeds.lua

@@ -3,10 +3,14 @@ local ____cachedClasses = require("cachedClasses")
 local game = ____cachedClasses.game
 local ____rng = require("functions.rng")
 local newRNG = ____rng.newRNG
+--- Alias for the `Seeds.GetStartSeedString` method.
 function ____exports.getStartSeedString(self)
     local seeds = game:GetSeeds()
     return seeds:GetStartSeedString()
 end
+--- Helper function to get the next seed value.
+-- 
+-- This function is useful when you are working with seed values directly over RNG objects.
 function ____exports.nextSeed(self, seed)
     local rng = newRNG(nil, seed)
     rng:Next()

package/functions/serialization.lua

@@ -13,7 +13,7 @@ local ISAAC_API_CLASS_TYPE_TO_COPY_FUNCTION = ____isaacAPIClassTypeToCopyFunctio
 local ____serializedIsaacAPIClassTypeToIdentityFunction = require("objects.serializedIsaacAPIClassTypeToIdentityFunction")
 local SERIALIZED_ISAAC_API_CLASS_TYPE_TO_IDENTITY_FUNCTION = ____serializedIsaacAPIClassTypeToIdentityFunction.SERIALIZED_ISAAC_API_CLASS_TYPE_TO_IDENTITY_FUNCTION
 local ____isaacAPIClass = require("functions.isaacAPIClass")
-local getIsaacAPIClassType = ____isaacAPIClass.getIsaacAPIClassType
+local getIsaacAPIClassName = ____isaacAPIClass.getIsaacAPIClassName
 function getSerializedTableType(self, serializedIsaacAPIClass)
     for ____, ____value in ipairs(__TS__ObjectEntries(ISAAC_API_CLASS_TYPE_TO_BRAND)) do
         local copyableIsaacAPIClassType = ____value[1]
@@ -29,7 +29,7 @@ function ____exports.copyIsaacAPIClass(self, isaacAPIClass, serializationType)
     if objectType ~= "userdata" then
         error("Failed to copy an Isaac API class since the provided object was of type: " .. objectType)
     end
-    local isaacAPIClassType = getIsaacAPIClassType(nil, isaacAPIClass)
+    local isaacAPIClassType = getIsaacAPIClassName(nil, isaacAPIClass)
     if isaacAPIClassType == nil then
         error("Failed to copy an Isaac API class since it does not have a class type.")
     end
@@ -40,6 +40,10 @@ function ____exports.copyIsaacAPIClass(self, isaacAPIClass, serializationType)
     end
     return copyFunction(nil, isaacAPIClass, serializationType)
 end
+--- Deserialization is a special case, so we make a dedicated function for this.
+-- 
+-- There is no need for a corresponding "serializeIsaacAPIClass" function because the
+-- "copyIsaacAPIClass" function can handles all serialization types.
 function ____exports.deserializeIsaacAPIClass(self, serializedIsaacAPIClass)
     local objectType = type(serializedIsaacAPIClass)
     if objectType ~= "table" then

package/functions/set.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 /**
  * Helper function to add all of the values in one set to another set. The first set passed will be
  * modified in place.

package/functions/set.lua

@@ -9,12 +9,20 @@ local ____array = require("functions.array")
 local getRandomArrayElement = ____array.getRandomArrayElement
 local ____rng = require("functions.rng")
 local getRandomSeed = ____rng.getRandomSeed
+--- Helper function to get a sorted array based on the contents of a set.
+-- 
+-- Normally, set values are returned in a random order, so use this function when the ordering of
+-- the contents is important.
 function ____exports.getSortedSetValues(self, set)
     local values = set:values()
     local array = {__TS__Spread(values)}
     __TS__ArraySort(array)
     return array
 end
+--- Helper function to add all of the values in one set to another set. The first set passed will be
+-- modified in place.
+-- 
+-- This function is variadic, meaning that you can specify N sets to add to the first set.
 function ____exports.addSetsToSet(self, mainSet, ...)
     local setsToAdd = {...}
     for ____, set in ipairs(setsToAdd) do
@@ -23,6 +31,9 @@ function ____exports.addSetsToSet(self, mainSet, ...)
         end
     end
 end
+--- Helper function to create a new set that is the composition of two or more sets.
+-- 
+-- This function is variadic, meaning that you can specify N sets.
 function ____exports.combineSets(self, ...)
     local sets = {...}
     local newSet = __TS__New(Set)
@@ -33,6 +44,7 @@ function ____exports.combineSets(self, ...)
     end
     return newSet
 end
+--- Helper function to copy a set. (You can also use a Set constructor to accomplish this task.)
 function ____exports.copySet(self, oldSet)
     local newSet = __TS__New(Set)
     for ____, value in __TS__Iterator(oldSet:values()) do
@@ -40,6 +52,10 @@ function ____exports.copySet(self, oldSet)
     end
     return newSet
 end
+--- Helper function to delete all of the values in one set from another set. The first set passed
+-- will be modified in place.
+-- 
+-- This function is variadic, meaning that you can specify N sets to remove from the first set.
 function ____exports.deleteSetsFromSet(self, mainSet, ...)
     local setsToRemove = {...}
     for ____, set in ipairs(setsToRemove) do
@@ -48,6 +64,12 @@ function ____exports.deleteSetsFromSet(self, mainSet, ...)
         end
     end
 end
+--- Helper function to get a random element from the provided set.
+-- 
+-- @param set The set to get an element from.
+-- @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+-- `RNG.Next` method will be called. Default is `getRandomSeed()`.
+-- @param exceptions Optional. An array of elements to skip over if selected.
 function ____exports.getRandomSetElement(self, set, seedOrRNG, exceptions)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)