isaacscript-common 2.3.2 → 3.0.0

package/functions/playerIndex.lua

@@ -10,6 +10,11 @@ local CollectibleType = ____isaac_2Dtypescript_2Ddefinitions.CollectibleType
 local PlayerType = ____isaac_2Dtypescript_2Ddefinitions.PlayerType
 local ____cachedClasses = require("cachedClasses")
 local game = ____cachedClasses.game
+--- Helper function to get every player with no restrictions, by using `Game.GetNumPlayers` and
+-- `Isaac.GetPlayer`.
+-- 
+-- This function is almost never what you want to use. For most purposes, use the `getPlayers`
+-- helper function instead to get a filtered list of players.
 function ____exports.getAllPlayers(self)
     local numPlayers = game:GetNumPlayers()
     local players = {}
@@ -23,6 +28,33 @@ function ____exports.getAllPlayers(self)
     end
     return players
 end
+--- Mods often have to track variables relating to the player. In naive mods, information will only
+-- be stored about the first player. However, in order to be robust, mods must handle up to 4
+-- players playing at the same time. This means that information must be stored on a map data
+-- structure. Finding a good index for these types of map data structures is difficult:
+-- 
+-- - We cannot use the index from `Isaac.GetPlayer(i)` since this fails in the case where there are
+--   two players and the first player leaves the run.
+-- - We cannot use `EntityPlayer.ControllerIndex` as an index because it fails in the case of Jacob
+--   & Esau or Tainted Forgotten. It also fails in the case of a player changing their controls
+--   mid-run.
+-- - We cannot use `EntityPlayer.GetData().index` because it does not persist across saving and
+--   continuing.
+-- - We cannot use `GetPtrHash()` as an index because it does not persist across exiting and
+--   relaunching the game.
+-- - We cannot use `EntityPlayer.InitSeed` because it is not consistent with additional players
+--   beyond the first.
+-- 
+-- Instead, we use the `EntityPlayer.GetCollectibleRNG` method with an arbitrary value of Sad Onion
+-- (1). This works even if the player does not have any Sad Onions.
+-- 
+-- Since the RNG value is the same for both Tainted Lazarus and Dead Tainted Lazarus, we revert to
+-- using the RNG of The Inner Eye (2) for Dead Tainted Lazarus.
+-- 
+-- Note that by default, this returns the same index for both The Forgotten and The Soul. (Even
+-- though they are technically different characters, they share the same inventory and InitSeed.) If
+-- this is not desired, pass true for the `differentiateForgottenAndSoul` argument, and the RNG of
+-- Spoon Bender (3) will be used for The Soul.
 function ____exports.getPlayerIndex(self, player, differentiateForgottenAndSoul)
     if differentiateForgottenAndSoul == nil then
         differentiateForgottenAndSoul = false
@@ -63,6 +95,14 @@ function getPlayerIndexCollectibleType(self, player, differentiateForgottenAndSo
         end
     until true
 end
+--- This function always excludes players with a non-undefined parent, since they are not real
+-- players (e.g. the Strawman Keeper).
+-- 
+-- If this is not desired, use the `getAllPlayers` helper function instead.
+-- 
+-- @param performCharacterExclusions Whether or not to exclude characters that are not directly
+-- controlled by the player (i.e. Esau & Tainted Soul). Default is
+-- false.
 function ____exports.getPlayers(self, performCharacterExclusions)
     if performCharacterExclusions == nil then
         performCharacterExclusions = false
@@ -81,6 +121,9 @@ function ____exports.getPlayers(self, performCharacterExclusions)
     )
     return performCharacterExclusions and nonChildPlayersFiltered or nonChildPlayers
 end
+--- Helper function to get a parent `EntityPlayer` object for a given `EntitySubPlayer` object. This
+-- is useful because calling the `EntityPlayer.GetSubPlayer` method on a sub-player object will
+-- return undefined.
 function ____exports.getSubPlayerParent(self, subPlayer)
     local subPlayerPtrHash = GetPtrHash(subPlayer)
     local players = ____exports.getPlayers(nil)
