isaacscript-common 1.2.40 → 1.2.41

package/dist/functions/familiars.d.ts

@@ -1,4 +1,29 @@
 /// <reference types="isaac-typescript-definitions" />
+/**
+ * Helper function to add and remove familiars based on a target amount that you specify. Use this
+ * instead of the `EntityPlayer.CheckFamiliar` method so that the InitSeed of the spawned familiar
+ * will be set properly. Note that when using this function, you need to automatically account for
+ * Box of Friends.
+ *
+ * This function is meant to be called in the EvaluateCache callback (when the cache flag is equal
+ * to `CacheFlag.CACHE_FAMILIARS`).
+ *
+ * Note that this function is only meant to be used in special circumstances. For general purpose
+ * usage, please use the `checkFamiliarFromCollectibles` helper function instead.
+ *
+ * @param player The player that owns the familiars.
+ * @param collectibleType The collectible type of the collectible associated with this familiar.
+ * @param numTargetFamiliars The number of familiars that should exist. This function will add or
+ * remove familiars until it matches the target count.
+ * @param familiarVariant The variant of the familiar to spawn or remove.
+ * @param familiarSubType Optional. The sub-type of the familiar to spawn or remove. If not
+ * specified, it will search for existing familiars of all sub-types, and spawn new familiars with a
+ * sub-type of 0.
+ * @returns The amount of familiars that were added or removed. For example, the player has 0
+ * collectibles and there were 2 familiars, this function would remove the 2 familiars and return
+ * -2.
+ */
+export declare function checkFamiliar(player: EntityPlayer, collectibleType: int, numTargetFamiliars: int, familiarVariant: int, familiarSubType?: int): int;
 /**
  * Helper function to add and remove familiars based on the amount of associated collectibles that a
  * player has. Use this instead of the `EntityPlayer.CheckFamiliar` method so that the InitSeed of
@@ -7,15 +32,21 @@
  * This function is meant to be called in the EvaluateCache callback (when the cache flag is equal
  * to `CacheFlag.CACHE_FAMILIARS`).
  *
- * @param player The player that has the collectibles for this familiar.
+ * Use this function when the amount of familiars should be equal to the amount of associated
+ * collectibles that the player has (plus any extras from having used Box of Friends). If you
+ * instead need to have a custom amount of familiars, use the `checkFamiliars` function instead.
+ *
+ * @param player The player that owns the familiars and collectibles.
  * @param collectibleType The collectible type of the collectible associated with this familiar.
  * @param familiarVariant The variant of the familiar to spawn or remove.
- * @param familiarSubType Optional. The sub-type of the familiar to spawn or remove. 0 by default.
+ * @param familiarSubType Optional. The sub-type of the familiar to spawn or remove. If not
+ * specified, it will search for existing familiars of all sub-types, and spawn new familiars with a
+ * sub-type of 0.
  * @returns The amount of familiars that were added or removed. For example, the player has 0
  * collectibles and there were 2 familiars, this function would remove the 2 familiars and return
  * -2.
  */
-export declare function checkFamiliar(player: EntityPlayer, collectibleType: int, familiarVariant: int, familiarSubType?: int): int;
+export declare function checkFamiliarFromCollectibles(player: EntityPlayer, collectibleType: int, familiarVariant: int, familiarSubType?: int): int;
 /**
  * Helper function to get all of the familiars in the room.
  *

package/dist/functions/familiars.lua

@@ -25,7 +25,7 @@ function ____exports.getFamiliars(self, matchingVariant, matchingSubType)
     end
     return familiars
 end
-function ____exports.checkFamiliar(self, player, collectibleType, familiarVariant, familiarSubType)
+function ____exports.checkFamiliar(self, player, collectibleType, numTargetFamiliars, familiarVariant, familiarSubType)
     local game = Game()
     local familiarSubTypeToSearchFor = familiarSubType == nil and -1 or familiarSubType
     local playerPtrHash = GetPtrHash(player)
@@ -34,15 +34,11 @@ function ____exports.checkFamiliar(self, player, collectibleType, familiarVarian
         familiars,
         function(____, familiar) return GetPtrHash(familiar.Player) == playerPtrHash end
     )
-    local numCollectibles = player:GetCollectibleNum(collectibleType)
-    local effects = player:GetEffects()
-    local numBoxOfFriendsUses = effects:GetCollectibleEffectNum(CollectibleType.COLLECTIBLE_BOX_OF_FRIENDS)
-    local numFamiliarsThatShouldExist = numCollectibles * (numBoxOfFriendsUses + 1)
-    if #familiarsForThisPlayer == numFamiliarsThatShouldExist then
+    if #familiarsForThisPlayer == numTargetFamiliars then
         return 0
     end
-    if #familiarsForThisPlayer > numFamiliarsThatShouldExist then
-        local numFamiliarsToRemove = #familiarsForThisPlayer - numFamiliarsThatShouldExist
+    if #familiarsForThisPlayer > numTargetFamiliars then
+        local numFamiliarsToRemove = #familiarsForThisPlayer - numTargetFamiliars
         do
             local i = 0
             while i < numFamiliarsToRemove do
@@ -53,7 +49,7 @@ function ____exports.checkFamiliar(self, player, collectibleType, familiarVarian
         end
         return numFamiliarsToRemove * -1
     end
-    local numFamiliarsToSpawn = numFamiliarsThatShouldExist - #familiarsForThisPlayer
+    local numFamiliarsToSpawn = numTargetFamiliars - #familiarsForThisPlayer
     local collectibleRNG = player:GetCollectibleRNG(collectibleType)
     local familiarSubTypeToUse = familiarSubType == nil and 0 or familiarSubType
     do
@@ -77,6 +73,20 @@ function ____exports.checkFamiliar(self, player, collectibleType, familiarVarian
     end
     return numFamiliarsToSpawn
 end
+function ____exports.checkFamiliarFromCollectibles(self, player, collectibleType, familiarVariant, familiarSubType)
+    local numCollectibles = player:GetCollectibleNum(collectibleType)
+    local effects = player:GetEffects()
+    local numBoxOfFriendsUses = effects:GetCollectibleEffectNum(CollectibleType.COLLECTIBLE_BOX_OF_FRIENDS)
+    local numTargetFamiliars = numCollectibles * (numBoxOfFriendsUses + 1)
+    return ____exports.checkFamiliar(
+        nil,
+        player,
+        collectibleType,
+        numTargetFamiliars,
+        familiarVariant,
+        familiarSubType
+    )
+end
 function ____exports.isFamiliarThatShootsPlayerTears(self, familiar)
     return FAMILIARS_THAT_SHOOT_PLAYER_TEARS:has(familiar.Type)
 end

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "1.2.40",
+  "version": "1.2.41",
   "description": "Helper functions for IsaacScript mods",
   "keywords": [
     "isaac",