isaacscript-common 14.1.3 → 15.0.0

package/src/functions/easing.ts

@@ -2,181 +2,332 @@
 /* eslint-disable no-return-assign */
 /* eslint-disable sort-exports/sort-exports */
 
-// These functions are from:
-// https://easings.net/
-
-export function easeInSine(x: number): number {
-  return 1 - Math.cos((x * Math.PI) / 2);
+/**
+ * From: https://easings.net/#easeInSine
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInSine(time: number): number {
+  return 1 - Math.cos((time * Math.PI) / 2);
 }
 
-export function easeOutSine(x: number): number {
-  return Math.sin((x * Math.PI) / 2);
+/**
+ * From: https://easings.net/#easeOutSine
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeOutSine(time: number): number {
+  return Math.sin((time * Math.PI) / 2);
 }
 
-export function easeInOutSine(x: number): number {
-  return -(Math.cos(Math.PI * x) - 1) / 2;
+/**
+ * From: https://easings.net/#easeInOutSine
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInOutSine(time: number): number {
+  return -(Math.cos(Math.PI * time) - 1) / 2;
 }
 
-export function easeInCubic(x: number): number {
-  return x * x * x;
+/**
+ * From: https://easings.net/#easeInCubic
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInCubic(time: number): number {
+  return time * time * time;
 }
 
-export function easeOutCubic(x: number): number {
-  return 1 - (1 - x) ** 3;
+/**
+ * From: https://easings.net/#easeOutCubic
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeOutCubic(time: number): number {
+  return 1 - (1 - time) ** 3;
 }
 
-export function easeInOutCubic(x: number): number {
-  return x < 0.5 ? 4 * x * x * x : 1 - (-2 * x + 2) ** 3 / 2;
+/**
+ * From: https://easings.net/#easeInOutCubic
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInOutCubic(time: number): number {
+  return time < 0.5 ? 4 * time * time * time : 1 - (-2 * time + 2) ** 3 / 2;
 }
 
-export function easeInQuint(x: number): number {
-  return x * x * x * x * x;
+/**
+ * From: https://easings.net/#easeInQuint
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInQuint(time: number): number {
+  return time * time * time * time * time;
 }
 
-export function easeOutQuint(x: number): number {
-  return 1 - (1 - x) ** 5;
+/**
+ * From: https://easings.net/#easeOutQuint
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeOutQuint(time: number): number {
+  return 1 - (1 - time) ** 5;
 }
 
-export function easeInOutQuint(x: number): number {
-  return x < 0.5 ? 16 * x * x * x * x * x : 1 - (-2 * x + 2) ** 5 / 2;
+/**
+ * From: https://easings.net/#easeInOutQuint
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInOutQuint(time: number): number {
+  return time < 0.5
+    ? 16 * time * time * time * time * time
+    : 1 - (-2 * time + 2) ** 5 / 2;
 }
 
-export function easeInCirc(x: number): number {
-  return 1 - Math.sqrt(1 - x ** 2);
+/**
+ * From: https://easings.net/#easeInCirc
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInCirc(time: number): number {
+  return 1 - Math.sqrt(1 - time ** 2);
 }
 
-export function easeOutCirc(x: number): number {
-  return Math.sqrt(1 - (x - 1) ** 2);
+/**
+ * From: https://easings.net/#easeOutCirc
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeOutCirc(time: number): number {
+  return Math.sqrt(1 - (time - 1) ** 2);
 }
 
-export function easeInOutCirc(x: number): number {
-  return x < 0.5
-    ? (1 - Math.sqrt(1 - (2 * x) ** 2)) / 2
-    : (Math.sqrt(1 - (-2 * x + 2) ** 2) + 1) / 2;
+/**
+ * From: https://easings.net/#easeInOutCirc
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInOutCirc(time: number): number {
+  return time < 0.5
+    ? (1 - Math.sqrt(1 - (2 * time) ** 2)) / 2
+    : (Math.sqrt(1 - (-2 * time + 2) ** 2) + 1) / 2;
 }
 
-export function easeInElastic(x: number): number {
+/**
+ * From: https://easings.net/#easeInElastic
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInElastic(time: number): number {
   const c4 = (2 * Math.PI) / 3;
 
-  return x === 0
+  return time === 0
     ? 0
-    : x === 1
+    : time === 1
     ? 1
-    : -(2 ** (10 * x - 10)) * Math.sin((x * 10 - 10.75) * c4);
+    : -(2 ** (10 * time - 10)) * Math.sin((time * 10 - 10.75) * c4);
 }
 
-export function easeOutElastic(x: number): number {
+/**
+ * From: https://easings.net/#easeOutElastic
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeOutElastic(time: number): number {
   const c4 = (2 * Math.PI) / 3;
 
-  return x === 0
+  return time === 0
     ? 0
-    : x === 1
+    : time === 1
     ? 1
-    : 2 ** (-10 * x) * Math.sin((x * 10 - 0.75) * c4) + 1;
+    : 2 ** (-10 * time) * Math.sin((time * 10 - 0.75) * c4) + 1;
 }
 
-export function easeInOutElastic(x: number): number {
+/**
+ * From: https://easings.net/#easeInOutElastic
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInOutElastic(time: number): number {
   const c5 = (2 * Math.PI) / 4.5;
 
-  return x === 0
+  return time === 0
     ? 0
-    : x === 1
+    : time === 1
     ? 1
-    : x < 0.5
-    ? -(2 ** (20 * x - 10) * Math.sin((20 * x - 11.125) * c5)) / 2
-    : (2 ** (-20 * x + 10) * Math.sin((20 * x - 11.125) * c5)) / 2 + 1;
+    : time < 0.5
+    ? -(2 ** (20 * time - 10) * Math.sin((20 * time - 11.125) * c5)) / 2
+    : (2 ** (-20 * time + 10) * Math.sin((20 * time - 11.125) * c5)) / 2 + 1;
 }
 
-export function easeInQuad(x: number): number {
-  return x * x;
+/**
+ * From: https://easings.net/#easeInQuad
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInQuad(time: number): number {
+  return time * time;
 }
 
-export function easeOutQuad(x: number): number {
-  return 1 - (1 - x) * (1 - x);
+/**
+ * From: https://easings.net/#easeOutQuad
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeOutQuad(time: number): number {
+  return 1 - (1 - time) * (1 - time);
 }
 
-export function easeInOutQuad(x: number): number {
-  return x < 0.5 ? 2 * x * x : 1 - (-2 * x + 2) ** 2 / 2;
+/**
+ * From: https://easings.net/#easeInOutQuad
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInOutQuad(time: number): number {
+  return time < 0.5 ? 2 * time * time : 1 - (-2 * time + 2) ** 2 / 2;
 }
 
-export function easeInQuart(x: number): number {
-  return x * x * x * x;
+/**
+ * From: https://easings.net/#easeInQuart
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInQuart(time: number): number {
+  return time * time * time * time;
 }
 
-export function easeOutQuart(x: number): number {
-  return 1 - (1 - x) ** 4;
+/**
+ * From: https://easings.net/#easeOutQuart
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeOutQuart(time: number): number {
+  return 1 - (1 - time) ** 4;
 }
 
-export function easeInOutQuart(x: number): number {
-  return x < 0.5 ? 8 * x * x * x * x : 1 - (-2 * x + 2) ** 4 / 2;
+/**
+ * From: https://easings.net/#easeInOutQuart
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInOutQuart(time: number): number {
+  return time < 0.5
+    ? 8 * time * time * time * time
+    : 1 - (-2 * time + 2) ** 4 / 2;
 }
 
-export function easeInExpo(x: number): number {
-  return x === 0 ? 0 : 2 ** (10 * x - 10);
+/**
+ * From: https://easings.net/#easeInExpo
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInExpo(time: number): number {
+  return time === 0 ? 0 : 2 ** (10 * time - 10);
 }
 
-export function easeOutExpo(x: number): number {
-  return x === 1 ? 1 : 1 - 2 ** (-10 * x);
+/**
+ * From: https://easings.net/#easeOutExpo
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeOutExpo(time: number): number {
+  return time === 1 ? 1 : 1 - 2 ** (-10 * time);
 }
 
-export function easeInOutExpo(x: number): number {
-  return x === 0
+/**
+ * From: https://easings.net/#easeInOutExpo
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInOutExpo(time: number): number {
+  return time === 0
     ? 0
-    : x === 1
+    : time === 1
     ? 1
-    : x < 0.5
-    ? 2 ** (20 * x - 10) / 2
-    : (2 - 2 ** (-20 * x + 10)) / 2;
+    : time < 0.5
+    ? 2 ** (20 * time - 10) / 2
+    : (2 - 2 ** (-20 * time + 10)) / 2;
 }
 
-export function easeInBack(x: number): number {
+/**
+ * From: https://easings.net/#easeInBack
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInBack(time: number): number {
   const c1 = 1.70158;
   const c3 = c1 + 1;
 
-  return c3 * x * x * x - c1 * x * x;
+  return c3 * time * time * time - c1 * time * time;
 }
 
-export function easeOutBack(x: number): number {
+/**
+ * From: https://easings.net/#easeOutBack
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeOutBack(time: number): number {
   const c1 = 1.70158;
   const c3 = c1 + 1;
 
-  return 1 + c3 * (x - 1) ** 3 + c1 * (x - 1) ** 2;
+  return 1 + c3 * (time - 1) ** 3 + c1 * (time - 1) ** 2;
 }
 
-export function easeInOutBack(x: number): number {
+/**
+ * From: https://easings.net/#easeInOutBack
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInOutBack(time: number): number {
   const c1 = 1.70158;
   const c2 = c1 * 1.525;
 
-  return x < 0.5
-    ? ((2 * x) ** 2 * ((c2 + 1) * 2 * x - c2)) / 2
-    : ((2 * x - 2) ** 2 * ((c2 + 1) * (x * 2 - 2) + c2) + 2) / 2;
+  return time < 0.5
+    ? ((2 * time) ** 2 * ((c2 + 1) * 2 * time - c2)) / 2
+    : ((2 * time - 2) ** 2 * ((c2 + 1) * (time * 2 - 2) + c2) + 2) / 2;
 }
 
-export function easeInBounce(x: number): number {
-  return 1 - easeOutBounce(1 - x);
+/**
+ * From: https://easings.net/#easeInBounce
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInBounce(time: number): number {
+  return 1 - easeOutBounce(1 - time);
 }
 
-export function easeOutBounce(x: number): number {
+/**
+ * From: https://easings.net/#easeInOutSine
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeOutBounce(time: number): number {
   const n1 = 7.5625;
   const d1 = 2.75;
 
-  if (x < 1 / d1) {
-    return n1 * x * x;
+  if (time < 1 / d1) {
+    return n1 * time * time;
   }
 
-  if (x < 2 / d1) {
-    return n1 * (x -= 1.5 / d1) * x + 0.75;
+  if (time < 2 / d1) {
+    return n1 * (time -= 1.5 / d1) * time + 0.75;
   }
 
-  if (x < 2.5 / d1) {
-    return n1 * (x -= 2.25 / d1) * x + 0.9375;
+  if (time < 2.5 / d1) {
+    return n1 * (time -= 2.25 / d1) * time + 0.9375;
   }
 
-  return n1 * (x -= 2.625 / d1) * x + 0.984375;
+  return n1 * (time -= 2.625 / d1) * time + 0.984375;
 }
 
-export function easeInOutBounce(x: number): number {
-  return x < 0.5
-    ? (1 - easeOutBounce(1 - 2 * x)) / 2
-    : (1 + easeOutBounce(2 * x - 1)) / 2;
+/**
+ * From: https://easings.net/#easeInOutBounce
+ *
+ * @param time A value between 0 and 1 that represents how far along you are in the transition.
+ */
+export function easeInOutBounce(time: number): number {
+  return time < 0.5
+    ? (1 - easeOutBounce(1 - 2 * time)) / 2
+    : (1 + easeOutBounce(2 * time - 1)) / 2;
 }

package/src/functions/familiars.ts

@@ -1,6 +1,11 @@
-import { CollectibleType, FamiliarVariant } from "isaac-typescript-definitions";
+import {
+  CollectibleType,
+  EntityType,
+  FamiliarVariant,
+} from "isaac-typescript-definitions";
 import { itemConfig } from "../core/cachedClasses";
 import { FAMILIARS_THAT_SHOOT_PLAYER_TEARS_SET } from "../sets/familiarsThatShootPlayerTearsSet";
+import { getEntities } from "./entities";
 import { getFamiliars } from "./entitiesSpecific";
 
 /**
@@ -82,7 +87,8 @@ export function checkFamiliarFromCollectibles(
   familiarVariant: FamiliarVariant,
   familiarSubType?: int,
 ): void {
-  // We need to include non-real collectibles, like Lilith's Incubus.
+  // We need to include non-real collectibles (like Lilith's Incubus), so we omit the second
+  // argument.
   const numCollectibles = player.GetCollectibleNum(collectibleType);
   const effects = player.GetEffects();
 
@@ -111,6 +117,43 @@ export function getPlayerFamiliars(player: EntityPlayer): EntityFamiliar[] {
   });
 }
 
+/**
+ * Helper function to get the corresponding "Siren Helper" entity for a stolen familiar.
+ *
+ * When The Siren boss "steals" your familiars, a hidden "Siren Helper" entity is spawned to control
+ * each familiar stolen. (Checking for the presence of this entity seems to be the only way to
+ * detect when the Siren steals a familiar.)
+ *
+ * @param familiar The familiar to be checked.
+ * @returns Returns the hidden "Siren Helper" entity corresponding to the given familiar, if it
+ *          exists. Returns undefined otherwise.
+ */
+export function getSirenHelper(familiar: EntityFamiliar): Entity | undefined {
+  const familiarPtrHash = GetPtrHash(familiar);
+
+  const sirenHelpers = getEntities(EntityType.SIREN_HELPER);
+  return sirenHelpers.find(
+    (sirenHelper) =>
+      sirenHelper.Target !== undefined &&
+      GetPtrHash(sirenHelper.Target) === familiarPtrHash,
+  );
+}
+
+/**
+ * Helper function to detect if the given familiar is "stolen" by The Siren boss.
+ *
+ * This function is useful because some familiars may need to behave differently when under The
+ * Siren's control (e.g. if they auto-target enemies).
+ */
+export function isFamiliarStolenBySiren(familiar: EntityFamiliar): boolean {
+  const sirenHelper = getSirenHelper(familiar);
+  return sirenHelper !== undefined;
+}
+
+/**
+ * Helper function to check if a familiar is the type that shoots tears that mimic the players
+ * tears, like Incubus, Fate's Reward, Sprinkler, and so on.
+ */
 export function isFamiliarThatShootsPlayerTears(
   familiar: EntityFamiliar,
 ): boolean {

package/src/functions/gridEntities.ts

@@ -430,6 +430,25 @@ export function removeAllMatchingGridEntities(
   return gridEntities;
 }
 
+/**
+ * Helper function to remove all entities that just spawned from a grid entity breaking.
+ * Specifically, this is any entities that overlap with the position of a grid entity and are on
+ * frame 0.
+ *
+ * You must specify an array of entities to look through.
+ */
+export function removeEntitiesSpawnedFromGridEntity(
+  entities: Entity[],
+  gridEntity: GridEntity,
+): void {
+  const entitiesFromGridEntity = entities.filter(
+    (entity) =>
+      entity.FrameCount === 0 &&
+      vectorEquals(entity.Position, gridEntity.Position),
+  );
+  removeEntities(entitiesFromGridEntity);
+}
+
 /**
  * Helper function to remove all of the grid entities in the supplied array.
  *

package/src/functions/initArray.ts

@@ -1,14 +1,13 @@
 import { deepCopy } from "./deepCopy";
-import { isPrimitive } from "./types";
 import { repeat } from "./utils";
 
 /**
  * Initializes an array with all of the elements containing the specified default value.
  *
- * If the provided default value is not a boolean, number, or string, then it will be copied with
- * the `deepCopy` function before adding it to the new array. In this way, you can initialize an
- * array of arrays, or an array of maps, and so on. (If the `deepCopy` function was not used, then
- * all of the array elements would just be references to the same underlying data structure.)
+ * The provided default value will be copied with the `deepCopy` function before adding it to the
+ * new array. Thus, you can initialize an array of arrays, or an array of maps, and so on. (If the
+ * `deepCopy` function was not used, then all of the array elements would just be references to the
+ * same underlying data structure.)
  *
  * For example:
  *
@@ -20,12 +19,8 @@ import { repeat } from "./utils";
 export function initArray<T>(defaultValue: T, size: int): T[] {
   const array: T[] = [];
   repeat(size, () => {
-    if (isPrimitive(defaultValue)) {
-      array.push(defaultValue);
-    } else {
-      const copy = deepCopy(defaultValue);
-      array.push(copy);
-    }
+    const copy = deepCopy(defaultValue);
+    array.push(copy);
   });
 
   return array;

package/src/functions/jsonRoom.ts

@@ -19,6 +19,8 @@ interface JSONObject {
 /**
  * Helper function to calculate what the resulting `BitFlags<DoorSlotFlag>` value would be for a
  * given JSON room.
+ *
+ * (A JSON room is an XML file converted to JSON so that it can be directly imported into your mod.)
  */
 export function getJSONRoomDoorSlotFlags(
   jsonRoom: JSONRoom,
@@ -75,6 +77,8 @@ export function getJSONRoomDoorSlotFlags(
 /**
  * Helper function to find a specific room from an array of JSON rooms.
  *
+ * (A JSON room is an XML file converted to JSON so that it can be directly imported into your mod.)
+ *
  * @param jsonRooms The array of rooms to search through.
  * @param variant The room variant to select. (The room variant can be thought of as the ID of the
  *                room.)
@@ -107,6 +111,8 @@ export function getJSONRoomOfVariant(
 /**
  * Helper function to find all of the JSON rooms that match the sub-type provided.
  *
+ * (A JSON room is an XML file converted to JSON so that it can be directly imported into your mod.)
+ *
  * @param jsonRooms The array of rooms to search through.
  * @param subType The sub-type to match.
  */
@@ -124,6 +130,9 @@ export function getJSONRoomsOfSubType(
 /**
  * Helper function to get a random JSON entity from an array of JSON entities.
  *
+ * (A JSON entity is an entity inside of a JSON room. A JSON room is an XML file converted to JSON
+ * so that it can be directly imported into your mod.)
+ *
  * Note that this function does not simply choose a random element in the provided array; it will
  * properly account for each room weight using the algorithm from:
  * https://stackoverflow.com/questions/1761626/weighted-random-numbers
@@ -163,6 +172,8 @@ export function getRandomJSONEntity(
 /**
  * Helper function to get a random JSON room from an array of JSON rooms.
  *
+ * (A JSON room is an XML file converted to JSON so that it can be directly imported into your mod.)
+ *
  * Note that this function does not simply choose a random element in the provided array; it will
  * properly account for each room weight using the algorithm from:
  * https://stackoverflow.com/questions/1761626/weighted-random-numbers

package/src/functions/kColor.ts

@@ -1,5 +1,5 @@
 import { CopyableIsaacAPIClassType } from "isaac-typescript-definitions";
-import { SerializationBrand } from "../enums/private/SerializationBrand";
+import { SerializationBrand } from "../enums/SerializationBrand";
 import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
 import { getRandom } from "./random";
 import { getRandomSeed, isRNG, newRNG } from "./rng";
@@ -92,8 +92,8 @@ export function isKColor(object: unknown): object is KColor {
 }
 
 /**
- * Used to determine is the given table is a serialized `KColor` object created by the save data
- * manager and/or the `deepCopy` function.
+ * Used to determine is the given table is a serialized `KColor` object created by the `deepCopy`
+ * function.
  */
 export function isSerializedKColor(
   object: unknown,

package/src/functions/logEntities.ts

@@ -69,14 +69,21 @@ export function logAllEntities(
     })\n`;
   }
 
-  log(msg);
+  // We must log each line because otherwise the message can get truncated.
+  for (const line of msg.trim().split("\n")) {
+    log(line);
+  }
 }
 
 /**
  * Helper function for printing out every grid entity (or filtered grid entity) in the current room.
+ *
+ * @param includeWalls Optional. Whether or not to log the walls. Default is false.
+ * @param gridEntityTypeFilter Optional. If specified, will only log the given `GridEntityType`.
+ *                             Default is undefined.
  */
 export function logAllGridEntities(
-  includeWalls: boolean,
+  includeWalls = false,
   gridEntityTypeFilter?: GridEntityType,
 ): void {
   let msg = "Grid entities in the room";
@@ -122,7 +129,10 @@ export function logAllGridEntities(
     })\n`;
   }
 
-  log(msg);
+  // We must log each line because otherwise the message can get truncated.
+  for (const line of msg.trim().split("\n")) {
+    log(line);
+  }
 }
 
 /** Helper function for logging an array of specific entities. */