isaacscript-common 2.3.2 → 3.1.1

package/functions/player.lua

@@ -15,6 +15,7 @@ local ActiveSlot = ____isaac_2Dtypescript_2Ddefinitions.ActiveSlot
 local CacheFlag = ____isaac_2Dtypescript_2Ddefinitions.CacheFlag
 local Challenge = ____isaac_2Dtypescript_2Ddefinitions.Challenge
 local CollectibleType = ____isaac_2Dtypescript_2Ddefinitions.CollectibleType
+local FamiliarVariant = ____isaac_2Dtypescript_2Ddefinitions.FamiliarVariant
 local NullItemID = ____isaac_2Dtypescript_2Ddefinitions.NullItemID
 local PlayerForm = ____isaac_2Dtypescript_2Ddefinitions.PlayerForm
 local PlayerType = ____isaac_2Dtypescript_2Ddefinitions.PlayerType
@@ -49,6 +50,7 @@ local addTearsStat = ____tears.addTearsStat
 local ____utils = require("functions.utils")
 local ensureAllCases = ____utils.ensureAllCases
 local ____repeat = ____utils["repeat"]
+--- Helper function to get an array containing the characters of all of the current players.
 function ____exports.getCharacters(self)
     local players = getPlayers(nil)
     return __TS__ArrayMap(
@@ -56,6 +58,10 @@ function ____exports.getCharacters(self)
         function(____, player) return player:GetPlayerType() end
     )
 end
+--- Returns the maximum heart containers that the provided player can have. Normally, this is 12, but
+-- it can change depending on the character (e.g. Keeper) and other things (e.g. Mother's Kiss).
+-- This function does not account for Broken Hearts; use the `getPlayerAvailableHeartSlots` helper
+-- function for that.
 function ____exports.getPlayerMaxHeartContainers(self, player)
     local character = player:GetPlayerType()
     local characterMaxHeartContainers = getCharacterMaxHeartContainers(nil, character)
@@ -72,12 +78,18 @@ function ____exports.getPlayerMaxHeartContainers(self, player)
     end
     return characterMaxHeartContainers
 end
+--- Helper function to check if a player is a specific character (i.e. `PlayerType`).
+-- 
+-- This function is variadic, meaning that you can supply as many characters as you want to check
+-- for. Returns true if the player is any of the supplied characters.
 function ____exports.isCharacter(self, player, ...)
     local characters = {...}
     local characterSet = __TS__New(Set, characters)
     local character = player:GetPlayerType()
     return characterSet:has(character)
 end
+--- Helper function for detecting when a player is Keeper or Tainted Keeper. Useful for situations
+-- where you want to know if the health is coin hearts, for example.
 function ____exports.isKeeper(self, player)
     local character = player:GetPlayerType()
     return character == PlayerType.KEEPER or character == PlayerType.KEEPER_B
@@ -110,6 +122,19 @@ function ____exports.addCollectibleCostume(self, player, collectibleType)
     end
     player:AddCostume(itemConfigItem, false)
 end
+--- Helper function to add a stat to a player based on the `CacheFlag` provided. Call this function
+-- from the EvaluateCache callback.
+-- 
+-- Note that for `CacheFlag.FIRE_DELAY`, the "amount" argument will be interpreted as the tear stat
+-- to add (and not the amount to mutate `EntityPlayer.MaxFireDelay` by).
+-- 
+-- This function supports the following cache flags:
+-- - CacheFlag.DAMAGE (1 << 0)
+-- - CacheFlag.FIRE_DELAY (1 << 1)
+-- - CacheFlag.SHOT_SPEED (1 << 2)
+-- - CacheFlag.RANGE (1 << 3)
+-- - CacheFlag.SPEED (1 << 4)
+-- - CacheFlag.LUCK (1 << 10)
 function ____exports.addStat(self, player, cacheFlag, amount)
     if not STAT_CACHE_FLAGS_SET:has(cacheFlag) then
         error("You cannot add a stat to a player with the cache flag of: " .. tostring(cacheFlag))
@@ -186,6 +211,10 @@ function ____exports.anyPlayerHasTrinket(self, trinketType)
         function(____, player) return player:HasTrinket(trinketType) end
     )
 end
