isaacscript-common 2.3.1 → 3.1.0

package/functions/player.lua

@@ -49,6 +49,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 +57,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 +77,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 +121,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 +210,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 +223,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 +246,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 +273,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 +291,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 +301,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 +318,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 +332,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 +352,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 +364,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 +377,19 @@ function ____exports.getPlayerCollectibleMap(self, player)
     end
     return collectibleMap
 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 +431,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 +453,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 +480,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 +495,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 +510,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 +534,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 +560,15 @@ 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 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 +576,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 +598,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 +624,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 +633,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 +646,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 +655,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
@@ -576,6 +733,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 +762,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;

package/functions/playerHealth.lua

@@ -89,6 +89,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 = {}
@@ -234,6 +239,11 @@ function ____exports.removeAllPlayerHealth(self, player)
         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()

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)