isaacscript-common 2.3.0 → 2.3.1

package/functions/enums.d.ts

@@ -0,0 +1,80 @@
+/// <reference types="isaac-typescript-definitions" />
+/**
+ * TypeScriptToLua will transpile TypeScript enums to Lua tables that have a double mapping. Thus,
+ * when you iterate over them, you will get both the names of the enums and the values of the enums,
+ * in a random order. Use this helper function to get the entries of the enum with the reverse
+ * mappings filtered out.
+ *
+ * This function will return the enum values in a sorted order, which may not necessarily be the
+ * same order as which they were declared in.
+ *
+ * This function will work properly for both number enums and string enums. (Reverse mappings are
+ * not created for string enums.)
+ *
+ * Also see the `getEnumKeys` and `getEnumValues` helper functions.
+ *
+ * For a more in depth explanation, see:
+ * https://isaacscript.github.io/gotchas#iterating-over-enums
+ */
+export declare function getEnumEntries<T>(transpiledEnum: T): Array<[key: string, value: T[keyof T]]>;
+/**
+ * TypeScriptToLua will transpile TypeScript enums to Lua tables that have a double mapping. Thus,
+ * when you iterate over them, you will get both the names of the enums and the values of the enums,
+ * in a random order. If all you need are the keys of an enum, use this helper function.
+ *
+ * This function will return the enum keys in a sorted order, which may not necessarily be the same
+ * order as which they were declared in.
+ *
+ * This function will work properly for both number enums and string enums. (Reverse mappings are
+ * not created for string enums.)
+ *
+ * Also see the `getEnumEntries` and `getEnumValues` helper functions.
+ *
+ * For a more in depth explanation, see:
+ * https://isaacscript.github.io/gotchas#iterating-over-enums
+ */
+export declare function getEnumKeys<T>(transpiledEnum: T): string[];
+/** Helper function to get the amount of entries inside of an enum. */
+export declare function getEnumLength<T>(transpiledEnum: T): int;
+/**
+ * TypeScriptToLua will transpile TypeScript enums to Lua tables that have a double mapping. Thus,
+ * when you iterate over them, you will get both the names of the enums and the values of the enums,
+ * in a random order. If all you need are the values of an enum, use this helper function.
+ *
+ * This function will return the enum values in a sorted order, which may not necessarily be the
+ * same order as which they were declared in.
+ *
+ * This function will work properly for both number enums and string enums. (Reverse mappings are
+ * not created for string enums.)
+ *
+ * Also see the `getEnumEntries` and `getEnumKeys` helper functions.
+ *
+ * For a more in depth explanation, see:
+ * https://isaacscript.github.io/gotchas#iterating-over-enums
+ */
+export declare function getEnumValues<T>(transpiledEnum: T): Array<T[keyof T]>;
+export declare function getLastEnumValue<T>(transpiledEnum: T): T[keyof T];
+/**
+ * Helper function to get a random value from the provided enum.
+ *
+ * @param transpiledEnum The enum to get the value 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 getRandomEnumValue<T>(transpiledEnum: T, seedOrRNG?: Seed | RNG, exceptions?: Array<T[keyof T]> | ReadonlyArray<T[keyof T]>): T[keyof T];
+/**
+ * Helper function to check every value of a custom enum for -1. This is helpful as a run-time check
+ * because many methods of the Isaac class return -1 if they fail.
+ *
+ * For example:
+ *
+ * ```ts
+ * enum EntityTypeCustom {
+ *   FOO = Isaac.GetEntityTypeByName("Foo"),
+ * }
+ *
+ * validateCustomEnum("EntityTypeCustom", EntityTypeCustom);
+ * ```
+ */
+export declare function validateCustomEnum(transpiledEnumName: string, transpiledEnum: unknown): void;

package/functions/enums.lua

