isaacscript-common 2.3.0 → 3.0.0

package/functions/playerIndex.lua

@@ -0,0 +1,174 @@
+local ____lualib = require("lualib_bundle")
+local Set = ____lualib.Set
+local __TS__New = ____lualib.__TS__New
+local __TS__ArrayFind = ____lualib.__TS__ArrayFind
+local __TS__ArrayFilter = ____lualib.__TS__ArrayFilter
+local ____exports = {}
+local getPlayerIndexCollectibleType, DEFAULT_COLLECTIBLE_TYPE, EXCLUDED_CHARACTERS
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local CollectibleType = ____isaac_2Dtypescript_2Ddefinitions.CollectibleType
+local PlayerType = ____isaac_2Dtypescript_2Ddefinitions.PlayerType
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+--- Helper function to get every player with no restrictions, by using `Game.GetNumPlayers` and
+-- `Isaac.GetPlayer`.
+-- 
+-- This function is almost never what you want to use. For most purposes, use the `getPlayers`
+-- helper function instead to get a filtered list of players.
+function ____exports.getAllPlayers(self)
+    local numPlayers = game:GetNumPlayers()
+    local players = {}
+    do
+        local i = 0
+        while i < numPlayers do
+            local player = Isaac.GetPlayer(i)
+            players[#players + 1] = player
+            i = i + 1
+        end
+    end
+    return players
+end
+--- Mods often have to track variables relating to the player. In naive mods, information will only
+-- be stored about the first player. However, in order to be robust, mods must handle up to 4
+-- players playing at the same time. This means that information must be stored on a map data
+-- structure. Finding a good index for these types of map data structures is difficult:
+-- 
+-- - We cannot use the index from `Isaac.GetPlayer(i)` since this fails in the case where there are
+--   two players and the first player leaves the run.
+-- - We cannot use `EntityPlayer.ControllerIndex` as an index because it fails in the case of Jacob
+--   & Esau or Tainted Forgotten. It also fails in the case of a player changing their controls
+--   mid-run.
+-- - We cannot use `EntityPlayer.GetData().index` because it does not persist across saving and
+--   continuing.
+-- - We cannot use `GetPtrHash()` as an index because it does not persist across exiting and
+--   relaunching the game.
+-- - We cannot use `EntityPlayer.InitSeed` because it is not consistent with additional players
+--   beyond the first.
+-- 
+-- Instead, we use the `EntityPlayer.GetCollectibleRNG` method with an arbitrary value of Sad Onion
+-- (1). This works even if the player does not have any Sad Onions.
+-- 
+-- Since the RNG value is the same for both Tainted Lazarus and Dead Tainted Lazarus, we revert to
+-- using the RNG of The Inner Eye (2) for Dead Tainted Lazarus.
+-- 
+-- Note that by default, this returns the same index for both The Forgotten and The Soul. (Even
+-- though they are technically different characters, they share the same inventory and InitSeed.) If
+-- this is not desired, pass true for the `differentiateForgottenAndSoul` argument, and the RNG of
+-- Spoon Bender (3) will be used for The Soul.
+function ____exports.getPlayerIndex(self, player, differentiateForgottenAndSoul)
+    if differentiateForgottenAndSoul == nil then
+        differentiateForgottenAndSoul = false
+    end
+    local playerToUse = player
+    local isSubPlayer = player:IsSubPlayer()
+    if isSubPlayer then
+        local playerParent = ____exports.getSubPlayerParent(nil, player)
+        if playerParent ~= nil then
+            playerToUse = playerParent
+        end
+    end
+    local collectibleType = getPlayerIndexCollectibleType(nil, player, differentiateForgottenAndSoul)
+    local collectibleRNG = playerToUse:GetCollectibleRNG(collectibleType)
+    local seed = collectibleRNG:GetSeed()
+    return seed
+end
+function getPlayerIndexCollectibleType(self, player, differentiateForgottenAndSoul)
+    local character = player:GetPlayerType()
+    repeat
+        local ____switch10 = character
+        local ____cond10 = ____switch10 == PlayerType.THE_SOUL
+        if ____cond10 then
+            do
+                return differentiateForgottenAndSoul and CollectibleType.SPOON_BENDER or DEFAULT_COLLECTIBLE_TYPE
+            end
+        end
+        ____cond10 = ____cond10 or ____switch10 == PlayerType.LAZARUS_2_B
+        if ____cond10 then
+            do
+                return CollectibleType.INNER_EYE
+            end
+        end
+        do
+            do
+                return DEFAULT_COLLECTIBLE_TYPE
+            end
+        end
+    until true
+end
+--- This function always excludes players with a non-undefined parent, since they are not real
+-- players (e.g. the Strawman Keeper).
+-- 
+-- If this is not desired, use the `getAllPlayers` helper function instead.
+-- 
+-- @param performCharacterExclusions Whether or not to exclude characters that are not directly
+-- controlled by the player (i.e. Esau & Tainted Soul). Default is
+-- false.
+function ____exports.getPlayers(self, performCharacterExclusions)
+    if performCharacterExclusions == nil then
+        performCharacterExclusions = false
+    end
+    local players = ____exports.getAllPlayers(nil)
+    local nonChildPlayers = __TS__ArrayFilter(
+        players,
+        function(____, player) return not ____exports.isChildPlayer(nil, player) end
+    )
+    local nonChildPlayersFiltered = __TS__ArrayFilter(
+        nonChildPlayers,
+        function(____, player)
+            local character = player:GetPlayerType()
+            return not EXCLUDED_CHARACTERS:has(character)
+        end
+    )
+    return performCharacterExclusions and nonChildPlayersFiltered or nonChildPlayers
+end
+--- Helper function to get a parent `EntityPlayer` object for a given `EntitySubPlayer` object. This
+-- is useful because calling the `EntityPlayer.GetSubPlayer` method on a sub-player object will
+-- return undefined.
+function ____exports.getSubPlayerParent(self, subPlayer)
+    local subPlayerPtrHash = GetPtrHash(subPlayer)
+    local players = ____exports.getPlayers(nil)
+    return __TS__ArrayFind(
+        players,
+        function(____, player)
+            local thisPlayerSubPlayer = player:GetSubPlayer()
+            if thisPlayerSubPlayer == nil then
+                return false
+            end
+            local thisPlayerSubPlayerPtrHash = GetPtrHash(thisPlayerSubPlayer)
+            return thisPlayerSubPlayerPtrHash == subPlayerPtrHash
+        end
+    )
+end
+--- Some players are "child" players, meaning that they have a non-undefined Parent property. (For
+-- example, the Strawman Keeper.)
+function ____exports.isChildPlayer(self, player)
+    return player.Parent ~= nil
+end
+DEFAULT_COLLECTIBLE_TYPE = CollectibleType.SAD_ONION
+EXCLUDED_CHARACTERS = __TS__New(Set, {PlayerType.ESAU, PlayerType.THE_SOUL_B})
+function ____exports.getPlayerFromIndex(self, playerIndex)
+    local players = ____exports.getPlayers(nil)
+    return __TS__ArrayFind(
+        players,
+        function(____, player) return ____exports.getPlayerIndex(nil, player) == playerIndex end
+    )
+end
+--- Helper function to return the index of this player with respect to the output of the
+-- `Isaac.GetPlayer` method.
+function ____exports.getPlayerIndexVanilla(self, playerToFind)
+    local numPlayers = game:GetNumPlayers()
+    local playerToFindHash = GetPtrHash(playerToFind)
+    do
+        local i = 0
+        while i < numPlayers do
+            local player = Isaac.GetPlayer(i)
+            local playerHash = GetPtrHash(player)
+            if playerHash == playerToFindHash then
+                return i
+            end
+            i = i + 1
+        end
+    end
+    return nil
+end
+return ____exports

package/functions/pocketItems.d.ts

@@ -0,0 +1,33 @@
+import { PocketItemSlot } from "isaac-typescript-definitions";
+import { PocketItemDescription } from "../interfaces/PocketItemDescription";
+/**
+ * Helper function to get the `PocketItemSlot` that the player's pocket active collectible item is
+ * in, if any. Returns undefined if the player does not have a pocket active item.
+ */
+export declare function getActivePocketItemSlot(player: EntityPlayer): PocketItemSlot | undefined;
+export declare function getFirstCardOrPill(player: EntityPlayer): PocketItemDescription | undefined;
+/**
+ * Use this helper function as a workaround for the `EntityPlayer.GetPocketItem` method not working
+ * correctly.
+ *
+ * Note that due to API limitations, there is no way to determine the location of a Dice Bag trinket
+ * dice. Furthermore, when the player has a Dice Bag trinket dice and a pocket active at the same
+ * time, there is no way to determine the location of the pocket active item. If this function
+ * cannot determine the identity of a particular slot, it will mark the type of the slot as
+ * `PocketItemType.UNDETERMINABLE`.
+ */
+export declare function getPocketItems(player: EntityPlayer): PocketItemDescription[];
+/**
+ * Returns whether or not the player can hold an additional pocket item, beyond what they are
+ * currently carrying. This takes into account items that modify the max number of pocket items,
+ * like Starter Deck.
+ *
+ * If the player is the Tainted Soul, this always returns false, since that character cannot pick up
+ * items. (Only Tainted Forgotten can pick up items.)
+ */
+export declare function hasOpenPocketItemSlot(player: EntityPlayer): boolean;
+/**
+ * Helper function to determine whether or not the player's "active" pocket item slot is set to
+ * their pocket active item.
+ */
+export declare function isFirstSlotPocketActiveItem(player: EntityPlayer): boolean;

package/functions/pocketItems.lua

@@ -0,0 +1,104 @@
+local ____lualib = require("lualib_bundle")
+local __TS__ArrayFind = ____lualib.__TS__ArrayFind
+local __TS__ArraySome = ____lualib.__TS__ArraySome
+local ____exports = {}
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local ActiveSlot = ____isaac_2Dtypescript_2Ddefinitions.ActiveSlot
+local Card = ____isaac_2Dtypescript_2Ddefinitions.Card
+local CollectibleType = ____isaac_2Dtypescript_2Ddefinitions.CollectibleType
+local PillColor = ____isaac_2Dtypescript_2Ddefinitions.PillColor
+local PlayerType = ____isaac_2Dtypescript_2Ddefinitions.PlayerType
+local PocketItemSlot = ____isaac_2Dtypescript_2Ddefinitions.PocketItemSlot
+local ____PocketItemType = require("enums.PocketItemType")
+local PocketItemType = ____PocketItemType.PocketItemType
+local ____enums = require("functions.enums")
+local getEnumValues = ____enums.getEnumValues
+local ____player = require("functions.player")
+local isCharacter = ____player.isCharacter
+--- Use this helper function as a workaround for the `EntityPlayer.GetPocketItem` method not working
+-- correctly.
+-- 
+-- Note that due to API limitations, there is no way to determine the location of a Dice Bag trinket
+-- dice. Furthermore, when the player has a Dice Bag trinket dice and a pocket active at the same
+-- time, there is no way to determine the location of the pocket active item. If this function
+-- cannot determine the identity of a particular slot, it will mark the type of the slot as
+-- `PocketItemType.UNDETERMINABLE`.
+function ____exports.getPocketItems(self, player)
+    local pocketItem = player:GetActiveItem(ActiveSlot.POCKET)
+    local hasPocketItem = pocketItem ~= CollectibleType.NULL
+    local pocketItem2 = player:GetActiveItem(ActiveSlot.POCKET_SINGLE_USE)
+    local hasPocketItem2 = pocketItem2 ~= CollectibleType.NULL
+    local maxPocketItems = player:GetMaxPocketItems()
+    local pocketItemSlots = getEnumValues(nil, PocketItemSlot)
+    local pocketItems = {}
+    local pocketItemIdentified = false
+    local pocketItem2Identified = false
+    for ____, slot in ipairs(pocketItemSlots) do
+        local card = player:GetCard(slot)
+        local pillColor = player:GetPill(slot)
+        if card ~= Card.NULL then
+            pocketItems[#pocketItems + 1] = {slot = slot, type = PocketItemType.CARD, subType = card}
+        elseif pillColor ~= PillColor.NULL then
+            pocketItems[#pocketItems + 1] = {slot = slot, type = PocketItemType.PILL, subType = pillColor}
+        elseif hasPocketItem and not hasPocketItem2 and not pocketItemIdentified then
+            pocketItemIdentified = true
+            pocketItems[#pocketItems + 1] = {slot = slot, type = PocketItemType.ACTIVE_ITEM, subType = pocketItem}
+        elseif not hasPocketItem and hasPocketItem2 and not pocketItem2Identified then
+            pocketItem2Identified = true
+            pocketItems[#pocketItems + 1] = {slot = slot, type = PocketItemType.DICE_BAG_DICE, subType = pocketItem2}
+        elseif hasPocketItem and hasPocketItem2 then
+            pocketItems[#pocketItems + 1] = {slot = slot, type = PocketItemType.UNDETERMINABLE, subType = 0}
+        else
+            pocketItems[#pocketItems + 1] = {slot = slot, type = PocketItemType.EMPTY, subType = 0}
+        end
+        if slot + 1 == maxPocketItems then
+            break
+        end
+    end
+    return pocketItems
+end
+--- Helper function to get the `PocketItemSlot` that the player's pocket active collectible item is
+-- in, if any. Returns undefined if the player does not have a pocket active item.
+function ____exports.getActivePocketItemSlot(self, player)
+    local pocketItems = ____exports.getPocketItems(nil, player)
+    for ____, pocketItem in ipairs(pocketItems) do
+        if pocketItem.type == PocketItemType.ACTIVE_ITEM then
+            return pocketItem.slot
+        end
+    end
+    return nil
+end
+function ____exports.getFirstCardOrPill(self, player)
+    local pocketItems = ____exports.getPocketItems(nil, player)
+    return __TS__ArrayFind(
+        pocketItems,
+        function(____, pocketItem) return pocketItem.type == PocketItemType.CARD or pocketItem.type == PocketItemType.PILL end
+    )
+end
+--- Returns whether or not the player can hold an additional pocket item, beyond what they are
+-- currently carrying. This takes into account items that modify the max number of pocket items,
+-- like Starter Deck.
+-- 
+-- If the player is the Tainted Soul, this always returns false, since that character cannot pick up
+-- items. (Only Tainted Forgotten can pick up items.)
+function ____exports.hasOpenPocketItemSlot(self, player)
+    if isCharacter(nil, player, PlayerType.THE_SOUL_B) then
+        return false
+    end
+    local pocketItems = ____exports.getPocketItems(nil, player)
+    return __TS__ArraySome(
+        pocketItems,
+        function(____, pocketItem) return pocketItem.type == PocketItemType.EMPTY end
+    )
+end
+--- Helper function to determine whether or not the player's "active" pocket item slot is set to
+-- their pocket active item.
+function ____exports.isFirstSlotPocketActiveItem(self, player)
+    local pocketItems = ____exports.getPocketItems(nil, player)
+    local firstPocketItem = pocketItems[1]
+    if firstPocketItem == nil then
+        return false
+    end
+    return firstPocketItem.type == PocketItemType.ACTIVE_ITEM
+end
+return ____exports

package/functions/positionVelocity.d.ts

@@ -0,0 +1,64 @@
+/// <reference types="isaac-typescript-definitions" />
+export declare function anyEntityCloserThan(entities: Entity[], position: Vector, distance: int): boolean;
+/** Iterates over all players and checks if any player is close enough to the specified position. */
+export declare function anyPlayerCloserThan(position: Vector, distance: float): boolean;
+/**
+ * Helper function to get a room position that is not overlapping with a grid entity, a heaven door,
+ * or a player. The `Room.FindFreePickupSpawnPosition` method will return locations that overlap
+ * with heaven doors and partially overlap with players, if the thing being spawned is bigger than a
+ * tile (like a Blood Donation Machine). Use this function instead if you want to account for those
+ * specific situations.
+ *
+ * @param startingPosition The position to start searching from. If this position is not overlapping
+ *                         with anything, then it will be returned.
+ * @param avoidActiveEntities Optional. Default is false.
+ */
+export declare function findFreePosition(startingPosition: Vector, avoidActiveEntities?: boolean): Vector;
+/**
+ * Helper function to get a map containing the positions of every entity in the current room.
+ *
+ * This is useful for rewinding entity positions at a later time. Also see `setEntityPositions`.
+ *
+ * @param entities Optional. If provided, will only get the positions of the provided entities. Use
+ *                 this with cached entities to avoid invoking the `Isaac.GetRoomEntities` method
+ *                 multiple times.
+ */
+export declare function getEntityPositions(entities?: Entity[]): Map<PtrHash, Vector>;
+/**
+ * Helper function to get a map containing the velocities of every entity in the current room.
+ *
+ * This is useful for rewinding entity velocities at a later time. Also see `setEntityVelocities`.
+ *
+ * @param entities Optional. If provided, will only get the velocities of the provided entities. Use
+ *                 this with cached entities to avoid invoking the `Isaac.GetRoomEntities` method
+ *                 multiple times.
+ */
+export declare function getEntityVelocities(entities?: Entity[]): Map<PtrHash, Vector>;
+/**
+ * Helper function to set the position of every entity in the room based on a map of positions. If
+ * an entity is found that does not have matching element in the provided map, then that entity will
+ * be skipped.
+ *
+ * This function is useful for rewinding entity positions at a later time. Also see
+ * `getEntityPositions`.
+ *
+ * @param entityPositions The map providing the positions for every entity.
+ * @param entities Optional. If provided, will only set the positions of the provided entities. Use
+ *                 this with cached entities to avoid invoking the `Isaac.GetRoomEntities` method
+ *                 multiple times.
+ */
+export declare function setEntityPositions(entityPositions: Map<PtrHash, Vector>, entities?: Entity[]): void;
+/**
+ * Helper function to set the velocity of every entity in the room based on a map of velocities. If
+ * an entity is found that does not have matching element in the provided map, then that entity will
+ * be skipped.
+ *
+ * This function is useful for rewinding entity velocities at a later time. Also see
+ * `getEntityVelocities`.
+ *
+ * @param entityVelocities The map providing the velocities for every entity.
+ * @param entities Optional. If provided, will only set the velocities of the provided entities. Use
+ *                 this with cached entities to avoid invoking the `Isaac.GetRoomEntities` method
+ *                 multiple times.
+ */
+export declare function setEntityVelocities(entityVelocities: Map<PtrHash, Vector>, entities?: Entity[]): void;

package/functions/positionVelocity.lua

@@ -0,0 +1,154 @@
+local ____lualib = require("lualib_bundle")
+local __TS__ArraySome = ____lualib.__TS__ArraySome
+local Map = ____lualib.Map
+local __TS__New = ____lualib.__TS__New
+local ____exports = {}
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local EffectVariant = ____isaac_2Dtypescript_2Ddefinitions.EffectVariant
+local HeavenLightDoorSubType = ____isaac_2Dtypescript_2Ddefinitions.HeavenLightDoorSubType
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+local ____constants = require("constants")
+local DISTANCE_OF_GRID_TILE = ____constants.DISTANCE_OF_GRID_TILE
+local ____entity = require("functions.entity")
+local getEntities = ____entity.getEntities
+local ____entitySpecific = require("functions.entitySpecific")
+local getEffects = ____entitySpecific.getEffects
+local ____player = require("functions.player")
+local getPlayerCloserThan = ____player.getPlayerCloserThan
+local ____playerIndex = require("functions.playerIndex")
+local getPlayers = ____playerIndex.getPlayers
+local MAX_FIND_FREE_POSITION_ATTEMPTS = 100
+function ____exports.anyEntityCloserThan(self, entities, position, distance)
+    return __TS__ArraySome(
+        entities,
+        function(____, entity) return position:Distance(entity.Position) <= distance end
+    )
+end
+--- Iterates over all players and checks if any player is close enough to the specified position.
+function ____exports.anyPlayerCloserThan(self, position, distance)
+    local players = getPlayers(nil)
+    return __TS__ArraySome(
+        players,
+        function(____, player) return player.Position:Distance(position) <= distance end
+    )
+end
+--- Helper function to get a room position that is not overlapping with a grid entity, a heaven door,
+-- or a player. The `Room.FindFreePickupSpawnPosition` method will return locations that overlap
+-- with heaven doors and partially overlap with players, if the thing being spawned is bigger than a
+-- tile (like a Blood Donation Machine). Use this function instead if you want to account for those
+-- specific situations.
+-- 
+-- @param startingPosition The position to start searching from. If this position is not overlapping
+-- with anything, then it will be returned.
+-- @param avoidActiveEntities Optional. Default is false.
+function ____exports.findFreePosition(self, startingPosition, avoidActiveEntities)
+    if avoidActiveEntities == nil then
+        avoidActiveEntities = false
+    end
+    local room = game:GetRoom()
+    local heavenDoors = getEffects(nil, EffectVariant.HEAVEN_LIGHT_DOOR, HeavenLightDoorSubType.HEAVEN_DOOR)
+    do
+        local i = 0
+        while i < MAX_FIND_FREE_POSITION_ATTEMPTS do
+            do
+                local position = room:FindFreePickupSpawnPosition(startingPosition, i, avoidActiveEntities)
+                local closePlayer = getPlayerCloserThan(nil, position, DISTANCE_OF_GRID_TILE)
+                if closePlayer ~= nil then
+                    goto __continue7
+                end
+                local isCloseHeavenDoor = ____exports.anyEntityCloserThan(nil, heavenDoors, position, DISTANCE_OF_GRID_TILE)
+                if isCloseHeavenDoor then
+                    goto __continue7
+                end
+                return position
+            end
+            ::__continue7::
+            i = i + 1
+        end
+    end
+    return room:FindFreePickupSpawnPosition(startingPosition)
+end
+--- Helper function to get a map containing the positions of every entity in the current room.
+-- 
+-- This is useful for rewinding entity positions at a later time. Also see `setEntityPositions`.
+-- 
+-- @param entities Optional. If provided, will only get the positions of the provided entities. Use
+-- this with cached entities to avoid invoking the `Isaac.GetRoomEntities` method
+-- multiple times.
+function ____exports.getEntityPositions(self, entities)
+    if entities == nil then
+        entities = getEntities(nil)
+    end
+    local entityPositions = __TS__New(Map)
+    for ____, entity in ipairs(entities) do
+        local ptrHash = GetPtrHash(entity)
+        entityPositions:set(ptrHash, entity.Position)
+    end
+    return entityPositions
+end
+--- Helper function to get a map containing the velocities of every entity in the current room.
+-- 
+-- This is useful for rewinding entity velocities at a later time. Also see `setEntityVelocities`.
+-- 
+-- @param entities Optional. If provided, will only get the velocities of the provided entities. Use
+-- this with cached entities to avoid invoking the `Isaac.GetRoomEntities` method
+-- multiple times.
+function ____exports.getEntityVelocities(self, entities)
+    if entities == nil then
+        entities = getEntities(nil)
+    end
+    local entityVelocities = __TS__New(Map)
+    for ____, entity in ipairs(entities) do
+        local ptrHash = GetPtrHash(entity)
+        entityVelocities:set(ptrHash, entity.Velocity)
+    end
+    return entityVelocities
+end
+--- Helper function to set the position of every entity in the room based on a map of positions. If
+-- an entity is found that does not have matching element in the provided map, then that entity will
+-- be skipped.
+-- 
+-- This function is useful for rewinding entity positions at a later time. Also see
+-- `getEntityPositions`.
+-- 
+-- @param entityPositions The map providing the positions for every entity.
+-- @param entities Optional. If provided, will only set the positions of the provided entities. Use
+-- this with cached entities to avoid invoking the `Isaac.GetRoomEntities` method
+-- multiple times.
+function ____exports.setEntityPositions(self, entityPositions, entities)
+    if entities == nil then
+        entities = getEntities(nil)
+    end
+    for ____, entity in ipairs(entities) do
+        local ptrHash = GetPtrHash(entity)
+        local entityPosition = entityPositions:get(ptrHash)
+        if entityPosition ~= nil then
+            entity.Position = entityPosition
+        end
+    end
+end
+--- Helper function to set the velocity of every entity in the room based on a map of velocities. If
+-- an entity is found that does not have matching element in the provided map, then that entity will
+-- be skipped.
+-- 
+-- This function is useful for rewinding entity velocities at a later time. Also see
+-- `getEntityVelocities`.
+-- 
+-- @param entityVelocities The map providing the velocities for every entity.
+-- @param entities Optional. If provided, will only set the velocities of the provided entities. Use
+-- this with cached entities to avoid invoking the `Isaac.GetRoomEntities` method
+-- multiple times.
+function ____exports.setEntityVelocities(self, entityVelocities, entities)
+    if entities == nil then
+        entities = getEntities(nil)
+    end
+    for ____, entity in ipairs(entities) do
+        local ptrHash = GetPtrHash(entity)
+        local entityVelocity = entityVelocities:get(ptrHash)
+        if entityVelocity ~= nil then
+            entity.Velocity = entityVelocity
+        end
+    end
+end
+return ____exports

package/functions/random.d.ts

@@ -0,0 +1,42 @@
+/// <reference types="isaac-typescript-definitions" />
+/**
+ * This returns a random float between 0 and 1. It is inclusive on the low end, but exclusive on the
+ * high end. (This is because the `RNG.RandomFloat` method will never return a value of exactly 1.)
+ *
+ * @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()`.
+ */
+export declare function getRandom(seedOrRNG?: Seed | RNG): float;
+/**
+ * This returns a random float between min and max.
+ *
+ * For example:
+ *
+ * ```ts
+ * const realNumberBetweenOneAndThree = getRandomFloat(1, 3);
+ * ```
+ *
+ * @param min The lower bound for the random number (inclusive).
+ * @param max The upper bound for the random number (exclusive).
+ * @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()`.
+ */
+export declare function getRandomFloat(min: int, max: int, seedOrRNG?: Seed | RNG): float;
+/**
+ * This returns a random integer between min and max. It is inclusive on both ends.
+ *
+ * Note that this function will invoke the `Next` method on the `RNG` object before returning the
+ * random number.
+ *
+ * For example:
+ *
+ * ```ts
+ * const oneTwoOrThree = getRandomInt(1, 3);
+ * ```
+ *
+ * @param min The lower bound for the random number (inclusive).
+ * @param max The upper bound for the random number (inclusive).
+ * @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()`.
+ */
+export declare function getRandomInt(min: int, max: int, seedOrRNG?: Seed | RNG): int;

package/functions/random.lua

@@ -0,0 +1,70 @@
+local ____exports = {}
+local ____rng = require("functions.rng")
+local getRandomSeed = ____rng.getRandomSeed
+local isRNG = ____rng.isRNG
+local newRNG = ____rng.newRNG
+--- This returns a random float between 0 and 1. It is inclusive on the low end, but exclusive on the
+-- high end. (This is because the `RNG.RandomFloat` method will never return a value of exactly 1.)
+-- 
+-- @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()`.
+function ____exports.getRandom(self, seedOrRNG)
+    if seedOrRNG == nil then
+        seedOrRNG = getRandomSeed(nil)
+    end
+    local rng = isRNG(nil, seedOrRNG) and seedOrRNG or newRNG(nil, seedOrRNG)
+    return rng:RandomFloat()
+end
+--- This returns a random float between min and max.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const realNumberBetweenOneAndThree = getRandomFloat(1, 3);
+-- ```
+-- 
+-- @param min The lower bound for the random number (inclusive).
+-- @param max The upper bound for the random number (exclusive).
+-- @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()`.
+function ____exports.getRandomFloat(self, min, max, seedOrRNG)
+    if seedOrRNG == nil then
+        seedOrRNG = getRandomSeed(nil)
+    end
+    if min > max then
+        local oldMin = min
+        local oldMax = max
+        min = oldMax
+        max = oldMin
+    end
+    return min + ____exports.getRandom(nil, seedOrRNG) * (max - min)
+end
+--- This returns a random integer between min and max. It is inclusive on both ends.
+-- 
+-- Note that this function will invoke the `Next` method on the `RNG` object before returning the
+-- random number.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const oneTwoOrThree = getRandomInt(1, 3);
+-- ```
+-- 
+-- @param min The lower bound for the random number (inclusive).
+-- @param max The upper bound for the random number (inclusive).
+-- @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()`.
+function ____exports.getRandomInt(self, min, max, seedOrRNG)
+    if seedOrRNG == nil then
+        seedOrRNG = getRandomSeed(nil)
+    end
+    local rng = isRNG(nil, seedOrRNG) and seedOrRNG or newRNG(nil, seedOrRNG)
+    if min > max then
+        local oldMin = min
+        local oldMax = max
+        min = oldMax
+        max = oldMin
+    end
+    return rng:RandomInt(max - min + 1) + min
+end
+return ____exports

package/functions/revive.d.ts

@@ -0,0 +1,31 @@
+/// <reference types="isaac-typescript-definitions" />
+/**
+ * Uses the player's current health and other miscellaneous things to determine if incoming damage
+ * will be fatal.
+ */
+export declare function isDamageToPlayerFatal(player: EntityPlayer, damageAmount: int, damageSource: EntityRef, lastDamageGameFrame: int | undefined): boolean;
+/**
+ * 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`
+ */
+export declare function willMysteriousPaperRevive(player: EntityPlayer): boolean;
+/**
+ * The `EntityPlayer.WillPlayerRevive` method does not properly account for Mysterious Paper, so use
+ * this helper function instead for more robust revival detection.
+ */
+export declare function willPlayerRevive(player: EntityPlayer): boolean;
+/**
+ * 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.
+ */
+export declare function willReviveFromHeartbreak(player: EntityPlayer): boolean;
+/**
+ * Helper function to determine if the Spirit Shackles item is in an enabled state. (It can be
+ * either enabled or disabled.)
+ */
+export declare function willReviveFromSpiritShackles(player: EntityPlayer): boolean;