isaacscript-common 2.3.0 → 2.3.1

package/src/functions/entityTypes.ts

@@ -1,6 +0,0 @@
-import { EntityType } from "isaac-typescript-definitions";
-
-/** For EntityType.SLOT (6) */
-export function isSlot(entity: Entity): entity is EntitySlot {
-  return entity.Type === EntityType.SLOT;
-}

package/src/functions/enums.ts

@@ -1,145 +0,0 @@
-import { getRandomArrayElement } from "./array";
-import { getRandomSeed } from "./rng";
-
-/**
- * TypeScriptToLua will transpile TypeScript enums to Lua tables that have a double mapping. Thus,
- * when you iterate over them, you will get both the names of the enums and the values of the enums,
- * in a random order. Use this helper function to get the entries of the enum with the reverse
- * mappings filtered out.
- *
- * This function will return the enum values in a sorted order, which may not necessarily be the
- * same order as which they were declared in.
- *
- * This function will work properly for both number enums and string enums. (Reverse mappings are
- * not created for string enums.)
- *
- * Also see the `getEnumKeys` and `getEnumValues` helper functions.
- *
- * For a more in depth explanation, see:
- * https://isaacscript.github.io/gotchas#iterating-over-enums
- */
-export function getEnumEntries<T>(
-  transpiledEnum: T,
-): Array<[key: string, value: T[keyof T]]> {
-  // The values cannot simply be type `T` due to the special construction of bit flag enums.
-  const enumEntries: Array<[key: string, value: T[keyof T]]> = [];
-  for (const [key, value] of pairs(transpiledEnum)) {
-    // Ignore the reverse mappings created by TypeScriptToLua. Note that reverse mappings are not
-    // created for string enums.
-    if (typeof key === "string") {
-      enumEntries.push([key, value]);
-    }
-  }
-
-  // The enums will be in a random order (because of "pairs"), so sort them based on the values.
-  // https://stackoverflow.com/questions/5199901/how-to-sort-an-associative-array-by-its-values-in-javascript
-  enumEntries.sort(
-    ([_key1, value1], [_key2, value2]) =>
-      value1 < value2 ? -1 : value1 > value2 ? 1 : 0, // eslint-disable-line no-nested-ternary
-  );
-
-  return enumEntries;
-}
-
-/**
- * TypeScriptToLua will transpile TypeScript enums to Lua tables that have a double mapping. Thus,
- * when you iterate over them, you will get both the names of the enums and the values of the enums,
- * in a random order. If all you need are the keys of an enum, use this helper function.
- *
- * This function will return the enum keys in a sorted order, which may not necessarily be the same
- * order as which they were declared in.
- *
- * This function will work properly for both number enums and string enums. (Reverse mappings are
- * not created for string enums.)
- *
- * Also see the `getEnumEntries` and `getEnumValues` helper functions.
- *
- * For a more in depth explanation, see:
- * https://isaacscript.github.io/gotchas#iterating-over-enums
- */
-export function getEnumKeys<T>(transpiledEnum: T): string[] {
-  const enumEntries = getEnumEntries(transpiledEnum);
-  return enumEntries.map(([key, _value]) => key);
-}
-
-/** Helper function to get the amount of entries inside of an enum. */
-export function getEnumLength<T>(transpiledEnum: T): int {
-  const enumEntries = getEnumEntries(transpiledEnum);
-  return enumEntries.length;
-}
-
-/**
- * TypeScriptToLua will transpile TypeScript enums to Lua tables that have a double mapping. Thus,
- * when you iterate over them, you will get both the names of the enums and the values of the enums,
- * in a random order. If all you need are the values of an enum, use this helper function.
- *
- * This function will return the enum values in a sorted order, which may not necessarily be the
- * same order as which they were declared in.
- *
- * This function will work properly for both number enums and string enums. (Reverse mappings are
- * not created for string enums.)
- *
- * Also see the `getEnumEntries` and `getEnumKeys` helper functions.
- *
- * For a more in depth explanation, see:
- * https://isaacscript.github.io/gotchas#iterating-over-enums
- */
-export function getEnumValues<T>(transpiledEnum: T): Array<T[keyof T]> {
-  const enumEntries = getEnumEntries(transpiledEnum);
-  return enumEntries.map(([_key, value]) => value);
-}
-
-export function getLastEnumValue<T>(transpiledEnum: T): T[keyof T] {
-  const enumValues = getEnumValues(transpiledEnum);
-
-  const lastElement = enumValues[enumValues.length - 1];
-  if (lastElement === undefined) {
-    error(
-      "Failed to get the last value from an enum since the enum was empty.",
-    );
-  }
-
-  return lastElement;
-}
-
-/**
- * Helper function to get a random value from the provided enum.
- *
- * @param transpiledEnum The enum to get the value from.
- * @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
- *                  `RNG.Next` method will be called. Default is `getRandomSeed()`.
- * @param exceptions Optional. An array of elements to skip over if selected.
- */
-export function getRandomEnumValue<T>(
-  transpiledEnum: T,
-  seedOrRNG: Seed | RNG = getRandomSeed(),
-  exceptions: Array<T[keyof T]> | ReadonlyArray<T[keyof T]> = [],
-): T[keyof T] {
-  const enumValues = getEnumValues(transpiledEnum);
-  return getRandomArrayElement(enumValues, seedOrRNG, exceptions);
-}
-
-/**
- * Helper function to check every value of a custom enum for -1. This is helpful as a run-time check
- * because many methods of the Isaac class return -1 if they fail.
- *
- * For example:
- *
- * ```ts
- * enum EntityTypeCustom {
- *   FOO = Isaac.GetEntityTypeByName("Foo"),
- * }
- *
- * validateCustomEnum("EntityTypeCustom", EntityTypeCustom);
- * ```
- */
-export function validateCustomEnum(
-  transpiledEnumName: string,
-  transpiledEnum: unknown,
-): void {
-  for (const [key, value] of getEnumEntries(transpiledEnum)) {
-    if (value === -1) {
-      error(`Failed to find custom enum value: ${transpiledEnumName}.${key}`);
-    }
-  }
-}

