isaacscript-common 2.2.0 → 2.3.0

package/src/functions/rng.ts

@@ -0,0 +1,177 @@
+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 { ensureAllCases } from "./utils";
+
+type SerializedRNG = LuaTable<string, unknown> & {
+  __serializedRNGBrand: void;
+};
+
+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.
+ * https://www.jstatsoft.org/article/view/v008i14/xorshift.pdf
+ */
+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);
+    }
+
+    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 LuaTable<string, unknown>();
+      rngTable.set("seed", seed);
+      rngTable.set(SerializationBrand.RNG, "");
+      return rngTable as SerializedRNG;
+    }
+
+    case SerializationType.DESERIALIZE: {
+      const rngType = type(rng);
+      if (isRNG(rng) || rngType !== "table") {
+        error(
+          `Failed to deserialize a ${OBJECT_NAME} object since the provided object was not a Lua table.`,
+        );
+      }
+
+      const [seedNumber] = getNumbersFromTable(rng, OBJECT_NAME, ...KEYS);
+      const seed = seedNumber as Seed;
+      return newRNG(seed);
+    }
+
+    default: {
+      return ensureAllCases(serializationType);
+    }
+  }
+}
+
+/**
+ * Helper function to get a random `Seed` value to be used in spawning entities and so on. Use this
+ * instead of calling the `Random` function directly since that can return a value of 0 and crash
+ * the game.
+ */
+export function getRandomSeed(): Seed {
+  const randomNumber = Random();
+  const safeRandomNumber = randomNumber === 0 ? 1 : randomNumber;
+  return safeRandomNumber as Seed;
+}
+
+/** Helper function to check if something is an instantiated RNG object. */
+export function isRNG(object: unknown): object is RNG {
+  return isIsaacAPIClassOfType(object, OBJECT_NAME);
+}
+
+/**
+ * Used to determine is the given table is a serialized `RNG` object created by the save data
+ * manager and/or the `deepCopy` function.
+ */
+export function isSerializedRNG(object: unknown): object is SerializedRNG {
+  const objectType = type(object);
+  if (objectType !== "table") {
+    return false;
+  }
+
+  const table = object as LuaTable<AnyNotNil, unknown>;
+  return tableHasKeys(table, ...KEYS) && table.has(SerializationBrand.RNG);
+}
+
+/**
+ * Helper function to initialize an RNG object using Blade's recommended shift index.
+ *
+ * @param seed The seed to initialize it with. Default is `getRandomSeed()`.
+ */
+export function newRNG(seed = getRandomSeed()): RNG {
+  const rng = RNG();
+  setSeed(rng, seed);
+  return rng;
+}
+
+export function rngEquals(rng1: RNG, rng2: RNG): boolean {
+  return isaacAPIClassEquals(rng1, rng2, KEYS);
+}
+
+/**
+ * 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.
+ */
+export function setAllRNGToSeed(object: unknown, seed: Seed): void {
+  const objectType = type(object);
+  if (objectType !== "table") {
+    error(
+      `Failed to iterate over the object containing RNG objects since the type of the provided object was: ${objectType}`,
+    );
+  }
+  const table = object as LuaTable<string, unknown>;
+
+  for (const value of Object.values(table)) {
+    if (isRNG(value)) {
+      setSeed(value, seed);
+    }
+  }
+}
+
+/**
+ * Helper function to iterate over the provided object and set the seed for all of the values that
+ * are RNG objects equal to the start seed for the current run.
+ */
+export function setAllRNGToStartSeed(object: unknown): void {
+  const seeds = game.GetSeeds();
+  const startSeed = seeds.GetStartSeed();
+
+  setAllRNGToSeed(object, startSeed);
+}
+
+/** Helper function to set a seed to an RNG object using Blade's recommended shift index. */
+export function setSeed(rng: RNG, seed: Seed): void {
+  if (seed === 0) {
+    error(
+      "You cannot set an RNG object to a seed of 0, or the game will crash.",
+    );
+  }
+
+  // The game expects seeds in the range of 1 to 4294967295 (1^32 - 1).
+  rng.SetSeed(seed, RECOMMENDED_SHIFT_IDX);
+}

