isaacscript-common 4.9.1 → 5.0.2

package/features/extraConsoleCommands/listCommands.lua

@@ -38,6 +38,8 @@ local ____cards = require("functions.cards")
 local getCardName = ____cards.getCardName
 local ____character = require("functions.character")
 local getCharacterName = ____character.getCharacterName
+local ____charge = require("functions.charge")
+local addCharge = ____charge.addCharge
 local ____collectibles = require("functions.collectibles")
 local isValidCollectibleType = ____collectibles.isValidCollectibleType
 local ____entitySpecific = require("functions.entitySpecific")
@@ -199,7 +201,7 @@ function ____exports.addCharges(self, params)
         printConsole(nil, "That is an invalid amount of arguments.")
         return
     end
-    local activeSlotString, chargeString = table.unpack(args)
+    local activeSlotString, numChargeString = table.unpack(args)
     local activeSlot = tonumber(activeSlotString)
     if activeSlot == nil then
         printConsole(
@@ -215,19 +217,17 @@ function ____exports.addCharges(self, params)
         )
         return
     end
-    local chargeNum = 1
-    if chargeString ~= nil then
-        local chargeNumAttempt = tonumber(chargeString)
-        if chargeNumAttempt == nil then
-            printConsole(nil, "The provided charge amount is invalid: " .. chargeString)
+    local numCharges = 1
+    if numChargeString ~= nil then
+        local numChargesAttempt = tonumber(numChargeString)
+        if numChargesAttempt == nil then
+            printConsole(nil, "The provided charge amount is invalid: " .. numChargeString)
             return
         end
-        chargeNum = chargeNumAttempt
+        numCharges = numChargesAttempt
     end
     local player = Isaac.GetPlayer()
-    local currentCharge = player:GetActiveCharge(activeSlot)
-    local newCharge = currentCharge + chargeNum
-    player:SetActiveCharge(newCharge, activeSlot)
+    addCharge(nil, player, activeSlot, numCharges)
 end
 --- Warps to the Angel Room for the floor. If the Devil Room has already been visited or initialized,
 -- this will uninitialize it and make an Angel Room instead.

package/functions/charge.d.ts

@@ -1,19 +1,40 @@
 import { ActiveSlot } from "isaac-typescript-definitions";
 /**
- * Helper function to add a charge to a player's active item, emulating what happens when a room is
- * cleared.
+ * 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:
- * - L rooms and 2x2 rooms granting a double charge
  * - The Battery
  * - AAA Battery
  *
  * @param player The player to grant the charges to.
- * @param ignoreBigRoomDoubleCharge Optional. If set to true, it will treat the current room as a
- *                                 1x1 room for the purposes of calculating how much charge to
- *                                 grant. Default is false.
+ * @param activeSlot The slot to grant the charges to.
+ * @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
+ *          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 addRoomClearCharge(player: EntityPlayer, ignoreBigRoomDoubleCharge?: boolean): void;
+export declare function addCharge(player: EntityPlayer, activeSlot: ActiveSlot, numCharges?: number, playSoundEffect?: boolean): int;
+/**
+ * Helper function to add a charge to a player's active item(s), emulating what happens when a room
+ * is cleared.
+ *
+ * This function will take the following things into account:
+ * - 2x2 rooms and L rooms granting a double charge
+ * - The Battery
+ * - AAA Battery
+ *
+ * @param player The player to grant the charges to.
+ * @param bigRoomDoubleCharge Optional. If set to false, it will treat the current room as a 1x1
+ *                            room for the purposes of calculating how much charge to grant. Default
+ *                            is true.
+ * @param playSoundEffect Optional. Whether to play a charge-related sound effect. Default is true.
+ */
+export declare function addRoomClearCharge(player: EntityPlayer, bigRoomDoubleCharge?: boolean, playSoundEffect?: boolean): void;
 /**
  * Helper function to add a charge to one of a player's active items, emulating what happens when a
  * room is cleared.
@@ -25,11 +46,12 @@ export declare function addRoomClearCharge(player: EntityPlayer, ignoreBigRoomDo
  *
  * @param player The player to grant the charges to.
  * @param activeSlot The active item slot to grant the charges to.
- * @param ignoreBigRoomDoubleCharge Optional. If set to true, it will treat the current room as a
- *                                 1x1 room for the purposes of calculating how much charge to
- *                                 grant. Default is false.
+ * @param bigRoomDoubleCharge Optional. If set to false, it will treat the current room as a 1x1
+ *                            room for the purposes of calculating how much charge to grant. Default
+ *                            is true.
+ * @param playSoundEffect Optional. Whether to play a charge-related sound effect. Default is true.
  */
