isaacscript-common 4.0.0 → 4.0.1-dev.0

package/functions/revive.ts

@@ -0,0 +1,201 @@
+import {
+  CollectibleType,
+  EntityType,
+  NullItemID,
+  PlayerType,
+  TrinketType,
+} from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import {
+  MAX_TAINTED_SAMSON_BERSERK_CHARGE,
+  TAINTED_SAMSON_BERSERK_CHARGE_FROM_TAKING_DAMAGE,
+} from "../constants";
+import { getCharacterDeathAnimationName } from "./character";
+import {
+  getPlayerMaxHeartContainers,
+  getPlayerNumHitsRemaining,
+  hasLostCurse,
+  isKeeper,
+} from "./player";
+import { getLastFrameOfAnimation } from "./sprite";
+import { giveTrinketsBack, temporarilyRemoveTrinket } from "./trinketGive";
+
+/**
+ * Uses the player's current health and other miscellaneous things to determine if incoming damage
+ * will be fatal.
+ */
+export function isDamageToPlayerFatal(
+  player: EntityPlayer,
+  damageAmount: int,
+  damageSource: EntityRef,
+  lastDamageGameFrame: int | undefined,
+): boolean {
+  const gameFrameCount = game.GetFrameCount();
+  const character = player.GetPlayerType();
+  const effects = player.GetEffects();
+  const isBerserk = effects.HasCollectibleEffect(CollectibleType.BERSERK);
+
+  // If we are Tainted Jacob and the damage source is Dark Esau, this will not be fatal damage
+  // (because we will transform into Tainted Jacob's lost form).
+  if (
+    character === PlayerType.JACOB_B &&
+    damageSource.Type === EntityType.DARK_ESAU
+  ) {
+    return false;
+  }
+
+  // If we are berserk, no damage is fatal. (The death is deferred until the end of the berserk
+  // effect.)
+  if (isBerserk) {
+    return false;
+  }
+
+  // If we are playing Tainted Samson and the incoming hit will cause us to become Berserk, then
+  // this will not be fatal damage.
+  const berserkChargeAfterHit =
+    player.SamsonBerserkCharge +
+    TAINTED_SAMSON_BERSERK_CHARGE_FROM_TAKING_DAMAGE;
+  if (
+    character === PlayerType.SAMSON_B &&
+    berserkChargeAfterHit >= MAX_TAINTED_SAMSON_BERSERK_CHARGE
+  ) {
+    return false;
+  }
+
+  // If Spirit Shackles is activated, no damage is fatal.
+  if (willReviveFromSpiritShackles(player)) {
+    return false;
+  }
+
+  // If we are Tainted Jacob in the Lost Form, we may have plenty of health left, but we will still
+  // die in one hit to anything.
+  if (character === PlayerType.JACOB_2_B) {
+    return true;
+  }
+
+  // If we are in the "Lost Curse" form from touching a white fire, all damage will be fatal.
+  if (hasLostCurse(player)) {
+    return true;
+  }
+
+  const playerNumAllHearts = getPlayerNumHitsRemaining(player);
+  if (damageAmount < playerNumAllHearts) {
+    return false;
+  }
+
+  // This will not be fatal damage if the player has Heartbreak and two slots open for broken
+  // hearts.
+  if (willReviveFromHeartbreak(player)) {
+    return false;
+  }
+
+  // This will not be fatal damage if we have Glass Cannon and this is the second time we are taking
+  // damage on the same frame.
+  if (
+    player.HasCollectible(CollectibleType.BROKEN_GLASS_CANNON) &&
+    gameFrameCount === lastDamageGameFrame
+  ) {
+    return false;
+  }
+
+  // This will not be fatal damage if we have two different kinds of hearts. For example, a bomb
+  // explosion deals 2 damage, but if the player has one half soul heart and one half red heart, the
+  // game will only remove the soul heart.
+  const hearts = player.GetHearts();
+  const eternalHearts = player.GetEternalHearts();
+  const soulHearts = player.GetSoulHearts();
+  const boneHearts = player.GetBoneHearts();
+  if (
+    (hearts > 0 && soulHearts > 0) ||
+    (hearts > 0 && boneHearts > 0) ||
+    (soulHearts > 0 && boneHearts > 0) ||
+    (soulHearts > 0 && eternalHearts > 0) ||
+    boneHearts >= 2 // Two bone hearts and nothing else should not result in a death
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Assuming that we are on the frame of fatal damage, this function returns whether or not
+ * Mysterious Paper would rotate to Missing Poster on the frame that the "Game Over" screen would
+ * appear (which would subsequently save the player from fatal damage).
+ *
+ * Mysterious Paper rotates between the 4 items on every frame, in order. The formula for whether
+ * Mysterious Paper be Missing Power is: `gameFrameCount % 4 === 3`
+ */
+export function willMysteriousPaperRevive(player: EntityPlayer): boolean {
+  const gameFrameCount = game.GetFrameCount();
+  const sprite = player.GetSprite();
+
+  // We want to explicitly check the length of the death animation because we might be playing on a
+  // modded character that has a custom death animation.
+  const character = player.GetPlayerType();
+  const animation = getCharacterDeathAnimationName(character);
+  const deathAnimationFrames = getLastFrameOfAnimation(sprite, animation);
+  const frameOfDeath = gameFrameCount + deathAnimationFrames + 1;
+  // (We add 1 because it takes one frame for the death animation to begin.)
+
+  return frameOfDeath % 4 === 3;
+}
+
+/**
+ * The `EntityPlayer.WillPlayerRevive` method does not properly account for Mysterious Paper, so use
+ * this helper function instead for more robust revival detection.
+ */
+export function willPlayerRevive(player: EntityPlayer): boolean {
+  const trinketSituation = temporarilyRemoveTrinket(
+    player,
+    TrinketType.MYSTERIOUS_PAPER,
+  );
+
+  const willRevive =
+    player.WillPlayerRevive() ||
+    (trinketSituation !== undefined && willMysteriousPaperRevive(player));
+
+  giveTrinketsBack(player, trinketSituation);
+
+  return willRevive;
+}
+
+/**
+ * Helper function to determine if the player will be revived by the Heartbreak collectible if they
+ * take fatal damage. This is contingent on the character that they are playing as and the amount of
+ * broken hearts that they already have.
+ */
+export function willReviveFromHeartbreak(player: EntityPlayer): boolean {
+  if (!player.HasCollectible(CollectibleType.HEARTBREAK)) {
+    return false;
+  }
+
+  const maxHeartContainers = getPlayerMaxHeartContainers(player);
+  const numBrokenHeartsThatWillBeAdded = isKeeper(player) ? 1 : 2;
+  const brokenHearts = player.GetBrokenHearts();
+  const numBrokenHeartsAfterRevival =
+    numBrokenHeartsThatWillBeAdded + brokenHearts;
+
+  return maxHeartContainers > numBrokenHeartsAfterRevival;
+}
+
+/**
+ * Helper function to determine if the Spirit Shackles item is in an enabled state. (It can be
+ * either enabled or disabled.)
+ */
+export function willReviveFromSpiritShackles(player: EntityPlayer): boolean {
+  if (!player.HasCollectible(CollectibleType.SPIRIT_SHACKLES)) {
+    return false;
+  }
+
+  const effects = player.GetEffects();
+
+  const spiritShacklesEnabled = !effects.HasNullEffect(
+    NullItemID.SPIRIT_SHACKLES_DISABLED,
+  );
+  const playerInSoulForm = effects.HasNullEffect(
+    NullItemID.SPIRIT_SHACKLES_SOUL,
+  );
+
+  return spiritShacklesEnabled && !playerInSoulForm;
+}

package/functions/rng.lua

@@ -17,8 +17,6 @@ local getNumbersFromTable = ____table.getNumbersFromTable
 local tableHasKeys = ____table.tableHasKeys
 local ____types = require("functions.types")
 local isTable = ____types.isTable
-local ____utils = require("functions.utils")
-local ensureAllCases = ____utils.ensureAllCases
 --- 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.
@@ -102,11 +100,6 @@ function ____exports.copyRNG(self, rng, serializationType)
                 return ____exports.newRNG(nil, seed)
             end
         end
-        do
-            do
-                return ensureAllCases(nil, serializationType)
-            end
-        end
     until true
 end
 --- Used to determine is the given table is a serialized `RNG` object created by the save data

package/functions/rng.ts

@@ -0,0 +1,172 @@
+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 = LuaTable<string, unknown> & {
+  readonly __serializedRNGBrand: unique 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.
+ * 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: {
+      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 LuaTable<string, unknown>,
+        OBJECT_NAME,
+        ...KEYS,
+      );
+      const seed = seedNumber as Seed;
+      return newRNG(seed);
+    }
+  }
+}
+
+/**
+ * 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 {
+  if (!isTable(object)) {
+    return false;
+  }
+
+  return tableHasKeys(object, ...KEYS) && object.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 {
+  if (!isTable(object)) {
+    error(
+      `Failed to iterate over the object containing RNG objects since the type of the provided object was: ${typeof object}`,
+    );
+  }
+
+  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/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";
+
+/**
+ * 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);
+}
+
+/**
+ * Alias for the `Level.GetCurrentRoomDesc` method. Use this to make it more clear what type of
+ * `RoomDescriptor` object that you are retrieving.
+ */
+export function getRoomDescriptorReadOnly(): ReadonlyRoomDescriptor {
+  const level = game.GetLevel();
+  return level.GetCurrentRoomDesc();
+}
+
+/**
+ * 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 = getRoomDescriptorReadOnly();
+  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/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);
+}