isaacscript-common 6.6.1-dev.1 → 6.6.1-dev.5

package/src/functions/gridEntitySpecific.ts

@@ -0,0 +1,143 @@
+import {
+  CrawlSpaceState,
+  GridEntityType,
+  PressurePlateState,
+  TrapdoorVariant,
+} from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { getGridEntities, getMatchingGridEntities } from "./gridEntity";
+
+/**
+ * Helper function to get all of the grid entities of type `GridEntityType.TRAPDOOR` in the room.
+ * Specify a specific trapdoor variant to select only trapdoors of that variant.
+ */
+export function getCrawlSpaces(
+  crawlSpaceVariant?: CrawlSpaceState,
+): GridEntity[] {
+  if (crawlSpaceVariant === undefined) {
+    return getGridEntities(GridEntityType.CRAWL_SPACE);
+  }
+
+  return getMatchingGridEntities(GridEntityType.CRAWL_SPACE, crawlSpaceVariant);
+}
+
+/** Helper function to get all of the `GridEntityPit` in the room. */
+export function getPits(): GridEntityPit[] {
+  const gridEntities = getGridEntities();
+
+  const pits: GridEntityPit[] = [];
+  for (const gridEntity of gridEntities) {
+    const pit = gridEntity.ToPit();
+    if (pit !== undefined) {
+      pits.push(pit);
+    }
+  }
+
+  return pits;
+}
+
+/** Helper function to get all of the `GridEntityPoop` in the room. */
+export function getPoops(): GridEntityPoop[] {
+  const gridEntities = getGridEntities();
+
+  const poops: GridEntityPoop[] = [];
+  for (const gridEntity of gridEntities) {
+    const poop = gridEntity.ToPoop();
+    if (poop !== undefined) {
+      poops.push(poop);
+    }
+  }
+
+  return poops;
+}
+
+/** Helper function to get all of the `GridEntityPressurePlate` in the room. */
+export function getPressurePlates(): GridEntityPressurePlate[] {
+  const gridEntities = getGridEntities();
+
+  const pressurePlates: GridEntityPressurePlate[] = [];
+  for (const gridEntity of gridEntities) {
+    const pressurePlate = gridEntity.ToPressurePlate();
+    if (pressurePlate !== undefined) {
+      pressurePlates.push(pressurePlate);
+    }
+  }
+
+  return pressurePlates;
+}
+
+/** Helper function to get all of the `GridEntityRock` in the room. */
+export function getRocks(): GridEntityRock[] {
+  const gridEntities = getGridEntities();
+
+  const rocks: GridEntityRock[] = [];
+  for (const gridEntity of gridEntities) {
+    const rock = gridEntity.ToRock();
+    if (rock !== undefined) {
+      rocks.push(rock);
+    }
+  }
+
+  return rocks;
+}
+
+/** Helper function to get all of the `GridEntitySpikes` in the room. */
+export function getSpikes(): GridEntitySpikes[] {
+  const gridEntities = getGridEntities();
+
+  const spikes: GridEntitySpikes[] = [];
+  for (const gridEntity of gridEntities) {
+    const spike = gridEntity.ToSpikes();
+    if (spike !== undefined) {
+      spikes.push(spike);
+    }
+  }
+
+  return spikes;
+}
+
+/** Helper function to get all of the `GridEntityTNT` in the room. */
+export function getTNT(): GridEntityTNT[] {
+  const gridEntities = getGridEntities();
+
+  const tntArray: GridEntityTNT[] = [];
+  for (const gridEntity of gridEntities) {
+    const tnt = gridEntity.ToTNT();
+    if (tnt !== undefined) {
+      tntArray.push(tnt);
+    }
+  }
+
+  return tntArray;
+}
+
+/**
+ * Helper function to get all of the grid entities of type `GridEntityType.TRAPDOOR` in the room.
+ * Specify a specific trapdoor variant to select only trapdoors of that variant.
+ */
+export function getTrapdoors(trapdoorVariant?: TrapdoorVariant): GridEntity[] {
+  if (trapdoorVariant === undefined) {
+    return getGridEntities(GridEntityType.TRAPDOOR);
+  }
+
+  return getMatchingGridEntities(GridEntityType.TRAPDOOR, trapdoorVariant);
+}
+
+/**
+ * Helper function to determine if all of the pressure plates in the current room are pushed.
+ * Returns true if there are no pressure plates in the room.
+ */
+export function isAllPressurePlatesPushed(): boolean {
+  const room = game.GetRoom();
+  const hasPressurePlates = room.HasTriggerPressurePlates();
+
+  if (!hasPressurePlates) {
+    return true;
+  }
+
+  const pressurePlates = getPressurePlates();
+  return pressurePlates.every(
+    (pressurePlate) =>
+      pressurePlate.State === PressurePlateState.PRESSURE_PLATE_PRESSED,
+  );
+}

