isaacscript-common 2.3.2 → 3.0.0

package/functions/jsonHelpers.lua

@@ -8,6 +8,12 @@ end
 local function tryEncode(____table)
     return json.encode(____table)
 end
+--- Converts a JSON string to a Lua table.
+-- 
+-- In most cases, this function will be used for reading data from a "save#.dat" file. If decoding
+-- fails, it will return a blank Lua table instead of throwing an error. (This allows execution to
+-- continue in cases where users have no current save data or have manually removed their existing
+-- save data.)
 function ____exports.jsonDecode(self, jsonString)
     local ok, luaTableOrErrMsg = pcall(tryDecode, jsonString)
     if not ok then
@@ -16,6 +22,11 @@ function ____exports.jsonDecode(self, jsonString)
     end
     return luaTableOrErrMsg
 end
+--- Converts a Lua table to a JSON string.
+-- 
+-- In most cases, this function will be used for writing data to a "save#.dat" file. If encoding
+-- fails, it will throw an error to prevent writing a blank string or corrupted data to a user's
+-- "save#.dat" file.
 function ____exports.jsonEncode(self, ____table)
     local ok, jsonStringOrErrMsg = pcall(tryEncode, ____table)
     if not ok then

package/functions/jsonRoom.lua

@@ -66,6 +66,11 @@ function ____exports.getJSONRoomsOfSubType(self, jsonRooms, subType)
         end
     )
 end
+--- Helper function to get a random JSON room from an array of JSON rooms.
+-- 
+-- Note that this function does not simply choose a random element in the provided array; it will
+-- properly account for each room weight using the algorithm from:
+-- https://stackoverflow.com/questions/1761626/weighted-random-numbers
 function ____exports.getRandomJSONRoom(self, jsonRooms, seedOrRNG, verbose)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)

package/functions/kColor.lua

@@ -13,11 +13,17 @@ local getNumbersFromTable = ____table.getNumbersFromTable
 local tableHasKeys = ____table.tableHasKeys
 local ____utils = require("functions.utils")
 local ensureAllCases = ____utils.ensureAllCases
+--- Helper function to check if something is an instantiated KColor object.
 function ____exports.isKColor(self, object)
     return isIsaacAPIClassOfType(nil, object, OBJECT_NAME)
 end
 local KEYS = {"Red", "Green", "Blue", "Alpha"}
 OBJECT_NAME = "KColor"
+--- Helper function to copy a `KColor` object.
+-- 
+-- @param kColor The KColor object to copy. In the case of deserialization, this will actually be a
+-- Lua table instead of an instantiated KColor class.
+-- @param serializationType Default is `SerializationType.NONE`.
 function ____exports.copyKColor(self, kColor, serializationType)
     if serializationType == nil then
         serializationType = SerializationType.NONE
@@ -80,9 +86,12 @@ function ____exports.copyKColor(self, kColor, serializationType)
         end
     until true
 end
+--- Returns `KColor(1, 1, 1, 1)`.
 function ____exports.getDefaultKColor(self)
     return KColor(1, 1, 1, 1)
 end
+--- Used to determine is the given table is a serialized `KColor` object created by the save data
+-- manager and/or the `deepCopy` function.
 function ____exports.isSerializedKColor(self, object)
     local objectType = type(object)
     if objectType ~= "table" then

package/functions/language.lua

@@ -1,6 +1,11 @@
 local ____exports = {}
 local ____languageNames = require("objects.languageNames")
 local LANGUAGE_NAMES = ____languageNames.LANGUAGE_NAMES
+--- Helper function to convert the language abbreviation from `Options.Language` to the "full"
+-- language name.
+-- 
+-- For example, if the current language is set to Korean, `Options.Language` will be set to "kr",
+-- and this function will return "Korean".
 function ____exports.getLanguageName(self)
     local languageAbbreviation = Options.Language
     return LANGUAGE_NAMES[languageAbbreviation]

package/functions/log.lua

@@ -53,6 +53,7 @@ local ____utils = require("functions.utils")
 local printConsole = ____utils.printConsole
 local ____vector = require("functions.vector")
 local vectorToString = ____vector.vectorToString
