isaacscript-common 2.3.0 → 3.0.0

package/functions/pills.lua

@@ -0,0 +1,128 @@
+local ____lualib = require("lualib_bundle")
+local __TS__ArraySlice = ____lualib.__TS__ArraySlice
+local ____exports = {}
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local PillColor = ____isaac_2Dtypescript_2Ddefinitions.PillColor
+local ____cachedClasses = require("cachedClasses")
+local itemConfig = ____cachedClasses.itemConfig
+local ____constantsFirstLast = require("constantsFirstLast")
+local FIRST_HORSE_PILL_COLOR = ____constantsFirstLast.FIRST_HORSE_PILL_COLOR
+local FIRST_MODDED_PILL_EFFECT = ____constantsFirstLast.FIRST_MODDED_PILL_EFFECT
+local FIRST_PILL_COLOR = ____constantsFirstLast.FIRST_PILL_COLOR
+local FIRST_PILL_EFFECT = ____constantsFirstLast.FIRST_PILL_EFFECT
+local LAST_HORSE_PILL_COLOR = ____constantsFirstLast.LAST_HORSE_PILL_COLOR
+local LAST_NORMAL_PILL_COLOR = ____constantsFirstLast.LAST_NORMAL_PILL_COLOR
+local LAST_PILL_EFFECT = ____constantsFirstLast.LAST_PILL_EFFECT
+local LAST_VANILLA_PILL_EFFECT = ____constantsFirstLast.LAST_VANILLA_PILL_EFFECT
+local ____pillEffectClasses = require("objects.pillEffectClasses")
+local DEFAULT_PILL_EFFECT_CLASS = ____pillEffectClasses.DEFAULT_PILL_EFFECT_CLASS
+local PILL_EFFECT_CLASSES = ____pillEffectClasses.PILL_EFFECT_CLASSES
+local ____pillEffectNames = require("objects.pillEffectNames")
+local DEFAULT_PILL_EFFECT_NAME = ____pillEffectNames.DEFAULT_PILL_EFFECT_NAME
+local PILL_EFFECT_NAMES = ____pillEffectNames.PILL_EFFECT_NAMES
+local ____pillEffectTypes = require("objects.pillEffectTypes")
+local DEFAULT_PILL_EFFECT_TYPE = ____pillEffectTypes.DEFAULT_PILL_EFFECT_TYPE
+local PILL_EFFECT_TYPES = ____pillEffectTypes.PILL_EFFECT_TYPES
+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
+        return pillEffectName
+    end
+    local itemConfigPillEffect = itemConfig:GetPillEffect(pillEffect)
+    if itemConfigPillEffect ~= nil then
+        return itemConfigPillEffect.Name
+    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
+function ____exports.isHorsePill(self, pillColor)
+    return pillColor > HORSE_PILL_ADJUSTMENT
+end
+return ____exports

package/functions/player.d.ts

