isaacscript-common 2.3.2 → 3.1.1

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.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 import { ChargeBarSprites } from "../interfaces/ChargeBarSprites";
 /**
  * Constructor for a `ChargeBarSprites` object. For more information, see the `renderChargeBar`

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(

package/functions/collectibles.d.ts

@@ -8,9 +8,14 @@ export declare function collectibleSpriteEquals(sprite1: Sprite, sprite2: Sprite
  * provided collectible type was not valid.
  */
 export declare function getCollectibleDescription(collectibleType: CollectibleType): string;
+/**
+ * Helper function to get the coin cost that a collectible item would be if it were being offered in
+ * a Devil Room deal. Returns 0 if passed `CollectibleType.NULL`.
+ */
+export declare function getCollectibleDevilCoinPrice(collectibleType: CollectibleType): int;
 /**
  * Helper function to get the heart cost that a collectible item would be if it were being offered
- * in a Devil Room deal. Returns 0 if passed CollectibleType.NULL.
+ * in a Devil Room deal. Returns 0 if passed `CollectibleType.NULL`.
  */
 export declare function getCollectibleDevilHeartPrice(collectibleType: CollectibleType, player: EntityPlayer): PickupPrice;
 /**
@@ -47,13 +52,13 @@ export declare function getCollectibleGfxFilename(collectibleType: CollectibleTy
  *   and the pedestal pushed to an adjacent tile, but this case should be extremely rare.)
  * - Mega Chests spawn two collectibles on the exact same position. However, both of them will have
  *   different InitSeeds, so this is not a problem for this indexing scheme.
- * - The indexing scheme used is different for collectibles that are inside of a Treasure Room, in
- *   order to handle the case of the player seeing the same collectible again in a post-Ascent
- *   Treasure Room. A 5-tuple of stage, stage type, grid index, SubType, and InitSeed is used in
- *   this case. (Using the room list index or the room grid index is not suitable for this purpose,
- *   since both of these values can change in the post-Ascent Treasure Room.) Even though there can
- *   be two Treasure Rooms on an XL floor, both Treasure Rooms should not have collectibles with the
- *   same grid index, Subtype, and InitSeed.
+ * - The indexing scheme used is different for collectibles that are inside of a Treasure Room or
+ *   Boss Room, in order to handle the case of the player seeing the same collectible again in a
+ *   post-Ascent Treasure Room or Boss Room. A 5-tuple of stage, stage type, grid index, SubType,
+ *   and InitSeed is used in this case. (Using the room list index or the room grid index is not
+ *   suitable for this purpose, since both of these values can change in the post-Ascent rooms.)
+ *   Even though Treasure Rooms and Boss Rooms are grouped together in this scheme, there probably
+ *   will not be collectibles with the same grid index, SubType, and InitSeed.
  */
 export declare function getCollectibleIndex(collectible: EntityPickup): CollectibleIndex;
 /**

package/functions/collectibles.lua

@@ -44,6 +44,16 @@ function initQuestionMarkSprite(self)
     sprite:LoadGraphics()
     return sprite
 end
+--- Helper function to change the sprite of a collectible pedestal entity.
+-- 
+-- For more information about removing the collectible sprite, see the documentation for the
+-- "clearSprite" helper function.
+-- 
+-- @param collectible The collectible whose sprite you want to modify.
+-- @param pngPath Equal to either the spritesheet path to load (e.g.
+-- "gfx/items/collectibles/collectibles_001_thesadonion.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.setCollectibleSprite(self, collectible, pngPath)
     if not isCollectible(nil, collectible) then
         local entityID = getEntityID(nil, collectible)
@@ -64,6 +74,7 @@ local questionMarkSprite = initQuestionMarkSprite(nil)
 function ____exports.clearCollectibleSprite(self, collectible)
     ____exports.setCollectibleSprite(nil, collectible, nil)
 end
+--- Helper function to check if two collectible sprites have the same sprite sheet loaded.
 function ____exports.collectibleSpriteEquals(self, sprite1, sprite2)
     local xStart = -1
     local xFinish = 1
@@ -84,6 +95,8 @@ function ____exports.collectibleSpriteEquals(self, sprite1, sprite2)
         yIncrement
     )
 end
+--- Helper function to get the in-game description for a collectible. Returns "Unknown" if the
+-- provided collectible type was not valid.
 function ____exports.getCollectibleDescription(self, collectibleType)
     local collectibleDescription = COLLECTIBLE_DESCRIPTION_MAP:get(collectibleType)
     if collectibleDescription ~= nil then
@@ -95,6 +108,21 @@ function ____exports.getCollectibleDescription(self, collectibleType)
     end
     return DEFAULT_COLLECTIBLE_DESCRIPTION
 end
+--- Helper function to get the coin cost that a collectible item would be if it were being offered in
+-- a Devil Room deal. Returns 0 if passed `CollectibleType.NULL`.
+function ____exports.getCollectibleDevilCoinPrice(self, collectibleType)
+    if collectibleType == CollectibleType.NULL then
+        return 0
+    end
+    local defaultCollectiblePrice = 15
+    local itemConfigItem = itemConfig:GetCollectible(collectibleType)
+    if itemConfigItem == nil then
+        return defaultCollectiblePrice
+    end
+    return itemConfigItem.DevilPrice * defaultCollectiblePrice
+end
+--- Helper function to get the heart cost that a collectible item would be if it were being offered
+-- in a Devil Room deal. Returns 0 if passed `CollectibleType.NULL`.
 function ____exports.getCollectibleDevilHeartPrice(self, collectibleType, player)
     local maxHearts = player:GetMaxHearts()
     if collectibleType == CollectibleType.NULL then
@@ -103,14 +131,16 @@ function ____exports.getCollectibleDevilHeartPrice(self, collectibleType, player
     if maxHearts == 0 then
         return PickupPrice.THREE_SOUL_HEARTS
     end
-    local defaultPickupPrice = PickupPrice.ONE_HEART
+    local defaultCollectiblePrice = PickupPrice.ONE_HEART
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     if itemConfigItem == nil then
-        return defaultPickupPrice
+        return defaultCollectiblePrice
     end
     local twoHeartPrice = maxHearts == 2 and PickupPrice.ONE_HEART_AND_TWO_SOUL_HEARTS or PickupPrice.TWO_HEARTS
     return itemConfigItem.DevilPrice == 2 and twoHeartPrice or PickupPrice.ONE_HEART
 end
+--- Helper function to get the path to a collectible's sprite. Returns the path to the question mark
+-- sprite (i.e. from Curse of the Blind) if the provided collectible type was not valid.
 function ____exports.getCollectibleGfxFilename(self, collectibleType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     if itemConfigItem == nil then
@@ -118,6 +148,41 @@ function ____exports.getCollectibleGfxFilename(self, collectibleType)
     end
     return itemConfigItem.GfxFileName
 end
+--- Mods often have to track variables relating to a collectible. Finding an index for these kinds of
+-- data structures is difficult, since collectibles are respawned every time a player re-enters a
+-- room, so the `PtrHash` will change. Instead, we use a 4-tuple of the room list index, the grid
+-- index of the collectible in the room, the collectible's SubType, and the collectible's InitSeed.
+-- 
+-- Collectibles that are shifted by Tainted Isaac's mechanic will have unique collectible indexes
+-- because the SubType is different. (The collectible entities share the same InitSeed.)
+-- 
+-- Collectibles that are rolled (with e.g. a D6) will have unique collectible indexes because the
+-- SubType and InitSeed are different. If you want to track collectibles independently of any
+-- rerolls, then you can use the `PtrHash` as an index instead. (The `PtrHash` will not persist
+-- between rooms, however.)
+-- 
+-- Note that:
+-- - The grid index is a necessary part of the collectible index because Diplopia and Crooked Penny
+--   can cause two or more collectibles with the same SubType and InitSeed to exist in the same
+--   room.
+-- - This index will fail in the case where the player uses Diplopia or a successful Crooked Penny
+--   seven or more times in the same room, since that will cause two or more collectibles with the
+--   same grid index, SubType, and InitSeed to exist.
+-- - The SubType is a necessary part of the collectible index because Tainted Isaac will
+--   continuously cause collectibles to morph into new sub-types with the same InitSeed.
+-- - Using a collectible's position as part of the index is problematic, since players can push a
+--   pedestal. (Even using the grid index does not solve this problem, since it is possible in
+--   certain cases for collectibles to be spawned at a position that is not aligned with the grid,
+--   and the pedestal pushed to an adjacent tile, but this case should be extremely rare.)
+-- - Mega Chests spawn two collectibles on the exact same position. However, both of them will have
+--   different InitSeeds, so this is not a problem for this indexing scheme.
+-- - The indexing scheme used is different for collectibles that are inside of a Treasure Room or
+--   Boss Room, in order to handle the case of the player seeing the same collectible again in a
+--   post-Ascent Treasure Room or Boss Room. A 5-tuple of stage, stage type, grid index, SubType,
+--   and InitSeed is used in this case. (Using the room list index or the room grid index is not
+--   suitable for this purpose, since both of these values can change in the post-Ascent rooms.)
+--   Even though Treasure Rooms and Boss Rooms are grouped together in this scheme, there probably
+--   will not be collectibles with the same grid index, SubType, and InitSeed.
 function ____exports.getCollectibleIndex(self, collectible)
     if not isCollectible(nil, collectible) then
         local entityID = getEntityID(nil, collectible)
@@ -130,11 +195,13 @@ function ____exports.getCollectibleIndex(self, collectible)
     local roomType = room:GetType()
     local gridIndex = room:GetGridIndex(collectible.Position)
     local roomListIndex = getRoomListIndex(nil)
-    if roomType == RoomType.TREASURE then
+    if roomType == RoomType.TREASURE or roomType == RoomType.BOSS then
         return (((((((tostring(stage) .. ",") .. tostring(stageType)) .. ",") .. tostring(gridIndex)) .. ",") .. tostring(collectible.SubType)) .. ",") .. tostring(collectible.InitSeed)
     end
     return (((((tostring(roomListIndex) .. ",") .. tostring(gridIndex)) .. ",") .. tostring(collectible.SubType)) .. ",") .. tostring(collectible.InitSeed)
 end
+--- Helper function to get the initial amount of charges that a collectible has. Returns 0 if the
+-- provided collectible type was not valid.
 function ____exports.getCollectibleInitCharge(self, collectibleType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     if itemConfigItem == nil then
@@ -142,6 +209,8 @@ function ____exports.getCollectibleInitCharge(self, collectibleType)
     end
     return itemConfigItem.InitCharge
 end
+--- Helper function to get the `ItemType` of a collectible. Returns `ItemType.ITEM_NULL` if the
+-- provided collectible type was not valid.
 function ____exports.getCollectibleItemType(self, collectibleType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     if itemConfigItem == nil then
@@ -149,6 +218,8 @@ function ____exports.getCollectibleItemType(self, collectibleType)
     end
     return itemConfigItem.Type
 end
+--- Helper function to get the maximum amount of charges that a collectible has. Returns 0 if the
+-- provided collectible type was not valid.
 function ____exports.getCollectibleMaxCharges(self, collectibleType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     if itemConfigItem == nil then
@@ -156,6 +227,15 @@ function ____exports.getCollectibleMaxCharges(self, collectibleType)
     end
     return itemConfigItem.MaxCharges
 end
+--- Helper function to get the name of a collectible. Returns "Unknown" if the provided collectible
+-- type is not valid.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const collectibleType = CollectibleType.SAD_ONION;
+-- const collectibleName = getCollectibleName(collectibleType); // collectibleName is "Sad Onion"
+-- ```
 function ____exports.getCollectibleName(self, collectibleType)
     local collectibleName = COLLECTIBLE_NAME_MAP:get(collectibleType)
     if collectibleName ~= nil then
@@ -175,6 +255,8 @@ function ____exports.getCollectiblePedestalType(self, collectible)
     local sprite = collectible:GetSprite()
     return sprite:GetOverlayFrame()
 end
+--- Helper function to get the path to a collectible's quality. Returns 0 if the provided collectible
+-- type was not valid.
 function ____exports.getCollectibleQuality(self, collectibleType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     if itemConfigItem == nil then
@@ -182,26 +264,59 @@ function ____exports.getCollectibleQuality(self, collectibleType)
     end
     return itemConfigItem.Quality
 end
+--- Helper function to get the tags of a collectible (which is the composition of zero or more
+-- `ItemConfigTag`). Returns 0 if the provided collectible type is not valid.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const collectibleType = CollectibleType.SAD_ONION;
+-- const itemConfigTags = getCollectibleTags(collectibleType); // itemConfigTags is "18350080"
+-- ```
 function ____exports.getCollectibleTags(self, collectibleType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     return itemConfigItem == nil and ItemConfigTagZero or itemConfigItem.Tags
 end
+--- Helper function to get an array that represents the range from the first collectible type to the
+-- last collectible type. This will include integers that do not represent any valid collectible
+-- types.
+-- 
+-- This function is only useful when building collectible type objects. For most purposes, you
+-- should use the `getCollectibleSet` helper function instead.
 function ____exports.getCollectibleTypeRange(self)
     return irange(nil, FIRST_COLLECTIBLE_TYPE, LAST_COLLECTIBLE_TYPE)
 end
+--- Helper function to get an array that represents the all modded collectible types.
+-- 
+-- This function is only useful when building collectible type objects. For most purposes, you
+-- should use the `getModdedCollectibleSet` helper function instead.
+-- 
+-- Returns an empty array if there are no modded collectible types.
+-- 
+-- (This function is named differently from the `getVanillaCollectibleTypeRange` function because
+-- all modded collectible types are contiguous. Thus, each value represents a real
+-- `CollectibleType`.)
 function ____exports.getModdedCollectibleTypes(self)
     if LAST_VANILLA_COLLECTIBLE_TYPE == LAST_COLLECTIBLE_TYPE then
         return {}
     end
     return irange(nil, FIRST_MODDED_COLLECTIBLE_TYPE, LAST_COLLECTIBLE_TYPE)
 end
+--- Helper function to get an array that represents the range from the first collectible type to the
+-- last vanilla collectible type. This will include integers that do not represent any valid
+-- collectible types.
+-- 
+-- This function is only useful when building collectible type objects. For most purposes, you
+-- should use the `getVanillaCollectibleSet` helper function instead.
 function ____exports.getVanillaCollectibleTypeRange(self)
     return irange(nil, FIRST_COLLECTIBLE_TYPE, LAST_VANILLA_COLLECTIBLE_TYPE)
 end
+--- Returns true if the item type in the item config is equal to `ItemType.ITEM_ACTIVE`.
 function ____exports.isActiveCollectible(self, collectibleType)
     local itemType = ____exports.getCollectibleItemType(nil, collectibleType)
     return itemType == ItemType.ACTIVE
 end
+--- Returns true if the collectible has a red question mark sprite.
 function ____exports.isBlindCollectible(self, collectible)
     if not isCollectible(nil, collectible) then
         local entityID = getEntityID(nil, collectible)
@@ -213,17 +328,28 @@ function ____exports.isBlindCollectible(self, collectible)
     questionMarkSprite:SetFrame(animation, frame)
     return ____exports.collectibleSpriteEquals(nil, sprite, questionMarkSprite)
 end
+--- Returns whether or not the given collectible is a "glitched" item. All items are replaced by
+-- glitched items once a player has TMTRAINER. However, glitched items can also "naturally" appear
+-- in secret rooms and I AM ERROR rooms if the "Corrupted Data" achievement is unlocked.
 function ____exports.isGlitchedCollectible(self, pickup)
     return pickup.Variant == PickupVariant.COLLECTIBLE and pickup.SubType > GLITCHED_ITEM_THRESHOLD
 end
+--- Returns true if the collectible has the "Hidden" attribute in the item config.
+-- 
+-- Hidden collectibles will not show up in any pools and Eden will not start with them.
 function ____exports.isHiddenCollectible(self, collectibleType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     return itemConfigItem ~= nil and itemConfigItem.Hidden
 end
+--- Returns true if the item type in the item config is equal to `ItemType.ITEM_PASSIVE` or
+-- `ItemType.ITEM_FAMILIAR`.
 function ____exports.isPassiveCollectible(self, collectibleType)
     local itemType = ____exports.getCollectibleItemType(nil, collectibleType)
     return itemType == ItemType.PASSIVE or itemType == ItemType.FAMILIAR
 end
+--- Helper function to determine if a particular collectible will disappear from the player's
+-- inventory upon use. Note that this will not work will modded items, as there is no way to
+-- dynamically know if a modded item will disappear.
 function ____exports.isSingleUseCollectible(self, collectibleType)
     return SINGLE_USE_ACTIVE_COLLECTIBLE_TYPES_SET:has(collectibleType)
 end
@@ -231,10 +357,17 @@ function ____exports.isValidCollectibleType(self, collectibleType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     return itemConfigItem ~= nil
 end
+--- Helper function to put a message in the log.txt file to let the Rebirth Item Tracker know that it
+-- should remove an item.
+-- 
+-- The "item tracker" in this function does not refer to the in-game item tracker, but rather to the
+-- Python program located at: https://github.com/Rchardon/RebirthItemTracker
 function ____exports.removeCollectibleFromItemTracker(self, collectibleType)
     local collectibleName = ____exports.getCollectibleName(nil, collectibleType)
     Isaac.DebugString(((("Removing collectible " .. tostring(collectibleType)) .. " (") .. collectibleName) .. ") on player 0 (Player)")
 end
+--- Helper function to remove all pickup delay on a collectible. By default, collectibles have a 20
+-- frame delay before they can be picked up by a player.
 function ____exports.removeCollectiblePickupDelay(self, collectible)
     if not isCollectible(nil, collectible) then
         local entityID = getEntityID(nil, collectible)
@@ -242,6 +375,8 @@ function ____exports.removeCollectiblePickupDelay(self, collectible)
     end
     collectible.Wait = 0
 end
+--- Helper function to set a collectible sprite to a question mark (i.e. how collectibles look when
+-- the player has Curse of the Blind).
 function ____exports.setCollectibleBlind(self, collectible)
     if not isCollectible(nil, collectible) then
         local entityID = getEntityID(nil, collectible)
@@ -249,6 +384,11 @@ function ____exports.setCollectibleBlind(self, collectible)
     end
     ____exports.setCollectibleSprite(nil, collectible, BLIND_ITEM_PNG_PATH)
 end
+--- Helper function to remove the collectible from a collectible pedestal and make it appear as if a
+-- player has already taken the item. This is accomplished by changing the sub-type to
+-- `CollectibleType.NULL` and then setting the sprite to an empty/missing PNG file.
+-- 
+-- For more information, see the documentation for the "clearSprite" helper function.
 function ____exports.setCollectibleEmpty(self, collectible)
     if not isCollectible(nil, collectible) then
         local entityID = getEntityID(nil, collectible)
@@ -257,6 +397,8 @@ function ____exports.setCollectibleEmpty(self, collectible)
     collectible.SubType = CollectibleType.NULL
     ____exports.clearCollectibleSprite(nil, collectible)
 end
+--- Helper function to change the collectible on a pedestal. Simply updating the `SubType` property
+-- is not sufficient because the sprite will not change.
 function ____exports.setCollectibleSubType(self, collectible, newCollectibleType)
     if not isCollectible(nil, collectible) then
         local entityID = getEntityID(nil, collectible)
@@ -275,6 +417,8 @@ function ____exports.setCollectibleSubType(self, collectible, newCollectibleType
         true
     )
 end
+--- Helper function to put a message in the log.txt file to let the Rebirth Item Tracker know that
+-- the build has been rerolled.
 function ____exports.setCollectiblesRerolledForItemTracker(self)
     Isaac.DebugString("Added 3 Collectibles")
 end

package/functions/color.lua

@@ -13,6 +13,9 @@ 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 Color object.
+-- 
+-- @category color
 function ____exports.isColor(self, object)
     return isIsaacAPIClassOfType(nil, object, OBJECT_NAME)
 end
@@ -26,9 +29,17 @@ local KEYS = {
     "BO"
 }
 OBJECT_NAME = "Color"
+---
+-- @category color
 function ____exports.colorEquals(self, color1, color2)
     return isaacAPIClassEquals(nil, color1, color2, KEYS)
 end
+--- Helper function to copy a `Color` object.
+-- 
+-- @param color The Color object to copy. In the case of deserialization, this will actually be a
+-- Lua table instead of an instantiated Color class.
+-- @param serializationType Default is `SerializationType.NONE`.
+-- @category color
 function ____exports.copyColor(self, color, serializationType)
     if serializationType == nil then
         serializationType = SerializationType.NONE
@@ -104,9 +115,16 @@ function ____exports.copyColor(self, color, serializationType)
         end
     until true
 end
+--- Returns `Color(1, 1, 1)`.
+-- 
+-- @category color
 function ____exports.getDefaultColor(self)
     return Color(1, 1, 1)
 end
+--- Used to determine is the given table is a serialized `Color` object created by the save data
+-- manager and/or the `deepCopy` function.
+-- 
+-- @category color
 function ____exports.isSerializedColor(self, object)
     local objectType = type(object)
     if objectType ~= "table" then

package/functions/debug.lua

@@ -1,6 +1,10 @@
 local ____exports = {}
 local ____log = require("functions.log")
 local log = ____log.log
+--- Helper function to get a stack trace.
+-- 
+-- This will only work if the `--luadebug` launch option is enabled or the Racing+ sandbox is
+-- enabled.
 function ____exports.getTraceback(self)
     if debug ~= nil then
         return debug.traceback()
@@ -10,9 +14,23 @@ function ____exports.getTraceback(self)
     end
     return "stack traceback:\n(the \"--luadebug\" flag is not enabled)"
 end
+--- Players can boot the game with an launch option called "--luadebug", which will enable additional
+-- functionality that is considered to be unsafe. For more information about this flag, see the
+-- wiki: https://bindingofisaacrebirth.fandom.com/wiki/Launch_Options
+-- 
+-- When this flag is enabled, the global environment will be slightly different. The differences are
+-- documented here: https://wofsauge.github.io/IsaacDocs/rep/Globals.html
+-- 
+-- This function uses the `package` global variable as a proxy to determine if the "--luadebug" flag
+-- is enabled or not.
 function ____exports.isLuaDebugEnabled(self)
     return package ~= nil
 end
+--- Helper function to print a stack trace to the "log.txt" file, similar to JavaScript's
+-- `console.trace` function.
+-- 
+-- This will only work if the `--luadebug` launch option is enabled or the Racing+ sandbox is
+-- enabled.
 function ____exports.traceback(self)
     local tracebackOutput = ____exports.getTraceback(nil)
     log(tracebackOutput)