isaacscript-common 2.2.0 → 2.3.0

package/src/functions/math.ts

@@ -0,0 +1,149 @@
+import { Direction } from "isaac-typescript-definitions";
+import { directionToVector } from "./direction";
+
+/**
+ * Helper function to normalize an integer.
+ *
+ * - If `x` is less than `min`, then it will be clamped to `min`.
+ * - If `x` is greater than `max`, then it will be clamped to `max`.
+ */
+export function clamp(x: int, min: int, max: int): int {
+  return Math.max(min, Math.min(x, max));
+}
+
+export function getAngleDifference(angle1: float, angle2: float): float {
+  const subtractedAngle = angle1 - angle2;
+  return ((subtractedAngle + 180) % 360) - 180;
+}
+
+/**
+ * Helper function to get an array of equidistant points on the circumference around a circle.
+ * Useful for equally distributing things in a circle pattern.
+ *
+ * @param centerPos A position that represents the center of the center to get the points from.
+ * @param radius The radius of the circle.
+ * @param numPoints The number of points on the circumference of the circle to get.
+ * @param xMultiplier An optional multiplier to get the points around an oval. Default is 1.
+ * @param yMultiplier An optional multiplier to get the points around an oval. Default is 1.
+ * @param initialDirection By default, the first point on the circle will be on the top center, but
+ *                         this can be optionally changed by specifying this argument.
+ */
+export function getCircleDiscretizedPoints(
+  centerPos: Vector,
+  radius: float,
+  numPoints: int,
+  xMultiplier = 1,
+  yMultiplier = 1,
+  initialDirection = Direction.UP,
+): Vector[] {
+  const vector = directionToVector(initialDirection);
+  const initialPosition = vector.mul(radius);
+  const positions: Vector[] = [];
+  for (let i = 0; i < numPoints; i++) {
+    const rotatedPosition = initialPosition.Rotated((i * 360) / numPoints);
+    rotatedPosition.X *= xMultiplier;
+    rotatedPosition.Y *= yMultiplier;
+    const positionFromCenter = centerPos.add(rotatedPosition);
+    positions.push(positionFromCenter);
+  }
+
+  return positions;
+}
+
+/**
+ * Helper function to check if a given position is within a given rectangle.
+ *
+ * This is an inclusive check, meaning that it will return true if the position is on the border of
+ * the rectangle.
+ */
+export function inRectangle(
+  position: Vector,
+  topLeft: Vector,
+  bottomRight: Vector,
+): boolean {
+  return (
+    position.X >= topLeft.X &&
+    position.X <= bottomRight.X &&
+    position.Y >= topLeft.Y &&
+    position.Y <= bottomRight.Y
+  );
+}
+
+/**
+ * From: https://www.geeksforgeeks.org/check-if-any-point-overlaps-the-given-circle-and-rectangle/
+ */
+export function isCircleIntersectingRectangle(
+  circleCenter: Vector,
+  circleRadius: float,
+  rectangleTopLeft: Vector,
+  rectangleBottomRight: Vector,
+): boolean {
+  const nearestX = Math.max(
+    rectangleTopLeft.X,
+    Math.min(circleCenter.X, rectangleBottomRight.X),
+  );
+
+  const nearestY = Math.max(
+    rectangleTopLeft.Y,
+    Math.min(circleCenter.Y, rectangleBottomRight.Y),
+  );
+
+  const nearestPointToCircleOnRectangle = Vector(nearestX, nearestY);
+  const distanceToCenterOfCircle =
+    nearestPointToCircleOnRectangle.Distance(circleCenter);
+
+  return distanceToCenterOfCircle <= circleRadius;
+}
+
+export function isEven(num: int): boolean {
+  // This is benchmarked to be faster than using the modulus operator by 3%.
+  return (num & 1) === 0;
+}
+
+export function isOdd(num: int): boolean {
+  // This is benchmarked to be faster than using the modulus operator by 3%.
+  return (num & 1) === 1;
+}
+
+export function lerp(a: number, b: number, pos: float): number {
+  return a + (b - a) * pos;
+}
+
+export function lerpAngleDegrees(
+  aStart: number,
+  aEnd: number,
+  percent: float,
+): number {
+  return aStart + getAngleDifference(aStart, aEnd) * percent;
+}
+
+/**
+ * If rounding fails, this function returns 0.
+ * From: http://lua-users.org/wiki/SimpleRound
+ *
+ * @param num The number to round.
+ * @param numDecimalPlaces Default is 0.
+ */
+export function round(num: float, numDecimalPlaces = 0): float {
+  const roundedNum = tonumber(string.format(`%.${numDecimalPlaces}f`, num));
+  return roundedNum === undefined ? 0 : roundedNum;
+}
+
+/**
+ * @returns 1 if n is positive, -1 if n is negative, or 0 if n is 0.
+ */
+export function sign(n: number): int {
+  if (n > 0) {
+    return 1;
+  }
+
+  if (n < 0) {
+    return -1;
+  }
+
+  return 0;
+}
+
+export function tanh(x: number): number {
+  return (Math.exp(x) - Math.exp(-x)) / (Math.exp(x) + Math.exp(-x));
+}

