isaacscript-common 2.3.2 → 3.0.0

package/features/getCollectibleItemPoolType.lua

@@ -26,10 +26,15 @@ function postPickupInitCollectible(self, pickup)
 end
 local FEATURE_NAME = "get collectible item pool type"
 v = {run = {collectibleItemPoolTypeMap = __TS__New(Map)}}
+---
+-- @internal
 function ____exports.getCollectibleItemPoolTypeInit(self, mod)
     saveDataManager(nil, "getCollectibleItemPoolType", v)
     mod:AddCallback(ModCallback.POST_PICKUP_INIT, postPickupInitCollectible, PickupVariant.COLLECTIBLE)
 end
+--- Helper function to get the item pool type that a given collectible came from. Since there is no
+-- native method in the API to get this, we listen in the PreGetCollectible callback for item pool
+-- types, and then assume that the next spawned collectible will match.
 function ____exports.getCollectibleItemPoolType(self, collectible)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     if not isCollectible(nil, collectible) then

package/features/playerInventory.lua

@@ -94,12 +94,24 @@ v = {run = {
         function() return {} end
     )
 }}
+---
+-- @internal
 function ____exports.playerInventoryInit(self, mod)
     saveDataManager(nil, "playerInventory", v)
     mod:AddCallback(ModCallback.POST_USE_ITEM, useItemD4, CollectibleType.D4)
     mod:AddCallback(ModCallback.POST_GAME_STARTED, postGameStarted)
     mod:AddCallbackCustom(ModCallbackCustom.POST_ITEM_PICKUP, postItemPickup)
 end
+--- Helper function to get all of the collectibles that the player has gotten so far on this run, in
+-- order.
+-- 
+-- Note that this does not include active collectibles that have since been dropped for other
+-- collectibles.
+-- 
+-- In the case of inventory initialization or the case where the player rerolls their build in the
+-- middle of the run (e.g. with D4), the order of the inventory will not correspond to the order
+-- that the items were actually given to the player. In this case, the inventory will be in the
+-- order of the lowest `CollectibleType` to the highest.
 function ____exports.getPlayerInventory(self, player, includeActiveCollectibles)
     if includeActiveCollectibles == nil then
         includeActiveCollectibles = true
@@ -116,6 +128,12 @@ function ____exports.getPlayerInventory(self, player, includeActiveCollectibles)
         function(____, collectibleType) return not isActiveCollectible(nil, collectibleType) end
     )
 end
