isaacscript-common 2.3.0 → 3.0.0

package/functions/flying.lua

@@ -0,0 +1,77 @@
+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}
+--- 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).
+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
+--- Returns a set of all of the trinkets that grant flight. (All trinkets that grant flight do so
+-- conditionally, like Bat Wing.)
+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;

package/functions/globals.lua

@@ -0,0 +1,236 @@
+local ____lualib = require("lualib_bundle")
+local Set = ____lualib.Set
+local __TS__New = ____lualib.__TS__New
+local __TS__ArraySort = ____lualib.__TS__ArraySort
+local __TS__ArrayForEach = ____lualib.__TS__ArrayForEach
+local ____exports = {}
+local twoDimensionalSort
+local ____debug = require("functions.debug")
+local isLuaDebugEnabled = ____debug.isLuaDebugEnabled
+local ____log = require("functions.log")
+local log = ____log.log
+local ____set = require("functions.set")
+local addSetsToSet = ____set.addSetsToSet
+local copySet = ____set.copySet
+function twoDimensionalSort(self, a, b)
+    if a[1] == nil or b[1] == nil then
+        error("Failed to two-dimensional sort since the first element of the array was undefined.")
+    end
+    if a[1] == b[1] then
+        return 0
+    end
+    return a[1] < b[1] and -1 or 1
+end
+local DEFAULT_GLOBALS = __TS__New(Set, {
+    "ActionTriggers",
+    "ActiveSlot",
+    "BabySubType",
+    "BackdropType",
+    "BatterySubType",
+    "BedSubType",
+    "BitSet128",
+    "BombSubType",
+    "BombVariant",
+    "ButtonAction",
+    "CacheFlag",
+    "Card",
+    "Challenge",
+    "ChampionColor",
+    "ChestSubType",
+    "CoinSubType",
+    "CollectibleType",
+    "Color",
+    "CppContainer",
+    "DamageFlag",
+    "Difficulty",
+    "Direction",
+    "DoorSlot",
+    "DoorState",
+    "DoorVariant",
+    "EffectVariant",
+    "Entity",
+    "EntityBomb",
+    "EntityCollisionClass",
+    "EntityEffect",
+    "EntityFamiliar",
+    "EntityFlag",
+    "EntityGridCollisionClass",
+    "EntityKnife",
+    "EntityLaser",
+    "EntityNPC",
+    "EntityPartition",
+    "EntityPickup",
+    "EntityPlayer",
+    "EntityProjectile",
+    "EntityPtr",
+    "EntityRef",
+    "EntityTear",
+    "EntityType",
+    "FamiliarVariant",
+    "Font",
+    "Game",
+    "GameStateFlag",
+    "GetPtrHash",
+    "GridCollisionClass",
+    "GridEntity",
+    "GridEntityDesc",
+    "GridEntityDoor",
+    "GridEntityPit",
+    "GridEntityPoop",
+    "GridEntityPressurePlate",
+    "GridEntityRock",
+    "GridEntitySpikes",
+    "GridEntityTNT",
+    "GridEntityType",
+    "GridRooms",
+    "HUD",
+    "HeartSubType",
+    "Input",
+    "InputHook",
+    "Isaac",
+    "ItemConfig",
+    "ItemPool",
+    "ItemPoolType",
+    "ItemType",
+    "KColor",
+    "KeySubType",
+    "Keyboard",
+    "LaserOffset",
+    "LaserSubType",
+    "Level",
+    "LevelCurse",
+    "LevelStage",
+    "LevelStateFlag",
+    "LocustSubtypes",
+    "ModCallbacks",
+    "Mouse",
+    "Music",
+    "MusicManager",
+    "NpcState",
+    "NullItemID",
+    "Options",
+    "PathFinder",
+    "PickupPrice",
+    "PickupVariant",
+    "PillColor",
+    "PillEffect",
+    "PlayerForm",
+    "PlayerSpriteLayer",
+    "PlayerType",
+    "PlayerTypes",
+    "PoopPickupSubType",
+    "PoopSpellType",
+    "ProjectileFlags",
+    "ProjectileParams",
+    "ProjectileVariant",
+    "QueueItemData",
+    "REPENTANCE",
+    "RNG",
+    "Random",
+    "RandomVector",
+    "RegisterMod",
+    "RenderMode",
+    "Room",
+    "RoomConfig",
+    "RoomDescriptor",
+    "RoomShape",
+    "RoomTransitionAnim",
+    "RoomType",
+    "SFXManager",
+    "SackSubType",
+    "SeedEffect",
+    "Seeds",
+    "ShockwaveParams",
+    "SkinColor",
+    "SortingLayer",
+    "SoundEffect",
+    "Sprite",
+    "StageType",
+    "StartDebug",
+    "TearFlags",
+    "TearParams",
+    "TearVariant",
+    "TemporaryEffect",
+    "TemporaryEffects",
+    "TrinketType",
+    "UseFlag",
+    "Vector",
+    "WeaponType",
+    "_G",
+    "_VERSION",
+    "assert",
+    "collectgarbage",
+    "coroutine",
+    "dofile",
+    "error",
+    "getmetatable",
+    "include",
+    "ipairs",
+    "load",
+    "loadfile",
+    "math",
+    "next",
+    "pairs",
+    "pcall",
+    "print",
+    "rawequal",
+    "rawget",
+    "rawlen",
+    "rawset",
+    "require",
+    "select",
+    "setmetatable",
+    "string",
+    "table",
+    "tonumber",
+    "tostring",
+    "type",
+    "utf8",
+    "xpcall"
+})
+local LUA_DEBUG_ADDED_GLOBALS = __TS__New(Set, {"debug", "io", "os", "package"})
+local RACING_PLUS_SANDBOX_ADDED_GLOBALS = __TS__New(Set, {"sandboxTraceback", "sandboxGetTraceback", "getParentFunctionDescription"})
+--- 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.
+function ____exports.getDefaultGlobals(self)
+    local defaultGlobals = copySet(nil, DEFAULT_GLOBALS)
+    if isLuaDebugEnabled(nil) then
+        addSetsToSet(nil, defaultGlobals, LUA_DEBUG_ADDED_GLOBALS)
+    end
+    addSetsToSet(nil, defaultGlobals, RACING_PLUS_SANDBOX_ADDED_GLOBALS)
+    return defaultGlobals
+end
+--- Helper function to get an array of any added global variables in the Isaac Lua environment.
+-- Returns an array of key/value tuples.
+function ____exports.getNewGlobals(self)
+    local defaultGlobals = ____exports.getDefaultGlobals(nil)
+    local newGlobals = {}
+    for key, value in pairs(_G) do
+        if not defaultGlobals:has(key) then
+            local keyValueTuple = {key, value}
+            newGlobals[#newGlobals + 1] = keyValueTuple
+        end
+    end
+    __TS__ArraySort(newGlobals, twoDimensionalSort)
+    return newGlobals
+end
+function ____exports.logNewGlobals(self)
+    local newGlobals = ____exports.getNewGlobals(nil)
+    log("List of added global variables in the Isaac environment:")
+    if #newGlobals == 0 then
+        log("- n/a (no extra global variables found)")
+    end
+    __TS__ArrayForEach(
+        newGlobals,
+        function(____, ____bindingPattern0, i)
+            local value
+            local key
+            key = ____bindingPattern0[1]
+            value = ____bindingPattern0[2]
+            log((((tostring(i + 1) .. ") ") .. tostring(key)) .. " - ") .. tostring(value))
+        end
+    )
+end
+return ____exports

package/functions/gridEntity.d.ts

@@ -0,0 +1,155 @@
+import { GridEntityType, GridEntityXMLType } from "isaac-typescript-definitions";
+/**
+ * Helper function to convert the grid entity type found in a room XML file to the corresponding
+ * grid entity type and variant normally used by the game. For example, a rock is represented as
+ * 1000.0 in a room XML file, but `GridEntityType.ROCK` is equal to 2.
+ */
+export declare function convertXMLGridEntityType(gridEntityXMLType: GridEntityXMLType, gridEntityXMLVariant: int): [GridEntityType, int] | undefined;
+/**
+ * Gets the entities that have a hitbox that overlaps with any part of the square that the grid
+ * entity is on.
+ *
+ * Note that this function will not work properly in the PostNewRoom callback, since entities do not
+ * have collision yet in that callback.
+ */
+export declare function getCollidingEntitiesWithGridEntity(gridEntity: GridEntity): Entity[];
+/**
+ * Helper function to get every grid entity in the current room.
+ *
+ * Use this function with no arguments to get every grid entity, or specify a variadic amount of
+ * arguments to match specific grid entity types.
+ *
+ * For example:
+ *
+ * ```ts
+ * for (const gridEntity of getGridEntities()) {
+ *   print(gridEntity.GetType())
+ * }
+ * ```
+ *
+ * For example:
+ *
+ * ```ts
+ * const rocks = getGridEntities(
+ *   GridEntityType.ROCK,
+ *   GridEntityType.BLOCK,
+ *   GridEntityType.ROCK_TINTED,
+ * );
+ * ```
+ */
+export declare function getGridEntities(...gridEntityTypes: GridEntityType[]): GridEntity[];
+/**
+ * Helper function to get a map of every grid entity in the current room. The indexes of the map are
+ * equal to the grid index. The values of the map are equal to the grid entities.
+ *
+ * Use this function with no arguments to get every grid entity, or specify a variadic amount of
+ * arguments to match specific grid entity types.
+ */
+export declare function getGridEntitiesMap(...gridEntityTypes: GridEntityType[]): Map<int, GridEntity>;
+/** Helper function to return a string containing the grid entity's type and variant. */
+export declare function getGridEntityID(gridEntity: GridEntity): string;
+export declare function getSurroundingGridEntities(gridEntity: GridEntity): GridEntity[];
+export declare function getTopLeftWall(): GridEntity | undefined;
+/**
+ * Helper function to get the grid index of the top left wall. (This will depend on what the current
+ * room shape is.)
+ */
+export declare function getTopLeftWallGridIndex(): int;
+export declare function isGridEntityBreakableByExplosion(gridEntity: GridEntity): boolean;
+/**
+ * Helper function to see if the provided gridEntity is in its respective broken state. See the
+ * `GRID_ENTITY_TYPE_TO_BROKEN_STATE_MAP` constant for more details.
+ *
+ * Note that in the case of `GridEntityType.LOCK` (11), the state will turn to being broken before
+ * the actual collision for the entity is removed.
+ */
+export declare function isGridEntityBroken(gridEntity: GridEntity): boolean;
+/**
+ * Helper function to detect whether a given Void Portal is one that randomly spawns after a boss is
+ * defeated or is one that naturally spawns in the room after Hush. (This is determined by looking
+ * at the VarData of the entity.)
+ */
+export declare function isPostBossVoidPortal(gridEntity: GridEntity): boolean;
+/**
+ * Helper function to all grid entities in the room except for ones matching the grid entity types
+ * provided.
+ *
+ * For example:
+ *
+ * ```ts
+ * removeAllGridEntitiesExceptFor(
+ *   GridEntityType.WALL,
+ *   GridEntityType.DOOR,
+ * );
+ * ```
+ *
+ * @returns True if one or more grid entities were removed, false otherwise.
+ */
+export declare function removeAllGridExcept(...gridEntityTypes: GridEntityType[]): boolean;
+/**
+ * Helper function to remove all of the grid entities in the room that match the grid entity types
+ * provided.
+ *
+ * For example:
+ *
+ * ```ts
+ * removeAllMatchingGridEntities(
+ *   GridEntityType.ROCK,
+ *   GridEntityType.BLOCK,
+ *   GridEntityType.ROCK_TINTED,
+ * );
+ * ```
+ *
+ * @returns True if one or more grid entities were removed, false otherwise.
+ */
+export declare function removeAllMatchingGridEntities(...gridEntityType: GridEntityType[]): boolean;
+/**
+ * Helper function to remove a grid entity simply by providing the grid entity object.
+ *
+ * @param gridEntity The grid entity to remove.
+ * @param updateRoom Optional. Whether or not to update the room after the grid entity is removed.
+ *                   Default is true. This is generally a good idea because if the room is not
+ *                   updated, you will be unable to spawn another grid entity on the same tile until
+ *                   a frame has passed. However, doing this is expensive, since it involves a call
+ *                   to `Isaac.GetRoomEntities`, so set it to false if you need to invoke this
+ *                   function multiple times.
+ */
+export declare function removeGrid(gridEntity: GridEntity, updateRoom?: boolean): void;
+/**
+ * Helper function to make a grid entity invisible. This is accomplished by setting its sprite to an
+ * empty/missing PNG file.
+ *
+ * For more information, see the documentation for the `clearSprite` helper function.
+ */
+export declare function setGridEntityInvisible(gridEntity: GridEntity): void;
+/**
+ * Helper function to spawn a giant poop. This is performed by spawning each of the four quadrant
+ * grid entities in the appropriate positions.
+ */
+export declare function spawnGiantPoop(topLeftGridIndex: int): void;
+/**
+ * Helper function to spawn a grid entity.
+ *
+ * This function assumes you want to give the grid entity a variant of 0. If you want to specify a
+ * variant, use the `spawnGridWithVariant` helper function instead.
+ *
+ * Use this instead of the `Isaac.GridSpawn` method since it:
+ * - handles giving pits collision
+ * - removes existing grid entities on the same tile, if any
+ * - allows you to specify either the grid index or the position
+ */
+export declare function spawnGrid(gridEntityType: GridEntityType, gridIndexOrPosition: int | Vector): GridEntity | undefined;
+/**
+ * Helper function to spawn a grid entity with a specific variant.
+ *
+ * Use this instead of the `Isaac.GridSpawn` method since it:
+ * - handles giving pits collision
+ * - removes existing grid entities on the same tile, if any
+ * - allows you to specify the grid index or the position
+ */
+export declare function spawnGridWithVariant(gridEntityType: GridEntityType, variant: int, gridIndexOrPosition: int | Vector): GridEntity | undefined;
+/**
+ * Helper function to spawn a Void Portal. This is more complicated than simply spawning a trapdoor
+ * with the appropriate variant, as the game does not give it the correct sprite automatically.
+ */
+export declare function spawnVoidPortal(gridIndex: int): GridEntity | undefined;