@@ -96,6 +139,8 @@ function ____exports.getSubPlayerParent(self, subPlayer)
         end
     )
 end
+--- Some players are "child" players, meaning that they have a non-undefined Parent property. (For
+-- example, the Strawman Keeper.)
 function ____exports.isChildPlayer(self, player)
     return player.Parent ~= nil
 end
@@ -108,6 +153,8 @@ function ____exports.getPlayerFromIndex(self, playerIndex)
         function(____, player) return ____exports.getPlayerIndex(nil, player) == playerIndex end
     )
 end
+--- Helper function to return the index of this player with respect to the output of the
+-- `Isaac.GetPlayer` method.
 function ____exports.getPlayerIndexVanilla(self, playerToFind)
     local numPlayers = game:GetNumPlayers()
     local playerToFindHash = GetPtrHash(playerToFind)

package/functions/pocketItems.lua

@@ -15,6 +15,14 @@ local ____enums = require("functions.enums")
 local getEnumValues = ____enums.getEnumValues
 local ____player = require("functions.player")
 local isCharacter = ____player.isCharacter
+--- Use this helper function as a workaround for the `EntityPlayer.GetPocketItem` method not working
+-- correctly.
+-- 
+-- Note that due to API limitations, there is no way to determine the location of a Dice Bag trinket
+-- dice. Furthermore, when the player has a Dice Bag trinket dice and a pocket active at the same
+-- time, there is no way to determine the location of the pocket active item. If this function
+-- cannot determine the identity of a particular slot, it will mark the type of the slot as
+-- `PocketItemType.UNDETERMINABLE`.
 function ____exports.getPocketItems(self, player)
     local pocketItem = player:GetActiveItem(ActiveSlot.POCKET)
     local hasPocketItem = pocketItem ~= CollectibleType.NULL
@@ -49,6 +57,8 @@ function ____exports.getPocketItems(self, player)
     end
     return pocketItems
 end
+--- Helper function to get the `PocketItemSlot` that the player's pocket active collectible item is
+-- in, if any. Returns undefined if the player does not have a pocket active item.
 function ____exports.getActivePocketItemSlot(self, player)
     local pocketItems = ____exports.getPocketItems(nil, player)
     for ____, pocketItem in ipairs(pocketItems) do
@@ -65,6 +75,12 @@ function ____exports.getFirstCardOrPill(self, player)
         function(____, pocketItem) return pocketItem.type == PocketItemType.CARD or pocketItem.type == PocketItemType.PILL end
     )
 end
+--- Returns whether or not the player can hold an additional pocket item, beyond what they are
+-- currently carrying. This takes into account items that modify the max number of pocket items,
+-- like Starter Deck.
+-- 
+-- If the player is the Tainted Soul, this always returns false, since that character cannot pick up
+-- items. (Only Tainted Forgotten can pick up items.)
 function ____exports.hasOpenPocketItemSlot(self, player)
     if isCharacter(nil, player, PlayerType.THE_SOUL_B) then
         return false
@@ -75,6 +91,8 @@ function ____exports.hasOpenPocketItemSlot(self, player)
         function(____, pocketItem) return pocketItem.type == PocketItemType.EMPTY end
     )
 end
+--- Helper function to determine whether or not the player's "active" pocket item slot is set to
+-- their pocket active item.
 function ____exports.isFirstSlotPocketActiveItem(self, player)
     local pocketItems = ____exports.getPocketItems(nil, player)
     local firstPocketItem = pocketItems[1]

package/functions/positionVelocity.lua

@@ -25,6 +25,7 @@ function ____exports.anyEntityCloserThan(self, entities, position, distance)
         function(____, entity) return position:Distance(entity.Position) <= distance end
     )
 end
+--- Iterates over all players and checks if any player is close enough to the specified position.
 function ____exports.anyPlayerCloserThan(self, position, distance)
     local players = getPlayers(nil)
     return __TS__ArraySome(
@@ -32,6 +33,15 @@ function ____exports.anyPlayerCloserThan(self, position, distance)
         function(____, player) return player.Position:Distance(position) <= distance end
     )
 end
