isaacscript-common 2.3.2 → 3.1.1

package/functions/spawnCollectible.lua

@@ -20,6 +20,20 @@ local anyPlayerIs = ____player.anyPlayerIs
 local ____rng = require("functions.rng")
 local getRandomSeed = ____rng.getRandomSeed
 local isRNG = ____rng.isRNG
+--- Helper function to spawn a collectible. Use this instead of the `Game.Spawn` method because it
+-- handles the cases of Tainted Keeper collectibles costing coins and preventing quest items from
+-- being rotated by Tainted Isaac's rotation mechanic. (Rotation prevention will only occur in
+-- upgraded mods.)
+-- 
+-- @param collectibleType The collectible type to spawn.
+-- @param position The position to spawn the collectible at.
+-- @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 options Optional. Set to true to make the collectible a "There's Options" style
+-- collectible. Default is false.
+-- @param forceFreeItem Optional. Set to true to disable the logic that gives the item a price for
+-- Tainted Keeper. Default is false.
+-- @param spawner Optional.
 function ____exports.spawnCollectible(self, collectibleType, position, seedOrRNG, options, forceFreeItem, spawner)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -52,6 +66,16 @@ function ____exports.spawnCollectible(self, collectibleType, position, seedOrRNG
     end
     return collectible
 end
+--- Helper function to spawn an empty collectible. Doing this is tricky since spawning a collectible
+-- with `CollectibleType.NULL` will result in spawning a collectible with a random type from the
+-- current room's item pool.
+-- 
+-- Instead, this function arbitrarily spawns a collectible with `CollectibleType.SAD_ONION`, and
+-- then converts it to an empty pedestal afterward.
+-- 
+-- @param position The position to spawn the empty collectible at.
+-- @param seedOrRNG 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.spawnEmptyCollectible(self, position, seedOrRNG)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)

package/functions/sprite.d.ts

