isaacscript-common 8.4.6 → 8.7.0

package/dist/functions/flying.lua

@@ -34,7 +34,10 @@ local CONDITIONAL_FLYING_COLLECTIBLE_TYPES = {CollectibleType.BIBLE, Collectible
 -- @param pruneConditionalItems Whether or not collectibles that only grant flight conditionally
 -- should be included in the set (like Empty Vessel).
 function ____exports.getFlyingCollectibles(self, pruneConditionalItems)
-    local collectiblesWithFlyingCacheFlag = getCollectiblesForCacheFlag(nil, CacheFlag.FLYING)
+    local collectiblesWithFlyingCacheFlag = copySet(
+        nil,
+        getCollectiblesForCacheFlag(nil, CacheFlag.FLYING)
+    )
     local collectiblesWithAllCacheFlag = getCollectiblesForCacheFlag(nil, CacheFlag.ALL)
     deleteSetsFromSet(nil, collectiblesWithFlyingCacheFlag, collectiblesWithAllCacheFlag)
     if pruneConditionalItems then
@@ -47,7 +50,7 @@ end
 --- Returns a set of all of the trinkets that grant flight. (All trinkets that grant flight do so
 -- conditionally, like Bat Wing.)
 function ____exports.getFlyingTrinkets(self)
-    return copySet(nil, FLYING_TRINKETS)
+    return FLYING_TRINKETS
 end
 function ____exports.hasFlyingTemporaryEffect(self, player)
     local effects = player:GetEffects()

package/dist/functions/input.d.ts

@@ -1,8 +1,8 @@
 import { ButtonAction, Controller, Keyboard } from "isaac-typescript-definitions";
 /** Helper function to get the enum name for the specified `Controller` value. */
 export declare function controllerToString(controller: Controller): string | undefined;
-export declare function getMoveActions(): Set<ButtonAction>;
-export declare function getShootActions(): Set<ButtonAction>;
+export declare function getMoveActions(): ReadonlySet<ButtonAction>;
+export declare function getShootActions(): ReadonlySet<ButtonAction>;
 /** Iterates over all inputs to determine if a particular button is pressed (i.e. held down). */
 export declare function isActionPressedOnAnyInput(buttonAction: ButtonAction): boolean;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../src/functions/input.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,UAAU,EAEV,QAAQ,EACT,MAAM,8BAA8B,CAAC;AAuCtC,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAO7E;AAED,wBAAgB,cAAc,IAAI,GAAG,CAAC,YAAY,CAAC,CAElD;AAED,wBAAgB,eAAe,IAAI,GAAG,CAAC,YAAY,CAAC,CAEnD;AAED,gGAAgG;AAChG,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAK7E;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,YAAY,GACzB,OAAO,CAKT;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,IAAI,EAAE,QAAQ,EAAE,GAAG,OAAO,CAI9D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AAED,wBAAgB,YAAY,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAEhE;AAED,wBAAgB,6BAA6B,IAAI,OAAO,CAIvD;AAED,wBAAgB,+BAA+B,IAAI,OAAO,CAIzD;AAED,wBAAgB,aAAa,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAEjE;AAED,wBAAgB,8BAA8B,IAAI,OAAO,CAIxD;AAED,wBAAgB,gCAAgC,IAAI,OAAO,CAI1D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,OAAO,GACjB,MAAM,GAAG,SAAS,CAQpB"}
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../src/functions/input.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,UAAU,EAEV,QAAQ,EACT,MAAM,8BAA8B,CAAC;AAsCtC,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAO7E;AAED,wBAAgB,cAAc,IAAI,WAAW,CAAC,YAAY,CAAC,CAE1D;AAED,wBAAgB,eAAe,IAAI,WAAW,CAAC,YAAY,CAAC,CAE3D;AAED,gGAAgG;AAChG,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAK7E;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,YAAY,GACzB,OAAO,CAKT;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,IAAI,EAAE,QAAQ,EAAE,GAAG,OAAO,CAI9D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AAED,wBAAgB,YAAY,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAEhE;AAED,wBAAgB,6BAA6B,IAAI,OAAO,CAIvD;AAED,wBAAgB,+BAA+B,IAAI,OAAO,CAIzD;AAED,wBAAgB,aAAa,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAEjE;AAED,wBAAgB,8BAA8B,IAAI,OAAO,CAIxD;AAED,wBAAgB,gCAAgC,IAAI,OAAO,CAI1D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,OAAO,GACjB,MAAM,GAAG,SAAS,CAQpB"}

package/dist/functions/input.lua

@@ -12,8 +12,6 @@ local ____keyboardToString = require("maps.keyboardToString")
 local KEYBOARD_TO_STRING = ____keyboardToString.KEYBOARD_TO_STRING
 local ____enums = require("functions.enums")
 local getEnumValues = ____enums.getEnumValues
-local ____set = require("functions.set")
-local copySet = ____set.copySet
 local ____string = require("functions.string")
 local trimPrefix = ____string.trimPrefix
 local MODIFIER_KEYS = {
@@ -39,10 +37,10 @@ function ____exports.controllerToString(self, controller)
     return trimPrefix(nil, key, "BUTTON_")
 end
 function ____exports.getMoveActions(self)
-    return copySet(nil, MOVEMENT_ACTIONS_SET)
+    return MOVEMENT_ACTIONS_SET
 end
 function ____exports.getShootActions(self)
-    return copySet(nil, SHOOTING_ACTIONS_SET)
+    return SHOOTING_ACTIONS_SET
 end
 --- Iterates over all inputs to determine if a particular button is pressed (i.e. held down).
 function ____exports.isActionPressedOnAnyInput(self, buttonAction)

package/dist/functions/playerHealth.d.ts

@@ -3,6 +3,47 @@
 import { HealthType } from "../enums/HealthType";
 import { PlayerHealth } from "../interfaces/PlayerHealth";
 export declare function addPlayerHealthType(player: EntityPlayer, healthType: HealthType, numHearts: int): void;
+/**
+ * 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.
+ */
+export declare function doesPlayerHaveAllBlackHearts(player: EntityPlayer): boolean;
+/**
+ * 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.
+ */
+export declare function doesPlayerHaveAllSoulHearts(player: EntityPlayer): boolean;
+/**
+ * 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).
+ */
+export declare function getPlayerAvailableHeartSlots(player: EntityPlayer): int;
+/**
+ * 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.
+ */
+export declare function getPlayerBlackHearts(player: EntityPlayer): int;
 /**
  * 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
@@ -12,6 +53,47 @@ export declare function addPlayerHealthType(player: EntityPlayer, healthType: He
  */
 export declare function getPlayerHealth(player: EntityPlayer): PlayerHealth;
 export declare function getPlayerHealthType(player: EntityPlayer, healthType: HealthType): int;
+/**
+ * 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.
+ */
+export declare function getPlayerHearts(player: EntityPlayer): int;
+/**
+ * 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.
+ */
+export declare function getPlayerLastHeart(player: EntityPlayer): HealthType;
+/**
+ * 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.
+ */
+export declare function getPlayerMaxHeartContainers(player: EntityPlayer): int;
+/**
+ * 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.
+ */
+export declare function getPlayerSoulHearts(player: EntityPlayer): int;
+/**
+ * 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.
+ */
+export declare function getTaintedMagdaleneNonTemporaryMaxHearts(player: EntityPlayer): int;
 /** Returns a `PlayerHealth` object with all zeros. */
 export declare function newPlayerHealth(): PlayerHealth;
 export declare function playerConvertBlackHeartsToSoulHearts(player: EntityPlayer): void;
@@ -32,4 +114,15 @@ export declare function removeAllPlayerHealth(player: EntityPlayer): void;
  * Based on the `REVEL.LoadHealth` function in the Revelations mod.
  */
 export declare function setPlayerHealth(player: EntityPlayer, playerHealth: PlayerHealth): void;
+/**
+ * Helper function to see if a certain damage amount would deal "permanent" damage to Tainted
+ * Magdalene.
+ *
+ * Tainted Magdalene has "permanent" health and "temporary" health. When standing still and doing
+ * nothing, all of Tainted Magdalene's temporary health will eventually go away.
+ *
+ * Before using this function, it is expected that you check to see if the player is Tainted
+ * Magdalene first, or else it will give a nonsensical result.
+ */
+export declare function wouldDamageTaintedMagdaleneNonTemporaryHeartContainers(player: EntityPlayer, damageAmount: float): boolean;
 //# sourceMappingURL=playerHealth.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"playerHealth.d.ts","sourceRoot":"","sources":["../../src/functions/playerHealth.ts"],"names":[],"mappings":";;AAOA,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAiB,MAAM,4BAA4B,CAAC;AAYzE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,GAAG,GACb,IAAI,CA+CN;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CA2ElE;AAED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,UAAU,GACrB,GAAG,CAmDL;AAED,sDAAsD;AACtD,wBAAgB,eAAe,IAAI,YAAY,CAc9C;AAED,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,YAAY,GACnB,IAAI,CAQN;AAED,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,YAAY,GACnB,IAAI,CAQN;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAMjE;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAwBhE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,YAAY,GACzB,IAAI,CAsHN"}
+{"version":3,"file":"playerHealth.d.ts","sourceRoot":"","sources":["../../src/functions/playerHealth.ts"],"names":[],"mappings":";;AAQA,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAiB,MAAM,4BAA4B,CAAC;AAQzE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,GAAG,GACb,IAAI,CA+CN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAK1E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAKzE;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,YAAY,GAAG,GAAG,CAYtE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,GAAG,CAK9D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CA2ElE;AAED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,UAAU,GACrB,GAAG,CAmDL;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,GAAG,CAKzD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,CAoDnE;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,YAAY,GAAG,GAAG,CAqCrE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,GAAG,CAK7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,wCAAwC,CACtD,MAAM,EAAE,YAAY,GACnB,GAAG,CAML;AAED,sDAAsD;AACtD,wBAAgB,eAAe,IAAI,YAAY,CAc9C;AAED,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,YAAY,GACnB,IAAI,CAQN;AAED,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,YAAY,GACnB,IAAI,CAQN;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAMjE;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAwBhE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,YAAY,GACzB,IAAI,CAsHN;AAED;;;;;;;;;GASG;AACH,wBAAgB,sDAAsD,CACpE,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,KAAK,GAClB,OAAO,CAyBT"}

package/dist/functions/playerHealth.lua

@@ -7,22 +7,79 @@ local ActiveSlot = ____isaac_2Dtypescript_2Ddefinitions.ActiveSlot
 local CollectibleType = ____isaac_2Dtypescript_2Ddefinitions.CollectibleType
 local HeartSubType = ____isaac_2Dtypescript_2Ddefinitions.HeartSubType
 local PlayerType = ____isaac_2Dtypescript_2Ddefinitions.PlayerType
+local TrinketType = ____isaac_2Dtypescript_2Ddefinitions.TrinketType
 local ____constants = require("core.constants")
 local MAX_PLAYER_HEART_CONTAINERS = ____constants.MAX_PLAYER_HEART_CONTAINERS
 local ____HealthType = require("enums.HealthType")
 local HealthType = ____HealthType.HealthType
+local ____bitwise = require("functions.bitwise")
+local countSetBits = ____bitwise.countSetBits
+local getKBitOfN = ____bitwise.getKBitOfN
+local getNumBitsOfN = ____bitwise.getNumBitsOfN
+local ____characters = require("functions.characters")
+local getCharacterMaxHeartContainers = ____characters.getCharacterMaxHeartContainers
 local ____charge = require("functions.charge")
 local getTotalCharge = ____charge.getTotalCharge
 local ____enums = require("functions.enums")
 local getEnumValues = ____enums.getEnumValues
 local ____players = require("functions.players")
-local getPlayerBlackHearts = ____players.getPlayerBlackHearts
-local getPlayerHearts = ____players.getPlayerHearts
-local getPlayerSoulHearts = ____players.getPlayerSoulHearts
 local isCharacter = ____players.isCharacter
+local isKeeper = ____players.isKeeper
 local setActiveItem = ____players.setActiveItem
 local ____utils = require("functions.utils")
 local ____repeat = ____utils["repeat"]
+--- 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 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
+--- 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 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
 function ____exports.removeAllPlayerHealth(self, player)
     local goldenHearts = player:GetGoldenHearts()
     local eternalHearts = player:GetEternalHearts()
@@ -78,25 +135,25 @@ function ____exports.setPlayerHealth(self, player, playerHealth)
                 addAmount = 1
             end
             repeat
-                local ____switch52 = soulHeartType
-                local ____cond52 = ____switch52 == HeartSubType.SOUL
-                if ____cond52 then
+                local ____switch71 = soulHeartType
+                local ____cond71 = ____switch71 == HeartSubType.SOUL
+                if ____cond71 then
                     do
                         player:AddSoulHearts(addAmount)
                         soulHeartsRemaining = soulHeartsRemaining - addAmount
                         break
                     end
                 end
-                ____cond52 = ____cond52 or ____switch52 == HeartSubType.BLACK
-                if ____cond52 then
+                ____cond71 = ____cond71 or ____switch71 == HeartSubType.BLACK
+                if ____cond71 then
                     do
                         player:AddBlackHearts(addAmount)
                         soulHeartsRemaining = soulHeartsRemaining - addAmount
                         break
                     end
                 end
-                ____cond52 = ____cond52 or ____switch52 == HeartSubType.BONE
-                if ____cond52 then
+                ____cond71 = ____cond71 or ____switch71 == HeartSubType.BONE
+                if ____cond71 then
                     do
                         player:AddBoneHearts(addAmount)
                         break
@@ -214,6 +271,51 @@ function ____exports.addPlayerHealthType(self, player, healthType, numHearts)
         end
     until true
 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
+--- 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
 --- 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.
@@ -222,7 +324,7 @@ end
 function ____exports.getPlayerHealth(self, player)
     local character = player:GetPlayerType()
     local maxHearts = player:GetMaxHearts()
-    local hearts = getPlayerHearts(nil, player)
+    local hearts = ____exports.getPlayerHearts(nil, player)
     local soulHearts = player:GetSoulHearts()
     local boneHearts = player:GetBoneHearts()
     local goldenHearts = player:GetGoldenHearts()
@@ -283,63 +385,120 @@ function ____exports.getPlayerHealth(self, player)
 end
 function ____exports.getPlayerHealthType(self, player, healthType)
     repeat
-        local ____switch24 = healthType
-        local ____cond24 = ____switch24 == HealthType.RED
-        if ____cond24 then
+        local ____switch28 = healthType
+        local ____cond28 = ____switch28 == HealthType.RED
+        if ____cond28 then
             do
-                return getPlayerHearts(nil, player)
+                return ____exports.getPlayerHearts(nil, player)
             end
         end
-        ____cond24 = ____cond24 or ____switch24 == HealthType.SOUL
-        if ____cond24 then
+        ____cond28 = ____cond28 or ____switch28 == HealthType.SOUL
+        if ____cond28 then
             do
-                return getPlayerSoulHearts(nil, player)
+                return ____exports.getPlayerSoulHearts(nil, player)
             end
         end
-        ____cond24 = ____cond24 or ____switch24 == HealthType.ETERNAL
-        if ____cond24 then
+        ____cond28 = ____cond28 or ____switch28 == HealthType.ETERNAL
+        if ____cond28 then
             do
                 return player:GetEternalHearts()
             end
         end
-        ____cond24 = ____cond24 or ____switch24 == HealthType.BLACK
-        if ____cond24 then
+        ____cond28 = ____cond28 or ____switch28 == HealthType.BLACK
+        if ____cond28 then
             do
-                return getPlayerBlackHearts(nil, player)
+                return ____exports.getPlayerBlackHearts(nil, player)
             end
         end
-        ____cond24 = ____cond24 or ____switch24 == HealthType.GOLDEN
-        if ____cond24 then
+        ____cond28 = ____cond28 or ____switch28 == HealthType.GOLDEN
+        if ____cond28 then
             do
                 return player:GetGoldenHearts()
             end
         end
-        ____cond24 = ____cond24 or ____switch24 == HealthType.BONE
-        if ____cond24 then
+        ____cond28 = ____cond28 or ____switch28 == HealthType.BONE
+        if ____cond28 then
             do
                 return player:GetBoneHearts()
             end
         end
-        ____cond24 = ____cond24 or ____switch24 == HealthType.ROTTEN
-        if ____cond24 then
+        ____cond28 = ____cond28 or ____switch28 == HealthType.ROTTEN
+        if ____cond28 then
             do
                 return player:GetRottenHearts()
             end
         end
-        ____cond24 = ____cond24 or ____switch24 == HealthType.BROKEN
-        if ____cond24 then
+        ____cond28 = ____cond28 or ____switch28 == HealthType.BROKEN
+        if ____cond28 then
             do
                 return player:GetBrokenHearts()
             end
         end
-        ____cond24 = ____cond24 or ____switch24 == HealthType.MAX_HEARTS
-        if ____cond24 then
+        ____cond28 = ____cond28 or ____switch28 == HealthType.MAX_HEARTS
+        if ____cond28 then
             do
                 return player:GetMaxHearts()
             end
         end
     until true
 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 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 a `PlayerHealth` object with all zeros.
 function ____exports.newPlayerHealth(self)
     return {
@@ -384,4 +543,28 @@ function ____exports.playerHasHealthLeft(self, player)
     local boneHearts = player:GetBoneHearts()
     return hearts > 0 or soulHearts > 0 or boneHearts > 0
 end
+--- Helper function to see if a certain damage amount would deal "permanent" damage to Tainted
+-- Magdalene.
+-- 
+-- Tainted Magdalene has "permanent" health and "temporary" health. When standing still and doing
+-- nothing, all of Tainted Magdalene's temporary health will eventually go away.
+-- 
+-- Before using this function, it is expected that you check to see if the player is Tainted
+-- Magdalene first, or else it will give a nonsensical result.
+function ____exports.wouldDamageTaintedMagdaleneNonTemporaryHeartContainers(self, player, damageAmount)
+    local soulHearts = player:GetSoulHearts()
+    if soulHearts > 0 then
+        return false
+    end
+    local boneHearts = player:GetBoneHearts()
+    if boneHearts > 0 then
+        return false
+    end
+    local hearts = player:GetHearts()
+    local rottenHearts = player:GetRottenHearts()
+    local effectiveDamageAmount = damageAmount + math.min(rottenHearts, damageAmount)
+    local heartsAfterDamage = hearts - effectiveDamageAmount
+    local nonTemporaryMaxHearts = ____exports.getTaintedMagdaleneNonTemporaryMaxHearts(nil, player)
+    return heartsAfterDamage < nonTemporaryMaxHearts
+end
 return ____exports