isaacscript-common 2.3.0 → 3.0.0

package/functions/utils.lua

@@ -0,0 +1,182 @@
+local ____lualib = require("lualib_bundle")
+local __TS__StringReplace = ____lualib.__TS__StringReplace
+local __TS__StringSubstr = ____lualib.__TS__StringSubstr
+local __TS__TypeOf = ____lualib.__TS__TypeOf
+local ____exports = {}
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local RenderMode = ____isaac_2Dtypescript_2Ddefinitions.RenderMode
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+local HEX_STRING_LENGTH = 6
+--- Helper function to get type safety on a switch statement.
+-- 
+-- Very useful to be future-safe against people adding values to a type or an enum.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- enum Situation {
+--   ONE,
+--   TWO,
+--   THREE,
+--   // FOUR, // If we uncomment this line, the program will no longer compile
+-- }
+-- 
+-- function handleSituation(situation: Situation) {
+--   switch (situation) {
+--     case Situation.ONE: {
+--       return 41;
+--     }
+-- 
+--     case Situation.TWO: {
+--       return 68;
+--     }
+-- 
+--     case Situation.THREE: {
+--       return 12;
+--     }
+-- 
+--     default: {
+--       return ensureAllCases(situation);
+--     }
+--   }
+-- }
+-- ```
+____exports.ensureAllCases = function(____, obj) return obj end
+--- Helper function to return an array with the elements from start to end. It is inclusive at the
+-- start and exclusive at the end. (The "e" stands for exclusive.)
+-- 
+-- For example, `erange(1, 3)` will return `[1, 2]`.
+-- 
+-- If only one argument is specified, then it will assume that the start is 0.
+function ____exports.erange(self, start, ____end)
+    if ____end == nil then
+        ____end = start
+        start = 0
+    end
+    local array = {}
+    do
+        local i = start
+        while i < ____end do
+            array[#array + 1] = i
+            i = i + 1
+        end
+    end
+    return array
+end
+--- Helper function to log what is happening in functions that recursively move through nested data
+-- structures.
+function ____exports.getTraversalDescription(self, key, traversalDescription)
+    if traversalDescription ~= "" then
+        traversalDescription = traversalDescription .. " --> "
+    end
+    traversalDescription = traversalDescription .. tostring(key)
+    return traversalDescription
+end
+--- Converts a hex string like "#33aa33" to a KColor object.
+-- 
+-- @param hexString A hex string like "#ffffff" or "ffffff". (The "#" character is optional.)
+function ____exports.hexToKColor(self, hexString, alpha)
+    hexString = __TS__StringReplace(hexString, "#", "")
+    if #hexString ~= HEX_STRING_LENGTH then
+        error(("Hex strings must be of length " .. tostring(HEX_STRING_LENGTH)) .. ".")
+    end
+    local rString = __TS__StringSubstr(hexString, 0, 2)
+    local R = tonumber("0x" .. rString)
+    if R == nil then
+        error(("Failed to convert `0x" .. rString) .. "` to a number.")
+    end
+    local gString = __TS__StringSubstr(hexString, 2, 2)
+    local G = tonumber("0x" .. gString)
+    if G == nil then
+        error(("Failed to convert `0x" .. gString) .. "` to a number.")
+    end
+    local bString = __TS__StringSubstr(hexString, 4, 2)
+    local B = tonumber("0x" .. bString)
+    if B == nil then
+        error(("Failed to convert `0x" .. bString) .. "` to a number.")
+    end
+    local base = 255
+    return KColor(R / base, G / base, B / base, alpha)
+end
+--- Helper function to return an array with the elements from start to end, inclusive. (The "i"
+-- stands for inclusive.)
+-- 
+-- For example, `irange(1, 3)` will return `[1, 2, 3]`.
+-- 
+-- If only one argument is specified, then it will assume that the start is 0.
+function ____exports.irange(self, start, ____end)
+    if ____end == nil then
+        ____end = start
+        start = 0
+    end
+    local array = {}
+    do
+        local i = start
+        while i <= ____end do
+            array[#array + 1] = i
+            i = i + 1
+        end
+    end
+    return array
+end
+function ____exports.isPrimitive(self, variable)
+    local ____type = __TS__TypeOf(variable)
+    return ____type == "boolean" or ____type == "number" or ____type == "string"
+end
+--- Since this is a UI element, we do not want to draw it in water reflections. `renderOffset` will
+-- be a non-zero value in reflections.
+function ____exports.isReflectionRender(self)
+    local room = game:GetRoom()
+    local renderMode = room:GetRenderMode()
+    return renderMode == RenderMode.WATER_REFLECT
+end
+--- Helper function to print something to the in-game console. Use this instead of invoking the
+-- `Isaac.ConsoleOutput` method directly because it will automatically insert a newline at the end
+-- of the message (which `Isaac.ConsoleOutput` does not do by default).
+function ____exports.printConsole(self, msg)
+    Isaac.ConsoleOutput(msg .. "\n")
+end
+--- Helper function to print whether something was enabled or disabled to the in-game console.
+function ____exports.printEnabled(self, enabled, description)
+    local enabledText = enabled and "Enabled" or "Disabled"
+    ____exports.printConsole(nil, ((enabledText .. " ") .. description) .. ".")
+end
+--- Helper function to repeat code N times. This is faster to type and cleaner than using a for loop.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const player = Isaac.GetPlayer();
+-- repeat(10, () => {
+--   player.AddCollectible(CollectibleType.STEVEN);
+-- });
+-- ```
+-- 
+-- The repeated function is passed the index of the iteration, if needed:
+-- 
+-- ```ts
+-- repeat(3, (i) => {
+--   print(i); // Prints "0", "1", "2"
+-- });
+-- ```
+____exports["repeat"] = function(self, n, func)
+    do
+        local i = 0
+        while i < n do
+            func(nil, i)
+            i = i + 1
+        end
+    end
+end
+--- Helper function to signify that the enclosing code block is not yet complete. Using this function
+-- is similar to writing a "TODO" comment, but it has the benefit of preventing ESLint errors due to
+-- early returns.
+-- 
+-- When you see this function, it simply means that the programmer intends to add in more code to
+-- this spot later.
+-- 
+-- This function does not actually do anything. (It is an "empty" function.)
+function ____exports.todo(self)
+end
+return ____exports

