isaacscript-common 2.3.2 → 3.0.0

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

@@ -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.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)

package/functions/spawnCollectible.lua

@@ -20,6 +20,20 @@ local anyPlayerIs = ____player.anyPlayerIs
 local ____rng = require("functions.rng")
 local getRandomSeed = ____rng.getRandomSeed
 local isRNG = ____rng.isRNG
+--- Helper function to spawn a collectible. Use this instead of the `Game.Spawn` method because it
+-- handles the cases of Tainted Keeper collectibles costing coins and preventing quest items from
+-- being rotated by Tainted Isaac's rotation mechanic. (Rotation prevention will only occur in
+-- upgraded mods.)
+-- 
+-- @param collectibleType The collectible type to spawn.
+-- @param position The position to spawn the collectible at.
+-- @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 options Optional. Set to true to make the collectible a "There's Options" style
+-- collectible. Default is false.
+-- @param forceFreeItem Optional. Set to true to disable the logic that gives the item a price for
+-- Tainted Keeper. Default is false.
+-- @param spawner Optional.
 function ____exports.spawnCollectible(self, collectibleType, position, seedOrRNG, options, forceFreeItem, spawner)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -52,6 +66,16 @@ function ____exports.spawnCollectible(self, collectibleType, position, seedOrRNG
     end
     return collectible
 end
+--- Helper function to spawn an empty collectible. Doing this is tricky since spawning a collectible
+-- with `CollectibleType.NULL` will result in spawning a collectible with a random type from the
+-- current room's item pool.
+-- 
+-- Instead, this function arbitrarily spawns a collectible with `CollectibleType.SAD_ONION`, and
+-- then converts it to an empty pedestal afterward.
+-- 
+-- @param position The position to spawn the empty collectible at.
+-- @param seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+-- `RNG.Next` method will be called. Default is `getRandomSeed()`.
 function ____exports.spawnEmptyCollectible(self, position, seedOrRNG)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)

package/functions/sprite.lua

@@ -6,11 +6,22 @@ local ____kColor = require("functions.kColor")
 local kColorEquals = ____kColor.kColorEquals
 local ____utils = require("functions.utils")
 local erange = ____utils.erange
+--- Helper function to check if two texels on a sprite are equivalent to each other.
 function ____exports.texelEquals(self, sprite1, sprite2, position, layerID)
     local kColor1 = sprite1:GetTexel(position, VectorZero, 1, layerID)
     local kColor2 = sprite2:GetTexel(position, VectorZero, 1, layerID)
     return kColorEquals(nil, kColor1, kColor2)
 end
+--- Helper function to clear a specific layer from a sprite.
+-- 
+-- This function is variadic, so pass as many layer IDs as you want to clear. If no specific layers
+-- are passed, it will clear every layer.
+-- 
+-- Since there is no official API method to "clear" a sprite, we can work around it by setting the
+-- spritesheet to a non-existent or completely transparent file. If the path to the spritesheet does
+-- not exist, then this function might cause spurious errors to appear in the "log.txt file". To
+-- silence these errors, create a transparent 1 pixel PNG file in your mod's resources folder at the
+-- path corresponding to the "EMPTY_PNG_PATH" constant.
 function ____exports.clearSprite(self, sprite, ...)
     local layerIDs = {...}
     if #layerIDs == 0 then
@@ -22,6 +33,15 @@ function ____exports.clearSprite(self, sprite, ...)
     end
     sprite:LoadGraphics()
 end
+--- Helper function that returns the number of the final frame in a particular animation for a
+-- sprite. By default, it will use the currently playing animation, but you can also specify a
+-- specific animation to check.
+-- 
+-- Note that this function is bugged with the Stop Watch or the Broken Watch, since using the
+-- `Sprite.SetFrame` method will reset the internal accumulator used to slow down the playback speed
+-- of the animation. (The `PlaybackSpeed` property of the sprite is not used.) Thus, it is only safe
+-- to use this function on animations that are not slowed down by Stop Watch or Broken Watch, such
+-- as player animations.
 function ____exports.getLastFrameOfAnimation(self, sprite, animation)
     local currentAnimation = sprite:GetAnimation()
     local currentFrame = sprite:GetFrame()
@@ -36,6 +56,11 @@ function ____exports.getLastFrameOfAnimation(self, sprite, animation)
     sprite:SetFrame(currentFrame)
     return finalFrame
 end
+--- Helper function to check if two sprite layers have the same sprite sheet by using the
+-- `Sprite.GetTexel` method.
+-- 
+-- Since checking every single texel in the entire sprite is very expensive, this function requires
+-- that you provide a range of specific texels to check.
 function ____exports.spriteEquals(self, sprite1, sprite2, layerID, xStart, xFinish, xIncrement, yStart, yFinish, yIncrement)
     do
         local x = xStart

package/functions/stage.lua

