isaacscript-common 2.3.2 → 3.0.0

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"

package/functions/charge.lua

@@ -13,6 +13,19 @@ local ____collectibles = require("functions.collectibles")
 local getCollectibleMaxCharges = ____collectibles.getCollectibleMaxCharges
 local ____playerIndex = require("functions.playerIndex")
 local getPlayers = ____playerIndex.getPlayers
+--- Helper function to add a charge to one of a player's active items, emulating what happens when a
+-- room is cleared.
+-- 
+-- This function will take the following things into account:
+-- - L rooms and 2x2 rooms granting a double charge
+-- - The Battery
+-- - AAA Battery
+-- 
+-- @param player The player to grant the charges to.
+-- @param activeSlot The active item slot to grant the charges to.
+-- @param ignoreBigRoomDoubleCharge Optional. If set to true, it will treat the current room as a
+-- 1x1 room for the purposes of calculating how much charge to
+-- grant. Default is false.
 function ____exports.addRoomClearChargeToSlot(self, player, activeSlot, ignoreBigRoomDoubleCharge)
     if ignoreBigRoomDoubleCharge == nil then
         ignoreBigRoomDoubleCharge = false
@@ -75,6 +88,9 @@ function getNumChargesWithAAAModifier(self, player, activeSlot, chargesToAdd)
     end
     return chargesToAdd
 end
+--- Helper function to get the combined normal charge and the battery charge for the player's active
+-- item. This is useful because you have to add these two values together when setting the active
+-- charge.
 function ____exports.getTotalCharge(self, player, activeSlot)
     local activeCharge = player:GetActiveCharge(activeSlot)
     local batteryCharge = player:GetBatteryCharge(activeSlot)
@@ -98,6 +114,18 @@ function shouldPlayFullRechargeSound(self, player, activeSlot)
     end
     return not player:NeedsCharge(activeSlot) or activeCharge == maxCharges and batteryCharge == 0
 end
+--- Helper function to add a charge to a player's active item, emulating what happens when a room is
+-- cleared.
+-- 
+-- This function will take the following things into account:
+-- - L rooms and 2x2 rooms granting a double charge
+-- - The Battery
+-- - AAA Battery
+-- 
+-- @param player The player to grant the charges to.
+-- @param ignoreBigRoomDoubleCharge Optional. If set to true, it will treat the current room as a
+-- 1x1 room for the purposes of calculating how much charge to
+-- grant. Default is false.
 function ____exports.addRoomClearCharge(self, player, ignoreBigRoomDoubleCharge)
     if ignoreBigRoomDoubleCharge == nil then
         ignoreBigRoomDoubleCharge = false
@@ -106,6 +134,17 @@ function ____exports.addRoomClearCharge(self, player, ignoreBigRoomDoubleCharge)
         ____exports.addRoomClearChargeToSlot(nil, player, activeSlot, ignoreBigRoomDoubleCharge)
     end
 end
+--- Helper function to add a charge to every player's active item, emulating what happens when a room
+-- is cleared.
+-- 
+-- This function will take the following things into account:
+-- - L rooms and 2x2 rooms granting a double charge
+-- - The Battery
+-- - AAA Battery
+-- 
+-- @param ignoreBigRoomDoubleCharge Optional. If set to true, it will treat the current room as a
+-- 1x1 room for the purposes of calculating how much charge to
+-- grant. Default is false.
 function ____exports.addRoomClearCharges(self, ignoreBigRoomDoubleCharge)
     if ignoreBigRoomDoubleCharge == nil then
         ignoreBigRoomDoubleCharge = false

package/functions/chargeBar.lua

@@ -8,6 +8,8 @@ function getChargeBarClamp(self, charges, maxCharges)
     return Vector(0, meterClip)
 end
 local CHARGE_BAR_ANM2 = "gfx/ui/ui_chargebar.anm2"
+--- Constructor for a `ChargeBarSprites` object. For more information, see the `renderChargeBar`
+-- helper function.
 function ____exports.newChargeBarSprites(self, maxCharges)
     local back = Sprite()
     back:Load(CHARGE_BAR_ANM2, true)
