isaacscript-common 2.2.0 → 2.3.0

package/src/functions/seeds.ts

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

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

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

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

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

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

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

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