isaacscript-common 2.3.0 → 3.0.0

package/functions/roomGrid.lua

@@ -0,0 +1,80 @@
+local ____exports = {}
+local isValidGridPositionNormal, isValidGridPositionLRoom
+local ____LRoomShapeToRectangles = require("objects.LRoomShapeToRectangles")
+local L_ROOM_SHAPE_TO_RECTANGLES = ____LRoomShapeToRectangles.L_ROOM_SHAPE_TO_RECTANGLES
+local ____math = require("functions.math")
+local inRectangle = ____math.inRectangle
+local ____roomShape = require("functions.roomShape")
+local getRoomShapeBottomRightPosition = ____roomShape.getRoomShapeBottomRightPosition
+local getRoomShapeTopLeftPosition = ____roomShape.getRoomShapeTopLeftPosition
+local getRoomShapeWidth = ____roomShape.getRoomShapeWidth
+local isLRoom = ____roomShape.isLRoom
+--- 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)`.
+function ____exports.gridPositionToWorldPosition(self, gridPosition)
+    local x = (gridPosition.X + 2) * 40
+    local y = (gridPosition.Y + 4) * 40
+    return Vector(x, y)
+end
+function isValidGridPositionNormal(self, gridPosition, roomShape)
+    local topLeft = getRoomShapeTopLeftPosition(nil, roomShape)
+    local bottomRight = getRoomShapeBottomRightPosition(nil, roomShape)
+    return inRectangle(nil, gridPosition, topLeft, bottomRight)
+end
+function isValidGridPositionLRoom(self, gridPosition, roomShape)
+    local rectangles = L_ROOM_SHAPE_TO_RECTANGLES[roomShape]
+    if rectangles == nil then
+        return false
+    end
+    local verticalTopLeft, verticalBottomRight, horizontalTopLeft, horizontalBottomRight = table.unpack(rectangles)
+    return inRectangle(nil, gridPosition, verticalTopLeft, verticalBottomRight) or inRectangle(nil, gridPosition, horizontalTopLeft, horizontalBottomRight)
+end
+--- Helper function to convert grid coordinates to a world position `Vector`.
+-- 
+-- For example, the coordinates of (0, 0) are equal to `Vector(80, 160)`.
+function ____exports.gridCoordinatesToWorldPosition(self, x, y)
+    local gridPosition = Vector(x, y)
+    return ____exports.gridPositionToWorldPosition(nil, gridPosition)
+end
+--- 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)".
+function ____exports.gridIndexToGridPosition(self, gridIndex, roomShape)
+    local gridWidth = getRoomShapeWidth(nil, roomShape)
+    local x = gridIndex % gridWidth - 1
+    local y = math.floor(gridIndex / gridWidth) - 1
+    return Vector(x, y)
+end
+--- 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)".
+function ____exports.isValidGridPosition(self, gridPosition, roomShape)
+    local ____isLRoom_result_0
+    if isLRoom(nil, roomShape) then
+        ____isLRoom_result_0 = isValidGridPositionLRoom(nil, gridPosition, roomShape)
+    else
+        ____isLRoom_result_0 = isValidGridPositionNormal(nil, gridPosition, roomShape)
+    end
+    return ____isLRoom_result_0
+end
+--- 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)".
+function ____exports.worldPositionToGridPosition(self, worldPos)
+    local x = math.floor(worldPos.X / 40 - 2 + 0.5)
+    local y = math.floor(worldPos.Y / 40 - 4 + 0.5)
+    return Vector(x, y)
+end
+--- 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.
+function ____exports.worldPositionToGridPositionFast(self, worldPos)
+    local x = worldPos.X / 40 - 2
+    local y = worldPos.Y / 40 - 4
+    return Vector(x, y)
+end
+return ____exports

package/functions/roomShape.d.ts

@@ -0,0 +1,43 @@
+import { DoorSlot, RoomShape } from "isaac-typescript-definitions";
+/**
+ * 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 declare function getGridIndexDelta(roomShape: RoomShape, doorSlot: DoorSlot): int | undefined;
+/**
+ * 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 declare function getRoomShapeBottomRightPosition(roomShape: RoomShape): Vector;
+/**
+ * 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 declare function getRoomShapeBounds(roomShape: RoomShape): Vector;
+/**
+ * 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 declare function getRoomShapeLayoutSize(roomShape: RoomShape): Vector;
+/**
+ * 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 declare function getRoomShapeTopLeftPosition(roomShape: RoomShape): Vector;
+/**
+ * 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 declare function getRoomShapeVolume(roomShape: RoomShape): int;
+export declare function getRoomShapeWidth(roomShape: RoomShape): int;
+export declare function isLRoom(roomShape: RoomShape): boolean;

package/functions/roomShape.lua

@@ -0,0 +1,67 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local ____exports = {}
+local ____roomShapeBounds = require("objects.roomShapeBounds")
+local ROOM_SHAPE_BOUNDS = ____roomShapeBounds.ROOM_SHAPE_BOUNDS
+local ____roomShapeLayoutSizes = require("objects.roomShapeLayoutSizes")
+local ROOM_SHAPE_LAYOUT_SIZES = ____roomShapeLayoutSizes.ROOM_SHAPE_LAYOUT_SIZES
+local ____roomShapeToBottomRightPosition = require("objects.roomShapeToBottomRightPosition")
+local ROOM_SHAPE_TO_BOTTOM_RIGHT_POSITION = ____roomShapeToBottomRightPosition.ROOM_SHAPE_TO_BOTTOM_RIGHT_POSITION
+local ____roomShapeToDoorSlotsToGridIndexDelta = require("objects.roomShapeToDoorSlotsToGridIndexDelta")
+local ROOM_SHAPE_TO_DOOR_SLOTS_TO_GRID_INDEX_DELTA = ____roomShapeToDoorSlotsToGridIndexDelta.ROOM_SHAPE_TO_DOOR_SLOTS_TO_GRID_INDEX_DELTA
+local ____roomShapeToGridWidth = require("objects.roomShapeToGridWidth")
+local ROOM_SHAPE_TO_GRID_WIDTH = ____roomShapeToGridWidth.ROOM_SHAPE_TO_GRID_WIDTH
+local ____roomShapeToTopLeftPosition = require("objects.roomShapeToTopLeftPosition")
+local ROOM_SHAPE_TO_TOP_LEFT_POSITION = ____roomShapeToTopLeftPosition.ROOM_SHAPE_TO_TOP_LEFT_POSITION
+local ____roomShapeVolumes = require("objects.roomShapeVolumes")
+local ROOM_SHAPE_VOLUMES = ____roomShapeVolumes.ROOM_SHAPE_VOLUMES
+local ____LRoomShapesSet = require("sets.LRoomShapesSet")
+local L_ROOM_SHAPES_SET = ____LRoomShapesSet.L_ROOM_SHAPES_SET
+--- 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.
+function ____exports.getGridIndexDelta(self, roomShape, doorSlot)
+    local doorSlotToGridIndexMap = ROOM_SHAPE_TO_DOOR_SLOTS_TO_GRID_INDEX_DELTA[roomShape]
+    return doorSlotToGridIndexMap:get(doorSlot)
+end
+--- 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)".)
+function ____exports.getRoomShapeBottomRightPosition(self, roomShape)
+    return ROOM_SHAPE_TO_BOTTOM_RIGHT_POSITION[roomShape]
+end
+--- 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.
+function ____exports.getRoomShapeBounds(self, roomShape)
+    return ROOM_SHAPE_BOUNDS[roomShape]
+end
+--- 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.
+function ____exports.getRoomShapeLayoutSize(self, roomShape)
+    return ROOM_SHAPE_LAYOUT_SIZES[roomShape]
+end
+--- 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)".)
+function ____exports.getRoomShapeTopLeftPosition(self, roomShape)
+    return ROOM_SHAPE_TO_TOP_LEFT_POSITION[roomShape]
+end
+--- 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.)
+function ____exports.getRoomShapeVolume(self, roomShape)
+    return ROOM_SHAPE_VOLUMES[roomShape]
+end
+function ____exports.getRoomShapeWidth(self, roomShape)
+    return ROOM_SHAPE_TO_GRID_WIDTH[roomShape]
+end
+function ____exports.isLRoom(self, roomShape)
+    return L_ROOM_SHAPES_SET:has(roomShape)
+end
+return ____exports

package/functions/rooms.d.ts

@@ -0,0 +1,194 @@
+import { BossID, Dimension, Direction, DoorSlot, ItemPoolType, MinibossID, RoomShape, RoomTransitionAnim, RoomType } from "isaac-typescript-definitions";
+/**
+ * Helper function for quickly switching to a new room without playing a particular animation. Use
+ * this helper function over invoking the `Game.ChangeRoom` method directly to ensure that you do
+ * not forget to set the `LeaveDoor` property and to prevent crashing on invalid room grid indexes.
+ */
+export declare function changeRoom(roomGridIndex: int): void;
+/**
+ * Helper function to get an array with every valid `Dimension` (not including `Dimension.CURRENT`).
+ */
+export declare function getAllDimensions(): Dimension[];
+export declare function getAllRoomGridIndexes(): int[];
+/**
+ * Helper function to get the current dimension. Most of the time, this will be `Dimension.MAIN`,
+ * but it can change if e.g. the player is in the mirror world of Downpour/Dross.
+ *
+ * Note that this function correctly handles detecting the Death Certificate dimension, which is
+ * tricky to properly detect.
+ */
+export declare function getCurrentDimension(): Dimension;
+/**
+ * Helper function to get the number of rooms that are currently on the floor layout. This does not
+ * include off-grid rooms, like the Devil Room.
+ */
+export declare function getNumRooms(): int;
+/**
+ * Helper function to get an array of all of the safe grid indexes for rooms that match the
+ * specified room type.
+ *
+ * This function only searches through rooms in the current dimension.
+ *
+ * This function is variadic, meaning that you can specify N arguments to get the combined grid
+ * indexes for N room types.
+ */
+export declare function getRoomGridIndexesForType(...roomTypes: RoomType[]): int[];
+/**
+ * Helper function to get the item pool type for the current room. For example, this returns
+ * `ItemPoolType.ItemPoolType.POOL_ANGEL` if you are in an Angel Room.
+ */
+export declare function getRoomItemPoolType(): ItemPoolType;
+/**
+ * Helper function to get the grid indexes of all the rooms connected to the given room index.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ */
+export declare function getRoomNeighbors(roomGridIndex?: int): int[];
+export declare function getRoomShapeNeighborGridIndexDeltas(roomShape: RoomShape): int[];
+/**
+ * Helper function to get the proper name of a room type.
+ *
+ * For example, `RoomType.TREASURE` will return "Treasure Room".
+ */
+export declare function getRoomTypeName(roomType: RoomType): string;
+/**
+ * Helper function to get the room descriptor for every room on the level. Uses the `Level.GetRooms`
+ * method to accomplish this. Rooms without data are assumed to be non-existent and are not added to
+ * the list.
+ *
+ * @param includeExtraDimensionalRooms Optional. On some floors (e.g. Downpour 2, Mines 2),
+ *                                 extra-dimensional rooms are automatically be generated and can be
+ *                                 seen when you iterate over the `RoomList`. Default is false.
+ */
+export declare function getRooms(includeExtraDimensionalRooms?: boolean): RoomDescriptor[];
+/**
+ * Helper function to get the room descriptor for every room on the level in a specific dimension.
+ * Uses the `Level.GetRooms` method to accomplish this. Rooms without data are assumed to be
+ * non-existent and are not added to the list.
+ *
+ * @returns A map of room ListIndex to RoomDescriptor.
+ */
+export declare function getRoomsOfDimension(dimension: Dimension): RoomDescriptor[];
+/**
+ * Helper function to determine if the current room shape is equal to `RoomShape.1x2` or
+ * `RoomShape.2x1`.
+ */
+export declare function in2x1Room(): boolean;
+export declare function inAngelShop(): boolean;
+export declare function inBeastRoom(): boolean;
+/**
+ * Helper function to check if the current room is a boss room for a particular boss. This will only
+ * work for bosses that have dedicated boss rooms in the "00.special rooms.stb" file.
+ */
+export declare function inBossRoomOf(bossID: BossID): boolean;
+/**
+ * Helper function for determining whether the current room is a crawlspace. Use this function over
+ * comparing to `RoomType.DUNGEON` or `GridRoom.DUNGEON_IDX` since there is a special case of the
+ * player being in a boss fight that take place in a dungeon.
+ */
+export declare function inCrawlspace(): boolean;
+/**
+ * We cannot use the standard code in the `inDimension` function for this purpose since it is bugged
+ * with the Death Certificate area.
+ */
+export declare function inDeathCertificateArea(): boolean;
+/**
+ * Helper function to detect if the current room is a Treasure Room created when entering with a
+ * Devil's Crown trinket. Under the hood, this checks for the `RoomDescriptorFlag.DEVIL_TREASURE`
+ * flag.
+ */
+export declare function inDevilsCrownTreasureRoom(): boolean;
+export declare function inDimension(dimension: Dimension): boolean;
+export declare function inDoubleTrouble(): boolean;
+export declare function inGenesisRoom(): boolean;
+/** Helper function to determine if the current room shape is one of the four L room shapes. */
+export declare function inLRoom(): boolean;
+export declare function inMegaSatanRoom(): boolean;
+/**
+ * Helper function to determine if the current room is part of the Repentance "escape sequence" in
+ * the Mines/Ashpit.
+ */
+export declare function inMineShaft(): boolean;
+/**
+ * Helper function to check if the current room is a miniboss room for a particular miniboss. This
+ * will only work for mini-bosses that have dedicated boss rooms in the "00.special rooms.stb" file.
+ */
+export declare function inMinibossRoomOf(minibossID: MinibossID): boolean;
+/**
+ * Helper function for checking if the room is a secret shop (from the Member Card collectible).
+ *
+ * Secret shops are simply copies of normal shops, but with the backdrop of a secret room. In other
+ * words, they will have the same room type, room variant, and room sub-type of a normal shop. Thus,
+ * the only way to detect them is by using the grid index.
+ */
+export declare function inSecretShop(): boolean;
+/**
+ * Helper function to determine whether or not the current room is the starting room of a floor. It
+ * only returns true for the starting room of the primary dimension (meaning that being in the
+ * starting room of the mirror world does not count).
+ */
+export declare function inStartingRoom(): boolean;
+/**
+ * Helper function to loop through every room on the floor and see if it has been cleared.
+ *
+ * This function will only check rooms in the current dimension.
+ *
+ * @param onlyCheckRoomTypes Optional. A whitelist of room types. If specified, room types not in
+ *                           the array will be ignored. If not specified, then all rooms will be
+ *                           checked. Undefined by default.
+ */
+export declare function isAllRoomsClear(onlyCheckRoomTypes?: RoomType[]): boolean;
+export declare function isDoorSlotValidAtGridIndex(doorSlot: DoorSlot, roomGridIndex: int): boolean;
+export declare function isDoorSlotValidAtGridIndexForRedRoom(doorSlot: DoorSlot, roomGridIndex: int): boolean;
+/**
+ * Helper function to detect if the provided room was created by the Red Key item. Under the hood,
+ * this checks for the `RoomDescriptorFlag.FLAG_RED_ROOM` flag.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ */
+export declare function isRedKeyRoom(roomGridIndex?: int): boolean;
+/**
+ * Helper function to determine if the provided room is part of the floor layout. For example, Devil
+ * Rooms and the Mega Satan room are not considered to be inside the map.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ */
+export declare function isRoomInsideMap(roomGridIndex?: int): boolean;
+/** Helper function to check if a room exists at the given room grid index. */
+export declare function roomExists(roomGridIndex: int): boolean;
+/**
+ * Helper function to get the coordinates of a given grid index. The floor is represented by a 13x13
+ * grid. For example, since the starting room is in the center, the starting room grid index of 84
+ * be equal to coordinates of (?, ?).
+ */
+export declare function roomGridIndexToXY(roomGridIndex: int): [x: int, y: int];
+/**
+ * If the `Room.Update` method is called in a PostNewRoom callback, then some entities will slide
+ * around (such as the player). Since those entity velocities are already at zero, setting them to
+ * zero will have no effect. Thus, a generic solution is to record all of the entity
+ * positions/velocities before updating the room, and then restore those positions/velocities.
+ */
+export declare function roomUpdateSafe(): void;
+/**
+ * Helper function to convert an uncleared room to a cleared room in the PostNewRoom callback. This
+ * is useful because if enemies are removed in this callback, a room drop will be awarded and the
+ * doors will start closed and then open.
+ */
+export declare function setRoomCleared(): void;
+/**
+ * Helper function to emulate what happens when you bomb an Angel Statue or push a Reward Plate that
+ * spawns an NPC.
+ */
+export declare function setRoomUncleared(): void;
+/**
+ * Helper function to change the current room. It can be used for both teleportation and "normal"
+ * room transitions, depending on what is passed for the `direction` and `roomTransitionAnim`
+ * arguments. Use this function instead of invoking the `Game.StartRoomTransition` method directly
+ * so that you do not forget to set `Level.LeaveDoor` property and to prevent crashing on invalid
+ * room grid indexes.
+ *
+ * @param roomGridIndex The room grid index of the destination room.
+ * @param direction Optional. Default is `Direction.NO_DIRECTION`.
+ * @param roomTransitionAnim Optional. Default is `RoomTransitionAnim.TELEPORT`.
+ */
+export declare function teleport(roomGridIndex: int, direction?: Direction, roomTransitionAnim?: RoomTransitionAnim): void;