isaacscript-common 2.3.2 → 3.1.1

package/features/sirenHelpers.lua

@@ -50,10 +50,18 @@ function getSirenHelper(self, familiar)
 end
 local FEATURE_NAME = "siren helpers"
 v = {run = {familiarBlacklist = {}}}
+---
+-- @internal
 function ____exports.sirenHelpersInit(self, mod)
     saveDataManager(nil, "sirenHelpers", v)
     mod:AddCallback(ModCallback.POST_NPC_INIT, postNPCInitSirenHelper, EntityType.SIREN_HELPER)
 end
+--- Blacklists a familiar from being stolen by The Siren boss. This should be called once at the
+-- beginning of every run.
+-- 
+-- @param familiarVariant The familiar variant to blacklist.
+-- @param familiarSubType The sub-type to blacklist. Optional. The default is to blacklist all
+-- sub-types of the given variant.
 function ____exports.setFamiliarNoSirenSteal(self, familiarVariant, familiarSubType)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     if blacklistEntryExists(nil, familiarVariant, familiarSubType) then
@@ -62,6 +70,11 @@ function ____exports.setFamiliarNoSirenSteal(self, familiarVariant, familiarSubT
     local ____v_run_familiarBlacklist_0 = v.run.familiarBlacklist
     ____v_run_familiarBlacklist_0[#____v_run_familiarBlacklist_0 + 1] = {familiarVariant, familiarSubType}
 end
+--- Helper function to check if the Siren boss has stolen a familiar. Some familiars may need to
+-- behave differently when under The Siren's control (e.g. if they auto-target enemies).
+-- 
+-- @param familiar The familiar to be checked.
+-- @returns Returns whether the familiar has been stolen by The Siren.
 function ____exports.hasSirenStolenFamiliar(self, familiar)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     return getSirenHelper(nil, familiar) ~= nil

package/features/taintedLazarusPlayers.lua

@@ -49,6 +49,8 @@ v = {run = {
     queuedDeadTaintedLazarus = {},
     subPlayerMap = __TS__New(Map)
 }}
+---
+-- @internal
 function ____exports.taintedLazarusPlayersInit(self, mod)
     saveDataManager(
         nil,
@@ -58,6 +60,15 @@ function ____exports.taintedLazarusPlayersInit(self, mod)
     )
     mod:AddCallback(ModCallback.POST_PLAYER_INIT, postPlayerInit)
 end
+--- Helper function to get the other version of Tainted Lazarus.
+-- 
+-- - On Tainted Lazarus, returns the player object for Dead Tainted Lazarus.
+-- - On Dead Tainted Lazarus, returns the player object for Tainted Lazarus.
+-- - Returns undefined if player object retrieval failed for any reason.
+-- 
+-- If you call the `EntityPlayer.Exists` method on the returned object, it will return false.
+-- However, you can still call the other methods like you normally would (e.g.
+-- `EntityPlayer.AddCollectible`).
 function ____exports.getTaintedLazarusSubPlayer(self, player)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     local ptrHash = GetPtrHash(player)

package/featuresInitialized.lua

@@ -1,13 +1,19 @@
 local ____exports = {}
 local featuresInitialized = false
+---
+-- @internal
 function ____exports.areFeaturesInitialized(self)
     return featuresInitialized
 end
+---
+-- @internal
 function ____exports.errorIfFeaturesNotInitialized(self, featureName)
     if not ____exports.areFeaturesInitialized(nil) then
         error(("The " .. featureName) .. " is not initialized. You must first upgrade your mod object by calling the \"upgradeMod\" function.")
     end
 end
+---
+-- @internal
 function ____exports.setFeaturesInitialized(self)
     featuresInitialized = true
 end

package/functions/array.d.ts

@@ -1,4 +1,6 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 /**
  * Helper function for determining if two arrays contain the exact same elements. Note that this
  * only performs a shallow comparison.

package/functions/array.lua

@@ -20,6 +20,11 @@ local newRNG = ____rng.newRNG
 local ____utils = require("functions.utils")
 local erange = ____utils.erange
 local ____repeat = ____utils["repeat"]
+--- Helper function to get a random index from the provided array.
+-- 
+-- @param array The array to get the index 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()`.
 function ____exports.getRandomArrayIndex(self, array, seedOrRNG)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -29,6 +34,13 @@ function ____exports.getRandomArrayIndex(self, array, seedOrRNG)
     end
     return getRandomInt(nil, 0, #array - 1, seedOrRNG)
 end
+--- Shuffles the provided array in-place using the Fisher-Yates algorithm.
+-- 
+-- From: https://stackoverflow.com/questions/2450954/how-to-randomize-shuffle-a-javascript-array
+-- 
+-- @param array The array to shuffle.
+-- @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.shuffleArrayInPlace(self, array, seedOrRNG)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -44,6 +56,8 @@ function ____exports.shuffleArrayInPlace(self, array, seedOrRNG)
         array[randomIndex + 1] = ____temp_0[2]
     end
 end
+--- Helper function for determining if two arrays contain the exact same elements. Note that this
+-- only performs a shallow comparison.
 function ____exports.arrayEquals(self, array1, array2)
     if #array1 ~= #array2 then
         return false
@@ -56,6 +70,11 @@ function ____exports.arrayEquals(self, array1, array2)
         end
     )
 end
+--- Shallow copies and removes the specified element(s) from the array. Returns the copied array. If
+-- the specified element(s) are not found in the array, it will simply return a shallow copy of the
+-- array.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to remove N elements.
 function ____exports.arrayRemove(self, originalArray, ...)
     local elementsToRemove = {...}
     local elementsToRemoveSet = __TS__New(Set, elementsToRemove)
@@ -67,6 +86,10 @@ function ____exports.arrayRemove(self, originalArray, ...)
     end
     return array
 end
+--- Removes the specified element(s) from the array. If the specified element(s) are not found in the
+-- array, this function will do nothing. Returns whether or not one or more elements were removed.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to remove N elements.
 function ____exports.arrayRemoveInPlace(self, array, ...)
     local elementsToRemove = {...}
     local removedOneOrMoreElements = false
@@ -79,6 +102,11 @@ function ____exports.arrayRemoveInPlace(self, array, ...)
     end
     return removedOneOrMoreElements
 end
+--- Shallow copies and removes the elements at the specified indexes from the array. Returns the
+-- copied array. If the specified indexes are not found in the array, it will simply return a
+-- shallow copy of the array.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to remove N elements.
 function ____exports.arrayRemoveIndex(self, originalArray, ...)
     local indexesToRemove = {...}
     local indexesToRemoveSet = __TS__New(Set, indexesToRemove)
@@ -93,6 +121,11 @@ function ____exports.arrayRemoveIndex(self, originalArray, ...)
     )
     return array
 end
+--- Removes the elements at the specified indexes from the array. If the specified indexes are not
+-- found in the array, this function will do nothing. Returns whether or not one or more elements
+-- were removed.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to remove N elements.
 function ____exports.arrayRemoveIndexInPlace(self, array, ...)
     local indexesToRemove = {...}
     local legalIndexes = __TS__ArrayFilter(
@@ -123,6 +156,11 @@ function ____exports.arrayToString(self, array)
     local commaSeparatedStrings = table.concat(strings, ", ")
     return ("[" .. commaSeparatedStrings) .. "]"
 end
+--- Helper function to combine two or more arrays. Returns a new array that is the composition of all
+-- of the specified arrays.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to combine N arrays. Note
+-- that this will only perform a shallow copy of the array elements.
 function ____exports.combineArrays(self, ...)
     local arrays = {...}
     local elements = {}
@@ -133,6 +171,11 @@ function ____exports.combineArrays(self, ...)
     end
     return elements
 end
+--- Helper function to perform a shallow copy.
+-- 
+-- @param oldArray The array to copy.
+-- @param numElements Optional. If specified, will only copy the first N elements. By default, the
+-- entire array will be copied.
 function ____exports.copyArray(self, oldArray, numElements)
     if numElements == nil then
         numElements = #oldArray
@@ -153,12 +196,24 @@ end
 function ____exports.emptyArray(self, array)
     __TS__ArraySplice(array, 0, #array)
 end
+--- Helper function to get an array containing the indexes of an array.
+-- 
+-- For example, an array of `["Apple", "Banana"]` would return an array of `[0, 1]`.
 function ____exports.getArrayIndexes(self, array)
     return erange(nil, #array)
 end
+--- Helper function to return the last element of an array.
+-- 
+-- If the array is empty, this will return undefined.
 function ____exports.getLastElement(self, array)
     return array[#array]
 end
+--- Helper function to get a random element from the provided array.
+-- 
+-- @param array The array to get an element from.
+-- @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+-- `RNG.Next` method will be called. Default is `getRandomSeed()`.
+-- @param exceptions Optional. An array of elements to skip over if selected.
 function ____exports.getRandomArrayElement(self, array, seedOrRNG, exceptions)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -181,6 +236,13 @@ function ____exports.getRandomArrayElement(self, array, seedOrRNG, exceptions)
     end
     return randomElement
 end
+--- Helper function to get a random element from the provided array. Once the random element is
+-- decided, it is then removed from the array (in-place).
+-- 
+-- @param array The array to get an element from.
+-- @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+-- `RNG.Next` method will be called. Default is `getRandomSeed()`.
+-- @param exceptions Optional. An array of elements to skip over if selected.
 function ____exports.getRandomArrayElementAndRemove(self, array, seedOrRNG, exceptions)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -192,6 +254,13 @@ function ____exports.getRandomArrayElementAndRemove(self, array, seedOrRNG, exce
     ____exports.arrayRemoveInPlace(nil, array, randomArrayElement)
     return randomArrayElement
 end
+--- Initializes an array with all elements containing the specified default value.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const playerTransformations = initArray(false, PlayerForm.NUM_PLAYER_FORMS - 1);
+-- ```
 function ____exports.initArray(self, defaultValue, size)
     local array = {}
     ____repeat(
@@ -203,6 +272,11 @@ function ____exports.initArray(self, defaultValue, size)
     )
     return array
 end
+--- Since Lua uses tables for every non-primitive data structure, it is non-trivial to determine if a
+-- particular table is being used as an array. `isArray` returns true if:
+-- 
+-- - the table contains all numerical indexes that are contiguous, starting at 1
+-- - the table has no keys (i.e. an "empty" table)
 function ____exports.isArray(self, object)
     if type(object) ~= "table" then
         return false
@@ -234,6 +308,9 @@ function ____exports.isArray(self, object)
     end
     return true
 end
+--- Helper function to see if every element in the array is N + 1.
+-- 
+-- For example, `[2, 3, 4]` would return true, and `[2, 3, 5]` would return false.
 function ____exports.isArrayContiguous(self, array)
     local lastValue
     for ____, element in ipairs(array) do
@@ -246,12 +323,20 @@ function ____exports.isArrayContiguous(self, array)
     end
     return true
 end
+--- Checks if an array is in the provided 2-dimensional array.
 function ____exports.isArrayInArray(self, arrayToMatch, parentArray)
     return __TS__ArraySome(
         parentArray,
         function(____, element) return ____exports.arrayEquals(nil, element, arrayToMatch) end
     )
 end
+--- Shallow copies and shuffles the array using the Fisher-Yates algorithm. Returns the copied array.
+-- 
+-- From: https://stackoverflow.com/questions/2450954/how-to-randomize-shuffle-a-javascript-array
+-- 
+-- @param originalArray The array to shuffle.
+-- @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.shuffleArray(self, originalArray, seedOrRNG)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)

package/functions/benchmark.lua

@@ -3,6 +3,12 @@ local __TS__ArrayForEach = ____lualib.__TS__ArrayForEach
 local ____exports = {}
 local ____log = require("functions.log")
 local log = ____log.log
+--- Helper function to benchmark the performance of a function.
+-- 
+-- This function is variadic, which means that you can supply as many as you want to benchmark.
+-- 
+-- @returns An array containing the average time in milliseconds for each function. (This will also
+-- be printed to the log.)
 function ____exports.benchmark(self, numTrials, ...)
     local functions = {...}
     log(((("Benchmarking " .. tostring(#functions)) .. " function(s) with ") .. tostring(numTrials)) .. " trials.")

package/functions/bombs.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="isaac-typescript-definitions" />
+/** Helper function to find out how large a bomb explosion is based on the damage inflicted. */
+export declare function getBombRadiusFromDamage(damage: float): float;

package/functions/bombs.lua

@@ -0,0 +1,12 @@
+local ____exports = {}
+--- Helper function to find out how large a bomb explosion is based on the damage inflicted.
+function ____exports.getBombRadiusFromDamage(self, damage)
+    if damage > 175 then
+        return 105
+    end
+    if damage <= 140 then
+        return 75
+    end
+    return 90
+end
+return ____exports

package/functions/boss.lua

@@ -63,6 +63,10 @@ local BOSSES_THAT_REQUIRE_MULTIPLE_SPAWNS = __TS__New(Set, {
     EntityType.TURDLET
 })
 DEFAULT_BOSS_MULTI_SEGMENTS = 4
+--- Helper function to get all of the non-dead bosses in the room.
+-- 
+-- This function will not include bosses on an internal blacklist, such as Death's scythes or Big
+-- Horn holes.
 function ____exports.getAliveBosses(self, matchingEntityType, matchingVariant, matchingSubType, ignoreFriendly)
     if ignoreFriendly == nil then
         ignoreFriendly = false
@@ -79,9 +83,20 @@ function ____exports.getAliveBosses(self, matchingEntityType, matchingVariant, m
         function(____, aliveNPC) return aliveNPC:IsBoss() end
     )
 end
+--- Helper function to get the set of every boss in the game.
+-- 
+-- The set contains strings with the entity type and variant, separated by a period.
+-- 
+-- Also see the `getBossSet` and `getCombinedBossSet` functions.
 function ____exports.getAllBossesSet(self)
     return copySet(nil, ALL_BOSSES_SET)
 end
+--- Helper function to get the set of vanilla bosses for a particular stage and stage type
+-- combination.
+-- 
+-- The set contains strings with the entity type and variant, separated by a period.
+-- 
+-- Also see the `getAllBossesSet` and `getCombinedBossSet` functions.
 function ____exports.getBossSet(self, stage, stageType)
     local stageTypeMap = STAGE_TO_STAGE_TYPE_TO_BOSS_SET_MAP:get(stage)
     if stageTypeMap == nil then
@@ -93,6 +108,7 @@ function ____exports.getBossSet(self, stage, stageType)
     end
     return copySet(nil, bossSet)
 end
+--- Helper function to get all of the bosses in the room.
 function ____exports.getBosses(self, matchingEntityType, matchingVariant, matchingSubType, ignoreFriendly)
     if ignoreFriendly == nil then
         ignoreFriendly = false
@@ -109,6 +125,13 @@ function ____exports.getBosses(self, matchingEntityType, matchingVariant, matchi
         function(____, npc) return npc:IsBoss() end
     )
 end
+--- Helper function to get the set of vanilla bosses for a particular stage across all of the stage
+-- types. For example, specifying a stage of 2 will return a set with all of the bosses for
+-- Basement, Cellar, Burning Basement, Downpour, and Dross.
+-- 
+-- The set contains strings with the entity type and variant, separated by a period.
+-- 
+-- Also see the `getAllBossesSet` and `getBossSet` functions.
 function ____exports.getCombinedBossSet(self, stage)
     local bossSet = STAGE_TO_COMBINED_BOSS_SET_MAP:get(stage)
     if bossSet == nil then
@@ -116,9 +139,18 @@ function ____exports.getCombinedBossSet(self, stage)
     end
     return copySet(nil, bossSet)
 end
+--- Helper function to check if the provided NPC is a Sin miniboss, such as Sloth or Lust.
 function ____exports.isSin(self, npc)
     return SIN_ENTITY_TYPES_SET:has(npc.Type)
 end
+--- Helper function to spawn a boss.
+-- 
+-- Use this function instead of `spawnNPC` since it handles automatically spawning multiple segments
+-- for multi-segment bosses.
+-- 
+-- By default, this will spawn Chub (and his variants) with 3 segments, Lokii with 2 copies,
+-- Gurglings/Turdlings with 2 copies, and other multi-segment bosses with 4 segments. You can
+-- customize this via the "numSegments" argument.
 function ____exports.spawnBoss(self, entityType, variant, subType, position, velocity, spawner, seed, numSegments)
     if velocity == nil then
         velocity = VectorZero
@@ -161,6 +193,9 @@ function ____exports.spawnBoss(self, entityType, variant, subType, position, vel
     end
     return npc
 end
+--- Helper function to spawn a boss with a specific seed.
+-- 
+-- For more information, see the documentation for the `spawnBoss` function.
 function ____exports.spawnBossWithSeed(self, entityType, variant, subType, position, seed, velocity, spawner, numSegments)
     if velocity == nil then
         velocity = VectorZero

package/functions/cacheFlag.lua

@@ -1,6 +1,10 @@
 local ____exports = {}
 local ____defaultPlayerStatMap = require("maps.defaultPlayerStatMap")
 local DEFAULT_PLAYER_STAT_MAP = ____defaultPlayerStatMap.DEFAULT_PLAYER_STAT_MAP
+--- Returns the starting stat that Isaac (the default character) starts with. For example, if you
+-- pass this function `CacheFlag.DAMAGE`, it will return 3.5.
+-- 
+-- Note that the default fire delay is represented in the tear stat, not the `MaxFireDelay` value.
 function ____exports.getDefaultPlayerStat(self, cacheFlag)
     return DEFAULT_PLAYER_STAT_MAP:get(cacheFlag)
 end

package/functions/cards.lua

@@ -57,6 +57,7 @@ function initCardObjects(self)
     )
     addSetsToSet(nil, CARD_SET, cards)
 end
+--- Helper function to get an array with every valid card sub-type. This includes modded cards.
 function ____exports.getAllCards(self)
     return irange(nil, FIRST_CARD, LAST_CARD)
 end
@@ -64,6 +65,10 @@ function ____exports.getCardType(self, card)
     local cardType = CARD_TYPES[card]
     return cardType == nil and DEFAULT_CARD_TYPE or cardType
 end
+--- Helper function to get a set of cards matching the type. Also see the `CardType` enum.
+-- 
+-- This function is variadic, meaning that you can you can specify N card types to get a set
+-- containing cards that match any of the specified types.
 function ____exports.getCardsOfType(self, ...)
     local cardTypes = {...}
     if CARD_TYPE_TO_CARDS_MAP.size == 0 then
@@ -83,6 +88,14 @@ function ____exports.getCardsOfType(self, ...)
 end
 CARD_TYPE_TO_CARDS_MAP = __TS__New(Map)
 CARD_SET = __TS__New(Set)
+--- Helper function to get a card description from a Card enum value.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const card = Card.FOOL;
+-- const cardDescription = getCardDescription(card); // cardDescription is "Where journey begins"
+-- ```
 function ____exports.getCardDescription(self, card)
     local cardDescription = CARD_DESCRIPTIONS[card]
     if cardDescription ~= nil then
@@ -94,6 +107,14 @@ function ____exports.getCardDescription(self, card)
     end
     return DEFAULT_CARD_DESCRIPTION
 end
+--- Helper function to get a card name from a Card.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const card = Card.FOOL;
+-- const cardName = getCardName(card); // cardName is "0 - The Fool"
+-- ```
 function ____exports.getCardName(self, card)
     local cardName = CARD_NAMES[card]
     if cardName ~= nil and cardName ~= DEFAULT_CARD_NAME then
@@ -105,12 +126,26 @@ function ____exports.getCardName(self, card)
     end
     return DEFAULT_CARD_NAME
 end
+--- Helper function to get an array with every modded card sub-type.
+-- 
+-- Returns an empty array if there are no modded cards.
 function ____exports.getModdedCards(self)
     if MAX_VANILLA_CARD == LAST_CARD then
         return {}
     end
     return irange(nil, FIRST_MODDED_CARD, LAST_CARD)
 end
+--- Has an equal chance of returning any card (e.g. Fool, Reverse Fool, Wild Card, etc.).
+-- 
+-- This will not return:
+-- - any runes
+-- - any objects like Dice Shard
+-- - any modded cards (since there is not a way to distinguish between modded cards and modded
+--   runes/objects)
+-- 
+-- @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 cards to not select.
 function ____exports.getRandomCard(self, seedOrRNG, exceptions)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -120,6 +155,11 @@ function ____exports.getRandomCard(self, seedOrRNG, exceptions)
     end
     return getRandomSetElement(nil, CARD_SET, seedOrRNG, exceptions)
 end
+---
+-- @param cardType The card type that represents the pool of cards to select 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 cards to not select.
 function ____exports.getRandomCardOfType(self, cardType, seedOrRNG, exceptions)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -130,6 +170,12 @@ function ____exports.getRandomCardOfType(self, cardType, seedOrRNG, exceptions)
     local cardSet = ____exports.getCardsOfType(nil, cardType)
     return getRandomSetElement(nil, cardSet, seedOrRNG, exceptions)
 end
+--- Has an equal chance of returning any rune (e.g. Rune of Hagalaz, Blank Rune, Black Rune, Soul of
+-- Isaac, etc.). This will never return a Rune Shard.
+-- 
+-- @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 runes to not select.
 function ____exports.getRandomRune(self, seedOrRNG, exceptions)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -141,33 +187,47 @@ function ____exports.getRandomRune(self, seedOrRNG, exceptions)
     runesSet:delete(Card.RUNE_SHARD)
     return getRandomSetElement(nil, runesSet, seedOrRNG, exceptions)
 end
+--- Helper function to get an array with every valid vanilla card sub-type.
 function ____exports.getVanillaCards(self)
     return irange(nil, FIRST_CARD, MAX_VANILLA_CARD)
 end
+--- Returns true for cards that have the following card type:
+-- - CardType.TAROT
+-- - CardType.SUIT
+-- - CardType.SPECIAL
+-- - CardType.TAROT_REVERSE
 function ____exports.isCard(self, card)
     return CARD_SET:has(card)
 end
+--- Returns whether or not the given card matches the specified card type.
 function ____exports.isCardType(self, card, cardType)
     return cardType == ____exports.getCardType(nil, card)
 end
+--- Returns true for cards that have `CardType.MODDED`.
 function ____exports.isModdedCard(self, card)
     return ____exports.isCardType(nil, card, ItemConfigCardType.MODDED)
 end
+--- Returns true for cards that have `CardType.SPECIAL_OBJECT`.
 function ____exports.isPocketItemObject(self, card)
     return ____exports.isCardType(nil, card, ItemConfigCardType.SPECIAL_OBJECT)
 end
+--- Returns true for cards that have `CardType.TAROT_REVERSE`.
 function ____exports.isReverseTarotCard(self, card)
     return ____exports.isCardType(nil, card, ItemConfigCardType.TAROT_REVERSE)
 end
+--- Returns true for cards that have `CardType.RUNE`.
 function ____exports.isRune(self, card)
     return ____exports.isCardType(nil, card, ItemConfigCardType.RUNE)
 end
+--- Returns true for cards that have `CardType.SPECIAL`.
 function ____exports.isSpecialCard(self, card)
     return ____exports.isCardType(nil, card, ItemConfigCardType.SPECIAL)
 end
+--- Returns true for cards that have `CardType.SUIT`.
 function ____exports.isSuitCard(self, card)
     return ____exports.isCardType(nil, card, ItemConfigCardType.SUIT)
 end
+--- Returns true for cards that have `CardType.TAROT`.
 function ____exports.isTarotCard(self, card)
     return ____exports.isCardType(nil, card, ItemConfigCardType.TAROT)
 end

package/functions/challenges.lua

@@ -2,6 +2,7 @@ local ____exports = {}
 local ____challengeNames = require("objects.challengeNames")
 local CHALLENGE_NAMES = ____challengeNames.CHALLENGE_NAMES
 local DEFAULT_CHALLENGE_NAME = ____challengeNames.DEFAULT_CHALLENGE_NAME
+--- Get the proper name for a `Challenge` enum. This will only work for vanilla challenges.
 function ____exports.getChallengeName(self, challenge)
     local challengeName = CHALLENGE_NAMES[challenge]
     return challengeName == nil and DEFAULT_CHALLENGE_NAME or challengeName

package/functions/character.lua

@@ -21,21 +21,40 @@ local LOST_STYLE_CHARACTERS_SET = ____lostStyleCharactersSet.LOST_STYLE_CHARACTE
 function ____exports.isVanillaCharacter(self, character)
     return character <= LAST_VANILLA_CHARACTER
 end
+--- Helper function to determine if the given character can have red heart containers. Returns true
+-- for characters like Isaac, Magdalene, or Cain. Returns true for Keeper and Tainted Keeper, even
+-- though coin containers are not technically the same as red heart containers. Returns false for
+-- characters like Blue Baby. Returns false for The Lost and Tainted Lost.
 function ____exports.characterCanHaveRedHearts(self, character)
     return not CHARACTERS_WITH_NO_RED_HEARTS_SET:has(character)
 end
+--- Helper function to determine if the given character can have soul hearts. Returns true for
+-- characters like Isaac, Magdalene, or Cain. Returns false for characters like Bethany. Returns
+-- false for The Lost and Tainted Lost.
 function ____exports.characterCanHaveSoulHearts(self, character)
     return not CHARACTERS_WITH_NO_SOUL_HEARTS_SET:has(character)
 end
+--- Helper function for determining whether the given character can take free Devil Deals. (e.g. The
+-- Lost, Tainted Lost, etc.)
 function ____exports.characterCanTakeFreeDevilDeals(self, character)
     return CHARACTERS_WITH_FREE_DEVIL_DEALS_SET:has(character)
 end
+--- Normally, characters get a red heart container upon reaching a new floor with an eternal heart,
+-- but some characters grant a black heart instead. Returns true for Dark Judas and Tainted Judas.
+-- Otherwise, returns false.
 function ____exports.characterGetsBlackHeartFromEternalHeart(self, character)
     return CHARACTERS_WITH_BLACK_HEART_FROM_ETERNAL_HEART_SET:has(character)
 end
+--- Helper function to determine if the specified character starts with an active item.
+-- 
+-- For the purposes of this function, the save file is considered to be fully unlocked (e.g. Isaac
+-- is considered to starts with the D6, but this is not the case on a brand new save file).
 function ____exports.characterStartsWithActiveItem(self, character)
     return CHARACTERS_THAT_START_WITH_AN_ACTIVE_ITEM_SET:has(character)
 end
+--- - Most characters have a 56 frame death animation (i.e. the "Death" animation).
+-- - The Lost and Tainted Lost have a 38 frame death animation (i.e. the "LostDeath" animation).
+-- - Tainted Forgotten have a 20 frame death animation (i.e. the "ForgottenDeath" animation).
 function ____exports.getCharacterDeathAnimationName(self, character)
     if LOST_STYLE_CHARACTERS_SET:has(character) then
         return "LostDeath"
@@ -45,6 +64,9 @@ function ____exports.getCharacterDeathAnimationName(self, character)
     end
     return "Death"
 end
+--- Returns the maximum heart containers that the provided character can have. Normally, this is 12,
+-- but with Keeper it is 3, and with Tainted Keeper it is 2. This does not account for Birthright or
+-- Mother's Kiss; use the `getPlayerMaxHeartContainers` helper function for that.
 function ____exports.getCharacterMaxHeartContainers(self, character)
     if character == PlayerType.KEEPER then
         return 3
@@ -60,6 +82,7 @@ function ____exports.getCharacterMaxHeartContainers(self, character)
     end
     return 12
 end
+--- Helper function to get the name of a character. Returns "unknown" for modded characters.
 function ____exports.getCharacterName(self, character)
     if ____exports.isVanillaCharacter(nil, character) then
         return "unknown"