isaacscript-common 2.3.0 → 3.0.0

package/src/functions/seeds.ts

@@ -1,19 +0,0 @@
-import { game } from "../cachedClasses";
-import { newRNG } from "./rng";
-
-/** Alias for the `Seeds.GetStartSeedString` method. */
-export function getStartSeedString(): string {
-  const seeds = game.GetSeeds();
-  return seeds.GetStartSeedString();
-}
-
-/**
- * Helper function to get the next seed value.
- *
- * This function is useful when you are working with seed values directly over RNG objects.
- */
-export function nextSeed(seed: Seed): Seed {
-  const rng = newRNG(seed);
-  rng.Next();
-  return rng.GetSeed();
-}

package/src/functions/serialization.ts

@@ -1,97 +0,0 @@
-import { CopyableIsaacAPIClassType } from "../enums/private/CopyableIsaacAPIClassType";
-import { SerializationType } from "../enums/SerializationType";
-import { ISAAC_API_CLASS_TYPE_TO_BRAND } from "../objects/isaacAPIClassTypeToBrand";
-import { ISAAC_API_CLASS_TYPE_TO_COPY_FUNCTION } from "../objects/isaacAPIClassTypeToCopyFunction";
-import { SERIALIZED_ISAAC_API_CLASS_TYPE_TO_IDENTITY_FUNCTION } from "../objects/serializedIsaacAPIClassTypeToIdentityFunction";
-import { SerializedIsaacAPIClass } from "../types/private/SerializedIsaacAPIClass";
-import { getIsaacAPIClassType } from "./isaacAPIClass";
-
-export function copyIsaacAPIClass(
-  isaacAPIClass: unknown,
-  serializationType: SerializationType,
-): unknown {
-  const objectType = type(isaacAPIClass);
-  if (objectType !== "userdata") {
-    error(
-      `Failed to copy an Isaac API class since the provided object was of type: ${objectType}`,
-    );
-  }
-
-  const isaacAPIClassType = getIsaacAPIClassType(isaacAPIClass);
-  if (isaacAPIClassType === undefined) {
-    error(
-      "Failed to copy an Isaac API class since it does not have a class type.",
-    );
-  }
-
-  const copyableIsaacAPIClassType =
-    isaacAPIClassType as CopyableIsaacAPIClassType;
-  const copyFunction =
-    ISAAC_API_CLASS_TYPE_TO_COPY_FUNCTION[copyableIsaacAPIClassType];
-  if (copyFunction === undefined) {
-    error(
-      `Failed to copy Isaac API class "${copyableIsaacAPIClassType}" since there is not a defined copy function for this class type.`,
-    );
-  }
-
-  return copyFunction(isaacAPIClass, serializationType);
-}
-
-/**
- * Deserialization is a special case, so we make a dedicated function for this.
- *
- * There is no need for a corresponding "serializeIsaacAPIClass" function because the
- * "copyIsaacAPIClass" function can handles all serialization types.
- */
-export function deserializeIsaacAPIClass(
-  serializedIsaacAPIClass: SerializedIsaacAPIClass,
-): unknown {
-  const objectType = type(serializedIsaacAPIClass);
-  if (objectType !== "table") {
-    error(
-      `Failed to deserialize an Isaac API class since the provided object was of type: ${objectType}`,
-    );
-  }
-
-  const copyableIsaacAPIClassType = getSerializedTableType(
-    serializedIsaacAPIClass,
-  );
-  if (copyableIsaacAPIClassType === undefined) {
-    error(
-      "Failed to deserialize an API class since a valid class type brand was not found.",
-    );
-  }
-
-  const copyFunction =
-    ISAAC_API_CLASS_TYPE_TO_COPY_FUNCTION[copyableIsaacAPIClassType];
-  if (copyFunction === undefined) {
-    error(
-      `Failed to deserialize Isaac API class "${copyableIsaacAPIClassType}" since there is not a defined copy function for this class type.`,
-    );
-  }
-
-  return copyFunction(serializedIsaacAPIClass, SerializationType.DESERIALIZE);
-}
-
-function getSerializedTableType(
-  serializedIsaacAPIClass: SerializedIsaacAPIClass,
-): CopyableIsaacAPIClassType | undefined {
-  for (const [copyableIsaacAPIClassType, serializationBrand] of Object.entries(
-    ISAAC_API_CLASS_TYPE_TO_BRAND,
-  )) {
-    if (serializedIsaacAPIClass.has(serializationBrand)) {
-      return copyableIsaacAPIClassType as CopyableIsaacAPIClassType;
-    }
-  }
-
-  return undefined;
-}
-
-export function isSerializedIsaacAPIClass(
-  object: unknown,
-): object is SerializedIsaacAPIClass {
-  const identityFunctions = Object.values(
-    SERIALIZED_ISAAC_API_CLASS_TYPE_TO_IDENTITY_FUNCTION,
-  );
-  return identityFunctions.some((identityFunction) => identityFunction(object));
-}