package/src/functions/roomData.ts

@@ -0,0 +1,199 @@
+import {
+  DoorSlot,
+  DoorSlotFlag,
+  RoomShape,
+  RoomType,
+  StageID,
+} from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { doorSlotFlagToDoorSlot } from "./doors";
+import { getEnumValues } from "./enums";
+import { hasFlag } from "./flag";
+
+/**
+ * Alias for the `Level.GetCurrentRoomDesc` method. Use this to make it more clear what type of
+ * `RoomDescriptor` object that you are retrieving.
+ */
+export function getCurrentRoomDescriptorReadOnly(): ReadonlyRoomDescriptor {
+  const level = game.GetLevel();
+  return level.GetCurrentRoomDesc();
+}
+
+/**
+ * Helper function to get the set of allowed door slots for the room at the supplied grid index.
+ * This corresponds to the doors that are enabled in the STB/XML file for the room.
+ */
+export function getRoomAllowedDoors(roomGridIndex?: int): Set<DoorSlot> {
+  const allowedDoors = new Set<DoorSlot>();
+
+  const roomData = getRoomData(roomGridIndex);
+  if (roomData === undefined) {
+    return allowedDoors;
+  }
+
+  const doorSlotFlags = getEnumValues(DoorSlotFlag);
+  for (const doorSlotFlag of doorSlotFlags) {
+    if (hasFlag(roomData.Doors, doorSlotFlag)) {
+      const doorSlot = doorSlotFlagToDoorSlot(doorSlotFlag);
+      allowedDoors.add(doorSlot);
+    }
+  }
+
+  return allowedDoors;
+}
+
+/**
+ * Helper function to get the room data for the provided room.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ */
+export function getRoomData(roomGridIndex?: int): RoomConfig | undefined {
+  const roomDescriptor = getRoomDescriptor(roomGridIndex);
+  return roomDescriptor.Data;
+}
+
+/**
+ * Helper function to get the descriptor for a room.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ */
+export function getRoomDescriptor(roomGridIndex?: int): RoomDescriptor {
+  const level = game.GetLevel();
+
+  if (roomGridIndex === undefined) {
+    roomGridIndex = getRoomGridIndex();
+  }
+
+  return level.GetRoomByIdx(roomGridIndex);
+}
+
+/**
+ * Helper function to get the grid index of the current room.
+ *
+ * - If the current room is inside of the grid, this function will return the `SafeGridIndex` from
+ *   the room descriptor. (The safe grid index is defined as the top-left 1x1 section that the room
+ *   overlaps with, or the top-right 1x1 section of a `RoomType.SHAPE_LTL` room.)
+ * - If the current room is outside of the grid, it will return the index from the
+ *   `Level.GetCurrentRoomIndex` method (since `SafeGridIndex` is bugged for these cases).
+ *
+ * Use this function instead of the `Level.GetCurrentRoomIndex` method directly because the latter
+ * will return the specific 1x1 quadrant that the player entered the room at. For most situations,
+ * using the safe grid index is more reliable than this.
+ *
+ * Data structures that store data per room should use the room's `ListIndex` instead of
+ * `SafeGridIndex`, since the former is unique across different dimensions.
+ */
+export function getRoomGridIndex(): int {
+  const level = game.GetLevel();
+  const currentRoomIndex = level.GetCurrentRoomIndex();
+
+  // Both `RoomDescriptor.GridIndex` and `RoomDescriptor.SafeGridIndex` will always be equal to -1
+  // for rooms outside of the grid. Thus, we revert to using the `Level.GetCurrentRoomIndex` method
+  // for these cases.
+  if (currentRoomIndex < 0) {
+    return currentRoomIndex;
+  }
+
+  const roomDescriptor = getCurrentRoomDescriptorReadOnly();
+  return roomDescriptor.SafeGridIndex;
+}
+
+/**
+ * Helper function to get the list grid index of the provided room, which is equal to the index in
+ * the `RoomList.Get` method. In other words, this is equal to the order that the room was created
+ * by the floor generation algorithm.
+ *
+ * Use this as an index for data structures that store data per room, since it is unique across
+ * different dimensions.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ */
+export function getRoomListIndex(roomGridIndex?: int): int {
+  const roomDescriptor = getRoomDescriptor(roomGridIndex);
+  return roomDescriptor.ListIndex;
+}
+
+/**
+ * Helper function to get the name of the room as it appears in the STB/XML data.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ * @returns The room name. Returns "Unknown" if the type was not found.
+ */
+export function getRoomName(roomGridIndex?: int): string {
+  const roomData = getRoomData(roomGridIndex);
+  return roomData === undefined ? "Unknown" : roomData.Name;
+}
+
+/**
+ * Helper function to get the name of the room as it appears in the STB/XML data.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ * @returns The room name. Returns "Unknown" if the type was not found.
+ */
+export function getRoomShape(roomGridIndex?: int): RoomShape | undefined {
+  const roomData = getRoomData(roomGridIndex);
+  return roomData === undefined ? undefined : roomData.Shape;
+}
+
+/**
+ * Helper function to get the stage ID for a room from the XML/STB data. The room stage ID will
+ * correspond to the first number in the filename of the XML/STB file. For example, a Depths room
+ * would have a stage ID of 7.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ * @returns The room stage ID. Returns -1 if the stage ID was not found.
+ */
+export function getRoomStageID(roomGridIndex?: int): StageID {
+  const roomData = getRoomData(roomGridIndex);
+  return roomData === undefined ? -1 : roomData.StageID;
+}
+
+/**
+ * Helper function to get the sub-type for a room from the XML/STB data. The room sub-type will
+ * correspond to different things depending on what XML/STB file it draws from. For example, in the
+ * "00.special rooms.stb" file, an Angel Room with a sub-type of 0 will correspond to a normal Angel
+ * Room and a sub-type of 1 will correspond to an Angel Room shop for The Stairway.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ * @returns The room sub-type. Returns -1 if the sub-type was not found.
+ */
+export function getRoomSubType(roomGridIndex?: int): int {
+  const roomData = getRoomData(roomGridIndex);
+  return roomData === undefined ? -1 : roomData.Subtype;
+}
+
+/**
+ * Helper function for getting the type of the room with the given grid index.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ * @returns The room data type. Returns -1 if the type was not found.
+ */
+export function getRoomType(roomGridIndex?: int): RoomType {
+  const roomData = getRoomData(roomGridIndex);
+  return roomData === undefined ? -1 : roomData.Type;
+}
+
+/**
+ * Helper function to get the variant for a room from the XML/STB data. You can think of a room
+ * variant as its identifier. For example, to go to Basement room #123, you would use a console
+ * command of `goto d.123` while on the Basement.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ * @returns The room variant. Returns -1 if the variant was not found.
+ */
+export function getRoomVariant(roomGridIndex?: int): int {
+  const roomData = getRoomData(roomGridIndex);
+  return roomData === undefined ? -1 : roomData.Variant;
+}
+
+/**
+ * Note that the room visited count will be inaccurate during the period before the PostNewRoom
+ * callback has fired (i.e. when entities are initializing and performing their first update). This
+ * is because the variable is only incremented immediately before the PostNewRoom callback fires.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ */
+export function getRoomVisitedCount(roomGridIndex?: int): int {
+  const roomDescriptor = getRoomDescriptor(roomGridIndex);
+  return roomDescriptor.VisitedCount;
+}

