isaacscript-common 2.2.0 → 2.3.0

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,65 @@
+import { IsaacAPIClass } from "../types/private/IsaacAPIClass";
+
+/**
+ * Helper function to get the type of a class from the Isaac API. This is contained within the
+ * "__type" metatable key. In this context, the type of the class is equivalent to the name.
+ *
+ * For example, a `Vector` class is has a type of "Vector".
+ *
+ * Returns undefined if the object is not of type `userdata` or if the "__type" metatable key does
+ * not exist.
+ */
+export function getIsaacAPIClassType(object: unknown): string | undefined {
+  const objectType = type(object);
+  if (objectType !== "userdata") {
+    return undefined;
+  }
+
+  const metatable = getmetatable(object) as LuaTable<string, unknown>;
+  if (metatable === undefined) {
+    return undefined;
+  }
+
+  const classType = metatable.get("__type");
+  if (typeof classType !== "string") {
+    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 = getIsaacAPIClassType(object);
+  return isaacAPIClassType !== undefined;
+}
+
+export function isIsaacAPIClassOfType(
+  object: unknown,
+  classType: string,
+): boolean {
+  const isaacAPIClassType = getIsaacAPIClassType(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, table: unknown) {
+  return json.encode(table);
+}
+
+/**
+ * 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(table: unknown): string {
+  const [ok, jsonStringOrErrMsg] = pcall(tryEncode, table);
+  if (!ok) {
+    error(`Failed to convert the Lua table to JSON: ${jsonStringOrErrMsg}`);
+  }
+
+  return jsonStringOrErrMsg;
+}

package/src/functions/jsonRoom.ts

@@ -0,0 +1,100 @@
+import { JSONRoom } from "../interfaces/JSONRoom";
+import { sumArray } from "./array";
+import { log } from "./log";
+import { getRandomFloat } from "./random";
+import { getRandomSeed } from "./rng";
+
+export function getJSONRoomOfVariant(
+  jsonRooms: 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];
+  }
+
+  return error(
+    `Found ${jsonRoomsOfVariant.length} JSON rooms with a variant of ${variant}, when there should only be 1.`,
+  );
+}
+
+export function getJSONRoomsOfSubType(
+  jsonRooms: 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
+ */
+export function getRandomJSONRoom(
+  jsonRooms: 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[]) {
+  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[],
+  chosenWeight: float,
+) {
+  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;
+  }
+
+  return error(`Failed to get a JSON room with chosen weight: ${chosenWeight}`);
+}

package/src/functions/kColor.ts

@@ -0,0 +1,130 @@
+import { SerializationBrand } from "../enums/private/SerializationBrand";
+import { SerializationType } from "../enums/SerializationType";
+import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
+import { copyValuesToTable, getNumbersFromTable, tableHasKeys } from "./table";
+import { ensureAllCases } from "./utils";
+
+type SerializedKColor = LuaTable<string, unknown> & {
+  __serializedKColorBrand: void;
+};
+
+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: {
+      const kColorType = type(kColor);
+      if (isKColor(kColor) || kColorType !== "table") {
+        error(
+          `Failed to deserialize a ${OBJECT_NAME} object since the provided object was not a Lua table.`,
+        );
+      }
+
+      const [r, g, b, a] = getNumbersFromTable(kColor, 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);
+    }
+
+    default: {
+      return ensureAllCases(serializationType);
+    }
+  }
+}
+
+/** Returns `KColor(1, 1, 1, 1)`. */
+export function getDefaultKColor(): KColor {
+  return KColor(1, 1, 1, 1);
+}
+
+/** 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 {
+  const objectType = type(object);
+  if (objectType !== "table") {
+    return false;
+  }
+
+  const table = object as LuaTable<AnyNotNil, unknown>;
+  return tableHasKeys(table, ...KEYS) && table.has(SerializationBrand.K_COLOR);
+}
+
+export function kColorEquals(kColor1: KColor, kColor2: KColor): boolean {
+  return isaacAPIClassEquals(kColor1, kColor2, KEYS);
+}

package/src/functions/language.ts

@@ -0,0 +1,13 @@
+import { LANGUAGE_NAMES } from "../objects/languageNames";
+
+/**
+ * Helper function to convert the language abbreviation from `Options.Language` to the "full"
+ * language name.
+ *
+ * For example, if the current language is set to Korean, `Options.Language` will be set to "kr",
+ * and this function will return "Korean".
+ */
+export function getLanguageName(): string {
+  const languageAbbreviation = Options.Language;
+  return LANGUAGE_NAMES[languageAbbreviation];
+}

package/src/functions/level.ts

@@ -0,0 +1,31 @@
+import { DoorSlot } from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { getEnumValues } from "./enums";
+import {
+  getNumRooms,
+  getRooms,
+  isDoorSlotValidAtGridIndexForRedRoom,
+} from "./rooms";
+
+export function fillLevelWithRedRooms(): void {
+  const level = game.GetLevel();
+
+  let numRooms: int;
+  do {
+    const rooms = getRooms();
+    numRooms = rooms.length;
+
+    for (const roomDescriptor of rooms) {
+      for (const doorSlot of getEnumValues(DoorSlot)) {
+        if (
+          isDoorSlotValidAtGridIndexForRedRoom(
+            doorSlot,
+            roomDescriptor.GridIndex,
+          )
+        ) {
+          level.MakeRedRoomDoor(roomDescriptor.GridIndex, doorSlot);
+        }
+      }
+    }
+  } while (numRooms !== getNumRooms());
+}