@@ -1,4 +1,6 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 /**
  * Helper function to clear a specific layer from a sprite.
  *

package/functions/sprite.lua

@@ -6,11 +6,22 @@ local ____kColor = require("functions.kColor")
 local kColorEquals = ____kColor.kColorEquals
 local ____utils = require("functions.utils")
 local erange = ____utils.erange
+--- Helper function to check if two texels on a sprite are equivalent to each other.
 function ____exports.texelEquals(self, sprite1, sprite2, position, layerID)
     local kColor1 = sprite1:GetTexel(position, VectorZero, 1, layerID)
     local kColor2 = sprite2:GetTexel(position, VectorZero, 1, layerID)
     return kColorEquals(nil, kColor1, kColor2)
 end
+--- Helper function to clear a specific layer from a sprite.
+-- 
+-- This function is variadic, so pass as many layer IDs as you want to clear. If no specific layers
+-- are passed, it will clear every layer.
+-- 
+-- Since there is no official API method to "clear" a sprite, we can work around it by setting the
+-- spritesheet to a non-existent or completely transparent file. If the path to the spritesheet does
+-- not exist, then this function might cause spurious errors to appear in the "log.txt file". To
+-- silence these errors, create a transparent 1 pixel PNG file in your mod's resources folder at the
+-- path corresponding to the "EMPTY_PNG_PATH" constant.
 function ____exports.clearSprite(self, sprite, ...)
     local layerIDs = {...}
     if #layerIDs == 0 then
@@ -22,6 +33,15 @@ function ____exports.clearSprite(self, sprite, ...)
     end
     sprite:LoadGraphics()
 end
+--- Helper function that returns the number of the final frame in a particular animation for a
+-- sprite. By default, it will use the currently playing animation, but you can also specify a
+-- specific animation to check.
+-- 
+-- Note that this function is bugged with the Stop Watch or the Broken Watch, since using the
+-- `Sprite.SetFrame` method will reset the internal accumulator used to slow down the playback speed
+-- of the animation. (The `PlaybackSpeed` property of the sprite is not used.) Thus, it is only safe
+-- to use this function on animations that are not slowed down by Stop Watch or Broken Watch, such
+-- as player animations.
 function ____exports.getLastFrameOfAnimation(self, sprite, animation)
     local currentAnimation = sprite:GetAnimation()
     local currentFrame = sprite:GetFrame()
@@ -36,6 +56,11 @@ function ____exports.getLastFrameOfAnimation(self, sprite, animation)
     sprite:SetFrame(currentFrame)
     return finalFrame
 end
+--- Helper function to check if two sprite layers have the same sprite sheet by using the
+-- `Sprite.GetTexel` method.
+-- 
+-- Since checking every single texel in the entire sprite is very expensive, this function requires
+-- that you provide a range of specific texels to check.
 function ____exports.spriteEquals(self, sprite1, sprite2, layerID, xStart, xFinish, xIncrement, yStart, yFinish, yIncrement)
     do
         local x = xStart

package/functions/stage.lua

@@ -14,9 +14,16 @@ function ____exports.onRepentanceStage(self)
     local stageType = level:GetStageType()
     return ____exports.isRepentanceStage(nil, stageType)
 end
+--- Helper function to convert a numerical `StageType` into the letter suffix supplied to the "stage"
+-- console command. For example, `StageType.REPENTANCE` is the stage type for Downpour, and the
+-- console command to go to Downpour is "stage 1c", so this function converts `StageType.REPENTANCE`
+-- to "c".
 function ____exports.stageTypeToLetter(self, stageType)
     return STAGE_TYPE_TO_LETTER[stageType]
 end
+--- Helper function to account for Repentance floors being offset by 1. For example, Downpour 2 is
+-- the third level of the run, but the game considers it to have a stage of 2. This function will
+-- consider Downpour 2 to have a stage of 3.
 function ____exports.getEffectiveStage(self)
     local level = game:GetLevel()
     local stage = level:GetStage()
@@ -25,14 +32,17 @@ function ____exports.getEffectiveStage(self)
     end
     return stage
 end
+--- Alias for the `Level.GetStage` method.
 function ____exports.getStage(self)
     local level = game:GetLevel()
     return level:GetStage()
 end
+--- Alias for the `Level.GetStageType` method.
 function ____exports.getStageType(self)
     local level = game:GetLevel()
     return level:GetStageType()
 end
+--- Helper function to directly warp to a specific stage using the "stage" console command.
 function ____exports.goToStage(self, stage, stageType)
     local stageTypeLetterSuffix = ____exports.stageTypeToLetter(nil, stageType)
     local command = ("stage " .. tostring(stage)) .. stageTypeLetterSuffix
@@ -56,6 +66,12 @@ function ____exports.onDarkRoom(self)
     local stageType = level:GetStageType()
     return stage == LevelStage.DARK_ROOM_CHEST and stageType == StageType.ORIGINAL
 end
+--- Returns whether or not the player is on the "final floor" of the particular run. The final floor
+-- is defined as one that prevents the player from entering the I AM ERROR room on.
+-- 
+-- For example, when using Undefined on The Chest, it has a 50% chance of teleporting the player to
+-- the Secret Room and a 50% chance of teleporting the player to the Super Secret Room, because the
+-- I AM ERROR room is never entered into the list of possibilities.
 function ____exports.onFinalFloor(self)
     local level = game:GetLevel()
     local stage = level:GetStage()

package/functions/string.lua

@@ -13,6 +13,10 @@ end
 function ____exports.removeAllCharacters(self, ____string, character)
     return __TS__StringReplaceAll(____string, character, "")
 end
+--- Helper function to remove one or more substrings from a string, if they exist. Returns the
+-- modified string.
+-- 
+-- This function is variadic, meaning that you can pass as many substrings as you want to remove.
 function ____exports.removeSubstring(self, ____string, ...)
     local substrings = {...}
     for ____, substring in ipairs(substrings) do
@@ -20,12 +24,14 @@ function ____exports.removeSubstring(self, ____string, ...)
     end
     return ____string
 end
+--- Helper function to trim a prefix from a string, if it exists. Returns the trimmed string.
 function ____exports.trimPrefix(self, ____string, prefix)
     if not __TS__StringStartsWith(____string, prefix) then
         return ____string
     end
     return __TS__StringSlice(____string, #prefix)
 end
+--- Helper function to trim a suffix from a string, if it exists. Returns the trimmed string.
 function ____exports.trimSuffix(self, ____string, prefix)
     if not __TS__StringEndsWith(____string, prefix) then
         return ____string

package/functions/table.d.ts

@@ -27,6 +27,18 @@ export declare function getNumbersFromTable(table: LuaTable<string, unknown>, ob
  * This function is variadic, meaning that you can specify N arguments to get N values.
  */
 export declare function getStringsFromTable(table: LuaTable<string, unknown>, objectName: string, ...keys: string[]): string[];