package/src/functions/familiars.ts

@@ -1,106 +0,0 @@
-import { CollectibleType, FamiliarVariant } from "isaac-typescript-definitions";
-import { itemConfig } from "../cachedClasses";
-import { FAMILIARS_THAT_SHOOT_PLAYER_TEARS_SET } from "../sets/familiarsThatShootPlayerTearsSet";
-
-/**
- * Helper function to add and remove familiars based on a target amount that you specify.
- *
- * This is a convenience wrapper around the `EntityPlayer.CheckFamiliar` method. Use this helper
- * function instead so that you do not have to retrieve the `ItemConfigItem` and so that you do not
- * specify an incorrect RNG object. (The vanilla method is bugged in that it does not increment the
- * RNG object; see the documentation of the method for more details.)
- *
- * This function is meant to be called in the EvaluateCache callback (when the cache flag is equal
- * to `CacheFlag.FAMILIARS`).
- *
- * Note that this function is only meant to be used in special circumstances where the familiar
- * count is completely custom and does not correspond to the amount of collectibles. For the general
- * case, use the `checkFamiliarFromCollectibles` helper function instead.
- *
- * Note that this will spawn familiars with a completely random `InitSeed`. When calculating random
- * events for this familiar, you should use a data structure that maps familiar `InitSeed` to RNG
- * objects that are initialized based on the seed from
- * `EntityPlayer.GetCollectibleRNG(collectibleType)`.
- *
- * @param player The player that owns the familiars.
- * @param collectibleType The collectible type of the collectible associated with this familiar.
- * @param targetCount 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.
- */
-export function checkFamiliar(
-  player: EntityPlayer,
-  collectibleType: CollectibleType,
-  targetCount: int,
-  familiarVariant: FamiliarVariant,
-  familiarSubType?: int,
-): void {
-  const itemConfigItem = itemConfig.GetCollectible(collectibleType);
-  player.CheckFamiliar(
-    familiarVariant,
-    targetCount,
-    RNG(),
-    itemConfigItem,
-    familiarSubType,
-  );
-}
-
-/**
- * Helper function to add and remove familiars based on the amount of associated collectibles that a
- * player has.
- *
- * Use this helper function instead of invoking the `EntityPlayer.CheckFamiliar` method directly so
- * that the target count is handled automatically.
- *
- * This function is meant to be called in the EvaluateCache callback (when the cache flag is equal
- * to `CacheFlag.FAMILIARS`).
- *
- * 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 or Monster
- * Manual). If you instead need to have a custom amount of familiars, use the `checkFamiliars`
- * function instead.
- *
- * Note that this will spawn familiars with a completely random `InitSeed`. When calculating random
- * events for this familiar, you should use a data structure that maps familiar `InitSeed` to RNG
- * objects that are initialized based on the seed from
- * `EntityPlayer.GetCollectibleRNG(collectibleType)`.
- *
- * @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. If not
- *                        specified, it will search for existing familiars of all sub-types, and
- *                        spawn new familiars with a sub-type of 0.
- */
-export function checkFamiliarFromCollectibles(
-  player: EntityPlayer,
-  collectibleType: CollectibleType,
-  familiarVariant: FamiliarVariant,
-  familiarSubType?: int,
-): void {
-  const numCollectibles = player.GetCollectibleNum(collectibleType);
-  const effects = player.GetEffects();
-
-  // Whenever Box of Friends or Monster Manual is used, it will automatically increment the number
-  // of collectible effects for this familiar.
-  const numCollectibleEffects =
-    effects.GetCollectibleEffectNum(collectibleType);
-  const targetCount = numCollectibles + numCollectibleEffects;
-
-  checkFamiliar(
-    player,
-    collectibleType,
-    targetCount,
-    familiarVariant,
-    familiarSubType,
-  );
-}
-
-export function isFamiliarThatShootsPlayerTears(
-  familiar: EntityFamiliar,
-): boolean {
-  return FAMILIARS_THAT_SHOOT_PLAYER_TEARS_SET.has(familiar.Variant);
-}