package/src/functions/input.ts

@@ -0,0 +1,139 @@
+import {
+  ButtonAction,
+  Controller,
+  ControllerIndex,
+  Keyboard,
+} from "isaac-typescript-definitions";
+import { MAX_NUM_INPUTS } from "../constants";
+import { copySet } from "./set";
+import { trimPrefix } from "./string";
+import { erange } from "./utils";
+
+const MODIFIER_KEYS: readonly Keyboard[] = [
+  Keyboard.LEFT_SHIFT, // 340
+  Keyboard.LEFT_CONTROL, // 341
+  Keyboard.LEFT_ALT, // 342
+  Keyboard.LEFT_SUPER, // 343
+  Keyboard.RIGHT_SHIFT, // 344
+  Keyboard.RIGHT_CONTROL, // 345
+  Keyboard.RIGHT_ALT, // 346
+  Keyboard.RIGHT_SUPER, // 347
+];
+
+const MOVEMENT_ACTIONS: readonly ButtonAction[] = [
+  ButtonAction.LEFT, // 0
+  ButtonAction.RIGHT, // 1
+  ButtonAction.UP, // 2
+  ButtonAction.DOWN, // 3
+];
+
+const MOVEMENT_ACTIONS_SET: ReadonlySet<ButtonAction> = new Set(
+  MOVEMENT_ACTIONS,
+);
+
+const SHOOTING_ACTIONS: readonly ButtonAction[] = [
+  ButtonAction.SHOOT_LEFT, // 4
+  ButtonAction.SHOOT_RIGHT, // 5
+  ButtonAction.SHOOT_UP, // 6
+  ButtonAction.SHOOT_DOWN, // 7
+];
+
+const SHOOTING_ACTIONS_SET: ReadonlySet<ButtonAction> = new Set(
+  SHOOTING_ACTIONS,
+);
+
+/** Helper function to get the enum name for the specified `Controller` value. */
+export function controllerToString(controller: Controller): string {
+  const key = Controller[controller];
+  if (key === undefined) {
+    return "unknown";
+  }
+
+  return trimPrefix(key, "BUTTON_");
+}
+
+export function getMoveActions(): Set<ButtonAction> {
+  return copySet(MOVEMENT_ACTIONS_SET);
+}
+
+export function getShootActions(): Set<ButtonAction> {
+  return copySet(SHOOTING_ACTIONS_SET);
+}
+
+/** Iterates over all inputs to determine if a particular button is pressed (i.e. held down). */
+export function isActionPressedOnAnyInput(buttonAction: ButtonAction): boolean {
+  const validInputs = erange(MAX_NUM_INPUTS);
+  return validInputs.some((input) =>
+    Input.IsActionPressed(buttonAction, input),
+  );
+}
+
+/**
+ * Iterates over all inputs to determine if a particular button is triggered (i.e. held down and
+ * then released).
+ */
+export function isActionTriggeredOnAnyInput(
+  buttonAction: ButtonAction,
+): boolean {
+  const validInputs = erange(MAX_NUM_INPUTS);
+  return validInputs.some((input) =>
+    Input.IsActionTriggered(buttonAction, input),
+  );
+}
+
+/**
+ * Helper function to see if a particular keyboard key is being pressed down by the player.
+ *
+ * This function is variadic, meaning you can pass as many keyboard values as you want to check for.
+ * This function will return true if any of the values are pressed.
+ */
+export function isKeyboardPressed(...keys: Keyboard[]): boolean {
+  return keys.some((key) =>
+    Input.IsButtonPressed(key, ControllerIndex.KEYBOARD),
+  );
+}
+
+/**
+ * Helper function to check if one or more modifier keys are being pressed down on the keyboard.
+ *
+ * A modifier key is defined as shift, control, alt, or Windows.
+ */
+export function isModifierKeyPressed(): boolean {
+  return isKeyboardPressed(...MODIFIER_KEYS);
+}
+
+export function isMoveAction(buttonAction: ButtonAction): boolean {
+  return MOVEMENT_ACTIONS_SET.has(buttonAction);
+}
+
+export function isMoveActionPressedOnAnyInput(): boolean {
+  return MOVEMENT_ACTIONS.some((moveAction) =>
+    isActionPressedOnAnyInput(moveAction),
+  );
+}
+
+export function isMoveActionTriggeredOnAnyInput(): boolean {
+  return MOVEMENT_ACTIONS.some((moveAction) =>
+    isActionTriggeredOnAnyInput(moveAction),
+  );
+}
+
+export function isShootAction(buttonAction: ButtonAction): boolean {
+  return SHOOTING_ACTIONS_SET.has(buttonAction);
+}
+
+export function isShootActionPressedOnAnyInput(): boolean {
+  return SHOOTING_ACTIONS.some((shootAction) =>
+    isActionPressedOnAnyInput(shootAction),
+  );
+}
+
+export function isShootActionTriggeredOnAnyInput(): boolean {
+  return SHOOTING_ACTIONS.some((shootAction) =>
+    isActionTriggeredOnAnyInput(shootAction),
+  );
+}
+
+export function keyboardToString(keyboard: Keyboard): string {
+  return Keyboard[keyboard] ?? "unknown";
+}

