isaacscript-common 2.3.0 → 3.0.0

package/features/saveDataManager/merge.d.ts

@@ -0,0 +1,24 @@
+/// <reference types="typescript-to-lua/language-extensions" />
+/**
+ * `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.
+ */
+export declare function merge(oldObject: LuaTable<AnyNotNil, unknown> | Map<AnyNotNil, unknown> | Set<AnyNotNil>, newTable: LuaTable<AnyNotNil, unknown>, traversalDescription: string): void;

package/features/saveDataManager/merge.lua

@@ -0,0 +1,144 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local __TS__InstanceOf = ____lualib.__TS__InstanceOf
+local Set = ____lualib.Set
+local ____exports = {}
+local mergeArray, mergeTSTLObject, mergeTable
+local ____SerializationBrand = require("enums.private.SerializationBrand")
+local SerializationBrand = ____SerializationBrand.SerializationBrand
+local ____SerializationType = require("enums.SerializationType")
+local SerializationType = ____SerializationType.SerializationType
+local ____array = require("functions.array")
+local isArray = ____array.isArray
+local ____deepCopy = require("functions.deepCopy")
+local deepCopy = ____deepCopy.deepCopy
+local ____log = require("functions.log")
+local log = ____log.log
+local ____serialization = require("functions.serialization")
+local deserializeIsaacAPIClass = ____serialization.deserializeIsaacAPIClass
+local isSerializedIsaacAPIClass = ____serialization.isSerializedIsaacAPIClass
+local ____table = require("functions.table")
+local clearTable = ____table.clearTable
+local ____utils = require("functions.utils")
+local getTraversalDescription = ____utils.getTraversalDescription
+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)
+    end
+    local oldObjectType = type(oldObject)
+    if oldObjectType ~= "table" then
+        error("The first argument given to the merge function is not a table.")
+    end
+    local newTableType = type(newTable)
+    if newTableType ~= "table" then
+        error("The second argument given to the merge function is not a table.")
+    end
+    if isArray(nil, oldObject) and isArray(nil, newTable) then
+        local oldTable = oldObject
+        mergeArray(nil, oldTable, newTable)
+        return
+    end
+    if __TS__InstanceOf(oldObject, Map) or __TS__InstanceOf(oldObject, Set) then
+        mergeTSTLObject(nil, oldObject, newTable, traversalDescription)
+    else
+        mergeTable(nil, oldObject, newTable, traversalDescription)
+    end
+end
+function mergeArray(self, oldArray, newArray)
+    clearTable(nil, oldArray)
+    for key, value in pairs(newArray) do
+        oldArray[key] = value
+    end
+end
+function mergeTSTLObject(self, oldObject, newTable, traversalDescription)
+    oldObject:clear()
+    local convertStringKeysToNumbers = newTable[SerializationBrand.OBJECT_WITH_NUMBER_KEYS] ~= nil
+    for key, value in pairs(newTable) do
+        do
+            if isSerializationBrand(nil, key) then
+                goto __continue12
+            end
+            local keyToUse = key
+            if convertStringKeysToNumbers then
+                local numberKey = tonumber(key)
+                if numberKey == nil then
+                    goto __continue12
+                end
+                keyToUse = numberKey
+            end
+            if __TS__InstanceOf(oldObject, Map) then
+                local valueType = type(value)
+                local valueCopy
+                if valueType == "table" then
+                    valueCopy = deepCopy(nil, value, SerializationType.DESERIALIZE, traversalDescription)
+                else
+                    valueCopy = value
+                end
+                oldObject:set(keyToUse, valueCopy)
+            elseif __TS__InstanceOf(oldObject, Set) then
+                oldObject:add(keyToUse)
+            end
+        end
+        ::__continue12::
+    end
+end
+function mergeTable(self, oldTable, newTable, traversalDescription)
+    for key, value in pairs(newTable) do
+        do
+            if SAVE_DATA_MANAGER_DEBUG then
+                local valueToPrint = value == "" and "(empty string)" or tostring(value)
+                log((("merge is merging: " .. traversalDescription) .. " --> ") .. valueToPrint)
+            end
+            if isSerializationBrand(nil, key) then
+                goto __continue21
+            end
+            if isSerializedIsaacAPIClass(nil, value) then
+                if SAVE_DATA_MANAGER_DEBUG then
+                    log("merge found a serialized Isaac API class.")
+                end
+                local deserializedObject = deserializeIsaacAPIClass(nil, value)
+                oldTable[key] = deserializedObject
+                goto __continue21
+            end
+            local valueType = type(value)
+            if valueType == "table" then
+                local oldValue = oldTable[key]
+                local oldValueType = type(oldValue)
+                if oldValueType ~= "table" then
+                    oldValue = {}
+                    oldTable[key] = oldValue
+                end
+                traversalDescription = getTraversalDescription(nil, key, traversalDescription)
+                ____exports.merge(nil, oldValue, value, traversalDescription)
+            else
+                oldTable[key] = value
+            end
+        end
+        ::__continue21::
+    end
+end
+return ____exports