-export declare function addRoomClearChargeToSlot(player: EntityPlayer, activeSlot: ActiveSlot, ignoreBigRoomDoubleCharge?: boolean): void;
+export declare function addRoomClearChargeToSlot(player: EntityPlayer, activeSlot: ActiveSlot, bigRoomDoubleCharge?: boolean, playSoundEffect?: boolean): void;
 /**
  * Helper function to add a charge to every player's active item, emulating what happens when a room
  * is cleared.

package/functions/charge.lua

@@ -1,9 +1,8 @@
 local ____exports = {}
-local getNumChargesToAdd, 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
-local RoomShape = ____isaac_2Dtypescript_2Ddefinitions.RoomShape
 local SoundEffect = ____isaac_2Dtypescript_2Ddefinitions.SoundEffect
 local TrinketType = ____isaac_2Dtypescript_2Ddefinitions.TrinketType
 local ____cachedClasses = require("cachedClasses")
@@ -13,41 +12,80 @@ local ____collectibles = require("functions.collectibles")
 local getCollectibleMaxCharges = ____collectibles.getCollectibleMaxCharges
 local ____playerIndex = require("functions.playerIndex")
 local getPlayers = ____playerIndex.getPlayers
---- Helper function to add a charge to one of a player's active items, emulating what happens when a
--- room is cleared.
+local ____roomShape = require("functions.roomShape")
+local getRoomShapeCharges = ____roomShape.getRoomShapeCharges
+--- 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:
--- - L rooms and 2x2 rooms granting a double charge
 -- - The Battery
 -- - AAA Battery
 -- 
 -- @param player The player to grant the charges to.
--- @param activeSlot The active item slot to grant the charges to.
--- @param ignoreBigRoomDoubleCharge Optional. If set to true, it will treat the current room as a
--- 1x1 room for the purposes of calculating how much charge to
--- grant. Default is false.
-function ____exports.addRoomClearChargeToSlot(self, player, activeSlot, ignoreBigRoomDoubleCharge)
-    if ignoreBigRoomDoubleCharge == nil then
-        ignoreBigRoomDoubleCharge = false
-    end
-    if not player:NeedsCharge(activeSlot) then
-        return
+-- @param activeSlot The slot to grant the charges to.
+-- @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
+-- 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
+    end
+    if playSoundEffect == nil then
+        playSoundEffect = true
     end
     local hud = game:GetHUD()
+    local chargesToAdd = getClampedChargesToAdd(nil, player, activeSlot, numCharges)
+    local modifiedChargesToAdd = getChargesToAddWithAAAModifier(nil, player, activeSlot, chargesToAdd)
     local totalCharge = ____exports.getTotalCharge(nil, player, activeSlot)
-    local chargesToAdd = getNumChargesToAdd(nil, player, activeSlot, ignoreBigRoomDoubleCharge)
-    local modifiedChargesToAdd = getNumChargesWithAAAModifier(nil, player, activeSlot, chargesToAdd)
     local newCharge = totalCharge + modifiedChargesToAdd
+    if newCharge == totalCharge then
+        return 0
+    end
     player:SetActiveCharge(newCharge, activeSlot)
     hud:FlashChargeBar(player, activeSlot)
-    ____exports.playChargeSoundEffect(nil, player, activeSlot)
+    if playSoundEffect then
+        ____exports.playChargeSoundEffect(nil, player, activeSlot)
+    end
+    return modifiedChargesToAdd
 end
-function getNumChargesToAdd(self, player, activeSlot, ignoreBigRoomDoubleCharge)
-    if ignoreBigRoomDoubleCharge == nil then
-        ignoreBigRoomDoubleCharge = false
+--- Helper function to add a charge to one of a player's active items, emulating what happens when a
+-- room is cleared.
+-- 
+-- This function will take the following things into account:
+-- - L rooms and 2x2 rooms granting a double charge
+-- - The Battery
+-- - AAA Battery
+-- 
+-- @param player The player to grant the charges to.
+-- @param activeSlot The active item slot to grant the charges to.
+-- @param bigRoomDoubleCharge Optional. If set to false, it will treat the current room as a 1x1
+-- room for the purposes of calculating how much charge to grant. Default
+-- is true.
+-- @param playSoundEffect Optional. Whether to play a charge-related sound effect. Default is true.
+function ____exports.addRoomClearChargeToSlot(self, player, activeSlot, bigRoomDoubleCharge, playSoundEffect)
+    if bigRoomDoubleCharge == nil then
+        bigRoomDoubleCharge = true
+    end
+    if playSoundEffect == nil then
+        playSoundEffect = true
     end
     local room = game:GetRoom()
     local roomShape = room:GetRoomShape()
+    local numCharges = bigRoomDoubleCharge and getRoomShapeCharges(nil, roomShape) or 1
+    ____exports.addCharge(
+        nil,
+        player,
+        activeSlot,
+        numCharges,
+        playSoundEffect
+    )
+end
+function getClampedChargesToAdd(self, player, activeSlot, numCharges)
     local activeItem = player:GetActiveItem(activeSlot)
     local activeCharge = player:GetActiveCharge(activeSlot)
     local batteryCharge = player:GetBatteryCharge(activeSlot)
@@ -65,12 +103,9 @@ function getNumChargesToAdd(self, player, activeSlot, ignoreBigRoomDoubleCharge)
     if hasBattery and batteryCharge + 1 == maxCharges then
         return 1
     end
-    if roomShape >= RoomShape.SHAPE_2x2 and not ignoreBigRoomDoubleCharge then
-        return 2
-    end
-    return 1
+    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)
@@ -81,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
@@ -110,28 +145,38 @@ 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, emulating what happens when a room is
--- cleared.
+--- Helper function to add a charge to a player's active item(s), emulating what happens when a room
+-- is cleared.
 -- 
 -- This function will take the following things into account:
--- - L rooms and 2x2 rooms granting a double charge
+-- - 2x2 rooms and L rooms granting a double charge
 -- - The Battery
 -- - AAA Battery
 -- 
 -- @param player The player to grant the charges to.
--- @param ignoreBigRoomDoubleCharge Optional. If set to true, it will treat the current room as a
--- 1x1 room for the purposes of calculating how much charge to
--- grant. Default is false.
-function ____exports.addRoomClearCharge(self, player, ignoreBigRoomDoubleCharge)
-    if ignoreBigRoomDoubleCharge == nil then
-        ignoreBigRoomDoubleCharge = false
+-- @param bigRoomDoubleCharge Optional. If set to false, it will treat the current room as a 1x1
+-- room for the purposes of calculating how much charge to grant. Default
+-- is true.
+-- @param playSoundEffect Optional. Whether to play a charge-related sound effect. Default is true.
+function ____exports.addRoomClearCharge(self, player, bigRoomDoubleCharge, playSoundEffect)
+    if bigRoomDoubleCharge == nil then
+        bigRoomDoubleCharge = true
+    end
+    if playSoundEffect == nil then
+        playSoundEffect = true
     end
     for ____, activeSlot in ipairs({ActiveSlot.PRIMARY, ActiveSlot.SECONDARY, ActiveSlot.POCKET}) do
-        ____exports.addRoomClearChargeToSlot(nil, player, activeSlot, ignoreBigRoomDoubleCharge)
+        ____exports.addRoomClearChargeToSlot(
+            nil,
+            player,
+            activeSlot,
+            bigRoomDoubleCharge,
+            playSoundEffect
+        )
     end
 end
 --- Helper function to add a charge to every player's active item, emulating what happens when a room

package/functions/roomShape.d.ts

@@ -6,18 +6,25 @@ import { DoorSlot, RoomShape } from "isaac-typescript-definitions";
  * started.
  */
 export declare function getGridIndexDelta(roomShape: RoomShape, doorSlot: DoorSlot): int | undefined;
