isaacscript-common 5.1.0 → 5.1.3

package/features/customGridEntity.d.ts

@@ -0,0 +1,41 @@
+import { GridCollisionClass, GridEntityType } from "isaac-typescript-definitions";
+/**
+ * Helper function to spawn a custom grid entity.
+ *
+ * This is an IsaacScript feature because the vanilla game does not support any custom grid
+ * entities. Under the hood, IsaacScript accomplishes this by using decorations to represent custom
+ * grid entities.
+ *
+ * Once a custom grid entity is spawned, you can take advantage of the custom grid callbacks such as
+ * `POST_GRID_ENTITY_CUSTOM_UPDATE`.
+ *
+ * @param gridEntityTypeCustom An integer that identifies what kind of grid entity you are creating.
+ *                             It should correspond to a local enum value in your mod. The integer
+ *                             can be any unique value and will not correspond to the actual grid
+ *                             entity type used. (This integer is used in the various custom grid
+ *                             entity callbacks.)
+ * @param gridIndexOrPosition The grid index or position in the room that you want to spawn the grid
+ *                            entity at. If a position is specified, the closest grid index will be
+ *                            used.
+ * @param anm2 The path to the ANM2 file to use for the sprite.
+ * @param defaultAnimation The name of the animation to play after the sprite is initialized and
+ *                         after the player re-enters a room with this grid entity in it.
+ * @param gridCollisionClass The collision class that you want the custom grid entity to have.
+ */
+export declare function spawnCustomGrid(gridEntityTypeCustom: GridEntityType, gridIndexOrPosition: int | Vector, anm2: string, defaultAnimation: string, gridCollisionClass: GridCollisionClass): GridEntity;
+/**
+ * Helper function to remove a custom grid entity created by the `spawnCustomGrid` function.
+ *
+ * @param gridIndexOrPositionOrGridEntity You can specify the custom grid entity to remove by
+ *                                 providing the grid index, the room position, or the grid entity
+ *                                 itself.
+ * @param updateRoom Optional. Whether or not to update the room after the grid entity is removed.
+ *                   Default is true. This is generally a good idea because if the room is not
+ *                   updated, you will be unable to spawn another grid entity on the same tile until
+ *                   a frame has passed. However, doing this is expensive, since it involves a call
+ *                   to `Isaac.GetRoomEntities`, so set it to false if you need to invoke this
+ *                   function multiple times.
+ * @returns The grid entity that was removed. Returns undefined if no grid entity was found at the
+ *          given location or if the given grid entity was not a custom grid entity.
+ */
+export declare function removeCustomGrid(gridIndexOrPositionOrGridEntity: int | Vector | GridEntity, updateRoom?: boolean): GridEntity | undefined;

package/features/customGridEntity.lua

@@ -0,0 +1,154 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local __TS__New = ____lualib.__TS__New
+local __TS__Iterator = ____lualib.__TS__Iterator
+local ____exports = {}
+local postNewRoomReordered, v
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local GridEntityType = ____isaac_2Dtypescript_2Ddefinitions.GridEntityType
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+local ____DefaultMap = require("classes.DefaultMap")
+local DefaultMap = ____DefaultMap.DefaultMap
+local ____ModCallbackCustom = require("enums.ModCallbackCustom")
+local ModCallbackCustom = ____ModCallbackCustom.ModCallbackCustom
+local ____featuresInitialized = require("featuresInitialized")
+local errorIfFeaturesNotInitialized = ____featuresInitialized.errorIfFeaturesNotInitialized
+local ____gridEntity = require("functions.gridEntity")
+local removeGrid = ____gridEntity.removeGrid
+local spawnGrid = ____gridEntity.spawnGrid
+local ____roomData = require("functions.roomData")
+local getRoomListIndex = ____roomData.getRoomListIndex
+local ____vector = require("functions.vector")
+local isVector = ____vector.isVector
+local ____exports = require("features.saveDataManager.exports")
+local saveDataManager = ____exports.saveDataManager
+function postNewRoomReordered(self)
+    local roomListIndex = getRoomListIndex(nil)
+    local roomCustomGridEntities = v.level.customGridEntities:get(roomListIndex)
+    if roomCustomGridEntities == nil then
+        return
+    end
+    local room = game:GetRoom()
+    for ____, ____value in __TS__Iterator(roomCustomGridEntities:entries()) do
+        local gridIndex = ____value[1]
+        local data = ____value[2]
+        do
+            local decoration = room:GetGridEntity(gridIndex)
+            if decoration == nil then
+                roomCustomGridEntities:delete(gridIndex)
+                goto __continue6
+            end
+            local sprite = decoration:GetSprite()
+            sprite:Load(data.anm2, true)
+            sprite:Play(data.defaultAnimation, true)
+        end
+        ::__continue6::
+    end
+end
+local FEATURE_NAME = "customGridEntity"
+v = {level = {customGridEntities = __TS__New(
+    DefaultMap,
+    function() return __TS__New(Map) end
+)}}
+---
+-- @internal
+function ____exports.customGridEntityInit(self, mod)
+    saveDataManager(nil, FEATURE_NAME, v)
+    mod:AddCallbackCustom(ModCallbackCustom.POST_NEW_ROOM_REORDERED, postNewRoomReordered)
+end
+--- Helper function to spawn a custom grid entity.
+-- 
+-- This is an IsaacScript feature because the vanilla game does not support any custom grid
+-- entities. Under the hood, IsaacScript accomplishes this by using decorations to represent custom
+-- grid entities.
+-- 
+-- Once a custom grid entity is spawned, you can take advantage of the custom grid callbacks such as
+-- `POST_GRID_ENTITY_CUSTOM_UPDATE`.
+-- 
+-- @param gridEntityTypeCustom An integer that identifies what kind of grid entity you are creating.
+-- It should correspond to a local enum value in your mod. The integer
+-- can be any unique value and will not correspond to the actual grid
+-- entity type used. (This integer is used in the various custom grid
+-- entity callbacks.)
+-- @param gridIndexOrPosition The grid index or position in the room that you want to spawn the grid
+-- entity at. If a position is specified, the closest grid index will be
+-- used.
+-- @param anm2 The path to the ANM2 file to use for the sprite.
+-- @param defaultAnimation The name of the animation to play after the sprite is initialized and
+-- after the player re-enters a room with this grid entity in it.
+-- @param gridCollisionClass The collision class that you want the custom grid entity to have.
+function ____exports.spawnCustomGrid(self, gridEntityTypeCustom, gridIndexOrPosition, anm2, defaultAnimation, gridCollisionClass)
+    errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
+    local room = game:GetRoom()
+    local roomListIndex = getRoomListIndex(nil)
+    local gridIndex = isVector(nil, gridIndexOrPosition) and room:GetGridIndex(gridIndexOrPosition) or gridIndexOrPosition
+    local existingGridEntity = room:GetGridEntity(gridIndex)
+    local isExistingDecoration = existingGridEntity ~= nil and existingGridEntity:GetType() == GridEntityType.DECORATION
+    local decoration = isExistingDecoration and existingGridEntity or spawnGrid(nil, GridEntityType.DECORATION, gridIndexOrPosition)
+    if decoration == nil then
+        error("Failed to spawn a decoration for a custom grid entity.")
+    end
+    local sprite = decoration:GetSprite()
+    sprite:Load(anm2, true)
+    sprite:Play(defaultAnimation, true)
+    local customGridEntityData = {
+        gridEntityTypeCustom = gridEntityTypeCustom,
+        roomListIndex = roomListIndex,
+        gridIndex = gridIndex,
+        anm2 = anm2,
+        defaultAnimation = defaultAnimation,
+        gridCollisionClass = gridCollisionClass
+    }
+    local roomCustomGridEntities = v.level.customGridEntities:getAndSetDefault(roomListIndex)
+    roomCustomGridEntities:set(gridIndex, customGridEntityData)
+    return decoration
+end
+--- Helper function to remove a custom grid entity created by the `spawnCustomGrid` function.
+-- 
+-- @param gridIndexOrPositionOrGridEntity You can specify the custom grid entity to remove by
+-- providing the grid index, the room position, or the grid entity
+-- itself.
+-- @param updateRoom Optional. Whether or not to update the room after the grid entity is removed.
+-- Default is true. This is generally a good idea because if the room is not
+-- updated, you will be unable to spawn another grid entity on the same tile until
+-- a frame has passed. However, doing this is expensive, since it involves a call
+-- to `Isaac.GetRoomEntities`, so set it to false if you need to invoke this
+-- function multiple times.
+-- @returns The grid entity that was removed. Returns undefined if no grid entity was found at the
+-- given location or if the given grid entity was not a custom grid entity.
+function ____exports.removeCustomGrid(self, gridIndexOrPositionOrGridEntity, updateRoom)
+    if updateRoom == nil then
+        updateRoom = true
+    end
+    local room = game:GetRoom()
+    local roomListIndex = getRoomListIndex(nil)
+    local decoration
+    if type(gridIndexOrPositionOrGridEntity) == "number" then
+        local gridIndex = gridIndexOrPositionOrGridEntity
+        local gridEntity = room:GetGridEntity(gridIndex)
+        if gridEntity == nil then
+            return nil
+        end
+        decoration = gridEntity
+    elseif isVector(nil, gridIndexOrPositionOrGridEntity) then
+        local position = gridIndexOrPositionOrGridEntity
+        local gridEntity = room:GetGridEntityFromPos(position)
+        if gridEntity == nil then
+            return nil
+        end
+        decoration = gridEntity
+    else
+        decoration = gridIndexOrPositionOrGridEntity
+    end
+    local gridIndex = decoration:GetGridIndex()
+    local roomCustomGridEntities = v.level.customGridEntities:getAndSetDefault(roomListIndex)
+    local exists = roomCustomGridEntities:has(gridIndex)
+    if not exists then
+        return nil
+    end
+    roomCustomGridEntities:delete(gridIndex)
+    removeGrid(nil, decoration, updateRoom)
+    return decoration
+end
+return ____exports

