isaacscript-common 2.3.0 → 2.3.1

package/src/functions/rng.ts

@@ -1,177 +0,0 @@
-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

@@ -1,199 +0,0 @@
-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

@@ -1,109 +0,0 @@
-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

@@ -1,80 +0,0 @@
-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);
-}