@@ -14,9 +14,16 @@ function ____exports.onRepentanceStage(self)
     local stageType = level:GetStageType()
     return ____exports.isRepentanceStage(nil, stageType)
 end
+--- Helper function to convert a numerical `StageType` into the letter suffix supplied to the "stage"
+-- console command. For example, `StageType.REPENTANCE` is the stage type for Downpour, and the
+-- console command to go to Downpour is "stage 1c", so this function converts `StageType.REPENTANCE`
+-- to "c".
 function ____exports.stageTypeToLetter(self, stageType)
     return STAGE_TYPE_TO_LETTER[stageType]
 end
+--- Helper function to account for Repentance floors being offset by 1. For example, Downpour 2 is
+-- the third level of the run, but the game considers it to have a stage of 2. This function will
+-- consider Downpour 2 to have a stage of 3.
 function ____exports.getEffectiveStage(self)
     local level = game:GetLevel()
     local stage = level:GetStage()
@@ -25,14 +32,17 @@ function ____exports.getEffectiveStage(self)
     end
     return stage
 end
+--- Alias for the `Level.GetStage` method.
 function ____exports.getStage(self)
     local level = game:GetLevel()
     return level:GetStage()
 end
+--- Alias for the `Level.GetStageType` method.
 function ____exports.getStageType(self)
     local level = game:GetLevel()
     return level:GetStageType()
 end
+--- Helper function to directly warp to a specific stage using the "stage" console command.
 function ____exports.goToStage(self, stage, stageType)
     local stageTypeLetterSuffix = ____exports.stageTypeToLetter(nil, stageType)
     local command = ("stage " .. tostring(stage)) .. stageTypeLetterSuffix
@@ -56,6 +66,12 @@ function ____exports.onDarkRoom(self)
     local stageType = level:GetStageType()
     return stage == LevelStage.DARK_ROOM_CHEST and stageType == StageType.ORIGINAL
 end
+--- Returns whether or not the player is on the "final floor" of the particular run. The final floor
+-- is defined as one that prevents the player from entering the I AM ERROR room on.
+-- 
+-- For example, when using Undefined on The Chest, it has a 50% chance of teleporting the player to
+-- the Secret Room and a 50% chance of teleporting the player to the Super Secret Room, because the
+-- I AM ERROR room is never entered into the list of possibilities.
 function ____exports.onFinalFloor(self)
     local level = game:GetLevel()
     local stage = level:GetStage()

package/functions/string.lua

@@ -13,6 +13,10 @@ end
 function ____exports.removeAllCharacters(self, ____string, character)
     return __TS__StringReplaceAll(____string, character, "")
 end
+--- Helper function to remove one or more substrings from a string, if they exist. Returns the
+-- modified string.
+-- 
+-- This function is variadic, meaning that you can pass as many substrings as you want to remove.
 function ____exports.removeSubstring(self, ____string, ...)
     local substrings = {...}
     for ____, substring in ipairs(substrings) do
@@ -20,12 +24,14 @@ function ____exports.removeSubstring(self, ____string, ...)
     end
     return ____string
 end