package/features/customStage/constants.d.ts

@@ -0,0 +1,18 @@
+import { RoomType } from "isaac-typescript-definitions";
+/**
+ * In order to keep the size of the STB file small, we only allow certain room types to be used in
+ * IsaacScript custom stages.
+ */
+export declare const CUSTOM_STAGE_ILLEGAL_ROOM_TYPES: Set<RoomType>;
+/** StageAPI uses 70000 as a base. */
+export declare const CUSTOM_STAGE_BASE_ROOM_VARIANT = 80000;
+/**
+ * - The `RoomShape` enum goes from 1 to 12.
+ * - 12 in binary is 1100.
+ * - Thus, we need 4 bits to represent `RoomShape`.
+ */
+export declare const CUSTOM_STAGE_NUM_ROOM_SHAPE_BITS = 4;
+/**
+ * One for each possible door slot. We add one to account for `DoorSlot.LEFT_0` being equal to zero.
+ */
+export declare const CUSTOM_STAGE_NUM_DOOR_SLOT_BITS: number;

package/features/customStage/constants.lua

@@ -0,0 +1,29 @@
+local ____lualib = require("lualib_bundle")
+local Set = ____lualib.Set
+local __TS__New = ____lualib.__TS__New
+local ____exports = {}
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local DoorSlot = ____isaac_2Dtypescript_2Ddefinitions.DoorSlot
+local RoomType = ____isaac_2Dtypescript_2Ddefinitions.RoomType
+local ____enums = require("functions.enums")
+local getLastEnumValue = ____enums.getLastEnumValue
+--- In order to keep the size of the STB file small, we only allow certain room types to be used in
+-- IsaacScript custom stages.
+____exports.CUSTOM_STAGE_ILLEGAL_ROOM_TYPES = __TS__New(Set, {
+    RoomType.BOSS_RUSH,
+    RoomType.BLACK_MARKET,
+    RoomType.GREED_EXIT,
+    RoomType.TELEPORTER,
+    RoomType.TELEPORTER_EXIT,
+    RoomType.SECRET_EXIT,
+    RoomType.BLUE
+})
+--- StageAPI uses 70000 as a base.
+____exports.CUSTOM_STAGE_BASE_ROOM_VARIANT = 80000
+--- - The `RoomShape` enum goes from 1 to 12.
+-- - 12 in binary is 1100.
+-- - Thus, we need 4 bits to represent `RoomShape`.
+____exports.CUSTOM_STAGE_NUM_ROOM_SHAPE_BITS = 4
+--- One for each possible door slot. We add one to account for `DoorSlot.LEFT_0` being equal to zero.
+____exports.CUSTOM_STAGE_NUM_DOOR_SLOT_BITS = getLastEnumValue(nil, DoorSlot) + 1
+return ____exports

package/features/customStage/exports.d.ts

@@ -0,0 +1,13 @@
+import { LevelStage } from "isaac-typescript-definitions";
+import { JSONRoom } from "../../interfaces/JSONRoom";
+/**
+ * Helper function to register a new custom stage with the IsaacScript standard library stage
+ * system.
+ */
+export declare function registerCustomStage(name: string, baseStage: LevelStage, jsonRooms: JSONRoom[] | readonly JSONRoom[]): void;
+/**
+ * Helper function to warp to a custom stage/level.
+ *
+ * Custom stages/levels must first be registered with the `registerCustomStage` function.
+ */
+export declare function setCustomStage(_name: string): void;

package/features/customStage/exports.lua

@@ -0,0 +1,23 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local ____exports = {}
+local ____v = require("features.customStage.v")
+local customStages = ____v.customStages
+--- Helper function to register a new custom stage with the IsaacScript standard library stage
+-- system.
+function ____exports.registerCustomStage(self, name, baseStage, jsonRooms)
+    if customStages:has(name) then
+        error(("Failed to register a custom stage of \"" .. name) .. "\" since there is already a custom stage registered by that name.")
+    end
+    if #jsonRooms == 0 then
+        error(("Failed to register a custom stage of \"" .. name) .. "\" since the provided JSON room array was empty.")
+    end
+    local customStageData = {name = name, baseStage = baseStage}
+    customStages:set(name, customStageData)
+end
+--- Helper function to warp to a custom stage/level.
+-- 
+-- Custom stages/levels must first be registered with the `registerCustomStage` function.
+function ____exports.setCustomStage(self, _name)
+end
+return ____exports

