isaacscript-common 5.0.1 → 5.1.0

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/charge.lua

@@ -1,5 +1,5 @@
 local ____exports = {}
-local getClampedChargesToAdd, getNumChargesWithAAAModifier, shouldPlayFullRechargeSound
+local getClampedChargesToAdd, getChargesToAddWithAAAModifier, shouldPlayFullRechargeSound
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local ActiveSlot = ____isaac_2Dtypescript_2Ddefinitions.ActiveSlot
 local CollectibleType = ____isaac_2Dtypescript_2Ddefinitions.CollectibleType
@@ -40,7 +40,7 @@ function ____exports.addCharge(self, player, activeSlot, numCharges, playSoundEf
     end
     local hud = game:GetHUD()
     local chargesToAdd = getClampedChargesToAdd(nil, player, activeSlot, numCharges)
-    local modifiedChargesToAdd = getNumChargesWithAAAModifier(nil, player, activeSlot, chargesToAdd)
+    local modifiedChargesToAdd = getChargesToAddWithAAAModifier(nil, player, activeSlot, chargesToAdd)
     local totalCharge = ____exports.getTotalCharge(nil, player, activeSlot)
     local newCharge = totalCharge + modifiedChargesToAdd
     if newCharge == totalCharge then
@@ -105,7 +105,7 @@ function getClampedChargesToAdd(self, player, activeSlot, numCharges)
     end
     return numCharges
 end
-function getNumChargesWithAAAModifier(self, player, activeSlot, chargesToAdd)
+function getChargesToAddWithAAAModifier(self, player, activeSlot, chargesToAdd)
     local activeItem = player:GetActiveItem(activeSlot)
     local activeCharge = player:GetActiveCharge(activeSlot)
     local batteryCharge = player:GetBatteryCharge(activeSlot)
@@ -145,9 +145,9 @@ function shouldPlayFullRechargeSound(self, player, activeSlot)
     local hasBattery = player:HasCollectible(CollectibleType.BATTERY)
     local maxCharges = getCollectibleMaxCharges(nil, activeItem)
     if not hasBattery then
-        return not player:NeedsCharge(activeSlot)
+        return activeCharge == maxCharges
     end
-    return not player:NeedsCharge(activeSlot) or activeCharge == maxCharges and batteryCharge == 0
+    return batteryCharge == maxCharges or activeCharge == maxCharges and batteryCharge == 0
 end
 --- Helper function to add a charge to a player's active item(s), emulating what happens when a room
 -- is cleared.

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,4 +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]: ReadonlySet<DoorSlot>;
+    readonly [key in RoomShape]: ReadonlyMap<DoorSlot, [x: int, y: int]>;
 };

package/objects/roomShapeToDoorSlotCoordinates.lua

@@ -1,46 +1,84 @@
 local ____lualib = require("lualib_bundle")
-local Set = ____lualib.Set
+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
-local ALL_DOOR_SLOTS_SET = __TS__New(Set, {
-    DoorSlot.LEFT_0,
-    DoorSlot.UP_0,
-    DoorSlot.RIGHT_0,
-    DoorSlot.DOWN_0,
-    DoorSlot.LEFT_1,
-    DoorSlot.UP_1,
-    DoorSlot.RIGHT_1,
-    DoorSlot.DOWN_1
-})
+--- 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(Set, {DoorSlot.LEFT_0, DoorSlot.UP_0, DoorSlot.RIGHT_0, DoorSlot.DOWN_0}),
-    [RoomShape.IH] = __TS__New(Set, {DoorSlot.LEFT_0, DoorSlot.RIGHT_0}),
-    [RoomShape.IV] = __TS__New(Set, {DoorSlot.UP_0, DoorSlot.DOWN_0}),
-    [RoomShape.SHAPE_1x2] = __TS__New(Set, {
-        DoorSlot.LEFT_0,
-        DoorSlot.UP_0,
-        DoorSlot.RIGHT_0,
-        DoorSlot.DOWN_0,
-        DoorSlot.LEFT_1,
-        DoorSlot.RIGHT_1
+    [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(Set, {DoorSlot.UP_0, DoorSlot.DOWN_0}),
-    [RoomShape.SHAPE_2x1] = __TS__New(Set, {
-        DoorSlot.LEFT_0,
-        DoorSlot.UP_0,
-        DoorSlot.RIGHT_0,
-        DoorSlot.DOWN_0,
-        DoorSlot.UP_1,
-        DoorSlot.DOWN_1
+    [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(Set, {DoorSlot.LEFT_0, DoorSlot.RIGHT_0}),
-    [RoomShape.SHAPE_2x2] = ALL_DOOR_SLOTS_SET,
-    [RoomShape.LTL] = ALL_DOOR_SLOTS_SET,
-    [RoomShape.LTR] = ALL_DOOR_SLOTS_SET,
-    [RoomShape.LBL] = ALL_DOOR_SLOTS_SET,
-    [RoomShape.LBR] = ALL_DOOR_SLOTS_SET
+    [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.1",
+  "version": "5.1.0",
   "description": "Helper functions and features for IsaacScript mods.",
   "keywords": [
     "isaac",
@@ -22,6 +22,6 @@
   "main": "index",
   "types": "index.d.ts",
   "dependencies": {
-    "isaac-typescript-definitions": "^3.0.17"
+    "isaac-typescript-definitions": "^3.0.18"
   }
 }