isaacscript-common 5.0.0 → 5.0.3

package/functions/array.d.ts

@@ -117,8 +117,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.
 -- 

package/functions/charge.d.ts

@@ -1,7 +1,10 @@
 import { ActiveSlot } from "isaac-typescript-definitions";
 /**
- * Helper function to add a charge to the player's active item. Will play the appropriate sound
- * effect, depending on whether the charge is partially full or completely full.
+ * Helper function to add a charge to the player's active item. Will flash the HUD and play the
+ * appropriate sound effect, depending on whether the charge is partially full or completely full.
+ *
+ * If the player's active item is already fully charged, then this function will return 0 and not
+ * flash the HUD or play a sound effect.
  *
  * This function will take the following things into account:
  * - The Battery
@@ -12,7 +15,8 @@ import { ActiveSlot } from "isaac-typescript-definitions";
  * @param numCharges Optional. The amount of charges to grant. Default is 1.
  * @param playSoundEffect Optional. Whether to play a charge-related sound effect. Default is true.
  * @returns The amount of charges that were actually granted. For example, if the active item was
- *          already fully charged, this function would return 0.
+ *          only one away from a full charge, but the `numCharges` provided to this function was 2,
+ *          then this function would return 1.
  */
 export declare function addCharge(player: EntityPlayer, activeSlot: ActiveSlot, numCharges?: number, playSoundEffect?: boolean): int;
 /**

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
@@ -14,8 +14,11 @@ local ____playerIndex = require("functions.playerIndex")
 local getPlayers = ____playerIndex.getPlayers
 local ____roomShape = require("functions.roomShape")
 local getRoomShapeCharges = ____roomShape.getRoomShapeCharges
---- Helper function to add a charge to the player's active item. Will play the appropriate sound
--- effect, depending on whether the charge is partially full or completely full.
+--- Helper function to add a charge to the player's active item. Will flash the HUD and play the
+-- appropriate sound effect, depending on whether the charge is partially full or completely full.
+-- 
+-- If the player's active item is already fully charged, then this function will return 0 and not
+-- flash the HUD or play a sound effect.
 -- 
 -- This function will take the following things into account:
 -- - The Battery
@@ -26,7 +29,8 @@ local getRoomShapeCharges = ____roomShape.getRoomShapeCharges
 -- @param numCharges Optional. The amount of charges to grant. Default is 1.
 -- @param playSoundEffect Optional. Whether to play a charge-related sound effect. Default is true.
 -- @returns The amount of charges that were actually granted. For example, if the active item was
--- already fully charged, this function would return 0.
+-- only one away from a full charge, but the `numCharges` provided to this function was 2,
+-- then this function would return 1.
 function ____exports.addCharge(self, player, activeSlot, numCharges, playSoundEffect)
     if numCharges == nil then
         numCharges = 1
@@ -35,9 +39,9 @@ function ____exports.addCharge(self, player, activeSlot, numCharges, playSoundEf
         playSoundEffect = true
     end
     local hud = game:GetHUD()
-    local totalCharge = ____exports.getTotalCharge(nil, player, activeSlot)
     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
         return 0
@@ -101,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)
@@ -112,10 +116,10 @@ function getNumChargesWithAAAModifier(self, player, activeSlot, chargesToAdd)
         return chargesToAdd
     end
     if not hasBattery and activeCharge + chargesToAdd == maxCharges - 1 then
-        return maxCharges + 1
+        return chargesToAdd + 1
     end
     if hasBattery and batteryCharge + chargesToAdd == maxCharges - 1 then
-        return maxCharges + 1
+        return chargesToAdd + 1
     end
     return chargesToAdd
 end
@@ -141,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/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/objects/roomShapeToDoorSlotCoordinates.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 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" />`
+ */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "5.0.0",
+  "version": "5.0.3",
   "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"
   }
 }