package/src/functions/set.ts

@@ -1,95 +0,0 @@
-import { getRandomArrayElement } from "./array";
-import { getRandomSeed } from "./rng";
-
-/**
- * Helper function to add all of the values in one set to another set. The first set passed will be
- * modified in place.
- *
- * This function is variadic, meaning that you can specify N sets to add to the first set.
- */
-export function addSetsToSet<T>(
-  mainSet: Set<T>,
-  ...setsToAdd: Array<Set<T> | ReadonlySet<T>>
-): void {
-  for (const set of setsToAdd) {
-    for (const value of set.values()) {
-      mainSet.add(value);
-    }
-  }
-}
-
-/**
- * Helper function to create a new set that is the composition of two or more sets.
- *
- * This function is variadic, meaning that you can specify N sets.
- */
-export function combineSets<T>(
-  ...sets: Array<Set<T> | ReadonlySet<T>>
-): Set<T> {
-  const newSet = new Set<T>();
-  for (const set of sets) {
-    for (const value of set.values()) {
-      newSet.add(value);
-    }
-  }
-
-  return newSet;
-}
-
-/** Helper function to copy a set. (You can also use a Set constructor to accomplish this task.) */
-export function copySet<T>(oldSet: Set<T> | ReadonlySet<T>): Set<T> {
-  const newSet = new Set<T>();
-  for (const value of oldSet.values()) {
-    newSet.add(value);
-  }
-
-  return newSet;
-}
-
-/**
- * Helper function to delete all of the values in one set from another set. The first set passed
- * will be modified in place.
- *
- * This function is variadic, meaning that you can specify N sets to remove from the first set.
- */
-export function deleteSetsFromSet<T>(
-  mainSet: Set<T>,
-  ...setsToRemove: Array<Set<T> | ReadonlySet<T>>
-): void {
-  for (const set of setsToRemove) {
-    for (const value of set.values()) {
-      mainSet.delete(value);
-    }
-  }
-}
-
-/**
- * Helper function to get a random element from the provided set.
- *
- * @param set The set 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 getRandomSetElement<T>(
-  set: Set<T> | ReadonlySet<T>,
-  seedOrRNG: Seed | RNG = getRandomSeed(),
-  exceptions: T[] | readonly T[] = [],
-): T {
-  const array = getSortedSetValues(set);
-  return getRandomArrayElement(array, seedOrRNG, exceptions);
-}
-
-/**
- * Helper function to get a sorted array based on the contents of a set.
- *
- * Normally, set values are returned in a random order, so use this function when the ordering of
- * the contents is important.
- */
-export function getSortedSetValues<T>(set: Set<T> | ReadonlySet<T>): T[] {
-  const values = set.values();
-  const array = [...values];
-  array.sort();
-
-  return array;
-}

package/src/functions/sound.ts

@@ -1,9 +0,0 @@
-import { SoundEffect } from "isaac-typescript-definitions";
-import { sfxManager } from "../cachedClasses";
-import { getEnumValues } from "./enums";
-
-export function stopAllSoundEffects(): void {
-  for (const soundEffect of getEnumValues(SoundEffect)) {
-    sfxManager.Stop(soundEffect);
-  }
-}

