isaacscript-common 2.3.2 → 3.1.1

package/functions/playerHealth.lua

@@ -1,4 +1,5 @@
 local ____lualib = require("lualib_bundle")
+local __TS__ArrayMap = ____lualib.__TS__ArrayMap
 local __TS__ArrayForEach = ____lualib.__TS__ArrayForEach
 local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
@@ -16,6 +17,79 @@ local isCharacter = ____player.isCharacter
 local ____utils = require("functions.utils")
 local ensureAllCases = ____utils.ensureAllCases
 local ____repeat = ____utils["repeat"]
+function ____exports.removeAllPlayerHealth(self, player)
+    local goldenHearts = player:GetGoldenHearts()
+    local eternalHearts = player:GetEternalHearts()
+    local boneHearts = player:GetBoneHearts()
+    local brokenHearts = player:GetBrokenHearts()
+    player:AddGoldenHearts(goldenHearts * -1)
+    player:AddEternalHearts(eternalHearts * -1)
+    player:AddBoneHearts(boneHearts * -1)
+    player:AddBrokenHearts(brokenHearts * -1)
+    player:AddMaxHearts(MAX_PLAYER_HEART_CONTAINERS * -2, true)
+    player:AddSoulHearts(MAX_PLAYER_HEART_CONTAINERS * -2)
+    if isCharacter(nil, player, PlayerType.THE_SOUL) then
+        local forgotten = player:GetSubPlayer()
+        if forgotten ~= nil then
+            local forgottenBoneHearts = forgotten:GetBoneHearts()
+            forgotten:AddBoneHearts(forgottenBoneHearts * -1)
+        end
+    end
+end
+--- Helper function to set a player's health to a specific state. You can use this in combination
+-- with the `getPlayerHealth` function to restore the player's health back to a certain
+-- configuration at a later time.
+-- 
+-- Based on the `REVEL.LoadHealth` function in the Revelations mod.
+function ____exports.setPlayerHealth(self, player, playerHealth)
+    local character = player:GetPlayerType()
+    local subPlayer = player:GetSubPlayer()
+    ____exports.removeAllPlayerHealth(nil, player)
+    if character == PlayerType.THE_SOUL and subPlayer ~= nil then
+        subPlayer:AddMaxHearts(playerHealth.maxHearts, false)
+    else
+        player:AddMaxHearts(playerHealth.maxHearts, false)
+    end
+    player:AddEternalHearts(playerHealth.eternalHearts)
+    local soulHeartsRemaining = playerHealth.soulHearts
+    __TS__ArrayForEach(
+        playerHealth.soulHeartTypes,
+        function(____, heartType, i)
+            local isHalf = playerHealth.soulHearts + playerHealth.boneHearts * 2 < (i + 1) * 2
+            local addAmount = 2
+            if isHalf or heartType == HeartSubType.BONE or soulHeartsRemaining < 2 then
+                addAmount = 1
+            end
+            if heartType == HeartSubType.SOUL then
+                player:AddSoulHearts(addAmount)
+                soulHeartsRemaining = soulHeartsRemaining - addAmount
+            elseif heartType == HeartSubType.BLACK then
+                player:AddBlackHearts(addAmount)
+                soulHeartsRemaining = soulHeartsRemaining - addAmount
+            elseif heartType == HeartSubType.BONE then
+                player:AddBoneHearts(addAmount)
+            end
+        end
+    )
+    player:AddRottenHearts(playerHealth.rottenHearts)
+    ____repeat(
+        nil,
+        playerHealth.hearts,
+        function()
+            player:AddHearts(1)
+            if character == PlayerType.MAGDALENE_B then
+                player:AddHearts(-1)
+            end
+        end
+    )
+    player:AddGoldenHearts(playerHealth.goldenHearts)
+    player:AddBrokenHearts(playerHealth.brokenHearts)
+    if character == PlayerType.BETHANY then
+        player:SetSoulCharge(playerHealth.soulCharges)
+    elseif character == PlayerType.BETHANY_B then
+        player:SetBloodCharge(playerHealth.bloodCharges)
+    end
+end
 function ____exports.addPlayerHealthType(self, player, healthType, numHearts)
     repeat
         local ____switch3 = healthType
@@ -89,6 +163,11 @@ function ____exports.addPlayerHealthType(self, player, healthType, numHearts)
         end
     until true
 end