+--- Helper function to prefix the name of the function and the line number before a debug message.
 function ____exports.getDebugPrependString(self, msg, numParentFunctions)
     if numParentFunctions == nil then
         numParentFunctions = 3
@@ -68,10 +69,15 @@ function ____exports.getDebugPrependString(self, msg, numParentFunctions)
     end
     return msg
 end
+--- Helper function to avoid typing out `Isaac.DebugString()`.
+-- 
+-- If you have the "--luadebug" launch flag turned on or the Racing+ sandbox enabled, then this
+-- function will also prepend the function name and the line number before the string.
 function ____exports.log(msg)
     local debugMsg = ____exports.getDebugPrependString(nil, msg)
     Isaac.DebugString(debugMsg)
 end
+--- Helper function for printing out every flag that is turned on. Useful when debugging.
 function ____exports.logFlags(flags, flagEnum, description)
     if description == nil then
         description = ""
@@ -111,6 +117,7 @@ end
 function ____exports.logColor(color)
     ____exports.log((((((((((((("Color: R" .. tostring(color.R)) .. ", G") .. tostring(color.G)) .. ", B") .. tostring(color.B)) .. ", A") .. tostring(color.A)) .. ", RO") .. tostring(color.RO)) .. ", BO") .. tostring(color.BO)) .. ", GO") .. tostring(color.GO))
 end
+--- Helper function for printing out every damage flag that is turned on. Useful when debugging.
 function ____exports.logDamageFlags(flags)
     ____exports.logFlags(flags, DamageFlag, "damage")
 end
@@ -140,6 +147,7 @@ function ____exports.logEffects(player)
         end
     )
 end
+--- Helper function for printing out every entity (or filtered entity) in the current room.
 function ____exports.logEntities(includeBackgroundEffects, entityTypeFilter)
     local msg = "Entities in the room"
     if entityTypeFilter ~= nil then
@@ -225,17 +233,23 @@ function ____exports.logEntities(includeBackgroundEffects, entityTypeFilter)
     end
     ____exports.log(msg)
 end
+--- Helper function for printing out every entity flag that is turned on. Useful when debugging.
 function ____exports.logEntityFlags(flags)
     ____exports.logFlags(flags, EntityFlag, "entity")
 end
 function ____exports.logEntityID(entity)
     ____exports.log((((("Entity: " .. tostring(entity.Type)) .. ".") .. tostring(entity.Variant)) .. ".") .. tostring(entity.SubType))
 end
+--- Helper function to log an error message and also print it to the console for better visibility.
+-- 
+-- This is useful in situations where using the `error` function would be dangerous (since it
+-- prevents all of the subsequent code in the callback from running).
 function ____exports.logError(msg)
     local errorMsg = "Error: " .. msg
     ____exports.log(errorMsg)
     printConsole(nil, errorMsg)
 end
+--- Helper function for printing out every game state flag that is turned on. Useful when debugging.
 function ____exports.logGameStateFlags()
     ____exports.log("Logging game state flags:")
     local gameStateFlagEntries = getEnumEntries(nil, GameStateFlag)
@@ -253,6 +267,7 @@ function ____exports.logGameStateFlags()
         ____exports.log("  n/a (no flags)")
     end
 end
+--- Helper function for printing out every grid entity (or filtered grid entity) in the current room.
 function ____exports.logGridEntities(includeWalls, gridEntityTypeFilter)
     local msg = "Grid entities in the room"
     if gridEntityTypeFilter ~= nil then
@@ -328,6 +343,7 @@ end
 function ____exports.logKColor(kColor)
     ____exports.log((((((("Color: R" .. tostring(kColor.Red)) .. ", G") .. tostring(kColor.Green)) .. ", B") .. tostring(kColor.Blue)) .. ", A") .. tostring(kColor.Alpha))
 end
+--- Helper function for printing out every level state flag that is turned on. Useful when debugging.
 function ____exports.logLevelStateFlags()
     local level = game:GetLevel()
     local levelStateFlagEntries = getEnumEntries(nil, LevelStateFlag)