package/src/functions/spawnCollectible.ts

@@ -1,104 +0,0 @@
-import {
-  CollectibleType,
-  PickupPrice,
-  PickupVariant,
-  PlayerType,
-} from "isaac-typescript-definitions";
-import { VectorZero } from "../constants";
-import { preventCollectibleRotation } from "../features/preventCollectibleRotation";
-import { areFeaturesInitialized } from "../featuresInitialized";
-import { setCollectibleEmpty } from "./collectibles";
-import { isQuestCollectible } from "./collectibleTag";
-import { spawnPickupWithSeed } from "./entitySpecific";
-import { anyPlayerIs } from "./player";
-import { getRandomSeed, isRNG } from "./rng";
-
-/**
- * Helper function to spawn a collectible. Use this instead of the `Game.Spawn` method because it
- * handles the cases of Tainted Keeper collectibles costing coins and preventing quest items from
- * being rotated by Tainted Isaac's rotation mechanic. (Rotation prevention will only occur in
- * upgraded mods.)
- *
- * @param collectibleType The collectible type to spawn.
- * @param position The position to spawn the collectible at.
- * @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 options Optional. Set to true to make the collectible a "There's Options" style
- *                collectible. Default is false.
- * @param forceFreeItem Optional. Set to true to disable the logic that gives the item a price for
- *                      Tainted Keeper. Default is false.
- * @param spawner Optional.
- */
-export function spawnCollectible(
-  collectibleType: CollectibleType,
-  position: Vector,
-  seedOrRNG: Seed | RNG = getRandomSeed(),
-  options = false,
-  forceFreeItem = false,
-  spawner?: Entity,
-): EntityPickupCollectible {
-  const seed = isRNG(seedOrRNG) ? seedOrRNG.Next() : seedOrRNG;
-  const collectible = spawnPickupWithSeed(
-    PickupVariant.COLLECTIBLE,
-    collectibleType,
-    position,
-    seed,
-    VectorZero,
-    spawner,
-  ) as EntityPickupCollectible;
-
-  if (options) {
-    collectible.OptionsPickupIndex = 1;
-  }
-
-  if (
-    anyPlayerIs(PlayerType.KEEPER_B) &&
-    !isQuestCollectible(collectibleType) &&
-    !forceFreeItem
-  ) {
-    // When playing Tainted Keeper, collectibles are supposed to have a price, and manually spawned
-    // items will not have a price, so we have to set it manually.
-
-    // Setting the shop item ID in this way prevents the bug where the item will sometimes change to
-    // 99 cents.
-    collectible.ShopItemId = -1;
-
-    // We can set the price to any arbitrary value; it will auto-update to the true price on the
-    // next frame.
-    collectible.Price = 15 as PickupPrice;
-  }
-
-  if (isQuestCollectible(collectibleType) && areFeaturesInitialized()) {
-    preventCollectibleRotation(collectible, collectibleType);
-  }
-
-  return collectible;
-}
-
-/**
- * Helper function to spawn an empty collectible. Doing this is tricky since spawning a collectible
- * with `CollectibleType.NULL` will result in spawning a collectible with a random type from the
- * current room's item pool.
- *
- * Instead, this function arbitrarily spawns a collectible with `CollectibleType.SAD_ONION`, and
- * then converts it to an empty pedestal afterward.
- *
- * @param position The position to spawn the empty collectible at.
- * @param seedOrRNG 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 spawnEmptyCollectible(
-  position: Vector,
-  seedOrRNG: Seed | RNG = getRandomSeed(),
-): EntityPickup {
-  const collectible = spawnCollectible(
-    CollectibleType.SAD_ONION,
-    position,
-    seedOrRNG,
-    false,
-    true,
-  );
-  setCollectibleEmpty(collectible);
-
-  return collectible;
-}

package/src/functions/sprite.ts

@@ -1,107 +0,0 @@
-import { EMPTY_PNG_PATH, VectorZero } from "../constants";
-import { kColorEquals } from "./kColor";
-import { erange } from "./utils";
-
-/**
- * Helper function to clear a specific layer from a sprite.
- *
- * This function is variadic, so pass as many layer IDs as you want to clear. If no specific layers
- * are passed, it will clear every layer.
- *
- * Since there is no official API method to "clear" a sprite, we can work around it by setting the
- * spritesheet to a non-existent or completely transparent file. If the path to the spritesheet does
- * not exist, then this function might cause spurious errors to appear in the "log.txt file". To
- * silence these errors, create a transparent 1 pixel PNG file in your mod's resources folder at the
- * path corresponding to the "EMPTY_PNG_PATH" constant.
- */
-export function clearSprite(sprite: Sprite, ...layerIDs: int[]): void {
-  if (layerIDs.length === 0) {
-    const numLayers = sprite.GetLayerCount();
-    layerIDs = erange(numLayers);
-  }
-
-  for (const layerID of layerIDs) {
-    sprite.ReplaceSpritesheet(layerID, EMPTY_PNG_PATH);
-  }
-
-  sprite.LoadGraphics();
-}
-
-/**
- * Helper function that returns the number of the final frame in a particular animation for a
- * sprite. By default, it will use the currently playing animation, but you can also specify a
- * specific animation to check.
- *
- * Note that this function is bugged with the Stop Watch or the Broken Watch, since using the
- * `Sprite.SetFrame` method will reset the internal accumulator used to slow down the playback speed
- * of the animation. (The `PlaybackSpeed` property of the sprite is not used.) Thus, it is only safe
- * to use this function on animations that are not slowed down by Stop Watch or Broken Watch, such
- * as player animations.
- */
-export function getLastFrameOfAnimation(
-  sprite: Sprite,
-  animation?: string,
-): int {
-  // Record the current sprite status.
-  const currentAnimation = sprite.GetAnimation();
-  const currentFrame = sprite.GetFrame();
-
-  // Get the final frame.
-  if (animation !== undefined && animation !== currentAnimation) {
-    sprite.SetAnimation(animation);
-  }
-  sprite.SetLastFrame();
-  const finalFrame = sprite.GetFrame();
-
-  // Set the sprite back to the way it was.
-  if (animation !== undefined && animation !== currentAnimation) {
-    sprite.Play(currentAnimation, true);
-  }
-  sprite.SetFrame(currentFrame);
-
-  return finalFrame;
-}
-
-/**
- * Helper function to check if two sprite layers have the same sprite sheet by using the
- * `Sprite.GetTexel` method.
- *
- * Since checking every single texel in the entire sprite is very expensive, this function requires
- * that you provide a range of specific texels to check.
- */
-export function spriteEquals(
-  sprite1: Sprite,
-  sprite2: Sprite,
-  layerID: int,
-  xStart: int,
-  xFinish: int,
-  xIncrement: int,
-  yStart: int,
-  yFinish: int,
-  yIncrement: int,
-): boolean {
-  // Iterate over N texels, checking for equality at each step. The center of the sprite is equal to
-  // the "pivot" point in the anm2 file.
-  for (let x = xStart; x <= xFinish; x += xIncrement) {
-    for (let y = yStart; y <= yFinish; y += yIncrement) {
-      const position = Vector(x, y);
-      if (!texelEquals(sprite1, sprite2, position, layerID)) {
-        return false;
-      }
-    }
-  }
-
-  return true;
-}
-
-/** Helper function to check if two texels on a sprite are equivalent to each other. */
-export function texelEquals(
-  sprite1: Sprite,
-  sprite2: Sprite,
-  position: Vector,
-  layerID: int,
-): boolean {
-  const kColor1 = sprite1.GetTexel(position, VectorZero, 1, layerID);
-  const kColor2 = sprite2.GetTexel(position, VectorZero, 1, layerID);
-  return kColorEquals(kColor1, kColor2);
-}