+--- Helper function to get an object representing the player's health. You can use this in
+-- combination with the `setPlayerHealth` function to restore the player's health back to a certain
+-- configuration at a later time.
+-- 
+-- This is based on the `REVEL.StoreHealth` function in the Revelations mod.
 function ____exports.getPlayerHealth(self, player)
     local character = player:GetPlayerType()
     local soulHeartTypes = {}
@@ -215,72 +294,22 @@ function ____exports.getPlayerHealthType(self, player, healthType)
         end
     until true
 end
-function ____exports.removeAllPlayerHealth(self, player)
-    local goldenHearts = player:GetGoldenHearts()
-    local eternalHearts = player:GetEternalHearts()
-    local boneHearts = player:GetBoneHearts()
-    local brokenHearts = player:GetBrokenHearts()
-    player:AddGoldenHearts(goldenHearts * -1)
-    player:AddEternalHearts(eternalHearts * -1)
-    player:AddBoneHearts(boneHearts * -1)
-    player:AddBrokenHearts(brokenHearts * -1)
-    player:AddMaxHearts(MAX_PLAYER_HEART_CONTAINERS * -2, true)
-    player:AddSoulHearts(MAX_PLAYER_HEART_CONTAINERS * -2)
-    if isCharacter(nil, player, PlayerType.THE_SOUL) then
-        local forgotten = player:GetSubPlayer()
-        if forgotten ~= nil then
-            local forgottenBoneHearts = forgotten:GetBoneHearts()
-            forgotten:AddBoneHearts(forgottenBoneHearts * -1)
-        end
-    end
-end
-function ____exports.setPlayerHealth(self, player, playerHealth)
-    local character = player:GetPlayerType()
-    local subPlayer = player:GetSubPlayer()
+function ____exports.playerConvertBlackHeartsToSoulHearts(self, player)
+    local playerHealth = ____exports.getPlayerHealth(nil, player)
     ____exports.removeAllPlayerHealth(nil, player)
-    if character == PlayerType.THE_SOUL and subPlayer ~= nil then
-        subPlayer:AddMaxHearts(playerHealth.maxHearts, false)
-    else
-        player:AddMaxHearts(playerHealth.maxHearts, false)
-    end
-    player:AddEternalHearts(playerHealth.eternalHearts)
-    local soulHeartsRemaining = playerHealth.soulHearts
-    __TS__ArrayForEach(
+    playerHealth.soulHeartTypes = __TS__ArrayMap(
         playerHealth.soulHeartTypes,
-        function(____, heartType, i)
-            local isHalf = playerHealth.soulHearts + playerHealth.boneHearts * 2 < (i + 1) * 2
-            local addAmount = 2
-            if isHalf or heartType == HeartSubType.BONE or soulHeartsRemaining < 2 then
-                addAmount = 1
-            end
-            if heartType == HeartSubType.SOUL then
-                player:AddSoulHearts(addAmount)
-                soulHeartsRemaining = soulHeartsRemaining - addAmount
-            elseif heartType == HeartSubType.BLACK then
-                player:AddBlackHearts(addAmount)
-                soulHeartsRemaining = soulHeartsRemaining - addAmount
-            elseif heartType == HeartSubType.BONE then
-                player:AddBoneHearts(addAmount)
-            end
-        end
+        function(____, soulHeartType) return soulHeartType == HeartSubType.BLACK and HeartSubType.SOUL or soulHeartType end
     )
-    player:AddRottenHearts(playerHealth.rottenHearts)
-    ____repeat(
-        nil,
-        playerHealth.hearts,
-        function()
-            player:AddHearts(1)
-            if character == PlayerType.MAGDALENE_B then
-                player:AddHearts(-1)
-            end
-        end
+    ____exports.setPlayerHealth(nil, player, playerHealth)
+end
+function ____exports.playerConvertSoulHeartsToBlackHearts(self, player)
+    local playerHealth = ____exports.getPlayerHealth(nil, player)
+    ____exports.removeAllPlayerHealth(nil, player)
+    playerHealth.soulHeartTypes = __TS__ArrayMap(
+        playerHealth.soulHeartTypes,
+        function(____, soulHeartType) return soulHeartType == HeartSubType.SOUL and HeartSubType.BLACK or soulHeartType end
     )
-    player:AddGoldenHearts(playerHealth.goldenHearts)
-    player:AddBrokenHearts(playerHealth.brokenHearts)
-    if character == PlayerType.BETHANY then
-        player:SetSoulCharge(playerHealth.soulCharges)
-    elseif character == PlayerType.BETHANY_B then
-        player:SetBloodCharge(playerHealth.bloodCharges)
-    end
+    ____exports.setPlayerHealth(nil, player, playerHealth)
 end
 return ____exports

package/functions/playerIndex.d.ts

@@ -1,4 +1,6 @@
 /// <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

package/functions/playerIndex.lua

@@ -10,6 +10,11 @@ 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 = {}
@@ -23,6 +28,33 @@ function ____exports.getAllPlayers(self)
     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
@@ -63,6 +95,14 @@ function getPlayerIndexCollectibleType(self, player, differentiateForgottenAndSo
         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
@@ -81,6 +121,9 @@ function ____exports.getPlayers(self, performCharacterExclusions)
     )
     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)
@@ -96,6 +139,8 @@ function ____exports.getSubPlayerParent(self, subPlayer)
         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
@@ -108,6 +153,8 @@ function ____exports.getPlayerFromIndex(self, playerIndex)
         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)