package/src/functions/isaacAPIClass.ts

@@ -0,0 +1,67 @@
+import { IsaacAPIClass } from "../types/private/IsaacAPIClass";
+import { isString, isUserdata } from "./types";
+
+/**
+ * Helper function to get the name of a class from the Isaac API. This is contained within the
+ * "__type" metatable key.
+ *
+ * For example, a `Vector` class is has a name of "Vector".
+ *
+ * Returns undefined if the object is not of type `userdata` or if the "__type" metatable key does
+ * not exist.
+ */
+export function getIsaacAPIClassName(object: unknown): string | undefined {
+  if (!isUserdata(object)) {
+    return undefined;
+  }
+
+  const metatable = getmetatable(object) as
+    | LuaTable<AnyNotNil, unknown>
+    | undefined;
+  if (metatable === undefined) {
+    return undefined;
+  }
+
+  const classType = metatable.get("__type");
+  if (!isString(classType)) {
+    return undefined;
+  }
+
+  return classType;
+}
+
+/**
+ * Helper function to check if something is an instantiated class from the Isaac API. (All classes
+ * from the Isaac API have a type of "userdata" in Lua with a metatable key of "__type" equal to the
+ * name of the class.)
+ */
+export function isIsaacAPIClass(object: unknown): object is IsaacAPIClass {
+  const isaacAPIClassType = getIsaacAPIClassName(object);
+  return isaacAPIClassType !== undefined;
+}
+
+export function isIsaacAPIClassOfType(
+  object: unknown,
+  classType: string,
+): boolean {
+  const isaacAPIClassType = getIsaacAPIClassName(object);
+  return (
+    isaacAPIClassType === classType ||
+    isaacAPIClassType === `const ${classType}`
+  );
+}
+
+/**
+ * Helper function to check if an instantiated Isaac API class is equal to another one of the same
+ * type. You must provide the list of keys to check for.
+ */
+export function isaacAPIClassEquals(
+  object1: unknown,
+  object2: unknown,
+  keys: string[],
+): boolean {
+  const table1 = object1 as LuaTable<AnyNotNil, unknown>;
+  const table2 = object2 as LuaTable<AnyNotNil, unknown>;
+
+  return keys.every((key) => table1.get(key) === table2.get(key));
+}

package/src/functions/jsonHelpers.ts