+--- Helper function to add a collectible to a player. Use this instead of the
+-- `EntityPlayer.AddCollectible` method if you want the collectible that is added to be
+-- automatically tracked by the player inventory tracker feature.
+-- 
+-- You only need to use this function if you are using the inventory feature from the standard
+-- library.
 function ____exports.addCollectible(self, player, collectibleType, charge, firstTimePickingUp, activeSlot, varData)
     player:AddCollectible(
         collectibleType,

package/features/ponyDetection.lua

@@ -38,10 +38,14 @@ end
 local FEATURE_NAME = "pony activation detector"
 FLAGS_WHEN_PONY_IS_ACTIVE = {EntityFlag.NO_KNOCKBACK, EntityFlag.NO_PHYSICS_KNOCKBACK, EntityFlag.NO_DAMAGE_BLINK}
 v = {run = {playersIsPonyActive = __TS__New(Set)}}
+---
+-- @internal
 function ____exports.ponyDetectionInit(self, mod)
     saveDataManager(nil, "ponyDetection", v)
     mod:AddCallbackCustom(ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED, postPEffectUpdateReordered)
 end
+--- Helper function to see if the player is under the effects of A Pony or White Pony charge.
+-- Detecting this is difficult, as the temporary effect will disappear upon entering a new room.
 function ____exports.isPonyActive(self, player)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     return setHasPlayer(nil, v.run.playersIsPonyActive, player)

package/features/preventCollectibleRotation.lua

@@ -40,11 +40,20 @@ function getMapIndex(self, collectible)
 end
 local FEATURE_NAME = "prevent collectible rotation"
 v = {room = {trackedCollectibles = __TS__New(Map)}}
+---
+-- @internal
 function ____exports.preventCollectibleRotationInit(self, mod)
     saveDataManager(nil, "preventCollectibleRotation", v)
     mod:AddCallback(ModCallback.POST_USE_CARD, useCardSoulOfIsaac, Card.SOUL_ISAAC)
     mod:AddCallback(ModCallback.POST_PICKUP_UPDATE, postPickupUpdateCollectible, PickupVariant.COLLECTIBLE)
 end
+--- Helper function to prevent a collectible from being affected by Tainted Isaac's rotation
+-- mechanic. (This mechanic also happens from Glitched Crown and Binge Eater.) This is useful
+-- because quest items that are manually spawned by mods will be automatically be affected by this
+-- mechanic.
+-- 
+-- It is required to pass the intended collectible type to this function since it is possible for
+-- collectibles to rotate on the first frame that they are spawned.
 function ____exports.preventCollectibleRotation(self, collectible, collectibleType)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     if not isCollectible(nil, collectible) then

package/features/runInNFrames.lua

@@ -41,6 +41,8 @@ function checkExecuteQueuedFunctions(self, frameCount, functionTuples)
 end
 local FEATURE_NAME = "run in N frames"
 v = {run = {queuedGameFunctionTuples = {}, queuedRenderFunctionTuples = {}}}
+---
+-- @internal
 function ____exports.runInNFramesInit(self, mod)
     saveDataManager(
         nil,
@@ -51,6 +53,14 @@ function ____exports.runInNFramesInit(self, mod)
     mod:AddCallback(ModCallback.POST_UPDATE, postUpdate)
     mod:AddCallback(ModCallback.POST_RENDER, postRender)
 end
+--- Supply a function to run N game frames from now in the PostUpdate callback.
+-- 
+-- For a usage example, see the documentation for the `runNextGameFrame`, which is used in a similar
+-- way.
+-- 
+-- Note that this function will not handle saving and quitting. If a player saving and quitting
+-- before the deferred function fires would cause a bug in your mod, then you should handle deferred
+-- functions manually using serializable data.
 function ____exports.runInNGameFrames(self, func, gameFrames)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     local gameFrameCount = game:GetFrameCount()
@@ -59,6 +69,14 @@ function ____exports.runInNGameFrames(self, func, gameFrames)
     local ____v_run_queuedGameFunctionTuples_0 = v.run.queuedGameFunctionTuples
     ____v_run_queuedGameFunctionTuples_0[#____v_run_queuedGameFunctionTuples_0 + 1] = tuple
 end
+--- Supply a function to run N render frames from now in the PostRender callback.
+-- 
+-- For a usage example, see the documentation for the `runNextGameFrame`, which is used in a similar
+-- way.
+-- 
+-- Note that this function will not handle saving and quitting. If a player saving and quitting
+-- before the deferred function fires would cause a bug in your mod, then you should handle deferred
+-- functions manually using serializable data.
 function ____exports.runInNRenderFrames(self, func, renderFrames)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     local renderFrameCount = Isaac.GetFrameCount()
@@ -67,10 +85,42 @@ function ____exports.runInNRenderFrames(self, func, renderFrames)
     local ____v_run_queuedRenderFunctionTuples_1 = v.run.queuedRenderFunctionTuples
     ____v_run_queuedRenderFunctionTuples_1[#____v_run_queuedRenderFunctionTuples_1 + 1] = tuple
 end
+--- Supply a function to run on the next PostUpdate callback.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const NUM_EXPLODER_EXPLOSIONS = 5;
+-- 
+-- function useItemExploder(player: EntityPlayer) {
+--   playSound("exploderBegin");
+--   explode(player, NUM_EXPLODER_EXPLOSIONS);
+-- }
+-- 
+-- function explode(player: EntityPlayer, numFramesLeft: int) {
+--   Isaac.Explode(player, undefined, 1);
+--   numFramesLeft -= 1;
+--   if (numFramesLeft === 0) {
+--     runNextFrame(() => {
+--       explode(player, numFramesLeft);
+--     });
+--   }
+-- }
+-- ```
+-- 
+-- Note that this function will not handle saving and quitting. If a player saving and quitting
+-- before the deferred function fires would cause a bug in your mod, then you should handle deferred
+-- functions manually using serializable data.
 function ____exports.runNextGameFrame(self, func)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     ____exports.runInNGameFrames(nil, func, 1)
 end
+--- Supply a function to run on the next PostRender callback.
+-- 
+-- For a usage example, see the documentation for the `runNextGameFrame`, which is used in a similar
+-- way.
+-- 
+-- Note that this function will not handle saving and quitting.
 function ____exports.runNextRenderFrame(self, func)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     ____exports.runInNRenderFrames(nil, func, 1)

package/features/saveDataManager/constants.lua

@@ -1,4 +1,5 @@
 local ____exports = {}
+--- Set this to true to enable more verbosity in the save data manger.
 ____exports.SAVE_DATA_MANAGER_DEBUG = false
 ____exports.SAVE_DATA_MANAGER_FEATURE_NAME = "save data manager"
 return ____exports

package/features/saveDataManager/exports.lua

@@ -18,6 +18,89 @@ local ____maps = require("features.saveDataManager.maps")
 local saveDataConditionalFuncMap = ____maps.saveDataConditionalFuncMap
 local saveDataDefaultsMap = ____maps.saveDataDefaultsMap
 local saveDataMap = ____maps.saveDataMap
+--- This is the entry point to the save data manager, a system which provides two major features:
+-- 
+-- 1. automatic resetting of variables on a new run, on a new level, or on a new room (as desired)
+-- 2. automatic saving and loading of all tracked data to the "save#.dat" file
+-- 
+-- You feed this function with an anonymous object containing your variables, and then it will
+-- automatically manage them for you. (See below for an example.)
+-- 
+-- The save data manager is meant to be called once for each feature of your mod. In other words,
+-- you should not put all of the data for your mod on the same object. Instead, scope your variables
+-- locally to a single file that contains a mod feature, and then call this function to register
+-- them. For example:
+-- 
+-- ```ts
+-- // in file: feature1.ts
+-- import { saveDataManager } from "isaacscript-common";
+-- 
+-- // Declare local variables for this file or feature.
+-- const v = {
+--   // These variables are never reset; manage them yourself at will.
+--   persistent: {
+--     foo1: 0,
+--   },
+-- 
+--   // These variables are reset at the beginning of every run.
+--   run: {
+--     foo2: 0,
+--   },
+-- 
+--   // These variables are reset at the beginning of every level.
+--   level: {
+--     foo3: 0,
+--   },
+-- 
+--   // These variables are reset at the beginning of every room.
+--   room: {
+--     foo4: 0,
+--   },
+-- };
+-- // Every child object is optional; only create the ones that you need.
+-- 
+-- // Register the variables with the save data manager. (We need to provide a string key that
+-- // matches the name of this file.)
+-- function feature1Init() {
+--   saveDataManager("feature1", v);
+-- }
+-- 
+-- // Elsewhere in the file, use your variables.
+-- function feature1Function() {
+--   if (v.run.foo1 > 0) {
+--     // Insert code here.
+--   }
+-- }
+-- ```
+-- 
+-- - Save data is loaded from disk in the `POST_PLAYER_INIT` callback (i.e. the first callback that
+--   can possibly run).
+-- - Save data is recorded to disk in the `PRE_GAME_EXIT` callback.
+-- 
+-- Note that before using the save data manager, you must call the `upgradeMod` function. (Upgrade
+-- your mod before registering any of your own callbacks so that the save data manager will run
+-- before any of your code does.)
+-- 
+-- If you want the save data manager to load data before the `POST_PLAYER_INIT` callback (i.e. in
+-- the main menu), then you should explicitly call the `saveDataManagerLoad` function. (The save
+-- data manager cannot do this on its own because it cannot know when your mod features are finished
+-- initializing.)
+-- 
+-- Finally, some features may have variables that need to be automatically reset per run/level, but
+-- not saved to disk on game exit. (For example, if they contain functions or other non-serializable
+-- data.) For these cases, set the second argument to `() => false`.
+-- 
+-- @param key The name of the file or feature that is submitting data to be managed by the save data
+-- manager. The save data manager will throw an error if the key is already registered.
+-- @param v An object that corresponds to the `SaveData` interface. The object is conventionally
+-- called "v" for brevity. ("v" is short for "local variables").
+-- @param conditionalFunc An optional function to run upon saving this key to disk. For example,
+-- this allows features to only save data to disk if the feature is enabled.
+-- Specify a value of `() => false` to completely disable saving this feature
+-- to disk. Disabling saving to disk is useful if you are using data that is
+-- not serializable. Alternatively, it could be useful if you want to use the
+-- save data manager to automatically reset variables on run/level/room, but
+-- not clutter the the "save#.dat" file with unnecessary keys.
 function ____exports.saveDataManager(self, key, v, conditionalFunc)
     errorIfFeaturesNotInitialized(nil, SAVE_DATA_MANAGER_FEATURE_NAME)
     local keyType = type(key)
@@ -39,18 +122,50 @@ function ____exports.saveDataManager(self, key, v, conditionalFunc)
         saveDataConditionalFuncMap:set(key, conditionalFunc)
     end
 end
+--- The save data manager will automatically load variables from disk at the appropriate times (i.e.
+-- when a new run is started). Use this function to explicitly force the save data manager to load
+-- all of its variables from disk immediately.
+-- 
+-- Obviously, doing this will overwrite the current data, so using this function can potentially
+-- result in lost state.
 function ____exports.saveDataManagerLoad(self)
     errorIfFeaturesNotInitialized(nil, SAVE_DATA_MANAGER_FEATURE_NAME)
     forceSaveDataManagerLoad(nil)
 end
+--- The save data manager will automatically save variables to disk at the appropriate times (i.e.
+-- when the run is exited). Use this function to explicitly force the save data manager to write all
+-- of its variables to disk immediately.
 function ____exports.saveDataManagerSave(self)
     errorIfFeaturesNotInitialized(nil, SAVE_DATA_MANAGER_FEATURE_NAME)
     forceSaveDataManagerSave(nil)
 end
+--- - Sets the global variable of "g" equal to all of the save data variables for this mod.
+-- - Sets the global variable of "gd" equal to all of the save data default variables for this mod.
+-- 
+-- This can make debugging easier, as you can access the variables from the game's debug console.
+-- e.g. `l print(g.feature1.foo)`
 function ____exports.saveDataManagerSetGlobal(self)
     g = saveDataMap
     gd = saveDataDefaultsMap
 end
+--- The save data manager will automatically reset variables at the appropriate times (i.e. when a
+-- player enters a new room). Use this function to explicitly force the save data manager to reset a
+-- specific variable group.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const v = {
+--   room: {
+--     foo: 123,
+--   },
+-- };
+-- 
+-- saveDataManager("file1", v);
+-- 
+-- // Then, later on, to explicit reset all of the "room" variables:
+-- saveDataManagerReset("file1", "room");
+-- ```
 function ____exports.saveDataManagerReset(self, key, childObjectKey)
     errorIfFeaturesNotInitialized(nil, SAVE_DATA_MANAGER_FEATURE_NAME)
     local keyType = type(key)

package/features/saveDataManager/main.lua

@@ -97,6 +97,8 @@ function clearAndCopyAllElements(self, oldTable, newTable)
 end
 mod = nil
 loadedDataOnThisRun = false
+---
+-- @internal
 function ____exports.saveDataManagerInit(self, incomingMod)
     mod = incomingMod
     mod:AddCallback(ModCallback.POST_PLAYER_INIT, postPlayerInit)
@@ -104,12 +106,16 @@ function ____exports.saveDataManagerInit(self, incomingMod)
     mod:AddCallback(ModCallback.POST_NEW_LEVEL, postNewLevel)
     mod:AddCallbackCustom(ModCallbackCustom.POST_NEW_ROOM_EARLY, postNewRoomEarly)
 end
+---
+-- @internal
 function ____exports.forceSaveDataManagerSave(self)
     if mod == nil then
         return
     end
     saveToDisk(nil, mod, saveDataMap, saveDataConditionalFuncMap)
 end
+---
+-- @internal
 function ____exports.forceSaveDataManagerLoad(self)
     if mod == nil then
         return

package/features/saveDataManager/maps.lua

@@ -2,6 +2,9 @@ local ____lualib = require("lualib_bundle")
 local Map = ____lualib.Map
 local __TS__New = ____lualib.__TS__New
 local ____exports = {}
+--- The save data map is indexed by subscriber name. We use Lua tables instead of TypeScriptToLua
+-- Maps for the master map so that we can access the variables via the in-game console when
+-- debugging. (TSTL Maps don't expose the map keys as normal keys.)
 ____exports.saveDataMap = {}
 ____exports.saveDataDefaultsMap = {}
 ____exports.saveDataConditionalFuncMap = __TS__New(Map)

package/features/saveDataManager/merge.lua

@@ -25,6 +25,26 @@ local ____constants = require("features.saveDataManager.constants")
 local SAVE_DATA_MANAGER_DEBUG = ____constants.SAVE_DATA_MANAGER_DEBUG
 local ____serializationBrand = require("features.saveDataManager.serializationBrand")
 local isSerializationBrand = ____serializationBrand.isSerializationBrand
+--- `merge` takes the values from a new table and recursively merges them into an old object (while
+-- performing appropriate deserialization).
+-- 
+-- It supports the following object types:
+-- 
+-- - `LuaTable` / basic TSTL objects
+-- - TSTL `Map`
+-- - TSTL `Set`
+-- - TSTL classes
+-- - `DefaultMap`
+-- - Isaac `Color` objects
+-- - Isaac `KColor` objects
+-- - Isaac `RNG` objects
+-- - Isaac `Vector` objects
+-- 
+-- Since it is common for a variable to have a type of `something | null`, we must iterate over the
+-- new object and copy over all of the values. (A value of null transpiles to nil, which means the
+-- table key does not exist.) The consequence of this is that it can copy over old variables that
+-- are no longer used in the code, or copy over old variables of a different type, which can cause
+-- run-time errors. In such cases, users will have to manually delete their save data.
 function ____exports.merge(self, oldObject, newTable, traversalDescription)
     if SAVE_DATA_MANAGER_DEBUG then
         log("merge is traversing: " .. traversalDescription)

package/features/sirenHelpers.lua

@@ -50,10 +50,18 @@ function getSirenHelper(self, familiar)
 end
 local FEATURE_NAME = "siren helpers"
 v = {run = {familiarBlacklist = {}}}
+---
+-- @internal
 function ____exports.sirenHelpersInit(self, mod)
     saveDataManager(nil, "sirenHelpers", v)
     mod:AddCallback(ModCallback.POST_NPC_INIT, postNPCInitSirenHelper, EntityType.SIREN_HELPER)
 end
+--- Blacklists a familiar from being stolen by The Siren boss. This should be called once at the
+-- beginning of every run.
+-- 
+-- @param familiarVariant The familiar variant to blacklist.
+-- @param familiarSubType The sub-type to blacklist. Optional. The default is to blacklist all
+-- sub-types of the given variant.
 function ____exports.setFamiliarNoSirenSteal(self, familiarVariant, familiarSubType)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     if blacklistEntryExists(nil, familiarVariant, familiarSubType) then
@@ -62,6 +70,11 @@ function ____exports.setFamiliarNoSirenSteal(self, familiarVariant, familiarSubT
     local ____v_run_familiarBlacklist_0 = v.run.familiarBlacklist
     ____v_run_familiarBlacklist_0[#____v_run_familiarBlacklist_0 + 1] = {familiarVariant, familiarSubType}
 end
+--- Helper function to check if the Siren boss has stolen a familiar. Some familiars may need to
+-- behave differently when under The Siren's control (e.g. if they auto-target enemies).
+-- 
+-- @param familiar The familiar to be checked.
+-- @returns Returns whether the familiar has been stolen by The Siren.
 function ____exports.hasSirenStolenFamiliar(self, familiar)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     return getSirenHelper(nil, familiar) ~= nil

package/features/taintedLazarusPlayers.lua

@@ -49,6 +49,8 @@ v = {run = {
     queuedDeadTaintedLazarus = {},
     subPlayerMap = __TS__New(Map)
 }}
+---
+-- @internal
 function ____exports.taintedLazarusPlayersInit(self, mod)
     saveDataManager(
         nil,
@@ -58,6 +60,15 @@ function ____exports.taintedLazarusPlayersInit(self, mod)
     )
     mod:AddCallback(ModCallback.POST_PLAYER_INIT, postPlayerInit)
 end
+--- Helper function to get the other version of Tainted Lazarus.
+-- 
+-- - On Tainted Lazarus, returns the player object for Dead Tainted Lazarus.
+-- - On Dead Tainted Lazarus, returns the player object for Tainted Lazarus.
+-- - Returns undefined if player object retrieval failed for any reason.
+-- 
+-- If you call the `EntityPlayer.Exists` method on the returned object, it will return false.
+-- However, you can still call the other methods like you normally would (e.g.
+-- `EntityPlayer.AddCollectible`).
 function ____exports.getTaintedLazarusSubPlayer(self, player)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     local ptrHash = GetPtrHash(player)

package/featuresInitialized.lua

@@ -1,13 +1,19 @@
 local ____exports = {}
 local featuresInitialized = false
+---
+-- @internal
 function ____exports.areFeaturesInitialized(self)
     return featuresInitialized
 end
+---
+-- @internal
 function ____exports.errorIfFeaturesNotInitialized(self, featureName)
     if not ____exports.areFeaturesInitialized(nil) then
         error(("The " .. featureName) .. " is not initialized. You must first upgrade your mod object by calling the \"upgradeMod\" function.")
     end
 end
+---
+-- @internal
 function ____exports.setFeaturesInitialized(self)
     featuresInitialized = true
 end

package/functions/array.lua

@@ -20,6 +20,11 @@ local newRNG = ____rng.newRNG
 local ____utils = require("functions.utils")
 local erange = ____utils.erange
 local ____repeat = ____utils["repeat"]
+--- Helper function to get a random index from the provided array.
+-- 
+-- @param array The array to get the index from.
+-- @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+-- `RNG.Next` method will be called. Default is `getRandomSeed()`.
 function ____exports.getRandomArrayIndex(self, array, seedOrRNG)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -29,6 +34,13 @@ function ____exports.getRandomArrayIndex(self, array, seedOrRNG)
     end
     return getRandomInt(nil, 0, #array - 1, seedOrRNG)
 end
+--- Shuffles the provided array in-place using the Fisher-Yates algorithm.
+-- 
+-- From: https://stackoverflow.com/questions/2450954/how-to-randomize-shuffle-a-javascript-array
+-- 
+-- @param array The array to shuffle.
+-- @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()`.
 function ____exports.shuffleArrayInPlace(self, array, seedOrRNG)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -44,6 +56,8 @@ function ____exports.shuffleArrayInPlace(self, array, seedOrRNG)
         array[randomIndex + 1] = ____temp_0[2]
     end
 end
+--- Helper function for determining if two arrays contain the exact same elements. Note that this
+-- only performs a shallow comparison.
 function ____exports.arrayEquals(self, array1, array2)
     if #array1 ~= #array2 then
         return false
@@ -56,6 +70,11 @@ function ____exports.arrayEquals(self, array1, array2)
         end
     )
 end
+--- Shallow copies and removes the specified element(s) from the array. Returns the copied array. If
+-- the specified element(s) are not found in the array, it will simply return a shallow copy of the
+-- array.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to remove N elements.
 function ____exports.arrayRemove(self, originalArray, ...)
     local elementsToRemove = {...}
     local elementsToRemoveSet = __TS__New(Set, elementsToRemove)
@@ -67,6 +86,10 @@ function ____exports.arrayRemove(self, originalArray, ...)
     end
     return array
 end
+--- Removes the specified element(s) from the array. If the specified element(s) are not found in the
+-- array, this function will do nothing. Returns whether or not one or more elements were removed.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to remove N elements.
 function ____exports.arrayRemoveInPlace(self, array, ...)
     local elementsToRemove = {...}
     local removedOneOrMoreElements = false
@@ -79,6 +102,11 @@ function ____exports.arrayRemoveInPlace(self, array, ...)
     end
     return removedOneOrMoreElements
 end
+--- Shallow copies and removes the elements at the specified indexes from the array. Returns the
+-- copied array. If the specified indexes are not found in the array, it will simply return a
+-- shallow copy of the array.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to remove N elements.
 function ____exports.arrayRemoveIndex(self, originalArray, ...)
     local indexesToRemove = {...}
     local indexesToRemoveSet = __TS__New(Set, indexesToRemove)
@@ -93,6 +121,11 @@ function ____exports.arrayRemoveIndex(self, originalArray, ...)
     )
     return array
 end
+--- Removes the elements at the specified indexes from the array. If the specified indexes are not
+-- found in the array, this function will do nothing. Returns whether or not one or more elements
+-- were removed.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to remove N elements.
 function ____exports.arrayRemoveIndexInPlace(self, array, ...)
     local indexesToRemove = {...}
     local legalIndexes = __TS__ArrayFilter(
@@ -123,6 +156,11 @@ function ____exports.arrayToString(self, array)
     local commaSeparatedStrings = table.concat(strings, ", ")
     return ("[" .. commaSeparatedStrings) .. "]"
 end
+--- Helper function to combine two or more arrays. Returns a new array that is the composition of all
+-- of the specified arrays.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to combine N arrays. Note
+-- that this will only perform a shallow copy of the array elements.
 function ____exports.combineArrays(self, ...)
     local arrays = {...}
     local elements = {}
@@ -133,6 +171,11 @@ function ____exports.combineArrays(self, ...)
     end
     return elements
 end
+--- Helper function to perform a shallow copy.
+-- 
+-- @param oldArray The array to copy.
+-- @param numElements Optional. If specified, will only copy the first N elements. By default, the
+-- entire array will be copied.
 function ____exports.copyArray(self, oldArray, numElements)
     if numElements == nil then
         numElements = #oldArray
@@ -153,12 +196,24 @@ end
 function ____exports.emptyArray(self, array)
     __TS__ArraySplice(array, 0, #array)
 end
+--- Helper function to get an array containing the indexes of an array.
+-- 
+-- For example, an array of `["Apple", "Banana"]` would return an array of `[0, 1]`.
 function ____exports.getArrayIndexes(self, array)
     return erange(nil, #array)
 end
+--- Helper function to return the last element of an array.
+-- 
+-- If the array is empty, this will return undefined.
 function ____exports.getLastElement(self, array)
     return array[#array]
 end
+--- Helper function to get a random element from the provided array.
+-- 
+-- @param array The array to get an element from.
+-- @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+-- `RNG.Next` method will be called. Default is `getRandomSeed()`.
+-- @param exceptions Optional. An array of elements to skip over if selected.
 function ____exports.getRandomArrayElement(self, array, seedOrRNG, exceptions)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -181,6 +236,13 @@ function ____exports.getRandomArrayElement(self, array, seedOrRNG, exceptions)
     end
     return randomElement
 end
+--- Helper function to get a random element from the provided array. Once the random element is
+-- decided, it is then removed from the array (in-place).
+-- 
+-- @param array The array to get an element from.
+-- @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+-- `RNG.Next` method will be called. Default is `getRandomSeed()`.
+-- @param exceptions Optional. An array of elements to skip over if selected.
 function ____exports.getRandomArrayElementAndRemove(self, array, seedOrRNG, exceptions)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -192,6 +254,13 @@ function ____exports.getRandomArrayElementAndRemove(self, array, seedOrRNG, exce
     ____exports.arrayRemoveInPlace(nil, array, randomArrayElement)
     return randomArrayElement
 end
+--- Initializes an array with all elements containing the specified default value.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const playerTransformations = initArray(false, PlayerForm.NUM_PLAYER_FORMS - 1);
+-- ```
 function ____exports.initArray(self, defaultValue, size)
     local array = {}
     ____repeat(
@@ -203,6 +272,11 @@ function ____exports.initArray(self, defaultValue, size)
     )
     return array
 end
+--- Since Lua uses tables for every non-primitive data structure, it is non-trivial to determine if a
+-- particular table is being used as an array. `isArray` returns true if:
+-- 
+-- - the table contains all numerical indexes that are contiguous, starting at 1
+-- - the table has no keys (i.e. an "empty" table)
 function ____exports.isArray(self, object)
     if type(object) ~= "table" then
         return false
@@ -234,6 +308,9 @@ function ____exports.isArray(self, object)
     end
     return true
 end
+--- Helper function to see if every element in the array is N + 1.
+-- 
+-- For example, `[2, 3, 4]` would return true, and `[2, 3, 5]` would return false.
 function ____exports.isArrayContiguous(self, array)
     local lastValue
     for ____, element in ipairs(array) do
@@ -246,12 +323,20 @@ function ____exports.isArrayContiguous(self, array)
     end
     return true
 end
+--- Checks if an array is in the provided 2-dimensional array.
 function ____exports.isArrayInArray(self, arrayToMatch, parentArray)
     return __TS__ArraySome(
         parentArray,
         function(____, element) return ____exports.arrayEquals(nil, element, arrayToMatch) end
     )
 end
+--- Shallow copies and shuffles the array using the Fisher-Yates algorithm. Returns the copied array.
+-- 
+-- From: https://stackoverflow.com/questions/2450954/how-to-randomize-shuffle-a-javascript-array
+-- 
+-- @param originalArray The array to shuffle.
+-- @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()`.
 function ____exports.shuffleArray(self, originalArray, seedOrRNG)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)

package/functions/benchmark.lua

@@ -3,6 +3,12 @@ local __TS__ArrayForEach = ____lualib.__TS__ArrayForEach
 local ____exports = {}
 local ____log = require("functions.log")
 local log = ____log.log
+--- Helper function to benchmark the performance of a function.
+-- 
+-- This function is variadic, which means that you can supply as many as you want to benchmark.
+-- 
+-- @returns An array containing the average time in milliseconds for each function. (This will also
+-- be printed to the log.)
 function ____exports.benchmark(self, numTrials, ...)
     local functions = {...}
     log(((("Benchmarking " .. tostring(#functions)) .. " function(s) with ") .. tostring(numTrials)) .. " trials.")