+--- Helper function to trim a prefix from a string, if it exists. Returns the trimmed string.
 function ____exports.trimPrefix(self, ____string, prefix)
     if not __TS__StringStartsWith(____string, prefix) then
         return ____string
     end
     return __TS__StringSlice(____string, #prefix)
 end
+--- Helper function to trim a suffix from a string, if it exists. Returns the trimmed string.
 function ____exports.trimSuffix(self, ____string, prefix)
     if not __TS__StringEndsWith(____string, prefix) then
         return ____string

package/functions/table.lua

@@ -2,11 +2,14 @@ local ____lualib = require("lualib_bundle")
 local __TS__TypeOf = ____lualib.__TS__TypeOf
 local __TS__ArrayEvery = ____lualib.__TS__ArrayEvery
 local ____exports = {}
+--- In a Map, you can use the `clear` method to delete every element. However, in a LuaTable, the
+-- `clear` method does not exist. Use this helper function as a drop-in replacement for this.
 function ____exports.clearTable(self, ____table)
     for key in pairs(____table) do
         ____table[key] = nil
     end
 end
+--- Helper function to copy specific values from a object to a table.
 function ____exports.copyValuesToTable(self, object, keys, ____table)
     local otherTable = object
     for ____, key in ipairs(keys) do
@@ -14,6 +17,10 @@ function ____exports.copyValuesToTable(self, object, keys, ____table)
         ____table[key] = value
     end
 end
+--- Helper function to safely get boolean values from a Lua table. Will throw an error if the
+-- specific value does not exist on the table.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to get N values.
 function ____exports.getBooleansFromTable(self, ____table, objectName, ...)
     local keys = {...}
     local booleans = {}
@@ -30,6 +37,10 @@ function ____exports.getBooleansFromTable(self, ____table, objectName, ...)
     end
     return booleans
 end
+--- Helper function to safely get number values from a Lua table. Will throw an error if the specific
+-- value does not exist on the table or if it cannot be converted to a number.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to get N values.
 function ____exports.getNumbersFromTable(self, ____table, objectName, ...)
     local keys = {...}
     local numbers = {}
@@ -52,6 +63,10 @@ function ____exports.getNumbersFromTable(self, ____table, objectName, ...)
     end
     return numbers
 end
+--- Helper function to safely get string values from a Lua table. Will throw an error if the specific
+-- value does not exist on the table.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to get N values.
 function ____exports.getStringsFromTable(self, ____table, objectName, ...)
     local keys = {...}
     local strings = {}
@@ -69,6 +84,10 @@ function ____exports.getStringsFromTable(self, ____table, objectName, ...)
     end
     return strings
 end
+--- Helper function to check if a Lua table has all of the provided keys.
+-- 
+-- This function is variadic, meaning that you can specify as many arguments as you want to check
+-- for.
 function ____exports.tableHasKeys(self, ____table, ...)
     local keys = {...}
     return __TS__ArrayEvery(

package/functions/tears.lua

@@ -1,10 +1,22 @@
 local ____exports = {}
+--- - The `EntityPlayer` object stores a player's tear rate in the `MaxFireDelay` attribute. This is
+--   equivalent to how many tears the player can shoot per frame.
+-- - If you already have a "tears" stat and you want to convert it back to MaxFireDelay, then use
+--   this function.
+-- - In this context, the "tears stat" represents what is shown on the in-game stat UI.
 function ____exports.getFireDelay(self, tearsStat)
     return math.max(30 / tearsStat - 1, -0.9999)
 end
+--- - The `EntityPlayer` object stores a player's tear rate in the `MaxFireDelay` attribute. This is
+--   equivalent to how many tears the player can shoot per frame.
+-- - If you want to convert this to the "tears" stat that is shown on the in-game stat UI, then use
+--   this function.
 function ____exports.getTearsStat(self, fireDelay)
     return 30 / (fireDelay + 1)
 end
+--- - Converts the specified amount of tears stat into MaxFireDelay and adds it to the player.
+-- - This function should only be used inside the EvaluateCache callback.
+-- - In this context, the "tears stat" represents what is shown on the in-game stat UI.
 function ____exports.addTearsStat(self, player, tearsStat)
     local existingTearsStat = ____exports.getTearsStat(nil, player.MaxFireDelay)
     local newTearsStat = existingTearsStat + tearsStat

package/functions/transformations.lua

@@ -36,6 +36,14 @@ local TRANSFORMATION_TO_TAG_MAP = __TS__New(Map, {
     {PlayerForm.SPIDER_BABY, ItemConfigTag.SPIDER}
 })
 local TRANSFORMATIONS_THAT_GRANT_FLYING = __TS__New(Set, {PlayerForm.GUPPY, PlayerForm.BEELZEBUB, PlayerForm.SERAPHIM, PlayerForm.LEVIATHAN})
+--- Helper function to get all of the collectible types in the game that count towards a particular
+-- transformation.
+-- 
+-- For example, to get all of the collectible types that count towards Guppy:
+-- 
+-- ```ts
+-- const guppyCollectibleTypes = getCollectibleTypesForTransformation(PlayerForm.GUPPY);
+-- ```
 function ____exports.getCollectibleTypesForTransformation(self, playerForm)
     local itemConfigTag = TRANSFORMATION_TO_TAG_MAP:get(playerForm)
     if itemConfigTag == nil then
@@ -43,6 +51,7 @@ function ____exports.getCollectibleTypesForTransformation(self, playerForm)
     end
     return getCollectibleTypesWithTag(nil, itemConfigTag)
 end
+--- Returns the number of items that a player has towards a particular transformation.
 function ____exports.getPlayerNumCollectiblesForTransformation(self, player, playerForm)
     local collectibleTypes = ____exports.getCollectibleTypesForTransformation(nil, playerForm)
     return getPlayerCollectibleCount(
@@ -51,6 +60,7 @@ function ____exports.getPlayerNumCollectiblesForTransformation(self, player, pla
         __TS__Spread(collectibleTypes:values())
     )
 end
+--- Returns a set of the player's current transformations.
 function ____exports.getPlayerTransformations(self, player)
     local transformations = __TS__New(Set)
     for ____, playerForm in ipairs(getEnumValues(nil, PlayerForm)) do
@@ -60,6 +70,14 @@ function ____exports.getPlayerTransformations(self, player)
     end
     return transformations
 end
+--- Helper function to get a transformation name from a PlayerForm enum.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const transformationName = getTransformationName(PlayerForm.LORD_OF_THE_FLIES);
+-- // transformationName is "Beelzebub"
+-- ```
 function ____exports.getTransformationName(self, playerForm)
     local transformationName = TRANSFORMATION_NAMES[playerForm]
     return transformationName == nil and DEFAULT_TRANSFORMATION_NAME or transformationName