isaacscript-common 2.3.0 → 3.0.0

package/functions/revive.lua

@@ -0,0 +1,117 @@
+local ____exports = {}
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local CollectibleType = ____isaac_2Dtypescript_2Ddefinitions.CollectibleType
+local EntityType = ____isaac_2Dtypescript_2Ddefinitions.EntityType
+local NullItemID = ____isaac_2Dtypescript_2Ddefinitions.NullItemID
+local PlayerType = ____isaac_2Dtypescript_2Ddefinitions.PlayerType
+local TrinketType = ____isaac_2Dtypescript_2Ddefinitions.TrinketType
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+local ____constants = require("constants")
+local MAX_TAINTED_SAMSON_BERSERK_CHARGE = ____constants.MAX_TAINTED_SAMSON_BERSERK_CHARGE
+local TAINTED_SAMSON_BERSERK_CHARGE_FROM_TAKING_DAMAGE = ____constants.TAINTED_SAMSON_BERSERK_CHARGE_FROM_TAKING_DAMAGE
+local ____character = require("functions.character")
+local getCharacterDeathAnimationName = ____character.getCharacterDeathAnimationName
+local ____player = require("functions.player")
+local getPlayerMaxHeartContainers = ____player.getPlayerMaxHeartContainers
+local getPlayerNumHitsRemaining = ____player.getPlayerNumHitsRemaining
+local hasLostCurse = ____player.hasLostCurse
+local isKeeper = ____player.isKeeper
+local ____sprite = require("functions.sprite")
+local getLastFrameOfAnimation = ____sprite.getLastFrameOfAnimation
+local ____trinketGive = require("functions.trinketGive")
+local giveTrinketsBack = ____trinketGive.giveTrinketsBack
+local temporarilyRemoveTrinket = ____trinketGive.temporarilyRemoveTrinket
+--- Helper function to determine if the player will be revived by the Heartbreak collectible if they
+-- take fatal damage. This is contingent on the character that they are playing as and the amount of
+-- broken hearts that they already have.
+function ____exports.willReviveFromHeartbreak(self, player)
+    if not player:HasCollectible(CollectibleType.HEARTBREAK) then
+        return false
+    end
+    local maxHeartContainers = getPlayerMaxHeartContainers(nil, player)
+    local numBrokenHeartsThatWillBeAdded = isKeeper(nil, player) and 1 or 2
+    local brokenHearts = player:GetBrokenHearts()
+    local numBrokenHeartsAfterRevival = numBrokenHeartsThatWillBeAdded + brokenHearts
+    return maxHeartContainers > numBrokenHeartsAfterRevival
+end
+--- Helper function to determine if the Spirit Shackles item is in an enabled state. (It can be
+-- either enabled or disabled.)
+function ____exports.willReviveFromSpiritShackles(self, player)
+    if not player:HasCollectible(CollectibleType.SPIRIT_SHACKLES) then
+        return false
+    end
+    local effects = player:GetEffects()
+    local spiritShacklesEnabled = not effects:HasNullEffect(NullItemID.SPIRIT_SHACKLES_DISABLED)
+    local playerInSoulForm = effects:HasNullEffect(NullItemID.SPIRIT_SHACKLES_SOUL)
+    return spiritShacklesEnabled and not playerInSoulForm
+end
+--- Uses the player's current health and other miscellaneous things to determine if incoming damage
+-- will be fatal.
+function ____exports.isDamageToPlayerFatal(self, player, damageAmount, damageSource, lastDamageGameFrame)
+    local gameFrameCount = game:GetFrameCount()
+    local character = player:GetPlayerType()
+    local effects = player:GetEffects()
+    local isBerserk = effects:HasCollectibleEffect(CollectibleType.BERSERK)
+    if character == PlayerType.JACOB_B and damageSource.Type == EntityType.DARK_ESAU then
+        return false
+    end
+    if isBerserk then
+        return false
+    end
+    local berserkChargeAfterHit = player.SamsonBerserkCharge + TAINTED_SAMSON_BERSERK_CHARGE_FROM_TAKING_DAMAGE
+    if character == PlayerType.SAMSON_B and berserkChargeAfterHit >= MAX_TAINTED_SAMSON_BERSERK_CHARGE then
+        return false
+    end
+    if ____exports.willReviveFromSpiritShackles(nil, player) then
+        return false
+    end
+    if character == PlayerType.JACOB_2_B then
+        return true
+    end
+    if hasLostCurse(nil, player) then
+        return true
+    end
+    local playerNumAllHearts = getPlayerNumHitsRemaining(nil, player)
+    if damageAmount < playerNumAllHearts then
+        return false
+    end
+    if ____exports.willReviveFromHeartbreak(nil, player) then
+        return false
+    end
+    if player:HasCollectible(CollectibleType.BROKEN_GLASS_CANNON) and gameFrameCount == lastDamageGameFrame then
+        return false
+    end
+    local hearts = player:GetHearts()
+    local eternalHearts = player:GetEternalHearts()
+    local soulHearts = player:GetSoulHearts()
+    local boneHearts = player:GetBoneHearts()
+    if hearts > 0 and soulHearts > 0 or hearts > 0 and boneHearts > 0 or soulHearts > 0 and boneHearts > 0 or soulHearts > 0 and eternalHearts > 0 or boneHearts >= 2 then
+        return false
+    end
+    return true
+end
+--- Assuming that we are on the frame of fatal damage, this function returns whether or not
+-- Mysterious Paper would rotate to Missing Poster on the frame that the "Game Over" screen would
+-- appear (which would subsequently save the player from fatal damage).
+-- 
+-- Mysterious Paper rotates between the 4 items on every frame, in order. The formula for whether
+-- Mysterious Paper be Missing Power is: `gameFrameCount % 4 === 3`
+function ____exports.willMysteriousPaperRevive(self, player)
+    local gameFrameCount = game:GetFrameCount()
+    local sprite = player:GetSprite()
+    local character = player:GetPlayerType()
+    local animation = getCharacterDeathAnimationName(nil, character)
+    local deathAnimationFrames = getLastFrameOfAnimation(nil, sprite, animation)
+    local frameOfDeath = gameFrameCount + deathAnimationFrames + 1
+    return frameOfDeath % 4 == 3
+end
+--- The `EntityPlayer.WillPlayerRevive` method does not properly account for Mysterious Paper, so use
+-- this helper function instead for more robust revival detection.
+function ____exports.willPlayerRevive(self, player)
+    local trinketSituation = temporarilyRemoveTrinket(nil, player, TrinketType.MYSTERIOUS_PAPER)
+    local willRevive = player:WillPlayerRevive() or trinketSituation ~= nil and ____exports.willMysteriousPaperRevive(nil, player)
+    giveTrinketsBack(nil, player, trinketSituation)
+    return willRevive
+end
+return ____exports