+--- Helper function to determine if the given character is present.
+-- 
+-- This function is variadic, meaning that you can supply as many characters as you want to check
+-- for. Returns true if any of the characters supplied are present.
 function ____exports.anyPlayerIs(self, ...)
     local matchingCharacters = {...}
     local matchingCharacterSet = __TS__New(Set, matchingCharacters)
@@ -195,10 +224,19 @@ function ____exports.anyPlayerIs(self, ...)
         function(____, character) return matchingCharacterSet:has(character) end
     )
 end
+--- Helper function to determine if a player will destroy a rock/pot/skull if they walk over it.
+-- 
+-- The following situations allow for this to be true:
+-- - the player has Leo (collectible 302)
+-- - the player has Thunder Thighs (collectible 314)
+-- - the player is under the effects of Mega Mush (collectible 625)
+-- - the player has Stompy (transformation 13)
 function ____exports.canPlayerCrushRocks(self, player)
     local effects = player:GetEffects()
     return player:HasCollectible(CollectibleType.LEO) or player:HasCollectible(CollectibleType.THUNDER_THIGHS) or effects:HasCollectibleEffect(CollectibleType.MEGA_MUSH) or player:HasPlayerForm(PlayerForm.STOMPY)
 end
+--- Helper function to find the active slot that the player has the corresponding collectible type
+-- in. Returns undefined if the player does not have the collectible in any active slot.
 function ____exports.getActiveItemSlot(self, player, collectibleType)
     local activeSlots = getEnumValues(nil, ActiveSlot)
     return __TS__ArrayFind(
@@ -209,6 +247,10 @@ function ____exports.getActiveItemSlot(self, player, collectibleType)
         end
     )
 end
+--- Helper function to get how long Azazel's Brimstone laser should be. You can pass either an
+-- `EntityPlayer` object or a tear height stat.
+-- 
+-- The formula for calculating it is: 32 - 2.5 * player.TearHeight
 function ____exports.getAzazelBrimstoneDistance(self, playerOrTearHeight)
     local tearHeight = tonumber(playerOrTearHeight)
     if tearHeight == nil then
@@ -232,6 +274,8 @@ function ____exports.getClosestPlayer(self, position)
     end
     return closestPlayer
 end
+--- Helper function to get an array of temporary effects for a player. This is helpful so that you
+-- don't have to manually create an array from an `EffectsList` object.
 function ____exports.getEffectsList(self, player)
     local effects = player:GetEffects()
     local effectsList = effects:GetEffectsList()
@@ -248,6 +292,8 @@ function ____exports.getEffectsList(self, player)
     end
     return effectArray
 end
+--- Helper function to return the player with the highest ID, according to the `Isaac.GetPlayer`
+-- method.
 function ____exports.getFinalPlayer(self)
     local players = getPlayers(nil)
     local lastPlayer = getLastElement(nil, players)
@@ -256,6 +302,9 @@ function ____exports.getFinalPlayer(self)
     end
     return lastPlayer
 end
+--- Helper function to get the first player with the lowest frame count. Useful to find a freshly
+-- spawned player after using items like Esau Jr. Don't use this function if two or more players
+-- will be spawned on the same frame.
 function ____exports.getNewestPlayer(self)
     local newestPlayer = nil
     local lowestFrame = math.huge
@@ -270,6 +319,9 @@ function ____exports.getNewestPlayer(self)
     end
     return newestPlayer
 end