@@ -372,9 +388,11 @@ function ____exports.logPlayerHealth(player)
     ____exports.log("  Blood charges: " .. tostring(playerHealth.bloodCharges))
     ____exports.log(("  Soul heart types: [" .. table.concat(playerHealth.soulHeartTypes, ",")) .. "]")
 end
+--- Helper function for printing out every projectile flag that is turned on. Useful when debugging.
 function ____exports.logProjectileFlags(flags)
     ____exports.logFlags(flags, ProjectileFlag, "projectile")
 end
+--- Helper function for logging information about the current room.
 function ____exports.logRoom()
     local roomGridIndex = getRoomGridIndex(nil)
     local roomListIndex = getRoomListIndex(nil)
@@ -389,6 +407,8 @@ function ____exports.logRoom()
     ____exports.log("Current room grid index: " .. tostring(roomGridIndex))
     ____exports.log("Current room list index: " .. tostring(roomListIndex))
 end
+--- Helper function for printing out every seed effect (i.e. Easter Egg) that is turned on for the
+-- particular run.
 function ____exports.logSeedEffects()
     local seeds = game:GetSeeds()
     local seedEffectEntries = getEnumEntries(nil, SeedEffect)
@@ -414,6 +434,7 @@ function ____exports.logSet(set)
     end
     ____exports.log("The size of the set was: " .. tostring(set.size))
 end
+--- Helper function for logging every sound effect that is currently playing.
 function ____exports.logSounds()
     local soundEffects = getEnumEntries(nil, SoundEffect)
     for ____, ____value in ipairs(soundEffects) do
@@ -455,12 +476,16 @@ function ____exports.logTable(____table, parentTables)
     end
     ____exports.log("The size of the table was: " .. tostring(numKeys))
 end
+--- Helper function for printing out every tear flag that is turned on. Useful when debugging.
 function ____exports.logTearFlags(flags)
     ____exports.logFlags(flags, TearFlag, "tear")
 end
+--- Helper function for printing out every use flag that is turned on. Useful when debugging.
 function ____exports.logUseFlags(flags)
     ____exports.logFlags(flags, UseFlag, "use")
 end
+--- Helper function to enumerate all of the properties of a "userdata" object (i.e. an object from
+-- the Isaac API).
 function ____exports.logUserdata(userdata)
     local userdataType = type(userdata)
     if userdataType ~= "userdata" then
@@ -487,6 +512,9 @@ function ____exports.logVector(vector, round)
     local vectorString = vectorToString(nil, vector, round)
     ____exports.log("Vector: " .. vectorString)
 end
+--- Converts every `isaacscript-common` function that begins with "log" to a global function.
+-- 
+-- This is useful when printing out variables from the in-game debug console.
 function ____exports.setLogFunctionsGlobal(self)
     local globals = _G
     globals.log = ____exports.log

package/functions/map.lua

@@ -8,6 +8,7 @@ local __TS__StringReplaceAll = ____lualib.__TS__StringReplaceAll
 local __TS__StringStartsWith = ____lualib.__TS__StringStartsWith
 local __TS__ArrayFilter = ____lualib.__TS__ArrayFilter
 local ____exports = {}
+--- Helper function to copy a map. (You can also use a Map constructor to accomplish this task.)
 function ____exports.copyMap(self, oldMap)
     local newMap = __TS__New(Map)
     for ____, ____value in __TS__Iterator(oldMap:entries()) do
@@ -17,6 +18,23 @@ function ____exports.copyMap(self, oldMap)
     end
     return newMap
 end