@@ -32,6 +34,8 @@ function ____exports.newChargeBarSprites(self, maxCharges)
         maxCharges = maxCharges
     }
 end
+--- Helper function to render a charge bar on the screen. First, call the `newChargeBarSprites`
+-- function to initialize the sprites, and then call this function on every render frame.
 function ____exports.renderChargeBar(self, sprites, position, normalCharges, batteryCharges)
     sprites.back:Render(position, VectorZero, VectorZero)
     local normalChargesClamp = getChargeBarClamp(nil, normalCharges, sprites.maxCharges)

package/functions/collectibleCacheFlag.lua

@@ -37,6 +37,8 @@ local function initCacheFlagMap(self)
         CACHE_FLAG_TO_COLLECTIBLES_MAP:set(cacheFlag, collectiblesSet)
     end
 end
+--- Returns a set containing every collectible type with the given cache flag, including modded
+-- collectibles.
 function ____exports.getCollectiblesForCacheFlag(self, cacheFlag)
     if CACHE_FLAG_TO_COLLECTIBLES_MAP.size == 0 then
         initCacheFlagMap(nil)
@@ -47,6 +49,19 @@ function ____exports.getCollectiblesForCacheFlag(self, cacheFlag)
     end
     return copySet(nil, collectiblesSet)
 end
+--- Returns an array containing every collectible type that the player has that matches the provided
+-- CacheFlag.
+-- 
+-- For example, if the cache flag is `CacheFlag.FLYING`, and the player has one Lord of the Pit and
+-- two Dead Doves, then this function would return:
+-- 
+-- ```ts
+-- [
+--   CollectibleType.LORD_OF_THE_PIT,
+--   CollectibleType.DEAD_DOVE,
+--   CollectibleType.DEAD_DOVE,
+-- ]
+-- ```
 function ____exports.getPlayerCollectiblesForCacheFlag(self, player, cacheFlag)
     local collectiblesForCacheFlag = ____exports.getCollectiblesForCacheFlag(nil, cacheFlag)
     local playerCollectibles = {}

package/functions/collectibleSet.lua

@@ -30,18 +30,21 @@ local function initCollectibleSets(self)
         ::__continue3::
     end
 end
+--- Returns a set containing every valid collectible type in the game, including modded collectibles.
 function ____exports.getCollectibleSet(self)
     if ALL_COLLECTIBLES_SET.size == 0 then
         initCollectibleSets(nil)
     end
     return copySet(nil, ALL_COLLECTIBLES_SET)
 end
+--- Returns a set containing every modded collectible type in the game.
 function ____exports.getModdedCollectibleSet(self)
     if ALL_COLLECTIBLES_SET.size == 0 then
         initCollectibleSets(nil)
     end
     return copySet(nil, MODDED_COLLECTIBLES_SET)
 end
+--- Returns a set containing every valid vanilla collectible type in the game.
 function ____exports.getVanillaCollectibleSet(self)
     if ALL_COLLECTIBLES_SET.size == 0 then
         initCollectibleSets(nil)

package/functions/collectibleTag.lua

@@ -50,6 +50,14 @@ local function initTagMap(self)
         end
     end
 end
+--- Helper function to get all of the collectible types in the game that have a certain tag.
+-- 
+-- For example, to get all of the collectible types that count as offensive for the purposes of
+-- Tainted Lost:
+-- 
+-- ```ts
+-- const offensiveCollectibleTypes = getCollectibleTypesWithTag(ItemConfigTag.OFFENSIVE);
+-- ```
 function ____exports.getCollectibleTypesWithTag(self, itemConfigTag)
     if TAG_TO_COLLECTIBLE_TYPES_MAP.size == 0 then
         initTagMap(nil)
@@ -60,6 +68,7 @@ function ____exports.getCollectibleTypesWithTag(self, itemConfigTag)
     end
     return copySet(nil, collectibleTypes)
 end
+--- Returns the number of items that a player has towards a particular transformation.
 function ____exports.getPlayerNumCollectiblesWithTag(self, player, itemConfigTag)
     local collectibleTypesSet = ____exports.getCollectibleTypesWithTag(nil, itemConfigTag)
     return getPlayerCollectibleCount(