package/functions/rng.d.ts

@@ -0,0 +1,53 @@
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="typescript-to-lua/language-extensions" />
+import { SerializationType } from "../enums/SerializationType";
+declare type SerializedRNG = LuaTable<string, unknown> & {
+    __serializedRNGBrand: void;
+};
+interface CopyRNGReturn {
+    [SerializationType.NONE]: RNG;
+    [SerializationType.SERIALIZE]: SerializedRNG;
+    [SerializationType.DESERIALIZE]: RNG;
+}
+/**
+ * Helper function to copy an `RNG` object.
+ *
+ * @param rng The RNG object to copy. In the case of deserialization, this will actually be a Lua
+ *            table instead of an instantiated RNG class.
+ * @param serializationType Default is `SerializationType.NONE`.
+ */
+export declare function copyRNG<R extends RNG | SerializedRNG, S extends SerializationType>(rng: R, serializationType: S): CopyRNGReturn[S];
+export declare function copyRNG<R extends RNG | SerializedRNG>(rng: R): CopyRNGReturn[SerializationType.NONE];
+/**
+ * Helper function to get a random `Seed` value to be used in spawning entities and so on. Use this
+ * instead of calling the `Random` function directly since that can return a value of 0 and crash
+ * the game.
+ */
+export declare function getRandomSeed(): Seed;
+/** Helper function to check if something is an instantiated RNG object. */
+export declare function isRNG(object: unknown): object is RNG;
+/**
+ * Used to determine is the given table is a serialized `RNG` object created by the save data
+ * manager and/or the `deepCopy` function.
+ */
+export declare function isSerializedRNG(object: unknown): object is SerializedRNG;
+/**
+ * Helper function to initialize an RNG object using Blade's recommended shift index.
+ *
+ * @param seed The seed to initialize it with. Default is `getRandomSeed()`.
+ */
+export declare function newRNG(seed?: Seed): RNG;
+export declare function rngEquals(rng1: RNG, rng2: RNG): boolean;
+/**
+ * Helper function to iterate over the provided object and set the seed for all of the values that
+ * are RNG objects equal to a particular seed.
+ */
+export declare function setAllRNGToSeed(object: unknown, seed: Seed): void;
+/**
+ * Helper function to iterate over the provided object and set the seed for all of the values that
+ * are RNG objects equal to the start seed for the current run.
+ */
+export declare function setAllRNGToStartSeed(object: unknown): void;
+/** Helper function to set a seed to an RNG object using Blade's recommended shift index. */
+export declare function setSeed(rng: RNG, seed: Seed): void;
+export {};

