isaacscript-common 2.3.2 → 3.0.0

package/functions/enums.lua

@@ -6,6 +6,21 @@ local ____array = require("functions.array")
 local getRandomArrayElement = ____array.getRandomArrayElement
 local ____rng = require("functions.rng")
 local getRandomSeed = ____rng.getRandomSeed
+--- TypeScriptToLua will transpile TypeScript enums to Lua tables that have a double mapping. Thus,
+-- when you iterate over them, you will get both the names of the enums and the values of the enums,
+-- in a random order. Use this helper function to get the entries of the enum with the reverse
+-- mappings filtered out.
+-- 
+-- This function will return the enum values in a sorted order, which may not necessarily be the
+-- same order as which they were declared in.
+-- 
+-- This function will work properly for both number enums and string enums. (Reverse mappings are
+-- not created for string enums.)
+-- 
+-- Also see the `getEnumKeys` and `getEnumValues` helper functions.
+-- 
+-- For a more in depth explanation, see:
+-- https://isaacscript.github.io/gotchas#iterating-over-enums
 function ____exports.getEnumEntries(self, transpiledEnum)
     local enumEntries = {}
     for key, value in pairs(transpiledEnum) do
@@ -27,6 +42,20 @@ function ____exports.getEnumEntries(self, transpiledEnum)
     )
     return enumEntries
 end
+--- TypeScriptToLua will transpile TypeScript enums to Lua tables that have a double mapping. Thus,
+-- when you iterate over them, you will get both the names of the enums and the values of the enums,
+-- in a random order. If all you need are the keys of an enum, use this helper function.
+-- 
+-- This function will return the enum keys in a sorted order, which may not necessarily be the same
+-- order as which they were declared in.
+-- 
+-- This function will work properly for both number enums and string enums. (Reverse mappings are
+-- not created for string enums.)
+-- 
+-- Also see the `getEnumEntries` and `getEnumValues` helper functions.
+-- 
+-- For a more in depth explanation, see:
+-- https://isaacscript.github.io/gotchas#iterating-over-enums
 function ____exports.getEnumKeys(self, transpiledEnum)
     local enumEntries = ____exports.getEnumEntries(nil, transpiledEnum)
     return __TS__ArrayMap(
@@ -39,10 +68,25 @@ function ____exports.getEnumKeys(self, transpiledEnum)
         end
     )
 end
+--- Helper function to get the amount of entries inside of an enum.
 function ____exports.getEnumLength(self, transpiledEnum)
     local enumEntries = ____exports.getEnumEntries(nil, transpiledEnum)
     return #enumEntries
 end