package/features/saveDataManager/save.d.ts

@@ -0,0 +1,4 @@
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="typescript-to-lua/language-extensions" />
+import { SaveData } from "../../interfaces/SaveData";
+export declare function saveToDisk(mod: Mod, saveDataMap: LuaTable<string, SaveData>, saveDataConditionalFuncMap: Map<string, () => boolean>): void;

package/features/saveDataManager/save.lua

@@ -0,0 +1,44 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local __TS__ObjectKeys = ____lualib.__TS__ObjectKeys
+local ____exports = {}
+local getAllSaveDataToWriteToDisk
+local ____SerializationType = require("enums.SerializationType")
+local SerializationType = ____SerializationType.SerializationType
+local ____deepCopy = require("functions.deepCopy")
+local deepCopy = ____deepCopy.deepCopy
+local ____jsonHelpers = require("functions.jsonHelpers")
+local jsonEncode = ____jsonHelpers.jsonEncode
+local ____log = require("functions.log")
+local log = ____log.log
+local ____constants = require("features.saveDataManager.constants")
+local SAVE_DATA_MANAGER_FEATURE_NAME = ____constants.SAVE_DATA_MANAGER_FEATURE_NAME
+function getAllSaveDataToWriteToDisk(self, saveDataMap, saveDataConditionalFuncMap)
+    local allSaveData = {}
+    for subscriberName, saveData in pairs(saveDataMap) do
+        do
+            local conditionalFunc = saveDataConditionalFuncMap:get(subscriberName)
+            if conditionalFunc ~= nil then
+                local shouldSave = conditionalFunc(nil)
+                if not shouldSave then
+                    goto __continue4
+                end
+            end
+            local saveDataWithoutRoom = {persistent = saveData.persistent, run = saveData.run, level = saveData.level}
+            if #__TS__ObjectKeys(saveDataWithoutRoom) == 0 then
+                goto __continue4
+            end
+            local saveDataCopy = deepCopy(nil, saveDataWithoutRoom, SerializationType.SERIALIZE, subscriberName)
+            allSaveData[subscriberName] = saveDataCopy
+        end
+        ::__continue4::
+    end
+    return allSaveData
+end
+function ____exports.saveToDisk(self, mod, saveDataMap, saveDataConditionalFuncMap)
+    local allSaveData = getAllSaveDataToWriteToDisk(nil, saveDataMap, saveDataConditionalFuncMap)
+    local jsonString = jsonEncode(nil, allSaveData)
+    mod:SaveData(jsonString)
+    log(("The " .. SAVE_DATA_MANAGER_FEATURE_NAME) .. " wrote data to the \"save#.dat\" file.")
+end
+return ____exports

package/features/saveDataManager/serializationBrand.d.ts

@@ -0,0 +1 @@
+export declare function isSerializationBrand(key: unknown): boolean;

package/features/saveDataManager/serializationBrand.lua

@@ -0,0 +1,17 @@
+local ____lualib = require("lualib_bundle")
+local Set = ____lualib.Set
+local __TS__New = ____lualib.__TS__New
+local ____exports = {}
+local ____SerializationBrand = require("enums.private.SerializationBrand")
+local SerializationBrand = ____SerializationBrand.SerializationBrand
+local ____enums = require("functions.enums")
+local getEnumValues = ____enums.getEnumValues
+local SERIALIZATION_BRANDS = getEnumValues(nil, SerializationBrand)
+local SERIALIZATION_BRAND_SET = __TS__New(Set, SERIALIZATION_BRANDS)
+function ____exports.isSerializationBrand(self, key)
+    if type(key) ~= "string" then
+        return false
+    end
+    return SERIALIZATION_BRAND_SET:has(key)
+end
+return ____exports

package/features/sirenHelpers.d.ts

@@ -0,0 +1,18 @@
+import { FamiliarVariant } from "isaac-typescript-definitions";
+/**
+ * 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.
+ */
+export declare function setFamiliarNoSirenSteal(familiarVariant: FamiliarVariant, familiarSubType?: int): void;
+/**
+ * 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.
+ */
+export declare function hasSirenStolenFamiliar(familiar: EntityFamiliar): boolean;

package/features/sirenHelpers.lua

