isaacscript-common 2.3.0 → 3.0.0

package/functions/isaacAPIClass.lua

@@ -0,0 +1,47 @@
+local ____lualib = require("lualib_bundle")
+local __TS__ArrayEvery = ____lualib.__TS__ArrayEvery
+local ____exports = {}
+--- 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.
+-- 
+-- For example, a `Vector` class is has a type of "Vector".
+-- 
+-- Returns undefined if the object is not of type `userdata` or if the "__type" metatable key does
+-- not exist.
+function ____exports.getIsaacAPIClassType(self, object)
+    local objectType = type(object)
+    if objectType ~= "userdata" then
+        return nil
+    end
+    local metatable = getmetatable(object)
+    if metatable == nil then
+        return nil
+    end
+    local classType = metatable.__type
+    if type(classType) ~= "string" then
+        return nil
+    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)
+    return isaacAPIClassType ~= nil
+end
+function ____exports.isIsaacAPIClassOfType(self, object, classType)
+    local isaacAPIClassType = ____exports.getIsaacAPIClassType(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
+    return __TS__ArrayEvery(
+        keys,
+        function(____, key) return table1[key] == table2[key] end
+    )
+end
+return ____exports

package/functions/jsonHelpers.d.ts

@@ -0,0 +1,18 @@
+/// <reference types="typescript-to-lua/language-extensions" />
+/**
+ * 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.)
+ */
+export declare function jsonDecode(jsonString: string): LuaTable<AnyNotNil, unknown>;
+/**
+ * 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.
+ */
+export declare function jsonEncode(table: unknown): string;

package/functions/jsonHelpers.lua

@@ -0,0 +1,37 @@
+local ____exports = {}
+local json = require("@NoResolution:json")
+local ____log = require("functions.log")
+local logError = ____log.logError
+local function tryDecode(jsonString)
+    return json.decode(jsonString)
+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
+        logError("Failed to convert the JSON string to a Lua table: " .. jsonString)
+        return {}
+    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
+        error("Failed to convert the Lua table to JSON: " .. jsonStringOrErrMsg)
+    end
+    return jsonStringOrErrMsg
+end
+return ____exports

package/functions/jsonRoom.d.ts

@@ -0,0 +1,12 @@
+/// <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[];
+/**
+ * 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
+ */
+export declare function getRandomJSONRoom(jsonRooms: JSONRoom[], seedOrRNG?: Seed | RNG, verbose?: boolean): JSONRoom;

package/functions/jsonRoom.lua

@@ -0,0 +1,91 @@
+local ____lualib = require("lualib_bundle")
+local __TS__ArrayFilter = ____lualib.__TS__ArrayFilter
+local __TS__ArrayMap = ____lualib.__TS__ArrayMap
+local ____exports = {}
+local getTotalWeightOfJSONRooms, getJSONRoomWithChosenWeight
+local ____array = require("functions.array")
+local sumArray = ____array.sumArray
+local ____log = require("functions.log")
+local log = ____log.log
+local ____random = require("functions.random")
+local getRandomFloat = ____random.getRandomFloat
+local ____rng = require("functions.rng")
+local getRandomSeed = ____rng.getRandomSeed
+function getTotalWeightOfJSONRooms(self, jsonRooms)
+    local weights = __TS__ArrayMap(
+        jsonRooms,
+        function(____, jsonRoom)
+            local roomWeightString = jsonRoom["$"].weight
+            local roomWeight = tonumber(roomWeightString)
+            if roomWeight == nil then
+                error(("Failed to parse the weight of a JSON room: " .. roomWeightString) .. ".")
+            end
+            return roomWeight
+        end
+    )
+    return sumArray(nil, weights)
+end
+function getJSONRoomWithChosenWeight(self, jsonRooms, chosenWeight)
+    for ____, jsonRoom in ipairs(jsonRooms) do
+        local roomWeightString = jsonRoom["$"].weight
+        local roomWeight = tonumber(roomWeightString)
+        if roomWeight == nil then
+            error("Failed to parse the weight of a JSON room: " .. roomWeightString)
+        end
+        if chosenWeight < roomWeight then
+            return jsonRoom
+        end
+        chosenWeight = chosenWeight - roomWeight
+    end
+    return error("Failed to get a JSON room with chosen weight: " .. tostring(chosenWeight))
+end
+function ____exports.getJSONRoomOfVariant(self, jsonRooms, variant)
+    local jsonRoomsOfVariant = __TS__ArrayFilter(
+        jsonRooms,
+        function(____, jsonRoom)
+            local roomVariantString = jsonRoom["$"].variant
+            local roomVariant = tonumber(roomVariantString)
+            return roomVariant == variant
+        end
+    )
+    if #jsonRoomsOfVariant == 0 then
+        return nil
+    end
+    if #jsonRoomsOfVariant == 1 then
+        return jsonRoomsOfVariant[1]
+    end
+    return error(((("Found " .. tostring(#jsonRoomsOfVariant)) .. " JSON rooms with a variant of ") .. tostring(variant)) .. ", when there should only be 1.")
+end
+function ____exports.getJSONRoomsOfSubType(self, jsonRooms, subType)
+    return __TS__ArrayFilter(
+        jsonRooms,
+        function(____, jsonRoom)
+            local roomSubTypeString = jsonRoom["$"].subtype
+            local roomSubType = tonumber(roomSubTypeString)
+            return roomSubType == 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)
+    end
+    if verbose == nil then
+        verbose = false
+    end
+    local totalWeight = getTotalWeightOfJSONRooms(nil, jsonRooms)
+    if verbose then
+        log("Total weight of the JSON rooms provided: " .. tostring(totalWeight))
+    end
+    local chosenWeight = getRandomFloat(nil, 0, totalWeight, seedOrRNG)
+    if verbose then
+        log("Randomly chose weight for JSON room: " .. tostring(chosenWeight))
+    end
+    return getJSONRoomWithChosenWeight(nil, jsonRooms, chosenWeight)
+end
+return ____exports

package/functions/kColor.d.ts

@@ -0,0 +1,31 @@
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="typescript-to-lua/language-extensions" />
+import { SerializationType } from "../enums/SerializationType";
+declare type SerializedKColor = LuaTable<string, unknown> & {
+    __serializedKColorBrand: void;
+};
+interface CopyKColorReturn {
+    [SerializationType.NONE]: KColor;
+    [SerializationType.SERIALIZE]: SerializedKColor;
+    [SerializationType.DESERIALIZE]: 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`.
+ */
+export declare function copyKColor<K extends KColor | SerializedKColor, S extends SerializationType>(kColor: K, serializationType: S): CopyKColorReturn[S];
+export declare function copyKColor<K extends KColor | SerializedKColor>(kColor: K): CopyKColorReturn[SerializationType.NONE];
+/** Returns `KColor(1, 1, 1, 1)`. */
+export declare function getDefaultKColor(): KColor;
+/** Helper function to check if something is an instantiated KColor object. */
+export declare function isKColor(object: unknown): object is KColor;
+/**
+ * Used to determine is the given table is a serialized `KColor` object created by the save data
+ * manager and/or the `deepCopy` function.
+ */
+export declare function isSerializedKColor(object: unknown): object is SerializedKColor;
+export declare function kColorEquals(kColor1: KColor, kColor2: KColor): boolean;
+export {};

package/functions/kColor.lua

@@ -0,0 +1,110 @@
+local ____exports = {}
+local OBJECT_NAME
+local ____SerializationBrand = require("enums.private.SerializationBrand")
+local SerializationBrand = ____SerializationBrand.SerializationBrand
+local ____SerializationType = require("enums.SerializationType")
+local SerializationType = ____SerializationType.SerializationType
+local ____isaacAPIClass = require("functions.isaacAPIClass")
+local isaacAPIClassEquals = ____isaacAPIClass.isaacAPIClassEquals
+local isIsaacAPIClassOfType = ____isaacAPIClass.isIsaacAPIClassOfType
+local ____table = require("functions.table")
+local copyValuesToTable = ____table.copyValuesToTable
+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
+    end
+    repeat
+        local ____switch3 = serializationType
+        local ____cond3 = ____switch3 == SerializationType.NONE
+        if ____cond3 then
+            do
+                if not ____exports.isKColor(nil, kColor) then
+                    error(((("Failed to copy a " .. OBJECT_NAME) .. " object since the provided object was not a userdata ") .. OBJECT_NAME) .. " class.")
+                end
+                return KColor(kColor.Red, kColor.Green, kColor.Blue, kColor.Alpha)
+            end
+        end
+        ____cond3 = ____cond3 or ____switch3 == SerializationType.SERIALIZE
+        if ____cond3 then
+            do
+                if not ____exports.isKColor(nil, kColor) then
+                    error(((("Failed to serialize a " .. OBJECT_NAME) .. " object since the provided object was not a userdata ") .. OBJECT_NAME) .. " class.")
+                end
+                local kColorTable = {}
+                copyValuesToTable(nil, kColor, KEYS, kColorTable)
+                kColorTable[SerializationBrand.K_COLOR] = ""
+                return kColorTable
+            end
+        end
+        ____cond3 = ____cond3 or ____switch3 == SerializationType.DESERIALIZE
+        if ____cond3 then
+            do
+                local kColorType = type(kColor)
+                if ____exports.isKColor(nil, kColor) or kColorType ~= "table" then
+                    error(("Failed to deserialize a " .. OBJECT_NAME) .. " object since the provided object was not a Lua table.")
+                end
+                local r, g, b, a = table.unpack(getNumbersFromTable(
+                    nil,
+                    kColor,
+                    OBJECT_NAME,
+                    table.unpack(KEYS)
+                ))
+                if r == nil then
+                    error(("Failed to deserialize a " .. OBJECT_NAME) .. " object since the provided object did not have a value for: r")
+                end
+                if g == nil then
+                    error(("Failed to deserialize a " .. OBJECT_NAME) .. " object since the provided object did not have a value for: g")
+                end
+                if b == nil then
+                    error(("Failed to deserialize a " .. OBJECT_NAME) .. " object since the provided object did not have a value for: b")
+                end
+                if a == nil then
+                    error(("Failed to deserialize a " .. OBJECT_NAME) .. " object since the provided object did not have a value for: a")
+                end
+                return KColor(r, g, b, a)
+            end
+        end
+        do
+            do
+                return ensureAllCases(nil, serializationType)
+            end
+        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
+        return false
+    end
+    local ____table = object
+    return tableHasKeys(
+        nil,
+        ____table,
+        table.unpack(KEYS)
+    ) and ____table[SerializationBrand.K_COLOR] ~= nil
+end
+function ____exports.kColorEquals(self, kColor1, kColor2)
+    return isaacAPIClassEquals(nil, kColor1, kColor2, KEYS)
+end
+return ____exports

package/functions/language.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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".
+ */
+export declare function getLanguageName(): string;

package/functions/language.lua

@@ -0,0 +1,13 @@
+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]
+end
+return ____exports

package/functions/level.d.ts

@@ -0,0 +1 @@
+export declare function fillLevelWithRedRooms(): void;

package/functions/level.lua

@@ -0,0 +1,29 @@
+local ____exports = {}
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local DoorSlot = ____isaac_2Dtypescript_2Ddefinitions.DoorSlot
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+local ____enums = require("functions.enums")
+local getEnumValues = ____enums.getEnumValues
+local ____rooms = require("functions.rooms")
+local getNumRooms = ____rooms.getNumRooms
+local getRooms = ____rooms.getRooms
+local isDoorSlotValidAtGridIndexForRedRoom = ____rooms.isDoorSlotValidAtGridIndexForRedRoom
+function ____exports.fillLevelWithRedRooms(self)
+    local level = game:GetLevel()
+    local numRooms
+    repeat
+        do
+            local rooms = getRooms(nil)
+            numRooms = #rooms
+            for ____, roomDescriptor in ipairs(rooms) do
+                for ____, doorSlot in ipairs(getEnumValues(nil, DoorSlot)) do
+                    if isDoorSlotValidAtGridIndexForRedRoom(nil, doorSlot, roomDescriptor.GridIndex) then
+                        level:MakeRedRoomDoor(roomDescriptor.GridIndex, doorSlot)
+                    end
+                end
+            end
+        end
+    until not (numRooms ~= getNumRooms(nil))
+end
+return ____exports

package/functions/log.d.ts

@@ -0,0 +1,78 @@
+/// <reference types="typescript-to-lua/language-extensions" />
+import { DamageFlag, EntityFlag, EntityType, GridEntityType, ProjectileFlag, TearFlag, UseFlag } from "isaac-typescript-definitions";
+/**
+ * Helper function to prefix the name of the function and the line number before a debug message.
+ */
+export declare function getDebugPrependString(msg: string, numParentFunctions?: number): string;
+/**
+ * Helper function to avoid typing out `Isaac.DebugString()`.
+ *
+ * If you have the "--luadebug" launch flag turned on or the Racing+ sandbox enabled, then this
+ * function will also prepend the function name and the line number before the string.
+ */
+export declare function log(this: void, msg: string): void;
+export declare function logArray<T>(this: void, array: T[]): void;
+export declare function logColor(this: void, color: Color): void;
+/** Helper function for printing out every damage flag that is turned on. Useful when debugging. */
+export declare function logDamageFlags(this: void, flags: DamageFlag | BitFlags<DamageFlag>): void;
+export declare function logEffects(this: void, player: EntityPlayer): void;
+/** Helper function for printing out every entity (or filtered entity) in the current room. */
+export declare function logEntities(this: void, includeBackgroundEffects: boolean, entityTypeFilter?: EntityType): void;
+/** Helper function for printing out every entity flag that is turned on. Useful when debugging. */
+export declare function logEntityFlags(this: void, flags: EntityFlag | BitFlags<EntityFlag>): void;
+export declare function logEntityID(this: void, entity: Entity): void;
+/**
+ * Helper function to log an error message and also print it to the console for better visibility.
+ *
+ * This is useful in situations where using the `error` function would be dangerous (since it
+ * prevents all of the subsequent code in the callback from running).
+ */
+export declare function logError(this: void, msg: string): void;
+/** Helper function for printing out every flag that is turned on. Useful when debugging. */
+export declare function logFlags<T extends BitFlag | BitFlag128>(this: void, flags: T | BitFlags<T>, flagEnum: Record<string, T>, description?: string): void;
+/**
+ * Helper function for printing out every game state flag that is turned on. Useful when debugging.
+ */
+export declare function logGameStateFlags(this: void): void;
+/**
+ * Helper function for printing out every grid entity (or filtered grid entity) in the current room.
+ */
+export declare function logGridEntities(this: void, includeWalls: boolean, gridEntityTypeFilter?: GridEntityType): void;
+export declare function logKColor(this: void, kColor: KColor): void;
+/**
+ * Helper function for printing out every level state flag that is turned on. Useful when debugging.
+ */
+export declare function logLevelStateFlags(this: void): void;
+export declare function logMap(this: void, map: Map<AnyNotNil, unknown>): void;
+export declare function logPlayerHealth(this: void, player: EntityPlayer): void;
+/**
+ * Helper function for printing out every projectile flag that is turned on. Useful when debugging.
+ */
+export declare function logProjectileFlags(this: void, flags: ProjectileFlag | BitFlags<ProjectileFlag>): void;
+/** Helper function for logging information about the current room. */
+export declare function logRoom(this: void): void;
+/**
+ * Helper function for printing out every seed effect (i.e. Easter Egg) that is turned on for the
+ * particular run.
+ */
+export declare function logSeedEffects(this: void): void;
+export declare function logSet(this: void, set: Set<AnyNotNil>): void;
+/** Helper function for logging every sound effect that is currently playing. */
+export declare function logSounds(this: void): void;
+export declare function logTable(this: void, table: unknown, parentTables?: number): void;
+/** Helper function for printing out every tear flag that is turned on. Useful when debugging. */
+export declare function logTearFlags(this: void, flags: TearFlag | BitFlags<TearFlag>): void;
+/** Helper function for printing out every use flag that is turned on. Useful when debugging. */
+export declare function logUseFlags(this: void, flags: UseFlag | BitFlags<UseFlag>): void;
+/**
+ * Helper function to enumerate all of the properties of a "userdata" object (i.e. an object from
+ * the Isaac API).
+ */
+export declare function logUserdata(this: void, userdata: unknown): void;
+export declare function logVector(this: void, vector: Vector, round?: boolean): void;
+/**
+ * Converts every `isaacscript-common` function that begins with "log" to a global function.
+ *
+ * This is useful when printing out variables from the in-game debug console.
+ */
+export declare function setLogFunctionsGlobal(): void;