@@ -0,0 +1,45 @@
+import * as json from "json";
+import { logError } from "./log";
+
+function tryDecode(this: void, jsonString: string) {
+  return json.decode(jsonString) as LuaTable;
+}
+
+function tryEncode(this: void, luaTable: unknown) {
+  return json.encode(luaTable);
+}
+
+/**
+ * Converts a JSON string to a Lua table.
+ *
+ * In most cases, this function will be used for reading data from a "save#.dat" file. If decoding
+ * fails, it will return a blank Lua table instead of throwing an error. (This allows execution to
+ * continue in cases where users have no current save data or have manually removed their existing
+ * save data.)
+ */
+export function jsonDecode(jsonString: string): LuaTable<AnyNotNil, unknown> {
+  const [ok, luaTableOrErrMsg] = pcall(tryDecode, jsonString);
+  if (!ok) {
+    // Instead of throwing an error, continue execution of the callback.
+    logError(`Failed to convert the JSON string to a Lua table: ${jsonString}`);
+    return new LuaTable();
+  }
+
+  return luaTableOrErrMsg;
+}
+
+/**
+ * Converts a Lua table to a JSON string.
+ *
+ * In most cases, this function will be used for writing data to a "save#.dat" file. If encoding
+ * fails, it will throw an error to prevent writing a blank string or corrupted data to a user's
+ * "save#.dat" file.
+ */
+export function jsonEncode(luaTable: unknown): string {
+  const [ok, jsonStringOrErrMsg] = pcall(tryEncode, luaTable);
+  if (!ok) {
+    error(`Failed to convert the Lua table to JSON: ${jsonStringOrErrMsg}`);
+  }
+
+  return jsonStringOrErrMsg;
+}

package/src/functions/jsonRoom.ts

@@ -0,0 +1,184 @@
+import {
+  DoorSlotFlag,
+  DoorSlotFlagZero,
+  RoomShape,
+} from "isaac-typescript-definitions";
+import { JSONRoom } from "../interfaces/JSONRoomsFile";
+import { sumArray } from "./array";
+import { doorSlotToDoorSlotFlag, getRoomShapeDoorSlot } from "./doors";
+import { addFlag } from "./flag";
+import { log } from "./log";
+import { getRandomFloat } from "./random";
+import { getRandomSeed } from "./rng";
+
+/**
+ * Helper function to calculate what the resulting `BitFlags<DoorSlotFlag>` value would be for a
+ * given JSON room.
+ */
+export function getJSONRoomDoorSlotFlags(
+  jsonRoom: JSONRoom,
+): BitFlags<DoorSlotFlag> {
+  const roomShapeString = jsonRoom.$.shape;
+  const roomShapeNumber = tonumber(roomShapeString);
+  if (roomShapeNumber === undefined) {
+    error(
+      `Failed to parse the "shape" property of a JSON room: ${roomShapeString}`,
+    );
+  }
+  const roomShape = roomShapeNumber as RoomShape;
+
+  let doorSlotFlags = DoorSlotFlagZero;
+
+  for (const door of jsonRoom.door) {
+    const existsString = door.$.exists;
+    if (existsString !== "True" && existsString !== "False") {
+      error(
+        `Failed to parse the "exists" property of a JSON room door: ${existsString}`,
+      );
+    }
+
+    if (existsString === "False") {
+      continue;
+    }
+
+    const xString = door.$.x;
+    const x = tonumber(xString);
+    if (x === undefined) {
+      error(`Failed to parse the "x" property of a JSON room door: ${xString}`);
+    }
+
+    const yString = door.$.y;
+    const y = tonumber(yString);
+    if (y === undefined) {
+      error(`Failed to parse the "y" property of a JSON room door: ${yString}`);
+    }
+
+    const doorSlot = getRoomShapeDoorSlot(roomShape, x, y);
+    if (doorSlot === undefined) {
+      error(
+        `Failed to retrieve the door slot for a JSON room door at coordinates: [${x}, ${y}]`,
+      );
+    }
+
+    const doorSlotFlag = doorSlotToDoorSlotFlag(doorSlot);
+    doorSlotFlags = addFlag(doorSlotFlags, doorSlotFlag);
+  }
+
+  return doorSlotFlags;
+}
+
+/**
+ * Helper function to find a specific room from an array of JSON rooms.
+ *
+ * @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.)
+ */
+export function getJSONRoomOfVariant(
+  jsonRooms: JSONRoom[] | readonly JSONRoom[],
+  variant: int,
+): JSONRoom | undefined {
+  const jsonRoomsOfVariant = jsonRooms.filter((jsonRoom) => {
+    const roomVariantString = jsonRoom.$.variant;
+    const roomVariant = tonumber(roomVariantString);
+    return roomVariant === variant;
+  });
+
+  // The room variant acts as an ID for the room. We assume that there should only be a single room
+  // per variant.
+  if (jsonRoomsOfVariant.length === 0) {
+    return undefined;
+  }
+
+  if (jsonRoomsOfVariant.length === 1) {
+    return jsonRoomsOfVariant[0];
+  }
+
+  error(
+    `Found ${jsonRoomsOfVariant.length} JSON rooms with a variant of ${variant}, when there should only be 1.`,
+  );
+}
+
+/**
+ * Helper function to find all of the JSON rooms that match the sub-type provided.
+ *
+ * @param jsonRooms The array of rooms to search through.
+ * @param subType The sub-type to match.
+ */
+export function getJSONRoomsOfSubType(
+  jsonRooms: JSONRoom[] | readonly JSONRoom[],
+  subType: int,
+): JSONRoom[] {
+  return jsonRooms.filter((jsonRoom) => {
+    const roomSubTypeString = jsonRoom.$.subtype;
+    const roomSubType = tonumber(roomSubTypeString);
+    return roomSubType === subType;
+  });
+}
+
+/**
+ * Helper function to get a random JSON room from an array of JSON rooms.
+ *
+ * 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
+ *
+ * @param jsonRooms The array of rooms to random choose between.
+ * @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 verbose Optional. If specified, will write entries to the "log.txt" file that describe
+ *                what the function is doing. Default is false.
+ */
+export function getRandomJSONRoom(
+  jsonRooms: JSONRoom[] | readonly JSONRoom[],
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+  verbose = false,
+): JSONRoom {
+  const totalWeight = getTotalWeightOfJSONRooms(jsonRooms);
+  if (verbose) {
+    log(`Total weight of the JSON rooms provided: ${totalWeight}`);
+  }
+
+  const chosenWeight = getRandomFloat(0, totalWeight, seedOrRNG);
+  if (verbose) {
+    log(`Randomly chose weight for JSON room: ${chosenWeight}`);
+  }
+
+  return getJSONRoomWithChosenWeight(jsonRooms, chosenWeight);
+}
+
+function getTotalWeightOfJSONRooms(
+  jsonRooms: JSONRoom[] | readonly JSONRoom[],
+): float {
+  const weights = jsonRooms.map((jsonRoom) => {
+    const roomWeightString = jsonRoom.$.weight;
+    const roomWeight = tonumber(roomWeightString);
+    if (roomWeight === undefined) {
+      error(`Failed to parse the weight of a JSON room: ${roomWeightString}.`);
+    }
+    return roomWeight;
+  });
+
+  return sumArray(weights);
+}
+
+function getJSONRoomWithChosenWeight(
+  jsonRooms: JSONRoom[] | readonly JSONRoom[],
+  chosenWeight: float,
+): JSONRoom {
+  for (const jsonRoom of jsonRooms) {
+    const roomWeightString = jsonRoom.$.weight;
+    const roomWeight = tonumber(roomWeightString);
+    if (roomWeight === undefined) {
+      error(`Failed to parse the weight of a JSON room: ${roomWeightString}`);
+    }
+
+    if (chosenWeight < roomWeight) {
+      return jsonRoom;
+    }
+
+    chosenWeight -= roomWeight;
+  }
+
+  error(`Failed to get a JSON room with chosen weight: ${chosenWeight}`);
+}