package/src/functions/flag.ts

@@ -1,165 +0,0 @@
-import { DamageFlag } from "isaac-typescript-definitions";
-
-/**
- * Helper function to add a bit flag to an existing set of bit flags.
- *
- * This is a variadic function, so pass as many flags as you want to add.
- *
- * Example 1:
- *
- * ```ts
- * // Give the player spectral tears
- * const player = Isaac.GetPlayer();
- * player.TearFlags = addFlag(player.TearFlags, TearFlags.TEAR_SPECTRAL);
- * ```
- *
- * Example 2:
- *
- * ```ts
- * // Give the player spectral and homing tears
- * const player = Isaac.GetPlayer();
- * player.TearFlags = addFlag(player.TearFlags, TearFlags.TEAR_SPECTRAL, TearFlags.TEAR_HOMING);
- * ```
- *
- * @param flags The existing set of bit flags.
- * @param flagsToAdd One or more bit flags to add, each as a separate argument.
- * @returns The combined bit flags.
- */
-export function addFlag<T extends BitFlag | BitFlag128>(
-  flags: T | BitFlags<T>,
-  ...flagsToAdd: T[]
-): BitFlags<T> {
-  let flagsAsInt = flags as int;
-
-  for (const flagToAdd of flagsToAdd) {
-    flagsAsInt |= flagToAdd as int;
-  }
-
-  return flagsAsInt as BitFlags<T>;
-}
-
-/**
- * Helper function for casting a flag enum value to a `BitFlags` object.
- *
- * This is useful because the compiler will prevent you from assigning a specific flag to a
- * `BitFlags` property. (It does this to ensure type safety, since `BitFlags` can represent a zero
- * value or a composition of N flags.)
- *
- * For example:
- *
- * ```ts
- * player.TearFlags = bitFlags(TearFlag.SPECTRAL);
- * ```
- */
-export function bitFlags<T extends BitFlag | BitFlag128>(flag: T): BitFlags<T> {
-  return flag as BitFlags<T>;
-}
-
-/**
- * Helper function to get the key associated with a particular flag.
- *
- * (Since bit flags are represented by custom objects instead of normal TypeScript enums, you cannot
- * use the reverse mapping to find the associated key of a given enum value. Use this helper
- * function instead of indexing the enum directly.)
- */
-export function getFlagName<T extends BitFlag | BitFlag128>(
-  flag: BitFlag,
-  flagEnum: Record<string, T>,
-): string | undefined {
-  for (const [key, value] of pairs(flagEnum)) {
-    if (value === flag) {
-      return key;
-    }
-  }
-
-  return undefined;
-}
-
-/**
- * Helper function to determine if a particular bit flag is set to true.
- *
- * This is a variadic function, so pass as many flags as you want to check for. If passed multiple
- * flags, it will only return true if all of the flags are set.
- *
- * For example:
- *
- * ```ts
- * const player = Isaac.GetPlayer();
- * if (hasFlag(player.TearFlags, TearFlags.TEAR_SPECTRAL) {
- *   // The player currently has spectral tears
- * }
- * ```
- *
- * @param flags The existing set of bit flags.
- * @param flagsToCheck One or more bit flags to check for, each as a separate argument.
- */
-export function hasFlag<T extends BitFlag | BitFlag128>(
-  flags: T | BitFlags<T>,
-  ...flagsToCheck: T[]
-): boolean {
-  const flagsAsInt = flags as int;
-
-  for (const flagToCheck of flagsToCheck) {
-    if (!((flagsAsInt & (flagToCheck as int)) === flagToCheck)) {
-      return false;
-    }
-  }
-
-  return true;
-}
-
-/**
- * Helper function to check if every bit in the flag is turned off.
- *
- * (This is equivalent to checking if the flag is equal to 0, but this is not possible without
- * casting the flag to a number.)
- */
-export function isEmptyFlag<T extends BitFlag | BitFlag128>(flag: T): boolean {
-  return flag === 0;
-}
-
-/**
- * Helper function to determine whether damage to a player in the EntityTakeDmg callback was
- * self-inflicted. For example, damage from a Curse Room door, a Razor, or a Blood Donation Machine
- * would count as self-inflicted damage.
- */
-export function isSelfDamage(
-  damageFlags: DamageFlag | BitFlags<DamageFlag>,
-): boolean {
-  return (
-    // Exclude self-damage from e.g. Curse Room door spikes.
-    hasFlag(damageFlags, DamageFlag.NO_PENALTIES) ||
-    // Exclude self-damage from e.g. Razor.
-    hasFlag(damageFlags, DamageFlag.RED_HEARTS)
-  );
-}
-
-/**
- * Helper function to remove a bit flag from an existing set of bit flags.
- *
- * This is a variadic function, so pass as many flags as you want to remove.
- *
- * For example:
- *
- * ```ts
- * // Remove spectral tears from the player, if present
- * const player = Isaac.GetPlayer();
- * player.TearFlags = removeFlag(player.TearFlags, TearFlags.TEAR_SPECTRAL);
- * ```
- *
- * @param flags The existing set of bit flags.
- * @param flagsToRemove One or more bit flags to remove, each as a separate argument.
- * @returns The combined bit flags.
- */
-export function removeFlag<T extends BitFlag | BitFlag128>(
-  flags: T | BitFlags<T>,
-  ...flagsToRemove: T[]
-): BitFlags<T> {
-  let flagsAsInt = flags as int;
-
-  for (const flagToRemove of flagsToRemove) {
-    flagsAsInt &= ~flagToRemove;
-  }
-
-  return flagsAsInt as BitFlags<T>;
-}

