isaacscript-common 4.0.2 → 4.0.5

package/features/taintedLazarusPlayers.ts

@@ -1,113 +0,0 @@
-// This feature provides a way for end-users to get the `EntityPlayer` object for the other Tainted
-// Lazarus.
-
-import { ModCallback, PlayerType } from "isaac-typescript-definitions";
-import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
-import { saveDataManager } from "./saveDataManager/exports";
-
-const FEATURE_NAME = "Tainted Lazarus entity finder";
-
-const v = {
-  run: {
-    queuedTaintedLazarus: [] as EntityPtr[],
-    queuedDeadTaintedLazarus: [] as EntityPtr[],
-
-    /**
-     * The PostPlayerInit callback fires for Dead Tainted Lazarus at the beginning of the run.
-     * However, the player index for the Dead Tainted Lazarus player object at that time does not
-     * actually correspond to the player index for the real player once Flip has been used. Thus, we
-     * revert to using PtrHash as an index for our map, which is consistent between the Dead Tainted
-     * Lazarus object in the PostPlayerInit callback and the "real" Dead Tainted Lazarus.
-     */
-    subPlayerMap: new Map<PtrHash, EntityPtr>(),
-  },
-};
-
-/** @internal */
-export function taintedLazarusPlayersInit(mod: Mod): void {
-  saveDataManager("taintedLazarusPlayers", v, () => false);
-
-  mod.AddCallback(ModCallback.POST_PLAYER_INIT, postPlayerInit);
-}
-
-// ModCallback.POST_PLAYER_INIT (9)
-function postPlayerInit(player: EntityPlayer) {
-  const entityPtr = EntityPtr(player);
-  const character = player.GetPlayerType();
-
-  if (character === PlayerType.LAZARUS_B) {
-    v.run.queuedTaintedLazarus.push(entityPtr);
-  } else if (character === PlayerType.LAZARUS_2_B) {
-    v.run.queuedDeadTaintedLazarus.push(entityPtr);
-  } else {
-    return;
-  }
-
-  checkDequeue();
-}
-
-/**
- * When starting a run, the PostPlayerInit callback will fire first for Dead Tainted Lazarus, then
- * for Tainted Lazarus. When continuing a run, the PostPlayerInit callback will fire first for the
- * character that is currently active. Thus, since the order of the characters is not certain, we
- * insert each of their pointers into a queue, and then only populate the map when we have one
- * Tainted Lazarus and one Dead Tainted Lazarus.
- */
-function checkDequeue() {
-  if (
-    v.run.queuedTaintedLazarus.length === 0 ||
-    v.run.queuedDeadTaintedLazarus.length === 0
-  ) {
-    return;
-  }
-
-  const taintedLazarusPtr = v.run.queuedTaintedLazarus.shift();
-  const deadTaintedLazarusPtr = v.run.queuedDeadTaintedLazarus.shift();
-
-  if (taintedLazarusPtr === undefined || deadTaintedLazarusPtr === undefined) {
-    return;
-  }
-
-  const taintedLazarus = taintedLazarusPtr.Ref;
-  const deadTaintedLazarus = deadTaintedLazarusPtr.Ref;
-
-  if (taintedLazarus === undefined || deadTaintedLazarus === undefined) {
-    return;
-  }
-
-  const taintedLazarusPtrHash = GetPtrHash(taintedLazarus);
-  const deadTaintedLazarusPtrHash = GetPtrHash(deadTaintedLazarus);
-
-  v.run.subPlayerMap.set(taintedLazarusPtrHash, deadTaintedLazarusPtr);
-  v.run.subPlayerMap.set(deadTaintedLazarusPtrHash, taintedLazarusPtr);
-}
-
-/**
- * Helper function to get the other version of Tainted Lazarus.
- *
- * - On Tainted Lazarus, returns the player object for Dead Tainted Lazarus.
- * - On Dead Tainted Lazarus, returns the player object for Tainted Lazarus.
- * - Returns undefined if player object retrieval failed for any reason.
- *
- * If you call the `EntityPlayer.Exists` method on the returned object, it will return false.
- * However, you can still call the other methods like you normally would (e.g.
- * `EntityPlayer.AddCollectible`).
- */
-export function getTaintedLazarusSubPlayer(
-  player: EntityPlayer,
-): EntityPlayer | undefined {
-  errorIfFeaturesNotInitialized(FEATURE_NAME);
-
-  const ptrHash = GetPtrHash(player);
-  const entityPtr = v.run.subPlayerMap.get(ptrHash);
-  if (entityPtr === undefined) {
-    return undefined;
-  }
-
-  const entity = entityPtr.Ref;
-  if (entity === undefined) {
-    return undefined;
-  }
-
-  return entity.ToPlayer();
-}

