isaacscript-common 2.2.0 → 2.3.0

package/src/functions/table.ts

@@ -0,0 +1,139 @@
+/**
+ * In a Map, you can use the `clear` method to delete every element. However, in a LuaTable, the
+ * `clear` method does not exist. Use this helper function as a drop-in replacement for this.
+ */
+export function clearTable(table: LuaTable): void {
+  for (const [key] of pairs(table)) {
+    table.delete(key);
+  }
+}
+
+/** Helper function to copy specific values from a object to a table. */
+export function copyValuesToTable(
+  object: unknown,
+  keys: string[],
+  table: LuaTable<string, unknown>,
+): void {
+  const otherTable = object as LuaTable<string, string | number>;
+
+  for (const key of keys) {
+    const value = otherTable.get(key);
+    table.set(key, value);
+  }
+}
+
+/**
+ * Helper function to safely get boolean values from a Lua table. Will throw an error if the
+ * specific value does not exist on the table.
+ *
+ * This function is variadic, meaning that you can specify N arguments to get N values.
+ */
+export function getBooleansFromTable(
+  table: LuaTable<string, unknown>,
+  objectName: string,
+  ...keys: string[]
+): boolean[] {
+  const booleans: boolean[] = [];
+  for (const key of keys) {
+    const value = table.get(key);
+    if (value === undefined) {
+      error(
+        `Failed to find a value for "${key}" in a table representing a "${objectName}" object.`,
+      );
+    }
+
+    if (typeof value === "boolean") {
+      booleans.push(value);
+    } else {
+      error(
+        `Failed to get the boolean for the "${key}" value of a table representing a "${objectName}" object because the type was: ${typeof value}`,
+      );
+    }
+  }
+
+  return booleans;
+}
+
+/**
+ * Helper function to safely get number values from a Lua table. Will throw an error if the specific
+ * value does not exist on the table or if it cannot be converted to a number.
+ *
+ * This function is variadic, meaning that you can specify N arguments to get N values.
+ */
+export function getNumbersFromTable(
+  table: LuaTable<string, unknown>,
+  objectName: string,
+  ...keys: string[]
+): number[] {
+  const numbers: number[] = [];
+  for (const key of keys) {
+    const value = table.get(key);
+    if (value === undefined) {
+      error(
+        `Failed to find a value for "${key}" in a table representing a "${objectName}" object.`,
+      );
+    }
+
+    if (typeof value === "number") {
+      numbers.push(value);
+    } else if (typeof value === "string") {
+      const number = tonumber(value);
+      if (number === undefined) {
+        error(
+          `Failed to convert the "${key}" value of a table representing a "${objectName}" object to a number: ${value}`,
+        );
+      }
+      numbers.push(number);
+    } else {
+      error(
+        `Failed to get the number for the "${key}" value of a table representing a "${objectName}" object because the type was: ${typeof value}`,
+      );
+    }
+  }
+
+  return numbers;
+}
+
+/**
+ * Helper function to safely get string values from a Lua table. Will throw an error if the specific
+ * value does not exist on the table.
+ *
+ * This function is variadic, meaning that you can specify N arguments to get N values.
+ */
+export function getStringsFromTable(
+  table: LuaTable<string, unknown>,
+  objectName: string,
+  ...keys: string[]
+): string[] {
+  const strings: string[] = [];
+  for (const key of keys) {
+    const value = table.get(key);
+    if (value === undefined) {
+      error(
+        `Failed to find a value for "${key}" in a table representing a "${objectName}" object.`,
+      );
+    }
+
+    if (typeof value === "string") {
+      strings.push(value);
+    } else {
+      const string = tostring(value);
+      strings.push(string);
+    }
+  }
+
+  return strings;
+}
+
+/**
+ * Helper function to check if a Lua table has all of the provided keys.
+ *
+ * This function is variadic, meaning that you can specify as many arguments as you want to check
+ * for.
+ */
+export function tableHasKeys(
+  table: LuaTable<AnyNotNil, unknown>,
+  ...keys: string[]
+): boolean {
+  return keys.every((key) => table.has(key));
+}

