isaacscript-common 6.6.1-dev.2 → 6.6.1

package/dist/functions/playerIndex.d.ts

@@ -0,0 +1,74 @@
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+import { PlayerIndex } from "../types/PlayerIndex";
+/**
+ * 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.
+ */
+export declare function getAllPlayers(): EntityPlayer[];
+export declare function getPlayerFromIndex(playerIndex: PlayerIndex): EntityPlayer | undefined;
+/**
+ * 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.
+ */
+export declare function getPlayerIndex(player: EntityPlayer, differentiateForgottenAndSoul?: boolean): PlayerIndex;
+/**
+ * Helper function to return the index of this player with respect to the output of the
+ * `Isaac.GetPlayer` method.
+ *
+ * Note that if you storing information about a player in a data structure, you never want to use
+ * this index; use the `getPlayerIndex` function instead.
+ */
+export declare function getPlayerIndexVanilla(playerToFind: EntityPlayer): int | undefined;
+/**
+ * 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.
+ */
+export declare function getPlayers(performCharacterExclusions?: boolean): EntityPlayer[];
+/**
+ * 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.
+ */
+export declare function getSubPlayerParent(subPlayer: EntitySubPlayer): EntityPlayer | undefined;
+/**
+ * Some players are "child" players, meaning that they have a non-undefined Parent property. (For
+ * example, the Strawman Keeper.)
+ */
+export declare function isChildPlayer(player: EntityPlayer): boolean;
+//# sourceMappingURL=playerIndex.d.ts.map

package/dist/functions/playerIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playerIndex.d.ts","sourceRoot":"","sources":["../../../../../packages/isaacscript-common/src/functions/playerIndex.ts"],"names":[],"mappings":";;;AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AASnD;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,YAAY,EAAE,CAU9C;AAED,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,WAAW,GACvB,YAAY,GAAG,SAAS,CAG1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,YAAY,EACpB,6BAA6B,UAAQ,GACpC,WAAW,CA4Bb;AA2BD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,YAAY,GACzB,GAAG,GAAG,SAAS,CAajB;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,0BAA0B,UAAQ,GAAG,YAAY,EAAE,CAS7E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,eAAe,GACzB,YAAY,GAAG,SAAS,CAa1B;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAE3D"}

package/dist/functions/playerIndex.lua

@@ -0,0 +1,177 @@
+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.
+-- 
+-- Note that if you storing information about a player in a data structure, you never want to use
+-- this index; use the `getPlayerIndex` function instead.
+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/dist/functions/pocketItems.d.ts

@@ -0,0 +1,34 @@
+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;
+//# sourceMappingURL=pocketItems.d.ts.map

package/dist/functions/pocketItems.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pocketItems.d.ts","sourceRoot":"","sources":["../../../../../packages/isaacscript-common/src/functions/pocketItems.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,cAAc,EACf,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAI5E;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,GACnB,cAAc,GAAG,SAAS,CAS5B;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,GACnB,qBAAqB,GAAG,SAAS,CAOnC;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,qBAAqB,EAAE,CAgE5E;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CASnE;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAQzE"}

package/dist/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/dist/functions/positionVelocity.d.ts

@@ -0,0 +1,68 @@
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <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;
+//# sourceMappingURL=positionVelocity.d.ts.map

package/dist/functions/positionVelocity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"positionVelocity.d.ts","sourceRoot":"","sources":["../../../../../packages/isaacscript-common/src/functions/positionVelocity.ts"],"names":[],"mappings":";;;;AAaA,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAAE,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,GAAG,GACZ,OAAO,CAIT;AAED,oGAAoG;AACpG,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,KAAK,GACd,OAAO,CAKT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,gBAAgB,EAAE,MAAM,EACxB,mBAAmB,UAAQ,GAC1B,MAAM,CAiCR;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAY5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAY7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,eAAe,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,EACrC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,IAAI,CAYN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,EACtC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,IAAI,CAYN"}

package/dist/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