isaacscript-common 2.3.1 → 3.1.0

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;
 /**

package/functions/tstlClass.lua

@@ -1,16 +1,38 @@
 local ____lualib = require("lualib_bundle")
 local Set = ____lualib.Set
 local __TS__New = ____lualib.__TS__New
-local __TS__InstanceOf = ____lualib.__TS__InstanceOf
-local Map = ____lualib.Map
-local WeakMap = ____lualib.WeakMap
-local WeakSet = ____lualib.WeakSet
 local ____exports = {}
-local newTSTLClassFromMetatable
-local ____DefaultMap = require("classes.DefaultMap")
-local DefaultMap = ____DefaultMap.DefaultMap
+local newTSTLClassFromMetatable, VANILLA_TSTL_CLASSES
+--- 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.
+function ____exports.getTSTLClassName(self, object)
+    if type(object) ~= "table" then
+        return nil
+    end
+    local metatable = getmetatable(object)
+    if metatable == nil then
+        return nil
+    end
+    local constructor = metatable.constructor
+    if constructor == nil then
+        return nil
+    end
+    return constructor.name
+end
+--- Returns whether or not this is a class that is provided as part of the TypeScriptToLua
+-- transpiler, such as a `Map` or a `Set`.
 function ____exports.isVanillaTSTLClass(self, object)
-    return __TS__InstanceOf(object, Map) or __TS__InstanceOf(object, Set) or __TS__InstanceOf(object, WeakMap) or __TS__InstanceOf(object, WeakSet)
+    local className = ____exports.getTSTLClassName(nil, object)
+    if className == nil then
+        return false
+    end
+    return VANILLA_TSTL_CLASSES:has(className)
 end
 function newTSTLClassFromMetatable(self, metatable)
     local newClass = {}
@@ -18,10 +40,38 @@ function newTSTLClassFromMetatable(self, metatable)
     newClassMetatable:____constructor()
     return newClass
 end
+VANILLA_TSTL_CLASSES = __TS__New(Set, {"Map", "Set", "WeakMap", "WeakSet"})
 local TSTL_CLASS_METATABLE_KEYS = __TS__New(Set, {"____constructor", "__index", "constructor"})
+--- 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`.
+function ____exports.isDefaultMap(self, object)
+    local className = ____exports.getTSTLClassName(nil, object)
+    return className == "DefaultMap"
+end
+--- Returns whether or not this is a class that is provided by the `isaacscript-common` library, such
+-- as a `DefaultMap`.
 function ____exports.isIsaacScriptCommonClass(self, object)
-    return __TS__InstanceOf(object, DefaultMap)
+    return ____exports.isDefaultMap(nil, object)
+end
+--- 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`.
+function ____exports.isTSTLMap(self, object)
+    local className = ____exports.getTSTLClassName(nil, object)
+    return className == "Map"
+end
+--- 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`.
+function ____exports.isTSTLSet(self, object)
+    local className = ____exports.getTSTLClassName(nil, object)
+    return className == "Set"
 end
+--- TypeScriptToLua classes are Lua tables that have a metatable with a certain amount of keys.
 function ____exports.isUserDefinedTSTLClass(self, object)
     if ____exports.isVanillaTSTLClass(nil, object) or ____exports.isIsaacScriptCommonClass(nil, object) then
         return false
@@ -46,6 +96,10 @@ function ____exports.isUserDefinedTSTLClass(self, object)
     end
     return numKeys == TSTL_CLASS_METATABLE_KEYS.size
 end
+--- Initializes a new TypeScriptToLua class in the situation where you do not know what kind of class
+-- it is. This function requires that you provide an instantiated class of the same type, as it will
+-- use the class constructor that is present on the other object's metatable to initialize the new
+-- class.
 function ____exports.newTSTLClass(self, oldClass)
     local metatable = getmetatable(oldClass)
     if metatable == nil then

package/functions/ui.d.ts

@@ -1,4 +1,6 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 /**
  * In the options menu, players have the ability to set a HUD offset. However, mods do not have
  * access to this value. To get around this, Mod Config Menu provides a separate HUD offset setting

package/functions/ui.lua

@@ -14,6 +14,14 @@ function ____exports.getScreenBottomRightPos(self)
     local screenHeight = Isaac.GetScreenHeight()
     return Vector(screenWidth, screenHeight)
 end
+--- In the options menu, players have the ability to set a HUD offset. However, mods do not have
+-- access to this value. To get around this, Mod Config Menu provides a separate HUD offset setting
+-- on the first page of the menu. This is intended to be set by end-users to match their vanilla HUD
+-- offset setting so that mods can render UI elements to the screen in the correct position.
+-- 
+-- @returns If the user does not have Mod Config Menu enabled, or does not have this option set,
+-- then this function will return `Vector.Zero.` Otherwise, it will return a Vector that
+-- represents a HUD offset that should be added to the position of a UI element.
 function ____exports.getHUDOffsetVector(self)
     local defaultVector = copyVector(nil, VectorZero)
     local hudOffset = math.floor(Options.HUDOffset * 10)
@@ -30,6 +38,8 @@ function ____exports.getHUDOffsetVector(self)
     end
     return Vector(x, y)
 end
+--- Returns how many hearts are in the heart UI row. If the player has more than 6 hearts, this
+-- function will return 6.
 function ____exports.getHeartRowLength(self, player)
     local maxHearts = player:GetMaxHearts()
     local soulHearts = player:GetSoulHearts()
@@ -38,6 +48,9 @@ function ____exports.getHeartRowLength(self, player)
     local heartRowLength = combinedHearts / 2
     return math.min(heartRowLength, 6)
 end
+--- Helper function to get the width of the first player's hearts on the UI. This is useful for
+-- drawing UI elements to the right of where the player's hearts are. Make sure to use this in
+-- combination with the the `getHUDOffsetVector` helper function.
 function ____exports.getHeartsUIWidth(self)
     local level = game:GetLevel()
     local curses = level:GetCurses()
@@ -81,6 +94,9 @@ function ____exports.getScreenTopRightPos(self)
     local bottomRight = ____exports.getScreenBottomRightPos(nil)
     return Vector(bottomRight.X, 0)
 end
+--- Get how many hearts are currently being shown on the hearts UI.
+-- 
+-- This function is originally from piber20 Helper.
 function ____exports.getVisibleHearts(self, player)
     local effectiveMaxHearts = player:GetEffectiveMaxHearts()
     local soulHearts = player:GetSoulHearts()

package/functions/utils.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 /**
  * Helper function to get type safety on a switch statement.
  *
@@ -65,6 +66,7 @@ export declare function hexToKColor(hexString: string, alpha: float): KColor;
  * If only one argument is specified, then it will assume that the start is 0.
  */
 export declare function irange(start: int, end?: int): int[];
+export declare function isPrimitive(variable: unknown): boolean;
 /**
  * Since this is a UI element, we do not want to draw it in water reflections. `renderOffset` will
  * be a non-zero value in reflections.
@@ -110,3 +112,17 @@ export declare function repeat(n: int, func: (i: int) => void): void;
  * This function does not actually do anything. (It is an "empty" function.)
  */
 export declare function todo(): void;
+/**
+ * Helper function to sort a two-dimensional array by the first element.
+ *
+ * For example:
+ *
+ * ```ts
+ * const myArray = [[1, 2], [2, 3], [3, 4]];
+ * myArray.sort(twoDimensionalSort);
+ * ```
+ *
+ * From:
+ * https://stackoverflow.com/questions/16096872/how-to-sort-2-dimensional-array-by-column-value
+ */
+export declare function twoDimensionalSort<T>(a: T[], b: T[]): -1 | 0 | 1;