package/src/functions/tears.ts

@@ -0,0 +1,32 @@
+/**
+ * - Converts the specified amount of tears stat into MaxFireDelay and adds it to the player.
+ * - This function should only be used inside the EvaluateCache callback.
+ * - In this context, the "tears stat" represents what is shown on the in-game stat UI.
+ */
+export function addTearsStat(player: EntityPlayer, tearsStat: float): void {
+  const existingTearsStat = getTearsStat(player.MaxFireDelay);
+  const newTearsStat = existingTearsStat + tearsStat;
+  const newMaxFireDelay = getFireDelay(newTearsStat);
+  player.MaxFireDelay = newMaxFireDelay;
+}
+
+/**
+ * - The `EntityPlayer` object stores a player's tear rate in the `MaxFireDelay` attribute. This is
+ *   equivalent to how many tears the player can shoot per frame.
+ * - If you already have a "tears" stat and you want to convert it back to MaxFireDelay, then use
+ *   this function.
+ * - In this context, the "tears stat" represents what is shown on the in-game stat UI.
+ */
+export function getFireDelay(tearsStat: float): float {
+  return math.max(30 / tearsStat - 1, -0.9999);
+}
+
+/**
+ * - The `EntityPlayer` object stores a player's tear rate in the `MaxFireDelay` attribute. This is
+ *   equivalent to how many tears the player can shoot per frame.
+ * - If you want to convert this to the "tears" stat that is shown on the in-game stat UI, then use
+ *   this function.
+ */
+export function getTearsStat(fireDelay: float): float {
+  return 30 / (fireDelay + 1);
+}

package/src/functions/transformations.ts