package/functions/vector.d.ts

@@ -0,0 +1,32 @@
+/// <reference types="typescript-to-lua/language-extensions" />
+import { Direction } from "isaac-typescript-definitions";
+import { SerializationType } from "../enums/SerializationType";
+declare type SerializedVector = LuaTable<string, unknown> & {
+    __serializedVectorBrand: void;
+};
+interface CopyVectorReturn {
+    [SerializationType.NONE]: Vector;
+    [SerializationType.SERIALIZE]: SerializedVector;
+    [SerializationType.DESERIALIZE]: Vector;
+}
+/**
+ * Helper function to copy a `Vector` object.
+ *
+ * @param vector The vector to copy. In the case of deserialization, this will actually be a Lua
+ *               table instead of an instantiated Vector class.
+ * @param serializationType Default is `SerializationType.NONE`.
+ */
+export declare function copyVector<V extends Vector | SerializedVector, S extends SerializationType>(vector: V, serializationType: S): CopyVectorReturn[S];
+export declare function copyVector<V extends Vector | SerializedVector>(vector: V): CopyVectorReturn[SerializationType.NONE];
+/**
+ * Used to determine is the given table is a serialized `Vector` object created by the save data
+ * manager and/or the `deepCopy` function.
+ */
+export declare function isSerializedVector(object: unknown): object is SerializedVector;
+/** Helper function to check if something is an instantiated Vector object. */
+export declare function isVector(object: unknown): object is Vector;
+export declare function vectorEquals(vector1: Vector, vector2: Vector): boolean;
+/** Helper function for finding out which way a vector is pointing. */
+export declare function vectorToDirection(vector: Vector): Direction;
+export declare function vectorToString(vector: Vector, round?: boolean): string;
+export {};

package/functions/vector.lua