package/functions/pocketItems.lua

@@ -15,6 +15,14 @@ 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
@@ -49,6 +57,8 @@ function ____exports.getPocketItems(self, player)
     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
@@ -65,6 +75,12 @@ function ____exports.getFirstCardOrPill(self, player)
         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
@@ -75,6 +91,8 @@ function ____exports.hasOpenPocketItemSlot(self, player)
         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]

package/functions/positionVelocity.d.ts

@@ -1,4 +1,7 @@
 /// <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;

package/functions/positionVelocity.lua

@@ -25,6 +25,7 @@ function ____exports.anyEntityCloserThan(self, entities, position, distance)
         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(
@@ -32,6 +33,15 @@ function ____exports.anyPlayerCloserThan(self, position, distance)
         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
@@ -59,6 +69,13 @@ function ____exports.findFreePosition(self, startingPosition, avoidActiveEntitie
     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)
@@ -70,6 +87,13 @@ function ____exports.getEntityPositions(self, entities)
     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)
@@ -81,6 +105,17 @@ function ____exports.getEntityVelocities(self, entities)
     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)
@@ -93,6 +128,17 @@ function ____exports.setEntityPositions(self, entityPositions, entities)
         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)

package/functions/random.d.ts

@@ -1,4 +1,6 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <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.)

package/functions/random.lua

@@ -3,6 +3,11 @@ 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)
@@ -10,6 +15,18 @@ function ____exports.getRandom(self, seedOrRNG)
     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)
@@ -22,6 +39,21 @@ function ____exports.getRandomFloat(self, min, max, seedOrRNG)
     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)

package/functions/revive.d.ts

@@ -1,4 +1,6 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 /**
  * Uses the player's current health and other miscellaneous things to determine if incoming damage
  * will be fatal.

package/functions/revive.lua

@@ -22,6 +22,9 @@ 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
@@ -32,6 +35,8 @@ function ____exports.willReviveFromHeartbreak(self, player)
     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
@@ -41,6 +46,8 @@ function ____exports.willReviveFromSpiritShackles(self, player)
     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()
@@ -84,6 +91,12 @@ function ____exports.isDamageToPlayerFatal(self, player, damageAmount, damageSou
     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()
@@ -93,6 +106,8 @@ function ____exports.willMysteriousPaperRevive(self, player)
     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)

package/functions/rng.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 /// <reference types="typescript-to-lua/language-extensions" />
 import { SerializationType } from "../enums/SerializationType";
 declare type SerializedRNG = LuaTable<string, unknown> & {

package/functions/rng.lua

@@ -16,14 +16,21 @@ 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)
@@ -32,6 +39,7 @@ function ____exports.newRNG(self, seed)
     ____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.")
@@ -41,6 +49,11 @@ 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
@@ -94,6 +107,8 @@ function ____exports.copyRNG(self, rng, serializationType)
         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
@@ -109,6 +124,8 @@ 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
@@ -121,6 +138,8 @@ function ____exports.setAllRNGToSeed(self, object, 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()