package/src/functions/flying.ts

@@ -1,117 +0,0 @@
-import {
-  CacheFlag,
-  CollectibleType,
-  NullItemID,
-  PlayerType,
-  TrinketType,
-} from "isaac-typescript-definitions";
-import { getCollectiblesForCacheFlag } from "./collectibleCacheFlag";
-import { copySet, deleteSetsFromSet } from "./set";
-
-const FLYING_CHARACTERS: ReadonlySet<PlayerType> = new Set([
-  PlayerType.AZAZEL, // 7
-  PlayerType.THE_LOST, // 10
-  PlayerType.THE_SOUL, // 17
-  PlayerType.THE_LOST_B, // 31
-  PlayerType.JACOB_2_B, // 39
-  PlayerType.THE_SOUL_B, // 40
-]);
-
-const FLYING_TRINKETS: ReadonlySet<TrinketType> = new Set([
-  TrinketType.BAT_WING, // 118
-  TrinketType.AZAZELS_STUMP, // 162
-]);
-
-const FLYING_NULL_ITEMS: readonly NullItemID[] = [
-  NullItemID.REVERSE_SUN, // 66
-  NullItemID.SPIRIT_SHACKLES_SOUL, // 10
-  NullItemID.LOST_CURSE, // 112
-];
-
-const CONDITIONAL_FLYING_COLLECTIBLE_TYPES: readonly CollectibleType[] = [
-  CollectibleType.BIBLE,
-  CollectibleType.EMPTY_VESSEL,
-  CollectibleType.ASTRAL_PROJECTION,
-  CollectibleType.RECALL,
-];
-
-/**
- * Returns a set of all of the collectibles that grant flight. This is derived from collectibles
- * that have `CacheFlag.FLYING` set in the "items.xml" file.
- *
- * Collectibles that only grant flight conditionally are manually pruned. Collectibles such as Empty
- * Vessel should be checked for via the `hasFlyingTemporaryEffect` function.
- *
- * @param pruneConditionalItems Whether or not collectibles that only grant flight conditionally
- *                              should be included in the set (like Empty Vessel).
- */
-export function getFlyingCollectibles(
-  pruneConditionalItems: boolean,
-): Set<CollectibleType> {
-  // Instead of manually compiling a list of collectibles that grant flying, we can instead
-  // dynamically look for collectibles that have `CacheFlag.FLYING`.
-  const collectiblesWithFlyingCacheFlag = getCollectiblesForCacheFlag(
-    CacheFlag.FLYING,
-  );
-
-  // None of the collectibles with a cache of "all" grant flying, so we can safely remove them from
-  // the list.
-  const collectiblesWithAllCacheFlag = getCollectiblesForCacheFlag(
-    CacheFlag.ALL,
-  );
-  deleteSetsFromSet(
-    collectiblesWithFlyingCacheFlag,
-    collectiblesWithAllCacheFlag,
-  );
-
-  if (pruneConditionalItems) {
-    for (const collectibleType of CONDITIONAL_FLYING_COLLECTIBLE_TYPES) {
-      collectiblesWithFlyingCacheFlag.delete(collectibleType);
-    }
-  }
-
-  return collectiblesWithFlyingCacheFlag;
-}
-
-/**
- * Returns a set of all of the trinkets that grant flight. (All trinkets that grant flight do so
- * conditionally, like Bat Wing.)
- */
-export function getFlyingTrinkets(): ReadonlySet<TrinketType> {
-  // We use a different algorithm than the "getFlyingCollectibles" function because Azazel's Stump
-  // has a cache of "all".
-  return copySet(FLYING_TRINKETS);
-}
-
-export function hasFlyingTemporaryEffect(player: EntityPlayer): boolean {
-  const effects = player.GetEffects();
-
-  // - Hanged Man card gives a Transcendence temporary effect.
-  // - Pinking Shears gives a Transcendence temporary effect.
-  const flyingCollectibles = getFlyingCollectibles(false);
-  for (const collectibleType of flyingCollectibles.values()) {
-    if (effects.HasCollectibleEffect(collectibleType)) {
-      return true;
-    }
-  }
-
-  const flyingTrinkets = getFlyingTrinkets();
-  for (const trinketType of flyingTrinkets.values()) {
-    if (effects.HasTrinketEffect(trinketType)) {
-      return true;
-    }
-  }
-
-  for (const nullItemID of FLYING_NULL_ITEMS) {
-    if (effects.HasNullEffect(nullItemID)) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
-export function isFlyingCharacter(player: EntityPlayer): boolean {
-  const character = player.GetPlayerType();
-  return FLYING_CHARACTERS.has(character);
-}