isaacscript-common 2.3.2 → 3.1.1

package/functions/pickups.lua

@@ -18,52 +18,62 @@ local removeAllPickups = ____entitySpecific.removeAllPickups
 local spawnPickup = ____entitySpecific.spawnPickup
 local ____pickupVariants = require("functions.pickupVariants")
 local isHeart = ____pickupVariants.isHeart
+--- Helper function to get all of the battery entities in the room.
 function ____exports.getBatteries(self, matchingSubType)
     if matchingSubType == nil then
         matchingSubType = -1
     end
     return getPickups(nil, PickupVariant.LIL_BATTERY, matchingSubType)
 end
+--- Helper function to get all of the card entities in the room.
 function ____exports.getCards(self, matchingSubType)
     if matchingSubType == nil then
         matchingSubType = -1
     end
     return getPickups(nil, PickupVariant.TAROT_CARD, matchingSubType)
 end
+--- Helper function to get the corresponding coin amount from a `CoinSubType`. Returns 1 for modded
+-- sub-types.
 function ____exports.getCoinValue(self, coinSubType)
     local value = COIN_SUBTYPE_TO_VALUE[coinSubType]
     return value == nil and DEFAULT_COIN_VALUE or value
 end
+--- Helper function to get all of the coin pickup entities in the room.
 function ____exports.getCoins(self, matchingSubType)
     if matchingSubType == nil then
         matchingSubType = -1
     end
     return getPickups(nil, PickupVariant.COIN, matchingSubType)
 end
+--- Helper function to get all of the collectible entities in the room.
 function ____exports.getCollectibles(self, matchingSubType)
     if matchingSubType == nil then
         matchingSubType = -1
     end
     return getPickups(nil, PickupVariant.COLLECTIBLE, matchingSubType)
 end
+--- Helper function to get all of the heart pickup entities in the room.
 function ____exports.getHearts(self, matchingSubType)
     if matchingSubType == nil then
         matchingSubType = -1
     end
     return getPickups(nil, PickupVariant.HEART, matchingSubType)
 end
+--- Helper function to get all of the key pickup entities in the room.
 function ____exports.getKeys(self, matchingSubType)
     if matchingSubType == nil then
         matchingSubType = -1
     end
     return getPickups(nil, PickupVariant.KEY, matchingSubType)
 end
+--- Helper function to get all of the pill entities in the room.
 function ____exports.getPills(self, matchingSubType)
     if matchingSubType == nil then
         matchingSubType = -1
     end
     return getPickups(nil, PickupVariant.PILL, matchingSubType)
 end
+--- Helper function to get all of the red heart pickup entities in the room.
 function ____exports.getRedHearts(self)
     local hearts = ____exports.getHearts(nil)
     return __TS__ArrayFilter(
@@ -71,12 +81,14 @@ function ____exports.getRedHearts(self)
         function(____, heart) return RED_HEART_SUB_TYPES_SET:has(heart.SubType) end
     )
 end
+--- Helper function to get all of the sack (i.e. grab bag) entities in the room.
 function ____exports.getSacks(self, matchingSubType)
     if matchingSubType == nil then
         matchingSubType = -1
     end
     return getPickups(nil, PickupVariant.SACK, matchingSubType)
 end
+--- Helper function to get all of the trinket entities in the room.
 function ____exports.getTrinkets(self, matchingSubType)
     if matchingSubType == nil then
         matchingSubType = -1
@@ -89,33 +101,81 @@ end
 function ____exports.isRedHeart(self, pickup)
     return isHeart(nil, pickup) and RED_HEART_SUB_TYPES_SET:has(pickup.SubType)
 end
+--- Helper function to remove all of the batteries in the room.
+-- 
+-- @param batterySubType Optional. If specified, will only remove cards that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of cards.
+-- @returns True if one or more cards were removed, false otherwise.
 function ____exports.removeAllBatteries(self, batterySubType, cap)
     return removeAllPickups(nil, PickupVariant.LIL_BATTERY, batterySubType, cap)
 end
+--- Helper function to remove all of the cards in the room.
+-- 
+-- @param card Optional. If specified, will only remove cards that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of cards.
+-- @returns True if one or more cards were removed, false otherwise.
 function ____exports.removeAllCards(self, card, cap)
     return removeAllPickups(nil, PickupVariant.TAROT_CARD, card, cap)
 end
+--- Helper function to remove all of the coins in the room.
+-- 
+-- @param coinSubType Optional. If specified, will only remove coins that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of coins.
+-- @returns True if one or more coins were removed, false otherwise.
 function ____exports.removeAllCoins(self, coinSubType, cap)
     return removeAllPickups(nil, PickupVariant.COIN, coinSubType, cap)
 end
+--- Helper function to remove all of the collectibles in the room.
+-- 
+-- @param collectibleType Optional. If specified, will only remove collectibles that match this
+-- collectible type.
+-- @param cap Optional. If specified, will only remove the given amount of collectibles.
+-- @returns True if one or more collectibles were removed, false otherwise.
 function ____exports.removeAllCollectibles(self, collectibleType, cap)
     return removeAllPickups(nil, PickupVariant.COLLECTIBLE, collectibleType, cap)
 end
