isaacscript-common 5.0.2 → 5.1.1

package/functions/array.d.ts

@@ -63,6 +63,7 @@ export declare function emptyArray<T>(array: T[]): void;
  * For example, if this function is provided an array containing 1, 2, and 3, then it will return an
  * array containing the following arrays:
  *
+ * - [] (if `includeEmptyArray` is set to true)
  * - [1]
  * - [2]
  * - [3]
@@ -117,8 +118,10 @@ export declare function getRandomArrayElementAndRemove<T>(array: T[], seedOrRNG?
  * @param array The array to get the index from.
  * @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 exceptions Optional. An array of indexes that will be skipped over when getting the random
+ *                   index. Default is an empty array.
  */
-export declare function getRandomArrayIndex<T>(array: T[] | readonly T[], seedOrRNG?: Seed | RNG): int;
+export declare function getRandomArrayIndex<T>(array: T[] | readonly T[], seedOrRNG?: Seed | RNG, exceptions?: int[] | readonly int[]): int;
 /**
  * Initializes an array with all elements containing the specified default value.
  *

package/functions/array.lua

@@ -32,14 +32,25 @@ local ____repeat = ____utils["repeat"]
 -- @param array The array to get the index from.
 -- @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()`.
-function ____exports.getRandomArrayIndex(self, array, seedOrRNG)
+-- @param exceptions Optional. An array of indexes that will be skipped over when getting the random
+-- index. Default is an empty array.
+function ____exports.getRandomArrayIndex(self, array, seedOrRNG, exceptions)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
     end
+    if exceptions == nil then
+        exceptions = {}
+    end
     if #array == 0 then
         error("Failed to get a random array index since the provided array is empty.")
     end
-    return getRandomInt(nil, 0, #array - 1, seedOrRNG)
+    return getRandomInt(
+        nil,
+        0,
+        #array - 1,
+        seedOrRNG,
+        exceptions
+    )
 end
 --- Shuffles the provided array in-place using the Fisher-Yates algorithm.
 -- 
@@ -214,6 +225,7 @@ end
 -- For example, if this function is provided an array containing 1, 2, and 3, then it will return an
 -- array containing the following arrays:
 -- 
+-- - [] (if `includeEmptyArray` is set to true)
 -- - [1]
 -- - [2]
 -- - [3]

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,5 +1,6 @@
 local ____lualib = require("lualib_bundle")
 local __TS__ParseInt = ____lualib.__TS__ParseInt
+local __TS__ArrayUnshift = ____lualib.__TS__ArrayUnshift
 local __TS__Iterator = ____lualib.__TS__Iterator
 local ____exports = {}
 local ____flag = require("functions.flag")
@@ -18,7 +19,13 @@ 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
@@ -26,6 +33,11 @@ function ____exports.convertDecimalToBinary(self, number)
         number = math.floor(number / 2)
         i = i + 1
     end
+    if minLength ~= nil then
+        while #bits < minLength do
+            __TS__ArrayUnshift(bits, 0)
+        end
+    end
     return bits
 end
 --- Helper function to count the number of bits that are set to 1 in a binary representation of a

package/functions/doors.d.ts

@@ -53,6 +53,11 @@ export declare function getDoors(...roomTypes: RoomType[]): GridEntityDoor[];
 export declare function getDoorsToRoomIndex(...roomGridIndex: int[]): GridEntityDoor[];
 export declare function getOppositeDoorSlot(doorSlot: DoorSlot): DoorSlot | undefined;
 export declare function getRepentanceDoor(): GridEntityDoor | undefined;
+/**
+ * Helper function to get the room grid coordinates for a specific room shape and door slot
+ * combination.
+ */
+export declare function getRoomShapeDoorSlotCoordinates(roomShape: RoomShape, doorSlot: DoorSlot): readonly [x: int, y: int] | undefined;
 /** Helper function to find unused door slots in the room that can be used to make custom doors. */
 export declare function getUnusedDoorSlots(): DoorSlot[];
 export declare function isAngelRoomDoor(door: GridEntityDoor): boolean;

package/functions/doors.lua

@@ -24,6 +24,8 @@ local ____doorSlotToDoorSlotFlag = require("objects.doorSlotToDoorSlotFlag")
 local DOOR_SLOT_TO_DOOR_SLOT_FLAG = ____doorSlotToDoorSlotFlag.DOOR_SLOT_TO_DOOR_SLOT_FLAG
 local ____oppositeDoorSlots = require("objects.oppositeDoorSlots")
 local OPPOSITE_DOOR_SLOTS = ____oppositeDoorSlots.OPPOSITE_DOOR_SLOTS
+local ____roomShapeToDoorSlotCoordinates = require("objects.roomShapeToDoorSlotCoordinates")
+local ROOM_SHAPE_TO_DOOR_SLOT_COORDINATES = ____roomShapeToDoorSlotCoordinates.ROOM_SHAPE_TO_DOOR_SLOT_COORDINATES
 local ____roomShapeToDoorSlots = require("objects.roomShapeToDoorSlots")
 local ROOM_SHAPE_TO_DOOR_SLOTS = ____roomShapeToDoorSlots.ROOM_SHAPE_TO_DOOR_SLOTS
 local ____bitwise = require("functions.bitwise")
@@ -190,6 +192,12 @@ function ____exports.getRepentanceDoor(self)
         function(____, door) return ____exports.isRepentanceDoor(nil, door) end
     )
 end