+/**
+ * Helper function to iterate over a table deterministically. This is useful because by default, the
+ * `pairs` function will return the keys of a Lua table in a random order.
+ *
+ * This function will sort the table entries based on the value of the key.
+ *
+ * @param table The table to iterate over.
+ * @param func The function to run for each iteration.
+ * @param deterministic Optional. Whether to iterate deterministically. True by default. You can
+ *                      dynamically set to false in situations where you need extra performance.
+ */
+export declare function iterateTableDeterministically<K, V>(table: LuaTable<K, V>, func: (key: K, value: V) => void, deterministic?: boolean): void;
 /**
  * Helper function to check if a Lua table has all of the provided keys.
  *

package/functions/table.lua

@@ -1,12 +1,18 @@
 local ____lualib = require("lualib_bundle")
 local __TS__TypeOf = ____lualib.__TS__TypeOf
+local __TS__ArraySort = ____lualib.__TS__ArraySort
 local __TS__ArrayEvery = ____lualib.__TS__ArrayEvery
 local ____exports = {}
+local ____utils = require("functions.utils")
+local twoDimensionalSort = ____utils.twoDimensionalSort
+--- In a Map, you can use the `clear` method to delete every element. However, in a LuaTable, the
+-- `clear` method does not exist. Use this helper function as a drop-in replacement for this.
 function ____exports.clearTable(self, ____table)
     for key in pairs(____table) do
         ____table[key] = nil
     end
 end
+--- Helper function to copy specific values from a object to a table.
 function ____exports.copyValuesToTable(self, object, keys, ____table)
     local otherTable = object
     for ____, key in ipairs(keys) do
@@ -14,6 +20,10 @@ function ____exports.copyValuesToTable(self, object, keys, ____table)
         ____table[key] = value
     end
 end
+--- Helper function to safely get boolean values from a Lua table. Will throw an error if the
+-- specific value does not exist on the table.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to get N values.
 function ____exports.getBooleansFromTable(self, ____table, objectName, ...)
     local keys = {...}
     local booleans = {}
@@ -30,6 +40,10 @@ function ____exports.getBooleansFromTable(self, ____table, objectName, ...)
     end
     return booleans
 end
+--- Helper function to safely get number values from a Lua table. Will throw an error if the specific
+-- value does not exist on the table or if it cannot be converted to a number.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to get N values.
 function ____exports.getNumbersFromTable(self, ____table, objectName, ...)
     local keys = {...}
     local numbers = {}
@@ -52,6 +66,10 @@ function ____exports.getNumbersFromTable(self, ____table, objectName, ...)
     end
     return numbers
 end
+--- Helper function to safely get string values from a Lua table. Will throw an error if the specific
+-- value does not exist on the table.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to get N values.
 function ____exports.getStringsFromTable(self, ____table, objectName, ...)
     local keys = {...}
     local strings = {}
@@ -69,6 +87,41 @@ function ____exports.getStringsFromTable(self, ____table, objectName, ...)
     end
     return strings
 end
+--- Helper function to iterate over a table deterministically. This is useful because by default, the
+-- `pairs` function will return the keys of a Lua table in a random order.
+-- 
+-- This function will sort the table entries based on the value of the key.
+-- 
+-- @param table The table to iterate over.
+-- @param func The function to run for each iteration.
+-- @param deterministic Optional. Whether to iterate deterministically. True by default. You can
+-- dynamically set to false in situations where you need extra performance.
+function ____exports.iterateTableDeterministically(self, ____table, func, deterministic)
+    if deterministic == nil then
+        deterministic = true
+    end
+    if not deterministic then
+        for key, value in pairs(____table) do
+            func(nil, key, value)
+        end
+        return
+    end
+    local entriesArray = {}
+    for key, value in pairs(____table) do
+        local entry = {key, value}
+        entriesArray[#entriesArray + 1] = entry
+    end
+    __TS__ArraySort(entriesArray, twoDimensionalSort)
+    for ____, ____value in ipairs(entriesArray) do
+        local key = ____value[1]
+        local value = ____value[2]
+        func(nil, key, value)
+    end
+end
+--- Helper function to check if a Lua table has all of the provided keys.
+-- 
+-- This function is variadic, meaning that you can specify as many arguments as you want to check
+-- for.
 function ____exports.tableHasKeys(self, ____table, ...)
     local keys = {...}
     return __TS__ArrayEvery(

package/functions/tears.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 /**
  * - Converts the specified amount of tears stat into MaxFireDelay and adds it to the player.
  * - This function should only be used inside the EvaluateCache callback.

package/functions/tears.lua

@@ -1,10 +1,22 @@
 local ____exports = {}
+--- - The `EntityPlayer` object stores a player's tear rate in the `MaxFireDelay` attribute. This is
+--   equivalent to how many tears the player can shoot per frame.
+-- - If you already have a "tears" stat and you want to convert it back to MaxFireDelay, then use
+--   this function.
+-- - In this context, the "tears stat" represents what is shown on the in-game stat UI.
 function ____exports.getFireDelay(self, tearsStat)
     return math.max(30 / tearsStat - 1, -0.9999)
 end
+--- - The `EntityPlayer` object stores a player's tear rate in the `MaxFireDelay` attribute. This is
+--   equivalent to how many tears the player can shoot per frame.
+-- - If you want to convert this to the "tears" stat that is shown on the in-game stat UI, then use
+--   this function.
 function ____exports.getTearsStat(self, fireDelay)
     return 30 / (fireDelay + 1)
 end
+--- - Converts the specified amount of tears stat into MaxFireDelay and adds it to the player.
+-- - This function should only be used inside the EvaluateCache callback.
+-- - In this context, the "tears stat" represents what is shown on the in-game stat UI.
 function ____exports.addTearsStat(self, player, tearsStat)
     local existingTearsStat = ____exports.getTearsStat(nil, player.MaxFireDelay)
     local newTearsStat = existingTearsStat + tearsStat

package/functions/transformations.lua

@@ -36,6 +36,14 @@ local TRANSFORMATION_TO_TAG_MAP = __TS__New(Map, {
     {PlayerForm.SPIDER_BABY, ItemConfigTag.SPIDER}
 })
 local TRANSFORMATIONS_THAT_GRANT_FLYING = __TS__New(Set, {PlayerForm.GUPPY, PlayerForm.BEELZEBUB, PlayerForm.SERAPHIM, PlayerForm.LEVIATHAN})
+--- Helper function to get all of the collectible types in the game that count towards a particular
+-- transformation.
+-- 
+-- For example, to get all of the collectible types that count towards Guppy:
+-- 
+-- ```ts
+-- const guppyCollectibleTypes = getCollectibleTypesForTransformation(PlayerForm.GUPPY);
+-- ```
 function ____exports.getCollectibleTypesForTransformation(self, playerForm)
     local itemConfigTag = TRANSFORMATION_TO_TAG_MAP:get(playerForm)
     if itemConfigTag == nil then
@@ -43,6 +51,7 @@ function ____exports.getCollectibleTypesForTransformation(self, playerForm)
     end
     return getCollectibleTypesWithTag(nil, itemConfigTag)
 end
+--- Returns the number of items that a player has towards a particular transformation.
 function ____exports.getPlayerNumCollectiblesForTransformation(self, player, playerForm)
     local collectibleTypes = ____exports.getCollectibleTypesForTransformation(nil, playerForm)
     return getPlayerCollectibleCount(
@@ -51,6 +60,7 @@ function ____exports.getPlayerNumCollectiblesForTransformation(self, player, pla
         __TS__Spread(collectibleTypes:values())
     )
 end
+--- Returns a set of the player's current transformations.
 function ____exports.getPlayerTransformations(self, player)
     local transformations = __TS__New(Set)
     for ____, playerForm in ipairs(getEnumValues(nil, PlayerForm)) do
@@ -60,6 +70,14 @@ function ____exports.getPlayerTransformations(self, player)
     end
     return transformations
 end
+--- Helper function to get a transformation name from a PlayerForm enum.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const transformationName = getTransformationName(PlayerForm.LORD_OF_THE_FLIES);
+-- // transformationName is "Beelzebub"
+-- ```
 function ____exports.getTransformationName(self, playerForm)
     local transformationName = TRANSFORMATION_NAMES[playerForm]
     return transformationName == nil and DEFAULT_TRANSFORMATION_NAME or transformationName

package/functions/trinketCacheFlag.lua

@@ -25,6 +25,7 @@ function initCacheFlagMap(self)
         CACHE_FLAG_TO_TRINKETS_MAP:set(cacheFlag, trinketsSet)
     end
 end
+--- Returns a set containing every trinket type with the given cache flag, including modded trinkets.
 function ____exports.getTrinketsForCacheFlag(self, cacheFlag)
     if CACHE_FLAG_TO_TRINKETS_MAP.size == 0 then
         initCacheFlagMap(nil)
@@ -36,6 +37,8 @@ function ____exports.getTrinketsForCacheFlag(self, cacheFlag)
     return copySet(nil, trinketsSet)
 end
 CACHE_FLAG_TO_TRINKETS_MAP = __TS__New(Map)
+--- Returns a map containing every trinket type that the player has that matches the provided
+-- CacheFlag. The values of the map correspond to the multiplier for that trinket.
 function ____exports.getPlayerTrinketsForCacheFlag(self, player, cacheFlag)
     local trinketsForCacheFlag = ____exports.getTrinketsForCacheFlag(nil, cacheFlag)
     local playerTrinkets = __TS__New(Map)

package/functions/trinketGive.lua

@@ -9,6 +9,11 @@ local ____trinkets = require("functions.trinkets")
 local getGoldenTrinketType = ____trinkets.getGoldenTrinketType
 local ____utils = require("functions.utils")
 local ____repeat = ____utils["repeat"]
+--- Helper function to temporarily removes a player's held trinkets, if any. This will not remove any
+-- smelted trinkets. Use this in combination with the `giveTrinketsBack` function to take away and
+-- give back trinkets on the same frame.
+-- 
+-- @returns Undefined if the player does not have any trinkets, or TrinketSituation if they do.
 function ____exports.temporarilyRemoveTrinkets(self, player)
     local trinketType1 = player:GetTrinket(TrinketSlot.SLOT_1)
     local trinketType2 = player:GetTrinket(TrinketSlot.SLOT_2)
@@ -23,6 +28,9 @@ function ____exports.temporarilyRemoveTrinkets(self, player)
     end
     return {trinketTypeRemoved = TrinketType.NULL, trinketType1 = trinketType1, trinketType2 = trinketType2, numSmeltedTrinkets = 0}
 end
+--- Helper function to restore the player's trinkets back to the way they were before the
+-- `temporarilyRemoveTrinket` function was used. It will re-smelt any smelted trinkets that were
+-- removed.
 function ____exports.giveTrinketsBack(self, player, trinketSituation)
     if trinketSituation == nil then
         return
@@ -50,6 +58,14 @@ function ____exports.giveTrinketsBack(self, player, trinketSituation)
         player:AddTrinket(trinketSituation.trinketType2, false)
     end
 end
+--- Helper function to smelt a trinket. Before smelting, this function will automatically remove the
+-- trinkets that the player is holding, if any, and then give them back after the new trinket is
+-- smelted.
+-- 
+-- @param player The player to smelt the trinkets to.
+-- @param trinketType The trinket type to smelt.
+-- @param numTrinkets Optional. If specified, will smelt the given number of trinkets. Use this to
+-- avoid calling this function multiple times. Default is 1.
 function ____exports.smeltTrinket(self, player, trinketType, numTrinkets)
     if numTrinkets == nil then
         numTrinkets = 1
@@ -65,6 +81,14 @@ function ____exports.smeltTrinket(self, player, trinketType, numTrinkets)
     )
     ____exports.giveTrinketsBack(nil, player, trinketSituation)
 end
+--- Helper function to temporarily remove a specific kind of trinket from the player. Use this in
+-- combination with the `giveTrinketsBack` function to take away and give back a trinket on the same
+-- frame. This function correctly handles multiple trinket slots and ensures that all copies of the
+-- trinket are removed, including smelted trinkets.
+-- 
+-- Note that one smelted golden trinket is the same as two smelted normal trinkets.
+-- 
+-- @returns Undefined if the player does not have the trinket, or TrinketSituation if they do.
 function ____exports.temporarilyRemoveTrinket(self, player, trinketType)
     if not player:HasTrinket(trinketType) then
         return nil

package/functions/trinkets.lua

@@ -28,17 +28,41 @@ local ____sprite = require("functions.sprite")
 local clearSprite = ____sprite.clearSprite
 local ____utils = require("functions.utils")
 local irange = ____utils.irange
+--- Add this to a `TrinketType` to get the corresponding golden trinket type.
+-- 
+-- Corresponds to the vanilla `PillColor.TRINKET_GOLDEN_FLAG` value.
+-- 
+-- 1 << 15
 local GOLDEN_TRINKET_ADJUSTMENT = 32768
 local TRINKET_SPRITE_LAYER = 0
+--- Helper function to get the corresponding golden trinket type from a normal trinket type.
+-- 
+-- For example, passing `TrinketType.SWALLOWED_PENNY` would result in 32769, which is the value that
+-- corresponds to the golden trinket sub-type for Swallowed Penny.
 function ____exports.getGoldenTrinketType(self, trinketType)
     return trinketType + GOLDEN_TRINKET_ADJUSTMENT
 end
+--- Helper function to get an array that represents every modded trinket type.
+-- 
+-- Returns an empty array if there are no modded trinket types.
 function ____exports.getModdedTrinketTypes(self)
     if LAST_VANILLA_TRINKET_TYPE == LAST_TRINKET_TYPE then
         return {}
     end
     return irange(nil, FIRST_MODDED_TRINKET_TYPE, LAST_TRINKET_TYPE)
 end
+--- Returns the slot number corresponding to where a trinket can be safely inserted.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const player = Isaac.GetPlayer();
+-- const trinketSlot = getOpenTrinketSlotNum(player);
+-- if (trinketSlot !== undefined) {
+--   // They have one or more open trinket slots
+--   player.AddTrinket(TrinketType.SWALLOWED_PENNY);
+-- }
+-- ```
 function ____exports.getOpenTrinketSlot(self, player)
     local maxTrinkets = player:GetMaxTrinkets()
     local trinketType1 = player:GetTrinket(TrinketSlot.SLOT_1)
@@ -54,6 +78,8 @@ function ____exports.getOpenTrinketSlot(self, player)
     end
     return error("The player has an unknown number of trinket slots: " .. tostring(maxTrinkets))
 end
+--- Helper function to get the in-game description for a trinket. Returns "Unknown" if the provided
+-- trinket type was not valid.
 function ____exports.getTrinketDescription(self, trinketType)
     local trinketDescription = TRINKET_DESCRIPTION_MAP:get(trinketType)
     if trinketDescription ~= nil then
@@ -65,6 +91,15 @@ function ____exports.getTrinketDescription(self, trinketType)
     end
     return DEFAULT_TRINKET_DESCRIPTION
 end
+--- Helper function to get the name of a trinket. Returns "Unknown" if the provided trinket type is
+-- not valid.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const trinketType = TrinketType.SWALLOWED_PENNY;
+-- const trinketName = getTrinketName(trinketType); // trinketName is "Swallowed Penny"
+-- ```
 function ____exports.getTrinketName(self, trinketType)
     local trinketName = TRINKET_NAME_MAP:get(trinketType)
     if trinketName ~= nil then
@@ -76,12 +111,19 @@ function ____exports.getTrinketName(self, trinketType)
     end
     return DEFAULT_TRINKET_NAME
 end
+--- Helper function to get an array that contains every trinket type.
 function ____exports.getTrinketTypes(self)
     return irange(nil, FIRST_TRINKET_TYPE, LAST_TRINKET_TYPE)
 end
+--- Helper function to get an array that represents every vanilla trinket type.
 function ____exports.getVanillaTrinketTypes(self)
     return irange(nil, FIRST_TRINKET_TYPE, LAST_VANILLA_TRINKET_TYPE)
 end
+--- Returns whether or not the player can hold an additional trinket, beyond what they are currently
+-- carrying. This takes into account items that modify the max number of trinkets, like Mom's Purse.
+-- 
+-- If the player is the Tainted Soul, this always returns false, since that character cannot pick up
+-- items. (Only Tainted Forgotten can pick up items.)
 function ____exports.hasOpenTrinketSlot(self, player)
     if isCharacter(nil, player, PlayerType.THE_SOUL_B) then
         return false
@@ -92,6 +134,16 @@ end
 function ____exports.isGoldenTrinket(self, trinketType)
     return trinketType > GOLDEN_TRINKET_ADJUSTMENT
 end
+--- Helper function to change the sprite of a trinket entity.
+-- 
+-- For more information about removing the trinket sprite, see the documentation for the
+-- "clearSprite" helper function.
+-- 
+-- @param trinket The trinket whose sprite you want to modify.
+-- @param pngPath Equal to either the spritesheet path to load (e.g.
+-- "gfx/items/trinkets/trinket_001_swallowedpenny.png") or undefined. If undefined,
+-- the sprite will be removed, making it appear like the collectible has already been
+-- taken by the player.
 function ____exports.setTrinketSprite(self, trinket, pngPath)
     if not isTrinket(nil, trinket) then
         local entityID = getEntityID(nil, trinket)

package/functions/tstlClass.d.ts

@@ -1,9 +1,43 @@
+/// <reference types="typescript-to-lua/language-extensions" />
+import { DefaultMap } from "../classes/DefaultMap";
 import { TSTLClass } from "../types/private/TSTLClass";
+/**
+ * Helper function to get the name of a TypeScriptToLua class. TSTL classes are Lua tables created
+ * with the `__TS__Class` Lua function from the TSTL lualib. Their name is contained within
+ * "constructor.name" metatable key.
+ *
+ * For example, a `Map` class is has a name of "Map".
+ *
+ * Returns undefined if the object is not a table or if the aforementioned metatable key does not
+ * exist.
+ */
+export declare function getTSTLClassName(object: unknown): string | undefined;
+/**
+ * Helper function to determine if a given object is a TypeScriptToLua `Map`.
+ *
+ * It is not reliable to use the `instanceof` operator to determine this because each Lua module has
+ * their own copies of the entire lualib and thus their own instantiated version of a `Map`.
+ */
+export declare function isDefaultMap(object: unknown): object is DefaultMap<AnyNotNil, unknown>;
 /**
  * Returns whether or not this is a class that is provided by the `isaacscript-common` library, such
  * as a `DefaultMap`.
  */
 export declare function isIsaacScriptCommonClass(object: unknown): boolean;
+/**
+ * Helper function to determine if a given object is a TypeScriptToLua `Map`.
+ *
+ * It is not reliable to use the `instanceof` operator to determine this because each Lua module has
+ * their own copies of the entire lualib and thus their own instantiated version of a `Map`.
+ */
+export declare function isTSTLMap(object: unknown): object is Map<AnyNotNil, unknown>;
+/**
+ * Helper function to determine if a given object is a TypeScriptToLua `Set`.
+ *
+ * It is not reliable to use the `instanceof` operator to determine this because each Lua module has
+ * their own copies of the entire lualib and thus their own instantiated version of a `Set`.
+ */
+export declare function isTSTLSet(object: unknown): object is Set<AnyNotNil>;
 /** TypeScriptToLua classes are Lua tables that have a metatable with a certain amount of keys. */
 export declare function isUserDefinedTSTLClass(object: unknown): object is TSTLClass;
 /**