package/features/customStage/scripts/generateCustomStageRooms.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Since room data is immutable, we need to create an array of empty rooms like the following:
+ *
+ * ```xml
+ * <room variant="80150" name="1x1" type="2" subtype="0" shape="1" width="13" height="7"
+ * difficulty="1" weight="0.0">
+ *   <door exists="True" x="-1" y="3"/>
+ *   <door exists="True" x="6" y="-1"/>
+ *   <door exists="True" x="6" y="7"/>
+ *   <door exists="True" x="13" y="3"/>
+ * </room>
+ * ```
+ *
+ * - We can repeat room variants between different room types.
+ * - The `RoomShape` enum goes from 1 to 12.
+ *   - 12 in binary is 1100.
+ *   - Thus, we need 4 bits to represent `RoomShape`.
+ * - There are 8 possible door slots.
+ *   - Thus, we need 8 bits to represent `BitFlags<DoorSlot>`.
+ *
+ * Thus, the room variant has the following sequence:
+ * - 4 bits of `RoomShape` + 8 bits of `BitFlags<DoorSlot>`
+ *
+ * Even though Basement Renovator does not allow setting variants to values above 16 bits, values
+ * with 17 bits work fine in-game.
+ */
+export declare function generateCustomStageBaseRooms(): void;

package/features/customStage/scripts/generateCustomStageRooms.lua

