isaacscript-common 2.3.0 → 3.0.0

package/functions/array.lua

@@ -0,0 +1,354 @@
+local ____lualib = require("lualib_bundle")
+local __TS__ArrayEvery = ____lualib.__TS__ArrayEvery
+local Set = ____lualib.Set
+local __TS__New = ____lualib.__TS__New
+local __TS__ArrayIndexOf = ____lualib.__TS__ArrayIndexOf
+local __TS__ArraySplice = ____lualib.__TS__ArraySplice
+local __TS__ArrayForEach = ____lualib.__TS__ArrayForEach
+local __TS__ArrayFilter = ____lualib.__TS__ArrayFilter
+local __TS__ArraySort = ____lualib.__TS__ArraySort
+local __TS__ArrayMap = ____lualib.__TS__ArrayMap
+local __TS__ArraySome = ____lualib.__TS__ArraySome
+local __TS__ArrayReduce = ____lualib.__TS__ArrayReduce
+local ____exports = {}
+local ____random = require("functions.random")
+local getRandomInt = ____random.getRandomInt
+local ____rng = require("functions.rng")
+local getRandomSeed = ____rng.getRandomSeed
+local isRNG = ____rng.isRNG
+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)
+    end
+    if #array == 0 then
+        error("Failed to get a random array index since the provided array is empty.")
+    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)
+    end
+    local currentIndex = #array
+    local randomIndex
+    local rng = isRNG(nil, seedOrRNG) and seedOrRNG or newRNG(nil, seedOrRNG)
+    while currentIndex > 0 do
+        currentIndex = currentIndex - 1
+        randomIndex = ____exports.getRandomArrayIndex(nil, array, rng)
+        local ____temp_0 = {array[randomIndex + 1], array[currentIndex + 1]}
+        array[currentIndex + 1] = ____temp_0[1]
+        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
+    end
+    return __TS__ArrayEvery(
+        array1,
+        function(____, array1Element, i)
+            local array2Element = array2[i + 1]
+            return array1Element == array2Element
+        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)
+    local array = {}
+    for ____, element in ipairs(originalArray) do
+        if not elementsToRemoveSet:has(element) then
+            array[#array + 1] = element
+        end
+    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
+    for ____, element in ipairs(elementsToRemove) do
+        local index = __TS__ArrayIndexOf(array, element)
+        if index > -1 then
+            removedOneOrMoreElements = true
+            __TS__ArraySplice(array, index, 1)
+        end
+    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)
+    local array = {}
+    __TS__ArrayForEach(
+        originalArray,
+        function(____, element, i)
+            if not indexesToRemoveSet:has(i) then
+                array[#array + 1] = element
+            end
+        end
+    )
+    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(
+        indexesToRemove,
+        function(____, i) return i >= 0 and i < #array end
+    )
+    __TS__ArraySort(legalIndexes)
+    if #legalIndexes == 0 then
+        return false
+    end
+    do
+        local i = #array - 1
+        while i >= 0 do
+            __TS__ArraySplice(array, i, 1)
+            i = i - 1
+        end
+    end
+    return true
+end
+function ____exports.arrayToString(self, array)
+    if #array == 0 then
+        return "[]"
+    end
+    local strings = __TS__ArrayMap(
+        array,
+        function(____, element) return tostring(element) end
+    )
+    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 = {}
+    for ____, array in ipairs(arrays) do
+        for ____, element in ipairs(array) do
+            elements[#elements + 1] = element
+        end
+    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
+    end
+    local newArray = {}
+    do
+        local i = 0
+        while i < numElements do
+            local oldElement = oldArray[i + 1]
+            if oldElement ~= nil then
+                newArray[#newArray + 1] = oldElement
+            end
+            i = i + 1
+        end
+    end
+    return newArray
+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)
+    end
+    if exceptions == nil then
+        exceptions = {}
+    end
+    if #array == 0 then
+        error("Failed to get a random array element since the provided array is empty.")
+    end
+    local arrayWithoutExceptions = ____exports.arrayRemove(
+        nil,
+        array,
+        table.unpack(exceptions)
+    )
+    local randomIndex = ____exports.getRandomArrayIndex(nil, arrayWithoutExceptions, seedOrRNG)
+    local randomElement = arrayWithoutExceptions[randomIndex + 1]
+    if randomElement == nil then
+        error(("Failed to get a random array element since the random index of " .. tostring(randomIndex)) .. " was not valid.")
+    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)
+    end
+    if exceptions == nil then
+        exceptions = {}
+    end
+    local randomArrayElement = ____exports.getRandomArrayElement(nil, array, seedOrRNG, exceptions)
+    ____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(
+        nil,
+        size,
+        function()
+            array[#array + 1] = defaultValue
+        end
+    )
+    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
+    end
+    local ____table = object
+    local metatable = getmetatable(____table)
+    if metatable ~= nil then
+        return false
+    end
+    local numEntries = 0
+    for key in pairs(____table) do
+        numEntries = numEntries + 1
+        if type(key) ~= "number" then
+            return false
+        end
+    end
+    if numEntries == 0 then
+        return true
+    end
+    do
+        local i = 1
+        while i <= numEntries do
+            local element = ____table[i]
+            if element == nil then
+                return false
+            end
+            i = i + 1
+        end
+    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
+        if lastValue == nil then
+            lastValue = element - 1
+        end
+        if element ~= lastValue - 1 then
+            return false
+        end
+    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)
+    end
+    local array = ____exports.copyArray(nil, originalArray)
+    ____exports.shuffleArrayInPlace(nil, array, seedOrRNG)
+    return array
+end
+function ____exports.sumArray(self, array)
+    return __TS__ArrayReduce(
+        array,
+        function(____, accumulator, element) return accumulator + element end
+    )
+end
+return ____exports

package/functions/benchmark.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="isaac-typescript-definitions" />
+/**
+ * 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.)
+ */
+export declare function benchmark(numTrials: int, ...functions: Array<() => void>): int[];

package/functions/benchmark.lua

@@ -0,0 +1,38 @@
+local ____lualib = require("lualib_bundle")
+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.")
+    local averages = {}
+    __TS__ArrayForEach(
+        functions,
+        function(____, func, i)
+            local totalTimeMilliseconds = 0
+            do
+                local j = 0
+                while j < numTrials do
+                    local startTimeMilliseconds = Isaac.GetTime()
+                    func(nil)
+                    local endTimeMilliseconds = Isaac.GetTime()
+                    local elapsedTimeMilliseconds = endTimeMilliseconds - startTimeMilliseconds
+                    totalTimeMilliseconds = totalTimeMilliseconds + elapsedTimeMilliseconds
+                    j = j + 1
+                end
+            end
+            local averageTimeMilliseconds = totalTimeMilliseconds / numTrials
+            log(((("The average time of the function at index " .. tostring(i)) .. " is: ") .. tostring(averageTimeMilliseconds)) .. " milliseconds")
+            averages[#averages + 1] = averageTimeMilliseconds
+        end
+    )
+    return averages
+end
+return ____exports

package/functions/bitwise.d.ts

@@ -0,0 +1,4 @@
+/// <reference types="isaac-typescript-definitions" />
+export declare function countSetBits(n: int): int;
+export declare function getKBitOfN(k: int, n: int): int;
+export declare function getNumBitsOfN(n: int): int;

package/functions/bitwise.lua

@@ -0,0 +1,21 @@
+local ____exports = {}
+function ____exports.countSetBits(self, n)
+    local count = 0
+    while n > 0 do
+        n = n & n - 1
+        count = count + 1
+    end
+    return count
+end
+function ____exports.getKBitOfN(self, k, n)
+    return n >> k & 1
+end
+function ____exports.getNumBitsOfN(self, n)
+    local numBits = 0
+    while n > 0 do
+        numBits = numBits + 1
+        n = n >> 1
+    end
+    return numBits
+end
+return ____exports

package/functions/boss.d.ts

@@ -0,0 +1,56 @@
+import { EntityType, StageType } from "isaac-typescript-definitions";
+/**
+ * Helper function to get all of the non-dead bosses in the room.
+ *
+ * This function will not include bosses on an internal blacklist, such as Death's scythes or Big
+ * Horn holes.
+ */
+export declare function getAliveBosses(matchingEntityType?: EntityType, matchingVariant?: int, matchingSubType?: int, ignoreFriendly?: boolean): EntityNPC[];
+/**
+ * Helper function to get the set of every boss in the game.
+ *
+ * The set contains strings with the entity type and variant, separated by a period.
+ *
+ * Also see the `getBossSet` and `getCombinedBossSet` functions.
+ */
+export declare function getAllBossesSet(): Set<string>;
+/**
+ * Helper function to get the set of vanilla bosses for a particular stage and stage type
+ * combination.
+ *
+ * The set contains strings with the entity type and variant, separated by a period.
+ *
+ * Also see the `getAllBossesSet` and `getCombinedBossSet` functions.
+ */
+export declare function getBossSet(stage: int, stageType: StageType): ReadonlySet<string> | undefined;
+/** Helper function to get all of the bosses in the room. */
+export declare function getBosses(matchingEntityType?: EntityType, matchingVariant?: int, matchingSubType?: int, ignoreFriendly?: boolean): EntityNPC[];
+/**
+ * Helper function to get the set of vanilla bosses for a particular stage across all of the stage
+ * types. For example, specifying a stage of 2 will return a set with all of the bosses for
+ * Basement, Cellar, Burning Basement, Downpour, and Dross.
+ *
+ * The set contains strings with the entity type and variant, separated by a period.
+ *
+ * Also see the `getAllBossesSet` and `getBossSet` functions.
+ */
+export declare function getCombinedBossSet(stage: int): Set<string> | undefined;
+/** Helper function to check if the provided NPC is a Sin miniboss, such as Sloth or Lust. */
+export declare function isSin(npc: EntityNPC): boolean;
+/**
+ * Helper function to spawn a boss.
+ *
+ * Use this function instead of `spawnNPC` since it handles automatically spawning multiple segments
+ * for multi-segment bosses.
+ *
+ * By default, this will spawn Chub (and his variants) with 3 segments, Lokii with 2 copies,
+ * Gurglings/Turdlings with 2 copies, and other multi-segment bosses with 4 segments. You can
+ * customize this via the "numSegments" argument.
+ */
+export declare function spawnBoss(entityType: EntityType, variant: int, subType: int, position: Vector, velocity?: Readonly<Vector>, spawner?: Entity | undefined, seed?: Seed | undefined, numSegments?: int): EntityNPC;
+/**
+ * Helper function to spawn a boss with a specific seed.
+ *
+ * For more information, see the documentation for the `spawnBoss` function.
+ */
+export declare function spawnBossWithSeed(entityType: EntityType, variant: int, subType: int, position: Vector, seed: Seed, velocity?: Readonly<Vector>, spawner?: Entity | undefined, numSegments?: int): EntityNPC;