package/src/functions/roomGrid.ts

@@ -0,0 +1,109 @@
+import { RoomShape } from "isaac-typescript-definitions";
+import { L_ROOM_SHAPE_TO_RECTANGLES } from "../objects/LRoomShapeToRectangles";
+import { inRectangle } from "./math";
+import {
+  getRoomShapeBottomRightPosition,
+  getRoomShapeTopLeftPosition,
+  getRoomShapeWidth,
+  isLRoom,
+} from "./roomShape";
+
+/**
+ * Helper function to convert grid coordinates to a world position `Vector`.
+ *
+ * For example, the coordinates of (0, 0) are equal to `Vector(80, 160)`.
+ */
+export function gridCoordinatesToWorldPosition(x: int, y: int): Vector {
+  const gridPosition = Vector(x, y);
+  return gridPositionToWorldPosition(gridPosition);
+}
+
+/**
+ * Helper function to convert a grid index to a grid position.
+ *
+ * For example, in a 1x1 room, grid index 0 is equal to "Vector(-1, -1) and grid index 16 is equal
+ * to "Vector(0, 0)".
+ */
+export function gridIndexToGridPosition(
+  gridIndex: int,
+  roomShape: RoomShape,
+): Vector {
+  const gridWidth = getRoomShapeWidth(roomShape);
+
+  const x = (gridIndex % gridWidth) - 1;
+  const y = Math.floor(gridIndex / gridWidth) - 1;
+  return Vector(x, y);
+}
+
+/**
+ * Helper function to convert a grid position `Vector` to a world position `Vector`.
+ *
+ * For example, the coordinates of (0, 0) are equal to `Vector(80, 160)`.
+ */
+export function gridPositionToWorldPosition(gridPosition: Vector): Vector {
+  const x = (gridPosition.X + 2) * 40;
+  const y = (gridPosition.Y + 4) * 40;
+  return Vector(x, y);
+}
+
+/**
+ * Test if a grid position is actually in the given `RoomShape`.
+ *
+ * In this context, the grid position of the top-left wall is "Vector(-1, -1)".
+ */
+export function isValidGridPosition(
+  gridPosition: Vector,
+  roomShape: RoomShape,
+): boolean {
+  return isLRoom(roomShape)
+    ? isValidGridPositionLRoom(gridPosition, roomShape)
+    : isValidGridPositionNormal(gridPosition, roomShape);
+}
+
+function isValidGridPositionNormal(gridPosition: Vector, roomShape: RoomShape) {
+  const topLeft = getRoomShapeTopLeftPosition(roomShape);
+  const bottomRight = getRoomShapeBottomRightPosition(roomShape);
+  return inRectangle(gridPosition, topLeft, bottomRight);
+}
+
+function isValidGridPositionLRoom(gridPosition: Vector, roomShape: RoomShape) {
+  const rectangles = L_ROOM_SHAPE_TO_RECTANGLES[roomShape];
+  if (rectangles === undefined) {
+    return false;
+  }
+
+  const [
+    verticalTopLeft,
+    verticalBottomRight,
+    horizontalTopLeft,
+    horizontalBottomRight,
+  ] = rectangles;
+  return (
+    inRectangle(gridPosition, verticalTopLeft, verticalBottomRight) ||
+    inRectangle(gridPosition, horizontalTopLeft, horizontalBottomRight)
+  );
+}
+
+/**
+ * Helper function to convert a world position `Vector` to a grid position `Vector`.
+ *
+ * In this context, the grid position of the top-left wall is "Vector(-1, -1)".
+ */
+export function worldPositionToGridPosition(worldPos: Vector): Vector {
+  const x = Math.round(worldPos.X / 40 - 2);
+  const y = Math.round(worldPos.Y / 40 - 4);
+  return Vector(x, y);
+}
+
+/**
+ * Helper function to convert a world position `Vector` to a grid position `Vector`.
+ *
+ * In this context, the grid position of the top-left wall is "Vector(-1, -1)".
+ *
+ * This is similar to the `worldPositionToGridPosition` function, but the values are not rounded.
+ */
+export function worldPositionToGridPositionFast(worldPos: Vector): Vector {
+  const x = worldPos.X / 40 - 2;
+  const y = worldPos.Y / 40 - 4;
+  return Vector(x, y);
+}