+--- Helper function to get a room position that is not overlapping with a grid entity, a heaven door,
+-- or a player. The `Room.FindFreePickupSpawnPosition` method will return locations that overlap
+-- with heaven doors and partially overlap with players, if the thing being spawned is bigger than a
+-- tile (like a Blood Donation Machine). Use this function instead if you want to account for those
+-- specific situations.
+-- 
+-- @param startingPosition The position to start searching from. If this position is not overlapping
+-- with anything, then it will be returned.
+-- @param avoidActiveEntities Optional. Default is false.
 function ____exports.findFreePosition(self, startingPosition, avoidActiveEntities)
     if avoidActiveEntities == nil then
         avoidActiveEntities = false
@@ -59,6 +69,13 @@ function ____exports.findFreePosition(self, startingPosition, avoidActiveEntitie
     end
     return room:FindFreePickupSpawnPosition(startingPosition)
 end
+--- Helper function to get a map containing the positions of every entity in the current room.
+-- 
+-- This is useful for rewinding entity positions at a later time. Also see `setEntityPositions`.
+-- 
+-- @param entities Optional. If provided, will only get the positions of the provided entities. Use
+-- this with cached entities to avoid invoking the `Isaac.GetRoomEntities` method
+-- multiple times.
 function ____exports.getEntityPositions(self, entities)
     if entities == nil then
         entities = getEntities(nil)
@@ -70,6 +87,13 @@ function ____exports.getEntityPositions(self, entities)
     end
     return entityPositions
 end
+--- Helper function to get a map containing the velocities of every entity in the current room.
+-- 
+-- This is useful for rewinding entity velocities at a later time. Also see `setEntityVelocities`.
+-- 
+-- @param entities Optional. If provided, will only get the velocities of the provided entities. Use
+-- this with cached entities to avoid invoking the `Isaac.GetRoomEntities` method
+-- multiple times.
 function ____exports.getEntityVelocities(self, entities)
     if entities == nil then
         entities = getEntities(nil)
@@ -81,6 +105,17 @@ function ____exports.getEntityVelocities(self, entities)
     end
     return entityVelocities
 end
+--- Helper function to set the position of every entity in the room based on a map of positions. If
+-- an entity is found that does not have matching element in the provided map, then that entity will
+-- be skipped.
+-- 
+-- This function is useful for rewinding entity positions at a later time. Also see
+-- `getEntityPositions`.
+-- 
+-- @param entityPositions The map providing the positions for every entity.
+-- @param entities Optional. If provided, will only set the positions of the provided entities. Use
+-- this with cached entities to avoid invoking the `Isaac.GetRoomEntities` method
+-- multiple times.
 function ____exports.setEntityPositions(self, entityPositions, entities)
     if entities == nil then
         entities = getEntities(nil)
@@ -93,6 +128,17 @@ function ____exports.setEntityPositions(self, entityPositions, entities)
         end
     end
 end
+--- Helper function to set the velocity of every entity in the room based on a map of velocities. If
+-- an entity is found that does not have matching element in the provided map, then that entity will
+-- be skipped.
+-- 
+-- This function is useful for rewinding entity velocities at a later time. Also see
+-- `getEntityVelocities`.
+-- 
+-- @param entityVelocities The map providing the velocities for every entity.
+-- @param entities Optional. If provided, will only set the velocities of the provided entities. Use
+-- this with cached entities to avoid invoking the `Isaac.GetRoomEntities` method
+-- multiple times.
 function ____exports.setEntityVelocities(self, entityVelocities, entities)
     if entities == nil then
         entities = getEntities(nil)

package/functions/random.lua

@@ -3,6 +3,11 @@ local ____rng = require("functions.rng")
 local getRandomSeed = ____rng.getRandomSeed
 local isRNG = ____rng.isRNG
 local newRNG = ____rng.newRNG
+--- This returns a random float between 0 and 1. It is inclusive on the low end, but exclusive on the
+-- high end. (This is because the `RNG.RandomFloat` method will never return a value of exactly 1.)
+-- 
+-- @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()`.
 function ____exports.getRandom(self, seedOrRNG)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -10,6 +15,18 @@ function ____exports.getRandom(self, seedOrRNG)
     local rng = isRNG(nil, seedOrRNG) and seedOrRNG or newRNG(nil, seedOrRNG)
     return rng:RandomFloat()
 end
+--- This returns a random float between min and max.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const realNumberBetweenOneAndThree = getRandomFloat(1, 3);
+-- ```
+-- 
+-- @param min The lower bound for the random number (inclusive).
+-- @param max The upper bound for the random number (exclusive).
+-- @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()`.
 function ____exports.getRandomFloat(self, min, max, seedOrRNG)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -22,6 +39,21 @@ function ____exports.getRandomFloat(self, min, max, seedOrRNG)
     end
     return min + ____exports.getRandom(nil, seedOrRNG) * (max - min)
 end
+--- This returns a random integer between min and max. It is inclusive on both ends.
+-- 
+-- Note that this function will invoke the `Next` method on the `RNG` object before returning the
+-- random number.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const oneTwoOrThree = getRandomInt(1, 3);
+-- ```
+-- 
+-- @param min The lower bound for the random number (inclusive).
+-- @param max The upper bound for the random number (inclusive).
+-- @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()`.
 function ____exports.getRandomInt(self, min, max, seedOrRNG)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)

package/functions/revive.lua

@@ -22,6 +22,9 @@ local getLastFrameOfAnimation = ____sprite.getLastFrameOfAnimation
 local ____trinketGive = require("functions.trinketGive")
 local giveTrinketsBack = ____trinketGive.giveTrinketsBack
 local temporarilyRemoveTrinket = ____trinketGive.temporarilyRemoveTrinket
+--- Helper function to determine if the player will be revived by the Heartbreak collectible if they
+-- take fatal damage. This is contingent on the character that they are playing as and the amount of
+-- broken hearts that they already have.
 function ____exports.willReviveFromHeartbreak(self, player)
     if not player:HasCollectible(CollectibleType.HEARTBREAK) then
         return false
@@ -32,6 +35,8 @@ function ____exports.willReviveFromHeartbreak(self, player)
     local numBrokenHeartsAfterRevival = numBrokenHeartsThatWillBeAdded + brokenHearts
     return maxHeartContainers > numBrokenHeartsAfterRevival
 end
+--- Helper function to determine if the Spirit Shackles item is in an enabled state. (It can be
+-- either enabled or disabled.)
 function ____exports.willReviveFromSpiritShackles(self, player)
     if not player:HasCollectible(CollectibleType.SPIRIT_SHACKLES) then
         return false
@@ -41,6 +46,8 @@ function ____exports.willReviveFromSpiritShackles(self, player)
     local playerInSoulForm = effects:HasNullEffect(NullItemID.SPIRIT_SHACKLES_SOUL)
     return spiritShacklesEnabled and not playerInSoulForm
 end
+--- Uses the player's current health and other miscellaneous things to determine if incoming damage
+-- will be fatal.
 function ____exports.isDamageToPlayerFatal(self, player, damageAmount, damageSource, lastDamageGameFrame)
     local gameFrameCount = game:GetFrameCount()
     local character = player:GetPlayerType()
@@ -84,6 +91,12 @@ function ____exports.isDamageToPlayerFatal(self, player, damageAmount, damageSou
     end
     return true
 end
+--- Assuming that we are on the frame of fatal damage, this function returns whether or not
+-- Mysterious Paper would rotate to Missing Poster on the frame that the "Game Over" screen would
+-- appear (which would subsequently save the player from fatal damage).
+-- 
+-- Mysterious Paper rotates between the 4 items on every frame, in order. The formula for whether
+-- Mysterious Paper be Missing Power is: `gameFrameCount % 4 === 3`
 function ____exports.willMysteriousPaperRevive(self, player)
     local gameFrameCount = game:GetFrameCount()
     local sprite = player:GetSprite()
@@ -93,6 +106,8 @@ function ____exports.willMysteriousPaperRevive(self, player)
     local frameOfDeath = gameFrameCount + deathAnimationFrames + 1
     return frameOfDeath % 4 == 3
 end
+--- The `EntityPlayer.WillPlayerRevive` method does not properly account for Mysterious Paper, so use
+-- this helper function instead for more robust revival detection.
 function ____exports.willPlayerRevive(self, player)
     local trinketSituation = temporarilyRemoveTrinket(nil, player, TrinketType.MYSTERIOUS_PAPER)
     local willRevive = player:WillPlayerRevive() or trinketSituation ~= nil and ____exports.willMysteriousPaperRevive(nil, player)

package/functions/rng.lua

@@ -16,14 +16,21 @@ local getNumbersFromTable = ____table.getNumbersFromTable
 local tableHasKeys = ____table.tableHasKeys
 local ____utils = require("functions.utils")
 local ensureAllCases = ____utils.ensureAllCases
+--- Helper function to get a random `Seed` value to be used in spawning entities and so on. Use this
+-- instead of calling the `Random` function directly since that can return a value of 0 and crash
+-- the game.
 function ____exports.getRandomSeed(self)
     local randomNumber = Random()
     local safeRandomNumber = randomNumber == 0 and 1 or randomNumber
     return safeRandomNumber
 end
+--- Helper function to check if something is an instantiated RNG object.
 function ____exports.isRNG(self, object)
     return isIsaacAPIClassOfType(nil, object, OBJECT_NAME)
 end
+--- Helper function to initialize an RNG object using Blade's recommended shift index.
+-- 
+-- @param seed The seed to initialize it with. Default is `getRandomSeed()`.
 function ____exports.newRNG(self, seed)
     if seed == nil then
         seed = ____exports.getRandomSeed(nil)
@@ -32,6 +39,7 @@ function ____exports.newRNG(self, seed)
     ____exports.setSeed(nil, rng, seed)
     return rng
 end
+--- Helper function to set a seed to an RNG object using Blade's recommended shift index.
 function ____exports.setSeed(self, rng, seed)
     if seed == 0 then
         error("You cannot set an RNG object to a seed of 0, or the game will crash.")
@@ -41,6 +49,11 @@ end
 RECOMMENDED_SHIFT_IDX = 35
 local KEYS = {"seed"}
 OBJECT_NAME = "RNG"
+--- Helper function to copy an `RNG` object.
+-- 
+-- @param rng The RNG object to copy. In the case of deserialization, this will actually be a Lua
+-- table instead of an instantiated RNG class.
+-- @param serializationType Default is `SerializationType.NONE`.
 function ____exports.copyRNG(self, rng, serializationType)
     if serializationType == nil then
         serializationType = SerializationType.NONE
@@ -94,6 +107,8 @@ function ____exports.copyRNG(self, rng, serializationType)
         end
     until true
 end
+--- Used to determine is the given table is a serialized `RNG` object created by the save data
+-- manager and/or the `deepCopy` function.
 function ____exports.isSerializedRNG(self, object)
     local objectType = type(object)
     if objectType ~= "table" then
@@ -109,6 +124,8 @@ end
 function ____exports.rngEquals(self, rng1, rng2)
     return isaacAPIClassEquals(nil, rng1, rng2, KEYS)
 end
+--- Helper function to iterate over the provided object and set the seed for all of the values that
+-- are RNG objects equal to a particular seed.
 function ____exports.setAllRNGToSeed(self, object, seed)
     local objectType = type(object)
     if objectType ~= "table" then
@@ -121,6 +138,8 @@ function ____exports.setAllRNGToSeed(self, object, seed)
         end
     end
 end
+--- Helper function to iterate over the provided object and set the seed for all of the values that
+-- are RNG objects equal to the start seed for the current run.
 function ____exports.setAllRNGToStartSeed(self, object)
     local seeds = game:GetSeeds()
     local startSeed = seeds:GetStartSeed()

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