@@ -0,0 +1,137 @@
+import {
+  CollectibleType,
+  ItemConfigTag,
+  PlayerForm,
+} from "isaac-typescript-definitions";
+import {
+  DEFAULT_TRANSFORMATION_NAME,
+  TRANSFORMATION_NAMES,
+} from "../objects/transformationNames";
+import { getCollectibleTags } from "./collectibles";
+import { getCollectibleTypesWithTag } from "./collectibleTag";
+import { getEnumValues } from "./enums";
+import { hasFlag } from "./flag";
+import { getPlayerCollectibleCount } from "./player";
+
+const TRANSFORMATION_TO_TAG_MAP: ReadonlyMap<PlayerForm, ItemConfigTag> =
+  new Map([
+    [PlayerForm.GUPPY, ItemConfigTag.GUPPY], // 0
+    [PlayerForm.BEELZEBUB, ItemConfigTag.FLY], // 1
+    [PlayerForm.FUN_GUY, ItemConfigTag.MUSHROOM], // 2
+    [PlayerForm.SERAPHIM, ItemConfigTag.ANGEL], // 3
+    [PlayerForm.BOB, ItemConfigTag.BOB], // 4
+    [PlayerForm.SPUN, ItemConfigTag.SYRINGE], // 5
+    [PlayerForm.YES_MOTHER, ItemConfigTag.MOM], // 6
+    [PlayerForm.CONJOINED, ItemConfigTag.BABY], // 7
+    [PlayerForm.LEVIATHAN, ItemConfigTag.DEVIL], // 8
+    [PlayerForm.OH_CRAP, ItemConfigTag.POOP], // 9
+    [PlayerForm.BOOKWORM, ItemConfigTag.BOOK], // 10
+    // PlayerForm.ADULTHOOD (11) is based on pill usage.
+    [PlayerForm.SPIDER_BABY, ItemConfigTag.SPIDER], // 12
+    // PlayerForm.STOMPY (13) is based on size.
+  ]);
+
+const TRANSFORMATIONS_THAT_GRANT_FLYING: ReadonlySet<PlayerForm> = new Set([
+  PlayerForm.GUPPY, // 0
+  PlayerForm.BEELZEBUB, // 1
+  PlayerForm.SERAPHIM, // 3
+  PlayerForm.LEVIATHAN, // 8
+]);
+
+/**
+ * Helper function to get all of the collectible types in the game that count towards a particular
+ * transformation.
+ *
+ * For example, to get all of the collectible types that count towards Guppy:
+ *
+ * ```ts
+ * const guppyCollectibleTypes = getCollectibleTypesForTransformation(PlayerForm.GUPPY);
+ * ```
+ */
+export function getCollectibleTypesForTransformation(
+  playerForm: PlayerForm,
+): Set<CollectibleType> {
+  const itemConfigTag = TRANSFORMATION_TO_TAG_MAP.get(playerForm);
+  if (itemConfigTag === undefined) {
+    error(
+      `Failed to get the collectible types for the transformation of ${playerForm} because that transformation is not based on collectibles.`,
+    );
+  }
+
+  return getCollectibleTypesWithTag(itemConfigTag);
+}
+
+/** Returns the number of items that a player has towards a particular transformation. */
+export function getPlayerNumCollectiblesForTransformation(
+  player: EntityPlayer,
+  playerForm: PlayerForm,
+): int {
+  const collectibleTypes = getCollectibleTypesForTransformation(playerForm);
+  return getPlayerCollectibleCount(player, ...collectibleTypes.values());
+}
+
+/** Returns a set of the player's current transformations. */
+export function getPlayerTransformations(
+  player: EntityPlayer,
+): Set<PlayerForm> {
+  const transformations = new Set<PlayerForm>();
+  for (const playerForm of getEnumValues(PlayerForm)) {
+    if (player.HasPlayerForm(playerForm)) {
+      transformations.add(playerForm);
+    }
+  }
+
+  return transformations;
+}
+
+/**
+ * Helper function to get a transformation name from a PlayerForm enum.
+ *
+ * For example:
+ *
+ * ```ts
+ * const transformationName = getTransformationName(PlayerForm.LORD_OF_THE_FLIES);
+ * // transformationName is "Beelzebub"
+ * ```
+ */
+export function getTransformationName(playerForm: PlayerForm): string {
+  const transformationName = TRANSFORMATION_NAMES[playerForm];
+  return transformationName === undefined
+    ? DEFAULT_TRANSFORMATION_NAME
+    : transformationName;
+}
+
+export function getTransformationsForCollectibleType(
+  collectibleType: CollectibleType,
+): Set<PlayerForm> {
+  const itemConfigTags = getCollectibleTags(collectibleType);
+
+  const playerForms = getEnumValues(PlayerForm);
+  const transformationSet = new Set<PlayerForm>();
+  for (const playerForm of playerForms) {
+    const itemConfigTag = TRANSFORMATION_TO_TAG_MAP.get(playerForm);
+    if (itemConfigTag === undefined) {
+      continue;
+    }
+
+    if (hasFlag(itemConfigTags, itemConfigTag)) {
+      transformationSet.add(playerForm);
+    }
+  }
+
+  return transformationSet;
+}
+
+export function hasFlyingTransformation(player: EntityPlayer): boolean {
+  for (const playerForm of TRANSFORMATIONS_THAT_GRANT_FLYING.values()) {
+    if (player.HasPlayerForm(playerForm)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export function isTransformationFlying(playerForm: PlayerForm): boolean {
+  return TRANSFORMATIONS_THAT_GRANT_FLYING.has(playerForm);
+}

package/src/functions/trinketCacheFlag.ts

@@ -0,0 +1,60 @@
+import { CacheFlag, TrinketType } from "isaac-typescript-definitions";
+import { getEnumValues } from "./enums";
+import { copySet } from "./set";
+import { getTrinketTypes, trinketHasCacheFlag } from "./trinkets";
+
+const CACHE_FLAG_TO_TRINKETS_MAP = new Map<CacheFlag, Set<TrinketType>>();
+
+function initCacheFlagMap() {
+  for (const cacheFlag of getEnumValues(CacheFlag)) {
+    const trinketsSet = new Set<TrinketType>();
+
+    for (const trinketType of getTrinketTypes()) {
+      if (trinketHasCacheFlag(trinketType, cacheFlag)) {
+        trinketsSet.add(trinketType);
+      }
+    }
+
+    CACHE_FLAG_TO_TRINKETS_MAP.set(cacheFlag, trinketsSet);
+  }
+}
+
+/**
+ * Returns a map containing every trinket type that the player has that matches the provided
+ * CacheFlag. The values of the map correspond to the multiplier for that trinket.
+ */
+export function getPlayerTrinketsForCacheFlag(
+  player: EntityPlayer,
+  cacheFlag: CacheFlag,
+): Map<TrinketType, int> {
+  const trinketsForCacheFlag = getTrinketsForCacheFlag(cacheFlag);
+
+  const playerTrinkets = new Map<TrinketType, int>();
+  for (const trinketType of trinketsForCacheFlag.values()) {
+    const trinketMultiplier = player.GetTrinketMultiplier(trinketType);
+    if (trinketMultiplier > 0) {
+      playerTrinkets.set(trinketType, trinketMultiplier);
+    }
+  }
+
+  return playerTrinkets;
+}
+
+/**
+ * Returns a set containing every trinket type with the given cache flag, including modded trinkets.
+ */
+export function getTrinketsForCacheFlag(
+  cacheFlag: CacheFlag,
+): Set<TrinketType> {
+  // Lazy initialize the map.
+  if (CACHE_FLAG_TO_TRINKETS_MAP.size === 0) {
+    initCacheFlagMap();
+  }
+
+  const trinketsSet = CACHE_FLAG_TO_TRINKETS_MAP.get(cacheFlag);
+  if (trinketsSet === undefined) {
+    return new Set();
+  }
+
+  return copySet(trinketsSet);
+}

package/src/functions/trinketGive.ts

@@ -0,0 +1,157 @@
+import {
+  CollectibleType,
+  TrinketSlot,
+  TrinketType,
+} from "isaac-typescript-definitions";
+import { TrinketSituation } from "../interfaces/TrinketSituation";
+import { useActiveItemTemp } from "./player";
+import { getGoldenTrinketType } from "./trinkets";
+import { repeat } from "./utils";
+
+/**
+ * Helper function to restore the player's trinkets back to the way they were before the
+ * `temporarilyRemoveTrinket` function was used. It will re-smelt any smelted trinkets that were
+ * removed.
+ */
+export function giveTrinketsBack(
+  player: EntityPlayer,
+  trinketSituation: TrinketSituation | undefined,
+): void {
+  // A trinket situation of undefined signifies that we did not have to remove the trinket. If this
+  // is the case, we do not have to give anything back.
+  if (trinketSituation === undefined) {
+    return;
+  }
+
+  const trinketType1 = player.GetTrinket(TrinketSlot.SLOT_1);
+  const trinketType2 = player.GetTrinket(TrinketSlot.SLOT_2);
+
+  // Remove any existing trinkets.
+  if (trinketType1 !== TrinketType.NULL) {
+    player.TryRemoveTrinket(trinketType1);
+  }
+  if (trinketType2 !== TrinketType.NULL) {
+    player.TryRemoveTrinket(trinketType2);
+  }
+
+  // First, add the smelted trinkets back.
+  repeat(trinketSituation.numSmeltedTrinkets, () => {
+    player.AddTrinket(trinketSituation.trinketTypeRemoved, false);
+    useActiveItemTemp(player, CollectibleType.SMELTER);
+  });
+
+  // Second, add back the stored trinkets.
+  if (trinketSituation.trinketType1 !== TrinketType.NULL) {
+    player.AddTrinket(trinketSituation.trinketType1, false);
+  }
+  if (trinketSituation.trinketType2 !== TrinketType.NULL) {
+    player.AddTrinket(trinketSituation.trinketType2, false);
+  }
+}
+
+/**
+ * Helper function to smelt a trinket. Before smelting, this function will automatically remove the
+ * trinkets that the player is holding, if any, and then give them back after the new trinket is
+ * smelted.
+ *
+ * @param player The player to smelt the trinkets to.
+ * @param trinketType The trinket type to smelt.
+ * @param numTrinkets Optional. If specified, will smelt the given number of trinkets. Use this to
+ *                    avoid calling this function multiple times. Default is 1.
+ */
+export function smeltTrinket(
+  player: EntityPlayer,
+  trinketType: TrinketType,
+  numTrinkets = 1,
+): void {
+  const trinketSituation = temporarilyRemoveTrinkets(player);
+
+  repeat(numTrinkets, () => {
+    player.AddTrinket(trinketType);
+    useActiveItemTemp(player, CollectibleType.SMELTER);
+  });
+
+  giveTrinketsBack(player, trinketSituation);
+}
+
+/**
+ * Helper function to temporarily remove a specific kind of trinket from the player. Use this in
+ * combination with the `giveTrinketsBack` function to take away and give back a trinket on the same
+ * frame. This function correctly handles multiple trinket slots and ensures that all copies of the
+ * trinket are removed, including smelted trinkets.
+ *
+ * Note that one smelted golden trinket is the same as two smelted normal trinkets.
+ *
+ * @returns Undefined if the player does not have the trinket, or TrinketSituation if they do.
+ */
+export function temporarilyRemoveTrinket(
+  player: EntityPlayer,
+  trinketType: TrinketType,
+): TrinketSituation | undefined {
+  if (!player.HasTrinket(trinketType)) {
+    return undefined;
+  }
+
+  const trinketType1 = player.GetTrinket(TrinketSlot.SLOT_1);
+  const trinketType2 = player.GetTrinket(TrinketSlot.SLOT_2);
+
+  let numTrinkets = 0;
+  while (player.HasTrinket(trinketType)) {
+    player.TryRemoveTrinket(trinketType);
+    numTrinkets += 1;
+  }
+
+  let numSmeltedTrinkets = numTrinkets;
+  const trinketWasInSlot1 =
+    trinketType1 === trinketType ||
+    trinketType1 === getGoldenTrinketType(trinketType);
+  if (trinketWasInSlot1) {
+    numSmeltedTrinkets -= 1;
+  }
+  const trinketWasInSlot2 =
+    trinketType2 === trinketType ||
+    trinketType2 === getGoldenTrinketType(trinketType);
+  if (trinketWasInSlot2) {
+    numSmeltedTrinkets -= 1;
+  }
+
+  return {
+    trinketTypeRemoved: trinketType,
+    trinketType1,
+    trinketType2,
+    numSmeltedTrinkets,
+  };
+}
+
+/**
+ * Helper function to temporarily removes a player's held trinkets, if any. This will not remove any
+ * smelted trinkets. Use this in combination with the `giveTrinketsBack` function to take away and
+ * give back trinkets on the same frame.
+ *
+ * @returns Undefined if the player does not have any trinkets, or TrinketSituation if they do.
+ */
+export function temporarilyRemoveTrinkets(
+  player: EntityPlayer,
+): TrinketSituation | undefined {
+  const trinketType1 = player.GetTrinket(TrinketSlot.SLOT_1);
+  const trinketType2 = player.GetTrinket(TrinketSlot.SLOT_2);
+
+  if (trinketType1 === TrinketType.NULL && trinketType2 === TrinketType.NULL) {
+    return undefined;
+  }
+
+  if (trinketType1 !== TrinketType.NULL) {
+    player.TryRemoveTrinket(trinketType1);
+  }
+
+  if (trinketType2 !== TrinketType.NULL) {
+    player.TryRemoveTrinket(trinketType2);
+  }
+
+  return {
+    trinketTypeRemoved: TrinketType.NULL,
+    trinketType1,
+    trinketType2,
+    numSmeltedTrinkets: 0,
+  };
+}