@@ -0,0 +1,85 @@
+local ____lualib = require("lualib_bundle")
+local __TS__ArraySort = ____lualib.__TS__ArraySort
+local __TS__ArrayMap = ____lualib.__TS__ArrayMap
+local ____exports = {}
+local ____array = require("functions.array")
+local getRandomArrayElement = ____array.getRandomArrayElement
+local ____rng = require("functions.rng")
+local getRandomSeed = ____rng.getRandomSeed
+function ____exports.getEnumEntries(self, transpiledEnum)
+    local enumEntries = {}
+    for key, value in pairs(transpiledEnum) do
+        if type(key) == "string" then
+            enumEntries[#enumEntries + 1] = {key, value}
+        end
+    end
+    __TS__ArraySort(
+        enumEntries,
+        function(____, ____bindingPattern0, ____bindingPattern1)
+            local value1
+            local _key1 = ____bindingPattern0[1]
+            value1 = ____bindingPattern0[2]
+            local value2
+            local _key2 = ____bindingPattern1[1]
+            value2 = ____bindingPattern1[2]
+            return value1 < value2 and -1 or (value1 > value2 and 1 or 0)
+        end
+    )
+    return enumEntries
+end
+function ____exports.getEnumKeys(self, transpiledEnum)
+    local enumEntries = ____exports.getEnumEntries(nil, transpiledEnum)
+    return __TS__ArrayMap(
+        enumEntries,
+        function(____, ____bindingPattern0)
+            local key
+            key = ____bindingPattern0[1]
+            local _value = ____bindingPattern0[2]
+            return key
+        end
+    )
+end
+function ____exports.getEnumLength(self, transpiledEnum)
+    local enumEntries = ____exports.getEnumEntries(nil, transpiledEnum)
+    return #enumEntries
+end
+function ____exports.getEnumValues(self, transpiledEnum)
+    local enumEntries = ____exports.getEnumEntries(nil, transpiledEnum)
+    return __TS__ArrayMap(
+        enumEntries,
+        function(____, ____bindingPattern0)
+            local value
+            local _key = ____bindingPattern0[1]
+            value = ____bindingPattern0[2]
+            return value
+        end
+    )
+end
+function ____exports.getLastEnumValue(self, transpiledEnum)
+    local enumValues = ____exports.getEnumValues(nil, transpiledEnum)
+    local lastElement = enumValues[#enumValues]
+    if lastElement == nil then
+        error("Failed to get the last value from an enum since the enum was empty.")
+    end
+    return lastElement
+end
+function ____exports.getRandomEnumValue(self, transpiledEnum, seedOrRNG, exceptions)
+    if seedOrRNG == nil then
+        seedOrRNG = getRandomSeed(nil)
+    end
+    if exceptions == nil then
+        exceptions = {}
+    end
+    local enumValues = ____exports.getEnumValues(nil, transpiledEnum)
+    return getRandomArrayElement(nil, enumValues, seedOrRNG, exceptions)
+end
+function ____exports.validateCustomEnum(self, transpiledEnumName, transpiledEnum)
+    for ____, ____value in ipairs(____exports.getEnumEntries(nil, transpiledEnum)) do
+        local key = ____value[1]
+        local value = ____value[2]
+        if value == -1 then
+            error((("Failed to find custom enum value: " .. transpiledEnumName) .. ".") .. key)
+        end
+    end
+end
+return ____exports

package/functions/familiars.d.ts

@@ -0,0 +1,60 @@
+import { CollectibleType, FamiliarVariant } from "isaac-typescript-definitions";
+/**
+ * Helper function to add and remove familiars based on a target amount that you specify.
+ *
+ * This is a convenience wrapper around the `EntityPlayer.CheckFamiliar` method. Use this helper
+ * function instead so that you do not have to retrieve the `ItemConfigItem` and so that you do not
+ * specify an incorrect RNG object. (The vanilla method is bugged in that it does not increment the
+ * RNG object; see the documentation of the method for more details.)
+ *
+ * This function is meant to be called in the EvaluateCache callback (when the cache flag is equal
+ * to `CacheFlag.FAMILIARS`).
+ *
+ * Note that this function is only meant to be used in special circumstances where the familiar
+ * count is completely custom and does not correspond to the amount of collectibles. For the general
+ * case, use the `checkFamiliarFromCollectibles` helper function instead.
+ *
+ * Note that this will spawn familiars with a completely random `InitSeed`. When calculating random
+ * events for this familiar, you should use a data structure that maps familiar `InitSeed` to RNG
+ * objects that are initialized based on the seed from
+ * `EntityPlayer.GetCollectibleRNG(collectibleType)`.
+ *
+ * @param player The player that owns the familiars.
+ * @param collectibleType The collectible type of the collectible associated with this familiar.
+ * @param targetCount The number of familiars that should exist. This function will add or remove
+ *                    familiars until it matches the target count.
+ * @param familiarVariant The variant of the familiar to spawn or remove.
+ * @param familiarSubType Optional. The sub-type of the familiar to spawn or remove. If not
+ *                        specified, it will search for existing familiars of all sub-types, and
+ *                        spawn new familiars with a sub-type of 0.
+ */
+export declare function checkFamiliar(player: EntityPlayer, collectibleType: CollectibleType, targetCount: int, familiarVariant: FamiliarVariant, familiarSubType?: int): void;
+/**
+ * Helper function to add and remove familiars based on the amount of associated collectibles that a
+ * player has.
+ *
+ * Use this helper function instead of invoking the `EntityPlayer.CheckFamiliar` method directly so
+ * that the target count is handled automatically.
+ *
+ * This function is meant to be called in the EvaluateCache callback (when the cache flag is equal
+ * to `CacheFlag.FAMILIARS`).
+ *
+ * Use this function when the amount of familiars should be equal to the amount of associated
+ * collectibles that the player has (plus any extras from having used Box of Friends or Monster
+ * Manual). If you instead need to have a custom amount of familiars, use the `checkFamiliars`
+ * function instead.
+ *
+ * Note that this will spawn familiars with a completely random `InitSeed`. When calculating random
+ * events for this familiar, you should use a data structure that maps familiar `InitSeed` to RNG
+ * objects that are initialized based on the seed from
+ * `EntityPlayer.GetCollectibleRNG(collectibleType)`.
+ *
+ * @param player The player that owns the familiars and collectibles.
+ * @param collectibleType The collectible type of the collectible associated with this familiar.
+ * @param familiarVariant The variant of the familiar to spawn or remove.
+ * @param familiarSubType Optional. The sub-type of the familiar to spawn or remove. If not
+ *                        specified, it will search for existing familiars of all sub-types, and
+ *                        spawn new familiars with a sub-type of 0.
+ */
+export declare function checkFamiliarFromCollectibles(player: EntityPlayer, collectibleType: CollectibleType, familiarVariant: FamiliarVariant, familiarSubType?: int): void;
+export declare function isFamiliarThatShootsPlayerTears(familiar: EntityFamiliar): boolean;

package/functions/familiars.lua

@@ -0,0 +1,33 @@
+local ____exports = {}
+local ____cachedClasses = require("cachedClasses")
+local itemConfig = ____cachedClasses.itemConfig
+local ____familiarsThatShootPlayerTearsSet = require("sets.familiarsThatShootPlayerTearsSet")
+local FAMILIARS_THAT_SHOOT_PLAYER_TEARS_SET = ____familiarsThatShootPlayerTearsSet.FAMILIARS_THAT_SHOOT_PLAYER_TEARS_SET
+function ____exports.checkFamiliar(self, player, collectibleType, targetCount, familiarVariant, familiarSubType)
+    local itemConfigItem = itemConfig:GetCollectible(collectibleType)
+    player:CheckFamiliar(
+        familiarVariant,
+        targetCount,
+        RNG(),
+        itemConfigItem,
+        familiarSubType
+    )
+end
+function ____exports.checkFamiliarFromCollectibles(self, player, collectibleType, familiarVariant, familiarSubType)
+    local numCollectibles = player:GetCollectibleNum(collectibleType)
+    local effects = player:GetEffects()
+    local numCollectibleEffects = effects:GetCollectibleEffectNum(collectibleType)
+    local targetCount = numCollectibles + numCollectibleEffects
+    ____exports.checkFamiliar(
+        nil,
+        player,
+        collectibleType,
+        targetCount,
+        familiarVariant,
+        familiarSubType
+    )
+end
+function ____exports.isFamiliarThatShootsPlayerTears(self, familiar)
+    return FAMILIARS_THAT_SHOOT_PLAYER_TEARS_SET:has(familiar.Variant)
+end
+return ____exports

package/functions/flag.d.ts

@@ -0,0 +1,99 @@
+import { DamageFlag } from "isaac-typescript-definitions";
+/**
+ * Helper function to add a bit flag to an existing set of bit flags.
+ *
+ * This is a variadic function, so pass as many flags as you want to add.
+ *
+ * Example 1:
+ *
+ * ```ts
+ * // Give the player spectral tears
+ * const player = Isaac.GetPlayer();
+ * player.TearFlags = addFlag(player.TearFlags, TearFlags.TEAR_SPECTRAL);
+ * ```
+ *
+ * Example 2:
+ *
+ * ```ts
+ * // Give the player spectral and homing tears
+ * const player = Isaac.GetPlayer();
+ * player.TearFlags = addFlag(player.TearFlags, TearFlags.TEAR_SPECTRAL, TearFlags.TEAR_HOMING);
+ * ```
+ *
+ * @param flags The existing set of bit flags.
+ * @param flagsToAdd One or more bit flags to add, each as a separate argument.
+ * @returns The combined bit flags.
+ */
+export declare function addFlag<T extends BitFlag | BitFlag128>(flags: T | BitFlags<T>, ...flagsToAdd: T[]): BitFlags<T>;
+/**
+ * Helper function for casting a flag enum value to a `BitFlags` object.
+ *
+ * This is useful because the compiler will prevent you from assigning a specific flag to a
+ * `BitFlags` property. (It does this to ensure type safety, since `BitFlags` can represent a zero
+ * value or a composition of N flags.)
+ *
+ * For example:
+ *
+ * ```ts
+ * player.TearFlags = bitFlags(TearFlag.SPECTRAL);
+ * ```
+ */
+export declare function bitFlags<T extends BitFlag | BitFlag128>(flag: T): BitFlags<T>;
+/**
+ * Helper function to get the key associated with a particular flag.
+ *
+ * (Since bit flags are represented by custom objects instead of normal TypeScript enums, you cannot
+ * use the reverse mapping to find the associated key of a given enum value. Use this helper
+ * function instead of indexing the enum directly.)
+ */
+export declare function getFlagName<T extends BitFlag | BitFlag128>(flag: BitFlag, flagEnum: Record<string, T>): string | undefined;
+/**
+ * Helper function to determine if a particular bit flag is set to true.
+ *
+ * This is a variadic function, so pass as many flags as you want to check for. If passed multiple
+ * flags, it will only return true if all of the flags are set.
+ *
+ * For example:
+ *
+ * ```ts
+ * const player = Isaac.GetPlayer();
+ * if (hasFlag(player.TearFlags, TearFlags.TEAR_SPECTRAL) {
+ *   // The player currently has spectral tears
+ * }
+ * ```
+ *
+ * @param flags The existing set of bit flags.
+ * @param flagsToCheck One or more bit flags to check for, each as a separate argument.
+ */
+export declare function hasFlag<T extends BitFlag | BitFlag128>(flags: T | BitFlags<T>, ...flagsToCheck: T[]): boolean;
+/**
+ * Helper function to check if every bit in the flag is turned off.
+ *
+ * (This is equivalent to checking if the flag is equal to 0, but this is not possible without
+ * casting the flag to a number.)
+ */
+export declare function isEmptyFlag<T extends BitFlag | BitFlag128>(flag: T): boolean;
+/**
+ * Helper function to determine whether damage to a player in the EntityTakeDmg callback was
+ * self-inflicted. For example, damage from a Curse Room door, a Razor, or a Blood Donation Machine
+ * would count as self-inflicted damage.
+ */
+export declare function isSelfDamage(damageFlags: DamageFlag | BitFlags<DamageFlag>): boolean;
+/**
+ * Helper function to remove a bit flag from an existing set of bit flags.
+ *
+ * This is a variadic function, so pass as many flags as you want to remove.
+ *
+ * For example:
+ *
+ * ```ts
+ * // Remove spectral tears from the player, if present
+ * const player = Isaac.GetPlayer();
+ * player.TearFlags = removeFlag(player.TearFlags, TearFlags.TEAR_SPECTRAL);
+ * ```
+ *
+ * @param flags The existing set of bit flags.
+ * @param flagsToRemove One or more bit flags to remove, each as a separate argument.
+ * @returns The combined bit flags.
+ */
+export declare function removeFlag<T extends BitFlag | BitFlag128>(flags: T | BitFlags<T>, ...flagsToRemove: T[]): BitFlags<T>;

package/functions/flag.lua

@@ -0,0 +1,47 @@
+local ____exports = {}
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local DamageFlag = ____isaac_2Dtypescript_2Ddefinitions.DamageFlag
+function ____exports.addFlag(self, flags, ...)
+    local flagsToAdd = {...}
+    local flagsAsInt = flags
+    for ____, flagToAdd in ipairs(flagsToAdd) do
+        flagsAsInt = flagsAsInt | flagToAdd
+    end
+    return flagsAsInt
+end
+function ____exports.bitFlags(self, flag)
+    return flag
+end
+function ____exports.getFlagName(self, flag, flagEnum)
+    for key, value in pairs(flagEnum) do
+        if value == flag then
+            return key
+        end
+    end
+    return nil
+end
+function ____exports.hasFlag(self, flags, ...)
+    local flagsToCheck = {...}
+    local flagsAsInt = flags
+    for ____, flagToCheck in ipairs(flagsToCheck) do
+        if not (flagsAsInt & flagToCheck == flagToCheck) then
+            return false
+        end
+    end
+    return true
+end
+function ____exports.isEmptyFlag(self, flag)
+    return flag == 0
+end
+function ____exports.isSelfDamage(self, damageFlags)
+    return ____exports.hasFlag(nil, damageFlags, DamageFlag.NO_PENALTIES) or ____exports.hasFlag(nil, damageFlags, DamageFlag.RED_HEARTS)
+end
+function ____exports.removeFlag(self, flags, ...)
+    local flagsToRemove = {...}
+    local flagsAsInt = flags
+    for ____, flagToRemove in ipairs(flagsToRemove) do
+        flagsAsInt = flagsAsInt & ~flagToRemove
+    end
+    return flagsAsInt
+end
+return ____exports

package/functions/flying.d.ts

@@ -0,0 +1,19 @@
+import { CollectibleType, TrinketType } from "isaac-typescript-definitions";
+/**
+ * Returns a set of all of the collectibles that grant flight. This is derived from collectibles
+ * that have `CacheFlag.FLYING` set in the "items.xml" file.
+ *
+ * Collectibles that only grant flight conditionally are manually pruned. Collectibles such as Empty
+ * Vessel should be checked for via the `hasFlyingTemporaryEffect` function.
+ *
+ * @param pruneConditionalItems Whether or not collectibles that only grant flight conditionally
+ *                              should be included in the set (like Empty Vessel).
+ */
+export declare function getFlyingCollectibles(pruneConditionalItems: boolean): Set<CollectibleType>;
+/**
+ * Returns a set of all of the trinkets that grant flight. (All trinkets that grant flight do so
+ * conditionally, like Bat Wing.)
+ */
+export declare function getFlyingTrinkets(): ReadonlySet<TrinketType>;
+export declare function hasFlyingTemporaryEffect(player: EntityPlayer): boolean;
+export declare function isFlyingCharacter(player: EntityPlayer): boolean;

package/functions/flying.lua

@@ -0,0 +1,67 @@
+local ____lualib = require("lualib_bundle")
+local Set = ____lualib.Set
+local __TS__New = ____lualib.__TS__New
+local __TS__Iterator = ____lualib.__TS__Iterator
+local ____exports = {}
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local CacheFlag = ____isaac_2Dtypescript_2Ddefinitions.CacheFlag
+local CollectibleType = ____isaac_2Dtypescript_2Ddefinitions.CollectibleType
+local NullItemID = ____isaac_2Dtypescript_2Ddefinitions.NullItemID
+local PlayerType = ____isaac_2Dtypescript_2Ddefinitions.PlayerType
+local TrinketType = ____isaac_2Dtypescript_2Ddefinitions.TrinketType
+local ____collectibleCacheFlag = require("functions.collectibleCacheFlag")
+local getCollectiblesForCacheFlag = ____collectibleCacheFlag.getCollectiblesForCacheFlag
+local ____set = require("functions.set")
+local copySet = ____set.copySet
+local deleteSetsFromSet = ____set.deleteSetsFromSet
+local FLYING_CHARACTERS = __TS__New(Set, {
+    PlayerType.AZAZEL,
+    PlayerType.THE_LOST,
+    PlayerType.THE_SOUL,
+    PlayerType.THE_LOST_B,
+    PlayerType.JACOB_2_B,
+    PlayerType.THE_SOUL_B
+})
+local FLYING_TRINKETS = __TS__New(Set, {TrinketType.BAT_WING, TrinketType.AZAZELS_STUMP})
+local FLYING_NULL_ITEMS = {NullItemID.REVERSE_SUN, NullItemID.SPIRIT_SHACKLES_SOUL, NullItemID.LOST_CURSE}
+local CONDITIONAL_FLYING_COLLECTIBLE_TYPES = {CollectibleType.BIBLE, CollectibleType.EMPTY_VESSEL, CollectibleType.ASTRAL_PROJECTION, CollectibleType.RECALL}
+function ____exports.getFlyingCollectibles(self, pruneConditionalItems)
+    local collectiblesWithFlyingCacheFlag = getCollectiblesForCacheFlag(nil, CacheFlag.FLYING)
+    local collectiblesWithAllCacheFlag = getCollectiblesForCacheFlag(nil, CacheFlag.ALL)
+    deleteSetsFromSet(nil, collectiblesWithFlyingCacheFlag, collectiblesWithAllCacheFlag)
+    if pruneConditionalItems then
+        for ____, collectibleType in ipairs(CONDITIONAL_FLYING_COLLECTIBLE_TYPES) do
+            collectiblesWithFlyingCacheFlag:delete(collectibleType)
+        end
+    end
+    return collectiblesWithFlyingCacheFlag
+end
+function ____exports.getFlyingTrinkets(self)
+    return copySet(nil, FLYING_TRINKETS)
+end
+function ____exports.hasFlyingTemporaryEffect(self, player)
+    local effects = player:GetEffects()
+    local flyingCollectibles = ____exports.getFlyingCollectibles(nil, false)
+    for ____, collectibleType in __TS__Iterator(flyingCollectibles:values()) do
+        if effects:HasCollectibleEffect(collectibleType) then
+            return true
+        end
+    end
+    local flyingTrinkets = ____exports.getFlyingTrinkets(nil)
+    for ____, trinketType in __TS__Iterator(flyingTrinkets:values()) do
+        if effects:HasTrinketEffect(trinketType) then
+            return true
+        end
+    end
+    for ____, nullItemID in ipairs(FLYING_NULL_ITEMS) do
+        if effects:HasNullEffect(nullItemID) then
+            return true
+        end
+    end
+    return false
+end
+function ____exports.isFlyingCharacter(self, player)
+    local character = player:GetPlayerType()
+    return FLYING_CHARACTERS:has(character)
+end
+return ____exports

package/functions/globals.d.ts

@@ -0,0 +1,14 @@
+/// <reference types="typescript-to-lua/language-extensions" />
+/**
+ * Helper function to get a set containing all of the global variable names that are contained
+ * within the Isaac environment by default.
+ *
+ * Returns a slightly different set depending on whether the "--luadebug" flag is enabled or not.
+ */
+export declare function getDefaultGlobals(): Set<string>;
+/**
+ * Helper function to get an array of any added global variables in the Isaac Lua environment.
+ * Returns an array of key/value tuples.
+ */
+export declare function getNewGlobals(): Array<[AnyNotNil, unknown]>;
+export declare function logNewGlobals(): void;