isaacscript-common 2.0.34 → 2.3.0

package/src/functions/entityTypes.ts

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,145 @@
+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

@@ -0,0 +1,106 @@
+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

@@ -0,0 +1,165 @@
+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

@@ -0,0 +1,117 @@
+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);
+}