isaacscript-common 2.3.1 → 3.1.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

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

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.d.ts

@@ -1,4 +1,6 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 /**
  * Helper function to clear a specific layer from a sprite.
  *

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.d.ts

@@ -27,6 +27,18 @@ export declare function getNumbersFromTable(table: LuaTable<string, unknown>, ob
  * This function is variadic, meaning that you can specify N arguments to get N values.
  */
 export declare function getStringsFromTable(table: LuaTable<string, unknown>, objectName: string, ...keys: string[]): string[];
+/**
+ * Helper function to iterate over a table deterministically. This is useful because by default, the
+ * `pairs` function will return the keys of a Lua table in a random order.
+ *
+ * This function will sort the table entries based on the value of the key.
+ *
+ * @param table The table to iterate over.
+ * @param func The function to run for each iteration.
+ * @param deterministic Optional. Whether to iterate deterministically. True by default. You can
+ *                      dynamically set to false in situations where you need extra performance.
+ */
+export declare function iterateTableDeterministically<K, V>(table: LuaTable<K, V>, func: (key: K, value: V) => void, deterministic?: boolean): void;
 /**
  * Helper function to check if a Lua table has all of the provided keys.
  *