isaacscript-common 2.2.0 → 2.3.0

package/src/functions/array.ts

@@ -0,0 +1,412 @@
+import { getRandomInt } from "./random";
+import { getRandomSeed, isRNG, newRNG } from "./rng";
+import { erange, repeat } from "./utils";
+
+/**
+ * Helper function for determining if two arrays contain the exact same elements. Note that this
+ * only performs a shallow comparison.
+ */
+export function arrayEquals<T>(
+  array1: T[] | readonly T[],
+  array2: T[] | readonly T[],
+): boolean {
+  if (array1.length !== array2.length) {
+    return false;
+  }
+
+  return array1.every((array1Element, i) => {
+    const array2Element = array2[i];
+    return array1Element === array2Element;
+  });
+}
+
+/**
+ * Shallow copies and removes the specified element(s) from the array. Returns the copied array. If
+ * the specified element(s) are not found in the array, it will simply return a shallow copy of the
+ * array.
+ *
+ * This function is variadic, meaning that you can specify N arguments to remove N elements.
+ */
+export function arrayRemove<T>(
+  originalArray: T[] | readonly T[],
+  ...elementsToRemove: T[]
+): T[] {
+  const elementsToRemoveSet = new Set(elementsToRemove);
+
+  const array: T[] = [];
+  for (const element of originalArray) {
+    if (!elementsToRemoveSet.has(element)) {
+      array.push(element);
+    }
+  }
+
+  return array;
+}
+
+/**
+ * Removes the specified element(s) from the array. If the specified element(s) are not found in the
+ * array, this function will do nothing. Returns whether or not one or more elements were removed.
+ *
+ * This function is variadic, meaning that you can specify N arguments to remove N elements.
+ */
+export function arrayRemoveInPlace<T>(
+  array: T[],
+  ...elementsToRemove: T[]
+): boolean {
+  let removedOneOrMoreElements = false;
+  for (const element of elementsToRemove) {
+    const index = array.indexOf(element);
+    if (index > -1) {
+      removedOneOrMoreElements = true;
+      array.splice(index, 1);
+    }
+  }
+
+  return removedOneOrMoreElements;
+}
+
+/**
+ * Shallow copies and removes the elements at the specified indexes from the array. Returns the
+ * copied array. If the specified indexes are not found in the array, it will simply return a
+ * shallow copy of the array.
+ *
+ * This function is variadic, meaning that you can specify N arguments to remove N elements.
+ */
+export function arrayRemoveIndex<T>(
+  originalArray: T[] | readonly T[],
+  ...indexesToRemove: int[]
+): T[] {
+  const indexesToRemoveSet = new Set(indexesToRemove);
+
+  const array: T[] = [];
+  originalArray.forEach((element, i) => {
+    if (!indexesToRemoveSet.has(i)) {
+      array.push(element);
+    }
+  });
+
+  return array;
+}
+
+/**
+ * Removes the elements at the specified indexes from the array. If the specified indexes are not
+ * found in the array, this function will do nothing. Returns whether or not one or more elements
+ * were removed.
+ *
+ * This function is variadic, meaning that you can specify N arguments to remove N elements.
+ */
+export function arrayRemoveIndexInPlace<T>(
+  array: T[],
+  ...indexesToRemove: int[]
+): boolean {
+  const legalIndexes = indexesToRemove.filter(
+    (i) => i >= 0 && i < array.length,
+  );
+  legalIndexes.sort();
+
+  if (legalIndexes.length === 0) {
+    return false;
+  }
+
+  for (let i = array.length - 1; i >= 0; i--) {
+    array.splice(i, 1);
+  }
+
+  return true;
+}
+
+export function arrayToString<T>(array: T[]): string {
+  if (array.length === 0) {
+    return "[]";
+  }
+
+  const strings = array.map((element) => tostring(element));
+  const commaSeparatedStrings = strings.join(", ");
+  return `[${commaSeparatedStrings}]`;
+}
+
+/**
+ * Helper function to combine two or more arrays. Returns a new array that is the composition of all
+ * of the specified arrays.
+ *
+ * This function is variadic, meaning that you can specify N arguments to combine N arrays. Note
+ * that this will only perform a shallow copy of the array elements.
+ */
+export function combineArrays<T>(...arrays: Array<T[] | readonly T[]>): T[] {
+  const elements: T[] = [];
+  for (const array of arrays) {
+    for (const element of array) {
+      elements.push(element);
+    }
+  }
+
+  return elements;
+}
+
+/**
+ * Helper function to perform a shallow copy.
+ *
+ * @param oldArray The array to copy.
+ * @param numElements Optional. If specified, will only copy the first N elements. By default, the
+ *                    entire array will be copied.
+ */
+export function copyArray<T>(
+  oldArray: T[] | readonly T[],
+  numElements?: int,
+): T[] {
+  if (numElements === undefined) {
+    numElements = oldArray.length;
+  }
+
+  const newArray: T[] = [];
+  for (let i = 0; i < numElements; i++) {
+    const oldElement = oldArray[i];
+    if (oldElement !== undefined) {
+      newArray.push(oldElement);
+    }
+  }
+
+  return newArray;
+}
+
+export function emptyArray<T>(array: T[]): void {
+  array.splice(0, array.length);
+}
+
+/**
+ * Helper function to get an array containing the indexes of an array.
+ *
+ * For example, an array of `["Apple", "Banana"]` would return an array of `[0, 1]`.
+ */
+export function getArrayIndexes<T>(array: T[] | readonly T[]): int[] {
+  return erange(array.length);
+}
+
+/**
+ * Helper function to return the last element of an array.
+ *
+ * If the array is empty, this will return undefined.
+ */
+export function getLastElement<T>(array: T[]): T | undefined {
+  return array[array.length - 1];
+}
+
+/**
+ * Helper function to get a random element from the provided array.
+ *
+ * @param array The array to get an element 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 getRandomArrayElement<T>(
+  array: T[] | readonly T[],
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+  exceptions: T[] | readonly T[] = [],
+): T {
+  if (array.length === 0) {
+    error(
+      "Failed to get a random array element since the provided array is empty.",
+    );
+  }
+
+  const arrayWithoutExceptions = arrayRemove(array, ...exceptions);
+  const randomIndex = getRandomArrayIndex(arrayWithoutExceptions, seedOrRNG);
+  const randomElement = arrayWithoutExceptions[randomIndex];
+  if (randomElement === undefined) {
+    error(
+      `Failed to get a random array element since the random index of ${randomIndex} was not valid.`,
+    );
+  }
+
+  return randomElement;
+}
+
+/**
+ * Helper function to get a random element from the provided array. Once the random element is
+ * decided, it is then removed from the array (in-place).
+ *
+ * @param array The array to get an element 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 getRandomArrayElementAndRemove<T>(
+  array: T[],
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+  exceptions: T[] | readonly T[] = [],
+): T {
+  const randomArrayElement = getRandomArrayElement(
+    array,
+    seedOrRNG,
+    exceptions,
+  );
+  arrayRemoveInPlace(array, randomArrayElement);
+  return randomArrayElement;
+}
+
+/**
+ * Helper function to get a random index from the provided array.
+ *
+ * @param array The array to get the index 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()`.
+ */
+export function getRandomArrayIndex<T>(
+  array: T[] | readonly T[],
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+): int {
+  if (array.length === 0) {
+    error(
+      "Failed to get a random array index since the provided array is empty.",
+    );
+  }
+
+  return getRandomInt(0, array.length - 1, seedOrRNG);
+}
+
+/**
+ * Initializes an array with all elements containing the specified default value.
+ *
+ * For example:
+ *
+ * ```ts
+ * const playerTransformations = initArray(false, PlayerForm.NUM_PLAYER_FORMS - 1);
+ * ```
+ */
+export function initArray<T>(defaultValue: T, size: int): T[] {
+  const array: T[] = [];
+  repeat(size, () => {
+    array.push(defaultValue);
+  });
+
+  return array;
+}
+
+/**
+ * Since Lua uses tables for every non-primitive data structure, it is non-trivial to determine if a
+ * particular table is being used as an array. `isArray` returns true if:
+ *
+ * - the table contains all numerical indexes that are contiguous, starting at 1
+ * - the table has no keys (i.e. an "empty" table)
+ */
+export function isArray(object: unknown): object is unknown[] {
+  if (type(object) !== "table") {
+    return false;
+  }
+
+  const table = object as LuaTable<AnyNotNil, unknown>;
+
+  // First, if there is a metatable, this cannot be a simple array and must be a more complex
+  // object.
+  const metatable = getmetatable(table);
+  if (metatable !== undefined) {
+    return false;
+  }
+
+  // Second, handle the case of non-numerical keys (and count the entries in the table).
+  let numEntries = 0;
+  for (const [key] of pairs(table)) {
+    numEntries += 1;
+
+    if (typeof key !== "number") {
+      return false;
+    }
+  }
+
+  if (numEntries === 0) {
+    return true;
+  }
+
+  // Third, check for non-contiguous elements. (Lua tables start at an index of 1.)
+  for (let i = 1; i <= numEntries; i++) {
+    const element = table.get(i);
+    if (element === undefined) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Helper function to see if every element in the array is N + 1.
+ *
+ * For example, `[2, 3, 4]` would return true, and `[2, 3, 5]` would return false.
+ */
+export function isArrayContiguous(array: int[]): boolean {
+  let lastValue: int | undefined;
+  for (const element of array) {
+    if (lastValue === undefined) {
+      lastValue = element - 1;
+    }
+
+    if (element !== lastValue - 1) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/** Checks if an array is in the provided 2-dimensional array. */
+export function isArrayInArray<T>(
+  arrayToMatch: T[] | readonly T[],
+  parentArray: Array<T[] | readonly T[]>,
+): boolean {
+  return parentArray.some((element) => arrayEquals(element, arrayToMatch));
+}
+
+/**
+ * Shallow copies and shuffles the array using the Fisher-Yates algorithm. Returns the copied array.
+ *
+ * From: https://stackoverflow.com/questions/2450954/how-to-randomize-shuffle-a-javascript-array
+ *
+ * @param originalArray The array to shuffle.
+ * @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()`.
+ */
+export function shuffleArray<T>(
+  originalArray: T[] | readonly T[],
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+): T[] {
+  const array = copyArray(originalArray);
+  shuffleArrayInPlace(array, seedOrRNG);
+
+  return array;
+}
+
+/**
+ * Shuffles the provided array in-place using the Fisher-Yates algorithm.
+ *
+ * From: https://stackoverflow.com/questions/2450954/how-to-randomize-shuffle-a-javascript-array
+ *
+ * @param array The array to shuffle.
+ * @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()`.
+ */
+export function shuffleArrayInPlace<T>(
+  array: T[],
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+): void {
+  let currentIndex = array.length;
+  let randomIndex: int;
+
+  const rng = isRNG(seedOrRNG) ? seedOrRNG : newRNG(seedOrRNG);
+
+  while (currentIndex > 0) {
+    currentIndex -= 1;
+
+    randomIndex = getRandomArrayIndex(array, rng);
+
+    // @ts-expect-error The shuffle can never be undefined.
+    [array[currentIndex], array[randomIndex]] = [
+      array[randomIndex],
+      array[currentIndex],
+    ];
+  }
+}
+
+export function sumArray(array: number[] | readonly number[]): number {
+  return array.reduce((accumulator, element) => accumulator + element);
+}

package/src/functions/benchmark.ts

@@ -0,0 +1,36 @@
+import { log } from "./log";
+
+/**
+ * Helper function to benchmark the performance of a function.
+ *
+ * This function is variadic, which means that you can supply as many as you want to benchmark.
+ *
+ * @returns An array containing the average time in milliseconds for each function. (This will also
+ *          be printed to the log.)
+ */
+export function benchmark(
+  numTrials: int,
+  ...functions: Array<() => void>
+): int[] {
+  log(`Benchmarking ${functions.length} function(s) with ${numTrials} trials.`);
+
+  const averages: int[] = [];
+  functions.forEach((func, i) => {
+    let totalTimeMilliseconds = 0;
+    for (let j = 0; j < numTrials; j++) {
+      const startTimeMilliseconds = Isaac.GetTime();
+      func();
+      const endTimeMilliseconds = Isaac.GetTime();
+      const elapsedTimeMilliseconds =
+        endTimeMilliseconds - startTimeMilliseconds;
+      totalTimeMilliseconds += elapsedTimeMilliseconds;
+    }
+    const averageTimeMilliseconds = totalTimeMilliseconds / numTrials;
+    log(
+      `The average time of the function at index ${i} is: ${averageTimeMilliseconds} milliseconds`,
+    );
+    averages.push(averageTimeMilliseconds);
+  });
+
+  return averages;
+}

package/src/functions/bitwise.ts

@@ -0,0 +1,24 @@
+export function countSetBits(n: int): int {
+  let count = 0;
+
+  while (n > 0) {
+    n &= n - 1;
+    count += 1;
+  }
+
+  return count;
+}
+
+export function getKBitOfN(k: int, n: int): int {
+  return (n >>> k) & 1;
+}
+
+export function getNumBitsOfN(n: int): int {
+  let numBits = 0;
+  while (n > 0) {
+    numBits += 1;
+    n >>>= 1;
+  }
+
+  return numBits;
+}

package/src/functions/boss.ts

@@ -0,0 +1,227 @@
+import {
+  EntityType,
+  LokiVariant,
+  StageType,
+} from "isaac-typescript-definitions";
+import { VectorZero } from "../constants";
+import {
+  ALL_BOSSES_SET,
+  STAGE_TO_COMBINED_BOSS_SET_MAP,
+  STAGE_TO_STAGE_TYPE_TO_BOSS_SET_MAP,
+} from "../sets/bossSets";
+import { SIN_ENTITY_TYPES_SET } from "../sets/sinEntityTypesSet";
+import { getNPCs, spawnNPC } from "./entitySpecific";
+import { getAliveNPCs } from "./npc";
+import { copySet } from "./set";
+import { repeat } from "./utils";
+
+const BOSSES_THAT_REQUIRE_MULTIPLE_SPAWNS: ReadonlySet<EntityType> = new Set([
+  EntityType.LARRY_JR, // 19 (and The Hollow / Tuff Twins / The Shell)
+  EntityType.CHUB, // 28 (and C.H.A.D. / The Carrion Queen)
+  EntityType.LOKI, // 69 (only for Lokii)
+  EntityType.GURGLING, // 237 (and Turdling)
+  EntityType.TURDLET, // 918
+]);
+
+const DEFAULT_BOSS_MULTI_SEGMENTS = 4;
+
+/**
+ * Helper function to get all of the non-dead bosses in the room.
+ *
+ * This function will not include bosses on an internal blacklist, such as Death's scythes or Big
+ * Horn holes.
+ */
+export function getAliveBosses(
+  matchingEntityType?: EntityType,
+  matchingVariant?: int,
+  matchingSubType?: int,
+  ignoreFriendly = false,
+): EntityNPC[] {
+  const aliveNPCs = getAliveNPCs(
+    matchingEntityType,
+    matchingVariant,
+    matchingSubType,
+    ignoreFriendly,
+  );
+  return aliveNPCs.filter((aliveNPC) => aliveNPC.IsBoss());
+}
+
+/**
+ * Helper function to get the set of every boss in the game.
+ *
+ * The set contains strings with the entity type and variant, separated by a period.
+ *
+ * Also see the `getBossSet` and `getCombinedBossSet` functions.
+ */
+export function getAllBossesSet(): Set<string> {
+  return copySet(ALL_BOSSES_SET);
+}
+
+/**
+ * Helper function to get the set of vanilla bosses for a particular stage and stage type
+ * combination.
+ *
+ * The set contains strings with the entity type and variant, separated by a period.
+ *
+ * Also see the `getAllBossesSet` and `getCombinedBossSet` functions.
+ */
+export function getBossSet(
+  stage: int,
+  stageType: StageType,
+): ReadonlySet<string> | undefined {
+  const stageTypeMap = STAGE_TO_STAGE_TYPE_TO_BOSS_SET_MAP.get(stage);
+  if (stageTypeMap === undefined) {
+    return undefined;
+  }
+
+  const bossSet = stageTypeMap.get(stageType);
+  if (bossSet === undefined) {
+    return undefined;
+  }
+
+  return copySet(bossSet);
+}
+
+/** Helper function to get all of the bosses in the room. */
+export function getBosses(
+  matchingEntityType?: EntityType,
+  matchingVariant?: int,
+  matchingSubType?: int,
+  ignoreFriendly = false,
+): EntityNPC[] {
+  const npcs = getNPCs(
+    matchingEntityType,
+    matchingVariant,
+    matchingSubType,
+    ignoreFriendly,
+  );
+  return npcs.filter((npc) => npc.IsBoss());
+}
+
+/**
+ * Helper function to get the set of vanilla bosses for a particular stage across all of the stage
+ * types. For example, specifying a stage of 2 will return a set with all of the bosses for
+ * Basement, Cellar, Burning Basement, Downpour, and Dross.
+ *
+ * The set contains strings with the entity type and variant, separated by a period.
+ *
+ * Also see the `getAllBossesSet` and `getBossSet` functions.
+ */
+export function getCombinedBossSet(stage: int): Set<string> | undefined {
+  const bossSet = STAGE_TO_COMBINED_BOSS_SET_MAP.get(stage);
+  if (bossSet === undefined) {
+    return undefined;
+  }
+
+  return copySet(bossSet);
+}
+
+/** Helper function to check if the provided NPC is a Sin miniboss, such as Sloth or Lust. */
+export function isSin(npc: EntityNPC): boolean {
+  return SIN_ENTITY_TYPES_SET.has(npc.Type);
+}
+
+/**
+ * Helper function to spawn a boss.
+ *
+ * Use this function instead of `spawnNPC` since it handles automatically spawning multiple segments
+ * for multi-segment bosses.
+ *
+ * By default, this will spawn Chub (and his variants) with 3 segments, Lokii with 2 copies,
+ * Gurglings/Turdlings with 2 copies, and other multi-segment bosses with 4 segments. You can
+ * customize this via the "numSegments" argument.
+ */
+export function spawnBoss(
+  entityType: EntityType,
+  variant: int,
+  subType: int,
+  position: Vector,
+  velocity = VectorZero,
+  spawner: Entity | undefined = undefined,
+  seed: Seed | undefined = undefined,
+  numSegments?: int,
+): EntityNPC {
+  const npc = spawnNPC(
+    entityType,
+    variant,
+    subType,
+    position,
+    velocity,
+    spawner,
+    seed,
+  );
+
+  if (BOSSES_THAT_REQUIRE_MULTIPLE_SPAWNS.has(entityType)) {
+    const numBossSegments = getNumBossSegments(
+      entityType,
+      variant,
+      numSegments,
+    );
+    const remainingSegmentsToSpawn = numBossSegments - 1;
+    repeat(remainingSegmentsToSpawn, () => {
+      spawnNPC(entityType, variant, subType, position, velocity, spawner, seed);
+    });
+  }
+
+  return npc;
+}
+
+function getNumBossSegments(
+  entityType: EntityType,
+  variant: int,
+  numSegments: int | undefined,
+) {
+  if (numSegments !== undefined) {
+    return numSegments;
+  }
+
+  switch (entityType) {
+    // 28
+    case EntityType.CHUB: {
+      // Chub is always composed of 3 segments.
+      return 3;
+    }
+
+    // 69
+    case EntityType.LOKI: {
+      return (variant as LokiVariant) === LokiVariant.LOKII ? 2 : 1;
+    }
+
+    // 237
+    case EntityType.GURGLING: {
+      // Gurglings & Turdlings are always encountered in groups of 2.
+      return 2;
+    }
+
+    default: {
+      return DEFAULT_BOSS_MULTI_SEGMENTS;
+    }
+  }
+}
+
+/**
+ * Helper function to spawn a boss with a specific seed.
+ *
+ * For more information, see the documentation for the `spawnBoss` function.
+ */
+export function spawnBossWithSeed(
+  entityType: EntityType,
+  variant: int,
+  subType: int,
+  position: Vector,
+  seed: Seed,
+  velocity = VectorZero,
+  spawner: Entity | undefined = undefined,
+  numSegments?: int,
+): EntityNPC {
+  return spawnBoss(
+    entityType,
+    variant,
+    subType,
+    position,
+    velocity,
+    spawner,
+    seed,
+    numSegments,
+  );
+}

package/src/functions/cacheFlag.ts

@@ -0,0 +1,12 @@
+import { CacheFlag } from "isaac-typescript-definitions";
+import { DEFAULT_PLAYER_STAT_MAP } from "../maps/defaultPlayerStatMap";
+
+/**
+ * Returns the starting stat that Isaac (the default character) starts with. For example, if you
+ * pass this function `CacheFlag.DAMAGE`, it will return 3.5.
+ *
+ * Note that the default fire delay is represented in the tear stat, not the `MaxFireDelay` value.
+ */
+export function getDefaultPlayerStat(cacheFlag: CacheFlag): number | undefined {
+  return DEFAULT_PLAYER_STAT_MAP.get(cacheFlag);
+}