package/src/functions/stage.ts

@@ -1,125 +0,0 @@
-import { LevelStage, StageType } from "isaac-typescript-definitions";
-import { game } from "../cachedClasses";
-import { STAGE_TYPE_TO_LETTER } from "../objects/stageTypeToLetter";
-
-/**
- * Helper function to account for Repentance floors being offset by 1. For example, Downpour 2 is
- * the third level of the run, but the game considers it to have a stage of 2. This function will
- * consider Downpour 2 to have a stage of 3.
- */
-export function getEffectiveStage(): int {
-  const level = game.GetLevel();
-  const stage = level.GetStage();
-
-  if (onRepentanceStage()) {
-    return stage + 1; // eslint-disable-line isaacscript/strict-enums
-  }
-
-  return stage;
-}
-
-/** Alias for the `Level.GetStage` method. */
-export function getStage(): LevelStage {
-  const level = game.GetLevel();
-
-  return level.GetStage();
-}
-
-/** Alias for the `Level.GetStageType` method. */
-export function getStageType(): StageType {
-  const level = game.GetLevel();
-
-  return level.GetStageType();
-}
-
-/** Helper function to directly warp to a specific stage using the "stage" console command. */
-export function goToStage(stage: LevelStage, stageType: StageType): void {
-  const stageTypeLetterSuffix = stageTypeToLetter(stageType);
-  const command = `stage ${stage}${stageTypeLetterSuffix}`;
-  Isaac.ExecuteCommand(command);
-}
-
-export function isRepentanceStage(stageType: StageType): boolean {
-  return (
-    stageType === StageType.REPENTANCE || stageType === StageType.REPENTANCE_B
-  );
-}
-
-export function onCathedral(): boolean {
-  const level = game.GetLevel();
-  const stage = level.GetStage();
-  const stageType = level.GetStageType();
-
-  return (
-    stage === LevelStage.SHEOL_CATHEDRAL &&
-    stageType === StageType.WRATH_OF_THE_LAMB
-  );
-}
-
-export function onChest(): boolean {
-  const level = game.GetLevel();
-  const stage = level.GetStage();
-  const stageType = level.GetStageType();
-
-  return (
-    stage === LevelStage.DARK_ROOM_CHEST &&
-    stageType === StageType.WRATH_OF_THE_LAMB
-  );
-}
-
-export function onDarkRoom(): boolean {
-  const level = game.GetLevel();
-  const stage = level.GetStage();
-  const stageType = level.GetStageType();
-
-  return (
-    stage === LevelStage.DARK_ROOM_CHEST && stageType === StageType.ORIGINAL
-  );
-}
-
-/**
- * Returns whether or not the player is on the "final floor" of the particular run. The final floor
- * is defined as one that prevents the player from entering the I AM ERROR room on.
- *
- * For example, when using Undefined on The Chest, it has a 50% chance of teleporting the player to
- * the Secret Room and a 50% chance of teleporting the player to the Super Secret Room, because the
- * I AM ERROR room is never entered into the list of possibilities.
- */
-export function onFinalFloor(): boolean {
-  const level = game.GetLevel();
-  const stage = level.GetStage();
-
-  return (
-    stage === LevelStage.DARK_ROOM_CHEST ||
-    stage === LevelStage.THE_VOID ||
-    stage === LevelStage.HOME ||
-    (stage === LevelStage.WOMB_2 && onRepentanceStage()) // Corpse 2
-  );
-}
-
-export function onRepentanceStage(): boolean {
-  const level = game.GetLevel();
-  const stageType = level.GetStageType();
-
-  return isRepentanceStage(stageType);
-}
-
-export function onSheol(): boolean {
-  const level = game.GetLevel();
-  const stage = level.GetStage();
-  const stageType = level.GetStageType();
-
-  return (
-    stage === LevelStage.SHEOL_CATHEDRAL && stageType === StageType.ORIGINAL
-  );
-}
-
-/**
- * Helper function to convert a numerical `StageType` into the letter suffix supplied to the "stage"
- * console command. For example, `StageType.REPENTANCE` is the stage type for Downpour, and the
- * console command to go to Downpour is "stage 1c", so this function converts `StageType.REPENTANCE`
- * to "c".
- */
-export function stageTypeToLetter(stageType: StageType): string {
-  return STAGE_TYPE_TO_LETTER[stageType];
-}

package/src/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);
-}