isaacscript-common 2.3.2 → 3.1.1

package/functions/flag.lua

@@ -1,6 +1,29 @@
 local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local DamageFlag = ____isaac_2Dtypescript_2Ddefinitions.DamageFlag
+--- Helper function to add a bit flag to an existing set of bit flags.
+-- 
+-- This is a variadic function, so pass as many flags as you want to add.
+-- 
+-- Example 1:
+-- 
+-- ```ts
+-- // Give the player spectral tears
+-- const player = Isaac.GetPlayer();
+-- player.TearFlags = addFlag(player.TearFlags, TearFlags.TEAR_SPECTRAL);
+-- ```
+-- 
+-- Example 2:
+-- 
+-- ```ts
+-- // Give the player spectral and homing tears
+-- const player = Isaac.GetPlayer();
+-- player.TearFlags = addFlag(player.TearFlags, TearFlags.TEAR_SPECTRAL, TearFlags.TEAR_HOMING);
+-- ```
+-- 
+-- @param flags The existing set of bit flags.
+-- @param flagsToAdd One or more bit flags to add, each as a separate argument.
+-- @returns The combined bit flags.
 function ____exports.addFlag(self, flags, ...)
     local flagsToAdd = {...}
     local flagsAsInt = flags
@@ -9,9 +32,25 @@ function ____exports.addFlag(self, flags, ...)
     end
     return flagsAsInt
 end
+--- Helper function for casting a flag enum value to a `BitFlags` object.
+-- 
+-- This is useful because the compiler will prevent you from assigning a specific flag to a
+-- `BitFlags` property. (It does this to ensure type safety, since `BitFlags` can represent a zero
+-- value or a composition of N flags.)
+-- 
+-- For example:
+-- 
+-- ```ts
+-- player.TearFlags = bitFlags(TearFlag.SPECTRAL);
+-- ```
 function ____exports.bitFlags(self, flag)
     return flag
 end
+--- Helper function to get the key associated with a particular flag.
+-- 
+-- (Since bit flags are represented by custom objects instead of normal TypeScript enums, you cannot
+-- use the reverse mapping to find the associated key of a given enum value. Use this helper
+-- function instead of indexing the enum directly.)
 function ____exports.getFlagName(self, flag, flagEnum)
     for key, value in pairs(flagEnum) do
         if value == flag then
@@ -20,6 +59,22 @@ function ____exports.getFlagName(self, flag, flagEnum)
     end
     return nil
 end