+--- Returns the number of slots that the player has remaining for new heart containers, accounting
+-- for broken hearts. For example, if the player is Judas and has 1 red heart containers and 2 full
+-- soul hearts and 3 broken hearts, then this function would return 6 (i.e. 12 - 1 - 2 - 3).
 function ____exports.getPlayerAvailableHeartSlots(self, player)
     local maxHeartContainers = ____exports.getPlayerMaxHeartContainers(nil, player)
     local effectiveMaxHearts = player:GetEffectiveMaxHearts()
@@ -281,11 +333,19 @@ function ____exports.getPlayerAvailableHeartSlots(self, player)
     local totalOccupiedHeartSlots = totalHeartContainers + brokenHearts
     return maxHeartContainers - totalOccupiedHeartSlots
 end
+--- Returns the number of black hearts that the player has, excluding any soul hearts. For example,
+-- if the player has one full black heart, one full soul heart, and one half black heart, this
+-- function returns 3.
+-- 
+-- This is different from the `EntityPlayer.GetBlackHearts` method, since that returns a bitmask.
 function ____exports.getPlayerBlackHearts(self, player)
     local blackHeartsBitmask = player:GetBlackHearts()
     local blackHeartBits = countSetBits(nil, blackHeartsBitmask)
     return blackHeartBits * 2
 end
+--- Iterates over all players and checks if any are close enough to the specified position.
+-- 
+-- @returns The first player found when iterating upwards from index 0.
 function ____exports.getPlayerCloserThan(self, position, distance)
     local players = getPlayers(nil)
     return __TS__ArrayFind(
@@ -293,6 +353,10 @@ function ____exports.getPlayerCloserThan(self, position, distance)
         function(____, player) return player.Position:Distance(position) <= distance end
     )
 end
+--- Helper function to return the total amount of collectibles that a player has that match the
+-- collectible type(s) provided.
+-- 
+-- This function is variadic, meaning that you can specify N collectible types.
 function ____exports.getPlayerCollectibleCount(self, player, ...)
     local collectibleTypes = {...}
     local numCollectibles = 0
@@ -301,6 +365,8 @@ function ____exports.getPlayerCollectibleCount(self, player, ...)
     end
     return numCollectibles
 end
+--- Iterates over every item in the game and returns a map containing the number of each item that
+-- the player has.
 function ____exports.getPlayerCollectibleMap(self, player)
     local collectibleSet = getCollectibleSet(nil)
     local collectibleMap = __TS__New(Map)
@@ -312,11 +378,43 @@ function ____exports.getPlayerCollectibleMap(self, player)
     end
     return collectibleMap
 end
+--- Helper function to get the player from a tear, laser, bomb, etc.
+function ____exports.getPlayerFromTear(self, entity)
+    if entity.Parent ~= nil then
+        local player = entity.Parent:ToPlayer()
+        if player ~= nil then
+            return player
+        end
+        local familiar = entity.Parent:ToFamiliar()
+        if familiar ~= nil and familiar.Variant == FamiliarVariant.INCUBUS then
+            return familiar.Player
+        end
+    end
+    if entity.SpawnerEntity ~= nil then
+        local player = entity.SpawnerEntity:ToPlayer()
+        if player ~= nil then
+            return player
+        end
+        local familiar = entity.SpawnerEntity:ToFamiliar()
+        if familiar ~= nil and familiar.Variant == FamiliarVariant.INCUBUS then
+            return familiar.Player
+        end
+    end
+    return nil
+end
+--- Returns the number of red hearts that the player has, excluding any rotten hearts. For example,
+-- if the player has one full black heart, one full soul heart, and one half black heart, this
+-- function returns 3.
+-- 
+-- This is different from the `EntityPlayer.GetHearts` method, since that returns a value that
+-- includes rotten hearts.
 function ____exports.getPlayerHearts(self, player)
     local rottenHearts = player:GetRottenHearts()
     local hearts = player:GetHearts()
     return hearts - rottenHearts * 2
 end