package/functions/rng.lua

@@ -0,0 +1,148 @@
+local ____lualib = require("lualib_bundle")
+local __TS__ObjectValues = ____lualib.__TS__ObjectValues
+local ____exports = {}
+local RECOMMENDED_SHIFT_IDX, OBJECT_NAME
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+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 getNumbersFromTable = ____table.getNumbersFromTable
+local tableHasKeys = ____table.tableHasKeys
+local ____utils = require("functions.utils")
+local ensureAllCases = ____utils.ensureAllCases
+--- Helper function to get a random `Seed` value to be used in spawning entities and so on. Use this
+-- instead of calling the `Random` function directly since that can return a value of 0 and crash
+-- the game.
+function ____exports.getRandomSeed(self)
+    local randomNumber = Random()
+    local safeRandomNumber = randomNumber == 0 and 1 or randomNumber
+    return safeRandomNumber
+end
+--- Helper function to check if something is an instantiated RNG object.
+function ____exports.isRNG(self, object)
+    return isIsaacAPIClassOfType(nil, object, OBJECT_NAME)
+end
+--- Helper function to initialize an RNG object using Blade's recommended shift index.
+-- 
+-- @param seed The seed to initialize it with. Default is `getRandomSeed()`.
+function ____exports.newRNG(self, seed)
+    if seed == nil then
+        seed = ____exports.getRandomSeed(nil)
+    end
+    local rng = RNG()
+    ____exports.setSeed(nil, rng, seed)
+    return rng
+end
+--- Helper function to set a seed to an RNG object using Blade's recommended shift index.
+function ____exports.setSeed(self, rng, seed)
+    if seed == 0 then
+        error("You cannot set an RNG object to a seed of 0, or the game will crash.")
+    end
+    rng:SetSeed(seed, RECOMMENDED_SHIFT_IDX)
+end
+RECOMMENDED_SHIFT_IDX = 35
+local KEYS = {"seed"}
+OBJECT_NAME = "RNG"
+--- Helper function to copy an `RNG` object.
+-- 
+-- @param rng The RNG object to copy. In the case of deserialization, this will actually be a Lua
+-- table instead of an instantiated RNG class.
+-- @param serializationType Default is `SerializationType.NONE`.
+function ____exports.copyRNG(self, rng, 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.isRNG(nil, rng) then
+                    error(((("Failed to copy a " .. OBJECT_NAME) .. " object since the provided object was not a userdata ") .. OBJECT_NAME) .. " class.")
+                end
+                local seed = rng:GetSeed()
+                return ____exports.newRNG(nil, seed)
+            end
+        end
+        ____cond3 = ____cond3 or ____switch3 == SerializationType.SERIALIZE
+        if ____cond3 then
+            do
+                if not ____exports.isRNG(nil, rng) then
+                    error(((("Failed to serialize a " .. OBJECT_NAME) .. " object since the provided object was not a userdata ") .. OBJECT_NAME) .. " class.")
+                end
+                local seed = rng:GetSeed()
+                local rngTable = {}
+                rngTable.seed = seed
+                rngTable[SerializationBrand.RNG] = ""
+                return rngTable
+            end
+        end
+        ____cond3 = ____cond3 or ____switch3 == SerializationType.DESERIALIZE
+        if ____cond3 then
+            do
+                local rngType = type(rng)
+                if ____exports.isRNG(nil, rng) or rngType ~= "table" then
+                    error(("Failed to deserialize a " .. OBJECT_NAME) .. " object since the provided object was not a Lua table.")
+                end
+                local seedNumber = table.unpack(getNumbersFromTable(
+                    nil,
+                    rng,
+                    OBJECT_NAME,
+                    table.unpack(KEYS)
+                ))
+                local seed = seedNumber
+                return ____exports.newRNG(nil, seed)
+            end
+        end
+        do
+            do
+                return ensureAllCases(nil, serializationType)
+            end
+        end
+    until true
+end
+--- Used to determine is the given table is a serialized `RNG` object created by the save data
+-- manager and/or the `deepCopy` function.
+function ____exports.isSerializedRNG(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.RNG] ~= nil
+end
+function ____exports.rngEquals(self, rng1, rng2)
+    return isaacAPIClassEquals(nil, rng1, rng2, KEYS)
+end
+--- Helper function to iterate over the provided object and set the seed for all of the values that
+-- are RNG objects equal to a particular seed.
+function ____exports.setAllRNGToSeed(self, object, seed)
+    local objectType = type(object)
+    if objectType ~= "table" then
+        error("Failed to iterate over the object containing RNG objects since the type of the provided object was: " .. objectType)
+    end
+    local ____table = object
+    for ____, value in ipairs(__TS__ObjectValues(____table)) do
+        if ____exports.isRNG(nil, value) then
+            ____exports.setSeed(nil, value, seed)
+        end
+    end
+end
+--- Helper function to iterate over the provided object and set the seed for all of the values that
+-- are RNG objects equal to the start seed for the current run.
+function ____exports.setAllRNGToStartSeed(self, object)
+    local seeds = game:GetSeeds()
+    local startSeed = seeds:GetStartSeed()
+    ____exports.setAllRNGToSeed(nil, object, startSeed)
+end
+return ____exports

package/functions/roomData.d.ts

@@ -0,0 +1,108 @@
+import { DoorSlot, RoomShape, RoomType, StageID } from "isaac-typescript-definitions";
+/**
+ * Alias for the `Level.GetCurrentRoomDesc` method. Use this to make it more clear what type of
+ * `RoomDescriptor` object that you are retrieving.
+ */
+export declare function getCurrentRoomDescriptorReadOnly(): ReadonlyRoomDescriptor;
+/**
+ * Helper function to get the set of allowed door slots for the room at the supplied grid index.
+ * This corresponds to the doors that are enabled in the STB/XML file for the room.
+ */
+export declare function getRoomAllowedDoors(roomGridIndex?: int): Set<DoorSlot>;
+/**
+ * Helper function to get the room data for the provided room.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ */
+export declare function getRoomData(roomGridIndex?: int): RoomConfig | undefined;
+/**
+ * Helper function to get the descriptor for a room.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ */
+export declare function getRoomDescriptor(roomGridIndex?: int): RoomDescriptor;
+/**
+ * Helper function to get the grid index of the current room.
+ *
+ * - If the current room is inside of the grid, this function will return the `SafeGridIndex` from
+ *   the room descriptor. (The safe grid index is defined as the top-left 1x1 section that the room
+ *   overlaps with, or the top-right 1x1 section of a `RoomType.SHAPE_LTL` room.)
+ * - If the current room is outside of the grid, it will return the index from the
+ *   `Level.GetCurrentRoomIndex` method (since `SafeGridIndex` is bugged for these cases).
+ *
+ * Use this function instead of the `Level.GetCurrentRoomIndex` method directly because the latter
+ * will return the specific 1x1 quadrant that the player entered the room at. For most situations,
+ * using the safe grid index is more reliable than this.
+ *
+ * Data structures that store data per room should use the room's `ListIndex` instead of
+ * `SafeGridIndex`, since the former is unique across different dimensions.
+ */
+export declare function getRoomGridIndex(): int;
+/**
+ * Helper function to get the list grid index of the provided room, which is equal to the index in
+ * the `RoomList.Get` method. In other words, this is equal to the order that the room was created
+ * by the floor generation algorithm.
+ *
+ * Use this as an index for data structures that store data per room, since it is unique across
+ * different dimensions.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ */
+export declare function getRoomListIndex(roomGridIndex?: int): int;
+/**
+ * Helper function to get the name of the room as it appears in the STB/XML data.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ * @returns The room name. Returns "Unknown" if the type was not found.
+ */
+export declare function getRoomName(roomGridIndex?: int): string;
+/**
+ * Helper function to get the name of the room as it appears in the STB/XML data.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ * @returns The room name. Returns "Unknown" if the type was not found.
+ */
+export declare function getRoomShape(roomGridIndex?: int): RoomShape | undefined;
+/**
+ * Helper function to get the stage ID for a room from the XML/STB data. The room stage ID will
+ * correspond to the first number in the filename of the XML/STB file. For example, a Depths room
+ * would have a stage ID of 7.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ * @returns The room stage ID. Returns -1 if the stage ID was not found.
+ */
+export declare function getRoomStageID(roomGridIndex?: int): StageID;
+/**
+ * Helper function to get the sub-type for a room from the XML/STB data. The room sub-type will
+ * correspond to different things depending on what XML/STB file it draws from. For example, in the
+ * "00.special rooms.stb" file, an Angel Room with a sub-type of 0 will correspond to a normal Angel
+ * Room and a sub-type of 1 will correspond to an Angel Room shop for The Stairway.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ * @returns The room sub-type. Returns -1 if the sub-type was not found.
+ */
+export declare function getRoomSubType(roomGridIndex?: int): int;
+/**
+ * Helper function for getting the type of the room with the given grid index.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ * @returns The room data type. Returns -1 if the type was not found.
+ */
+export declare function getRoomType(roomGridIndex?: int): RoomType;
+/**
+ * Helper function to get the variant for a room from the XML/STB data. You can think of a room
+ * variant as its identifier. For example, to go to Basement room #123, you would use a console
+ * command of `goto d.123` while on the Basement.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ * @returns The room variant. Returns -1 if the variant was not found.
+ */
+export declare function getRoomVariant(roomGridIndex?: int): int;
+/**
+ * Note that the room visited count will be inaccurate during the period before the PostNewRoom
+ * callback has fired (i.e. when entities are initializing and performing their first update). This
+ * is because the variable is only incremented immediately before the PostNewRoom callback fires.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ */
+export declare function getRoomVisitedCount(roomGridIndex?: int): int;

package/functions/roomData.lua

@@ -0,0 +1,160 @@
+local ____lualib = require("lualib_bundle")
+local Set = ____lualib.Set
+local __TS__New = ____lualib.__TS__New
+local ____exports = {}
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local DoorSlotFlag = ____isaac_2Dtypescript_2Ddefinitions.DoorSlotFlag
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+local ____doors = require("functions.doors")
+local doorSlotFlagToDoorSlot = ____doors.doorSlotFlagToDoorSlot
+local ____enums = require("functions.enums")
+local getEnumValues = ____enums.getEnumValues
+local ____flag = require("functions.flag")
+local hasFlag = ____flag.hasFlag
+--- Alias for the `Level.GetCurrentRoomDesc` method. Use this to make it more clear what type of
+-- `RoomDescriptor` object that you are retrieving.
+function ____exports.getCurrentRoomDescriptorReadOnly(self)
+    local level = game:GetLevel()
+    return level:GetCurrentRoomDesc()
+end
+--- Helper function to get the room data for the provided room.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
+function ____exports.getRoomData(self, roomGridIndex)
+    local roomDescriptor = ____exports.getRoomDescriptor(nil, roomGridIndex)
+    return roomDescriptor.Data
+end
+--- Helper function to get the descriptor for a room.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
+function ____exports.getRoomDescriptor(self, roomGridIndex)
+    local level = game:GetLevel()
+    if roomGridIndex == nil then
+        roomGridIndex = ____exports.getRoomGridIndex(nil)
+    end
+    return level:GetRoomByIdx(roomGridIndex)
+end
+--- Helper function to get the grid index of the current room.
+-- 
+-- - If the current room is inside of the grid, this function will return the `SafeGridIndex` from
+--   the room descriptor. (The safe grid index is defined as the top-left 1x1 section that the room
+--   overlaps with, or the top-right 1x1 section of a `RoomType.SHAPE_LTL` room.)
+-- - If the current room is outside of the grid, it will return the index from the
+--   `Level.GetCurrentRoomIndex` method (since `SafeGridIndex` is bugged for these cases).
+-- 
+-- Use this function instead of the `Level.GetCurrentRoomIndex` method directly because the latter
+-- will return the specific 1x1 quadrant that the player entered the room at. For most situations,
+-- using the safe grid index is more reliable than this.
+-- 
+-- Data structures that store data per room should use the room's `ListIndex` instead of
+-- `SafeGridIndex`, since the former is unique across different dimensions.
+function ____exports.getRoomGridIndex(self)
+    local level = game:GetLevel()
+    local currentRoomIndex = level:GetCurrentRoomIndex()
+    if currentRoomIndex < 0 then
+        return currentRoomIndex
+    end
+    local roomDescriptor = ____exports.getCurrentRoomDescriptorReadOnly(nil)
+    return roomDescriptor.SafeGridIndex
+end
+--- Helper function to get the set of allowed door slots for the room at the supplied grid index.
+-- This corresponds to the doors that are enabled in the STB/XML file for the room.
+function ____exports.getRoomAllowedDoors(self, roomGridIndex)
+    local allowedDoors = __TS__New(Set)
+    local roomData = ____exports.getRoomData(nil, roomGridIndex)
+    if roomData == nil then
+        return allowedDoors
+    end
+    local doorSlotFlags = getEnumValues(nil, DoorSlotFlag)
+    for ____, doorSlotFlag in ipairs(doorSlotFlags) do
+        if hasFlag(nil, roomData.Doors, doorSlotFlag) then
+            local doorSlot = doorSlotFlagToDoorSlot(nil, doorSlotFlag)
+            allowedDoors:add(doorSlot)
+        end
+    end
+    return allowedDoors
+end
+--- Helper function to get the list grid index of the provided room, which is equal to the index in
+-- the `RoomList.Get` method. In other words, this is equal to the order that the room was created
+-- by the floor generation algorithm.
+-- 
+-- Use this as an index for data structures that store data per room, since it is unique across
+-- different dimensions.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
+function ____exports.getRoomListIndex(self, roomGridIndex)
+    local roomDescriptor = ____exports.getRoomDescriptor(nil, roomGridIndex)
+    return roomDescriptor.ListIndex
+end
+--- Helper function to get the name of the room as it appears in the STB/XML data.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
+-- @returns The room name. Returns "Unknown" if the type was not found.
+function ____exports.getRoomName(self, roomGridIndex)
+    local roomData = ____exports.getRoomData(nil, roomGridIndex)
+    return roomData == nil and "Unknown" or roomData.Name
+end
+--- Helper function to get the name of the room as it appears in the STB/XML data.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
+-- @returns The room name. Returns "Unknown" if the type was not found.
+function ____exports.getRoomShape(self, roomGridIndex)
+    local roomData = ____exports.getRoomData(nil, roomGridIndex)
+    local ____temp_0
+    if roomData == nil then
+        ____temp_0 = nil
+    else
+        ____temp_0 = roomData.Shape
+    end
+    return ____temp_0
+end
+--- Helper function to get the stage ID for a room from the XML/STB data. The room stage ID will
+-- correspond to the first number in the filename of the XML/STB file. For example, a Depths room
+-- would have a stage ID of 7.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
+-- @returns The room stage ID. Returns -1 if the stage ID was not found.
+function ____exports.getRoomStageID(self, roomGridIndex)
+    local roomData = ____exports.getRoomData(nil, roomGridIndex)
+    return roomData == nil and -1 or roomData.StageID
+end
+--- Helper function to get the sub-type for a room from the XML/STB data. The room sub-type will
+-- correspond to different things depending on what XML/STB file it draws from. For example, in the
+-- "00.special rooms.stb" file, an Angel Room with a sub-type of 0 will correspond to a normal Angel
+-- Room and a sub-type of 1 will correspond to an Angel Room shop for The Stairway.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
+-- @returns The room sub-type. Returns -1 if the sub-type was not found.
+function ____exports.getRoomSubType(self, roomGridIndex)
+    local roomData = ____exports.getRoomData(nil, roomGridIndex)
+    return roomData == nil and -1 or roomData.Subtype
+end
+--- Helper function for getting the type of the room with the given grid index.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
+-- @returns The room data type. Returns -1 if the type was not found.
+function ____exports.getRoomType(self, roomGridIndex)
+    local roomData = ____exports.getRoomData(nil, roomGridIndex)
+    return roomData == nil and -1 or roomData.Type
+end
+--- Helper function to get the variant for a room from the XML/STB data. You can think of a room
+-- variant as its identifier. For example, to go to Basement room #123, you would use a console
+-- command of `goto d.123` while on the Basement.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
+-- @returns The room variant. Returns -1 if the variant was not found.
+function ____exports.getRoomVariant(self, roomGridIndex)
+    local roomData = ____exports.getRoomData(nil, roomGridIndex)
+    return roomData == nil and -1 or roomData.Variant
+end
+--- Note that the room visited count will be inaccurate during the period before the PostNewRoom
+-- callback has fired (i.e. when entities are initializing and performing their first update). This
+-- is because the variable is only incremented immediately before the PostNewRoom callback fires.
+-- 
+-- @param roomGridIndex Optional. Default is the current room index.
+function ____exports.getRoomVisitedCount(self, roomGridIndex)
+    local roomDescriptor = ____exports.getRoomDescriptor(nil, roomGridIndex)
+    return roomDescriptor.VisitedCount
+end
+return ____exports

package/functions/roomGrid.d.ts

@@ -0,0 +1,40 @@
+import { RoomShape } from "isaac-typescript-definitions";
+/**
+ * Helper function to convert grid coordinates to a world position `Vector`.
+ *
+ * For example, the coordinates of (0, 0) are equal to `Vector(80, 160)`.
+ */
+export declare function gridCoordinatesToWorldPosition(x: int, y: int): Vector;
+/**
+ * Helper function to convert a grid index to a grid position.
+ *
+ * For example, in a 1x1 room, grid index 0 is equal to "Vector(-1, -1) and grid index 16 is equal
+ * to "Vector(0, 0)".
+ */
+export declare function gridIndexToGridPosition(gridIndex: int, roomShape: RoomShape): Vector;
+/**
+ * Helper function to convert a grid position `Vector` to a world position `Vector`.
+ *
+ * For example, the coordinates of (0, 0) are equal to `Vector(80, 160)`.
+ */
+export declare function gridPositionToWorldPosition(gridPosition: Vector): Vector;
+/**
+ * Test if a grid position is actually in the given `RoomShape`.
+ *
+ * In this context, the grid position of the top-left wall is "Vector(-1, -1)".
+ */
+export declare function isValidGridPosition(gridPosition: Vector, roomShape: RoomShape): boolean;
+/**
+ * Helper function to convert a world position `Vector` to a grid position `Vector`.
+ *
+ * In this context, the grid position of the top-left wall is "Vector(-1, -1)".
+ */
+export declare function worldPositionToGridPosition(worldPos: Vector): Vector;
+/**
+ * Helper function to convert a world position `Vector` to a grid position `Vector`.
+ *
+ * In this context, the grid position of the top-left wall is "Vector(-1, -1)".
+ *
+ * This is similar to the `worldPositionToGridPosition` function, but the values are not rounded.
+ */
+export declare function worldPositionToGridPositionFast(worldPos: Vector): Vector;