+/**
+ * Helper function to see if a given room shape will grant a single charge or a double charge to the
+ * player's active item(s).
+ *
+ * For example, `RoomShape.SHAPE_2x2` will return 2.
+ */
+export declare function getRoomShapeBottomRightPosition(roomShape: RoomShape): Vector;
 /**
  * Helper function to get the grid position of the bottom-right tile of a given room shape.
  *
  * "Vector(0, 0)" corresponds to the top left tile of a room, not including the walls. (The top-left
  * wall would be at "Vector(-1, -1)".)
  */
-export declare function getRoomShapeBottomRightPosition(roomShape: RoomShape): Vector;
+export declare function getRoomShapeBounds(roomShape: RoomShape): readonly [width: int, height: int];
 /**
  * Helper function to get the bounds of a room shape, which are a box representing its contents.
  * This does not include the tiles that the walls are on. L rooms use the same bounds as a 2x2 room.
  */
-export declare function getRoomShapeBounds(roomShape: RoomShape): readonly [width: int, height: int];
+export declare function getRoomShapeCharges(roomShape: RoomShape): int;
 /**
  * Helper function to get the dimensions of a room shape's layout. This is NOT the size of the
  * room's actual contents! For that, use the `getRoomShapeBounds` function.
@@ -41,3 +48,10 @@ export declare function getRoomShapeTopLeftPosition(roomShape: RoomShape): Vecto
 export declare function getRoomShapeVolume(roomShape: RoomShape): int;
 export declare function getRoomShapeWidth(roomShape: RoomShape): int;
 export declare function isLRoom(roomShape: RoomShape): boolean;
+/**
+ * Helper function to see if a given room shape will grant a single charge or a double charge to the
+ * player's active item(s).
+ *
+ * For example, `RoomShape.SHAPE_2x2` will return true.
+ */
+export declare function isRoomShapeDoubleCharge(roomShape: RoomShape): boolean;