package/src/functions/kColor.ts

@@ -0,0 +1,124 @@
+import { SerializationBrand } from "../enums/private/SerializationBrand";
+import { SerializationType } from "../enums/SerializationType";
+import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
+import { copyValuesToTable, getNumbersFromTable, tableHasKeys } from "./table";
+import { isTable } from "./types";
+
+type SerializedKColor = LuaTable<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` 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`.
+ */
+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 LuaTable<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 LuaTable<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);
+    }
+  }
+}
+
+/** Helper function to check if something is an instantiated KColor object. */
+export function isKColor(object: unknown): object is KColor {
+  return isIsaacAPIClassOfType(object, OBJECT_NAME);
+}
+
+/**
+ * Used to determine is the given table is a serialized `KColor` object created by the save data
+ * manager and/or the `deepCopy` function.
+ */
+export function isSerializedKColor(
+  object: unknown,
+): object is SerializedKColor {
+  if (!isTable(object)) {
+    return false;
+  }
+
+  return (
+    tableHasKeys(object, ...KEYS) && object.has(SerializationBrand.K_COLOR)
+  );
+}
+
+export function kColorEquals(kColor1: KColor, kColor2: KColor): boolean {
+  return isaacAPIClassEquals(kColor1, kColor2, KEYS);
+}