+--- Helper function to remove all of the hearts in the room.
+-- 
+-- @param heartSubType Optional. If specified, will only remove hearts that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of hearts.
+-- @returns True if one or more hearts were removed, false otherwise.
 function ____exports.removeAllHearts(self, heartSubType, cap)
     return removeAllPickups(nil, PickupVariant.HEART, heartSubType, cap)
 end
+--- Helper function to remove all of the keys in the room.
+-- 
+-- @param keySubType Optional. If specified, will only remove keys that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of keys.
+-- @returns True if one or more keys were removed, false otherwise.
 function ____exports.removeAllKeys(self, keySubType, cap)
     return removeAllPickups(nil, PickupVariant.KEY, keySubType, cap)
 end
+--- Helper function to remove all of the pills in the room.
+-- 
+-- @param pillColor Optional. If specified, will only remove pills that match this color.
+-- @param cap Optional. If specified, will only remove the given amount of pills.
+-- @returns True if one or more pills were removed, false otherwise.
 function ____exports.removeAllPills(self, pillColor, cap)
     return removeAllPickups(nil, PickupVariant.PILL, pillColor, cap)
 end
+--- Helper function to remove all of the sacks (i.e. grab bags) in the room.
+-- 
+-- @param sackSubType Optional. If specified, will only remove sacks that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of trinkets.
+-- @returns True if one or more trinkets were removed, false otherwise.
 function ____exports.removeAllSacks(self, sackSubType, cap)
     return removeAllPickups(nil, PickupVariant.TRINKET, sackSubType, cap)
 end
+--- Helper function to remove all of the trinkets in the room.
+-- 
+-- @param trinketType Optional. If specified, will only remove trinkets that match this trinket
+-- type.
+-- @param cap Optional. If specified, will only remove the given amount of trinkets.
+-- @returns True if one or more trinkets were removed, false otherwise.
 function ____exports.removeAllTrinkets(self, trinketType, cap)
     return removeAllPickups(nil, PickupVariant.TRINKET, trinketType, cap)
 end