package/functions/roomShape.lua

@@ -1,6 +1,8 @@
 local ____lualib = require("lualib_bundle")
 local Map = ____lualib.Map
 local ____exports = {}
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local RoomShape = ____isaac_2Dtypescript_2Ddefinitions.RoomShape
 local ____roomShapeBounds = require("objects.roomShapeBounds")
 local ROOM_SHAPE_BOUNDS = ____roomShapeBounds.ROOM_SHAPE_BOUNDS
 local ____roomShapeLayoutSizes = require("objects.roomShapeLayoutSizes")
@@ -17,6 +19,13 @@ local ____roomShapeVolumes = require("objects.roomShapeVolumes")
 local ROOM_SHAPE_VOLUMES = ____roomShapeVolumes.ROOM_SHAPE_VOLUMES
 local ____LRoomShapesSet = require("sets.LRoomShapesSet")
 local L_ROOM_SHAPES_SET = ____LRoomShapesSet.L_ROOM_SHAPES_SET
+--- Helper function to see if a given room shape will grant a single charge or a double charge to the
+-- player's active item(s).
+-- 
+-- For example, `RoomShape.SHAPE_2x2` will return true.
+function ____exports.isRoomShapeDoubleCharge(self, roomShape)
+    return roomShape >= RoomShape.SHAPE_2x2
+end
 --- Helper function to get the grid index delta that a door out of the given room shape would lead
 -- to. For example, if you went through the bottom door in a room of `RoomShape.SHAPE_1x2`, you
 -- would end up in a room with a grid index that is +26 units from the `SafeGridIndex` of where you
@@ -25,17 +34,24 @@ function ____exports.getGridIndexDelta(self, roomShape, doorSlot)
     local doorSlotToGridIndexMap = ROOM_SHAPE_TO_DOOR_SLOTS_TO_GRID_INDEX_DELTA[roomShape]
     return doorSlotToGridIndexMap:get(doorSlot)
 end
+--- Helper function to see if a given room shape will grant a single charge or a double charge to the
+-- player's active item(s).
+-- 
+-- For example, `RoomShape.SHAPE_2x2` will return 2.
+function ____exports.getRoomShapeBottomRightPosition(self, roomShape)
+    return ROOM_SHAPE_TO_BOTTOM_RIGHT_POSITION[roomShape]
+end
 --- Helper function to get the grid position of the bottom-right tile of a given room shape.
 -- 
 -- "Vector(0, 0)" corresponds to the top left tile of a room, not including the walls. (The top-left
 -- wall would be at "Vector(-1, -1)".)
-function ____exports.getRoomShapeBottomRightPosition(self, roomShape)
-    return ROOM_SHAPE_TO_BOTTOM_RIGHT_POSITION[roomShape]
+function ____exports.getRoomShapeBounds(self, roomShape)
+    return ROOM_SHAPE_BOUNDS[roomShape]
 end
 --- Helper function to get the bounds of a room shape, which are a box representing its contents.
 -- This does not include the tiles that the walls are on. L rooms use the same bounds as a 2x2 room.
-function ____exports.getRoomShapeBounds(self, roomShape)
-    return ROOM_SHAPE_BOUNDS[roomShape]
+function ____exports.getRoomShapeCharges(self, roomShape)
+    return ____exports.isRoomShapeDoubleCharge(nil, roomShape) and 2 or 1
 end
 --- Helper function to get the dimensions of a room shape's layout. This is NOT the size of the
 -- room's actual contents! For that, use the `getRoomShapeBounds` function.

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": "4.9.1",
+  "version": "5.0.2",
   "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"
   }
 }