+--- Helper function to determine if a particular bit flag is set to true.
+-- 
+-- This is a variadic function, so pass as many flags as you want to check for. If passed multiple
+-- flags, it will only return true if all of the flags are set.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const player = Isaac.GetPlayer();
+-- if (hasFlag(player.TearFlags, TearFlags.TEAR_SPECTRAL) {
+--   // The player currently has spectral tears
+-- }
+-- ```
+-- 
+-- @param flags The existing set of bit flags.
+-- @param flagsToCheck One or more bit flags to check for, each as a separate argument.
 function ____exports.hasFlag(self, flags, ...)
     local flagsToCheck = {...}
     local flagsAsInt = flags
@@ -30,12 +85,34 @@ function ____exports.hasFlag(self, flags, ...)
     end
     return true
 end
+--- Helper function to check if every bit in the flag is turned off.
+-- 
+-- (This is equivalent to checking if the flag is equal to 0, but this is not possible without
+-- casting the flag to a number.)
 function ____exports.isEmptyFlag(self, flag)
     return flag == 0
 end
+--- Helper function to determine whether damage to a player in the EntityTakeDmg callback was
+-- self-inflicted. For example, damage from a Curse Room door, a Razor, or a Blood Donation Machine
+-- would count as self-inflicted damage.
 function ____exports.isSelfDamage(self, damageFlags)
     return ____exports.hasFlag(nil, damageFlags, DamageFlag.NO_PENALTIES) or ____exports.hasFlag(nil, damageFlags, DamageFlag.RED_HEARTS)
 end
+--- Helper function to remove a bit flag from an existing set of bit flags.
+-- 
+-- This is a variadic function, so pass as many flags as you want to remove.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- // Remove spectral tears from the player, if present
+-- const player = Isaac.GetPlayer();
+-- player.TearFlags = removeFlag(player.TearFlags, TearFlags.TEAR_SPECTRAL);
+-- ```
+-- 
+-- @param flags The existing set of bit flags.
+-- @param flagsToRemove One or more bit flags to remove, each as a separate argument.
+-- @returns The combined bit flags.
 function ____exports.removeFlag(self, flags, ...)
     local flagsToRemove = {...}
     local flagsAsInt = flags

package/functions/flying.lua

@@ -25,6 +25,14 @@ local FLYING_CHARACTERS = __TS__New(Set, {
 local FLYING_TRINKETS = __TS__New(Set, {TrinketType.BAT_WING, TrinketType.AZAZELS_STUMP})
 local FLYING_NULL_ITEMS = {NullItemID.REVERSE_SUN, NullItemID.SPIRIT_SHACKLES_SOUL, NullItemID.LOST_CURSE}
 local CONDITIONAL_FLYING_COLLECTIBLE_TYPES = {CollectibleType.BIBLE, CollectibleType.EMPTY_VESSEL, CollectibleType.ASTRAL_PROJECTION, CollectibleType.RECALL}
+--- Returns a set of all of the collectibles that grant flight. This is derived from collectibles
+-- that have `CacheFlag.FLYING` set in the "items.xml" file.
+-- 
+-- Collectibles that only grant flight conditionally are manually pruned. Collectibles such as Empty
+-- Vessel should be checked for via the `hasFlyingTemporaryEffect` function.
+-- 
+-- @param pruneConditionalItems Whether or not collectibles that only grant flight conditionally
+-- should be included in the set (like Empty Vessel).
 function ____exports.getFlyingCollectibles(self, pruneConditionalItems)
     local collectiblesWithFlyingCacheFlag = getCollectiblesForCacheFlag(nil, CacheFlag.FLYING)
     local collectiblesWithAllCacheFlag = getCollectiblesForCacheFlag(nil, CacheFlag.ALL)
@@ -36,6 +44,8 @@ function ____exports.getFlyingCollectibles(self, pruneConditionalItems)
     end
     return collectiblesWithFlyingCacheFlag
 end
+--- Returns a set of all of the trinkets that grant flight. (All trinkets that grant flight do so
+-- conditionally, like Bat Wing.)
 function ____exports.getFlyingTrinkets(self)
     return copySet(nil, FLYING_TRINKETS)
 end

package/functions/globals.lua

@@ -4,7 +4,6 @@ local __TS__New = ____lualib.__TS__New
 local __TS__ArraySort = ____lualib.__TS__ArraySort
 local __TS__ArrayForEach = ____lualib.__TS__ArrayForEach
 local ____exports = {}
-local twoDimensionalSort
 local ____debug = require("functions.debug")
 local isLuaDebugEnabled = ____debug.isLuaDebugEnabled
 local ____log = require("functions.log")
@@ -12,15 +11,8 @@ local log = ____log.log
 local ____set = require("functions.set")
 local addSetsToSet = ____set.addSetsToSet
 local copySet = ____set.copySet
-function twoDimensionalSort(self, a, b)
-    if a[1] == nil or b[1] == nil then
-        error("Failed to two-dimensional sort since the first element of the array was undefined.")
-    end
-    if a[1] == b[1] then
-        return 0
-    end
-    return a[1] < b[1] and -1 or 1
-end
+local ____utils = require("functions.utils")
+local twoDimensionalSort = ____utils.twoDimensionalSort
 local DEFAULT_GLOBALS = __TS__New(Set, {
     "ActionTriggers",
     "ActiveSlot",
@@ -190,6 +182,10 @@ local DEFAULT_GLOBALS = __TS__New(Set, {
 })
 local LUA_DEBUG_ADDED_GLOBALS = __TS__New(Set, {"debug", "io", "os", "package"})
 local RACING_PLUS_SANDBOX_ADDED_GLOBALS = __TS__New(Set, {"sandboxTraceback", "sandboxGetTraceback", "getParentFunctionDescription"})
+--- Helper function to get a set containing all of the global variable names that are contained
+-- within the Isaac environment by default.
+-- 
+-- Returns a slightly different set depending on whether the "--luadebug" flag is enabled or not.
 function ____exports.getDefaultGlobals(self)
     local defaultGlobals = copySet(nil, DEFAULT_GLOBALS)
     if isLuaDebugEnabled(nil) then
@@ -198,6 +194,8 @@ function ____exports.getDefaultGlobals(self)
     addSetsToSet(nil, defaultGlobals, RACING_PLUS_SANDBOX_ADDED_GLOBALS)
     return defaultGlobals
 end
+--- Helper function to get an array of any added global variables in the Isaac Lua environment.
+-- Returns an array of key/value tuples.
 function ____exports.getNewGlobals(self)
     local defaultGlobals = ____exports.getDefaultGlobals(nil)
     local newGlobals = {}

package/functions/gridEntity.lua

@@ -44,12 +44,23 @@ function getAllGridEntities(self)
     end
     return gridEntities
 end
+--- Helper function to get the grid index of the top left wall. (This will depend on what the current
+-- room shape is.)
 function ____exports.getTopLeftWallGridIndex(self)
     local room = game:GetRoom()
     local roomShape = room:GetRoomShape()
     local topLeftWallGridIndex = ROOM_SHAPE_TO_TOP_LEFT_WALL_GRID_INDEX_MAP:get(roomShape)
     return topLeftWallGridIndex == nil and DEFAULT_TOP_LEFT_WALL_GRID_INDEX or topLeftWallGridIndex
 end
+--- Helper function to remove a grid entity simply by providing the grid entity object.
+-- 
+-- @param gridEntity The grid entity to remove.
+-- @param updateRoom Optional. Whether or not to update the room after the grid entity is removed.
+-- Default is true. This is generally a good idea because if the room is not
+-- updated, you will be unable to spawn another grid entity on the same tile until
+-- a frame has passed. However, doing this is expensive, since it involves a call
+-- to `Isaac.GetRoomEntities`, so set it to false if you need to invoke this
+-- function multiple times.
 function ____exports.removeGrid(self, gridEntity, updateRoom)
     if updateRoom == nil then
         updateRoom = true
@@ -61,6 +72,12 @@ function ____exports.removeGrid(self, gridEntity, updateRoom)
         roomUpdateSafe(nil)
     end
 end
+--- Helper function to spawn a grid entity with a specific variant.
+-- 
+-- Use this instead of the `Isaac.GridSpawn` method since it:
+-- - handles giving pits collision
+-- - removes existing grid entities on the same tile, if any
+-- - allows you to specify the grid index or the position
 function ____exports.spawnGridWithVariant(self, gridEntityType, variant, gridIndexOrPosition)
     local room = game:GetRoom()
     local ____isVector_result_0
@@ -105,6 +122,9 @@ local BREAKABLE_GRID_ENTITY_TYPES_VARIANTS_BY_EXPLOSIONS = __TS__New(
     Set,
     {(tostring(GridEntityType.STATUE) .. ".") .. tostring(StatueVariant.ANGEL)}
 )
+--- Helper function to convert the grid entity type found in a room XML file to the corresponding
+-- grid entity type and variant normally used by the game. For example, a rock is represented as
+-- 1000.0 in a room XML file, but `GridEntityType.ROCK` is equal to 2.
 function ____exports.convertXMLGridEntityType(self, gridEntityXMLType, gridEntityXMLVariant)
     local gridEntityArray = GRID_ENTITY_XML_MAP:get(gridEntityXMLType)
     if gridEntityArray == nil then
@@ -117,6 +137,11 @@ function ____exports.convertXMLGridEntityType(self, gridEntityXMLType, gridEntit
     end
     return {gridEntityType, gridEntityVariant}
 end
+--- Gets the entities that have a hitbox that overlaps with any part of the square that the grid
+-- entity is on.
+-- 
+-- Note that this function will not work properly in the PostNewRoom callback, since entities do not
+-- have collision yet in that callback.
 function ____exports.getCollidingEntitiesWithGridEntity(self, gridEntity)
     local gridEntityCollisionTopLeft = Vector(gridEntity.Position.X - DISTANCE_OF_GRID_TILE / 2, gridEntity.Position.Y - DISTANCE_OF_GRID_TILE / 2)
     local gridEntityCollisionBottomRight = Vector(gridEntity.Position.X + DISTANCE_OF_GRID_TILE / 2, gridEntity.Position.Y + DISTANCE_OF_GRID_TILE / 2)
@@ -132,6 +157,28 @@ function ____exports.getCollidingEntitiesWithGridEntity(self, gridEntity)
         ) end
     )
 end
+--- Helper function to get every grid entity in the current room.
+-- 
+-- Use this function with no arguments to get every grid entity, or specify a variadic amount of
+-- arguments to match specific grid entity types.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- for (const gridEntity of getGridEntities()) {
+--   print(gridEntity.GetType())
+-- }
+-- ```
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const rocks = getGridEntities(
+--   GridEntityType.ROCK,
+--   GridEntityType.BLOCK,
+--   GridEntityType.ROCK_TINTED,
+-- );
+-- ```
 function ____exports.getGridEntities(self, ...)
     local gridEntityTypes = {...}
     local gridEntities = getAllGridEntities(nil)
@@ -147,6 +194,11 @@ function ____exports.getGridEntities(self, ...)
         end
     )
 end
+--- Helper function to get a map of every grid entity in the current room. The indexes of the map are
+-- equal to the grid index. The values of the map are equal to the grid entities.
+-- 
+-- Use this function with no arguments to get every grid entity, or specify a variadic amount of
+-- arguments to match specific grid entity types.
 function ____exports.getGridEntitiesMap(self, ...)
     local gridEntities = ____exports.getGridEntities(nil, ...)
     local gridEntityMap = __TS__New(Map)
@@ -156,6 +208,7 @@ function ____exports.getGridEntitiesMap(self, ...)
     end
     return gridEntityMap
 end
+--- Helper function to return a string containing the grid entity's type and variant.
 function ____exports.getGridEntityID(self, gridEntity)
     local gridEntityType = gridEntity:GetType()
     local gridEntityVariant = gridEntity:GetVariant()
@@ -195,15 +248,36 @@ function ____exports.isGridEntityBreakableByExplosion(self, gridEntity)
     local gridEntityTypeVariant = (tostring(gridEntityType) .. ".") .. tostring(gridEntityVariant)
     return BREAKABLE_GRID_ENTITY_TYPES_BY_EXPLOSIONS:has(gridEntityType) or BREAKABLE_GRID_ENTITY_TYPES_VARIANTS_BY_EXPLOSIONS:has(gridEntityTypeVariant)
 end
+--- Helper function to see if the provided gridEntity is in its respective broken state. See the
+-- `GRID_ENTITY_TYPE_TO_BROKEN_STATE_MAP` constant for more details.
+-- 
+-- Note that in the case of `GridEntityType.LOCK` (11), the state will turn to being broken before
+-- the actual collision for the entity is removed.
 function ____exports.isGridEntityBroken(self, gridEntity)
     local gridEntityType = gridEntity:GetType()
     local brokenState = GRID_ENTITY_TYPE_TO_BROKEN_STATE_MAP:get(gridEntityType)
     return gridEntity.State == brokenState
 end
+--- Helper function to detect whether a given Void Portal is one that randomly spawns after a boss is
+-- defeated or is one that naturally spawns in the room after Hush. (This is determined by looking
+-- at the VarData of the entity.)
 function ____exports.isPostBossVoidPortal(self, gridEntity)
     local saveState = gridEntity:GetSaveState()
     return saveState.VarData == 1
 end
+--- Helper function to all grid entities in the room except for ones matching the grid entity types
+-- provided.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- removeAllGridEntitiesExceptFor(
+--   GridEntityType.WALL,
+--   GridEntityType.DOOR,
+-- );
+-- ```
+-- 
+-- @returns True if one or more grid entities were removed, false otherwise.
 function ____exports.removeAllGridExcept(self, ...)
     local gridEntityTypes = {...}
     local gridEntityTypeExceptions = __TS__New(Set, gridEntityTypes)
@@ -221,6 +295,20 @@ function ____exports.removeAllGridExcept(self, ...)
     end
     return removedOneOrMoreGridEntities
 end
+--- Helper function to remove all of the grid entities in the room that match the grid entity types
+-- provided.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- removeAllMatchingGridEntities(
+--   GridEntityType.ROCK,
+--   GridEntityType.BLOCK,
+--   GridEntityType.ROCK_TINTED,
+-- );
+-- ```
+-- 
+-- @returns True if one or more grid entities were removed, false otherwise.
 function ____exports.removeAllMatchingGridEntities(self, ...)
     local gridEntities = ____exports.getGridEntities(nil, ...)
     if #gridEntities == 0 then
@@ -232,10 +320,16 @@ function ____exports.removeAllMatchingGridEntities(self, ...)
     roomUpdateSafe(nil)
     return true
 end
+--- Helper function to make a grid entity invisible. This is accomplished by setting its sprite to an
+-- empty/missing PNG file.
+-- 
+-- For more information, see the documentation for the `clearSprite` helper function.
 function ____exports.setGridEntityInvisible(self, gridEntity)
     local sprite = gridEntity:GetSprite()
     clearSprite(nil, sprite)
 end
+--- Helper function to spawn a giant poop. This is performed by spawning each of the four quadrant
+-- grid entities in the appropriate positions.
 function ____exports.spawnGiantPoop(self, topLeftGridIndex)
     local room = game:GetRoom()
     local gridWidth = room:GetGridWidth()
@@ -247,9 +341,20 @@ function ____exports.spawnGiantPoop(self, topLeftGridIndex)
     ____exports.spawnGridWithVariant(nil, GridEntityType.POOP, PoopGridEntityVariant.GIGA_BOTTOM_LEFT, bottomLeftGridIndex)
     ____exports.spawnGridWithVariant(nil, GridEntityType.POOP, PoopGridEntityVariant.GIGA_BOTTOM_RIGHT, bottomRightGridIndex)
 end
+--- Helper function to spawn a grid entity.
+-- 
+-- This function assumes you want to give the grid entity a variant of 0. If you want to specify a
+-- variant, use the `spawnGridWithVariant` helper function instead.
+-- 
+-- Use this instead of the `Isaac.GridSpawn` method since it:
+-- - handles giving pits collision
+-- - removes existing grid entities on the same tile, if any
+-- - allows you to specify either the grid index or the position
 function ____exports.spawnGrid(self, gridEntityType, gridIndexOrPosition)
     return ____exports.spawnGridWithVariant(nil, gridEntityType, 0, gridIndexOrPosition)
 end
+--- Helper function to spawn a Void Portal. This is more complicated than simply spawning a trapdoor
+-- with the appropriate variant, as the game does not give it the correct sprite automatically.
 function ____exports.spawnVoidPortal(self, gridIndex)
     local voidPortal = ____exports.spawnGridWithVariant(nil, GridEntityType.TRAPDOOR, TrapdoorVariant.VOID_PORTAL, gridIndex)
     if voidPortal == nil then

package/functions/gridEntitySpecific.d.ts

@@ -1,4 +1,9 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 /** Helper function to get all of the `GridEntityPit` in the room. */
 export declare function getPits(): GridEntityPit[];
 /** Helper function to get all of the `GridEntityPoop` in the room. */

package/functions/gridEntitySpecific.lua

@@ -7,6 +7,7 @@ local ____cachedClasses = require("cachedClasses")
 local game = ____cachedClasses.game
 local ____gridEntity = require("functions.gridEntity")
 local getGridEntities = ____gridEntity.getGridEntities
+--- Helper function to get all of the `GridEntityPit` in the room.
 function ____exports.getPits(self)
     local gridEntities = getGridEntities(nil)
     local pits = {}
@@ -18,6 +19,7 @@ function ____exports.getPits(self)
     end
     return pits
 end
+--- Helper function to get all of the `GridEntityPoop` in the room.
 function ____exports.getPoops(self)
     local gridEntities = getGridEntities(nil)
     local poops = {}
@@ -29,6 +31,7 @@ function ____exports.getPoops(self)
     end
     return poops
 end
+--- Helper function to get all of the `GridEntityPressurePlate` in the room.
 function ____exports.getPressurePlates(self)
     local gridEntities = getGridEntities(nil)
     local pressurePlates = {}
@@ -40,6 +43,7 @@ function ____exports.getPressurePlates(self)
     end
     return pressurePlates
 end
+--- Helper function to get all of the `GridEntityRock` in the room.
 function ____exports.getRocks(self)
     local gridEntities = getGridEntities(nil)
     local rocks = {}
@@ -51,6 +55,7 @@ function ____exports.getRocks(self)
     end
     return rocks
 end
+--- Helper function to get all of the `GridEntitySpikes` in the room.
 function ____exports.getSpikes(self)
     local gridEntities = getGridEntities(nil)
     local spikes = {}
@@ -62,6 +67,7 @@ function ____exports.getSpikes(self)
     end
     return spikes
 end
+--- Helper function to get all of the `GridEntityTNT` in the room.
 function ____exports.getTNT(self)
     local gridEntities = getGridEntities(nil)
     local tntArray = {}
@@ -73,6 +79,8 @@ function ____exports.getTNT(self)
     end
     return tntArray
 end
+--- Helper function to determine if all of the pressure plates in the current room are pushed.
+-- Returns true if there are no pressure plates in the room.
 function ____exports.isAllPressurePlatesPushed(self)
     local room = game:GetRoom()
     local hasPressurePlates = room:HasTriggerPressurePlates()

package/functions/input.lua

@@ -30,6 +30,7 @@ local MOVEMENT_ACTIONS = {ButtonAction.LEFT, ButtonAction.RIGHT, ButtonAction.UP
 local MOVEMENT_ACTIONS_SET = __TS__New(Set, MOVEMENT_ACTIONS)
 local SHOOTING_ACTIONS = {ButtonAction.SHOOT_LEFT, ButtonAction.SHOOT_RIGHT, ButtonAction.SHOOT_UP, ButtonAction.SHOOT_DOWN}
 local SHOOTING_ACTIONS_SET = __TS__New(Set, SHOOTING_ACTIONS)
+--- Helper function to get the enum name for the specified `Controller` value.
 function ____exports.controllerToString(self, controller)
     local key = Controller[controller]
     if key == nil then
@@ -43,6 +44,7 @@ end
 function ____exports.getShootActions(self)
     return copySet(nil, SHOOTING_ACTIONS_SET)
 end
+--- Iterates over all inputs to determine if a particular button is pressed (i.e. held down).
 function ____exports.isActionPressedOnAnyInput(self, buttonAction)
     local validInputs = erange(nil, MAX_NUM_INPUTS)
     return __TS__ArraySome(
@@ -50,6 +52,8 @@ function ____exports.isActionPressedOnAnyInput(self, buttonAction)
         function(____, input) return Input.IsActionPressed(buttonAction, input) end
     )
 end
+--- Iterates over all inputs to determine if a particular button is triggered (i.e. held down and
+-- then released).
 function ____exports.isActionTriggeredOnAnyInput(self, buttonAction)
     local validInputs = erange(nil, MAX_NUM_INPUTS)
     return __TS__ArraySome(
@@ -57,6 +61,10 @@ function ____exports.isActionTriggeredOnAnyInput(self, buttonAction)
         function(____, input) return Input.IsActionTriggered(buttonAction, input) end
     )
 end
+--- Helper function to see if a particular keyboard key is being pressed down by the player.
+-- 
+-- This function is variadic, meaning you can pass as many keyboard values as you want to check for.
+-- This function will return true if any of the values are pressed.
 function ____exports.isKeyboardPressed(self, ...)
     local keys = {...}
     return __TS__ArraySome(
@@ -64,6 +72,9 @@ function ____exports.isKeyboardPressed(self, ...)
         function(____, key) return Input.IsButtonPressed(key, ControllerIndex.KEYBOARD) end
     )
 end
+--- Helper function to check if one or more modifier keys are being pressed down on the keyboard.
+-- 
+-- A modifier key is defined as shift, control, alt, or Windows.
 function ____exports.isModifierKeyPressed(self)
     return ____exports.isKeyboardPressed(
         nil,

package/functions/isaacAPIClass.d.ts

@@ -1,14 +1,14 @@
 import { IsaacAPIClass } from "../types/private/IsaacAPIClass";
 /**
- * Helper function to get the type of a class from the Isaac API. This is contained within the
- * "__type" metatable key. In this context, the type of the class is equivalent to the name.
+ * Helper function to get the name of a class from the Isaac API. This is contained within the
+ * "__type" metatable key.
  *
- * For example, a `Vector` class is has a type of "Vector".
+ * For example, a `Vector` class is has a name of "Vector".
  *
  * Returns undefined if the object is not of type `userdata` or if the "__type" metatable key does
  * not exist.
  */
-export declare function getIsaacAPIClassType(object: unknown): string | undefined;
+export declare function getIsaacAPIClassName(object: unknown): string | undefined;
 /**
  * Helper function to check if something is an instantiated class from the Isaac API. (All classes
  * from the Isaac API have a type of "userdata" in Lua with a metatable key of "__type" equal to the

package/functions/isaacAPIClass.lua

@@ -1,7 +1,14 @@
 local ____lualib = require("lualib_bundle")
 local __TS__ArrayEvery = ____lualib.__TS__ArrayEvery
 local ____exports = {}
-function ____exports.getIsaacAPIClassType(self, object)
+--- Helper function to get the name of a class from the Isaac API. This is contained within the
+-- "__type" metatable key.
+-- 
+-- For example, a `Vector` class is has a name of "Vector".
+-- 
+-- Returns undefined if the object is not of type `userdata` or if the "__type" metatable key does
+-- not exist.
+function ____exports.getIsaacAPIClassName(self, object)
     local objectType = type(object)
     if objectType ~= "userdata" then
         return nil
@@ -16,14 +23,19 @@ function ____exports.getIsaacAPIClassType(self, object)
     end
     return classType
 end
+--- Helper function to check if something is an instantiated class from the Isaac API. (All classes
+-- from the Isaac API have a type of "userdata" in Lua with a metatable key of "__type" equal to the
+-- name of the class.)
 function ____exports.isIsaacAPIClass(self, object)
-    local isaacAPIClassType = ____exports.getIsaacAPIClassType(nil, object)
+    local isaacAPIClassType = ____exports.getIsaacAPIClassName(nil, object)
     return isaacAPIClassType ~= nil
 end
 function ____exports.isIsaacAPIClassOfType(self, object, classType)
-    local isaacAPIClassType = ____exports.getIsaacAPIClassType(nil, object)
+    local isaacAPIClassType = ____exports.getIsaacAPIClassName(nil, object)
     return isaacAPIClassType == classType or isaacAPIClassType == "const " .. classType
 end
+--- Helper function to check if an instantiated Isaac API class is equal to another one of the same
+-- type. You must provide the list of keys to check for.
 function ____exports.isaacAPIClassEquals(self, object1, object2, keys)
     local table1 = object1
     local table2 = object2

package/functions/jsonHelpers.lua

@@ -8,6 +8,12 @@ end
 local function tryEncode(____table)
     return json.encode(____table)
 end
+--- Converts a JSON string to a Lua table.
+-- 
+-- In most cases, this function will be used for reading data from a "save#.dat" file. If decoding
+-- fails, it will return a blank Lua table instead of throwing an error. (This allows execution to
+-- continue in cases where users have no current save data or have manually removed their existing
+-- save data.)
 function ____exports.jsonDecode(self, jsonString)
     local ok, luaTableOrErrMsg = pcall(tryDecode, jsonString)
     if not ok then
@@ -16,6 +22,11 @@ function ____exports.jsonDecode(self, jsonString)
     end
     return luaTableOrErrMsg
 end
+--- Converts a Lua table to a JSON string.
+-- 
+-- In most cases, this function will be used for writing data to a "save#.dat" file. If encoding
+-- fails, it will throw an error to prevent writing a blank string or corrupted data to a user's
+-- "save#.dat" file.
 function ____exports.jsonEncode(self, ____table)
     local ok, jsonStringOrErrMsg = pcall(tryEncode, ____table)
     if not ok then

package/functions/jsonRoom.d.ts

@@ -1,4 +1,6 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 import { JSONRoom } from "../interfaces/JSONRoom";
 export declare function getJSONRoomOfVariant(jsonRooms: JSONRoom[], variant: int): JSONRoom | undefined;
 export declare function getJSONRoomsOfSubType(jsonRooms: JSONRoom[], subType: int): JSONRoom[];

package/functions/jsonRoom.lua

@@ -66,6 +66,11 @@ function ____exports.getJSONRoomsOfSubType(self, jsonRooms, subType)
         end
     )
 end
+--- Helper function to get a random JSON room from an array of JSON rooms.
+-- 
+-- Note that this function does not simply choose a random element in the provided array; it will
+-- properly account for each room weight using the algorithm from:
+-- https://stackoverflow.com/questions/1761626/weighted-random-numbers
 function ____exports.getRandomJSONRoom(self, jsonRooms, seedOrRNG, verbose)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)

package/functions/kColor.lua

@@ -13,11 +13,17 @@ 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 KColor object.
 function ____exports.isKColor(self, object)
     return isIsaacAPIClassOfType(nil, object, OBJECT_NAME)
 end
 local KEYS = {"Red", "Green", "Blue", "Alpha"}
 OBJECT_NAME = "KColor"
+--- Helper function to copy a `KColor` object.
+-- 
+-- @param kColor The KColor object to copy. In the case of deserialization, this will actually be a
+-- Lua table instead of an instantiated KColor class.
+-- @param serializationType Default is `SerializationType.NONE`.
 function ____exports.copyKColor(self, kColor, serializationType)
     if serializationType == nil then
         serializationType = SerializationType.NONE
@@ -80,9 +86,12 @@ function ____exports.copyKColor(self, kColor, serializationType)
         end
     until true
 end
+--- Returns `KColor(1, 1, 1, 1)`.
 function ____exports.getDefaultKColor(self)
     return KColor(1, 1, 1, 1)
 end
+--- Used to determine is the given table is a serialized `KColor` object created by the save data
+-- manager and/or the `deepCopy` function.
 function ____exports.isSerializedKColor(self, object)
     local objectType = type(object)
     if objectType ~= "table" then

package/functions/language.lua

@@ -1,6 +1,11 @@
 local ____exports = {}
 local ____languageNames = require("objects.languageNames")
 local LANGUAGE_NAMES = ____languageNames.LANGUAGE_NAMES
+--- Helper function to convert the language abbreviation from `Options.Language` to the "full"
+-- language name.
+-- 
+-- For example, if the current language is set to Korean, `Options.Language` will be set to "kr",
+-- and this function will return "Korean".
 function ____exports.getLanguageName(self)
     local languageAbbreviation = Options.Language
     return LANGUAGE_NAMES[languageAbbreviation]