+--- Helper function to spawn a `EntityType.PICKUP` (5) with variant `PickupVariant.LIL_BATTERY` (90).
 function ____exports.spawnBattery(self, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -152,6 +212,7 @@ function ____exports.spawnBatteryWithSeed(self, subType, position, seed, velocit
         seed
     )
 end
+--- Helper function to spawn a `EntityType.PICKUP` (5) with variant `PickupVariant.TAROT_CARD` (300).
 function ____exports.spawnCard(self, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -188,6 +249,7 @@ function ____exports.spawnCardWithSeed(self, subType, position, seed, velocity,
         seed
     )
 end
+--- Helper function to spawn a `EntityType.PICKUP` (5) with variant `PickupVariant.COIN` (20).
 function ____exports.spawnCoin(self, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -224,6 +286,7 @@ function ____exports.spawnCoinWithSeed(self, subType, position, seed, velocity,
         seed
     )
 end
+--- Helper function to spawn a `EntityType.PICKUP` (5) with variant `PickupVariant.HEART` (10).
 function ____exports.spawnHeart(self, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -260,6 +323,7 @@ function ____exports.spawnHeartWithSeed(self, subType, position, seed, velocity,
         seed
     )
 end
+--- Helper function to spawn a `EntityType.PICKUP` (5) with variant `PickupVariant.KEY` (30).
 function ____exports.spawnKey(self, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -296,6 +360,7 @@ function ____exports.spawnKeyWithSeed(self, subType, position, seed, velocity, s
         seed
     )
 end
+--- Helper function to spawn a `EntityType.PICKUP` (5) with variant `PickupVariant.PILL` (70).
 function ____exports.spawnPill(self, pillColor, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -332,6 +397,7 @@ function ____exports.spawnPillWithSeed(self, subType, position, seed, velocity,
         seed
     )
 end
+--- Helper function to spawn a `EntityType.PICKUP` (5) with variant `PickupVariant.SACK` (69).
 function ____exports.spawnSack(self, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -368,6 +434,7 @@ function ____exports.spawnSackWithSeed(self, subType, position, seed, velocity,
         seed
     )
 end
+--- Helper function to spawn a `EntityType.PICKUP` (5) with variant `PickupVariant.TRINKET` (350).
 function ____exports.spawnTrinket(self, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero

package/functions/pills.lua

@@ -27,38 +27,75 @@ local ____enums = require("functions.enums")
 local getEnumValues = ____enums.getEnumValues
 local ____utils = require("functions.utils")
 local irange = ____utils.irange
+--- Add this to a `PillColor` to get the corresponding giant pill color.
+-- 
+-- Corresponds to the vanilla `PillColor.GIANT_FLAG` value.
+-- 
+-- 1 << 11
 local HORSE_PILL_ADJUSTMENT = 2048
+--- Helper function to get an array with every non-null pill color. This includes all gold colors and
+-- all horse colors.
 function ____exports.getAllPillColors(self)
     local pillColors = getEnumValues(nil, PillColor)
     __TS__ArraySlice(pillColors)
     return pillColors
 end
+--- Helper function to get an array with every valid pill effect. This includes modded pill effects.
 function ____exports.getAllPillEffects(self)
     return irange(nil, FIRST_PILL_EFFECT, LAST_PILL_EFFECT)
 end
+--- Helper function to get the corresponding horse pill color from a normal pill color.
+-- 
+-- For example, passing `PillColor.BLUE_BLUE` would result in 2049, which is the value that
+-- corresponds to the horse pill color for blue/blue.
 function ____exports.getHorsePillColor(self, pillColor)
     return pillColor + HORSE_PILL_ADJUSTMENT
 end
+--- Helper function to get an array with every non-gold horse pill color.
 function ____exports.getHorsePillColors(self)
     return irange(nil, FIRST_HORSE_PILL_COLOR, LAST_HORSE_PILL_COLOR)
 end
+--- Helper function to get an array with every modded pill effect.
+-- 
+-- Returns an empty array if there are no modded pill effects.
 function ____exports.getModdedPillEffects(self)
     if LAST_VANILLA_PILL_EFFECT == LAST_PILL_EFFECT then
         return {}
     end
     return irange(nil, FIRST_MODDED_PILL_EFFECT, LAST_PILL_EFFECT)
 end
+--- Helper function to get the corresponding normal pill color from a horse pill color.
+-- 
+-- For example, passing 2049 would result in `PillColor.BLUE_BLUE`.
+-- 
+-- If called with a non-horse pill color, this function will return back the same color.
 function ____exports.getNormalPillColorFromHorse(self, pillColor)
     local normalPillColor = pillColor - HORSE_PILL_ADJUSTMENT
     return normalPillColor > PillColor.NULL and normalPillColor or pillColor
 end
+--- Helper function to get an array with every non-gold and non-horse pill color.
 function ____exports.getNormalPillColors(self)
     return irange(nil, FIRST_PILL_COLOR, LAST_NORMAL_PILL_COLOR)
 end
+--- Helper function to get a pill effect class from a PillEffect enum value. In this context, the
+-- class is equal to the numerical prefix in the "class" tag in the "pocketitems.xml" file. Use the
+-- `getPillEffectType` helper function to determine whether or not the pill effect is positive,
+-- negative, or neutral.
+-- 
+-- Due to limitations in the API, this function will not work properly for modded pill effects, and
+-- will always return `DEFAULT_PILL_EFFECT_CLASS` in those cases.
 function ____exports.getPillEffectClass(self, pillEffect)
     local pillEffectClass = PILL_EFFECT_CLASSES[pillEffect]
     return pillEffectClass == nil and DEFAULT_PILL_EFFECT_CLASS or pillEffectClass
 end
+--- Helper function to get a pill effect name from a PillEffect enum value.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const pillEffect = PillEffect.BAD_GAS;
+-- const pillEffectName = getPillEffectName(pillEffect); // trinketName is "Bad Gas"
+-- ```
 function ____exports.getPillEffectName(self, pillEffect)
     local pillEffectName = PILL_EFFECT_NAMES[pillEffect]
     if pillEffectName ~= nil and pillEffectName ~= DEFAULT_PILL_EFFECT_NAME then
@@ -70,10 +107,18 @@ function ____exports.getPillEffectName(self, pillEffect)
     end
     return DEFAULT_PILL_EFFECT_NAME
 end
+--- Helper function to get a pill effect type from a PillEffect enum value. In this context, the type
+-- is equal to positive, negative, or neutral. This is derived from the suffix of the the "class"
+-- tag in the "pocketitems.xml" file. Use the `getPillEffectClass` helper function to determine the
+-- "power" of the pill.
+-- 
+-- Due to limitations in the API, this function will not work properly for modded pill effects, and
+-- will always return `DEFAULT_PILL_EFFECT_TYPE` in those cases.
 function ____exports.getPillEffectType(self, pillEffect)
     local pillEffectClass = PILL_EFFECT_TYPES[pillEffect]
     return pillEffectClass == nil and DEFAULT_PILL_EFFECT_TYPE or pillEffectClass
 end
+--- Helper function to get an array with every vanilla pill effect.
 function ____exports.getVanillaPillEffects(self)
     return irange(nil, FIRST_PILL_EFFECT, LAST_VANILLA_PILL_EFFECT)
 end

package/functions/player.d.ts

@@ -100,6 +100,8 @@ export declare function getPlayerCollectibleCount(player: EntityPlayer, ...colle
  * the player has.
  */
 export declare function getPlayerCollectibleMap(player: EntityPlayer): Map<CollectibleType, int>;
+/** Helper function to get the player from a tear, laser, bomb, etc. */
+export declare function getPlayerFromTear(entity: Entity): EntityPlayer | undefined;
 /**
  * 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
@@ -207,6 +209,11 @@ export declare function isBethany(player: EntityPlayer): boolean;
  * for. Returns true if the player is any of the supplied characters.
  */
 export declare function isCharacter(player: EntityPlayer, ...characters: PlayerType[]): boolean;
+/**
+ * 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.
+ */
+export declare function isDamageFromPlayer(damageSource: Entity): boolean;
 /**
  * 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.