isaacscript-common 2.3.0 → 2.3.1

package/src/functions/array.ts

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

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

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

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

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