+--- Helper function that returns the type of the rightmost heart. This does not including golden
+-- hearts or broken hearts, since they cannot be damaged directly.
 function ____exports.getPlayerLastHeart(self, player)
     local hearts = player:GetHearts()
     local effectiveMaxHearts = player:GetEffectiveMaxHearts()
@@ -358,10 +456,20 @@ function ____exports.getPlayerLastHeart(self, player)
     end
     return HealthType.RED
 end
+--- Helper function to get the proper name of the player. Use this instead of the
+-- `EntityPlayer.GetName` method because it accounts for Blue Baby, Lazarus II, and Tainted
+-- characters.
 function ____exports.getPlayerName(self, player)
     local character = player:GetPlayerType()
     return ____exports.isModdedPlayer(nil, player) and player:GetName() or getCharacterName(nil, character)
 end
+--- Returns the combined value of all of the player's red hearts, soul/black hearts, and bone hearts,
+-- minus the value of the player's rotten hearts.
+-- 
+-- This is equivalent to the number of hits that the player can currently take, but does not take
+-- into account double damage from champion enemies and/or being on later floors. (For example, on
+-- Womb 1, players who have 1 soul heart remaining would die in 1 hit to anything, even though this
+-- function would report that they have 2 hits remaining.)
 function ____exports.getPlayerNumHitsRemaining(self, player)
     local hearts = player:GetHearts()
     local soulHearts = player:GetSoulHearts()
@@ -370,11 +478,21 @@ function ____exports.getPlayerNumHitsRemaining(self, player)
     local rottenHearts = player:GetRottenHearts()
     return hearts + soulHearts + boneHearts + eternalHearts - rottenHearts
 end
+--- Returns the number of soul hearts that the player has, excluding any black hearts. For example,
+-- if the player has one full black heart, one full soul heart, and one half black heart, this
+-- function returns 2.
+-- 
+-- This is different from the `EntityPlayer.GetSoulHearts` method, since that returns the combined
+-- number of soul hearts and black hearts.
 function ____exports.getPlayerSoulHearts(self, player)
     local soulHearts = player:GetSoulHearts()
     local blackHearts = ____exports.getPlayerBlackHearts(nil, player)
     return soulHearts - blackHearts
 end
+--- Helper function to get all of the players that are a certain character.
+-- 
+-- This function is variadic, meaning that you can supply as many characters as you want to check
+-- for. Returns true if any of the characters supplied are present.
 function ____exports.getPlayersOfType(self, ...)
     local characters = {...}
     local charactersSet = __TS__New(Set, characters)
@@ -387,6 +505,10 @@ function ____exports.getPlayersOfType(self, ...)
         end
     )
 end
+--- Helper function to get only the players that have a certain collectible.
+-- 
+-- This function is variadic, meaning that you can supply as many collectible types as you want to
+-- check for. It only returns the players that have all of the collectibles.
 function ____exports.getPlayersWithCollectible(self, ...)
     local collectibleTypes = {...}
     local players = getPlayers(nil)
@@ -398,6 +520,10 @@ function ____exports.getPlayersWithCollectible(self, ...)
         ) end
     )
 end
+--- Helper function to get only the players that have a certain trinket.
+-- 
+-- This function is variadic, meaning that you can supply as many trinket types as you want to check
+-- for. It only returns the players that have all of the trinkets.
 function ____exports.getPlayersWithTrinket(self, ...)
     local trinketTypes = {...}
     local players = getPlayers(nil)
@@ -409,12 +535,22 @@ function ____exports.getPlayersWithTrinket(self, ...)
         ) end
     )
 end