package/src/functions/mergeTests.ts

@@ -0,0 +1,288 @@
+import { SerializationType } from "../enums/SerializationType";
+import { merge } from "../features/saveDataManager/merge";
+import { deepCopy } from "./deepCopy";
+import { log } from "./log";
+import { isRNG, newRNG } from "./rng";
+import { isSerializedIsaacAPIClass } from "./serialization";
+import { copyVector, isVector } from "./vector";
+
+export function mergeTests(): void {
+  oldTableHasUpdatedValue();
+  newTableHasSameValue();
+  oldTableHasUpdatedValueFromNull();
+  oldTableHasSerializedIsaacAPIClass();
+
+  oldTableHasFilledInterface();
+  oldTableHasVector();
+  oldTableHasVectorSerialized();
+  oldTableHasRNG();
+  oldTableHasRNGSerialized();
+
+  log("All merge tests passed!");
+}
+
+function oldTableHasUpdatedValue() {
+  const key = "foo";
+  const oldValue = "bar";
+  const newValue = "baz";
+  const oldTable = {
+    foo: oldValue,
+  } as unknown as LuaTable<AnyNotNil, unknown>;
+  const newTable = {
+    foo: newValue,
+  } as unknown as LuaTable<AnyNotNil, unknown>;
+
+  merge(oldTable, newTable, "oldTableHasUpdatedValue");
+
+  const oldTableValue = oldTable.get(key) as string;
+  if (oldTableValue !== newValue) {
+    error(`The old table does not have a value of: ${newValue}`);
+  }
+}
+
+function newTableHasSameValue() {
+  const key = "foo";
+  const oldValue = "bar";
+  const newValue = "baz";
+  const oldTable = {
+    foo: oldValue,
+  } as unknown as LuaTable<AnyNotNil, unknown>;
+  const newTable = {
+    foo: newValue,
+  } as unknown as LuaTable<AnyNotNil, unknown>;
+
+  merge(oldTable, newTable, "newTableHasSameValue");
+
+  const newTableValue = newTable.get(key) as string;
+  if (newTableValue !== newValue) {
+    error(`The new table does not have a value of: ${newValue}`);
+  }
+}
+
+function oldTableHasUpdatedValueFromNull() {
+  const key = "foo";
+  const newValue = "baz";
+  const oldTable = {
+    foo: null as string | null,
+  } as unknown as LuaTable<AnyNotNil, unknown>;
+  const newTable = {
+    foo: newValue,
+  } as unknown as LuaTable<AnyNotNil, unknown>;
+
+  merge(oldTable, newTable, "oldTableHasUpdatedValueFromNull");
+
+  const oldTableValue = oldTable.get(key) as string;
+  if (oldTableValue !== newValue) {
+    error(`The old table does not have a value of: ${newValue}`);
+  }
+}
+
+function oldTableHasSerializedIsaacAPIClass() {
+  const x = 50;
+  const y = 60;
+  const vector = Vector(x, y);
+
+  const vectorSerialized = copyVector(vector, SerializationType.SERIALIZE);
+  if (!isSerializedIsaacAPIClass(vectorSerialized)) {
+    error(
+      'The "isSerializedIsaacAPIClass" function says that a serialized vector is not serialized.',
+    );
+  }
+}
+
+function oldTableHasFilledInterface() {
+  interface Foo {
+    bar: string;
+  }
+
+  const key = "foo";
+  const newValue = "baz";
+  const oldTable = {
+    foo: null as Foo | null,
+  } as unknown as LuaTable<AnyNotNil, unknown>;
+  const foo: Foo = {
+    bar: newValue,
+  };
+  const newTable = {
+    foo,
+  } as unknown as LuaTable<AnyNotNil, unknown>;
+
+  merge(oldTable, newTable, "oldTableHasFilledInterface");
+
+  const oldTableValue = oldTable.get(key) as Foo | undefined;
+  if (oldTableValue === undefined) {
+    error(`The old table's key of "${key}" was not filled.`);
+  }
+
+  if (oldTableValue.bar !== newValue) {
+    error('The old table\'s key of "bar" was not filled.');
+  }
+}
+
+function oldTableHasVector() {
+  log("Starting test: oldTableHasVector");
+
+  interface Foo {
+    bar: Vector;
+  }
+
+  const key = "foo";
+  const x = 50;
+  const y = 60;
+  const newValue = Vector(x, y);
+  const oldTable = {
+    foo: null as Foo | null,
+  } as unknown as LuaTable<AnyNotNil, unknown>;
+  const foo: Foo = {
+    bar: newValue,
+  };
+  const newTable = {
+    foo,
+  } as unknown as LuaTable<AnyNotNil, unknown>;
+
+  merge(oldTable, newTable, "oldTableHasVector");
+
+  const oldTableValue = oldTable.get(key) as Foo | undefined;
+  if (oldTableValue === undefined) {
+    error(`The old table's key of "${key}" was not filled.`);
+  }
+
+  if (oldTableValue.bar.X !== x) {
+    error(`The old table's value for "x" does not match: ${x}`);
+  }
+
+  if (oldTableValue.bar.Y !== y) {
+    error(`The old table's value for "y" does not match: ${y}`);
+  }
+
+  if (!isVector(oldTableValue.bar)) {
+    error("The old table's value is not a Vector object.");
+  }
+}
+
+function oldTableHasVectorSerialized() {
+  log("Starting test: oldTableHasVectorSerialized");
+
+  interface Foo {
+    bar: Vector;
+  }
+
+  const key = "foo";
+  const x = 50;
+  const y = 60;
+  const newValue = Vector(x, y);
+  const oldTable = {
+    foo: null as Foo | null,
+  } as unknown as LuaTable<AnyNotNil, unknown>;
+  const foo: Foo = {
+    bar: newValue,
+  };
+  const newTable = {
+    foo,
+  } as unknown as LuaTable<AnyNotNil, unknown>;
+  const newTableSerialized = deepCopy(
+    newTable,
+    SerializationType.SERIALIZE,
+  ) as LuaTable<AnyNotNil, unknown>;
+
+  merge(oldTable, newTableSerialized, "oldTableHasVectorSerialized");
+
+  const oldTableValue = oldTable.get(key) as Foo | undefined;
+  if (oldTableValue === undefined) {
+    error(`The old table's key of "${key}" was not filled.`);
+  }
+
+  if (oldTableValue.bar.X !== x) {
+    error(`The old table's value for "x" does not match: ${x}`);
+  }
+
+  if (oldTableValue.bar.Y !== y) {
+    error(`The old table's value for "y" does not match: ${y}`);
+  }
+
+  if (!isVector(oldTableValue.bar)) {
+    error(
+      "The old table's value is not a Vector object (during the serialized test).",
+    );
+  }
+}
+
+function oldTableHasRNG() {
+  log("Starting test: oldTableHasRNG");
+
+  interface Foo {
+    bar: RNG;
+  }
+
+  const key = "foo";
+  const seed = 50 as Seed;
+  const newValue = newRNG(seed);
+  const oldTable = {
+    foo: null as Foo | null,
+  } as unknown as LuaTable<AnyNotNil, unknown>;
+  const foo: Foo = {
+    bar: newValue,
+  };
+  const newTable = {
+    foo,
+  } as unknown as LuaTable<AnyNotNil, unknown>;
+
+  merge(oldTable, newTable, "oldTableHasRNG");
+
+  const oldTableValue = oldTable.get(key) as Foo | undefined;
+  if (oldTableValue === undefined) {
+    error(`The old table's key of "${key}" was not filled.`);
+  }
+
+  if (!isRNG(oldTableValue.bar)) {
+    error("The old table's value is not an RNG object.");
+  }
+
+  const newSeed = oldTableValue.bar.GetSeed();
+  if (newSeed !== seed) {
+    error(`The old table's seed not match: ${seed}`);
+  }
+}
+
+function oldTableHasRNGSerialized() {
+  log("Starting test: oldTableHasRNGSerialized");
+
+  interface Foo {
+    bar: RNG;
+  }
+
+  const key = "foo";
+  const seed = 50 as Seed;
+  const newValue = newRNG(seed);
+  const oldTable = {
+    foo: null as Foo | null,
+  } as unknown as LuaTable<AnyNotNil, unknown>;
+  const foo: Foo = {
+    bar: newValue,
+  };
+  const newTable = {
+    foo,
+  } as unknown as LuaTable<AnyNotNil, unknown>;
+  const newTableSerialized = deepCopy(
+    newTable,
+    SerializationType.SERIALIZE,
+  ) as LuaTable<AnyNotNil, unknown>;
+
+  merge(oldTable, newTableSerialized, "oldTableHasRNGSerialized");
+
+  const oldTableValue = oldTable.get(key) as Foo | undefined;
+  if (oldTableValue === undefined) {
+    error(`The old table's key of "${key}" was not filled.`);
+  }
+
+  if (!isRNG(oldTableValue.bar)) {
+    error(
+      "The old table's value is not an RNG object (during the serialized test).",
+    );
+  }
+
+  const newSeed = oldTableValue.bar.GetSeed();
+  if (newSeed !== seed) {
+    error(`The old table's seed not match: ${seed}`);
+  }
+}

