isaacscript-common 6.6.1-dev.1 → 6.6.1-dev.5

package/dist/functions/player.lua

@@ -0,0 +1,831 @@
+local ____lualib = require("lualib_bundle")
+local Set = ____lualib.Set
+local __TS__New = ____lualib.__TS__New
+local __TS__ArraySome = ____lualib.__TS__ArraySome
+local __TS__ArrayFind = ____lualib.__TS__ArrayFind
+local __TS__ArrayMap = ____lualib.__TS__ArrayMap
+local Map = ____lualib.Map
+local __TS__ArrayFilter = ____lualib.__TS__ArrayFilter
+local __TS__ArrayEvery = ____lualib.__TS__ArrayEvery
+local ____exports = {}
+local isTaintedModded
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+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
+local TrinketType = ____isaac_2Dtypescript_2Ddefinitions.TrinketType
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+local itemConfig = ____cachedClasses.itemConfig
+local ____HealthType = require("enums.HealthType")
+local HealthType = ____HealthType.HealthType
+local ____array = require("functions.array")
+local getLastElement = ____array.getLastElement
+local sumArray = ____array.sumArray
+local ____bitwise = require("functions.bitwise")
+local countSetBits = ____bitwise.countSetBits
+local getKBitOfN = ____bitwise.getKBitOfN
+local getNumBitsOfN = ____bitwise.getNumBitsOfN
+local ____character = require("functions.character")
+local getCharacterMaxHeartContainers = ____character.getCharacterMaxHeartContainers
+local getCharacterName = ____character.getCharacterName
+local isVanillaCharacter = ____character.isVanillaCharacter
+local ____collectibles = require("functions.collectibles")
+local getCollectibleMaxCharges = ____collectibles.getCollectibleMaxCharges
+local ____collectibleSet = require("functions.collectibleSet")
+local getCollectibleArray = ____collectibleSet.getCollectibleArray
+local ____enums = require("functions.enums")
+local getEnumValues = ____enums.getEnumValues
+local ____playerIndex = require("functions.playerIndex")
+local getPlayerIndexVanilla = ____playerIndex.getPlayerIndexVanilla
+local getPlayers = ____playerIndex.getPlayers
+local ____tears = require("functions.tears")
+local addTearsStat = ____tears.addTearsStat
+local ____utils = require("functions.utils")
+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(
+        players,
+        function(____, player) return player:GetPlayerType() end
+    )
+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
+--- 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)
+    if character == PlayerType.MAGDALENE and player:HasCollectible(CollectibleType.BIRTHRIGHT) then
+        local extraMaxHeartContainersFromBirthright = 6
+        return characterMaxHeartContainers + extraMaxHeartContainersFromBirthright
+    end
+    if ____exports.isKeeper(nil, player) then
+        local numMothersKisses = player:GetTrinketMultiplier(TrinketType.MOTHERS_KISS)
+        local hasGreedsGullet = player:HasCollectible(CollectibleType.GREEDS_GULLET)
+        local coins = player:GetNumCoins()
+        local greedsGulletCoinContainers = hasGreedsGullet and math.floor(coins / 25) or 0
+        return characterMaxHeartContainers + numMothersKisses + greedsGulletCoinContainers
+    end
+    return characterMaxHeartContainers
+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 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
+end
+function ____exports.isModdedPlayer(self, player)
+    return not ____exports.isVanillaPlayer(nil, player)
+end
+function isTaintedModded(self, player)
+    local character = player:GetPlayerType()
+    local name = player:GetName()
+    local taintedCharacter = Isaac.GetPlayerTypeByName(name, true)
+    return character == taintedCharacter
+end
+function ____exports.isVanillaPlayer(self, player)
+    local character = player:GetPlayerType()
+    return isVanillaCharacter(nil, character)
+end
+local STAT_CACHE_FLAGS_SET = __TS__New(Set, {
+    CacheFlag.DAMAGE,
+    CacheFlag.FIRE_DELAY,
+    CacheFlag.SHOT_SPEED,
+    CacheFlag.RANGE,
+    CacheFlag.SPEED,
+    CacheFlag.LUCK
+})
+function ____exports.addCollectibleCostume(self, player, collectibleType)
+    local itemConfigItem = itemConfig:GetCollectible(collectibleType)
+    if itemConfigItem == nil then
+        return
+    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))
+    end
+    repeat
+        local ____switch6 = cacheFlag
+        local ____cond6 = ____switch6 == CacheFlag.DAMAGE
+        if ____cond6 then
+            do
+                player.Damage = player.Damage + amount
+                break
+            end
+        end
+        ____cond6 = ____cond6 or ____switch6 == CacheFlag.FIRE_DELAY
+        if ____cond6 then
+            do
+                addTearsStat(nil, player, amount)
+                break
+            end
+        end
+        ____cond6 = ____cond6 or ____switch6 == CacheFlag.SHOT_SPEED
+        if ____cond6 then
+            do
+                player.ShotSpeed = player.ShotSpeed + amount
+                break
+            end
+        end
+        ____cond6 = ____cond6 or ____switch6 == CacheFlag.RANGE
+        if ____cond6 then
+            do
+                player.TearHeight = player.TearHeight + amount
+                break
+            end
+        end
+        ____cond6 = ____cond6 or ____switch6 == CacheFlag.SPEED
+        if ____cond6 then
+            do
+                player.MoveSpeed = player.MoveSpeed + amount
+                break
+            end
+        end
+        ____cond6 = ____cond6 or ____switch6 == CacheFlag.LUCK
+        if ____cond6 then
+            do
+                player.Luck = player.Luck + amount
+                break
+            end
+        end
+    until true
+end
+function ____exports.addTrinketCostume(self, player, trinketType)
+    local itemConfigTrinket = itemConfig:GetTrinket(trinketType)
+    if itemConfigTrinket == nil then
+        return
+    end
+    player:AddCostume(itemConfigTrinket, false)
+end
+function ____exports.anyPlayerHasCollectible(self, collectibleType)
+    local players = getPlayers(nil)
+    return __TS__ArraySome(
+        players,
+        function(____, player) return player:HasCollectible(collectibleType) end
+    )
+end
+function ____exports.anyPlayerHasTrinket(self, trinketType)
+    local players = getPlayers(nil)
+    return __TS__ArraySome(
+        players,
+        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)
+    local characters = ____exports.getCharacters(nil)
+    return __TS__ArraySome(
+        characters,
+        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
+--- Returns whether or not all of the player's soul-heart-type hearts are black hearts.
+-- 
+-- Note that this function does not consider red heart containers.
+-- 
+-- For example:
+-- 
+-- - If the player has one black heart, this function would return true.
+-- - If the player has one soul heart and two black hearts, this function would return false.
+-- - If the player has no black hearts, this function will return false.
+-- - If the player has one red heart container and three black hearts, this function would return
+--   true.
+function ____exports.doesPlayerHaveAllBlackHearts(self, player)
+    local soulHearts = ____exports.getPlayerSoulHearts(nil, player)
+    local blackHearts = ____exports.getPlayerBlackHearts(nil, player)
+    return blackHearts > 0 and soulHearts == 0
+end
+--- Returns whether or not all of the player's soul-heart-type hearts are soul hearts.
+-- 
+-- Note that this function does not consider red heart containers.
+-- 
+-- For example:
+-- 
+-- - If the player has two soul hearts and one black heart, this function would return false.
+-- - If the player has no soul hearts, this function will return false.
+-- - If the player has one red heart container and three soul hearts, this function would return
+--   true.
+function ____exports.doesPlayerHaveAllSoulHearts(self, player)
+    local soulHearts = ____exports.getPlayerSoulHearts(nil, player)
+    local blackHearts = ____exports.getPlayerBlackHearts(nil, player)
+    return soulHearts > 0 and blackHearts == 0
+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(
+        activeSlots,
+        function(____, activeSlot)
+            local activeItem = player:GetActiveItem(activeSlot)
+            return activeItem == 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
+        local player = playerOrTearHeight
+        tearHeight = player.TearHeight
+    end
+    return 32 - 2.5 * tearHeight
+end
+function ____exports.getClosestPlayer(self, position)
+    local closestPlayer = nil
+    local closestDistance = math.huge
+    for ____, player in ipairs(getPlayers(nil)) do
+        local distance = position:Distance(player.Position)
+        if distance < closestDistance then
+            closestPlayer = player
+            closestDistance = distance
+        end
+    end
+    if closestPlayer == nil then
+        error("Failed to find the closest player.")
+    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()
+    local effectArray = {}
+    do
+        local i = 0
+        while i < effectsList.Size do
+            local effect = effectsList:Get(i)
+            if effect ~= nil then
+                effectArray[#effectArray + 1] = effect
+            end
+            i = i + 1
+        end
+    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)
+    if lastPlayer == nil then
+        error("Failed to get the final player since there were 0 players.")
+    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
+    for ____, player in ipairs(getPlayers(nil)) do
+        if player.FrameCount < lowestFrame then
+            newestPlayer = player
+            lowestFrame = player.FrameCount
+        end
+    end
+    if newestPlayer == nil then
+        error("Failed to find the newest player.")
+    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()
+    local normalAndBoneHeartContainers = effectiveMaxHearts / 2
+    local soulHearts = player:GetSoulHearts()
+    local soulHeartContainers = math.ceil(soulHearts / 2)
+    local totalHeartContainers = normalAndBoneHeartContainers + soulHeartContainers
+    local brokenHearts = player:GetBrokenHearts()
+    local totalOccupiedHeartSlots = totalHeartContainers + brokenHearts
+    return maxHeartContainers - totalOccupiedHeartSlots
+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(
+        players,
+        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
+    for ____, collectibleType in ipairs(collectibleTypes) do
+        numCollectibles = numCollectibles + player:GetCollectibleNum(collectibleType, true)
+    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 collectibleArray = getCollectibleArray(nil)
+    local collectibleMap = __TS__New(Map)
+    for ____, collectibleType in ipairs(collectibleArray) do
+        local collectibleNum = player:GetCollectibleNum(collectibleType, true)
+        if collectibleNum > 0 then
+            collectibleMap:set(collectibleType, collectibleNum)
+        end
+    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()
+    local soulHearts = player:GetSoulHearts()
+    local blackHearts = player:GetBlackHearts()
+    local eternalHearts = player:GetEternalHearts()
+    local boneHearts = player:GetBoneHearts()
+    local rottenHearts = player:GetRottenHearts()
+    local soulHeartSlots = soulHearts / 2
+    local lastHeartIndex = boneHearts + soulHeartSlots - 1
+    local isLastHeartBone = player:IsBoneHeart(lastHeartIndex)
+    if isLastHeartBone then
+        local isLastContainerEmpty = hearts <= effectiveMaxHearts - 2
+        if isLastContainerEmpty then
+            return HealthType.BONE
+        end
+        if rottenHearts > 0 then
+            return HealthType.ROTTEN
+        end
+        if eternalHearts > 0 then
+            return HealthType.ETERNAL
+        end
+        return HealthType.RED
+    end
+    if soulHearts > 0 then
+        local numBits = getNumBitsOfN(nil, blackHearts)
+        local finalBit = getKBitOfN(nil, numBits - 1, blackHearts)
+        local isBlack = finalBit == 1
+        if isBlack then
+            return HealthType.BLACK
+        end
+        return HealthType.SOUL
+    end
+    if eternalHearts > 0 then
+        return HealthType.ETERNAL
+    end
+    if rottenHearts > 0 then
+        return HealthType.ROTTEN
+    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()
+    local boneHearts = player:GetBoneHearts()
+    local eternalHearts = player:GetEternalHearts()
+    local rottenHearts = player:GetRottenHearts()
+    return hearts + soulHearts + boneHearts + eternalHearts - rottenHearts
+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)
+    local players = getPlayers(nil)
+    return __TS__ArrayFilter(
+        players,
+        function(____, player)
+            local character = player:GetPlayerType()
+            return charactersSet:has(character)
+        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)
+    return __TS__ArrayFilter(
+        players,
+        function(____, player) return __TS__ArrayEvery(
+            collectibleTypes,
+            function(____, collectibleType) return player:HasCollectible(collectibleType) end
+        ) 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)
+    return __TS__ArrayFilter(
+        players,
+        function(____, player) return __TS__ArrayEvery(
+            trinketTypes,
+            function(____, trinketType) return player:HasTrinket(trinketType) end
+        ) 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(
+        players,
+        function(____, player) return player:GetCollectibleNum(collectibleType) end
+    )
+    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
+    end
+    local activeItemPrimary = player:GetActiveItem(ActiveSlot.PRIMARY)
+    local activeItemSecondary = player:GetActiveItem(ActiveSlot.SECONDARY)
+    local hasSchoolbag = player:HasCollectible(CollectibleType.SCHOOLBAG)
+    if hasSchoolbag then
+        return activeItemPrimary == CollectibleType.NULL or activeItemSecondary == CollectibleType.NULL
+    end
+    return activeItemPrimary == CollectibleType.NULL
+end
+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
+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
+    if ____exports.isVanillaPlayer(nil, player) then
+        ____isVanillaPlayer_result_0 = character >= PlayerType.ISAAC_B
+    else
+        ____isVanillaPlayer_result_0 = isTaintedModded(nil, 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(
+        collectibleTypes,
+        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
+        return
+    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,
+        100,
+        function()
+            player:ClearDeadEyeCharge()
+        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
+        return
+    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
+    end
+    local itemPool = game:GetItemPool()
+    local primaryCollectibleType = player:GetActiveItem(ActiveSlot.PRIMARY)
+    local primaryCharge = player:GetActiveCharge(ActiveSlot.PRIMARY)
+    local secondaryCollectibleType = player:GetActiveItem(ActiveSlot.SECONDARY)
+    if charge == nil then
+        charge = getCollectibleMaxCharges(nil, collectibleType)
+    end
+    if not keepInPools then
+        itemPool:RemoveCollectible(collectibleType)
+    end
+    repeat
+        local ____switch123 = activeSlot
+        local ____cond123 = ____switch123 == ActiveSlot.PRIMARY
+        if ____cond123 then
+            do
+                if primaryCollectibleType ~= CollectibleType.NULL then
+                    player:RemoveCollectible(primaryCollectibleType)
+                end
+                player:AddCollectible(collectibleType, charge, false)
+                break
+            end
+        end
+        ____cond123 = ____cond123 or ____switch123 == ActiveSlot.SECONDARY
+        if ____cond123 then
+            do
+                if primaryCollectibleType ~= CollectibleType.NULL then
+                    player:RemoveCollectible(primaryCollectibleType)
+                end
+                if secondaryCollectibleType ~= CollectibleType.NULL then
+                    player:RemoveCollectible(secondaryCollectibleType)
+                end
+                player:AddCollectible(secondaryCollectibleType, charge, false)
+                if primaryCollectibleType ~= CollectibleType.NULL then
+                    player:AddCollectible(primaryCollectibleType, primaryCharge, false)
+                end
+                break
+            end
+        end
+        ____cond123 = ____cond123 or ____switch123 == ActiveSlot.POCKET
+        if ____cond123 then
+            do
+                player:SetPocketActiveItem(collectibleType, activeSlot, keepInPools)
+                player:SetActiveCharge(charge, activeSlot)
+                break
+            end
+        end
+        ____cond123 = ____cond123 or ____switch123 == ActiveSlot.POCKET_SINGLE_USE
+        if ____cond123 then
+            do
+                player:SetPocketActiveItem(collectibleType, activeSlot, keepInPools)
+                break
+            end
+        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
+    end
+    local character = player:GetPlayerType()
+    local challenge = Isaac.GetChallenge()
+    if enabled then
+        game.Challenge = Challenge.SOLAR_SYSTEM
+        player:ChangePlayerType(character)
+        game.Challenge = challenge
+        if not modifyCostume then
+            player:TryRemoveNullCostume(NullItemID.BLINDFOLD)
+        end
+    else
+        game.Challenge = Challenge.NULL
+        player:ChangePlayerType(character)
+        game.Challenge = challenge
+        if modifyCostume then
+            player:TryRemoveNullCostume(NullItemID.BLINDFOLD)
+        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,
+        false,
+        false,
+        true,
+        false,
+        -1
+    )
+end
+return ____exports