isaacscript-common 3.4.2 → 3.5.0

package/functions/player.d.ts

@@ -37,6 +37,33 @@ export declare function anyPlayerIs(...matchingCharacters: PlayerType[]): boolea
  * - the player has Stompy (transformation 13)
  */
 export declare function canPlayerCrushRocks(player: EntityPlayer): boolean;
+/**
+ * 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;
 /**
  * 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.

package/functions/player.lua

@@ -58,6 +58,16 @@ function ____exports.getCharacters(self)
         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
@@ -78,6 +88,17 @@ function ____exports.getPlayerMaxHeartContainers(self, player)
     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
@@ -235,6 +256,37 @@ 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)
@@ -333,16 +385,6 @@ 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.
@@ -478,17 +520,6 @@ 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
@@ -719,9 +750,9 @@ function ____exports.setActiveItem(self, player, collectibleType, activeSlot, ch
         itemPool:RemoveCollectible(collectibleType)
     end
     repeat
-        local ____switch122 = activeSlot
-        local ____cond122 = ____switch122 == ActiveSlot.PRIMARY
-        if ____cond122 then
+        local ____switch124 = activeSlot
+        local ____cond124 = ____switch124 == ActiveSlot.PRIMARY
+        if ____cond124 then
             do
                 if primaryCollectibleType ~= CollectibleType.NULL then
                     player:RemoveCollectible(primaryCollectibleType)
@@ -730,8 +761,8 @@ function ____exports.setActiveItem(self, player, collectibleType, activeSlot, ch
                 break
             end
         end
-        ____cond122 = ____cond122 or ____switch122 == ActiveSlot.SECONDARY
-        if ____cond122 then
+        ____cond124 = ____cond124 or ____switch124 == ActiveSlot.SECONDARY
+        if ____cond124 then
             do
                 if primaryCollectibleType ~= CollectibleType.NULL then
                     player:RemoveCollectible(primaryCollectibleType)
@@ -746,16 +777,16 @@ function ____exports.setActiveItem(self, player, collectibleType, activeSlot, ch
                 break
             end
         end
-        ____cond122 = ____cond122 or ____switch122 == ActiveSlot.POCKET
-        if ____cond122 then
+        ____cond124 = ____cond124 or ____switch124 == ActiveSlot.POCKET
+        if ____cond124 then
             do
                 player:SetPocketActiveItem(collectibleType, activeSlot, keepInPools)
                 player:SetActiveCharge(charge, activeSlot)
                 break
             end
         end
-        ____cond122 = ____cond122 or ____switch122 == ActiveSlot.POCKET_SINGLE_USE
-        if ____cond122 then
+        ____cond124 = ____cond124 or ____switch124 == ActiveSlot.POCKET_SINGLE_USE
+        if ____cond124 then
             do
                 player:SetPocketActiveItem(collectibleType, activeSlot, keepInPools)
                 break

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "3.4.2",
+  "version": "3.5.0",
   "description": "Helper functions and features for IsaacScript mods.",
   "keywords": [
     "isaac",