@@ -0,0 +1,82 @@
+local ____lualib = require("lualib_bundle")
+local __TS__ArrayFind = ____lualib.__TS__ArrayFind
+local ____exports = {}
+local postNPCInitSirenHelper, checkReturnFamiliarToPlayer, blacklistEntryExists, getSirenHelper, v
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local EntityType = ____isaac_2Dtypescript_2Ddefinitions.EntityType
+local ModCallback = ____isaac_2Dtypescript_2Ddefinitions.ModCallback
+local ____featuresInitialized = require("featuresInitialized")
+local errorIfFeaturesNotInitialized = ____featuresInitialized.errorIfFeaturesNotInitialized
+local ____entity = require("functions.entity")
+local getEntities = ____entity.getEntities
+local ____exports = require("features.saveDataManager.exports")
+local saveDataManager = ____exports.saveDataManager
+function postNPCInitSirenHelper(self, npc)
+    checkReturnFamiliarToPlayer(nil, npc)
+end
+function checkReturnFamiliarToPlayer(self, npc)
+    if npc.Target == nil then
+        return
+    end
+    local familiar = npc.Target:ToFamiliar()
+    if familiar == nil then
+        return
+    end
+    if blacklistEntryExists(nil, familiar.Variant, familiar.SubType) then
+        npc:Remove()
+        familiar:AddToFollowers()
+    end
+end
+function blacklistEntryExists(self, incomingFamiliarVariant, incomingFamiliarSubType)
+    for ____, ____value in ipairs(v.run.familiarBlacklist) do
+        local familiarVariant = ____value[1]
+        local familiarSubType = ____value[2]
+        if incomingFamiliarVariant == familiarVariant and familiarSubType == incomingFamiliarSubType then
+            return true
+        end
+        if incomingFamiliarVariant == familiarVariant and familiarSubType == nil then
+            return true
+        end
+    end
+    return false
+end
+function getSirenHelper(self, familiar)
+    local familiarPtrHash = GetPtrHash(familiar)
+    local sirenHelpers = getEntities(nil, EntityType.SIREN_HELPER)
+    return __TS__ArrayFind(
+        sirenHelpers,
+        function(____, sirenHelper) return sirenHelper.Target ~= nil and GetPtrHash(sirenHelper.Target) == familiarPtrHash end
+    )
+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
+        return
+    end
+    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
+end
+return ____exports

package/features/taintedLazarusPlayers.d.ts

@@ -0,0 +1,13 @@
+/// <reference types="isaac-typescript-definitions" />
+/**
+ * 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`).
+ */
+export declare function getTaintedLazarusSubPlayer(player: EntityPlayer): EntityPlayer | undefined;

package/features/taintedLazarusPlayers.lua