package/featuresInitialized.ts

@@ -1,20 +0,0 @@
-let featuresInitialized = false;
-
-/** @internal */
-export function areFeaturesInitialized(): boolean {
-  return featuresInitialized;
-}
-
-/** @internal */
-export function errorIfFeaturesNotInitialized(featureName: string): void {
-  if (!areFeaturesInitialized()) {
-    error(
-      `The ${featureName} is not initialized. You must first upgrade your mod object by calling the "upgradeMod" function.`,
-    );
-  }
-}
-
-/** @internal */
-export function setFeaturesInitialized(): void {
-  featuresInitialized = true;
-}

package/functions/ambush.ts

@@ -1,47 +0,0 @@
-import { PickupVariant } from "isaac-typescript-definitions";
-import { runNextGameFrame } from "../features/runInNFrames";
-import { removeEntities } from "./entity";
-import { spawnPickupWithSeed } from "./entitySpecific";
-import { getCoins } from "./pickups";
-
-/** Hard-coding this makes it easier to clean up the pickups afterwards. */
-const SACK_SEED_THAT_SPAWNS_TWO_COINS = 6 as Seed;
-
-/**
- * Helper function to start a Challenge Room or the Boss Rush.
- *
- * Specifically, this is performed by spawning a sack on top of the player, waiting a game frame,
- * and then removing the sack and the pickups that the sack dropped.
- */
-export function startAmbush(): void {
-  const player = Isaac.GetPlayer();
-  const sack = spawnPickupWithSeed(
-    PickupVariant.SACK,
-    0,
-    player.Position,
-    SACK_SEED_THAT_SPAWNS_TWO_COINS,
-  );
-
-  // The sack will play the "Appear" animation and the player will not be able to interact with it
-  // while this is occurring. By stopping the animation, it will transition to the "Idle" animation
-  // and be interactable on the next game frame.
-  const sprite = sack.GetSprite();
-  sprite.Stop();
-  const sackPtr = EntityPtr(sack);
-  runNextGameFrame(() => {
-    const futureSack = sackPtr.Ref;
-    if (futureSack === undefined) {
-      return;
-    }
-
-    futureSack.Remove();
-    const sackPtrHash = GetPtrHash(futureSack);
-    const coins = getCoins();
-    const coinsFromSack = coins.filter(
-      (pickup) =>
-        pickup.SpawnerEntity !== undefined &&
-        GetPtrHash(pickup.SpawnerEntity) === sackPtrHash,
-    );
-    removeEntities(coinsFromSack);
-  });
-}

package/functions/array.ts

@@ -1,410 +0,0 @@
-import { getRandomInt } from "./random";
-import { getRandomSeed, isRNG, newRNG } from "./rng";
-import { isNumber, isTable } from "./types";
-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 true if 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 true if 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;
-}
-
-/** Helper function to remove all of the elements in an array in-place. */
-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 (!isTable(object)) {
-    return false;
-  }
-
-  // First, if there is a metatable, this cannot be a simple array and must be a more complex
-  // object.
-  const metatable = getmetatable(object);
-  if (metatable !== undefined) {
-    return false;
-  }
-
-  // Second, handle the case of non-numerical keys.
-  const keys = Object.keys(object);
-  const hasAllNumberKeys = keys.every((key) => isNumber(key));
-  if (!hasAllNumberKeys) {
-    return false;
-  }
-
-  const tableLength = object.length();
-  if (tableLength === 0) {
-    return true;
-  }
-
-  // Third, check for non-contiguous elements. (Lua tables start at an index of 1.)
-  for (let i = 1; i <= tableLength; i++) {
-    const element = object.get(i) as unknown;
-    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/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/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/functions/bombs.ts

@@ -1,12 +0,0 @@
-/** Helper function to find out how large a bomb explosion is based on the damage inflicted. */
-export function getBombRadiusFromDamage(damage: float): float {
-  if (damage > 175) {
-    return 105;
-  }
-
-  if (damage <= 140) {
-    return 75;
-  }
-
-  return 90;
-}