isaacscript-common 30.12.11 → 31.0.1

package/dist/index.rollup.d.ts

@@ -5696,10 +5696,13 @@ export declare function getNewGlobals(): ReadonlyArray<[AnyNotNil, unknown]>;
  *
  * @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
  *                  `RNG.Next` method will be called. Default is `getRandomSeed()`.
+ * @param ensureDeadEnd Optional. Whether to pick a valid dead end attached to a normal room. If
+ *                      false, the function will randomly pick from any valid location that would
+ *                      have a red door.
  * @returns Either a tuple of adjacent room grid index, `DoorSlot`, and new room grid index, or
  *          undefined.
  */
-export declare function getNewRoomCandidate(seedOrRNG?: Seed | RNG): {
+export declare function getNewRoomCandidate(seedOrRNG?: Seed | RNG, ensureDeadEnd?: boolean): {
     readonly adjacentRoomGridIndex: int;
     readonly doorSlot: DoorSlot;
     readonly newRoomGridIndex: int;
@@ -5707,25 +5710,29 @@ export declare function getNewRoomCandidate(seedOrRNG?: Seed | RNG): {
 
 /**
  * Helper function to iterate through the possible doors for a room and see if any of them would be
- * a valid spot to insert a brand new room on the floor. (Any potential new rooms cannot be
- * connected to any other existing rooms on the floor.)
+ * a valid spot to insert a brand new room on the floor.
  *
  * @param roomGridIndex Optional. Default is the current room index.
+ * @param ensureDeadEnd Optional. Whether to only include doors that lead to a valid dead end
+ *                      attached to a normal room. If false, the function will include all doors
+ *                      that would have a red door.
  * @returns A array of tuples of `DoorSlot` and room grid index.
  */
-export declare function getNewRoomCandidatesBesideRoom(roomGridIndex?: int): ReadonlyArray<{
+export declare function getNewRoomCandidatesBesideRoom(roomGridIndex?: int, ensureDeadEnd?: boolean): ReadonlyArray<{
     readonly doorSlot: DoorSlot;
     readonly roomGridIndex: int;
 }>;
 
 /**
- * Helper function to search through all of the rooms on the floor for a spot to insert a brand new
- * room.
+ * Helper function to get all of the spots on the floor to insert a brand new room.
  *
+ * @param ensureDeadEnd Optional. Whether to only include spots that are a valid dead end attached
+ *                      to a normal room. If false, the function will include all valid spots that
+ *                      have a red door.
  * @returns A array of tuples containing the adjacent room grid index, the `DoorSlot`, and the new
  *          room grid index.
  */
-export declare function getNewRoomCandidatesForLevel(): ReadonlyArray<{
+export declare function getNewRoomCandidatesForLevel(ensureDeadEnd?: boolean): ReadonlyArray<{
     readonly adjacentRoomGridIndex: int;
     readonly doorSlot: DoorSlot;
     readonly newRoomGridIndex: int;
@@ -6497,11 +6504,8 @@ export declare function getRoomAdjacentGridIndexes(roomGridIndex?: int): Readonl
  */
 export declare function getRoomAllowedDoors(roomGridIndex?: int): Set<DoorSlot>;
 
-/**
- * Helper function to get the room data for the provided room.
- *
- * @param roomGridIndex Optional. Default is the current room index.
- */
+export declare function getRoomData(): RoomConfig;
+
 export declare function getRoomData(roomGridIndex?: int): RoomConfig | undefined;
 
 /**
@@ -7535,7 +7539,7 @@ export declare function includes<T>(array: T[], element: T): boolean;
 /**
  * Helper function for determining whether the current room is a crawl space. Use this function over
  * comparing to `RoomType.DUNGEON` or `GridRoom.DUNGEON_IDX` since there is a special case of the
- * player being in a boss fight that take place in a dungeon.
+ * player being in a boss fight that takes place in a dungeon.
  */
 export declare function inCrawlSpace(): boolean;
 
@@ -7567,9 +7571,14 @@ export declare function inDimension(dimension: Dimension): boolean;
  * This is performed by checking for the string "Double Trouble" inside of the room name. The
  * vanilla game uses this convention for every Double Trouble Boss Room. Note that this method might
  * fail for mods that add extra Double Trouble rooms but do not follow the convention.
+ *
+ * Internally, the game is coded to detect Double Trouble Boss Rooms by checking for the variant
+ * range of 3700 through 3850. We intentionally do not use this method since it may not work as well
+ * with modded rooms.
  */
 export declare function inDoubleTrouble(): boolean;
 
+/** Helper function to determine if the current room index is equal to `GridRoom.GENESIS`. */
 export declare function inGenesisRoom(): boolean;
 
 /**
@@ -7693,6 +7702,11 @@ export declare function inStartingRoom(): boolean;
  */
 export declare function iRange(start: int, end?: int, increment?: number): int[];
 
+/**
+ * Helper function to determine if the provided room is equal to `RoomShape.1x2` or `RoomShape.2x1`.
+ */
+export declare function is2x1Room(roomData: RoomConfig): boolean;
+
 /**
  * Helper function to check if an instantiated Isaac API class is equal to another one of the same
  * type. You must provide the list of keys to check for.
@@ -7805,6 +7819,8 @@ export declare function isAllRoomsClear(onlyCheckRoomTypes?: RoomType[], include
 
 export declare function isAngelRoomDoor(door: GridEntityDoor): boolean;
 
+export declare function isAngelShop(roomData: RoomConfig): boolean;
+
 /**
  * Since Lua uses tables for every non-primitive data structure, it is non-trivial to determine if a
  * particular table is being used as an array. `isArray` returns true if:
@@ -7831,6 +7847,8 @@ export declare function isArrayInArray<T>(arrayToMatch: T[] | readonly T[], pare
 /** For `PickupVariant.LIL_BATTERY` (90). */
 export declare function isBattery(pickup: EntityPickup): pickup is EntityPickupBattery;
 
+export declare function isBeastRoom(roomData: RoomConfig): boolean;
+
 /**
  * Helper function for detecting when a player is Bethany or Tainted Bethany. This is useful if you
  * need to adjust UI elements to account for Bethany's soul charges or Tainted Bethany's blood
@@ -7859,6 +7877,12 @@ export declare function isBombPickup(pickup: EntityPickup): pickup is EntityPick
 
 export declare function isBoolean(variable: unknown): variable is boolean;
 
+/**
+ * Helper function to check if the provided room is a boss room for a particular boss. This will
+ * only work for bosses that have dedicated boss rooms in the "00.special rooms.stb" file.
+ */
+export declare function isBossRoomOf(roomData: RoomConfig, bossID: BossID): boolean;
+
 /**
  * Returns true for cards that have the following card type:
  * - CardType.TAROT
@@ -8050,6 +8074,13 @@ export declare function isColor(object: unknown): object is Color;
  */
 export declare function isCopyableIsaacAPIClass(object: unknown): object is CopyableIsaacAPIClass;
 
+/**
+ * Helper function for determining whether the provided room is a crawl space. Use this function
+ * over comparing to `RoomType.DUNGEON` or `GridRoom.DUNGEON_IDX` since there is a special case of
+ * the player being in a boss fight that takes place in a dungeon.
+ */
+export declare function isCrawlSpace(roomData: RoomConfig): boolean;
+
 /**
  * Helper function to distinguish between a normal Daddy Long Legs / Triachnid and the child entity
  * that is spawned when the boss does the multi-stomp attack.
@@ -8086,6 +8117,11 @@ export declare function isDamageToPlayerFatal(player: EntityPlayer, amount: int,
  */
 export declare function isDeadEnd(roomGridIndex?: int): boolean;
 
+/**
+ * Helper function to detect if the provided room is one of the rooms in the Death Certificate area.
+ */
+export declare function isDeathCertificateArea(roomData: RoomConfig): boolean;
+
 /**
  * Helper function to determine if a given object is a TypeScriptToLua `Map`.
  *
@@ -8096,6 +8132,14 @@ export declare function isDefaultMap(object: unknown): object is DefaultMap<AnyN
 
 export declare function isDevilRoomDoor(door: GridEntityDoor): boolean;
 
+/**
+ * Helper function to detect if the provided room is a Treasure Room created when entering with a
+ * Devil's Crown trinket.
+ *
+ * Under the hood, this checks for `RoomDescriptorFlag.DEVIL_TREASURE`.
+ */
+export declare function isDevilsCrownTreasureRoom(roomDescriptor: RoomDescriptor): boolean;
+
 /** Helper function to detect if a variable is of type `GridEntityDoor`. */
 export declare function isDoor(variable: unknown): variable is GridEntityDoor;
 
@@ -8136,6 +8180,19 @@ export declare function isDoorToMines(door: GridEntityDoor): boolean;
  */
 export declare function isDoorToMomsHeart(door: GridEntityDoor): boolean;
 
+/**
+ * Helper function to detect if the provided room is a Double Trouble Boss Room.
+ *
+ * This is performed by checking for the string "Double Trouble" inside of the room name. The
+ * vanilla game uses this convention for every Double Trouble Boss Room. Note that this method might
+ * fail for mods that add extra Double Trouble rooms but do not follow the convention.
+ *
+ * Internally, the game is coded to detect Double Trouble Boss Rooms by checking for the variant
+ * range of 3700 through 3850. We intentionally do not use this method since it may not work as well
+ * with modded rooms.
+ */
+export declare function isDoubleTrouble(roomData: RoomConfig): boolean;
+
 /**
  * Helper function to detect the custom death state of a Dump. When Dumps die, they go to
  * `NPCState.SPECIAL`, spit out their head, and then slowly fade away while shooting a burst of
@@ -8222,6 +8279,11 @@ export declare function isFoundSoul(player: EntityPlayer): boolean;
 
 export declare function isFunction(variable: unknown): variable is Function;
 
+/**
+ * Helper function to determine if the index of the provided room is equal to `GridRoom.GENESIS`.
+ */
+export declare function isGenesisRoom(roomDescriptor: RoomDescriptor): boolean;
+
 /**
  * Returns whether or not the given collectible is a "glitched" item. All items are replaced by
  * glitched items once a player has TMTRAINER. However, glitched items can also "naturally" appear
@@ -8268,6 +8330,14 @@ export declare function isHiddenCollectible(collectibleOrCollectibleType: Entity
 
 export declare function isHiddenSecretRoomDoor(door: GridEntityDoor): boolean;
 
+/**
+ * Helper function to check if the provided room is either the left Home closet (behind the red
+ * door) or the right Home closet (with one random pickup).
+ *
+ * Home closets have a unique shape that is different from any other room in the game.
+ */
+export declare function isHomeCloset(roomData: RoomConfig): boolean;
+
 export declare function isHorsePill(pillColor: PillColor): boolean;
 
 /**
@@ -8314,7 +8384,10 @@ export declare function isLaser(variable: unknown): variable is EntityLaser;
 /** Helper function for detecting when a player is The Lost or Tainted Lost. */
 export declare function isLost(player: EntityPlayer): boolean;
 
-export declare function isLRoom(roomShape: RoomShape): boolean;
+/** Helper function to determine if the provided room is one of the four L room shapes. */
+export declare function isLRoom(roomData: RoomConfig): boolean;
+
+export declare function isLRoomShape(roomShape: RoomShape): boolean;
 
 /**
  * Players can boot the game with an launch option called "--luadebug", which will enable additional
@@ -8333,6 +8406,29 @@ export declare function isLRoom(roomShape: RoomShape): boolean;
  */
 export declare function isLuaDebugEnabled(): boolean;
 
+/**
+ * Helper function to determine if the index of the provided room is equal to `GridRoom.MEGA_SATAN`.
+ */
+export declare function isMegaSatanRoom(roomDescriptor: RoomDescriptor): boolean;
+
+/**
+ * Helper function to determine if the provided room is part of the Repentance "escape sequence" in
+ * the Mines/Ashpit.
+ */
+export declare function isMineShaft(roomData: RoomConfig): boolean;
+
+/**
+ * Helper function to check if the provided room is a miniboss room for a particular miniboss. This
+ * will only work for mini-bosses that have dedicated boss rooms in the "00.special rooms.stb" file.
+ */
+export declare function isMinibossRoomOf(roomData: RoomConfig, minibossID: MinibossID): boolean;
+
+/**
+ * Helper function to check if the provided room is a "mirror room" in Downpour or Dross. (These
+ * rooms are marked with a specific sub-type.)
+ */
+export declare function isMirrorRoom(roomData: RoomConfig): boolean;
+
 /** Returns true for any card or rune added by a mod. */
 export declare function isModdedCardType(cardType: CardType): boolean;
 
@@ -8527,6 +8623,13 @@ export declare function isRoomInsideGrid(roomGridIndex?: int): boolean;
  */
 export declare function isRoomShapeDoubleCharge(roomShape: RoomShape): boolean;
 
+/**
+ * Helper function to check if the provided room matches one of the given room types.
+ *
+ * This function is variadic, which means you can pass as many room types as you want to match for.
+ */
+export declare function isRoomType(roomData: RoomConfig, ...roomTypes: RoomType[]): boolean;
+
 /**
  * Helper function to check if a given room is visible on the minimap.
  *
@@ -8542,6 +8645,12 @@ export declare function isRune(cardType: CardType): boolean;
 /** For `PickupVariant.SACK` (69). */
 export declare function isSack(pickup: EntityPickup): pickup is EntityPickupSack;
 
+/**
+ * Helper function for checking if the provided room is a secret exit that leads to a Repentance
+ * floor.
+ */
+export declare function isSecretExit(roomDescriptor: RoomDescriptor): boolean;
+
 /**
  * This refers to the hole in the wall that appears after bombing the entrance to a secret room.
  * Note that the door still exists before it has been bombed open. It has a sprite filename of
@@ -8558,6 +8667,16 @@ export declare function isSecretRoomDoor(door: GridEntityDoor): boolean;
  */
 export declare function isSecretRoomType(roomType: RoomType): boolean;
 
+/**
+ * Helper function for checking if the provided room is a secret shop (from the Member Card
+ * collectible).
+ *
+ * Secret shops are simply copies of normal shops, but with the backdrop of a secret room. In other
+ * words, they will have the same room type, room variant, and room sub-type of a normal shop. Thus,
+ * the only way to detect them is by using the grid index.
+ */
+export declare function isSecretShop(roomDescriptor: RoomDescriptor): boolean;
+
 /**
  * Helper function to determine whether damage to a player in the `ENTITY_TAKE_DMG` callback was
  * self-inflicted. For example, damage from a Curse Room door, a Razor, or a Blood Donation Machine
@@ -13121,23 +13240,25 @@ export declare function newReadonlyVector(x: float, y: float): Readonly<Vector>;
 export declare function newRNG(seed?: Seed): RNG;
 
 /**
- * Helper function to generate a new room on the floor at a valid dead end attached to a normal
- * room.
+ * Helper function to generate a new room on the floor.
  *
  * Under the hood, this function uses the `Level.MakeRedRoomDoor` method to create the room.
  *
- * The newly created room will have data corresponding to the game's randomly generated red room. If
- * you want to modify this, use the `setRoomData` helper function.
- *
  * @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
  *                  `RNG.Next` method will be called. Default is `Level.GetDungeonPlacementSeed`.
  *                  Note that the RNG is only used to select the random location to put the room on
  *                  the floor; it does not influence the randomly chosen room contents. (That is
  *                  performed by the game and can not be manipulated prior to its generation.)
+ * @param ensureDeadEnd Optional. Whether to place the room at a valid dead end attached to a normal
+ *                      room. If false, it will randomly appear at any valid location that would
+ *                      have a red door.
+ * @param customRoomData Optional. By default, the newly created room will have data corresponding
+ *                       to the game's randomly generated red room. If you provide this function
+ *                       with room data, it will be used to override the vanilla data.
  * @returns The room grid index of the new room or undefined if the floor had no valid dead ends to
  *          place a room.
  */
-export declare function newRoom(seedOrRNG?: Seed | RNG): int | undefined;
+export declare function newRoom(seedOrRNG?: Seed | RNG, ensureDeadEnd?: boolean, customRoomData?: RoomConfig): int | undefined;
 
 /**
  * Helper function to load a new sprite and play its default animation.