+--- Helper function to determine how many heart containers that Tainted Magdalene has that will not
+-- be automatically depleted over time. By default, this is 2, but this function will return 4 so
+-- that it is consistent with the `player.GetHearts` and `player.GetMaxHearts` methods.
+-- 
+-- If Tainted Magdalene has Birthright, she will gained an additional non-temporary heart container.
+-- 
+-- This function does not validate whether or not the provided player is Tainted Magdalene; that
+-- should be accomplished before invoking this function.
 function ____exports.getTaintedMagdaleneNonTemporaryMaxHearts(self, player)
     local maxHearts = player:GetMaxHearts()
     local hasBirthright = player:HasCollectible(CollectibleType.BIRTHRIGHT)
     local maxNonTemporaryMaxHearts = hasBirthright and 6 or 4
     return math.min(maxHearts, maxNonTemporaryMaxHearts)
 end
+--- Returns the total number of collectibles amongst all players. For example, if player 1 has 1 Sad
+-- Onion and player 2 has 2 Sad Onions, then this function would return 3.
 function ____exports.getTotalPlayerCollectibles(self, collectibleType)
     local players = getPlayers(nil)
     local numCollectiblesArray = __TS__ArrayMap(
@@ -423,10 +559,16 @@ function ____exports.getTotalPlayerCollectibles(self, collectibleType)
     )
     return sumArray(nil, numCollectiblesArray)
 end
+--- After touching a white fire, a player will turn into The Lost until they clear a room.
 function ____exports.hasLostCurse(self, player)
     local effects = player:GetEffects()
     return effects:HasNullEffect(NullItemID.LOST_CURSE)
 end
+--- Returns whether or not the player can hold an additional active item, beyond what they are
+-- currently carrying. This takes the Schoolbag into account.
+-- 
+-- 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.hasOpenActiveItemSlot(self, player)
     if ____exports.isCharacter(nil, player, PlayerType.THE_SOUL_B) then
         return false
@@ -443,10 +585,25 @@ function ____exports.isActiveSlotEmpty(self, player, activeSlot)
     local activeCollectibleType = player:GetActiveItem(activeSlot)
     return activeCollectibleType == CollectibleType.NULL
 end
+--- Helper function for detecting when a player is Bethany or Tainted Bethany. This is useful if you
+-- need to adjust UI elements to account for Bethany's soul charges or Tainted Bethany's blood
+-- charges.
 function ____exports.isBethany(self, player)
     local character = player:GetPlayerType()
     return character == PlayerType.BETHANY or character == PlayerType.BETHANY_B
 end
+--- Helper function to see if a damage source is from a player. Use this instead of comparing to the
+-- entity directly because it takes familiars into account.
+function ____exports.isDamageFromPlayer(self, damageSource)
+    local player = damageSource:ToPlayer()
+    if player ~= nil then
+        return true
+    end
+    local indirectPlayer = ____exports.getPlayerFromTear(nil, damageSource)
+    return indirectPlayer ~= nil
+end
+--- Helper function for detecting when a player is Eden or Tainted Eden. Useful for situations where
+-- you want to know if the starting stats were randomized, for example.
 function ____exports.isEden(self, player)
     local character = player:GetPlayerType()
     return character == PlayerType.EDEN or character == PlayerType.EDEN_B
@@ -454,14 +611,18 @@ end
 function ____exports.isFirstPlayer(self, player)
     return getPlayerIndexVanilla(nil, player) == 0
 end
+--- Helper function for detecting when a player is Jacob or Esau. This will only match the
+-- non-tainted versions of these characters.
 function ____exports.isJacobOrEsau(self, player)
     local character = player:GetPlayerType()
     return character == PlayerType.JACOB or character == PlayerType.ESAU
 end
+--- Helper function for detecting when a player is The Lost or Tainted Lost.
 function ____exports.isLost(self, player)
     local character = player:GetPlayerType()
     return character == PlayerType.THE_LOST or character == PlayerType.THE_LOST_B
 end
+--- Helper function for detecting if a player is one of the Tainted characters.
 function ____exports.isTainted(self, player)
     local character = player:GetPlayerType()
     local ____isVanillaPlayer_result_0
@@ -472,16 +633,25 @@ function ____exports.isTainted(self, player)
     end
     return ____isVanillaPlayer_result_0
 end