@@ -0,0 +1,126 @@
+local ____lualib = require("lualib_bundle")
+local Set = ____lualib.Set
+local __TS__New = ____lualib.__TS__New
+local __TS__SparseArrayNew = ____lualib.__TS__SparseArrayNew
+local __TS__SparseArrayPush = ____lualib.__TS__SparseArrayPush
+local __TS__SparseArraySpread = ____lualib.__TS__SparseArraySpread
+local __TS__StringTrim = ____lualib.__TS__StringTrim
+local __TS__StringSplit = ____lualib.__TS__StringSplit
+local ____exports = {}
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local DoorSlot = ____isaac_2Dtypescript_2Ddefinitions.DoorSlot
+local RoomShape = ____isaac_2Dtypescript_2Ddefinitions.RoomShape
+local RoomType = ____isaac_2Dtypescript_2Ddefinitions.RoomType
+local ____bitwise = require("functions.bitwise")
+local convertBinaryToDecimal = ____bitwise.convertBinaryToDecimal
+local convertDecimalToBinary = ____bitwise.convertDecimalToBinary
+local setToBitFlags = ____bitwise.setToBitFlags
+local ____doors = require("functions.doors")
+local doorSlotToDoorSlotFlag = ____doors.doorSlotToDoorSlotFlag
+local getDoorSlotsForRoomShape = ____doors.getDoorSlotsForRoomShape
+local getRoomShapeDoorSlotCoordinates = ____doors.getRoomShapeDoorSlotCoordinates
+local ____enums = require("functions.enums")
+local getEnumValues = ____enums.getEnumValues
+local ____flag = require("functions.flag")
+local hasFlag = ____flag.hasFlag
+local ____roomShape = require("functions.roomShape")
+local getRoomShapeLayoutSize = ____roomShape.getRoomShapeLayoutSize
+local ____set = require("functions.set")
+local getSetCombinations = ____set.getSetCombinations
+local getSortedSetValues = ____set.getSortedSetValues
+local ____constants = require("features.customStage.constants")
+local CUSTOM_STAGE_BASE_ROOM_VARIANT = ____constants.CUSTOM_STAGE_BASE_ROOM_VARIANT
+local CUSTOM_STAGE_ILLEGAL_ROOM_TYPES = ____constants.CUSTOM_STAGE_ILLEGAL_ROOM_TYPES
+local CUSTOM_STAGE_NUM_DOOR_SLOT_BITS = ____constants.CUSTOM_STAGE_NUM_DOOR_SLOT_BITS
+local CUSTOM_STAGE_NUM_ROOM_SHAPE_BITS = ____constants.CUSTOM_STAGE_NUM_ROOM_SHAPE_BITS
+--- Since room data is immutable, we need to create an array of empty rooms like the following:
+-- 
+-- ```xml
+-- <room variant="80150" name="1x1" type="2" subtype="0" shape="1" width="13" height="7"
+-- difficulty="1" weight="0.0">
+--   <door exists="True" x="-1" y="3"/>
+--   <door exists="True" x="6" y="-1"/>
+--   <door exists="True" x="6" y="7"/>
+--   <door exists="True" x="13" y="3"/>
+-- </room>
+-- ```
+-- 
+-- - We can repeat room variants between different room types.
+-- - The `RoomShape` enum goes from 1 to 12.
+--   - 12 in binary is 1100.
+--   - Thus, we need 4 bits to represent `RoomShape`.
+-- - There are 8 possible door slots.
+--   - Thus, we need 8 bits to represent `BitFlags<DoorSlot>`.
+-- 
+-- Thus, the room variant has the following sequence:
+-- - 4 bits of `RoomShape` + 8 bits of `BitFlags<DoorSlot>`
+-- 
+-- Even though Basement Renovator does not allow setting variants to values above 16 bits, values
+-- with 17 bits work fine in-game.
+function ____exports.generateCustomStageBaseRooms(self)
+    local rooms = {}
+    for ____, roomType in ipairs(getEnumValues(nil, RoomType)) do
+        do
+            if CUSTOM_STAGE_ILLEGAL_ROOM_TYPES:has(roomType) then
+                goto __continue3
+            end
+            for ____, roomShape in ipairs(getEnumValues(nil, RoomShape)) do
+                do
+                    if roomType ~= RoomType.DEFAULT and roomShape ~= RoomShape.SHAPE_1x1 then
+                        goto __continue5
+                    end
+                    local roomShapeBits = convertDecimalToBinary(nil, roomShape, CUSTOM_STAGE_NUM_ROOM_SHAPE_BITS)
+                    local doorSlotsSet = getDoorSlotsForRoomShape(nil, roomShape)
+                    local doorSlots = getSortedSetValues(nil, doorSlotsSet)
+                    local doorSlotFlagsSet = __TS__New(Set)
+                    for ____, doorSlot in ipairs(doorSlots) do
+                        local doorSlotFlag = doorSlotToDoorSlotFlag(nil, doorSlot)
+                        doorSlotFlagsSet:add(doorSlotFlag)
+                    end
+                    local doorSlotFlagCombinations = getSetCombinations(nil, doorSlotFlagsSet, false)
+                    for ____, doorSlotFlagCombination in ipairs(doorSlotFlagCombinations) do
+                        local doorSlotFlags = setToBitFlags(nil, doorSlotFlagCombination)
+                        local doorSlotBits = convertDecimalToBinary(nil, doorSlotFlags, CUSTOM_STAGE_NUM_DOOR_SLOT_BITS)
+                        local ____array_0 = __TS__SparseArrayNew(table.unpack(roomShapeBits))
+                        __TS__SparseArrayPush(
+                            ____array_0,
+                            table.unpack(doorSlotBits)
+                        )
+                        local combinedBits = {__TS__SparseArraySpread(____array_0)}
+                        local roomVariant = CUSTOM_STAGE_BASE_ROOM_VARIANT + convertBinaryToDecimal(nil, combinedBits)
+                        local name = (((("Type: " .. tostring(roomType)) .. ", Shape: ") .. tostring(roomShape)) .. ", DoorSlotFlags: ") .. tostring(doorSlotFlags)
+                        local width, height = table.unpack(getRoomShapeLayoutSize(nil, roomShape))
+                        local roomHeader = ((((((((((("  <room name=\"" .. name) .. "\" type=\"") .. tostring(roomType)) .. "\" variant=\"") .. tostring(roomVariant)) .. "\" subtype=\"0\" shape=\"") .. tostring(roomShape)) .. "\" width=\"") .. tostring(width)) .. "\" height=\"") .. tostring(height)) .. "\" difficulty=\"1\" weight=\"0.0\">\n"
+                        local doors = {}
+                        for ____, doorSlot in ipairs(doorSlots) do
+                            local thisDoorSlotFlag = doorSlotToDoorSlotFlag(nil, doorSlot)
+                            local exists = hasFlag(nil, doorSlotFlags, thisDoorSlotFlag)
+                            local existsText = exists and "True" or "False"
+                            local coordinates = getRoomShapeDoorSlotCoordinates(nil, roomShape, doorSlot)
+                            if coordinates == nil then
+                                error(((((((("Failed to get the coordinates for room shape " .. tostring(RoomShape[roomShape])) .. " (") .. tostring(roomShape)) .. ") and door slot ") .. tostring(DoorSlot[doorSlot])) .. " (") .. tostring(doorSlot)) .. ").")
+                            end
+                            local x, y = table.unpack(coordinates)
+                            local door = ((((("    <door exists=\"" .. existsText) .. "\" x=\"") .. tostring(x)) .. "\" y=\"") .. tostring(y)) .. "\" />\n"
+                            doors[#doors + 1] = door
+                        end
+                        local doorsXML = table.concat(doors, "")
+                        local roomFooter = "  </room>\n"
+                        local room = (roomHeader .. doorsXML) .. roomFooter
+                        rooms[#rooms + 1] = room
+                    end
+                end
+                ::__continue5::
+            end
+        end
+        ::__continue3::
+    end
+    local xml = table.concat({
+        __TS__StringTrim(("\n<?xml version=\"1.0\" ?>\n<rooms>\n" .. table.concat(rooms, "")) .. "\n</rooms>"),
+        "\n"
+    })
+    for ____, line in ipairs(__TS__StringSplit(xml, "\n")) do
+        Isaac.DebugString(line)
+    end
+end
+return ____exports

package/features/customStage/v.d.ts

@@ -0,0 +1,2 @@
+import { CustomStageData } from "../../interfaces/CustomStageData";
+export declare const customStages: Map<string, CustomStageData>;

package/features/customStage/v.lua

@@ -0,0 +1,6 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local __TS__New = ____lualib.__TS__New
+local ____exports = {}
+____exports.customStages = __TS__New(Map)
+return ____exports

package/features/debugDisplay/v.d.ts

@@ -1,21 +1,3 @@
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
 declare const v: {
     run: {
         player: boolean;

package/features/deployJSONRoom.d.ts

@@ -24,7 +24,7 @@ import { JSONRoom } from "../interfaces/JSONRoom";
  * @param verbose Optional. If specified, will write entries to the "log.txt" file that describe
  *                what the function is doing. Default is false.
  */
-export declare function deployJSONRoom(jsonRoom: JSONRoom, seedOrRNG?: Seed | RNG, verbose?: boolean): void;
+export declare function deployJSONRoom(jsonRoom: JSONRoom | Readonly<JSONRoom>, seedOrRNG?: Seed | RNG, verbose?: boolean): void;
 /**
  * Helper function to deconstruct a vanilla room and set up a custom room in its place.
  * Specifically, this will clear the current room of all entities and grid entities, and then spawn
@@ -52,7 +52,7 @@ export declare function deployJSONRoom(jsonRoom: JSONRoom, seedOrRNG?: Seed | RN
  * @param verbose Optional. If specified, will write entries to the "log.txt" file that describe
  *                what the function is doing. Default is false.
  */
-export declare function deployRandomJSONRoom(jsonRooms: JSONRoom[], seedOrRNG?: Seed | RNG, verbose?: boolean): void;
+export declare function deployRandomJSONRoom(jsonRooms: JSONRoom[] | readonly JSONRoom[], seedOrRNG?: Seed | RNG, verbose?: boolean): void;
 /**
  * Helper function to remove all naturally spawning entities and grid entities from a room. Notably,
  * this will not remove players (1), tears (2), familiars (3), lasers (7), knives (8), projectiles

package/features/ponyDetection.lua

@@ -38,7 +38,7 @@ function postPEffectUpdateReordered(self, player)
         setDeletePlayer(nil, v.run.playersIsPonyActive, player)
     end
 end
-local FEATURE_NAME = "ponyDetector"
+local FEATURE_NAME = "ponyDetection"
 FLAGS_WHEN_PONY_IS_ACTIVE = {EntityFlag.NO_KNOCKBACK, EntityFlag.NO_PHYSICS_KNOCKBACK, EntityFlag.NO_DAMAGE_BLINK}
 v = {run = {playersIsPonyActive = __TS__New(Set)}}
 ---

package/features/runInNFrames.lua

@@ -1,7 +1,7 @@
 local ____lualib = require("lualib_bundle")
-local __TS__ArrayForEach = ____lualib.__TS__ArrayForEach
+local __TS__ArrayFilter = ____lualib.__TS__ArrayFilter
 local ____exports = {}
-local postUpdate, postRender, checkExecuteQueuedFunctions, checkExecuteIntervalFunctions, getFunctionsThatShouldFireOnThisFrame, v
+local postUpdate, postRender, checkExecuteQueuedFunctions, checkExecuteIntervalFunctions, v
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local ModCallback = ____isaac_2Dtypescript_2Ddefinitions.ModCallback
 local ____cachedClasses = require("cachedClasses")
@@ -9,7 +9,7 @@ local game = ____cachedClasses.game
 local ____featuresInitialized = require("featuresInitialized")
 local errorIfFeaturesNotInitialized = ____featuresInitialized.errorIfFeaturesNotInitialized
 local ____array = require("functions.array")
-local arrayRemoveIndexInPlace = ____array.arrayRemoveIndexInPlace
+local arrayRemoveInPlace = ____array.arrayRemoveInPlace
 local ____exports = require("features.saveDataManager.exports")
 local saveDataManager = ____exports.saveDataManager
 function postUpdate(self)
@@ -23,43 +23,40 @@ function postRender(self)
     checkExecuteIntervalFunctions(nil, renderFrameCount, v.run.intervalRenderFunctionTuples)
 end
 function checkExecuteQueuedFunctions(self, frameCount, functionTuples)
-    local firingFunctions = getFunctionsThatShouldFireOnThisFrame(nil, frameCount, functionTuples)
-    for ____, ____value in ipairs(firingFunctions) do
-        local i = ____value[1]
-        local func = ____value[2]
+    local firingFunctions = __TS__ArrayFilter(
+        functionTuples,
+        function(____, ____bindingPattern0)
+            local frameCountToFire
+            frameCountToFire = ____bindingPattern0[1]
+            return frameCount >= frameCountToFire
+        end
+    )
+    for ____, tuple in ipairs(firingFunctions) do
+        local _frameCountToFire, func = table.unpack(tuple)
         func(nil)
-        arrayRemoveIndexInPlace(nil, functionTuples, i)
+        arrayRemoveInPlace(nil, functionTuples, tuple)
     end
 end
 function checkExecuteIntervalFunctions(self, frameCount, functionTuples)
-    local firingFunctions = getFunctionsThatShouldFireOnThisFrame(nil, frameCount, functionTuples)
-    for ____, ____value in ipairs(firingFunctions) do
-        local i = ____value[1]
-        local func = ____value[2]
-        local numIntervalFrames = ____value[3]
+    local firingFunctions = __TS__ArrayFilter(
+        functionTuples,
+        function(____, ____bindingPattern0)
+            local frameCountToFire
+            frameCountToFire = ____bindingPattern0[1]
+            return frameCount >= frameCountToFire
+        end
+    )
+    for ____, tuple in ipairs(firingFunctions) do
+        local _frameCountToFire, func, numIntervalFrames = table.unpack(tuple)
         local returnValue = func(nil)
-        arrayRemoveIndexInPlace(nil, functionTuples, i)
-        if numIntervalFrames ~= nil and returnValue ~= false then
+        arrayRemoveInPlace(nil, functionTuples, tuple)
+        if returnValue then
             local nextFireFrame = frameCount + numIntervalFrames
-            local tuple = {nextFireFrame, func, numIntervalFrames}
-            functionTuples[#functionTuples + 1] = tuple
+            local newTuple = {nextFireFrame, func, numIntervalFrames}
+            functionTuples[#functionTuples + 1] = newTuple
         end
     end
 end
-function getFunctionsThatShouldFireOnThisFrame(self, frameCount, functionTuples)
-    local firingFunctionTuples = {}
-    __TS__ArrayForEach(
-        functionTuples,
-        function(____, functionTuple, i)
-            local frameCountToFire, func, numIntervalFrames = table.unpack(functionTuple)
-            if frameCount >= frameCountToFire then
-                local firingFunctionTuple = {i, func, numIntervalFrames}
-                firingFunctionTuples[#firingFunctionTuples + 1] = firingFunctionTuple
-            end
-        end
-    )
-    return firingFunctionTuples
-end
 local FEATURE_NAME = "runInNFrames"
 v = {run = {queuedGameFunctionTuples = {}, queuedRenderFunctionTuples = {}, intervalGameFunctionTuples = {}, intervalRenderFunctionTuples = {}}}
 ---

package/functions/ambush.lua

@@ -2,15 +2,14 @@ local ____lualib = require("lualib_bundle")
 local __TS__ArrayFilter = ____lualib.__TS__ArrayFilter
 local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
-local PickupVariant = ____isaac_2Dtypescript_2Ddefinitions.PickupVariant
+local SackSubType = ____isaac_2Dtypescript_2Ddefinitions.SackSubType
 local ____runInNFrames = require("features.runInNFrames")
 local runNextGameFrame = ____runInNFrames.runNextGameFrame
 local ____entity = require("functions.entity")
 local removeEntities = ____entity.removeEntities
-local ____entitySpecific = require("functions.entitySpecific")
-local spawnPickupWithSeed = ____entitySpecific.spawnPickupWithSeed
 local ____pickups = require("functions.pickups")
 local getCoins = ____pickups.getCoins
+local spawnSackWithSeed = ____pickups.spawnSackWithSeed
 --- Hard-coding this makes it easier to clean up the pickups afterwards.
 local SACK_SEED_THAT_SPAWNS_TWO_COINS = 6
 --- Helper function to start a Challenge Room or the Boss Rush.
@@ -19,13 +18,7 @@ local SACK_SEED_THAT_SPAWNS_TWO_COINS = 6
 -- and then removing the sack and the pickups that the sack dropped.
 function ____exports.startAmbush(self)
     local player = Isaac.GetPlayer()
-    local sack = spawnPickupWithSeed(
-        nil,
-        PickupVariant.SACK,
-        0,
-        player.Position,
-        SACK_SEED_THAT_SPAWNS_TWO_COINS
-    )
+    local sack = spawnSackWithSeed(nil, SackSubType.NULL, player.Position, SACK_SEED_THAT_SPAWNS_TWO_COINS)
     local sprite = sack:GetSprite()
     sprite:Stop()
     local sackPtr = EntityPtr(sack)

package/functions/array.d.ts

@@ -12,13 +12,48 @@ export declare function arrayEquals<T>(array1: T[] | readonly T[], array2: T[] |
  * array.
  *
  * This function is variadic, meaning that you can specify N arguments to remove N elements.
+ *
+ * If there is more than one matching element in the array, this function will only remove the first
+ * matching element. If you want to remove all of the elements, use the `arrayRemoveAll` function
+ * instead.
  */
 export declare function arrayRemove<T>(originalArray: T[] | readonly T[], ...elementsToRemove: T[]): T[];
+/**
+ * Shallow copies and removes the specified element(s) from the array. Returns the copied array. If
+ * the specified element(s) are not found in the array, it will simply return a shallow copy of the
+ * array.
+ *
+ * This function is variadic, meaning that you can specify N arguments to remove N elements.
+ *
+ * If there is more than one matching element in the array, this function will remove every matching
+ * element. If you want to only remove the first matching element, use the `arrayRemove` function
+ * instead.
+ */
+export declare function arrayRemoveAll<T>(originalArray: T[] | readonly T[], ...elementsToRemove: T[]): T[];
+/**
+ * Removes all of the specified element(s) from the array. If the specified element(s) are not found
+ * in the array, this function will do nothing.
+ *
+ * This function is variadic, meaning that you can specify N arguments to remove N elements.
+ *
+ * If there is more than one matching element in the array, this function will remove every matching
+ * element. If you want to only remove the first matching element, use the `arrayRemoveInPlace`
+ * function instead.
+ *
+ * @returns True if one or more elements were removed, false otherwise.
+ */
+export declare function arrayRemoveAllInPlace<T>(array: T[], ...elementsToRemove: T[]): boolean;
 /**
  * Removes the specified element(s) from the array. If the specified element(s) are not found in the
- * array, this function will do nothing. Returns true if one or more elements were removed.
+ * array, this function will do nothing.
  *
  * This function is variadic, meaning that you can specify N arguments to remove N elements.
+ *
+ * If there is more than one matching element in the array, this function will only remove the first
+ * matching element. If you want to remove all of the elements, use the `arrayRemoveAllInPlace`
+ * function instead.
+ *
+ * @returns True if one or more elements were removed, false otherwise.
  */
 export declare function arrayRemoveInPlace<T>(array: T[], ...elementsToRemove: T[]): boolean;
 /**
@@ -35,6 +70,8 @@ export declare function arrayRemoveIndex<T>(originalArray: T[] | readonly T[], .
  * removed.
  *
  * This function is variadic, meaning that you can specify N arguments to remove N elements.
+ *
+ * @returns Whether or not any array elements were removed.
  */
 export declare function arrayRemoveIndexInPlace<T>(array: T[], ...indexesToRemove: int[]): boolean;
 export declare function arrayToString<T>(array: T[] | readonly T[]): string;

package/functions/array.lua

@@ -1,9 +1,9 @@
 local ____lualib = require("lualib_bundle")
 local __TS__ArrayEvery = ____lualib.__TS__ArrayEvery
-local Set = ____lualib.Set
-local __TS__New = ____lualib.__TS__New
 local __TS__ArrayIndexOf = ____lualib.__TS__ArrayIndexOf
 local __TS__ArraySplice = ____lualib.__TS__ArraySplice
+local Set = ____lualib.Set
+local __TS__New = ____lualib.__TS__New
 local __TS__ArrayForEach = ____lualib.__TS__ArrayForEach
 local __TS__ArrayFilter = ____lualib.__TS__ArrayFilter
 local __TS__ArraySort = ____lualib.__TS__ArraySort
@@ -27,6 +27,77 @@ local isTable = ____types.isTable
 local ____utils = require("functions.utils")
 local erange = ____utils.erange
 local ____repeat = ____utils["repeat"]
+--- Removes all of the specified element(s) from the array. If the specified element(s) are not found
+-- in the array, this function will do nothing.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to remove N elements.
+-- 
+-- If there is more than one matching element in the array, this function will remove every matching
+-- element. If you want to only remove the first matching element, use the `arrayRemoveInPlace`
+-- function instead.
+-- 
+-- @returns True if one or more elements were removed, false otherwise.
+function ____exports.arrayRemoveAllInPlace(self, array, ...)
+    local elementsToRemove = {...}
+    local removedOneOrMoreElements = false
+    for ____, element in ipairs(elementsToRemove) do
+        local index
+        repeat
+            do
+                index = __TS__ArrayIndexOf(array, element)
+                if index > -1 then
+                    removedOneOrMoreElements = true
+                    __TS__ArraySplice(array, index, 1)
+                end
+            end
+        until not (index > -1)
+    end
+    return removedOneOrMoreElements
+end
+--- Removes the specified element(s) from the array. If the specified element(s) are not found in the
+-- array, this function will do nothing.
+-- 
+-- This function is variadic, meaning that you can specify N arguments to remove N elements.
+-- 
+-- If there is more than one matching element in the array, this function will only remove the first
+-- matching element. If you want to remove all of the elements, use the `arrayRemoveAllInPlace`
+-- function instead.
+-- 
+-- @returns True if one or more elements were removed, false otherwise.
+function ____exports.arrayRemoveInPlace(self, array, ...)
+    local elementsToRemove = {...}
+    local removedOneOrMoreElements = false
+    for ____, element in ipairs(elementsToRemove) do
+        local index = __TS__ArrayIndexOf(array, element)
+        if index > -1 then
+            removedOneOrMoreElements = true
+            __TS__ArraySplice(array, index, 1)
+        end
+    end
+    return removedOneOrMoreElements
+end
+--- Helper function to perform a shallow copy.
+-- 
+-- @param oldArray The array to copy.
+-- @param numElements Optional. If specified, will only copy the first N elements. By default, the
+-- entire array will be copied.
+function ____exports.copyArray(self, oldArray, numElements)
+    if numElements == nil then
+        numElements = #oldArray
+    end
+    local newArray = {}
+    do
+        local i = 0
+        while i < numElements do
+            local oldElement = oldArray[i + 1]
+            if oldElement ~= nil then
+                newArray[#newArray + 1] = oldElement
+            end
+            i = i + 1
+        end
+    end
+    return newArray
+end
 --- Helper function to get a random index from the provided array.
 -- 
 -- @param array The array to get the index from.
@@ -97,32 +168,28 @@ end
 -- array.
 -- 
 -- This function is variadic, meaning that you can specify N arguments to remove N elements.
+-- 
+-- If there is more than one matching element in the array, this function will only remove the first
+-- matching element. If you want to remove all of the elements, use the `arrayRemoveAll` function
+-- instead.
 function ____exports.arrayRemove(self, originalArray, ...)
-    local elementsToRemove = {...}
-    local elementsToRemoveSet = __TS__New(Set, elementsToRemove)
-    local array = {}
-    for ____, element in ipairs(originalArray) do
-        if not elementsToRemoveSet:has(element) then
-            array[#array + 1] = element
-        end
-    end
+    local array = ____exports.copyArray(nil, originalArray)
+    ____exports.arrayRemoveInPlace(nil, array, ...)
     return array
 end
---- Removes the specified element(s) from the array. If the specified element(s) are not found in the
--- array, this function will do nothing. Returns true if one or more elements were removed.
+--- Shallow copies and removes the specified element(s) from the array. Returns the copied array. If
+-- the specified element(s) are not found in the array, it will simply return a shallow copy of the
+-- array.
 -- 
 -- This function is variadic, meaning that you can specify N arguments to remove N elements.
-function ____exports.arrayRemoveInPlace(self, array, ...)
-    local elementsToRemove = {...}
-    local removedOneOrMoreElements = false
-    for ____, element in ipairs(elementsToRemove) do
-        local index = __TS__ArrayIndexOf(array, element)
-        if index > -1 then
-            removedOneOrMoreElements = true
-            __TS__ArraySplice(array, index, 1)
-        end
-    end
-    return removedOneOrMoreElements
+-- 
+-- If there is more than one matching element in the array, this function will remove every matching
+-- element. If you want to only remove the first matching element, use the `arrayRemove` function
+-- instead.
+function ____exports.arrayRemoveAll(self, originalArray, ...)
+    local array = ____exports.copyArray(nil, originalArray)
+    ____exports.arrayRemoveAllInPlace(nil, array, ...)
+    return array
 end
 --- Shallow copies and removes the elements at the specified indexes from the array. Returns the
 -- copied array. If the specified indexes are not found in the array, it will simply return a
@@ -148,6 +215,8 @@ end
 -- removed.
 -- 
 -- This function is variadic, meaning that you can specify N arguments to remove N elements.
+-- 
+-- @returns Whether or not any array elements were removed.
 function ____exports.arrayRemoveIndexInPlace(self, array, ...)
     local indexesToRemove = {...}
     local legalIndexes = __TS__ArrayFilter(
@@ -193,28 +262,6 @@ function ____exports.combineArrays(self, ...)
     end
     return elements
 end
---- Helper function to perform a shallow copy.
--- 
--- @param oldArray The array to copy.
--- @param numElements Optional. If specified, will only copy the first N elements. By default, the
--- entire array will be copied.
-function ____exports.copyArray(self, oldArray, numElements)
-    if numElements == nil then
-        numElements = #oldArray
-    end
-    local newArray = {}
-    do
-        local i = 0
-        while i < numElements do
-            local oldElement = oldArray[i + 1]
-            if oldElement ~= nil then
-                newArray[#newArray + 1] = oldElement
-            end
-            i = i + 1
-        end
-    end
-    return newArray
-end
 --- Helper function to remove all of the elements in an array in-place.
 function ____exports.emptyArray(self, array)
     __TS__ArraySplice(array, 0, #array)

package/functions/bitwise.d.ts

@@ -6,8 +6,16 @@
 export declare function arrayToBitFlags<T extends BitFlag | BitFlag128>(array: T[] | readonly T[]): BitFlags<T>;
 /** Helper function to convert an array of bits to the resulting decimal number. */
 export declare function convertBinaryToDecimal(bits: int[]): number;
-/** Helper function to convert a number to an array of bits. */
-export declare function convertDecimalToBinary(number: number): int[];
+/**
+ * Helper function to convert a number to an array of bits.
+ *
+ * @param number The number to convert.
+ * @param minLength Optional. Equal to the minimum amount of bits that should be returned. If the
+ *                  converted number of bits is below this number, 0's will be padded to the left
+ *                  side until the minimum length is met. Default is undefined (which will not cause
+ *                  any padding).
+ */
+export declare function convertDecimalToBinary(number: number, minLength?: int): int[];
 /**
  * Helper function to count the number of bits that are set to 1 in a binary representation of a
  * number.

package/functions/bitwise.lua

@@ -1,6 +1,8 @@
 local ____lualib = require("lualib_bundle")
 local __TS__ParseInt = ____lualib.__TS__ParseInt
+local __TS__NumberToString = ____lualib.__TS__NumberToString
 local __TS__Iterator = ____lualib.__TS__Iterator
+local __TS__ArrayUnshift = ____lualib.__TS__ArrayUnshift
 local ____exports = {}
 local ____flag = require("functions.flag")
 local addFlag = ____flag.addFlag
@@ -18,13 +20,26 @@ function ____exports.convertBinaryToDecimal(self, bits)
     return __TS__ParseInt(bitsString, 2)
 end
 --- Helper function to convert a number to an array of bits.
-function ____exports.convertDecimalToBinary(self, number)
+-- 
+-- @param number The number to convert.
+-- @param minLength Optional. Equal to the minimum amount of bits that should be returned. If the
+-- converted number of bits is below this number, 0's will be padded to the left
+-- side until the minimum length is met. Default is undefined (which will not cause
+-- any padding).
+function ____exports.convertDecimalToBinary(self, number, minLength)
     local bits = {}
-    local i = 0
-    while number > 0 do
-        bits[i + 1] = number % 2
-        number = math.floor(number / 2)
-        i = i + 1
+    local bitsString = __TS__NumberToString(number, 2)
+    for ____, bitString in __TS__Iterator(bitsString) do
+        local bit = tonumber(bitString)
+        if bit == nil then
+            error("Failed to convert the following number to binary: " .. tostring(number))
+        end
+        bits[#bits + 1] = bit
+    end
+    if minLength ~= nil then
+        while #bits < minLength do
+            __TS__ArrayUnshift(bits, 0)
+        end
     end
     return bits
 end

package/functions/color.d.ts

@@ -1,5 +1,5 @@
-/// <reference types="isaac-typescript-definitions" />
 /// <reference types="typescript-to-lua/language-extensions" />
+/// <reference types="isaac-typescript-definitions" />
 import { SerializationType } from "../enums/SerializationType";
 declare type SerializedColor = LuaTable<string, unknown> & {
     readonly __serializedColorBrand: symbol;

package/functions/gridEntity.d.ts

@@ -44,6 +44,13 @@ export declare function getCollidingEntitiesWithGridEntity(gridEntity: GridEntit
  * ```
  */
 export declare function getGridEntities(...gridEntityTypes: GridEntityType[]): GridEntity[];
+/**
+ * Helper function to get every grid entity in the current room except for certain specific types.
+ *
+ * This function is variadic, meaning that you can specify as many grid entity types as you want to
+ * exclude.
+ */
+export declare function getGridEntitiesExcept(...gridEntityTypes: GridEntityType[]): GridEntity[];
 /**
  * Helper function to get a map of every grid entity in the current room. The indexes of the map are
  * equal to the grid index. The values of the map are equal to the grid entities.
@@ -121,9 +128,10 @@ export declare function removeAllGridExcept(...gridEntityTypes: GridEntityType[]
  */
 export declare function removeAllMatchingGridEntities(...gridEntityType: GridEntityType[]): GridEntity[];
 /**
- * Helper function to remove a grid entity simply by providing the grid entity object.
+ * Helper function to remove a grid entity simply by providing the grid entity object. By default,
+ * this will also update the room.
  *
- * @param gridEntity The grid entity to remove.
+ * @param gridEntityOrGridIndex The grid entity or grid index to remove.
  * @param updateRoom Optional. Whether or not to update the room after the grid entity is removed.
  *                   Default is true. This is generally a good idea because if the room is not
  *                   updated, you will be unable to spawn another grid entity on the same tile until
@@ -131,7 +139,7 @@ export declare function removeAllMatchingGridEntities(...gridEntityType: GridEnt
  *                   to `Isaac.GetRoomEntities`, so set it to false if you need to invoke this
  *                   function multiple times.
  */
-export declare function removeGrid(gridEntity: GridEntity, updateRoom?: boolean): void;
+export declare function removeGrid(gridEntityOrGridIndex: GridEntity, updateRoom?: boolean): void;
 /**
  * Helper function to make a grid entity invisible. This is accomplished by setting its sprite to an
  * empty/missing PNG file.

package/functions/gridEntity.lua

@@ -59,21 +59,22 @@ function ____exports.getTopLeftWallGridIndex(self)
     local topLeftWallGridIndex = ROOM_SHAPE_TO_TOP_LEFT_WALL_GRID_INDEX_MAP:get(roomShape)
     return topLeftWallGridIndex == nil and DEFAULT_TOP_LEFT_WALL_GRID_INDEX or topLeftWallGridIndex
 end
---- Helper function to remove a grid entity simply by providing the grid entity object.
+--- Helper function to remove a grid entity simply by providing the grid entity object. By default,
+-- this will also update the room.
 -- 
--- @param gridEntity The grid entity to remove.
+-- @param gridEntityOrGridIndex The grid entity or grid index to remove.
 -- @param updateRoom Optional. Whether or not to update the room after the grid entity is removed.
 -- Default is true. This is generally a good idea because if the room is not
 -- updated, you will be unable to spawn another grid entity on the same tile until
 -- a frame has passed. However, doing this is expensive, since it involves a call
 -- to `Isaac.GetRoomEntities`, so set it to false if you need to invoke this
 -- function multiple times.
-function ____exports.removeGrid(self, gridEntity, updateRoom)
+function ____exports.removeGrid(self, gridEntityOrGridIndex, updateRoom)
     if updateRoom == nil then
         updateRoom = true
     end
     local room = game:GetRoom()
-    local gridIndex = gridEntity:GetGridIndex()
+    local gridIndex = gridEntityOrGridIndex:GetGridIndex()
     room:RemoveGridEntity(gridIndex, 0, false)
     if updateRoom then
         roomUpdateSafe(nil)
@@ -201,6 +202,25 @@ function ____exports.getGridEntities(self, ...)
         end
     )
 end
+--- Helper function to get every grid entity in the current room except for certain specific types.
+-- 
+-- This function is variadic, meaning that you can specify as many grid entity types as you want to
+-- exclude.
+function ____exports.getGridEntitiesExcept(self, ...)
+    local gridEntityTypes = {...}
+    local gridEntities = getAllGridEntities(nil)
+    if #gridEntityTypes == 0 then
+        return gridEntities
+    end
+    local gridEntityTypesSet = __TS__New(Set, gridEntityTypes)
+    return __TS__ArrayFilter(
+        gridEntities,
+        function(____, gridEntity)
+            local gridEntityType = gridEntity:GetType()
+            return not gridEntityTypesSet:has(gridEntityType)
+        end
+    )
+end
 --- Helper function to get a map of every grid entity in the current room. The indexes of the map are
 -- equal to the grid index. The values of the map are equal to the grid entities.
 -- 

package/functions/jsonRoom.d.ts

@@ -2,8 +2,8 @@
 /// <reference types="isaac-typescript-definitions" />
 /// <reference types="isaac-typescript-definitions" />
 import { JSONRoom } from "../interfaces/JSONRoom";
-export declare function getJSONRoomOfVariant(jsonRooms: JSONRoom[], variant: int): JSONRoom | undefined;
-export declare function getJSONRoomsOfSubType(jsonRooms: JSONRoom[], subType: int): JSONRoom[];
+export declare function getJSONRoomOfVariant(jsonRooms: JSONRoom[] | readonly JSONRoom[], variant: int): JSONRoom | undefined;
+export declare function getJSONRoomsOfSubType(jsonRooms: JSONRoom[] | readonly JSONRoom[], subType: int): JSONRoom[];
 /**
  * Helper function to get a random JSON room from an array of JSON rooms.
  *
@@ -11,4 +11,4 @@ export declare function getJSONRoomsOfSubType(jsonRooms: JSONRoom[], subType: in
  * properly account for each room weight using the algorithm from:
  * https://stackoverflow.com/questions/1761626/weighted-random-numbers
  */
-export declare function getRandomJSONRoom(jsonRooms: JSONRoom[], seedOrRNG?: Seed | RNG, verbose?: boolean): JSONRoom;
+export declare function getRandomJSONRoom(jsonRooms: JSONRoom[] | readonly JSONRoom[], seedOrRNG?: Seed | RNG, verbose?: boolean): JSONRoom;

package/functions/kColor.d.ts

@@ -1,5 +1,5 @@
-/// <reference types="isaac-typescript-definitions" />
 /// <reference types="typescript-to-lua/language-extensions" />
+/// <reference types="isaac-typescript-definitions" />
 import { SerializationType } from "../enums/SerializationType";
 declare type SerializedKColor = LuaTable<string, unknown> & {
     readonly __serializedKColorBrand: symbol;

package/functions/rng.d.ts

@@ -1,6 +1,6 @@
+/// <reference types="typescript-to-lua/language-extensions" />
 /// <reference types="isaac-typescript-definitions" />
 /// <reference types="isaac-typescript-definitions" />
-/// <reference types="typescript-to-lua/language-extensions" />
 import { SerializationType } from "../enums/SerializationType";
 declare type SerializedRNG = LuaTable<string, unknown> & {
     readonly __serializedRNGBrand: symbol;

package/index.d.ts

@@ -12,6 +12,7 @@ export * from "./enums/SerializationType";
 export { ConversionHeartSubType, registerCharacterHealthConversion, } from "./features/characterHealthConversion";
 export { registerCharacterStats } from "./features/characterStats";
 export { getCollectibleItemPoolType } from "./features/collectibleItemPoolType";
+export { removeCustomGrid, spawnCustomGrid } from "./features/customGridEntity";
 export * from "./features/debugDisplay/exports";
 export { deployJSONRoom, deployRandomJSONRoom, emptyRoom, } from "./features/deployJSONRoom";
 export { disableAllSound, enableAllSound } from "./features/disableAllSound";

package/index.lua

@@ -100,6 +100,13 @@ do
     local getCollectibleItemPoolType = ____collectibleItemPoolType.getCollectibleItemPoolType
     ____exports.getCollectibleItemPoolType = getCollectibleItemPoolType
 end
+do
+    local ____customGridEntity = require("features.customGridEntity")
+    local removeCustomGrid = ____customGridEntity.removeCustomGrid
+    local spawnCustomGrid = ____customGridEntity.spawnCustomGrid
+    ____exports.removeCustomGrid = removeCustomGrid
+    ____exports.spawnCustomGrid = spawnCustomGrid
+end
 do
     local ____export = require("features.debugDisplay.exports")
     for ____exportKey, ____exportValue in pairs(____export) do

package/initFeatures.lua

@@ -5,6 +5,8 @@ local ____characterStats = require("features.characterStats")
 local characterStatsInit = ____characterStats.characterStatsInit
 local ____collectibleItemPoolType = require("features.collectibleItemPoolType")
 local collectibleItemPoolTypeInit = ____collectibleItemPoolType.collectibleItemPoolTypeInit
+local ____customGridEntity = require("features.customGridEntity")
+local customGridEntityInit = ____customGridEntity.customGridEntityInit
 local ____deployJSONRoom = require("features.deployJSONRoom")
 local deployJSONRoomInit = ____deployJSONRoom.deployJSONRoomInit
 local ____disableAllSound = require("features.disableAllSound")
@@ -42,6 +44,7 @@ function ____exports.initFeaturesMajor(self, mod)
     runInNFramesInit(nil, mod)
     characterStatsInit(nil, mod)
     characterHealthConversionInit(nil, mod)
+    customGridEntityInit(nil, mod)
 end
 function ____exports.initFeaturesMinor(self, mod)
     disableAllSoundInit(nil, mod)

package/interfaces/CustomGridEntityData.d.ts

@@ -0,0 +1,9 @@
+import { GridCollisionClass, GridEntityType } from "isaac-typescript-definitions";
+export interface CustomGridEntityData {
+    gridEntityTypeCustom: GridEntityType;
+    roomListIndex: int;
+    gridIndex: int;
+    anm2: string;
+    defaultAnimation: string;
+    gridCollisionClass: GridCollisionClass;
+}

package/interfaces/CustomGridEntityData.lua

@@ -0,0 +1,2 @@
+local ____exports = {}
+return ____exports

package/interfaces/CustomStageData.d.ts

@@ -0,0 +1,5 @@
+import { LevelStage } from "isaac-typescript-definitions";
+export interface CustomStageData {
+    name: string;
+    baseStage: LevelStage;
+}

package/interfaces/CustomStageData.lua

@@ -0,0 +1,2 @@
+local ____exports = {}
+return ____exports

package/objects/colors.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="isaac-typescript-definitions" />
 /**
  * A collection of common colors that can be reused.
  *

package/package.json

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