@@ -0,0 +1,296 @@
+import { ActiveSlot, CacheFlag, CollectibleType, PlayerType, TrinketType } from "isaac-typescript-definitions";
+import { HealthType } from "../enums/HealthType";
+export declare function addCollectibleCostume(player: EntityPlayer, collectibleType: CollectibleType): void;
+/**
+ * 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)
+ */
+export declare function addStat(player: EntityPlayer, cacheFlag: CacheFlag, amount: number): void;
+export declare function addTrinketCostume(player: EntityPlayer, trinketType: TrinketType): void;
+export declare function anyPlayerHasCollectible(collectibleType: CollectibleType): boolean;
+export declare function anyPlayerHasTrinket(trinketType: TrinketType): boolean;
+/**
+ * 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.
+ */
+export declare function anyPlayerIs(...matchingCharacters: PlayerType[]): boolean;
+/**
+ * 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)
+ */
+export declare function canPlayerCrushRocks(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.
+ */
+export declare function getActiveItemSlot(player: EntityPlayer, collectibleType: CollectibleType): ActiveSlot | undefined;
+/**
+ * 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
+ */
+export declare function getAzazelBrimstoneDistance(playerOrTearHeight: EntityPlayer | float): float;
+/** Helper function to get an array containing the characters of all of the current players. */
+export declare function getCharacters(): PlayerType[];
+export declare function getClosestPlayer(position: Vector): EntityPlayer;
+/**
+ * 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.
+ */
+export declare function getEffectsList(player: EntityPlayer): TemporaryEffect[];
+/**
+ * Helper function to return the player with the highest ID, according to the `Isaac.GetPlayer`
+ * method.
+ */
+export declare function getFinalPlayer(): EntityPlayer;
+/**
+ * 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.
+ */
+export declare function getNewestPlayer(): EntityPlayer;
+/**
+ * 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;
+/**
+ * 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.
+ */
+export declare function getPlayerCloserThan(position: Vector, distance: float): EntityPlayer | undefined;
+/**
+ * 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.
+ */
+export declare function getPlayerCollectibleCount(player: EntityPlayer, ...collectibleTypes: CollectibleType[]): int;
+/**
+ * Iterates over every item in the game and returns a map containing the number of each item that
+ * the player has.
+ */
+export declare function getPlayerCollectibleMap(player: EntityPlayer): Map<CollectibleType, 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;
+/**
+ * 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.
+ */
+export declare function getPlayerName(player: EntityPlayer): string;
+/**
+ * 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.)
+ */
+export declare function getPlayerNumHitsRemaining(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 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.
+ */
+export declare function getPlayersOfType(...characters: PlayerType[]): EntityPlayer[];
+/**
+ * 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.
+ */
+export declare function getPlayersWithCollectible(...collectibleTypes: CollectibleType[]): EntityPlayer[];
+/**
+ * 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.
+ */
+export declare function getPlayersWithTrinket(...trinketTypes: TrinketType[]): EntityPlayer[];
+/**
+ * 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 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.
+ */
+export declare function getTotalPlayerCollectibles(collectibleType: CollectibleType): int;
+/** After touching a white fire, a player will turn into The Lost until they clear a room. */
+export declare function hasLostCurse(player: EntityPlayer): boolean;
+/**
+ * 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.)
+ */
+export declare function hasOpenActiveItemSlot(player: EntityPlayer): boolean;
+export declare function isActiveSlotEmpty(player: EntityPlayer, activeSlot: ActiveSlot): boolean;
+/**
+ * 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.
+ */
+export declare function isBethany(player: EntityPlayer): boolean;
+/**
+ * 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.
+ */
+export declare function isCharacter(player: EntityPlayer, ...characters: PlayerType[]): 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.
+ */
+export declare function isEden(player: EntityPlayer): boolean;
+export declare function isFirstPlayer(player: EntityPlayer): boolean;
+/**
+ * Helper function for detecting when a player is Jacob or Esau. This will only match the
+ * non-tainted versions of these characters.
+ */
+export declare function isJacobOrEsau(player: EntityPlayer): boolean;
+/**
+ * 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.
+ */
+export declare function isKeeper(player: EntityPlayer): boolean;
+/** Helper function for detecting when a player is The Lost or Tainted Lost. */
+export declare function isLost(player: EntityPlayer): boolean;
+export declare function isModdedPlayer(player: EntityPlayer): boolean;
+/** Helper function for detecting if a player is one of the Tainted characters. */
+export declare function isTainted(player: EntityPlayer): boolean;
+/** Helper function for detecting when a player is Tainted Lazarus or Dead Tainted Lazarus. */
+export declare function isTaintedLazarus(player: EntityPlayer): boolean;
+export declare function isVanillaPlayer(player: EntityPlayer): boolean;
+/**
+ * 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.
+ */
+export declare function playerAddCollectible(player: EntityPlayer, ...collectibleTypes: CollectibleType[]): void;
+/**
+ * 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.
+ */
+export declare function playerHasCollectible(player: EntityPlayer, ...collectibleTypes: CollectibleType[]): boolean;
+/**
+ * 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.
+ */
+export declare function removeCollectibleCostume(player: EntityPlayer, collectibleType: CollectibleType): void;
+/**
+ * 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.
+ */
+export declare function removeDeadEyeMultiplier(player: EntityPlayer): void;
+/**
+ * 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.
+ */
+export declare function removeTrinketCostume(player: EntityPlayer, trinketType: TrinketType): void;
+/**
+ * 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.
+ */
+export declare function setActiveItem(player: EntityPlayer, collectibleType: CollectibleType, activeSlot: ActiveSlot, charge?: int, keepInPools?: boolean): void;
+/**
+ * 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.
+ */
+export declare function setBlindfold(player: EntityPlayer, enabled: boolean, modifyCostume?: boolean): void;
+/**
+ * Helper function to use an active item without showing an animation, keeping the item, or adding
+ * any costumes.
+ */
+export declare function useActiveItemTemp(player: EntityPlayer, collectibleType: CollectibleType): void;