isaacscript-common 4.0.1-dev.0 → 4.0.4

package/functions/string.ts

@@ -1,47 +0,0 @@
-export function capitalizeFirstLetter(string: string): string {
-  const firstCharacter = string.charAt(0);
-  const capitalizedFirstLetter = firstCharacter.toUpperCase();
-  const restOfString = string.slice(1);
-
-  return `${capitalizedFirstLetter}${restOfString}`;
-}
-
-export function removeAllCharacters(string: string, character: string): string {
-  return string.replaceAll(character, "");
-}
-
-/**
- * Helper function to remove one or more substrings from a string, if they exist. Returns the
- * modified string.
- *
- * This function is variadic, meaning that you can pass as many substrings as you want to remove.
- */
-export function removeSubstring(
-  string: string,
-  ...substrings: string[]
-): string {
-  for (const substring of substrings) {
-    string = string.replaceAll(substring, "");
-  }
-
-  return string;
-}
-
-/** Helper function to trim a prefix from a string, if it exists. Returns the trimmed string. */
-export function trimPrefix(string: string, prefix: string): string {
-  if (!string.startsWith(prefix)) {
-    return string;
-  }
-
-  return string.slice(prefix.length);
-}
-
-/** Helper function to trim a suffix from a string, if it exists. Returns the trimmed string. */
-export function trimSuffix(string: string, prefix: string): string {
-  if (!string.endsWith(prefix)) {
-    return string;
-  }
-
-  const endCharacter = string.length - prefix.length;
-  return string.slice(0, endCharacter);
-}

package/functions/table.ts

@@ -1,189 +0,0 @@
-import { isBoolean, isNumber, isString } from "./types";
-
-/**
- * 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(luaTable: LuaTable): void {
-  for (const [key] of pairs(luaTable)) {
-    luaTable.delete(key);
-  }
-}
-
-/** Helper function to copy specific values from a object to a table. */
-export function copyValuesToTable(
-  object: unknown,
-  keys: string[],
-  luaTable: LuaTable<string, unknown>,
-): void {
-  const otherTable = object as LuaTable<string, string | number>;
-
-  for (const key of keys) {
-    const value = otherTable.get(key);
-    luaTable.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(
-  luaTable: LuaTable<string, unknown>,
-  objectName: string,
-  ...keys: string[]
-): boolean[] {
-  const booleans: boolean[] = [];
-  for (const key of keys) {
-    const value = luaTable.get(key);
-    if (value === undefined) {
-      error(
-        `Failed to find a value for "${key}" in a table representing a "${objectName}" object.`,
-      );
-    }
-
-    if (isBoolean(value)) {
-      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(
-  luaTable: LuaTable<string, unknown>,
-  objectName: string,
-  ...keys: string[]
-): number[] {
-  const numbers: number[] = [];
-  for (const key of keys) {
-    const value = luaTable.get(key);
-    if (value === undefined) {
-      error(
-        `Failed to find a value for "${key}" in a table representing a "${objectName}" object.`,
-      );
-    }
-
-    if (isNumber(value)) {
-      numbers.push(value);
-    } else if (isString(value)) {
-      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(
-  luaTable: LuaTable<string, unknown>,
-  objectName: string,
-  ...keys: string[]
-): string[] {
-  const strings: string[] = [];
-  for (const key of keys) {
-    const value = luaTable.get(key);
-    if (value === undefined) {
-      error(
-        `Failed to find a value for "${key}" in a table representing a "${objectName}" object.`,
-      );
-    }
-
-    if (isString(value)) {
-      strings.push(value);
-    } else {
-      const string = tostring(value);
-      strings.push(string);
-    }
-  }
-
-  return strings;
-}
-
-/**
- * Helper function to iterate over a table deterministically. This is useful because by default, the
- * `pairs` function will return the keys of a Lua table in a random order.
- *
- * This function will sort the table entries based on the value of the key.
- *
- * This function will only work on tables that have number keys or string keys. It will throw a
- * runtime error if it encounters a key of another type.
- *
- * @param luaTable The table to iterate over.
- * @param func The function to run for each iteration.
- * @param inOrder Optional. Whether to iterate in order. True by default. You can dynamically set to
- *                false in situations where iterating randomly would not matter and you need the
- *                extra performance.
- */
-export function iterateTableInOrder<K, V>(
-  luaTable: LuaTable<K, V>,
-  func: (key: K, value: V) => void,
-  inOrder = true,
-): void {
-  // First, handle the trivial case of a non-deterministic iteration.
-  if (!inOrder) {
-    for (const [key, value] of pairs(luaTable)) {
-      func(key, value);
-    }
-    return;
-  }
-
-  const keys = Object.keys(luaTable);
-  const hasAllNumberKeys = keys.every((key) => isNumber(key));
-  const hasAllStringKeys = keys.every((key) => isString(key));
-  if (!hasAllNumberKeys && !hasAllStringKeys) {
-    // Since the table has non-homogenous keys, we won't be able to sort it. Revert to
-    // non-deterministic iteration in this case.
-    for (const [key, value] of pairs(luaTable)) {
-      func(key, value);
-    }
-    return;
-  }
-  keys.sort();
-
-  for (const key of keys) {
-    const keyIndex = key as unknown as K;
-    const value = luaTable.get(keyIndex);
-    func(keyIndex, value);
-  }
-}
-
-/**
- * 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(
-  luaTable: LuaTable<AnyNotNil, unknown>,
-  ...keys: string[]
-): boolean {
-  return keys.every((key) => luaTable.has(key));
-}

package/functions/tears.ts

@@ -1,32 +0,0 @@
-/**
- * - 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/functions/transformations.ts

@@ -1,131 +0,0 @@
-import {
-  CollectibleType,
-  ItemConfigTag,
-  PlayerForm,
-} from "isaac-typescript-definitions";
-import { 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 {
-  return TRANSFORMATION_NAMES[playerForm];
-}
-
-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/functions/trinketCacheFlag.ts

@@ -1,60 +0,0 @@
-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/functions/trinketGive.ts

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