+--- Helper function for detecting when a player is Tainted Lazarus or Dead Tainted Lazarus.
 function ____exports.isTaintedLazarus(self, player)
     local character = player:GetPlayerType()
     return character == PlayerType.LAZARUS_B or character == PlayerType.LAZARUS_2_B
 end
+--- Helper function to add one or more collectibles to a player.
+-- 
+-- This function is variadic, meaning that you can supply as many collectible types as you want to
+-- add.
 function ____exports.playerAddCollectible(self, player, ...)
     local collectibleTypes = {...}
     for ____, collectibleType in ipairs(collectibleTypes) do
         player:AddCollectible(collectibleType)
     end
 end
+--- Helper function to check to see if a player has one or more collectibles.
+-- 
+-- This function is variadic, meaning that you can supply as many collectible types as you want to
+-- check for. Returns true if the player has any of the supplied collectible types.
 function ____exports.playerHasCollectible(self, player, ...)
     local collectibleTypes = {...}
     return __TS__ArraySome(
@@ -489,6 +659,8 @@ function ____exports.playerHasCollectible(self, player, ...)
         function(____, collectibleType) return player:HasCollectible(collectibleType) end
     )
 end
+--- Helper function to remove a collectible costume from a player. Use this helper function to avoid
+-- having to request the collectible from the item config.
 function ____exports.removeCollectibleCostume(self, player, collectibleType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     if itemConfigItem == nil then
@@ -496,6 +668,10 @@ function ____exports.removeCollectibleCostume(self, player, collectibleType)
     end
     player:RemoveCostume(itemConfigItem)
 end
+--- Helper function to remove the Dead Eye multiplier from a player.
+-- 
+-- Note that each time the `EntityPlayer.ClearDeadEyeCharge` method is called, it only has a chance
+-- of working, so this function calls it 100 times to be safe.
 function ____exports.removeDeadEyeMultiplier(self, player)
     ____repeat(
         nil,
@@ -505,6 +681,8 @@ function ____exports.removeDeadEyeMultiplier(self, player)
         end
     )
 end
+--- Helper function to remove a trinket costume from a player. Use this helper function to avoid
+-- having to request the trinket from the item config.
 function ____exports.removeTrinketCostume(self, player, trinketType)
     local itemConfigTrinket = itemConfig:GetTrinket(trinketType)
     if itemConfigTrinket == nil then
@@ -512,6 +690,20 @@ function ____exports.removeTrinketCostume(self, player, trinketType)
     end
     player:RemoveCostume(itemConfigTrinket)
 end
+--- Helper function to set an active collectible to a particular slot. This has different behavior
+-- than calling the `player.AddCollectible` method with the `activeSlot` argument, because this
+-- function will not shift existing items into the Schoolbag and it handles
+-- `ActiveSlot.SLOT_POCKET2`.
+-- 
+-- Note that if an item is set to `ActiveSlot.SLOT_POCKET2`, it will disappear after being used and
+-- will be automatically removed upon entering a new room.
+-- 
+-- @param player The player to give the item to.
+-- @param collectibleType The collectible type of the item to give.
+-- @param activeSlot The slot to set.
+-- @param charge Optional. The argument of charges to set. If not specified, the item will be set
+-- with maximum charges.
+-- @param keepInPools Optional. Whether or not to remove the item from pools. Default is false.
 function ____exports.setActiveItem(self, player, collectibleType, activeSlot, charge, keepInPools)
     if keepInPools == nil then
         keepInPools = false
@@ -527,9 +719,9 @@ function ____exports.setActiveItem(self, player, collectibleType, activeSlot, ch
         itemPool:RemoveCollectible(collectibleType)
     end
     repeat
-        local ____switch113 = activeSlot
-        local ____cond113 = ____switch113 == ActiveSlot.PRIMARY
-        if ____cond113 then
+        local ____switch122 = activeSlot
+        local ____cond122 = ____switch122 == ActiveSlot.PRIMARY
+        if ____cond122 then
             do
                 if primaryCollectibleType ~= CollectibleType.NULL then
                     player:RemoveCollectible(primaryCollectibleType)
@@ -538,8 +730,8 @@ function ____exports.setActiveItem(self, player, collectibleType, activeSlot, ch
                 break
             end
         end
-        ____cond113 = ____cond113 or ____switch113 == ActiveSlot.SECONDARY
-        if ____cond113 then
+        ____cond122 = ____cond122 or ____switch122 == ActiveSlot.SECONDARY
+        if ____cond122 then
             do
                 if primaryCollectibleType ~= CollectibleType.NULL then
                     player:RemoveCollectible(primaryCollectibleType)
@@ -554,16 +746,16 @@ function ____exports.setActiveItem(self, player, collectibleType, activeSlot, ch
                 break
             end
         end
-        ____cond113 = ____cond113 or ____switch113 == ActiveSlot.POCKET
-        if ____cond113 then
+        ____cond122 = ____cond122 or ____switch122 == ActiveSlot.POCKET
+        if ____cond122 then
             do
                 player:SetPocketActiveItem(collectibleType, activeSlot, keepInPools)
                 player:SetActiveCharge(charge, activeSlot)
                 break
             end
         end
-        ____cond113 = ____cond113 or ____switch113 == ActiveSlot.POCKET_SINGLE_USE
-        if ____cond113 then
+        ____cond122 = ____cond122 or ____switch122 == ActiveSlot.POCKET_SINGLE_USE
+        if ____cond122 then
             do
                 player:SetPocketActiveItem(collectibleType, activeSlot, keepInPools)
                 break
@@ -576,6 +768,13 @@ function ____exports.setActiveItem(self, player, collectibleType, activeSlot, ch
         end
     until true
 end
+--- Helper function to blindfold the player by using a hack with the challenge variable.
+-- 
+-- The method used in this function was discovered by im_tem.
+-- 
+-- @param player The player to apply or remove the blindfold state from.
+-- @param enabled Whether or not to apply or remove the blindfold.
+-- @param modifyCostume Optional. Whether to add or remove the blindfold costume. Default is true.
 function ____exports.setBlindfold(self, player, enabled, modifyCostume)
     if modifyCostume == nil then
         modifyCostume = true
@@ -598,6 +797,8 @@ function ____exports.setBlindfold(self, player, enabled, modifyCostume)
         end
     end
 end
+--- Helper function to use an active item without showing an animation, keeping the item, or adding
+-- any costumes.
 function ____exports.useActiveItemTemp(self, player, collectibleType)
     player:UseActiveItem(
         collectibleType,

package/functions/playerDataStructures.lua

@@ -4,33 +4,98 @@ local Set = ____lualib.Set
 local ____exports = {}
 local ____playerIndex = require("functions.playerIndex")
 local getPlayerIndex = ____playerIndex.getPlayerIndex
+--- Helper function to make using maps with an index of `PlayerIndex` easier. Use this instead of the
+-- `Map.set` method if you have a map of this type.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const v = {
+--   run: {
+--     playersSpeedBoost: new Map<PlayerIndex, int>(),
+--   },
+-- };
+-- 
+-- function incrementSpeedBoost(player: EntityPlayer) {
+--   const oldSpeedBoost = mapGetPlayer(v.run.playersSpeedBoost, player);
+--   const newSpeedBoost = oldSpeedBoost + 0.1;
+--   mapSetPlayer(v.run.playersSpeedBoost, player);
+-- }
+-- ```
 function ____exports.mapSetPlayer(self, map, player, value)
     local playerIndex = getPlayerIndex(nil, player)
     map:set(playerIndex, value)
 end
+--- Helper function to make using default maps with an index of `PlayerIndex` easier. Use this
+-- instead of the `DefaultMap.getAndSetDefault` method if you have a default map of this type.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const v = {
+--   run: {
+--     playersSpeedBoost: new DefaultMap<PlayerIndex, int>(0),
+--   },
+-- };
+-- 
+-- function evaluateCacheSpeed(player: EntityPlayer) {
+--   player.MoveSpeed = defaultMapGetPlayer(v.run.playersSpeedBoost, player);
+-- }
+-- ```
 function ____exports.defaultMapGetPlayer(self, map, player, ...)
     local playerIndex = getPlayerIndex(nil, player)
     return map:getAndSetDefault(playerIndex, ...)
 end
+--- Helper function to make using maps with an index of `PlayerIndex` easier. Use this instead of the
+-- `Map.set` method if you have a map of this type.
+-- 
+-- Since `Map` and `DefaultMap` set values in the same way, this function is simply an alias for the
+-- `mapSetPlayer` helper function.
 function ____exports.defaultMapSetPlayer(self, map, player, value)
     ____exports.mapSetPlayer(nil, map, player, value)
 end
+--- Helper function to make using maps with an index of `PlayerIndex` easier. Use this instead of the
+-- `Map.get` method if you have a map of this type.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const v = {
+--   run: {
+--     playersSpeedBoost: new Map<PlayerIndex, int>(),
+--   },
+-- };
+-- 
+-- function incrementSpeedBoost(player: EntityPlayer) {
+--   const oldSpeedBoost = mapGetPlayer(v.run.playersSpeedBoost, player);
+--   const newSpeedBoost = oldSpeedBoost + 0.1;
+--   mapSetPlayer(v.run.playersSpeedBoost, player);
+-- }
+-- ```
 function ____exports.mapGetPlayer(self, map, player)
     local playerIndex = getPlayerIndex(nil, player)
     return map:get(playerIndex)
 end
+--- Helper function to make using maps with an index of `PlayerIndex` easier. Use this instead of the
+-- `Map.has` method if you have a map of this type.
 function ____exports.mapHasPlayer(self, map, player)
     local playerIndex = getPlayerIndex(nil, player)
     return map:has(playerIndex)
 end
+--- Helper function to make using sets with an type of `PlayerIndex` easier. Use this instead of the
+-- `Set.add` method if you have a set of this type.
 function ____exports.setAddPlayer(self, set, player)
     local playerIndex = getPlayerIndex(nil, player)
     return set:add(playerIndex)
 end
+--- Helper function to make using sets with an type of `PlayerIndex` easier. Use this instead of the
+-- `Set.delete` method if you have a set of this type.
 function ____exports.setDeletePlayer(self, set, player)
     local playerIndex = getPlayerIndex(nil, player)
     return set:delete(playerIndex)
 end
+--- Helper function to make using sets with an type of `PlayerIndex` easier. Use this instead of the
+-- `Set.has` method if you have a set of this type.
 function ____exports.setHasPlayer(self, set, player)
     local playerIndex = getPlayerIndex(nil, player)
     return set:has(playerIndex)

package/functions/playerHealth.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 import { HealthType } from "../enums/HealthType";
 import { PlayerHealth } from "../interfaces/PlayerHealth";
 export declare function addPlayerHealthType(player: EntityPlayer, healthType: HealthType, numHearts: int): void;
@@ -11,6 +12,8 @@ export declare function addPlayerHealthType(player: EntityPlayer, healthType: He
  */
 export declare function getPlayerHealth(player: EntityPlayer): PlayerHealth;
 export declare function getPlayerHealthType(player: EntityPlayer, healthType: HealthType): int;
+export declare function playerConvertBlackHeartsToSoulHearts(player: EntityPlayer): void;
+export declare function playerConvertSoulHeartsToBlackHearts(player: EntityPlayer): void;
 export declare function removeAllPlayerHealth(player: EntityPlayer): void;
 /**
  * Helper function to set a player's health to a specific state. You can use this in combination