+--- Helper function to get the closest value from a map based on partial search text. For the
+-- purposes of this function, both search text and map keys are converted to lowercase before
+-- attempting to find a match.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const map = new <string, number>Map([
+--   ["foo", 123],
+--   ["bar", 456],
+-- ]);
+-- const searchText = "f";
+-- const match = getMapPartialMatch(map, searchText); // match is now equal to 123
+-- 
+-- @returns If a match was found, returns a tuple of the map key and value. If a match was not
+-- found, returns undefined.
+-- ```
 function ____exports.getMapPartialMatch(self, searchText, map)
     local keys = {__TS__Spread(map:keys())}
     __TS__ArraySort(keys)

package/functions/math.lua

@@ -3,6 +3,10 @@ local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitio
 local Direction = ____isaac_2Dtypescript_2Ddefinitions.Direction
 local ____direction = require("functions.direction")
 local directionToVector = ____direction.directionToVector
+--- Helper function to normalize an integer.
+-- 
+-- - If `x` is less than `min`, then it will be clamped to `min`.
+-- - If `x` is greater than `max`, then it will be clamped to `max`.
 function ____exports.clamp(self, x, min, max)
     return math.max(
         min,
@@ -13,6 +17,16 @@ function ____exports.getAngleDifference(self, angle1, angle2)
     local subtractedAngle = angle1 - angle2
     return (subtractedAngle + 180) % 360 - 180
 end
+--- Helper function to get an array of equidistant points on the circumference around a circle.
+-- Useful for equally distributing things in a circle pattern.
+-- 
+-- @param centerPos A position that represents the center of the center to get the points from.
+-- @param radius The radius of the circle.
+-- @param numPoints The number of points on the circumference of the circle to get.
+-- @param xMultiplier An optional multiplier to get the points around an oval. Default is 1.
+-- @param yMultiplier An optional multiplier to get the points around an oval. Default is 1.
+-- @param initialDirection By default, the first point on the circle will be on the top center, but
+-- this can be optionally changed by specifying this argument.
 function ____exports.getCircleDiscretizedPoints(self, centerPos, radius, numPoints, xMultiplier, yMultiplier, initialDirection)
     if xMultiplier == nil then
         xMultiplier = 1
@@ -39,9 +53,14 @@ function ____exports.getCircleDiscretizedPoints(self, centerPos, radius, numPoin
     end
     return positions
 end
+--- Helper function to check if a given position is within a given rectangle.
+-- 
+-- This is an inclusive check, meaning that it will return true if the position is on the border of
+-- the rectangle.
 function ____exports.inRectangle(self, position, topLeft, bottomRight)
     return position.X >= topLeft.X and position.X <= bottomRight.X and position.Y >= topLeft.Y and position.Y <= bottomRight.Y
 end
+--- From: https://www.geeksforgeeks.org/check-if-any-point-overlaps-the-given-circle-and-rectangle/
 function ____exports.isCircleIntersectingRectangle(self, circleCenter, circleRadius, rectangleTopLeft, rectangleBottomRight)
     local nearestX = math.max(
         rectangleTopLeft.X,
@@ -67,6 +86,11 @@ end
 function ____exports.lerpAngleDegrees(self, aStart, aEnd, percent)
     return aStart + ____exports.getAngleDifference(nil, aStart, aEnd) * percent
 end
+--- If rounding fails, this function returns 0.
+-- From: http://lua-users.org/wiki/SimpleRound
+-- 
+-- @param num The number to round.
+-- @param numDecimalPlaces Default is 0.
 function ____exports.round(self, num, numDecimalPlaces)
     if numDecimalPlaces == nil then
         numDecimalPlaces = 0
@@ -77,6 +101,8 @@ function ____exports.round(self, num, numDecimalPlaces)
     ))
     return roundedNum == nil and 0 or roundedNum
 end
+---
+-- @returns 1 if n is positive, -1 if n is negative, or 0 if n is 0.
 function ____exports.sign(self, n)
     if n > 0 then
         return 1

package/functions/npc.lua

@@ -27,6 +27,8 @@ local getFilteredNewEntities = ____entity.getFilteredNewEntities
 local ____entitySpecific = require("functions.entitySpecific")
 local getNPCs = ____entitySpecific.getNPCs
 local getProjectiles = ____entitySpecific.getProjectiles
+--- Checks for specific NPCs that have "CanShutDoors" set to true naturally by the game, but should
+-- not actually keep the doors closed (like Death's scythes).
 function ____exports.isAliveExceptionNPC(self, npc)
     local entityTypeVariant = (tostring(npc.Type) .. ".") .. tostring(npc.Variant)
     if NON_ALIVE_NPCS_TYPE_VARIANT:has(entityTypeVariant) then
@@ -44,9 +46,16 @@ function ____exports.isAliveExceptionNPC(self, npc)
     end
     return false
 end
+--- Helper function to detect the custom death state of an Eggy. Eggies are never actually marked
+-- dead by the game. Instead, when Eggies take fatal damage, they go into NpcState.STATE_SUICIDE and
+-- spawn 14 Swarm Spiders while their StateFrame ticks upwards.
 function ____exports.isDyingEggyWithNoSpidersLeft(self, npc)
     return npc.State == NpcState.SUICIDE and npc.StateFrame >= EGGY_STATE_FRAME_OF_FINAL_SPIDER
 end
+--- Helper function to detect the custom death state of a Rag Man Ragling. When Rag Man Raglings die,
+-- they turn into a patch on the ground and can be revived by Rag Man at a later time. This causes
+-- them to show up as an "alive" enemy, so they should usually be filtered out of lists of alive
+-- enemies.
 function ____exports.isRaglingDeathPatch(self, npc)
     return npc.Type == EntityType.RAGLING and npc.Variant == RaglingVariant.RAG_MANS_RAGLING and npc.State == NpcState.SPECIAL
 end
@@ -73,6 +82,17 @@ NON_ALIVE_NPCS_TYPE_VARIANT_SUBTYPE = __TS__New(
         (((tostring(EntityType.MOTHER) .. ".") .. tostring(MotherVariant.MOTHER_1)) .. ".") .. tostring(MotherSubType.PHASE_2)
     }
 )
+--- Helper function to make an NPC fire a projectile. Returns the fired projectile. Use this function
+-- instead of the `EntityNPC.FireProjectiles` method, since that returns void.
+-- 
+-- @param npc The NPC to fire the projectile from.
+-- @param position The staring position of the projectile.
+-- @param velocity The starting velocity of the projectile.
+-- @param projectilesMode The mode of the projectile. Optional. Default is
+-- `ProjectilesMode.ONE_PROJECTILE`.
+-- @param projectileParams The parameters of the projectile. Optional. Default is
+-- `ProjectileParams()`.
+-- @returns The fired projectile.
 function ____exports.fireProjectiles(self, npc, position, velocity, projectilesMode, projectileParams)
     if projectilesMode == nil then
         projectilesMode = ProjectilesMode.ONE_PROJECTILE
@@ -85,6 +105,10 @@ function ____exports.fireProjectiles(self, npc, position, velocity, projectilesM
     local newProjectiles = getProjectiles(nil, projectileParams.Variant)
     return getFilteredNewEntities(nil, oldProjectiles, newProjectiles)
 end
+--- Helper function to get all of the non-dead NPCs in the room.
+-- 
+-- This function will not include NPCs on an internal blacklist, such as Death's scythes or Big Horn
+-- holes.
 function ____exports.getAliveNPCs(self, matchingEntityType, matchingVariant, matchingSubType, ignoreFriendly)
     if ignoreFriendly == nil then
         ignoreFriendly = false

package/functions/pickupVariants.d.ts

@@ -1,23 +1,23 @@
 /// <reference types="isaac-typescript-definitions" />
-/** For PickupVariant.HEART (10) */
+/** For `PickupVariant.HEART` (10) */
 export declare function isHeart(pickup: EntityPickup): pickup is EntityPickupHeart;
-/** For PickupVariant.COIN (20) */
+/** For `PickupVariant.COIN` (20) */
 export declare function isCoin(pickup: EntityPickup): pickup is EntityPickupCoin;
-/** For PickupVariant.KEY (30) */
+/** For `PickupVariant.KEY` (30) */
 export declare function isKey(pickup: EntityPickup): pickup is EntityPickupKey;
-/** For PickupVariant.BOMB (40) */
+/** For `PickupVariant.BOMB` (40) */
 export declare function isBomb(pickup: EntityPickup): pickup is EntityPickupBomb;
-/** For PickupVariant.POOP (42) */
+/** For `PickupVariant.POOP` (42) */
 export declare function isPoop(pickup: EntityPickup): pickup is EntityPickupPoop;
-/** For PickupVariant.POOP (42) */
+/** For `PickupVariant.SACK` (69) */
 export declare function isSack(pickup: EntityPickup): pickup is EntityPickupSack;
-/** For PickupVariant.PILL (70) */
+/** For `PickupVariant.PILL` (70) */
 export declare function isPill(pickup: EntityPickup): pickup is EntityPickupPill;
-/** For PickupVariant.LIL_BATTERY (90) */
+/** For `PickupVariant.LIL_BATTERY` (90) */
 export declare function isBattery(pickup: EntityPickup): pickup is EntityPickupBattery;
-/** For PickupVariant.COLLECTIBLE (100) */
+/** For `PickupVariant.COLLECTIBLE` (100) */
 export declare function isCollectible(pickup: EntityPickup): pickup is EntityPickupCollectible;
-/** For PickupVariant.TAROT_CARD (300) */
+/** For `PickupVariant.TAROT_CARD` (300) */
 export declare function isCardPickup(pickup: EntityPickup): pickup is EntityPickupCard;
-/** For PickupVariant.TRINKET (350) */
+/** For `PickupVariant.TRINKET` (350) */
 export declare function isTrinket(pickup: EntityPickup): pickup is EntityPickupTrinket;

package/functions/pickupVariants.lua

@@ -1,36 +1,47 @@
 local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local PickupVariant = ____isaac_2Dtypescript_2Ddefinitions.PickupVariant
+--- For `PickupVariant.HEART` (10)
 function ____exports.isHeart(self, pickup)
     return pickup.Variant == PickupVariant.HEART
 end
+--- For `PickupVariant.COIN` (20)
 function ____exports.isCoin(self, pickup)
     return pickup.Variant == PickupVariant.COIN
 end
+--- For `PickupVariant.KEY` (30)
 function ____exports.isKey(self, pickup)
     return pickup.Variant == PickupVariant.KEY
 end
+--- For `PickupVariant.BOMB` (40)
 function ____exports.isBomb(self, pickup)
     return pickup.Variant == PickupVariant.BOMB
 end
+--- For `PickupVariant.POOP` (42)
 function ____exports.isPoop(self, pickup)
     return pickup.Variant == PickupVariant.POOP
 end
+--- For `PickupVariant.SACK` (69)
 function ____exports.isSack(self, pickup)
     return pickup.Variant == PickupVariant.SACK
 end
+--- For `PickupVariant.PILL` (70)
 function ____exports.isPill(self, pickup)
     return pickup.Variant == PickupVariant.PILL
 end
+--- For `PickupVariant.LIL_BATTERY` (90)
 function ____exports.isBattery(self, pickup)
     return pickup.Variant == PickupVariant.LIL_BATTERY
 end
+--- For `PickupVariant.COLLECTIBLE` (100)
 function ____exports.isCollectible(self, pickup)
     return pickup.Variant == PickupVariant.COLLECTIBLE
 end
+--- For `PickupVariant.TAROT_CARD` (300)
 function ____exports.isCardPickup(self, pickup)
     return pickup.Variant == PickupVariant.TAROT_CARD
 end
+--- For `PickupVariant.TRINKET` (350)
 function ____exports.isTrinket(self, pickup)
     return pickup.Variant == PickupVariant.TRINKET
 end

package/functions/pickups.lua

@@ -18,52 +18,62 @@ local removeAllPickups = ____entitySpecific.removeAllPickups
 local spawnPickup = ____entitySpecific.spawnPickup
 local ____pickupVariants = require("functions.pickupVariants")
 local isHeart = ____pickupVariants.isHeart
+--- Helper function to get all of the battery entities in the room.
 function ____exports.getBatteries(self, matchingSubType)
     if matchingSubType == nil then
         matchingSubType = -1
     end
     return getPickups(nil, PickupVariant.LIL_BATTERY, matchingSubType)
 end
+--- Helper function to get all of the card entities in the room.
 function ____exports.getCards(self, matchingSubType)
     if matchingSubType == nil then
         matchingSubType = -1
     end
     return getPickups(nil, PickupVariant.TAROT_CARD, matchingSubType)
 end
+--- Helper function to get the corresponding coin amount from a `CoinSubType`. Returns 1 for modded
+-- sub-types.
 function ____exports.getCoinValue(self, coinSubType)
     local value = COIN_SUBTYPE_TO_VALUE[coinSubType]
     return value == nil and DEFAULT_COIN_VALUE or value
 end
+--- Helper function to get all of the coin pickup entities in the room.
 function ____exports.getCoins(self, matchingSubType)
     if matchingSubType == nil then
         matchingSubType = -1
     end
     return getPickups(nil, PickupVariant.COIN, matchingSubType)
 end
+--- Helper function to get all of the collectible entities in the room.
 function ____exports.getCollectibles(self, matchingSubType)
     if matchingSubType == nil then
         matchingSubType = -1
     end
     return getPickups(nil, PickupVariant.COLLECTIBLE, matchingSubType)
 end
+--- Helper function to get all of the heart pickup entities in the room.
 function ____exports.getHearts(self, matchingSubType)
     if matchingSubType == nil then
         matchingSubType = -1
     end
     return getPickups(nil, PickupVariant.HEART, matchingSubType)
 end
+--- Helper function to get all of the key pickup entities in the room.
 function ____exports.getKeys(self, matchingSubType)
     if matchingSubType == nil then
         matchingSubType = -1
     end
     return getPickups(nil, PickupVariant.KEY, matchingSubType)
 end
+--- Helper function to get all of the pill entities in the room.
 function ____exports.getPills(self, matchingSubType)
     if matchingSubType == nil then
         matchingSubType = -1
     end
     return getPickups(nil, PickupVariant.PILL, matchingSubType)
 end
+--- Helper function to get all of the red heart pickup entities in the room.
 function ____exports.getRedHearts(self)
     local hearts = ____exports.getHearts(nil)
     return __TS__ArrayFilter(
@@ -71,12 +81,14 @@ function ____exports.getRedHearts(self)
         function(____, heart) return RED_HEART_SUB_TYPES_SET:has(heart.SubType) end
     )
 end
+--- Helper function to get all of the sack (i.e. grab bag) entities in the room.
 function ____exports.getSacks(self, matchingSubType)
     if matchingSubType == nil then
         matchingSubType = -1
     end
     return getPickups(nil, PickupVariant.SACK, matchingSubType)
 end
+--- Helper function to get all of the trinket entities in the room.
 function ____exports.getTrinkets(self, matchingSubType)
     if matchingSubType == nil then
         matchingSubType = -1
@@ -89,33 +101,81 @@ end
 function ____exports.isRedHeart(self, pickup)
     return isHeart(nil, pickup) and RED_HEART_SUB_TYPES_SET:has(pickup.SubType)
 end
+--- Helper function to remove all of the batteries in the room.
+-- 
+-- @param batterySubType Optional. If specified, will only remove cards that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of cards.
+-- @returns True if one or more cards were removed, false otherwise.
 function ____exports.removeAllBatteries(self, batterySubType, cap)
     return removeAllPickups(nil, PickupVariant.LIL_BATTERY, batterySubType, cap)
 end
+--- Helper function to remove all of the cards in the room.
+-- 
+-- @param card Optional. If specified, will only remove cards that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of cards.
+-- @returns True if one or more cards were removed, false otherwise.
 function ____exports.removeAllCards(self, card, cap)
     return removeAllPickups(nil, PickupVariant.TAROT_CARD, card, cap)
 end
+--- Helper function to remove all of the coins in the room.
+-- 
+-- @param coinSubType Optional. If specified, will only remove coins that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of coins.
+-- @returns True if one or more coins were removed, false otherwise.
 function ____exports.removeAllCoins(self, coinSubType, cap)
     return removeAllPickups(nil, PickupVariant.COIN, coinSubType, cap)
 end
+--- Helper function to remove all of the collectibles in the room.
+-- 
+-- @param collectibleType Optional. If specified, will only remove collectibles that match this
+-- collectible type.
+-- @param cap Optional. If specified, will only remove the given amount of collectibles.
+-- @returns True if one or more collectibles were removed, false otherwise.
 function ____exports.removeAllCollectibles(self, collectibleType, cap)
     return removeAllPickups(nil, PickupVariant.COLLECTIBLE, collectibleType, cap)
 end
+--- Helper function to remove all of the hearts in the room.
+-- 
+-- @param heartSubType Optional. If specified, will only remove hearts that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of hearts.
+-- @returns True if one or more hearts were removed, false otherwise.
 function ____exports.removeAllHearts(self, heartSubType, cap)
     return removeAllPickups(nil, PickupVariant.HEART, heartSubType, cap)
 end
+--- Helper function to remove all of the keys in the room.
+-- 
+-- @param keySubType Optional. If specified, will only remove keys that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of keys.
+-- @returns True if one or more keys were removed, false otherwise.
 function ____exports.removeAllKeys(self, keySubType, cap)
     return removeAllPickups(nil, PickupVariant.KEY, keySubType, cap)
 end
+--- Helper function to remove all of the pills in the room.
+-- 
+-- @param pillColor Optional. If specified, will only remove pills that match this color.
+-- @param cap Optional. If specified, will only remove the given amount of pills.
+-- @returns True if one or more pills were removed, false otherwise.
 function ____exports.removeAllPills(self, pillColor, cap)
     return removeAllPickups(nil, PickupVariant.PILL, pillColor, cap)
 end
+--- Helper function to remove all of the sacks (i.e. grab bags) in the room.
+-- 
+-- @param sackSubType Optional. If specified, will only remove sacks that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of trinkets.
+-- @returns True if one or more trinkets were removed, false otherwise.
 function ____exports.removeAllSacks(self, sackSubType, cap)
     return removeAllPickups(nil, PickupVariant.TRINKET, sackSubType, cap)
 end
+--- Helper function to remove all of the trinkets in the room.
+-- 
+-- @param trinketType Optional. If specified, will only remove trinkets that match this trinket
+-- type.
+-- @param cap Optional. If specified, will only remove the given amount of trinkets.
+-- @returns True if one or more trinkets were removed, false otherwise.
 function ____exports.removeAllTrinkets(self, trinketType, cap)
     return removeAllPickups(nil, PickupVariant.TRINKET, trinketType, cap)
 end
+--- Helper function to spawn a `EntityType.PICKUP` (5) with variant `PickupVariant.LIL_BATTERY` (90).
 function ____exports.spawnBattery(self, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -152,6 +212,7 @@ function ____exports.spawnBatteryWithSeed(self, subType, position, seed, velocit
         seed
     )
 end
+--- Helper function to spawn a `EntityType.PICKUP` (5) with variant `PickupVariant.TAROT_CARD` (300).
 function ____exports.spawnCard(self, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -188,6 +249,7 @@ function ____exports.spawnCardWithSeed(self, subType, position, seed, velocity,
         seed
     )
 end
+--- Helper function to spawn a `EntityType.PICKUP` (5) with variant `PickupVariant.COIN` (20).
 function ____exports.spawnCoin(self, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -224,6 +286,7 @@ function ____exports.spawnCoinWithSeed(self, subType, position, seed, velocity,
         seed
     )
 end
+--- Helper function to spawn a `EntityType.PICKUP` (5) with variant `PickupVariant.HEART` (10).
 function ____exports.spawnHeart(self, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -260,6 +323,7 @@ function ____exports.spawnHeartWithSeed(self, subType, position, seed, velocity,
         seed
     )
 end
+--- Helper function to spawn a `EntityType.PICKUP` (5) with variant `PickupVariant.KEY` (30).
 function ____exports.spawnKey(self, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -296,6 +360,7 @@ function ____exports.spawnKeyWithSeed(self, subType, position, seed, velocity, s
         seed
     )
 end
+--- Helper function to spawn a `EntityType.PICKUP` (5) with variant `PickupVariant.PILL` (70).
 function ____exports.spawnPill(self, pillColor, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -332,6 +397,7 @@ function ____exports.spawnPillWithSeed(self, subType, position, seed, velocity,
         seed
     )
 end
+--- Helper function to spawn a `EntityType.PICKUP` (5) with variant `PickupVariant.SACK` (69).
 function ____exports.spawnSack(self, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -368,6 +434,7 @@ function ____exports.spawnSackWithSeed(self, subType, position, seed, velocity,
         seed
     )
 end
+--- Helper function to spawn a `EntityType.PICKUP` (5) with variant `PickupVariant.TRINKET` (350).
 function ____exports.spawnTrinket(self, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero