isaacscript-common 6.13.0 → 6.16.0

package/src/functions/kColor.ts

@@ -1,101 +1,87 @@
 import { SerializationBrand } from "../enums/private/SerializationBrand";
-import { SerializationType } from "../enums/SerializationType";
 import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
+import { getRandom } from "./random";
+import { getRandomSeed, isRNG, newRNG } from "./rng";
 import { copyValuesToTable, getNumbersFromTable, tableHasKeys } from "./table";
 import { isTable } from "./types";
 
-type SerializedKColor = LuaMap<string, unknown> & {
+export type SerializedKColor = LuaMap<string, unknown> & {
   readonly __serializedKColorBrand: symbol;
 };
 
-interface CopyKColorReturn {
-  [SerializationType.NONE]: KColor;
-  [SerializationType.SERIALIZE]: SerializedKColor;
-  [SerializationType.DESERIALIZE]: KColor;
-}
-
 const KEYS = ["Red", "Green", "Blue", "Alpha"];
 const OBJECT_NAME = "KColor";
 
+/** Helper function to copy a `KColor` Isaac API class. */
+export function copyKColor(kColor: KColor): KColor {
+  if (!isKColor(kColor)) {
+    error(
+      `Failed to copy a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`,
+    );
+  }
+
+  return KColor(kColor.Red, kColor.Green, kColor.Blue, kColor.Alpha);
+}
+
 /**
- * Helper function to copy a `KColor` object.
- *
- * @param kColor The KColor object to copy. In the case of deserialization, this will actually be a
- *               Lua table instead of an instantiated KColor class.
- * @param serializationType Default is `SerializationType.NONE`.
+ * Helper function to convert a `SerializedKColor` object to a normal `KColor` object. (This is used
+ * by the save data manager when reading data from the "save#.dat" file.)
  */
-export function copyKColor<
-  K extends KColor | SerializedKColor,
-  S extends SerializationType,
->(kColor: K, serializationType: S): CopyKColorReturn[S];
-export function copyKColor<K extends KColor | SerializedKColor>(
-  kColor: K,
-): CopyKColorReturn[SerializationType.NONE];
-export function copyKColor(
-  kColor: KColor | SerializedKColor,
-  serializationType = SerializationType.NONE,
-): CopyKColorReturn[keyof CopyKColorReturn] {
-  switch (serializationType) {
-    case SerializationType.NONE: {
-      if (!isKColor(kColor)) {
-        error(
-          `Failed to copy a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`,
-        );
-      }
-
-      return KColor(kColor.Red, kColor.Green, kColor.Blue, kColor.Alpha);
-    }
-
-    case SerializationType.SERIALIZE: {
-      if (!isKColor(kColor)) {
-        error(
-          `Failed to serialize a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`,
-        );
-      }
-
-      const kColorTable = new LuaMap<string, unknown>();
-      copyValuesToTable(kColor, KEYS, kColorTable);
-      kColorTable.set(SerializationBrand.K_COLOR, "");
-      return kColorTable as SerializedKColor;
-    }
-
-    case SerializationType.DESERIALIZE: {
-      if (!isTable(kColor)) {
-        error(
-          `Failed to deserialize a ${OBJECT_NAME} object since the provided object was not a Lua table.`,
-        );
-      }
-
-      const [r, g, b, a] = getNumbersFromTable(
-        kColor as LuaMap<string, unknown>,
-        OBJECT_NAME,
-        ...KEYS,
-      );
-
-      if (r === undefined) {
-        error(
-          `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: r`,
-        );
-      }
-      if (g === undefined) {
-        error(
-          `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: g`,
-        );
-      }
-      if (b === undefined) {
-        error(
-          `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: b`,
-        );
-      }
-      if (a === undefined) {
-        error(
-          `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: a`,
-        );
-      }
-
-      return KColor(r, g, b, a);
-    }
+export function deserializeKColor(kColor: SerializedKColor): KColor {
+  if (!isTable(kColor)) {
+    error(
+      `Failed to deserialize a ${OBJECT_NAME} object since the provided object was not a Lua table.`,
+    );
+  }
+
+  const [r, g, b, a] = getNumbersFromTable(
+    kColor as LuaMap<string, unknown>,
+    OBJECT_NAME,
+    ...KEYS,
+  );
+
+  if (r === undefined) {
+    error(
+      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Red`,
+    );
+  }
+  if (g === undefined) {
+    error(
+      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Green`,
+    );
+  }
+  if (b === undefined) {
+    error(
+      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Blue`,
+    );
+  }
+  if (a === undefined) {
+    error(
+      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Alpha`,
+    );
   }
+
+  return KColor(r, g, b, a);
+}
+
+/**
+ * Helper function to get a random color.
+ *
+ * @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 alpha Optional. The alpha value to use. Default is 1.
+ */
+export function getRandomKColor(
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+  alpha = 1,
+): KColor {
+  const rng = isRNG(seedOrRNG) ? seedOrRNG : newRNG(seedOrRNG);
+
+  const r = getRandom(rng);
+  const g = getRandom(rng);
+  const b = getRandom(rng);
+
+  return KColor(r, g, b, alpha);
 }
 
 /** Helper function to check if something is an instantiated KColor object. */
@@ -122,3 +108,20 @@ export function isSerializedKColor(
 export function kColorEquals(kColor1: KColor, kColor2: KColor): boolean {
   return isaacAPIClassEquals(kColor1, kColor2, KEYS);
 }
+
+/**
+ * Helper function to convert a `KColor` object to a `SerializedKColor` object. (This is used by the
+ * save data manager when writing data from the "save#.dat" file.)
+ */
+export function serializeKColor(kColor: KColor): SerializedKColor {
+  if (!isKColor(kColor)) {
+    error(
+      `Failed to serialize a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`,
+    );
+  }
+
+  const kColorTable = new LuaMap<string, unknown>();
+  copyValuesToTable(kColor, KEYS, kColorTable);
+  kColorTable.set(SerializationBrand.K_COLOR, "");
+  return kColorTable as SerializedKColor;
+}

package/src/functions/mergeTests.ts

@@ -5,7 +5,7 @@ import { deepCopy } from "./deepCopy";
 import { log } from "./log";
 import { isRNG, newRNG } from "./rng";
 import { isSerializedIsaacAPIClass } from "./serialization";
-import { copyVector, isVector } from "./vector";
+import { isVector, serializeVector } from "./vector";
 
 /**
  * Run the suite of tests that prove that the "merge" function works properly. (This function is not
@@ -92,7 +92,7 @@ function oldTableHasSerializedIsaacAPIClass() {
   const y = 60;
   const vector = Vector(x, y);
 
-  const vectorSerialized = copyVector(vector, SerializationType.SERIALIZE);
+  const vectorSerialized = serializeVector(vector);
   if (!isSerializedIsaacAPIClass(vectorSerialized)) {
     error(
       'The "isSerializedIsaacAPIClass" function says that a serialized vector is not serialized.',

package/src/functions/npcs.ts

@@ -11,13 +11,11 @@ import {
   MotherVariant,
   NpcState,
   PeepVariant,
-  ProjectilesMode,
   RaglingVariant,
   VisVariant,
 } from "isaac-typescript-definitions";
 import { EGGY_STATE_FRAME_OF_FINAL_SPIDER } from "../constants";
-import { getFilteredNewEntities } from "./entities";
-import { getNPCs, getProjectiles } from "./entitiesSpecific";
+import { getNPCs } from "./entitiesSpecific";
 
 /**
  * Used to filter out certain NPCs when determining of an NPC is "alive" and/or should keep the
@@ -46,33 +44,6 @@ const NON_ALIVE_NPCS_TYPE_VARIANT_SUBTYPE: ReadonlySet<string> = new Set([
   `${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.
  *
@@ -149,31 +120,3 @@ export function isRaglingDeathPatch(npc: EntityNPC): boolean {
     npc.State === NpcState.SPECIAL
   );
 }
-
-/**
- * The base game `EntityNPC.FireProjectiles` method does not return anything, which is a problem in
- * situations where you need to work with the fired projectiles. This function invokes that method,
- * and then returns the projectiles that were spawned.
- *
- * @param npc The EntityNPC firing projectiles.
- * @param position The starting position of the projectiles.
- * @param velocity The starting velocity of the projectiles.
- * @param projectilesMode A ProjectilesMode enum value defining how to fire the projectiles.
- * @param projectileParams A ProjectileParams object containing various parameters for the
- *                         projectiles.
- * @returns An array of EntityProjectiles containing all fired projectiles.
- */
-export function npcFireProjectiles(
-  npc: EntityNPC,
-  position: Vector,
-  velocity: Vector,
-  projectilesMode: ProjectilesMode,
-  projectileParams: ProjectileParams,
-): EntityProjectile[] {
-  const oldEntities = getProjectiles();
-  npc.FireProjectiles(position, velocity, projectilesMode, projectileParams);
-  const newEntities = getProjectiles();
-  const filteredNewEntities = getFilteredNewEntities(oldEntities, newEntities);
-
-  return filteredNewEntities;
-}

package/src/functions/projectiles.ts

@@ -0,0 +1,78 @@
+import {
+  EntityFlag,
+  EntityType,
+  ProjectilesMode,
+} from "isaac-typescript-definitions";
+import { getFilteredNewEntities } from "./entities";
+import { getProjectiles, spawnNPC } from "./entitiesSpecific";
+
+/**
+ * Helper function to make an NPC fire one or more projectiles. Returns the fired projectile(s).
+ *
+ * Use this function instead of the `EntityNPC.FireProjectiles` method if you need to modify or
+ * access the `EntityProjectile` objects after they are fired, since this function returns the
+ * objects in an array.
+ *
+ * @param npc The NPC to fire the projectile(s) from. You can also pass undefined if you do not want
+ *            the projectile(s) to come from anything in particular.
+ * @param position The staring position of the projectile(s).
+ * @param velocity The starting velocity of the projectile(s).
+ * @param projectilesMode Optional. The mode of the projectile(s). Default is
+ *                        `ProjectilesMode.ONE_PROJECTILE`.
+ * @param projectileParams Optional. The parameters of the projectile(s). Default is
+ *                         `ProjectileParams()`.
+ * @returns The fired projectile(s).
+ */
+export function fireProjectiles(
+  npc: EntityNPC | undefined,
+  position: Vector,
+  velocity: Vector,
+  projectilesMode: ProjectilesMode = ProjectilesMode.ONE_PROJECTILE,
+  projectileParams: ProjectileParams = ProjectileParams(),
+): EntityProjectile[] {
+  const oldProjectiles = getProjectiles(projectileParams.Variant);
+
+  let spawnedFly = false;
+  if (npc === undefined) {
+    // Since the `EntityNPC.FireProjectiles` method is not static, we arbitrarily spawn a fly.
+    spawnedFly = true;
+    npc = spawnNPC(EntityType.FLY, 0, 0, position);
+    npc.Visible = false;
+    npc.ClearEntityFlags(EntityFlag.APPEAR);
+  }
+
+  npc.FireProjectiles(position, velocity, projectilesMode, projectileParams);
+  const newProjectiles = getProjectiles(projectileParams.Variant);
+
+  if (spawnedFly) {
+    npc.Remove();
+  }
+
+  return getFilteredNewEntities(oldProjectiles, newProjectiles);
+}
+
+/**
+ * Helper function to spawn projectiles in a circle around a position. Under the hood, this
+ * leverages `ProjectileMode.N_PROJECTILES_IN_CIRCLE`.
+ *
+ * @param npc The NPC to fire the projectile(s) from. You can also pass undefined if you do not want
+ *            the projectile(s) to come from anything in particular.
+ * @param position The staring position of the projectile(s).
+ * @param speed The speed of the projectile(s).
+ * @param numProjectiles The amount of projectiles to spawn.
+ * @returns The fired projectile(s).
+ */
+export function fireProjectilesInCircle(
+  npc: EntityNPC | undefined,
+  position: Vector,
+  speed: float,
+  numProjectiles: int,
+): EntityProjectile[] {
+  const velocity = Vector(speed, numProjectiles);
+  return fireProjectiles(
+    npc,
+    position,
+    velocity,
+    ProjectilesMode.N_PROJECTILES_IN_CIRCLE,
+  );
+}

package/src/functions/random.ts

@@ -45,7 +45,7 @@ export function getRandomFloat(
 /**
  * This returns a random integer between min and max. It is inclusive on both ends.
  *
- * Note that this function will invoke the `Next` method on the `RNG` object before returning the
+ * Note that this function will run the `Next` method on the `RNG` object before returning the
  * random number.
  *
  * For example:

package/src/functions/rng.ts

@@ -1,20 +1,13 @@
 import { game } from "../cachedClasses";
 import { SerializationBrand } from "../enums/private/SerializationBrand";
-import { SerializationType } from "../enums/SerializationType";
 import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
 import { getNumbersFromTable, tableHasKeys } from "./table";
 import { isTable } from "./types";
 
-type SerializedRNG = LuaMap<string, unknown> & {
+export type SerializedRNG = LuaMap<string, unknown> & {
   readonly __serializedRNGBrand: symbol;
 };
 
-interface CopyRNGReturn {
-  [SerializationType.NONE]: RNG;
-  [SerializationType.SERIALIZE]: SerializedRNG;
-  [SerializationType.DESERIALIZE]: RNG;
-}
-
 /**
  * This is the ShiftIdx that Blade recommended after having reviewing the game's internal functions.
  * Any value between 0 and 80 should work equally well.
@@ -25,66 +18,35 @@ const RECOMMENDED_SHIFT_IDX = 35;
 const KEYS = ["seed"];
 const OBJECT_NAME = "RNG";
 
-/**
- * Helper function to copy an `RNG` object.
- *
- * @param rng The RNG object to copy. In the case of deserialization, this will actually be a Lua
- *            table instead of an instantiated RNG class.
- * @param serializationType Default is `SerializationType.NONE`.
- */
-export function copyRNG<
-  R extends RNG | SerializedRNG,
-  S extends SerializationType,
->(rng: R, serializationType: S): CopyRNGReturn[S];
-export function copyRNG<R extends RNG | SerializedRNG>(
-  rng: R,
-): CopyRNGReturn[SerializationType.NONE];
-export function copyRNG(
-  rng: RNG | SerializedRNG,
-  serializationType = SerializationType.NONE,
-): CopyRNGReturn[keyof CopyRNGReturn] {
-  switch (serializationType) {
-    case SerializationType.NONE: {
-      if (!isRNG(rng)) {
-        error(
-          `Failed to copy a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`,
-        );
-      }
-
-      const seed = rng.GetSeed();
-      return newRNG(seed);
-    }
+/** Helper function to copy an `RNG` Isaac API class. */
+export function copyRNG(rng: RNG): RNG {
+  if (!isRNG(rng)) {
+    error(
+      `Failed to copy a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`,
+    );
+  }
 
-    case SerializationType.SERIALIZE: {
-      if (!isRNG(rng)) {
-        error(
-          `Failed to serialize a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`,
-        );
-      }
-
-      const seed = rng.GetSeed();
-      const rngTable = new LuaMap<string, unknown>();
-      rngTable.set("seed", seed);
-      rngTable.set(SerializationBrand.RNG, "");
-      return rngTable as SerializedRNG;
-    }
+  const seed = rng.GetSeed();
+  return newRNG(seed);
+}
 
-    case SerializationType.DESERIALIZE: {
-      if (!isTable(rng)) {
-        error(
-          `Failed to deserialize a ${OBJECT_NAME} object since the provided object was not a Lua table.`,
-        );
-      }
-
-      const [seedNumber] = getNumbersFromTable(
-        rng as LuaMap<string, unknown>,
-        OBJECT_NAME,
-        ...KEYS,
-      );
-      const seed = seedNumber as Seed;
-      return newRNG(seed);
-    }
+/**
+ * Helper function to convert a `SerializedRNG` object to a normal `RNG` object. (This is used by
+ * the save data manager when reading data from the "save#.dat" file.)
+ */
+export function deserializeRNG(rng: SerializedRNG): RNG {
+  if (!isTable(rng)) {
+    error(
+      `Failed to deserialize a ${OBJECT_NAME} object since the provided object was not a Lua table.`,
+    );
   }
+
+  const [seed] = getNumbersFromTable(
+    rng as LuaMap<string, unknown>,
+    OBJECT_NAME,
+    ...KEYS,
+  );
+  return newRNG(seed as Seed);
 }
 
 /**
@@ -130,6 +92,24 @@ export function rngEquals(rng1: RNG, rng2: RNG): boolean {
   return isaacAPIClassEquals(rng1, rng2, KEYS);
 }
 
+/**
+ * Helper function to convert a `RNG` object to a `SerializedRNG` object. (This is used by the save
+ * data manager when writing data from the "save#.dat" file.)
+ */
+export function serializeRNG(rng: RNG): SerializedRNG {
+  if (!isRNG(rng)) {
+    error(
+      `Failed to serialize a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`,
+    );
+  }
+
+  const seed = rng.GetSeed();
+  const rngTable = new LuaMap<string, unknown>();
+  rngTable.set("seed", seed);
+  rngTable.set(SerializationBrand.RNG, "");
+  return rngTable as SerializedRNG;
+}
+
 /**
  * Helper function to iterate over the provided object and set the seed for all of the values that
  * are RNG objects equal to a particular seed.