@@ -0,0 +1,85 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local __TS__New = ____lualib.__TS__New
+local ____exports = {}
+local postPlayerInit, checkDequeue, v
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local ModCallback = ____isaac_2Dtypescript_2Ddefinitions.ModCallback
+local PlayerType = ____isaac_2Dtypescript_2Ddefinitions.PlayerType
+local ____featuresInitialized = require("featuresInitialized")
+local errorIfFeaturesNotInitialized = ____featuresInitialized.errorIfFeaturesNotInitialized
+local ____exports = require("features.saveDataManager.exports")
+local saveDataManager = ____exports.saveDataManager
+function postPlayerInit(self, player)
+    local entityPtr = EntityPtr(player)
+    local character = player:GetPlayerType()
+    if character == PlayerType.LAZARUS_B then
+        local ____v_run_queuedTaintedLazarus_0 = v.run.queuedTaintedLazarus
+        ____v_run_queuedTaintedLazarus_0[#____v_run_queuedTaintedLazarus_0 + 1] = entityPtr
+    elseif character == PlayerType.LAZARUS_2_B then
+        local ____v_run_queuedDeadTaintedLazarus_1 = v.run.queuedDeadTaintedLazarus
+        ____v_run_queuedDeadTaintedLazarus_1[#____v_run_queuedDeadTaintedLazarus_1 + 1] = entityPtr
+    else
+        return
+    end
+    checkDequeue(nil)
+end
+function checkDequeue(self)
+    if #v.run.queuedTaintedLazarus == 0 or #v.run.queuedDeadTaintedLazarus == 0 then
+        return
+    end
+    local taintedLazarusPtr = table.remove(v.run.queuedTaintedLazarus, 1)
+    local deadTaintedLazarusPtr = table.remove(v.run.queuedDeadTaintedLazarus, 1)
+    if taintedLazarusPtr == nil or deadTaintedLazarusPtr == nil then
+        return
+    end
+    local taintedLazarus = taintedLazarusPtr.Ref
+    local deadTaintedLazarus = deadTaintedLazarusPtr.Ref
+    if taintedLazarus == nil or deadTaintedLazarus == nil then
+        return
+    end
+    local taintedLazarusPtrHash = GetPtrHash(taintedLazarus)
+    local deadTaintedLazarusPtrHash = GetPtrHash(deadTaintedLazarus)
+    v.run.subPlayerMap:set(taintedLazarusPtrHash, deadTaintedLazarusPtr)
+    v.run.subPlayerMap:set(deadTaintedLazarusPtrHash, taintedLazarusPtr)
+end
+local FEATURE_NAME = "Tainted Lazarus entity finder"
+v = {run = {
+    queuedTaintedLazarus = {},
+    queuedDeadTaintedLazarus = {},
+    subPlayerMap = __TS__New(Map)
+}}
+---
+-- @internal
+function ____exports.taintedLazarusPlayersInit(self, mod)
+    saveDataManager(
+        nil,
+        "taintedLazarusPlayers",
+        v,
+        function() return false end
+    )
+    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)
+    local entityPtr = v.run.subPlayerMap:get(ptrHash)
+    if entityPtr == nil then
+        return nil
+    end
+    local entity = entityPtr.Ref
+    if entity == nil then
+        return nil
+    end
+    return entity:ToPlayer()
+end
+return ____exports

package/featuresInitialized.d.ts

@@ -0,0 +1 @@
+export {};

package/featuresInitialized.lua

@@ -0,0 +1,20 @@
+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
+return ____exports

package/functions/array.d.ts

@@ -0,0 +1,141 @@
+/// <reference types="isaac-typescript-definitions" />
+/**
+ * Helper function for determining if two arrays contain the exact same elements. Note that this
+ * only performs a shallow comparison.
+ */
+export declare function arrayEquals<T>(array1: T[] | readonly T[], array2: T[] | readonly T[]): boolean;
+/**
+ * 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.
+ */
+export declare function arrayRemove<T>(originalArray: T[] | readonly T[], ...elementsToRemove: T[]): T[];
+/**
+ * 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.
+ */
+export declare function arrayRemoveInPlace<T>(array: T[], ...elementsToRemove: T[]): boolean;
+/**
+ * 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.
+ */
+export declare function arrayRemoveIndex<T>(originalArray: T[] | readonly T[], ...indexesToRemove: int[]): T[];
+/**
+ * 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.
+ */
+export declare function arrayRemoveIndexInPlace<T>(array: T[], ...indexesToRemove: int[]): boolean;
+export declare function arrayToString<T>(array: T[]): string;
+/**
+ * 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.
+ */
+export declare function combineArrays<T>(...arrays: Array<T[] | readonly T[]>): T[];
+/**
+ * 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.
+ */
+export declare function copyArray<T>(oldArray: T[] | readonly T[], numElements?: int): T[];
+export declare function emptyArray<T>(array: T[]): void;
+/**
+ * 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]`.
+ */
+export declare function getArrayIndexes<T>(array: T[] | readonly T[]): int[];
+/**
+ * Helper function to return the last element of an array.
+ *
+ * If the array is empty, this will return undefined.
+ */
+export declare function getLastElement<T>(array: T[]): T | undefined;
+/**
+ * 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.
+ */
+export declare function getRandomArrayElement<T>(array: T[] | readonly T[], seedOrRNG?: Seed | RNG, exceptions?: T[] | readonly T[]): T;
+/**
+ * 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.
+ */
+export declare function getRandomArrayElementAndRemove<T>(array: T[], seedOrRNG?: Seed | RNG, exceptions?: T[] | readonly T[]): T;
+/**
+ * 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()`.
+ */
+export declare function getRandomArrayIndex<T>(array: T[] | readonly T[], seedOrRNG?: Seed | RNG): int;
+/**
+ * Initializes an array with all elements containing the specified default value.
+ *
+ * For example:
+ *
+ * ```ts
+ * const playerTransformations = initArray(false, PlayerForm.NUM_PLAYER_FORMS - 1);
+ * ```
+ */
+export declare function initArray<T>(defaultValue: T, size: int): T[];
+/**
+ * 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)
+ */
+export declare function isArray(object: unknown): object is unknown[];
+/**
+ * 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.
+ */
+export declare function isArrayContiguous(array: int[]): boolean;
+/** Checks if an array is in the provided 2-dimensional array. */
+export declare function isArrayInArray<T>(arrayToMatch: T[] | readonly T[], parentArray: Array<T[] | readonly T[]>): boolean;
+/**
+ * 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()`.
+ */
+export declare function shuffleArray<T>(originalArray: T[] | readonly T[], seedOrRNG?: Seed | RNG): T[];
+/**
+ * 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()`.
+ */
+export declare function shuffleArrayInPlace<T>(array: T[], seedOrRNG?: Seed | RNG): void;
+export declare function sumArray(array: number[] | readonly number[]): number;