package/src/functions/roomShape.ts

@@ -0,0 +1,80 @@
+import { DoorSlot, RoomShape } from "isaac-typescript-definitions";
+import { ROOM_SHAPE_BOUNDS } from "../objects/roomShapeBounds";
+import { ROOM_SHAPE_LAYOUT_SIZES } from "../objects/roomShapeLayoutSizes";
+import { ROOM_SHAPE_TO_BOTTOM_RIGHT_POSITION } from "../objects/roomShapeToBottomRightPosition";
+import { ROOM_SHAPE_TO_DOOR_SLOTS_TO_GRID_INDEX_DELTA } from "../objects/roomShapeToDoorSlotsToGridIndexDelta";
+import { ROOM_SHAPE_TO_GRID_WIDTH } from "../objects/roomShapeToGridWidth";
+import { ROOM_SHAPE_TO_TOP_LEFT_POSITION } from "../objects/roomShapeToTopLeftPosition";
+import { ROOM_SHAPE_VOLUMES } from "../objects/roomShapeVolumes";
+import { L_ROOM_SHAPES_SET } from "../sets/LRoomShapesSet";
+
+/**
+ * Helper function to get the grid index delta that a door out of the given room shape would lead
+ * to. For example, if you went through the bottom door in a room of `RoomShape.SHAPE_1x2`, you
+ * would end up in a room with a grid index that is +26 units from the `SafeGridIndex` of where you
+ * started.
+ */
+export function getGridIndexDelta(
+  roomShape: RoomShape,
+  doorSlot: DoorSlot,
+): int | undefined {
+  const doorSlotToGridIndexMap =
+    ROOM_SHAPE_TO_DOOR_SLOTS_TO_GRID_INDEX_DELTA[roomShape];
+  return doorSlotToGridIndexMap.get(doorSlot);
+}
+
+/**
+ * Helper function to get the grid position of the bottom-right tile of a given room shape.
+ *
+ * "Vector(0, 0)" corresponds to the top left tile of a room, not including the walls. (The top-left
+ * wall would be at "Vector(-1, -1)".)
+ */
+export function getRoomShapeBottomRightPosition(roomShape: RoomShape): Vector {
+  return ROOM_SHAPE_TO_BOTTOM_RIGHT_POSITION[roomShape];
+}
+
+/**
+ * Helper function to get the bounds of a room shape, which are a box representing its contents.
+ * This does not include the tiles that the walls are on. L rooms use the same bounds as a 2x2 room.
+ */
+export function getRoomShapeBounds(roomShape: RoomShape): Vector {
+  return ROOM_SHAPE_BOUNDS[roomShape];
+}
+
+/**
+ * Helper function to get the dimensions of a room shape's layout. This is NOT the size of the
+ * room's actual contents! For that, use the `getRoomShapeBounds` function.
+ *
+ * For example, a horizontal narrow room has a layout size of equal to that of a 1x1 room.
+ */
+export function getRoomShapeLayoutSize(roomShape: RoomShape): Vector {
+  return ROOM_SHAPE_LAYOUT_SIZES[roomShape];
+}
+
+/**
+ * Helper function to get the grid position of the top-left tile of a given room shape.
+ *
+ * "Vector(0, 0)" corresponds to the top left tile of a room, not including the walls. (The top-left
+ * wall would be at "Vector(-1, -1)".)
+ */
+export function getRoomShapeTopLeftPosition(roomShape: RoomShape): Vector {
+  return ROOM_SHAPE_TO_TOP_LEFT_POSITION[roomShape];
+}
+
+/**
+ * Helper function to get the volume of a room shape, which is the amount of tiles that are inside
+ * the room.
+ *
+ * (This cannot be directly calculated from the bounds since L rooms are a special case.)
+ */
+export function getRoomShapeVolume(roomShape: RoomShape): int {
+  return ROOM_SHAPE_VOLUMES[roomShape];
+}
+
+export function getRoomShapeWidth(roomShape: RoomShape): int {
+  return ROOM_SHAPE_TO_GRID_WIDTH[roomShape];
+}
+
+export function isLRoom(roomShape: RoomShape): boolean {
+  return L_ROOM_SHAPES_SET.has(roomShape);
+}