package/src/functions/npc.ts

@@ -0,0 +1,148 @@
+import {
+  BegottenVariant,
+  BigHornVariant,
+  ChargerSubType,
+  ChargerVariant,
+  DarkEsauVariant,
+  DeathVariant,
+  EntityType,
+  MamaGurdyVariant,
+  MotherSubType,
+  MotherVariant,
+  NpcState,
+  PeepVariant,
+  ProjectilesMode,
+  RaglingVariant,
+  VisVariant,
+} from "isaac-typescript-definitions";
+import { EGGY_STATE_FRAME_OF_FINAL_SPIDER } from "../constants";
+import { getFilteredNewEntities } from "./entity";
+import { getNPCs, getProjectiles } from "./entitySpecific";
+
+/**
+ * Used to filter out certain NPCs when determining of an NPC is "alive" and/or should keep the
+ * doors open.
+ */
+const NON_ALIVE_NPCS_TYPE_VARIANT: ReadonlySet<string> = new Set([
+  `${EntityType.VIS}.${VisVariant.CHUBBER_PROJECTILE}`, // 39.22
+  `${EntityType.DEATH}.${DeathVariant.DEATH_SCYTHE}`, // 66.10
+  `${EntityType.PEEP}.${PeepVariant.PEEP_EYE}`, // 68.10
+  `${EntityType.PEEP}.${PeepVariant.BLOAT_EYE}`, // 68.11
+  `${EntityType.BEGOTTEN}.${BegottenVariant.BEGOTTEN_CHAIN}`, // 251.10
+  `${EntityType.MAMA_GURDY}.${MamaGurdyVariant.LEFT_HAND}`, // 266.1
+  `${EntityType.MAMA_GURDY}.${MamaGurdyVariant.RIGHT_HAND}`, // 266.2
+  `${EntityType.BIG_HORN}.${BigHornVariant.SMALL_HOLE}`, // 411.1
+  `${EntityType.BIG_HORN}.${BigHornVariant.BIG_HOLE}`, // 411.2
+  `${EntityType.DARK_ESAU}.${DarkEsauVariant.DARK_ESAU}`, // 866.0
+  `${EntityType.DARK_ESAU}.${DarkEsauVariant.PIT}`, // 866.1
+]);
+
+/**
+ * Used to filter out certain NPCs when determining of an NPC is "alive" and/or should keep the
+ * doors open.
+ */
+const NON_ALIVE_NPCS_TYPE_VARIANT_SUBTYPE: ReadonlySet<string> = new Set([
+  `${EntityType.CHARGER}.${ChargerVariant.CHARGER}.${ChargerSubType.MY_SHADOW}`, // 23.0.1
+  `${EntityType.MOTHER}.${MotherVariant.MOTHER_1}.${MotherSubType.PHASE_2}`, // 912
+]);
+
+/**
+ * Helper function to make an NPC fire a projectile. Returns the fired projectile. Use this function
+ * instead of the `EntityNPC.FireProjectiles` method, since that returns void.
+ *
+ * @param npc The NPC to fire the projectile from.
+ * @param position The staring position of the projectile.
+ * @param velocity The starting velocity of the projectile.
+ * @param projectilesMode The mode of the projectile. Optional. Default is
+ *                        `ProjectilesMode.ONE_PROJECTILE`.
+ * @param projectileParams The parameters of the projectile. Optional. Default is
+ *                         `ProjectileParams()`.
+ * @returns The fired projectile.
+ */
+export function fireProjectiles(
+  npc: EntityNPC,
+  position: Vector,
+  velocity: Vector,
+  projectilesMode: ProjectilesMode = ProjectilesMode.ONE_PROJECTILE,
+  projectileParams: ProjectileParams = ProjectileParams(),
+): EntityProjectile[] {
+  const oldProjectiles = getProjectiles(projectileParams.Variant);
+  npc.FireProjectiles(position, velocity, projectilesMode, projectileParams);
+  const newProjectiles = getProjectiles(projectileParams.Variant);
+
+  return getFilteredNewEntities(oldProjectiles, newProjectiles);
+}
+
+/**
+ * Helper function to get all of the non-dead NPCs in the room.
+ *
+ * This function will not include NPCs on an internal blacklist, such as Death's scythes or Big Horn
+ * holes.
+ */
+export function getAliveNPCs(
+  matchingEntityType?: EntityType,
+  matchingVariant?: int,
+  matchingSubType?: int,
+  ignoreFriendly = false,
+): EntityNPC[] {
+  const npcs = getNPCs(
+    matchingEntityType,
+    matchingVariant,
+    matchingSubType,
+    ignoreFriendly,
+  );
+  return npcs.filter((npc) => !npc.IsDead() && !isAliveExceptionNPC(npc));
+}
+
+/**
+ * Checks for specific NPCs that have "CanShutDoors" set to true naturally by the game, but should
+ * not actually keep the doors closed (like Death's scythes).
+ */
+export function isAliveExceptionNPC(npc: EntityNPC): boolean {
+  const entityTypeVariant = `${npc.Type}.${npc.Variant}`;
+  if (NON_ALIVE_NPCS_TYPE_VARIANT.has(entityTypeVariant)) {
+    return true;
+  }
+
+  const entityTypeVariantSubType = `${npc.Type}.${npc.Variant}.${npc.SubType}`;
+  if (NON_ALIVE_NPCS_TYPE_VARIANT_SUBTYPE.has(entityTypeVariantSubType)) {
+    return true;
+  }
+
+  if (isRaglingDeathPatch(npc)) {
+    return true;
+  }
+
+  if (isDyingEggyWithNoSpidersLeft(npc)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Helper function to detect the custom death state of an Eggy. Eggies are never actually marked
+ * dead by the game. Instead, when Eggies take fatal damage, they go into NpcState.STATE_SUICIDE and
+ * spawn 14 Swarm Spiders while their StateFrame ticks upwards.
+ */
+export function isDyingEggyWithNoSpidersLeft(npc: EntityNPC): boolean {
+  return (
+    npc.State === NpcState.SUICIDE &&
+    npc.StateFrame >= EGGY_STATE_FRAME_OF_FINAL_SPIDER
+  );
+}
+
+/**
+ * Helper function to detect the custom death state of a Rag Man Ragling. When Rag Man Raglings die,
+ * they turn into a patch on the ground and can be revived by Rag Man at a later time. This causes
+ * them to show up as an "alive" enemy, so they should usually be filtered out of lists of alive
+ * enemies.
+ */
+export function isRaglingDeathPatch(npc: EntityNPC): boolean {
+  return (
+    npc.Type === EntityType.RAGLING &&
+    npc.Variant === (RaglingVariant.RAG_MANS_RAGLING as int) &&
+    // They go to `STATE_SPECIAL` when they are patches on the ground.
+    npc.State === NpcState.SPECIAL
+  );
+}

package/src/functions/pickupVariants.ts

@@ -0,0 +1,60 @@
+/* eslint-disable sort-exports/sort-exports */
+
+import { PickupVariant } from "isaac-typescript-definitions";
+
+/** For PickupVariant.HEART (10) */
+export function isHeart(pickup: EntityPickup): pickup is EntityPickupHeart {
+  return pickup.Variant === PickupVariant.HEART;
+}
+
+/** For PickupVariant.COIN (20) */
+export function isCoin(pickup: EntityPickup): pickup is EntityPickupCoin {
+  return pickup.Variant === PickupVariant.COIN;
+}
+
+/** For PickupVariant.KEY (30) */
+export function isKey(pickup: EntityPickup): pickup is EntityPickupKey {
+  return pickup.Variant === PickupVariant.KEY;
+}
+
+/** For PickupVariant.BOMB (40) */
+export function isBomb(pickup: EntityPickup): pickup is EntityPickupBomb {
+  return pickup.Variant === PickupVariant.BOMB;
+}
+
+/** For PickupVariant.POOP (42) */
+export function isPoop(pickup: EntityPickup): pickup is EntityPickupPoop {
+  return pickup.Variant === PickupVariant.POOP;
+}
+
+/** For PickupVariant.POOP (42) */
+export function isSack(pickup: EntityPickup): pickup is EntityPickupSack {
+  return pickup.Variant === PickupVariant.SACK;
+}
+
+/** For PickupVariant.PILL (70) */
+export function isPill(pickup: EntityPickup): pickup is EntityPickupPill {
+  return pickup.Variant === PickupVariant.PILL;
+}
+
+/** For PickupVariant.LIL_BATTERY (90) */
+export function isBattery(pickup: EntityPickup): pickup is EntityPickupBattery {
+  return pickup.Variant === PickupVariant.LIL_BATTERY;
+}
+
+/** For PickupVariant.COLLECTIBLE (100) */
+export function isCollectible(
+  pickup: EntityPickup,
+): pickup is EntityPickupCollectible {
+  return pickup.Variant === PickupVariant.COLLECTIBLE;
+}
+
+/** For PickupVariant.TAROT_CARD (300) */
+export function isCardPickup(pickup: EntityPickup): pickup is EntityPickupCard {
+  return pickup.Variant === PickupVariant.TAROT_CARD;
+}
+
+/** For PickupVariant.TRINKET (350) */
+export function isTrinket(pickup: EntityPickup): pickup is EntityPickupTrinket {
+  return pickup.Variant === PickupVariant.TRINKET;
+}