+--- TypeScriptToLua will transpile TypeScript enums to Lua tables that have a double mapping. Thus,
+-- when you iterate over them, you will get both the names of the enums and the values of the enums,
+-- in a random order. If all you need are the values of an enum, use this helper function.
+-- 
+-- This function will return the enum values in a sorted order, which may not necessarily be the
+-- same order as which they were declared in.
+-- 
+-- This function will work properly for both number enums and string enums. (Reverse mappings are
+-- not created for string enums.)
+-- 
+-- Also see the `getEnumEntries` and `getEnumKeys` helper functions.
+-- 
+-- For a more in depth explanation, see:
+-- https://isaacscript.github.io/gotchas#iterating-over-enums
 function ____exports.getEnumValues(self, transpiledEnum)
     local enumEntries = ____exports.getEnumEntries(nil, transpiledEnum)
     return __TS__ArrayMap(
@@ -63,6 +107,12 @@ function ____exports.getLastEnumValue(self, transpiledEnum)
     end
     return lastElement
 end
+--- Helper function to get a random value from the provided enum.
+-- 
+-- @param transpiledEnum The enum to get the value 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.getRandomEnumValue(self, transpiledEnum, seedOrRNG, exceptions)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -73,6 +123,18 @@ function ____exports.getRandomEnumValue(self, transpiledEnum, seedOrRNG, excepti
     local enumValues = ____exports.getEnumValues(nil, transpiledEnum)
     return getRandomArrayElement(nil, enumValues, seedOrRNG, exceptions)
 end
+--- Helper function to check every value of a custom enum for -1. This is helpful as a run-time check
+-- because many methods of the Isaac class return -1 if they fail.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- enum EntityTypeCustom {
+--   FOO = Isaac.GetEntityTypeByName("Foo"),
+-- }
+-- 
+-- validateCustomEnum("EntityTypeCustom", EntityTypeCustom);
+-- ```
 function ____exports.validateCustomEnum(self, transpiledEnumName, transpiledEnum)
     for ____, ____value in ipairs(____exports.getEnumEntries(nil, transpiledEnum)) do
         local key = ____value[1]

package/functions/familiars.lua

@@ -3,6 +3,33 @@ local ____cachedClasses = require("cachedClasses")
 local itemConfig = ____cachedClasses.itemConfig
 local ____familiarsThatShootPlayerTearsSet = require("sets.familiarsThatShootPlayerTearsSet")
 local FAMILIARS_THAT_SHOOT_PLAYER_TEARS_SET = ____familiarsThatShootPlayerTearsSet.FAMILIARS_THAT_SHOOT_PLAYER_TEARS_SET
+--- Helper function to add and remove familiars based on a target amount that you specify.
+-- 
+-- This is a convenience wrapper around the `EntityPlayer.CheckFamiliar` method. Use this helper
+-- function instead so that you do not have to retrieve the `ItemConfigItem` and so that you do not
+-- specify an incorrect RNG object. (The vanilla method is bugged in that it does not increment the
+-- RNG object; see the documentation of the method for more details.)
+-- 
+-- This function is meant to be called in the EvaluateCache callback (when the cache flag is equal
+-- to `CacheFlag.FAMILIARS`).
+-- 
+-- Note that this function is only meant to be used in special circumstances where the familiar
+-- count is completely custom and does not correspond to the amount of collectibles. For the general
+-- case, use the `checkFamiliarFromCollectibles` helper function instead.
+-- 
+-- Note that this will spawn familiars with a completely random `InitSeed`. When calculating random
+-- events for this familiar, you should use a data structure that maps familiar `InitSeed` to RNG
+-- objects that are initialized based on the seed from
+-- `EntityPlayer.GetCollectibleRNG(collectibleType)`.
+-- 
+-- @param player The player that owns the familiars.
+-- @param collectibleType The collectible type of the collectible associated with this familiar.
+-- @param targetCount The number of familiars that should exist. This function will add or remove
+-- familiars until it matches the target count.
+-- @param familiarVariant The variant of the familiar to spawn or remove.
+-- @param familiarSubType Optional. The sub-type of the familiar to spawn or remove. If not
+-- specified, it will search for existing familiars of all sub-types, and
+-- spawn new familiars with a sub-type of 0.
 function ____exports.checkFamiliar(self, player, collectibleType, targetCount, familiarVariant, familiarSubType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     player:CheckFamiliar(
@@ -13,6 +40,31 @@ function ____exports.checkFamiliar(self, player, collectibleType, targetCount, f
         familiarSubType
     )
 end
+--- Helper function to add and remove familiars based on the amount of associated collectibles that a
+-- player has.
+-- 
+-- Use this helper function instead of invoking the `EntityPlayer.CheckFamiliar` method directly so
+-- that the target count is handled automatically.
+-- 
+-- This function is meant to be called in the EvaluateCache callback (when the cache flag is equal
+-- to `CacheFlag.FAMILIARS`).
+-- 
+-- Use this function when the amount of familiars should be equal to the amount of associated
+-- collectibles that the player has (plus any extras from having used Box of Friends or Monster
+-- Manual). If you instead need to have a custom amount of familiars, use the `checkFamiliars`
+-- function instead.
+-- 
+-- Note that this will spawn familiars with a completely random `InitSeed`. When calculating random
+-- events for this familiar, you should use a data structure that maps familiar `InitSeed` to RNG
+-- objects that are initialized based on the seed from
+-- `EntityPlayer.GetCollectibleRNG(collectibleType)`.
+-- 
+-- @param player The player that owns the familiars and collectibles.
+-- @param collectibleType The collectible type of the collectible associated with this familiar.
+-- @param familiarVariant The variant of the familiar to spawn or remove.
+-- @param familiarSubType Optional. The sub-type of the familiar to spawn or remove. If not
+-- specified, it will search for existing familiars of all sub-types, and
+-- spawn new familiars with a sub-type of 0.
 function ____exports.checkFamiliarFromCollectibles(self, player, collectibleType, familiarVariant, familiarSubType)
     local numCollectibles = player:GetCollectibleNum(collectibleType)
     local effects = player:GetEffects()

package/functions/flag.lua

@@ -1,6 +1,29 @@
 local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local DamageFlag = ____isaac_2Dtypescript_2Ddefinitions.DamageFlag
+--- Helper function to add a bit flag to an existing set of bit flags.
+-- 
+-- This is a variadic function, so pass as many flags as you want to add.
+-- 
+-- Example 1:
+-- 
+-- ```ts
+-- // Give the player spectral tears
+-- const player = Isaac.GetPlayer();
+-- player.TearFlags = addFlag(player.TearFlags, TearFlags.TEAR_SPECTRAL);
+-- ```
+-- 
+-- Example 2:
+-- 
+-- ```ts
+-- // Give the player spectral and homing tears
+-- const player = Isaac.GetPlayer();
+-- player.TearFlags = addFlag(player.TearFlags, TearFlags.TEAR_SPECTRAL, TearFlags.TEAR_HOMING);
+-- ```
+-- 
+-- @param flags The existing set of bit flags.
+-- @param flagsToAdd One or more bit flags to add, each as a separate argument.
+-- @returns The combined bit flags.
 function ____exports.addFlag(self, flags, ...)
     local flagsToAdd = {...}
     local flagsAsInt = flags
@@ -9,9 +32,25 @@ function ____exports.addFlag(self, flags, ...)
     end
     return flagsAsInt
 end
+--- Helper function for casting a flag enum value to a `BitFlags` object.
+-- 
+-- This is useful because the compiler will prevent you from assigning a specific flag to a
+-- `BitFlags` property. (It does this to ensure type safety, since `BitFlags` can represent a zero
+-- value or a composition of N flags.)
+-- 
+-- For example:
+-- 
+-- ```ts
+-- player.TearFlags = bitFlags(TearFlag.SPECTRAL);
+-- ```
 function ____exports.bitFlags(self, flag)
     return flag
 end
+--- Helper function to get the key associated with a particular flag.
+-- 
+-- (Since bit flags are represented by custom objects instead of normal TypeScript enums, you cannot
+-- use the reverse mapping to find the associated key of a given enum value. Use this helper
+-- function instead of indexing the enum directly.)
 function ____exports.getFlagName(self, flag, flagEnum)
     for key, value in pairs(flagEnum) do
         if value == flag then
@@ -20,6 +59,22 @@ function ____exports.getFlagName(self, flag, flagEnum)
     end
     return nil
 end
+--- Helper function to determine if a particular bit flag is set to true.
+-- 
+-- This is a variadic function, so pass as many flags as you want to check for. If passed multiple
+-- flags, it will only return true if all of the flags are set.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const player = Isaac.GetPlayer();
+-- if (hasFlag(player.TearFlags, TearFlags.TEAR_SPECTRAL) {
+--   // The player currently has spectral tears
+-- }
+-- ```
+-- 
+-- @param flags The existing set of bit flags.
+-- @param flagsToCheck One or more bit flags to check for, each as a separate argument.
 function ____exports.hasFlag(self, flags, ...)
     local flagsToCheck = {...}
     local flagsAsInt = flags
@@ -30,12 +85,34 @@ function ____exports.hasFlag(self, flags, ...)
     end
     return true
 end
+--- Helper function to check if every bit in the flag is turned off.
+-- 
+-- (This is equivalent to checking if the flag is equal to 0, but this is not possible without
+-- casting the flag to a number.)
 function ____exports.isEmptyFlag(self, flag)
     return flag == 0
 end
+--- Helper function to determine whether damage to a player in the EntityTakeDmg callback was
+-- self-inflicted. For example, damage from a Curse Room door, a Razor, or a Blood Donation Machine
+-- would count as self-inflicted damage.
 function ____exports.isSelfDamage(self, damageFlags)
     return ____exports.hasFlag(nil, damageFlags, DamageFlag.NO_PENALTIES) or ____exports.hasFlag(nil, damageFlags, DamageFlag.RED_HEARTS)
 end
+--- Helper function to remove a bit flag from an existing set of bit flags.
+-- 
+-- This is a variadic function, so pass as many flags as you want to remove.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- // Remove spectral tears from the player, if present
+-- const player = Isaac.GetPlayer();
+-- player.TearFlags = removeFlag(player.TearFlags, TearFlags.TEAR_SPECTRAL);
+-- ```
+-- 
+-- @param flags The existing set of bit flags.
+-- @param flagsToRemove One or more bit flags to remove, each as a separate argument.
+-- @returns The combined bit flags.
 function ____exports.removeFlag(self, flags, ...)
     local flagsToRemove = {...}
     local flagsAsInt = flags

package/functions/flying.lua

@@ -25,6 +25,14 @@ local FLYING_CHARACTERS = __TS__New(Set, {
 local FLYING_TRINKETS = __TS__New(Set, {TrinketType.BAT_WING, TrinketType.AZAZELS_STUMP})
 local FLYING_NULL_ITEMS = {NullItemID.REVERSE_SUN, NullItemID.SPIRIT_SHACKLES_SOUL, NullItemID.LOST_CURSE}
 local CONDITIONAL_FLYING_COLLECTIBLE_TYPES = {CollectibleType.BIBLE, CollectibleType.EMPTY_VESSEL, CollectibleType.ASTRAL_PROJECTION, CollectibleType.RECALL}
+--- Returns a set of all of the collectibles that grant flight. This is derived from collectibles
+-- that have `CacheFlag.FLYING` set in the "items.xml" file.
+-- 
+-- Collectibles that only grant flight conditionally are manually pruned. Collectibles such as Empty
+-- Vessel should be checked for via the `hasFlyingTemporaryEffect` function.
+-- 
+-- @param pruneConditionalItems Whether or not collectibles that only grant flight conditionally
+-- should be included in the set (like Empty Vessel).
 function ____exports.getFlyingCollectibles(self, pruneConditionalItems)
     local collectiblesWithFlyingCacheFlag = getCollectiblesForCacheFlag(nil, CacheFlag.FLYING)
     local collectiblesWithAllCacheFlag = getCollectiblesForCacheFlag(nil, CacheFlag.ALL)
@@ -36,6 +44,8 @@ function ____exports.getFlyingCollectibles(self, pruneConditionalItems)
     end
     return collectiblesWithFlyingCacheFlag
 end
+--- Returns a set of all of the trinkets that grant flight. (All trinkets that grant flight do so
+-- conditionally, like Bat Wing.)
 function ____exports.getFlyingTrinkets(self)
     return copySet(nil, FLYING_TRINKETS)
 end

package/functions/globals.lua

@@ -190,6 +190,10 @@ local DEFAULT_GLOBALS = __TS__New(Set, {
 })
 local LUA_DEBUG_ADDED_GLOBALS = __TS__New(Set, {"debug", "io", "os", "package"})
 local RACING_PLUS_SANDBOX_ADDED_GLOBALS = __TS__New(Set, {"sandboxTraceback", "sandboxGetTraceback", "getParentFunctionDescription"})
+--- Helper function to get a set containing all of the global variable names that are contained
+-- within the Isaac environment by default.
+-- 
+-- Returns a slightly different set depending on whether the "--luadebug" flag is enabled or not.
 function ____exports.getDefaultGlobals(self)
     local defaultGlobals = copySet(nil, DEFAULT_GLOBALS)
     if isLuaDebugEnabled(nil) then
@@ -198,6 +202,8 @@ function ____exports.getDefaultGlobals(self)
     addSetsToSet(nil, defaultGlobals, RACING_PLUS_SANDBOX_ADDED_GLOBALS)
     return defaultGlobals
 end
+--- Helper function to get an array of any added global variables in the Isaac Lua environment.
+-- Returns an array of key/value tuples.
 function ____exports.getNewGlobals(self)
     local defaultGlobals = ____exports.getDefaultGlobals(nil)
     local newGlobals = {}

package/functions/gridEntity.lua

@@ -44,12 +44,23 @@ function getAllGridEntities(self)
     end
     return gridEntities
 end
+--- Helper function to get the grid index of the top left wall. (This will depend on what the current
+-- room shape is.)
 function ____exports.getTopLeftWallGridIndex(self)
     local room = game:GetRoom()
     local roomShape = room:GetRoomShape()
     local topLeftWallGridIndex = ROOM_SHAPE_TO_TOP_LEFT_WALL_GRID_INDEX_MAP:get(roomShape)
     return topLeftWallGridIndex == nil and DEFAULT_TOP_LEFT_WALL_GRID_INDEX or topLeftWallGridIndex
 end
+--- Helper function to remove a grid entity simply by providing the grid entity object.
+-- 
+-- @param gridEntity The grid entity to remove.
+-- @param updateRoom Optional. Whether or not to update the room after the grid entity is removed.
+-- Default is true. This is generally a good idea because if the room is not
+-- updated, you will be unable to spawn another grid entity on the same tile until
+-- a frame has passed. However, doing this is expensive, since it involves a call
+-- to `Isaac.GetRoomEntities`, so set it to false if you need to invoke this
+-- function multiple times.
 function ____exports.removeGrid(self, gridEntity, updateRoom)
     if updateRoom == nil then
         updateRoom = true
@@ -61,6 +72,12 @@ function ____exports.removeGrid(self, gridEntity, updateRoom)
         roomUpdateSafe(nil)
     end
 end
+--- Helper function to spawn a grid entity with a specific variant.
+-- 
+-- Use this instead of the `Isaac.GridSpawn` method since it:
+-- - handles giving pits collision
+-- - removes existing grid entities on the same tile, if any
+-- - allows you to specify the grid index or the position
 function ____exports.spawnGridWithVariant(self, gridEntityType, variant, gridIndexOrPosition)
     local room = game:GetRoom()
     local ____isVector_result_0
@@ -105,6 +122,9 @@ local BREAKABLE_GRID_ENTITY_TYPES_VARIANTS_BY_EXPLOSIONS = __TS__New(
     Set,
     {(tostring(GridEntityType.STATUE) .. ".") .. tostring(StatueVariant.ANGEL)}
 )
+--- Helper function to convert the grid entity type found in a room XML file to the corresponding
+-- grid entity type and variant normally used by the game. For example, a rock is represented as
+-- 1000.0 in a room XML file, but `GridEntityType.ROCK` is equal to 2.
 function ____exports.convertXMLGridEntityType(self, gridEntityXMLType, gridEntityXMLVariant)
     local gridEntityArray = GRID_ENTITY_XML_MAP:get(gridEntityXMLType)
     if gridEntityArray == nil then
@@ -117,6 +137,11 @@ function ____exports.convertXMLGridEntityType(self, gridEntityXMLType, gridEntit
     end
     return {gridEntityType, gridEntityVariant}
 end
+--- Gets the entities that have a hitbox that overlaps with any part of the square that the grid
+-- entity is on.
+-- 
+-- Note that this function will not work properly in the PostNewRoom callback, since entities do not
+-- have collision yet in that callback.
 function ____exports.getCollidingEntitiesWithGridEntity(self, gridEntity)
     local gridEntityCollisionTopLeft = Vector(gridEntity.Position.X - DISTANCE_OF_GRID_TILE / 2, gridEntity.Position.Y - DISTANCE_OF_GRID_TILE / 2)
     local gridEntityCollisionBottomRight = Vector(gridEntity.Position.X + DISTANCE_OF_GRID_TILE / 2, gridEntity.Position.Y + DISTANCE_OF_GRID_TILE / 2)
@@ -132,6 +157,28 @@ function ____exports.getCollidingEntitiesWithGridEntity(self, gridEntity)
         ) end
     )
 end
+--- Helper function to get every grid entity in the current room.
+-- 
+-- Use this function with no arguments to get every grid entity, or specify a variadic amount of
+-- arguments to match specific grid entity types.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- for (const gridEntity of getGridEntities()) {
+--   print(gridEntity.GetType())
+-- }
+-- ```
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const rocks = getGridEntities(
+--   GridEntityType.ROCK,
+--   GridEntityType.BLOCK,
+--   GridEntityType.ROCK_TINTED,
+-- );
+-- ```
 function ____exports.getGridEntities(self, ...)
     local gridEntityTypes = {...}
     local gridEntities = getAllGridEntities(nil)
@@ -147,6 +194,11 @@ function ____exports.getGridEntities(self, ...)
         end
     )
 end
+--- Helper function to get a map of every grid entity in the current room. The indexes of the map are
+-- equal to the grid index. The values of the map are equal to the grid entities.
+-- 
+-- Use this function with no arguments to get every grid entity, or specify a variadic amount of
+-- arguments to match specific grid entity types.
 function ____exports.getGridEntitiesMap(self, ...)
     local gridEntities = ____exports.getGridEntities(nil, ...)
     local gridEntityMap = __TS__New(Map)
@@ -156,6 +208,7 @@ function ____exports.getGridEntitiesMap(self, ...)
     end
     return gridEntityMap
 end
+--- Helper function to return a string containing the grid entity's type and variant.
 function ____exports.getGridEntityID(self, gridEntity)
     local gridEntityType = gridEntity:GetType()
     local gridEntityVariant = gridEntity:GetVariant()
@@ -195,15 +248,36 @@ function ____exports.isGridEntityBreakableByExplosion(self, gridEntity)
     local gridEntityTypeVariant = (tostring(gridEntityType) .. ".") .. tostring(gridEntityVariant)
     return BREAKABLE_GRID_ENTITY_TYPES_BY_EXPLOSIONS:has(gridEntityType) or BREAKABLE_GRID_ENTITY_TYPES_VARIANTS_BY_EXPLOSIONS:has(gridEntityTypeVariant)
 end
+--- Helper function to see if the provided gridEntity is in its respective broken state. See the
+-- `GRID_ENTITY_TYPE_TO_BROKEN_STATE_MAP` constant for more details.
+-- 
+-- Note that in the case of `GridEntityType.LOCK` (11), the state will turn to being broken before
+-- the actual collision for the entity is removed.
 function ____exports.isGridEntityBroken(self, gridEntity)
     local gridEntityType = gridEntity:GetType()
     local brokenState = GRID_ENTITY_TYPE_TO_BROKEN_STATE_MAP:get(gridEntityType)
     return gridEntity.State == brokenState
 end
+--- Helper function to detect whether a given Void Portal is one that randomly spawns after a boss is
+-- defeated or is one that naturally spawns in the room after Hush. (This is determined by looking
+-- at the VarData of the entity.)
 function ____exports.isPostBossVoidPortal(self, gridEntity)
     local saveState = gridEntity:GetSaveState()
     return saveState.VarData == 1
 end
+--- Helper function to all grid entities in the room except for ones matching the grid entity types
+-- provided.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- removeAllGridEntitiesExceptFor(
+--   GridEntityType.WALL,
+--   GridEntityType.DOOR,
+-- );
+-- ```
+-- 
+-- @returns True if one or more grid entities were removed, false otherwise.
 function ____exports.removeAllGridExcept(self, ...)
     local gridEntityTypes = {...}
     local gridEntityTypeExceptions = __TS__New(Set, gridEntityTypes)
@@ -221,6 +295,20 @@ function ____exports.removeAllGridExcept(self, ...)
     end
     return removedOneOrMoreGridEntities
 end
+--- Helper function to remove all of the grid entities in the room that match the grid entity types
+-- provided.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- removeAllMatchingGridEntities(
+--   GridEntityType.ROCK,
+--   GridEntityType.BLOCK,
+--   GridEntityType.ROCK_TINTED,
+-- );
+-- ```
+-- 
+-- @returns True if one or more grid entities were removed, false otherwise.
 function ____exports.removeAllMatchingGridEntities(self, ...)
     local gridEntities = ____exports.getGridEntities(nil, ...)
     if #gridEntities == 0 then
@@ -232,10 +320,16 @@ function ____exports.removeAllMatchingGridEntities(self, ...)
     roomUpdateSafe(nil)
     return true
 end
+--- Helper function to make a grid entity invisible. This is accomplished by setting its sprite to an
+-- empty/missing PNG file.
+-- 
+-- For more information, see the documentation for the `clearSprite` helper function.
 function ____exports.setGridEntityInvisible(self, gridEntity)
     local sprite = gridEntity:GetSprite()
     clearSprite(nil, sprite)
 end
+--- Helper function to spawn a giant poop. This is performed by spawning each of the four quadrant
+-- grid entities in the appropriate positions.
 function ____exports.spawnGiantPoop(self, topLeftGridIndex)
     local room = game:GetRoom()
     local gridWidth = room:GetGridWidth()
@@ -247,9 +341,20 @@ function ____exports.spawnGiantPoop(self, topLeftGridIndex)
     ____exports.spawnGridWithVariant(nil, GridEntityType.POOP, PoopGridEntityVariant.GIGA_BOTTOM_LEFT, bottomLeftGridIndex)
     ____exports.spawnGridWithVariant(nil, GridEntityType.POOP, PoopGridEntityVariant.GIGA_BOTTOM_RIGHT, bottomRightGridIndex)
 end
+--- Helper function to spawn a grid entity.
+-- 
+-- This function assumes you want to give the grid entity a variant of 0. If you want to specify a
+-- variant, use the `spawnGridWithVariant` helper function instead.
+-- 
+-- Use this instead of the `Isaac.GridSpawn` method since it:
+-- - handles giving pits collision
+-- - removes existing grid entities on the same tile, if any
+-- - allows you to specify either the grid index or the position
 function ____exports.spawnGrid(self, gridEntityType, gridIndexOrPosition)
     return ____exports.spawnGridWithVariant(nil, gridEntityType, 0, gridIndexOrPosition)
 end
+--- Helper function to spawn a Void Portal. This is more complicated than simply spawning a trapdoor
+-- with the appropriate variant, as the game does not give it the correct sprite automatically.
 function ____exports.spawnVoidPortal(self, gridIndex)
     local voidPortal = ____exports.spawnGridWithVariant(nil, GridEntityType.TRAPDOOR, TrapdoorVariant.VOID_PORTAL, gridIndex)
     if voidPortal == nil then

package/functions/gridEntitySpecific.lua

@@ -7,6 +7,7 @@ local ____cachedClasses = require("cachedClasses")
 local game = ____cachedClasses.game
 local ____gridEntity = require("functions.gridEntity")
 local getGridEntities = ____gridEntity.getGridEntities
+--- Helper function to get all of the `GridEntityPit` in the room.
 function ____exports.getPits(self)
     local gridEntities = getGridEntities(nil)
     local pits = {}
@@ -18,6 +19,7 @@ function ____exports.getPits(self)
     end
     return pits
 end
+--- Helper function to get all of the `GridEntityPoop` in the room.
 function ____exports.getPoops(self)
     local gridEntities = getGridEntities(nil)
     local poops = {}
@@ -29,6 +31,7 @@ function ____exports.getPoops(self)
     end
     return poops
 end
+--- Helper function to get all of the `GridEntityPressurePlate` in the room.
 function ____exports.getPressurePlates(self)
     local gridEntities = getGridEntities(nil)
     local pressurePlates = {}
@@ -40,6 +43,7 @@ function ____exports.getPressurePlates(self)
     end
     return pressurePlates
 end
+--- Helper function to get all of the `GridEntityRock` in the room.
 function ____exports.getRocks(self)
     local gridEntities = getGridEntities(nil)
     local rocks = {}
@@ -51,6 +55,7 @@ function ____exports.getRocks(self)
     end
     return rocks
 end
+--- Helper function to get all of the `GridEntitySpikes` in the room.
 function ____exports.getSpikes(self)
     local gridEntities = getGridEntities(nil)
     local spikes = {}
@@ -62,6 +67,7 @@ function ____exports.getSpikes(self)
     end
     return spikes
 end
+--- Helper function to get all of the `GridEntityTNT` in the room.
 function ____exports.getTNT(self)
     local gridEntities = getGridEntities(nil)
     local tntArray = {}
@@ -73,6 +79,8 @@ function ____exports.getTNT(self)
     end
     return tntArray
 end
+--- Helper function to determine if all of the pressure plates in the current room are pushed.
+-- Returns true if there are no pressure plates in the room.
 function ____exports.isAllPressurePlatesPushed(self)
     local room = game:GetRoom()
     local hasPressurePlates = room:HasTriggerPressurePlates()

package/functions/input.lua

@@ -30,6 +30,7 @@ local MOVEMENT_ACTIONS = {ButtonAction.LEFT, ButtonAction.RIGHT, ButtonAction.UP
 local MOVEMENT_ACTIONS_SET = __TS__New(Set, MOVEMENT_ACTIONS)
 local SHOOTING_ACTIONS = {ButtonAction.SHOOT_LEFT, ButtonAction.SHOOT_RIGHT, ButtonAction.SHOOT_UP, ButtonAction.SHOOT_DOWN}
 local SHOOTING_ACTIONS_SET = __TS__New(Set, SHOOTING_ACTIONS)
+--- Helper function to get the enum name for the specified `Controller` value.
 function ____exports.controllerToString(self, controller)
     local key = Controller[controller]
     if key == nil then
@@ -43,6 +44,7 @@ end
 function ____exports.getShootActions(self)
     return copySet(nil, SHOOTING_ACTIONS_SET)
 end
+--- Iterates over all inputs to determine if a particular button is pressed (i.e. held down).
 function ____exports.isActionPressedOnAnyInput(self, buttonAction)
     local validInputs = erange(nil, MAX_NUM_INPUTS)
     return __TS__ArraySome(
@@ -50,6 +52,8 @@ function ____exports.isActionPressedOnAnyInput(self, buttonAction)
         function(____, input) return Input.IsActionPressed(buttonAction, input) end
     )
 end
+--- Iterates over all inputs to determine if a particular button is triggered (i.e. held down and
+-- then released).
 function ____exports.isActionTriggeredOnAnyInput(self, buttonAction)
     local validInputs = erange(nil, MAX_NUM_INPUTS)
     return __TS__ArraySome(
@@ -57,6 +61,10 @@ function ____exports.isActionTriggeredOnAnyInput(self, buttonAction)
         function(____, input) return Input.IsActionTriggered(buttonAction, input) end
     )
 end
+--- Helper function to see if a particular keyboard key is being pressed down by the player.
+-- 
+-- This function is variadic, meaning you can pass as many keyboard values as you want to check for.
+-- This function will return true if any of the values are pressed.
 function ____exports.isKeyboardPressed(self, ...)
     local keys = {...}
     return __TS__ArraySome(
@@ -64,6 +72,9 @@ function ____exports.isKeyboardPressed(self, ...)
         function(____, key) return Input.IsButtonPressed(key, ControllerIndex.KEYBOARD) end
     )
 end
+--- Helper function to check if one or more modifier keys are being pressed down on the keyboard.
+-- 
+-- A modifier key is defined as shift, control, alt, or Windows.
 function ____exports.isModifierKeyPressed(self)
     return ____exports.isKeyboardPressed(
         nil,

package/functions/isaacAPIClass.lua

@@ -1,6 +1,13 @@
 local ____lualib = require("lualib_bundle")
 local __TS__ArrayEvery = ____lualib.__TS__ArrayEvery
 local ____exports = {}
+--- Helper function to get the type of a class from the Isaac API. This is contained within the
+-- "__type" metatable key. In this context, the type of the class is equivalent to the name.
+-- 
+-- For example, a `Vector` class is has a type of "Vector".
+-- 
+-- Returns undefined if the object is not of type `userdata` or if the "__type" metatable key does
+-- not exist.
 function ____exports.getIsaacAPIClassType(self, object)
     local objectType = type(object)
     if objectType ~= "userdata" then
@@ -16,6 +23,9 @@ function ____exports.getIsaacAPIClassType(self, object)
     end
     return classType
 end
+--- Helper function to check if something is an instantiated class from the Isaac API. (All classes
+-- from the Isaac API have a type of "userdata" in Lua with a metatable key of "__type" equal to the
+-- name of the class.)
 function ____exports.isIsaacAPIClass(self, object)
     local isaacAPIClassType = ____exports.getIsaacAPIClassType(nil, object)
     return isaacAPIClassType ~= nil
@@ -24,6 +34,8 @@ function ____exports.isIsaacAPIClassOfType(self, object, classType)
     local isaacAPIClassType = ____exports.getIsaacAPIClassType(nil, object)
     return isaacAPIClassType == classType or isaacAPIClassType == "const " .. classType
 end
+--- Helper function to check if an instantiated Isaac API class is equal to another one of the same
+-- type. You must provide the list of keys to check for.
 function ____exports.isaacAPIClassEquals(self, object1, object2, keys)
     local table1 = object1
     local table2 = object2