@@ -0,0 +1,127 @@
+local ____exports = {}
+local OBJECT_NAME
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local Direction = ____isaac_2Dtypescript_2Ddefinitions.Direction
+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 Vector object.
+function ____exports.isVector(self, object)
+    return isIsaacAPIClassOfType(nil, object, OBJECT_NAME)
+end
+local KEYS = {"X", "Y"}
+OBJECT_NAME = "Vector"
+--- Helper function to copy a `Vector` object.
+-- 
+-- @param vector The vector to copy. In the case of deserialization, this will actually be a Lua
+-- table instead of an instantiated Vector class.
+-- @param serializationType Default is `SerializationType.NONE`.
+function ____exports.copyVector(self, vector, 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.isVector(nil, vector) then
+                    error(((("Failed to copy a " .. OBJECT_NAME) .. " object since the provided object was not a userdata ") .. OBJECT_NAME) .. " class.")
+                end
+                return Vector(vector.X, vector.Y)
+            end
+        end
+        ____cond3 = ____cond3 or ____switch3 == SerializationType.SERIALIZE
+        if ____cond3 then
+            do
+                if not ____exports.isVector(nil, vector) then
+                    error(((("Failed to serialize a " .. OBJECT_NAME) .. " object since the provided object was not a userdata ") .. OBJECT_NAME) .. " class.")
+                end
+                local vectorTable = {}
+                copyValuesToTable(nil, vector, KEYS, vectorTable)
+                vectorTable[SerializationBrand.VECTOR] = ""
+                return vectorTable
+            end
+        end
+        ____cond3 = ____cond3 or ____switch3 == SerializationType.DESERIALIZE
+        if ____cond3 then
+            do
+                local vectorType = type(vector)
+                if ____exports.isVector(nil, vector) or vectorType ~= "table" then
+                    error(("Failed to deserialize a " .. OBJECT_NAME) .. " object since the provided object was not a Lua table.")
+                end
+                local x, y = table.unpack(getNumbersFromTable(
+                    nil,
+                    vector,
+                    OBJECT_NAME,
+                    table.unpack(KEYS)
+                ))
+                if x == nil then
+                    error(("Failed to deserialize a " .. OBJECT_NAME) .. " object since the provided object did not have a value for: x")
+                end
+                if y == nil then
+                    error(("Failed to deserialize a " .. OBJECT_NAME) .. " object since the provided object did not have a value for: y")
+                end
+                return Vector(x, y)
+            end
+        end
+        do
+            do
+                return ensureAllCases(nil, serializationType)
+            end
+        end
+    until true
+end
+--- Used to determine is the given table is a serialized `Vector` object created by the save data
+-- manager and/or the `deepCopy` function.
+function ____exports.isSerializedVector(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.VECTOR] ~= nil
+end
+function ____exports.vectorEquals(self, vector1, vector2)
+    return isaacAPIClassEquals(nil, vector1, vector2, KEYS)
+end
+--- Helper function for finding out which way a vector is pointing.
+function ____exports.vectorToDirection(self, vector)
+    local degrees = vector:GetAngleDegrees()
+    if degrees > -45 and degrees < 45 then
+        return Direction.RIGHT
+    end
+    if degrees >= 45 and degrees <= 135 then
+        return Direction.DOWN
+    end
+    if degrees <= -45 and degrees >= -135 then
+        return Direction.UP
+    end
+    if degrees > 135 or degrees < -135 then
+        return Direction.LEFT
+    end
+    return Direction.NO_DIRECTION
+end
+function ____exports.vectorToString(self, vector, round)
+    if round == nil then
+        round = false
+    end
+    local x = round and math.floor(vector.X + 0.5) or vector.X
+    local y = round and math.floor(vector.Y + 0.5) or vector.Y
+    return ((("(" .. tostring(x)) .. ", ") .. tostring(y)) .. ")"
+end
+return ____exports

package/index.d.ts

@@ -0,0 +1,129 @@
+export * from "./cachedClasses";
+export { initCustomDoor, spawnCustomDoor, } from "./callbacks/postCustomDoorEnter";
+export { forceNewLevelCallback, forceNewRoomCallback, } from "./callbacks/reorderedCallbacks";
+export * from "./classes/DefaultMap";
+export * from "./classes/ModUpgraded";
+export * from "./constants";
+export * from "./constantsFirstLast";
+export * from "./enums/HealthType";
+export * from "./enums/ModCallbackCustom";
+export * from "./enums/PocketItemType";
+export * from "./enums/SerializationType";
+export { ConversionHeartSubType, registerCharacterHealthConversion, } from "./features/characterHealthConversion";
+export { registerCharacterStats } from "./features/characterStats";
+export * from "./features/debugDisplay/exports";
+export { deployJSONRoom, deployRandomJSONRoom, emptyRoom, } from "./features/deployJSONRoom";
+export { disableAllInputs, disableAllInputsExceptFor, disableMovementInputs, disableShootingInputs, enableAllInputs, enableAllInputsExceptFor, } from "./features/disableInputs";
+export { disableAllSound, enableAllSound } from "./features/disableSound";
+export { addConsoleCommand, enableExtraConsoleCommands, removeConsoleCommand, } from "./features/extraConsoleCommands/init";
+export { removeFadeIn, restoreFadeIn } from "./features/fadeInRemover";
+export { disableFastReset, enableFastReset } from "./features/fastReset";
+export { forgottenSwitch } from "./features/forgottenSwitch";
+export { getCollectibleItemPoolType } from "./features/getCollectibleItemPoolType";
+export { addCollectible, getPlayerInventory } from "./features/playerInventory";
+export * from "./features/ponyDetection";
+export { preventCollectibleRotation } from "./features/preventCollectibleRotation";
+export { runInNGameFrames, runInNRenderFrames, runNextGameFrame, runNextRenderFrame, } from "./features/runInNFrames";
+export * from "./features/saveDataManager/exports";
+export { hasSirenStolenFamiliar, setFamiliarNoSirenSteal, } from "./features/sirenHelpers";
+export { getTaintedLazarusSubPlayer } from "./features/taintedLazarusPlayers";
+export * from "./functions/array";
+export * from "./functions/benchmark";
+export * from "./functions/bitwise";
+export * from "./functions/boss";
+export * from "./functions/cacheFlag";
+export * from "./functions/cards";
+export * from "./functions/challenges";
+export * from "./functions/character";
+export * from "./functions/charge";
+export * from "./functions/chargeBar";
+export * from "./functions/collectibleCacheFlag";
+export * from "./functions/collectibles";
+export * from "./functions/collectibleSet";
+export * from "./functions/collectibleTag";
+export * from "./functions/color";
+export * from "./functions/debug";
+export { deepCopy } from "./functions/deepCopy";
+export { deepCopyTests } from "./functions/deepCopyTests";
+export * from "./functions/direction";
+export * from "./functions/doors";
+export * from "./functions/easing";
+export * from "./functions/eden";
+export * from "./functions/entity";
+export * from "./functions/entitySpecific";
+export * from "./functions/entityTypes";
+export * from "./functions/enums";
+export * from "./functions/familiars";
+export * from "./functions/flag";
+export * from "./functions/flying";
+export * from "./functions/globals";
+export * from "./functions/gridEntity";
+export * from "./functions/gridEntitySpecific";
+export * from "./functions/input";
+export * from "./functions/isaacAPIClass";
+export * from "./functions/jsonHelpers";
+export * from "./functions/jsonRoom";
+export * from "./functions/kColor";
+export * from "./functions/language";
+export * from "./functions/level";
+export * from "./functions/log";
+export * from "./functions/map";
+export * from "./functions/math";
+export { mergeTests } from "./functions/mergeTests";
+export * from "./functions/npc";
+export * from "./functions/pickups";
+export * from "./functions/pickupVariants";
+export * from "./functions/pills";
+export * from "./functions/player";
+export * from "./functions/playerDataStructures";
+export * from "./functions/playerHealth";
+export * from "./functions/playerIndex";
+export * from "./functions/pocketItems";
+export * from "./functions/positionVelocity";
+export * from "./functions/random";
+export * from "./functions/revive";
+export * from "./functions/rng";
+export * from "./functions/roomData";
+export * from "./functions/roomGrid";
+export * from "./functions/rooms";
+export * from "./functions/roomShape";
+export * from "./functions/run";
+export * from "./functions/seeds";
+export * from "./functions/serialization";
+export * from "./functions/set";
+export * from "./functions/sound";
+export * from "./functions/spawnCollectible";
+export * from "./functions/sprite";
+export * from "./functions/stage";
+export * from "./functions/string";
+export * from "./functions/table";
+export * from "./functions/tears";
+export * from "./functions/transformations";
+export * from "./functions/trinketCacheFlag";
+export * from "./functions/trinketGive";
+export * from "./functions/trinkets";
+export * from "./functions/tstlClass";
+export * from "./functions/ui";
+export * from "./functions/utils";
+export * from "./functions/vector";
+export * from "./interfaces/AddCallbackParameterCustom";
+export * from "./interfaces/ChargeBarSprites";
+export * from "./interfaces/JSONDoor";
+export * from "./interfaces/JSONEntity";
+export * from "./interfaces/JSONRoom";
+export * from "./interfaces/JSONRooms";
+export * from "./interfaces/JSONSpawn";
+export * from "./interfaces/PlayerHealth";
+export * from "./interfaces/PocketItemDescription";
+export * from "./interfaces/SaveData";
+export * from "./interfaces/TrinketSituation";
+export * from "./maps/cardMap";
+export * from "./maps/characterMap";
+export * from "./maps/pillEffectMap";
+export * from "./maps/roomTypeMap";
+export * from "./objects/colors";
+export * from "./types/AnyEntity";
+export * from "./types/CollectibleIndex";
+export * from "./types/PickingUpItem";
+export * from "./types/PlayerIndex";
+export * from "./upgradeMod";