+--- Helper function to get the room grid coordinates for a specific room shape and door slot
+-- combination.
+function ____exports.getRoomShapeDoorSlotCoordinates(self, roomShape, doorSlot)
+    local coordinatesMap = ROOM_SHAPE_TO_DOOR_SLOT_COORDINATES[roomShape]
+    return coordinatesMap:get(doorSlot)
+end
 --- Helper function to find unused door slots in the room that can be used to make custom doors.
 function ____exports.getUnusedDoorSlots(self)
     local room = game:GetRoom()

package/functions/random.d.ts

@@ -42,6 +42,7 @@ export declare function getRandomFloat(min: int, max: int, seedOrRNG?: Seed | RN
  *                  `RNG.Next` method will be called. Default is `getRandomSeed()`.
  * @param exceptions Optional. An array of elements that will be skipped over when getting the
  *                   random integer. For example, a min of 1, a max of 4, and an exceptions array of
- *                   `[2]` would cause the function to return either 1, 3, or 4.
+ *                   `[2]` would cause the function to return either 1, 3, or 4. Default is an empty
+ *                   array.
  */
 export declare function getRandomInt(min: int, max: int, seedOrRNG?: Seed | RNG, exceptions?: int[] | readonly int[]): int;

package/functions/random.lua

@@ -59,7 +59,8 @@ end
 -- `RNG.Next` method will be called. Default is `getRandomSeed()`.
 -- @param exceptions Optional. An array of elements that will be skipped over when getting the
 -- random integer. For example, a min of 1, a max of 4, and an exceptions array of
--- `[2]` would cause the function to return either 1, 3, or 4.
+-- `[2]` would cause the function to return either 1, 3, or 4. Default is an empty
+-- array.
 function ____exports.getRandomInt(self, min, max, seedOrRNG, exceptions)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -80,7 +81,7 @@ function ____exports.getRandomInt(self, min, max, seedOrRNG, exceptions)
         do
             randomInt = rng:RandomInt(max - min + 1) + min
         end
-    until exceptionsSet:has(randomInt)
+    until not exceptionsSet:has(randomInt)
     return randomInt
 end
 return ____exports

package/functions/set.d.ts

@@ -38,7 +38,7 @@ export declare function getRandomSetElement<T>(set: Set<T> | ReadonlySet<T>, see
  * For example, if this function is provided a set containing 1, 2, and 3, then it will return an
  * array containing the following sets:
  *
- * - []
+ * - [] (if `includeEmptyArray` is set to true)
  * - [1]
  * - [2]
  * - [3]

package/functions/set.lua

@@ -88,7 +88,7 @@ end
 -- For example, if this function is provided a set containing 1, 2, and 3, then it will return an
 -- array containing the following sets:
 -- 
--- - []
+-- - [] (if `includeEmptyArray` is set to true)
 -- - [1]
 -- - [2]
 -- - [3]

package/objects/roomShapeToDoorSlotCoordinates.d.ts

@@ -1,5 +1,9 @@
+import { DoorSlot, RoomShape } from "isaac-typescript-definitions";
 /**
  * The coordinates correspond to the x and y values that are present in a room's XML file.
  *
  * e.g. `<door exists="False" x="-1" y="3" />`
  */
+export declare const ROOM_SHAPE_TO_DOOR_SLOT_COORDINATES: {
+    readonly [key in RoomShape]: ReadonlyMap<DoorSlot, [x: int, y: int]>;
+};

package/objects/roomShapeToDoorSlotCoordinates.lua

@@ -0,0 +1,84 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local __TS__New = ____lualib.__TS__New
+local ____exports = {}
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local DoorSlot = ____isaac_2Dtypescript_2Ddefinitions.DoorSlot
+local RoomShape = ____isaac_2Dtypescript_2Ddefinitions.RoomShape
+--- The coordinates correspond to the x and y values that are present in a room's XML file.
+-- 
+-- e.g. `<door exists="False" x="-1" y="3" />`
+____exports.ROOM_SHAPE_TO_DOOR_SLOT_COORDINATES = {
+    [RoomShape.SHAPE_1x1] = __TS__New(Map, {{DoorSlot.LEFT_0, {-1, 3}}, {DoorSlot.UP_0, {6, -1}}, {DoorSlot.RIGHT_0, {13, 3}}, {DoorSlot.DOWN_0, {6, 7}}}),
+    [RoomShape.IH] = __TS__New(Map, {{DoorSlot.LEFT_0, {-1, 3}}, {DoorSlot.RIGHT_0, {13, 3}}}),
+    [RoomShape.IV] = __TS__New(Map, {{DoorSlot.UP_0, {6, -1}}, {DoorSlot.DOWN_0, {6, 7}}}),
+    [RoomShape.SHAPE_1x2] = __TS__New(Map, {
+        {DoorSlot.LEFT_0, {-1, 3}},
+        {DoorSlot.UP_0, {6, -1}},
+        {DoorSlot.RIGHT_0, {13, 3}},
+        {DoorSlot.DOWN_0, {6, 14}},
+        {DoorSlot.LEFT_1, {-1, 10}},
+        {DoorSlot.RIGHT_1, {13, 10}}
+    }),
+    [RoomShape.IIV] = __TS__New(Map, {{DoorSlot.UP_0, {6, -1}}, {DoorSlot.DOWN_0, {6, 14}}}),
+    [RoomShape.SHAPE_2x1] = __TS__New(Map, {
+        {DoorSlot.LEFT_0, {-1, 3}},
+        {DoorSlot.UP_0, {6, -1}},
+        {DoorSlot.RIGHT_0, {26, 3}},
+        {DoorSlot.DOWN_0, {6, 7}},
+        {DoorSlot.UP_1, {19, -1}},
+        {DoorSlot.DOWN_1, {19, 7}}
+    }),
+    [RoomShape.IIH] = __TS__New(Map, {{DoorSlot.LEFT_0, {-1, 3}}, {DoorSlot.RIGHT_0, {26, 3}}}),
+    [RoomShape.SHAPE_2x2] = __TS__New(Map, {
+        {DoorSlot.LEFT_0, {-1, 3}},
+        {DoorSlot.UP_0, {6, -1}},
+        {DoorSlot.RIGHT_0, {26, 3}},
+        {DoorSlot.DOWN_0, {6, 14}},
+        {DoorSlot.LEFT_1, {-1, 10}},
+        {DoorSlot.UP_1, {19, -1}},
+        {DoorSlot.RIGHT_1, {26, 10}},
+        {DoorSlot.DOWN_1, {19, 14}}
+    }),
+    [RoomShape.LTL] = __TS__New(Map, {
+        {DoorSlot.LEFT_0, {12, 3}},
+        {DoorSlot.UP_0, {6, 6}},
+        {DoorSlot.RIGHT_0, {26, 3}},
+        {DoorSlot.DOWN_0, {6, 14}},
+        {DoorSlot.LEFT_1, {-1, 10}},
+        {DoorSlot.UP_1, {19, -1}},
+        {DoorSlot.RIGHT_1, {26, 10}},
+        {DoorSlot.DOWN_1, {19, 14}}
+    }),
+    [RoomShape.LTR] = __TS__New(Map, {
+        {DoorSlot.LEFT_0, {-1, 3}},
+        {DoorSlot.UP_0, {6, -1}},
+        {DoorSlot.RIGHT_0, {13, 3}},
+        {DoorSlot.DOWN_0, {6, 14}},
+        {DoorSlot.LEFT_1, {-1, 10}},
+        {DoorSlot.UP_1, {19, 6}},
+        {DoorSlot.RIGHT_1, {26, 10}},
+        {DoorSlot.DOWN_1, {19, 14}}
+    }),
+    [RoomShape.LBL] = __TS__New(Map, {
+        {DoorSlot.LEFT_0, {-1, 3}},
+        {DoorSlot.UP_0, {6, -1}},
+        {DoorSlot.RIGHT_0, {26, 3}},
+        {DoorSlot.DOWN_0, {6, 7}},
+        {DoorSlot.LEFT_1, {12, 10}},
+        {DoorSlot.UP_1, {19, -1}},
+        {DoorSlot.RIGHT_1, {26, 10}},
+        {DoorSlot.DOWN_1, {19, 14}}
+    }),
+    [RoomShape.LBR] = __TS__New(Map, {
+        {DoorSlot.LEFT_0, {-1, 3}},
+        {DoorSlot.UP_0, {6, -1}},
+        {DoorSlot.RIGHT_0, {26, 3}},
+        {DoorSlot.DOWN_0, {6, 14}},
+        {DoorSlot.LEFT_1, {-1, 10}},
+        {DoorSlot.UP_1, {19, -1}},
+        {DoorSlot.RIGHT_1, {13, 10}},
+        {DoorSlot.DOWN_1, {19, 7}}
+    })
+}
+return ____exports

package/package.json

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