isaacscript-common 34.1.0 → 35.0.0

package/dist/index.rollup.d.ts

@@ -4739,6 +4739,10 @@ export declare function getArrayCombinations<T>(array: T[] | readonly T[], inclu
  * Helper function to get an array containing the indexes of an array.
  *
  * For example, an array of `["Apple", "Banana"]` would return an array of `[0, 1]`.
+ *
+ * Note that normally, you would use the `Object.keys` method to get the indexes of an array, but
+ * due to implementation details of TypeScriptToLua, this results in an array of 1 through N
+ * (instead of an array of 0 through N -1).
  */
 export declare function getArrayIndexes<T>(array: T[] | readonly T[]): int[];
 
@@ -6652,8 +6656,23 @@ export declare function getRoomAdjacentGridIndexes(roomGridIndex?: int): Readonl
  */
 export declare function getRoomAllowedDoors(roomGridIndex?: int): Set<DoorSlot>;
 
+/**
+ * Helper function to get the room data for the current room.
+ *
+ * You can optionally provide a room grid index as an argument to get the data for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
 export declare function getRoomData(): RoomConfig;
 
+/**
+ * Helper function to get the room data for the current or provided room.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ * @returns The room data for the room or undefined if the provided room does not have any data.
+ */
 export declare function getRoomData(roomGridIndex?: int): RoomConfig | undefined;
 
 /**
@@ -6718,12 +6737,15 @@ export declare function getRoomDescriptorsForType(...roomTypes: RoomType[]): Roo
 export declare function getRoomDisplayFlags(roomGridIndex?: int, minimapAPI?: boolean): BitFlags<DisplayFlag>;
 
 /**
- * Helper function to get the safe grid index of the current room. (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.)
+ * Helper function to get the grid index of the current room.
  *
- * Under the hood, this function uses the `Level.GetCurrentRoomDesc` method. (In Afterbirth+, this
- * method was bugged for rooms outside of the grid, but it is now fixed.)
+ * - 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, as
+ *   demonstrated by entering a Genesis room and entering `l
+ *   print(Game():GetLevel():GetCurrentRoomDesc().SafeGridIndex)` into the console).
  *
  * 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,
@@ -6763,13 +6785,24 @@ export declare function getRoomItemPoolType(): ItemPoolType;
  */
 export declare function getRoomListIndex(roomGridIndex?: int): int;
 
+/**
+ * Helper function to get the name of the current room as it appears in the STB/XML data.
+ *
+ * You can optionally provide a room grid index as an argument to get the name for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
+export declare function getRoomName(): string;
+
 /**
  * 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 room data was not found.
+ * @returns The room name. Returns undefined if the room data was not found.
  */
-export declare function getRoomName(roomGridIndex?: int): string;
+export declare function getRoomName(roomGridIndex?: int): string | undefined;
 
 /**
  * Helper function to get the room descriptor for every room on the level. This includes off-grid
@@ -6787,10 +6820,21 @@ export declare function getRoomName(roomGridIndex?: int): string;
 export declare function getRooms(includeExtraDimensionalRooms?: boolean): RoomDescriptor[];
 
 /**
- * Helper function to get the name of the room as it appears in the STB/XML data.
+ * Helper function to get the shape of the current room as it appears in the STB/XML data.
+ *
+ * You can optionally provide a room grid index as an argument to get the shape for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
+export declare function getRoomShape(): RoomShape;
+
+/**
+ * Helper function to get the shape 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 room data was not found.
+ * @returns The room shape. Returns undefined if the room data was not found.
  */
 export declare function getRoomShape(roomGridIndex?: int): RoomShape | undefined;
 
@@ -6931,33 +6975,77 @@ export declare function getRoomsOfDimension(dimension: Dimension): RoomDescripto
 export declare function getRoomsOutsideGrid(): RoomDescriptor[];
 
 /**
- * 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.
+ * Helper function to get the stage ID for the current room as it appears in the STB/XML 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 `StageID.DEPTHS` (7).
+ *
+ * You can optionally provide a room grid index as an argument to get the stage ID for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
+export declare function getRoomStageID(): StageID;
+
+/**
+ * Helper function to get the stage ID for a room as it appears in the STB/XML 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 `StageID.DEPTHS` (7).
  *
  * @param roomGridIndex Optional. Default is the current room index.
- * @returns The room stage ID. Returns -1 if the room data was not found.
+ * @returns The room stage ID. Returns undefined if the room data was not found.
  */
-export declare function getRoomStageID(roomGridIndex?: int): StageID | -1;
+export declare function getRoomStageID(roomGridIndex?: int): StageID | undefined;
 
 /**
- * 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.
+ * Helper function to get the sub-type for the current room as it appears in the STB/XML 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 from
+ * The Stairway.
+ *
+ * You can optionally provide a room grid index as an argument to get the sub-type for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
+export declare function getRoomSubType(): int;
+
+/**
+ * Helper function to get the sub-type for a room as it appears in the STB/XML 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 from
+ * The Stairway.
  *
  * @param roomGridIndex Optional. Default is the current room index.
- * @returns The room sub-type. Returns -1 if the room data was not found.
+ * @returns The room sub-type. Returns undefined if the room data was not found.
+ */
+export declare function getRoomSubType(roomGridIndex?: int): int | undefined;
+
+/**
+ * Helper function to get the type for the current room as it appears in the STB/XML data.
+ *
+ * You can optionally provide a room grid index as an argument to get the type for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
  */
-export declare function getRoomSubType(roomGridIndex?: int): int;
+export declare function getRoomType(): RoomType;
 
 /**
- * Helper function for getting the type of the room with the given grid index.
+ * Helper function to get the type for a room as it appears in the STB/XML data.
  *
  * @param roomGridIndex Optional. Default is the current room index.
- * @returns The room data type. Returns -1 if the room data was not found.
+ * @returns The room type. Returns undefined if the room data was not found.
  */
-export declare function getRoomType(roomGridIndex?: int): RoomType | -1;
+export declare function getRoomType(roomGridIndex?: int): RoomType | undefined;
 
 /**
  * Helper function to get the proper name of a room type.
@@ -6967,14 +7055,29 @@ export declare function getRoomType(roomGridIndex?: int): RoomType | -1;
 export declare function getRoomTypeName(roomType: RoomType): string;
 
 /**
- * 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.
+ * Helper function to get the variant for the current room as it appears in the STB/XML 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.
+ *
+ * You can optionally provide a room grid index as an argument to get the variant for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
+export declare function getRoomVariant(): int;
+
+/**
+ * Helper function to get the variant for a room as it appears in the STB/XML 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 room data was not found.
+ * @returns The room variant. Returns undefined if the room data was not found.
  */
-export declare function getRoomVariant(roomGridIndex?: int): int;
+export declare function getRoomVariant(roomGridIndex?: int): int | undefined;
 
 /**
  * Note that the room visited count will be inaccurate during the period before the `POST_NEW_ROOM`
@@ -8456,7 +8559,7 @@ export declare function isEntity(variable: unknown): variable is Entity;
 export declare function isEntityMoving(entity: Entity, threshold?: number): boolean;
 
 /** Helper function to validate that a particular value exists inside of an enum. */
-export declare function isEnumValue(value: number | string, transpiledEnum: Record<string | number, string | number>): boolean;
+export declare function isEnumValue<T extends Record<string, number | string>>(value: number | string, transpiledEnum: T): value is T[keyof T];
 
 export declare function isEven(num: int): boolean;
 

package/dist/isaacscript-common.lua

@@ -1,6 +1,6 @@
 --[[
 
-isaacscript-common 34.1.0
+isaacscript-common 35.0.0
 
 This is the "isaacscript-common" library, which was created with the IsaacScript tool.
 
@@ -26790,6 +26790,11 @@ function ____exports.getRoomDescriptorReadOnly(self)
     return level:GetCurrentRoomDesc()
 end
 function ____exports.getRoomGridIndex(self)
+    local level = game:GetLevel()
+    local currentRoomIndex = level:GetCurrentRoomIndex()
+    if currentRoomIndex < 0 then
+        return currentRoomIndex
+    end
     local roomDescriptor = ____exports.getRoomDescriptorReadOnly(nil)
     return roomDescriptor.SafeGridIndex
 end
@@ -26812,30 +26817,54 @@ function ____exports.getRoomListIndex(self, roomGridIndex)
     return roomDescriptor.ListIndex
 end
 function ____exports.getRoomName(self, roomGridIndex)
-    local roomData = ____exports.getRoomData(nil, roomGridIndex)
-    return roomData == nil and "Unknown" or roomData.Name
-end
-function ____exports.getRoomShape(self, roomGridIndex)
     local roomData = ____exports.getRoomData(nil, roomGridIndex)
     local ____temp_0
     if roomData == nil then
         ____temp_0 = nil
     else
-        ____temp_0 = roomData.Shape
+        ____temp_0 = roomData.Name
     end
     return ____temp_0
 end
+function ____exports.getRoomShape(self, roomGridIndex)
+    local roomData = ____exports.getRoomData(nil, roomGridIndex)
+    local ____temp_1
+    if roomData == nil then
+        ____temp_1 = nil
+    else
+        ____temp_1 = roomData.Shape
+    end
+    return ____temp_1
+end
 function ____exports.getRoomStageID(self, roomGridIndex)
     local roomData = ____exports.getRoomData(nil, roomGridIndex)
-    return roomData == nil and -1 or roomData.StageID
+    local ____temp_2
+    if roomData == nil then
+        ____temp_2 = nil
+    else
+        ____temp_2 = roomData.StageID
+    end
+    return ____temp_2
 end
 function ____exports.getRoomSubType(self, roomGridIndex)
     local roomData = ____exports.getRoomData(nil, roomGridIndex)
-    return roomData == nil and -1 or roomData.Subtype
+    local ____temp_3
+    if roomData == nil then
+        ____temp_3 = nil
+    else
+        ____temp_3 = roomData.Subtype
+    end
+    return ____temp_3
 end
 function ____exports.getRoomType(self, roomGridIndex)
     local roomData = ____exports.getRoomData(nil, roomGridIndex)
-    return roomData == nil and -1 or roomData.Type
+    local ____temp_4
+    if roomData == nil then
+        ____temp_4 = nil
+    else
+        ____temp_4 = roomData.Type
+    end
+    return ____temp_4
 end
 function ____exports.getRoomVariant(self, roomGridIndex)
     local roomData = ____exports.getRoomData(nil, roomGridIndex)
@@ -46725,12 +46754,11 @@ function getJSONObjectWithChosenWeight(self, jsonOjectArray, chosenWeight)
 end
 function ____exports.getJSONRoomDoorSlotFlags(self, jsonRoom)
     local roomShapeString = jsonRoom["$"].shape
-    local roomShapeNumber = tonumber(roomShapeString)
-    assertDefined(nil, roomShapeNumber, "Failed to parse the \"shape\" field of a JSON room: " .. roomShapeString)
-    if not isEnumValue(nil, roomShapeNumber, RoomShape) then
-        error("Failed to parse the \"shape\" field of a JSON room since it was an invalid number: " .. tostring(roomShapeNumber))
+    local roomShape = tonumber(roomShapeString)
+    assertDefined(nil, roomShape, "Failed to parse the \"shape\" field of a JSON room: " .. roomShapeString)
+    if not isEnumValue(nil, roomShape, RoomShape) then
+        error("Failed to parse the \"shape\" field of a JSON room since it was an invalid number: " .. tostring(roomShape))
     end
-    local roomShape = roomShapeNumber
     local doorSlotFlags = DoorSlotFlagZero
     for ____, door in ipairs(jsonRoom.door) do
         do

package/dist/src/functions/array.d.ts

@@ -134,6 +134,10 @@ export declare function getArrayCombinations<T>(array: T[] | readonly T[], inclu
  * Helper function to get an array containing the indexes of an array.
  *
  * For example, an array of `["Apple", "Banana"]` would return an array of `[0, 1]`.
+ *
+ * Note that normally, you would use the `Object.keys` method to get the indexes of an array, but
+ * due to implementation details of TypeScriptToLua, this results in an array of 1 through N
+ * (instead of an array of 0 through N -1).
  */
 export declare function getArrayIndexes<T>(array: T[] | readonly T[]): int[];
 /**

package/dist/src/functions/array.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../../src/functions/array.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../../src/functions/array.ts"],"names":[],"mappings":"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"}

package/dist/src/functions/array.lua

@@ -364,6 +364,10 @@ end
 --- Helper function to get an array containing the indexes of an array.
 -- 
 -- For example, an array of `["Apple", "Banana"]` would return an array of `[0, 1]`.
+-- 
+-- Note that normally, you would use the `Object.keys` method to get the indexes of an array, but
+-- due to implementation details of TypeScriptToLua, this results in an array of 1 through N
+-- (instead of an array of 0 through N -1).
 function ____exports.getArrayIndexes(self, array)
     return eRange(nil, #array)
 end

package/dist/src/functions/enums.d.ts

@@ -83,7 +83,7 @@ export declare function getLowestEnumValue<T>(transpiledEnum: T): T[keyof T];
  */
 export declare function getRandomEnumValue<T>(transpiledEnum: T, seedOrRNG?: Seed | RNG, exceptions?: Array<T[keyof T]> | ReadonlyArray<T[keyof T]>): T[keyof T];
 /** Helper function to validate that a particular value exists inside of an enum. */
-export declare function isEnumValue(value: number | string, transpiledEnum: Record<string | number, string | number>): boolean;
+export declare function isEnumValue<T extends Record<string, number | string>>(value: number | string, transpiledEnum: T): value is T[keyof T];
 /**
  * Helper function to check every value of a custom enum for -1. Will throw an run-time error if any
  * -1 values are found. This is helpful because many methods of the Isaac class return -1 if they

package/dist/src/functions/enums.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../../../src/functions/enums.ts"],"names":[],"mappings":";;;AAMA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,cAAc,EAAE,CAAC,GAChB,KAAK,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAmBzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACzB,cAAc,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GACvD,MAAM,EAAE,CAGV;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAC3B,cAAc,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GACvD,GAAG,CAGL;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAGrE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAUpE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAUnE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,cAAc,EAAE,CAAC,EACjB,SAAS,GAAE,IAAI,GAAG,GAAqB,EACvC,UAAU,GAAE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAM,GAC7D,CAAC,CAAC,MAAM,CAAC,CAAC,CAGZ;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,cAAc,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GACvD,OAAO,CAGT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,kBAAkB,EAAE,MAAM,EAC1B,cAAc,EAAE,OAAO,GACtB,IAAI,CAQN;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,kBAAkB,EAAE,MAAM,EAC1B,cAAc,EAAE,CAAC,GAChB,IAAI,CAsBN;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,4BAA4B,CAE1C,CAAC,SAAS,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,EAC/B,IAAI,SAAS,MAAM,GAAG,MAAM,KACzB,IAAI,CAAG"}
+{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../../../src/functions/enums.ts"],"names":[],"mappings":";;;AAMA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,cAAc,EAAE,CAAC,GAChB,KAAK,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAmBzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACzB,cAAc,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GACvD,MAAM,EAAE,CAGV;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAC3B,cAAc,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GACvD,GAAG,CAGL;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAGrE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAUpE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAUnE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,cAAc,EAAE,CAAC,EACjB,SAAS,GAAE,IAAI,GAAG,GAAqB,EACvC,UAAU,GAAE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAM,GAC7D,CAAC,CAAC,MAAM,CAAC,CAAC,CAGZ;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EACnE,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,cAAc,EAAE,CAAC,GAChB,KAAK,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAGrB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,kBAAkB,EAAE,MAAM,EAC1B,cAAc,EAAE,OAAO,GACtB,IAAI,CAQN;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,kBAAkB,EAAE,MAAM,EAC1B,cAAc,EAAE,CAAC,GAChB,IAAI,CAsBN;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,4BAA4B,CAE1C,CAAC,SAAS,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,EAC/B,IAAI,SAAS,MAAM,GAAG,MAAM,KACzB,IAAI,CAAG"}

package/dist/src/functions/jsonRoom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jsonRoom.d.ts","sourceRoot":"","sources":["../../../src/functions/jsonRoom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAEjE,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAexE;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,QAAQ,GACjB,QAAQ,CAAC,YAAY,CAAC,CAsDxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,QAAQ,EAAE,GAAG,SAAS,QAAQ,EAAE,EAC3C,OAAO,EAAE,GAAG,GACX,QAAQ,GAAG,SAAS,CAoBtB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,QAAQ,EAAE,GAAG,SAAS,QAAQ,EAAE,EAC3C,OAAO,EAAE,GAAG,GACX,QAAQ,EAAE,CAMZ;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,UAAU,EAAE,EAC1B,SAAS,GAAE,IAAI,GAAG,GAAqB,EACvC,OAAO,UAAQ,GACd,UAAU,CAqBZ;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,QAAQ,EAAE,EACrB,SAAS,GAAE,IAAI,GAAG,GAAqB,EACvC,OAAO,UAAQ,GACd,QAAQ,CAkBV"}
+{"version":3,"file":"jsonRoom.d.ts","sourceRoot":"","sources":["../../../src/functions/jsonRoom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAEjE,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAexE;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,QAAQ,GACjB,QAAQ,CAAC,YAAY,CAAC,CAqDxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,QAAQ,EAAE,GAAG,SAAS,QAAQ,EAAE,EAC3C,OAAO,EAAE,GAAG,GACX,QAAQ,GAAG,SAAS,CAoBtB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,QAAQ,EAAE,GAAG,SAAS,QAAQ,EAAE,EAC3C,OAAO,EAAE,GAAG,GACX,QAAQ,EAAE,CAMZ;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,UAAU,EAAE,EAC1B,SAAS,GAAE,IAAI,GAAG,GAAqB,EACvC,OAAO,UAAQ,GACd,UAAU,CAqBZ;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,QAAQ,EAAE,EACrB,SAAS,GAAE,IAAI,GAAG,GAAqB,EACvC,OAAO,UAAQ,GACd,QAAQ,CAkBV"}

package/dist/src/functions/jsonRoom.lua

@@ -62,12 +62,11 @@ end
 -- (A JSON room is an XML file converted to JSON so that it can be directly imported into your mod.)
 function ____exports.getJSONRoomDoorSlotFlags(self, jsonRoom)
     local roomShapeString = jsonRoom["$"].shape
-    local roomShapeNumber = tonumber(roomShapeString)
-    assertDefined(nil, roomShapeNumber, "Failed to parse the \"shape\" field of a JSON room: " .. roomShapeString)
-    if not isEnumValue(nil, roomShapeNumber, RoomShape) then
-        error("Failed to parse the \"shape\" field of a JSON room since it was an invalid number: " .. tostring(roomShapeNumber))
+    local roomShape = tonumber(roomShapeString)
+    assertDefined(nil, roomShape, "Failed to parse the \"shape\" field of a JSON room: " .. roomShapeString)
+    if not isEnumValue(nil, roomShape, RoomShape) then
+        error("Failed to parse the \"shape\" field of a JSON room since it was an invalid number: " .. tostring(roomShape))
     end
-    local roomShape = roomShapeNumber
     local doorSlotFlags = DoorSlotFlagZero
     for ____, door in ipairs(jsonRoom.door) do
         do

package/dist/src/functions/roomData.d.ts

@@ -4,7 +4,22 @@ import type { DoorSlot, RoomShape, RoomType, StageID } from "isaac-typescript-de
  * This corresponds to the doors that are enabled in the STB/XML file for the room.
  */
 export declare function getRoomAllowedDoors(roomGridIndex?: int): Set<DoorSlot>;
+/**
+ * Helper function to get the room data for the current room.
+ *
+ * You can optionally provide a room grid index as an argument to get the data for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
 export declare function getRoomData(): RoomConfig;
+/**
+ * Helper function to get the room data for the current or provided room.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ * @returns The room data for the room or undefined if the provided room does not have any data.
+ */
 export declare function getRoomData(roomGridIndex?: int): RoomConfig | undefined;
 /**
  * Helper function to get the descriptor for a room.
@@ -18,12 +33,15 @@ export declare function getRoomDescriptor(roomGridIndex?: int): RoomDescriptor;
  */
 export declare function getRoomDescriptorReadOnly(): Readonly<RoomDescriptor>;
 /**
- * Helper function to get the safe grid index of the current room. (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.)
+ * Helper function to get the grid index of the current room.
  *
- * Under the hood, this function uses the `Level.GetCurrentRoomDesc` method. (In Afterbirth+, this
- * method was bugged for rooms outside of the grid, but it is now fixed.)
+ * - 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, as
+ *   demonstrated by entering a Genesis room and entering `l
+ *   print(Game():GetLevel():GetCurrentRoomDesc().SafeGridIndex)` into the console).
  *
  * 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,
@@ -44,55 +62,130 @@ export declare function getRoomGridIndex(): int;
  * @param roomGridIndex Optional. Default is the current room index.
  */
 export declare function getRoomListIndex(roomGridIndex?: int): int;
+/**
+ * Helper function to get the name of the current room as it appears in the STB/XML data.
+ *
+ * You can optionally provide a room grid index as an argument to get the name for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
+export declare function getRoomName(): string;
 /**
  * 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 room data was not found.
+ * @returns The room name. Returns undefined if the room data was not found.
  */
-export declare function getRoomName(roomGridIndex?: int): string;
+export declare function getRoomName(roomGridIndex?: int): string | undefined;
 /**
- * Helper function to get the name of the room as it appears in the STB/XML data.
+ * Helper function to get the shape of the current room as it appears in the STB/XML data.
+ *
+ * You can optionally provide a room grid index as an argument to get the shape for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
+export declare function getRoomShape(): RoomShape;
+/**
+ * Helper function to get the shape 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 room data was not found.
+ * @returns The room shape. Returns undefined if the room data was not found.
  */
 export declare function getRoomShape(roomGridIndex?: int): RoomShape | undefined;
 /**
- * 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.
+ * Helper function to get the stage ID for the current room as it appears in the STB/XML 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 `StageID.DEPTHS` (7).
+ *
+ * You can optionally provide a room grid index as an argument to get the stage ID for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
+export declare function getRoomStageID(): StageID;
+/**
+ * Helper function to get the stage ID for a room as it appears in the STB/XML 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 `StageID.DEPTHS` (7).
  *
  * @param roomGridIndex Optional. Default is the current room index.
- * @returns The room stage ID. Returns -1 if the room data was not found.
+ * @returns The room stage ID. Returns undefined if the room data was not found.
+ */
+export declare function getRoomStageID(roomGridIndex?: int): StageID | undefined;
+/**
+ * Helper function to get the sub-type for the current room as it appears in the STB/XML 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 from
+ * The Stairway.
+ *
+ * You can optionally provide a room grid index as an argument to get the sub-type for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
  */
-export declare function getRoomStageID(roomGridIndex?: int): StageID | -1;
+export declare function getRoomSubType(): int;
 /**
- * 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.
+ * Helper function to get the sub-type for a room as it appears in the STB/XML 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 from
+ * The Stairway.
  *
  * @param roomGridIndex Optional. Default is the current room index.
- * @returns The room sub-type. Returns -1 if the room data was not found.
+ * @returns The room sub-type. Returns undefined if the room data was not found.
  */
-export declare function getRoomSubType(roomGridIndex?: int): int;
+export declare function getRoomSubType(roomGridIndex?: int): int | undefined;
 /**
- * Helper function for getting the type of the room with the given grid index.
+ * Helper function to get the type for the current room as it appears in the STB/XML data.
+ *
+ * You can optionally provide a room grid index as an argument to get the type for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
+export declare function getRoomType(): RoomType;
+/**
+ * Helper function to get the type for a room as it appears in the STB/XML data.
  *
  * @param roomGridIndex Optional. Default is the current room index.
- * @returns The room data type. Returns -1 if the room data was not found.
+ * @returns The room type. Returns undefined if the room data was not found.
  */
-export declare function getRoomType(roomGridIndex?: int): RoomType | -1;
+export declare function getRoomType(roomGridIndex?: int): RoomType | undefined;
 /**
- * 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.
+ * Helper function to get the variant for the current room as it appears in the STB/XML 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.
+ *
+ * You can optionally provide a room grid index as an argument to get the variant for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
+export declare function getRoomVariant(): int;
+/**
+ * Helper function to get the variant for a room as it appears in the STB/XML 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 room data was not found.
+ * @returns The room variant. Returns undefined if the room data was not found.
  */
-export declare function getRoomVariant(roomGridIndex?: int): int;
+export declare function getRoomVariant(roomGridIndex?: int): int | undefined;
 /**
  * Note that the room visited count will be inaccurate during the period before the `POST_NEW_ROOM`
  * callback has fired (i.e. when entities are initializing and performing their first update). This

package/dist/src/functions/roomData.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"roomData.d.ts","sourceRoot":"","sources":["../../../src/functions/roomData.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,OAAO,EACR,MAAM,8BAA8B,CAAC;AAMtC;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC,CAgBtE;AAGD,wBAAgB,WAAW,IAAI,UAAU,CAAC;AAC1C,wBAAgB,WAAW,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,UAAU,GAAG,SAAS,CAAC;AAYzE;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,cAAc,CAQrE;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,QAAQ,CAAC,cAAc,CAAC,CAGpE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,IAAI,GAAG,CAGtC;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,GAAG,CAGzD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,MAAM,CAGvD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,SAAS,GAAG,SAAS,CAGvE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,OAAO,GAAG,CAAC,CAAC,CAGhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,GAAG,CAGvD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,QAAQ,GAAG,CAAC,CAAC,CAG9D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,GAAG,CAGvD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,GAAG,CAG5D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,aAAa,EAAE,GAAG,EAAE,QAAQ,EAAE,UAAU,GAAG,IAAI,CAG1E"}
+{"version":3,"file":"roomData.d.ts","sourceRoot":"","sources":["../../../src/functions/roomData.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,OAAO,EACR,MAAM,8BAA8B,CAAC;AAMtC;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC,CAgBtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,IAAI,UAAU,CAAC;AAE1C;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,UAAU,GAAG,SAAS,CAAC;AAOzE;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,cAAc,CAQrE;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,QAAQ,CAAC,cAAc,CAAC,CAGpE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,IAAI,GAAG,CAUtC;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,GAAG,CAGzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAAC;AAEtC;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAAC;AAOrE;;;;;;;;GAQG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAAC;AAE1C;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,SAAS,GAAG,SAAS,CAAC;AAOzE;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAAC;AAE1C;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,OAAO,GAAG,SAAS,CAAC;AAOzE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,IAAI,GAAG,CAAC;AAEtC;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,SAAS,CAAC;AAOrE;;;;;;;;GAQG;AACH,wBAAgB,WAAW,IAAI,QAAQ,CAAC;AAExC;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,QAAQ,GAAG,SAAS,CAAC;AAavE;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,IAAI,GAAG,CAAC;AAEtC;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,SAAS,CAAC;AAOrE;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,CAAC,EAAE,GAAG,GAAG,GAAG,CAG5D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,aAAa,EAAE,GAAG,EAAE,QAAQ,EAAE,UAAU,GAAG,IAAI,CAG1E"}

package/dist/src/functions/roomData.lua

@@ -10,9 +10,17 @@ local ____doors = require("src.functions.doors")
 local doorSlotFlagToDoorSlot = ____doors.doorSlotFlagToDoorSlot
 local ____flag = require("src.functions.flag")
 local hasFlag = ____flag.hasFlag
---- Helper function to get the room data for the provided room.
+--- Helper function to get the room data for the current room.
+-- 
+-- You can optionally provide a room grid index as an argument to get the data for that room
+-- instead.
+-- 
+-- (The version of the function without any arguments will not return undefined since the current
+-- room is guaranteed to have data.)
+-- Helper function to get the room data for the current or provided room.
 -- 
 -- @param roomGridIndex Optional. Default is the current room index.
+-- @returns The room data for the room or undefined if the provided room does not have any data.
 function ____exports.getRoomData(self, roomGridIndex)
     local roomDescriptor = ____exports.getRoomDescriptor(nil, roomGridIndex)
     return roomDescriptor.Data
@@ -33,12 +41,15 @@ function ____exports.getRoomDescriptorReadOnly(self)
     local level = game:GetLevel()
     return level:GetCurrentRoomDesc()
 end
---- Helper function to get the safe grid index of the current room. (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.)
+--- Helper function to get the grid index of the current room.
 -- 
--- Under the hood, this function uses the `Level.GetCurrentRoomDesc` method. (In Afterbirth+, this
--- method was bugged for rooms outside of the grid, but it is now fixed.)
+-- - 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, as
+--   demonstrated by entering a Genesis room and entering `l
+--   print(Game():GetLevel():GetCurrentRoomDesc().SafeGridIndex)` into the console).
 -- 
 -- 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,
@@ -47,6 +58,11 @@ end
 -- Data structures that store data per room should use the room's `ListIndex` instead of
 -- `SafeGridIndex`, since the former is unique across different dimensions.
 function ____exports.getRoomGridIndex(self)
+    local level = game:GetLevel()
+    local currentRoomIndex = level:GetCurrentRoomIndex()
+    if currentRoomIndex < 0 then
+        return currentRoomIndex
+    end
     local roomDescriptor = ____exports.getRoomDescriptorReadOnly(nil)
     return roomDescriptor.SafeGridIndex
 end
@@ -78,63 +94,147 @@ function ____exports.getRoomListIndex(self, roomGridIndex)
     local roomDescriptor = ____exports.getRoomDescriptor(nil, roomGridIndex)
     return roomDescriptor.ListIndex
 end
---- Helper function to get the name of the room as it appears in the STB/XML data.
+--- Helper function to get the name of the current room as it appears in the STB/XML data.
+-- 
+-- You can optionally provide a room grid index as an argument to get the name for that room
+-- instead.
+-- 
+-- (The version of the function without any arguments will not return undefined since the current
+-- room is guaranteed to have data.)
+-- 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 room data was not found.
+-- @returns The room name. Returns undefined if the room data was not found.
 function ____exports.getRoomName(self, roomGridIndex)
     local roomData = ____exports.getRoomData(nil, roomGridIndex)
-    return roomData == nil and "Unknown" or roomData.Name
+    local ____temp_0
+    if roomData == nil then
+        ____temp_0 = nil
+    else
+        ____temp_0 = roomData.Name
+    end
+    return ____temp_0
 end
---- Helper function to get the name of the room as it appears in the STB/XML data.
+--- Helper function to get the shape of the current room as it appears in the STB/XML data.
+-- 
+-- You can optionally provide a room grid index as an argument to get the shape for that room
+-- instead.
+-- 
+-- (The version of the function without any arguments will not return undefined since the current
+-- room is guaranteed to have data.)
+-- Helper function to get the shape 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 room data was not found.
+-- @returns The room shape. Returns undefined if the room data was not found.
 function ____exports.getRoomShape(self, roomGridIndex)
     local roomData = ____exports.getRoomData(nil, roomGridIndex)
-    local ____temp_0
+    local ____temp_1
     if roomData == nil then
-        ____temp_0 = nil
+        ____temp_1 = nil
     else
-        ____temp_0 = roomData.Shape
+        ____temp_1 = roomData.Shape
     end
-    return ____temp_0
+    return ____temp_1
 end
---- 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.
+--- Helper function to get the stage ID for the current room as it appears in the STB/XML 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 `StageID.DEPTHS` (7).
+-- 
+-- You can optionally provide a room grid index as an argument to get the stage ID for that room
+-- instead.
+-- 
+-- (The version of the function without any arguments will not return undefined since the current
+-- room is guaranteed to have data.)
+-- Helper function to get the stage ID for a room as it appears in the STB/XML 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 `StageID.DEPTHS` (7).
 -- 
 -- @param roomGridIndex Optional. Default is the current room index.
--- @returns The room stage ID. Returns -1 if the room data was not found.
+-- @returns The room stage ID. Returns undefined if the room data was not found.
 function ____exports.getRoomStageID(self, roomGridIndex)
     local roomData = ____exports.getRoomData(nil, roomGridIndex)
-    return roomData == nil and -1 or roomData.StageID
+    local ____temp_2
+    if roomData == nil then
+        ____temp_2 = nil
+    else
+        ____temp_2 = roomData.StageID
+    end
+    return ____temp_2
 end
---- 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.
+--- Helper function to get the sub-type for the current room as it appears in the STB/XML 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 from
+-- The Stairway.
+-- 
+-- You can optionally provide a room grid index as an argument to get the sub-type for that room
+-- instead.
+-- 
+-- (The version of the function without any arguments will not return undefined since the current
+-- room is guaranteed to have data.)
+-- Helper function to get the sub-type for a room as it appears in the STB/XML 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 from
+-- The Stairway.
 -- 
 -- @param roomGridIndex Optional. Default is the current room index.
--- @returns The room sub-type. Returns -1 if the room data was not found.
+-- @returns The room sub-type. Returns undefined if the room data was not found.
 function ____exports.getRoomSubType(self, roomGridIndex)
     local roomData = ____exports.getRoomData(nil, roomGridIndex)
-    return roomData == nil and -1 or roomData.Subtype
+    local ____temp_3
+    if roomData == nil then
+        ____temp_3 = nil
+    else
+        ____temp_3 = roomData.Subtype
+    end
+    return ____temp_3
 end
---- Helper function for getting the type of the room with the given grid index.
+--- Helper function to get the type for the current room as it appears in the STB/XML data.
 -- 
+-- You can optionally provide a room grid index as an argument to get the type for that room
+-- instead.
+-- 
+-- (The version of the function without any arguments will not return undefined since the current
+-- room is guaranteed to have data.)
+-- Helper function to get the type for a room as it appears in the STB/XML data.
+-- 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 type. Returns undefined if the room data was not found.
 -- @param roomGridIndex Optional. Default is the current room index.
 -- @returns The room data type. Returns -1 if the room data was not found.
 function ____exports.getRoomType(self, roomGridIndex)
     local roomData = ____exports.getRoomData(nil, roomGridIndex)
-    return roomData == nil and -1 or roomData.Type
+    local ____temp_4
+    if roomData == nil then
+        ____temp_4 = nil
+    else
+        ____temp_4 = roomData.Type
+    end
+    return ____temp_4
 end
---- 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.
+--- Helper function to get the variant for the current room as it appears in the STB/XML 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.
+-- 
+-- You can optionally provide a room grid index as an argument to get the variant for that room
+-- instead.
+-- 
+-- (The version of the function without any arguments will not return undefined since the current
+-- room is guaranteed to have data.)
+-- Helper function to get the variant for a room as it appears in the STB/XML 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 room data was not found.
+-- @returns The room variant. Returns undefined if the room data was not found.
 function ____exports.getRoomVariant(self, roomGridIndex)
     local roomData = ____exports.getRoomData(nil, roomGridIndex)
     return roomData == nil and -1 or roomData.Variant

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "34.1.0",
+  "version": "35.0.0",
   "description": "Helper functions and features for IsaacScript mods.",
   "keywords": [
     "isaac",

package/src/functions/array.ts

@@ -335,6 +335,10 @@ function addCombinations<T>(
  * Helper function to get an array containing the indexes of an array.
  *
  * For example, an array of `["Apple", "Banana"]` would return an array of `[0, 1]`.
+ *
+ * Note that normally, you would use the `Object.keys` method to get the indexes of an array, but
+ * due to implementation details of TypeScriptToLua, this results in an array of 1 through N
+ * (instead of an array of 0 through N -1).
  */
 export function getArrayIndexes<T>(array: T[] | readonly T[]): int[] {
   return eRange(array.length);

package/src/functions/enums.ts

@@ -154,12 +154,12 @@ export function getRandomEnumValue<T>(
 }
 
 /** Helper function to validate that a particular value exists inside of an enum. */
-export function isEnumValue(
+export function isEnumValue<T extends Record<string, number | string>>(
   value: number | string,
-  transpiledEnum: Record<string | number, string | number>,
-): boolean {
+  transpiledEnum: T,
+): value is T[keyof T] {
   const enumValues = getEnumValues(transpiledEnum);
-  return enumValues.includes(value);
+  return enumValues.includes(value as T[keyof T]);
 }
 
 /**

package/src/functions/jsonRoom.ts

@@ -25,18 +25,17 @@ export function getJSONRoomDoorSlotFlags(
   jsonRoom: JSONRoom,
 ): BitFlags<DoorSlotFlag> {
   const roomShapeString = jsonRoom.$.shape;
-  const roomShapeNumber = tonumber(roomShapeString);
+  const roomShape = tonumber(roomShapeString);
   assertDefined(
-    roomShapeNumber,
+    roomShape,
     `Failed to parse the "shape" field of a JSON room: ${roomShapeString}`,
   );
 
-  if (!isEnumValue(roomShapeNumber, RoomShape)) {
+  if (!isEnumValue(roomShape, RoomShape)) {
     error(
-      `Failed to parse the "shape" field of a JSON room since it was an invalid number: ${roomShapeNumber}`,
+      `Failed to parse the "shape" field of a JSON room since it was an invalid number: ${roomShape}`,
     );
   }
-  const roomShape = roomShapeNumber as RoomShape;
 
   let doorSlotFlags = DoorSlotFlagZero;
 

package/src/functions/roomData.ts

@@ -31,15 +31,25 @@ export function getRoomAllowedDoors(roomGridIndex?: int): Set<DoorSlot> {
   return allowedDoors;
 }
 
-// We provide an overload because the current room is guaranteed to have data.
+/**
+ * Helper function to get the room data for the current room.
+ *
+ * You can optionally provide a room grid index as an argument to get the data for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
 export function getRoomData(): RoomConfig;
-export function getRoomData(roomGridIndex?: int): RoomConfig | undefined;
 
 /**
- * Helper function to get the room data for the provided room.
+ * Helper function to get the room data for the current or provided room.
  *
  * @param roomGridIndex Optional. Default is the current room index.
+ * @returns The room data for the room or undefined if the provided room does not have any data.
  */
+export function getRoomData(roomGridIndex?: int): RoomConfig | undefined;
+
 export function getRoomData(roomGridIndex?: int): RoomConfig | undefined {
   const roomDescriptor = getRoomDescriptor(roomGridIndex);
   return roomDescriptor.Data;
@@ -70,12 +80,15 @@ export function getRoomDescriptorReadOnly(): Readonly<RoomDescriptor> {
 }
 
 /**
- * Helper function to get the safe grid index of the current room. (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.)
+ * Helper function to get the grid index of the current room.
  *
- * Under the hood, this function uses the `Level.GetCurrentRoomDesc` method. (In Afterbirth+, this
- * method was bugged for rooms outside of the grid, but it is now fixed.)
+ * - 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, as
+ *   demonstrated by entering a Genesis room and entering `l
+ *   print(Game():GetLevel():GetCurrentRoomDesc().SafeGridIndex)` into the console).
  *
  * 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,
@@ -85,6 +98,13 @@ export function getRoomDescriptorReadOnly(): Readonly<RoomDescriptor> {
  * `SafeGridIndex`, since the former is unique across different dimensions.
  */
 export function getRoomGridIndex(): int {
+  const level = game.GetLevel();
+  const currentRoomIndex = level.GetCurrentRoomIndex();
+
+  if (currentRoomIndex < 0) {
+    return currentRoomIndex;
+  }
+
   const roomDescriptor = getRoomDescriptorReadOnly();
   return roomDescriptor.SafeGridIndex;
 }
@@ -104,74 +124,173 @@ export function getRoomListIndex(roomGridIndex?: int): int {
   return roomDescriptor.ListIndex;
 }
 
+/**
+ * Helper function to get the name of the current room as it appears in the STB/XML data.
+ *
+ * You can optionally provide a room grid index as an argument to get the name for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
+export function getRoomName(): string;
+
 /**
  * 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 room data was not found.
+ * @returns The room name. Returns undefined if the room data was not found.
  */
-export function getRoomName(roomGridIndex?: int): string {
+export function getRoomName(roomGridIndex?: int): string | undefined;
+
+export function getRoomName(roomGridIndex?: int): string | undefined {
   const roomData = getRoomData(roomGridIndex);
-  return roomData === undefined ? "Unknown" : roomData.Name;
+  return roomData === undefined ? undefined : roomData.Name;
 }
 
 /**
- * Helper function to get the name of the room as it appears in the STB/XML data.
+ * Helper function to get the shape of the current room as it appears in the STB/XML data.
+ *
+ * You can optionally provide a room grid index as an argument to get the shape for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
+export function getRoomShape(): RoomShape;
+
+/**
+ * Helper function to get the shape 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 room data was not found.
+ * @returns The room shape. Returns undefined if the room data was not found.
  */
+export function getRoomShape(roomGridIndex?: int): RoomShape | undefined;
+
 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.
+ * Helper function to get the stage ID for the current room as it appears in the STB/XML 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 `StageID.DEPTHS` (7).
+ *
+ * You can optionally provide a room grid index as an argument to get the stage ID for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
+export function getRoomStageID(): StageID;
+
+/**
+ * Helper function to get the stage ID for a room as it appears in the STB/XML 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 `StageID.DEPTHS` (7).
  *
  * @param roomGridIndex Optional. Default is the current room index.
- * @returns The room stage ID. Returns -1 if the room data was not found.
+ * @returns The room stage ID. Returns undefined if the room data was not found.
  */
-export function getRoomStageID(roomGridIndex?: int): StageID | -1 {
+export function getRoomStageID(roomGridIndex?: int): StageID | undefined;
+
+export function getRoomStageID(roomGridIndex?: int): StageID | undefined {
   const roomData = getRoomData(roomGridIndex);
-  return roomData === undefined ? -1 : roomData.StageID;
+  return roomData === undefined ? undefined : 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.
+ * Helper function to get the sub-type for the current room as it appears in the STB/XML 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 from
+ * The Stairway.
+ *
+ * You can optionally provide a room grid index as an argument to get the sub-type for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
+export function getRoomSubType(): int;
+
+/**
+ * Helper function to get the sub-type for a room as it appears in the STB/XML 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 from
+ * The Stairway.
  *
  * @param roomGridIndex Optional. Default is the current room index.
- * @returns The room sub-type. Returns -1 if the room data was not found.
+ * @returns The room sub-type. Returns undefined if the room data was not found.
  */
-export function getRoomSubType(roomGridIndex?: int): int {
+export function getRoomSubType(roomGridIndex?: int): int | undefined;
+
+export function getRoomSubType(roomGridIndex?: int): int | undefined {
   const roomData = getRoomData(roomGridIndex);
-  return roomData === undefined ? -1 : roomData.Subtype;
+  return roomData === undefined ? undefined : roomData.Subtype;
 }
 
+/**
+ * Helper function to get the type for the current room as it appears in the STB/XML data.
+ *
+ * You can optionally provide a room grid index as an argument to get the type for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
+export function getRoomType(): RoomType;
+
+/**
+ * Helper function to get the type for a room as it appears in the STB/XML data.
+ *
+ * @param roomGridIndex Optional. Default is the current room index.
+ * @returns The room type. Returns undefined if the room data was not found.
+ */
+export function getRoomType(roomGridIndex?: int): RoomType | undefined;
+
 /**
  * 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 room data was not found.
  */
-export function getRoomType(roomGridIndex?: int): RoomType | -1 {
+export function getRoomType(roomGridIndex?: int): RoomType | undefined {
   const roomData = getRoomData(roomGridIndex);
-  return roomData === undefined ? -1 : roomData.Type;
+  return roomData === undefined ? undefined : 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.
+ * Helper function to get the variant for the current room as it appears in the STB/XML 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.
+ *
+ * You can optionally provide a room grid index as an argument to get the variant for that room
+ * instead.
+ *
+ * (The version of the function without any arguments will not return undefined since the current
+ * room is guaranteed to have data.)
+ */
+export function getRoomVariant(): int;
+
+/**
+ * Helper function to get the variant for a room as it appears in the STB/XML 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 room data was not found.
+ * @returns The room variant. Returns undefined if the room data was not found.
  */
+export function getRoomVariant(roomGridIndex?: int): int | undefined;
+
 export function getRoomVariant(roomGridIndex?: int): int {
   const roomData = getRoomData(roomGridIndex);
   return roomData === undefined ? -1 : roomData.Variant;