isaacscript-common 2.3.2 → 3.0.0

package/constantsFirstLast.lua

@@ -11,40 +11,103 @@ local itemConfig = ____cachedClasses.itemConfig
 local ____enums = require("functions.enums")
 local getEnumLength = ____enums.getEnumLength
 local getLastEnumValue = ____enums.getLastEnumValue
+--- Equal to `CollectibleType.SAD_ONION`.
 ____exports.FIRST_COLLECTIBLE_TYPE = CollectibleType.SAD_ONION
+--- Will change depending on how many modded collectibles there are.
+-- 
+-- Equal to `itemConfig.GetCollectibles().Size - 1`. (`Size` includes invalid collectibles. We
+-- subtract one to account for `CollectibleType.NULL`.)
 ____exports.LAST_COLLECTIBLE_TYPE = itemConfig:GetCollectibles().Size - 1
+--- Calculated from the `CollectibleType` enum.
+-- 
+-- Note that this cannot be calculated from the length of the enum, because unlike all of the other
+-- enums, collectible types are not contiguous.
 ____exports.LAST_VANILLA_COLLECTIBLE_TYPE = getLastEnumValue(nil, CollectibleType)
+--- If there are no modded collectibles, this constant will represent a collectible type that does
+-- not exist.
 ____exports.FIRST_MODDED_COLLECTIBLE_TYPE = ____exports.LAST_VANILLA_COLLECTIBLE_TYPE + 1
+--- Calculated from the `CollectibleType` enum. `CollectibleType.NULL` is not included.
 ____exports.NUM_VANILLA_COLLECTIBLE_TYPES = getEnumLength(nil, CollectibleType) - 1
+--- Unlike vanilla collectible types, modded collectible types are always contiguous.
 ____exports.NUM_MODDED_COLLECTIBLE_TYPES = ____exports.LAST_COLLECTIBLE_TYPE - ____exports.LAST_VANILLA_COLLECTIBLE_TYPE
 ____exports.NUM_COLLECTIBLE_TYPES = ____exports.NUM_VANILLA_COLLECTIBLE_TYPES + ____exports.NUM_MODDED_COLLECTIBLE_TYPES
+--- Will change depending on how many modded cards there are.
+-- 
+-- Equal to `itemConfig.GetTrinkets().Size - 1`. (We subtract one to account for
+-- `TrinketType.NULL`.)
 ____exports.NUM_TRINKET_TYPES = itemConfig:GetTrinkets().Size - 1
+--- Calculated from the `TrinketType` enum. `TrinketType.NULL` is not included.
 ____exports.NUM_VANILLA_TRINKET_TYPES = getEnumLength(nil, TrinketType) - 1
 ____exports.NUM_MODDED_TRINKET_TYPES = ____exports.NUM_TRINKET_TYPES - ____exports.NUM_VANILLA_TRINKET_TYPES
+--- Equal to `TrinketType.SWALLOWED_PENNY`.
 ____exports.FIRST_TRINKET_TYPE = TrinketType.SWALLOWED_PENNY
+--- Will change depending on how many modded cards there are.
+-- 
+-- Equal to `itemConfig.GetTrinkets().Size - 1`. (We subtract one to account for
+-- `TrinketType.NULL`.)
 ____exports.LAST_TRINKET_TYPE = ____exports.NUM_TRINKET_TYPES
+--- Calculated from the `TrinketType` enum.
 ____exports.LAST_VANILLA_TRINKET_TYPE = getLastEnumValue(nil, TrinketType)
+--- If there are no modded trinkets, this constant will represent a trinket type that does not exist.
 ____exports.FIRST_MODDED_TRINKET_TYPE = ____exports.LAST_VANILLA_TRINKET_TYPE + 1
+--- Will change depending on how many modded cards there are.
+-- 
+-- Equal to `itemConfig.GetCards().Size - 1`. (We subtract one to account for `Card.NULL`.)
 ____exports.NUM_CARDS = itemConfig:GetCards().Size - 1
+--- Calculated from the `Card` enum. `Card.NULL` is not included.
 ____exports.NUM_VANILLA_CARDS = getEnumLength(nil, Card) - 1
 ____exports.NUM_MODDED_CARDS = ____exports.NUM_CARDS - ____exports.NUM_VANILLA_CARDS
+--- Equal to `Card.FOOL`.
 ____exports.FIRST_CARD = Card.FOOL
+--- Will change depending on how many modded cards there are.
+-- 
+-- Equal to `itemConfig.GetCards().Size - 1`. (We subtract one to account for `Card.NULL`.)
 ____exports.LAST_CARD = ____exports.NUM_CARDS
+--- Calculated from the `Card` enum.
 ____exports.MAX_VANILLA_CARD = getLastEnumValue(nil, Card)
+--- If there are no modded cards, this constant will represent a card that does not exist.
 ____exports.FIRST_MODDED_CARD = ____exports.MAX_VANILLA_CARD + 1
+--- Will change depending on how many modded pill effects there are.
+-- 
+-- Equal to `itemConfig.GetPillEffects().Size - 1`. (We subtract one to account for
+-- `PillEffect.NULL`.)
 ____exports.NUM_PILL_EFFECTS = itemConfig:GetPillEffects().Size - 1
+--- Calculated from the `PillEffect` enum.
+-- 
+-- (There is no `PillEffect.NULL` in the custom enum, so we don't have to subtract one here.)
 ____exports.NUM_VANILLA_PILL_EFFECTS = getEnumLength(nil, PillEffect)
 ____exports.NUM_MODDED_PILL_EFFECTS = ____exports.NUM_PILL_EFFECTS - ____exports.NUM_VANILLA_PILL_EFFECTS
+--- Equal to `PillEffect.BAD_GAS`.
 ____exports.FIRST_PILL_EFFECT = PillEffect.BAD_GAS
+--- Will change depending on how many modded pill effects there are.
+-- 
+-- Equal to `itemConfig.GetPillEffects().Size - 1`. (We subtract one to account for
+-- `PillEffect.NULL`.)
 ____exports.LAST_PILL_EFFECT = ____exports.NUM_PILL_EFFECTS
+--- Calculated from the `PillEffect` enum.
 ____exports.LAST_VANILLA_PILL_EFFECT = getLastEnumValue(nil, PillEffect)
+--- If there are no modded pill effects, this constant will represent a pill effect that does not
+-- exist.
 ____exports.FIRST_MODDED_PILL_EFFECT = ____exports.LAST_VANILLA_PILL_EFFECT + 1
+--- Equal to `PillColor.BLUE_BLUE`.
 ____exports.FIRST_PILL_COLOR = PillColor.BLUE_BLUE
+--- Equal to `PillColor.WHITE_YELLOW`.
+-- 
+-- Note that `PillColor.GOLD` is technically higher, but that is not considered for the purposes of
+-- this constant.
 ____exports.LAST_NORMAL_PILL_COLOR = PillColor.WHITE_YELLOW
+--- Equal to `PillColor.HORSE_BLUE_BLUE`.
 ____exports.FIRST_HORSE_PILL_COLOR = PillColor.HORSE_BLUE_BLUE
+--- Equal to `PillColor.HORSE_WHITE_YELLOW`.
+-- 
+-- Note that `PillColor.HORSE_GOLD` is technically higher, but that is not considered for the
+-- purposes of this constant.
 ____exports.LAST_HORSE_PILL_COLOR = PillColor.HORSE_WHITE_YELLOW
 ____exports.NUM_NORMAL_PILL_COLORS = ____exports.LAST_NORMAL_PILL_COLOR - ____exports.FIRST_PILL_COLOR
+--- Equal to `PlayerType.ISAAC`.
 ____exports.FIRST_CHARACTER = PlayerType.ISAAC
+--- Calculated from the `PlayerType` enum.
 ____exports.LAST_VANILLA_CHARACTER = getLastEnumValue(nil, PlayerType)
+--- If there are no modded characters, this constant will represent a character that does not exist.
 ____exports.FIRST_MODDED_CHARACTER = ____exports.LAST_VANILLA_CHARACTER + 1
 return ____exports

package/enums/HealthType.lua

@@ -1,4 +1,7 @@
 local ____exports = {}
+--- This represents the type of health that is either given or taken away from a player. Note that we
+-- cannot use the `HeartSubType` enum for this purpose this since it has no value for broken hearts
+-- or max hearts.
 ____exports.HealthType = {}
 ____exports.HealthType.RED = 0
 ____exports.HealthType[____exports.HealthType.RED] = "RED"

package/enums/ModCallbackCustom.d.ts

@@ -2,7 +2,7 @@
  * - The Isaac API offers a lot of callbacks, but a lot of times there isn't one for the specific
  *   thing that you are looking to do. So, `isaacscript-common` adds a bunch of new callbacks that
  *   you can use.
- * - The extra callbacks are efficient such that no code is ran until they have one or more
+ * - The extra callbacks are efficient such that no code is executed until there is one or more
  *   subscriptions.
  * - You must upgrade your mod with the `upgradeMod` helper function before using a custom callback.
  */

package/enums/ModCallbackCustom.lua

@@ -1,4 +1,10 @@
 local ____exports = {}
+--- - The Isaac API offers a lot of callbacks, but a lot of times there isn't one for the specific
+--   thing that you are looking to do. So, `isaacscript-common` adds a bunch of new callbacks that
+--   you can use.
+-- - The extra callbacks are efficient such that no code is executed until there is one or more
+--   subscriptions.
+-- - You must upgrade your mod with the `upgradeMod` helper function before using a custom callback.
 ____exports.ModCallbackCustom = {}
 ____exports.ModCallbackCustom.POST_BOMB_INIT_LATE = 0
 ____exports.ModCallbackCustom[____exports.ModCallbackCustom.POST_BOMB_INIT_LATE] = "POST_BOMB_INIT_LATE"

package/enums/private/CopyableIsaacAPIClassType.lua

@@ -1,4 +1,5 @@
 local ____exports = {}
+--- This must match the enumeration in the JSDoc comments for `deepCopy` and `merge`.
 ____exports.CopyableIsaacAPIClassType = {}
 ____exports.CopyableIsaacAPIClassType.COLOR = "Color"
 ____exports.CopyableIsaacAPIClassType.K_COLOR = "KColor"

package/enums/private/SerializationBrand.lua

@@ -1,4 +1,9 @@
 local ____exports = {}
+--- During serialization, we write an arbitrary string key to the object with a value of an empty
+-- string. This is used during deserialization to instantiate the correct type of object.
+-- 
+-- Note that we do not bother branding TSTL classes because we have no way to invoke the proper
+-- constructor during deserialization.
 ____exports.SerializationBrand = {}
 ____exports.SerializationBrand.DEFAULT_MAP = "__TSTL_DEFAULT_MAP"
 ____exports.SerializationBrand.MAP = "__TSTL_MAP"

package/features/characterHealthConversion.lua

@@ -74,10 +74,16 @@ function prePickupCollisionHeart(self, pickup, collider)
 end
 local FEATURE_NAME = "character health manager"
 characterHealthReplacementMap = __TS__New(Map)
+---
+-- @internal
 function ____exports.characterHealthConversionInit(self, mod)
     mod:AddCallback(ModCallback.POST_PEFFECT_UPDATE, postPEffectUpdate)
     mod:AddCallback(ModCallback.PRE_PICKUP_COLLISION, prePickupCollisionHeart, PickupVariant.HEART)
 end
+--- Helper function to make a character that has the same health mechanic as Blue Baby (red heart
+-- containers --> soul hearts) or Dark Judas (red heart containers --> black hearts).
+-- 
+-- Call this function once at the beginning of your mod to declare the health conversion type.
 function ____exports.registerCharacterHealthConversion(self, playerType, conversionHeartSubType)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     characterHealthReplacementMap:set(playerType, conversionHeartSubType)

package/features/characterStats.lua

@@ -27,9 +27,26 @@ function evaluateCache(self, player, cacheFlag)
 end
 local FEATURE_NAME = "character stat manager"
 charactersStatMap = __TS__New(Map)
+---
+-- @internal
 function ____exports.characterStatsInit(self, mod)
     mod:AddCallback(ModCallback.EVALUATE_CACHE, evaluateCache)
 end
+--- Helper function to manage the stats for a vanilla or custom character. Call this function once at
+-- the beginning of your mod to declare the starting stats.
+-- 
+-- You must provide this function with a map of CacheFlag to the default stat amount. For example,
+-- the default amount of damage is 3.5. To make a custom character start with 4.5 damage:
+-- 
+-- ```ts
+-- const fooDefaultStats = new Map<CacheFlag, number>([
+--   [CacheFlag.DAMAGE, 4.5],
+-- ])
+-- registerCharacterStats(PlayerTypeCustom.FOO, fooDefaultStats);
+-- ```
+-- 
+-- Note that the format for the `CacheFlag.FIRE_DELAY` value should be in the tears stat format, not
+-- the `MaxFireDelay` format.
 function ____exports.registerCharacterStats(self, playerType, statMap)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     charactersStatMap:set(playerType, statMap)

package/features/debugDisplay/exports.lua

@@ -4,128 +4,218 @@ local printEnabled = ____utils.printEnabled
 local ____v = require("features.debugDisplay.v")
 local v = ____v.default
 local debugDisplayTextCallbacks = ____v.debugDisplayTextCallbacks
+--- After using the "playerDisplay" console command, text will be drawn on each player for debugging
+-- purposes. Use this function to specify a callback function that will returns the string that
+-- should be drawn.
 function ____exports.setPlayerDisplay(self, textCallback)
     debugDisplayTextCallbacks.player = textCallback
 end
+--- After using the "tearDisplay" console command, text will be drawn on each tear for debugging
+-- purposes. Use this function to specify a callback function that will returns the string that
+-- should be drawn.
 function ____exports.setTearDisplay(self, textCallback)
     debugDisplayTextCallbacks.tear = textCallback
 end
+--- After using the "familiarDisplay" console command, text will be drawn on each familiar for
+-- debugging purposes. Use this function to specify a callback function that will returns the string
+-- that should be drawn.
 function ____exports.setFamiliarDisplay(self, textCallback)
     debugDisplayTextCallbacks.familiar = textCallback
 end
+--- After using the "bombDisplay" console command, text will be drawn on each bomb for debugging
+-- purposes. Use this function to specify a callback function that will returns the string that
+-- should be drawn.
 function ____exports.setBombDisplay(self, textCallback)
     debugDisplayTextCallbacks.bomb = textCallback
 end
+--- After using the "pickupDisplay" console command, text will be drawn on each pickup for debugging
+-- purposes. Use this function to specify a callback function that will returns the string that
+-- should be drawn.
 function ____exports.setPickupDisplay(self, textCallback)
     debugDisplayTextCallbacks.pickup = textCallback
 end
+--- After using the "slotDisplay" console command, text will be drawn on each slot for debugging
+-- purposes. Use this function to specify a callback function that will returns the string that
+-- should be drawn.
 function ____exports.setSlotDisplay(self, textCallback)
     debugDisplayTextCallbacks.slot = textCallback
 end
+--- After using the "laserDisplay" console command, text will be drawn on each laser for debugging
+-- purposes. Use this function to specify a callback function that will returns the string that
+-- should be drawn.
 function ____exports.setLaserDisplay(self, textCallback)
     debugDisplayTextCallbacks.laser = textCallback
 end
+--- After using the "knifeDisplay" console command, text will be drawn on each knife for debugging
+-- purposes. Use this function to specify a callback function that will returns the string that
+-- should be drawn.
 function ____exports.setKnifeDisplay(self, textCallback)
     debugDisplayTextCallbacks.knife = textCallback
 end
+--- After using the "projectileDisplay" console command, text will be drawn on each projectile for
+-- debugging purposes. Use this function to specify a callback function that will returns the string
+-- that should be drawn.
 function ____exports.setProjectileDisplay(self, textCallback)
     debugDisplayTextCallbacks.projectile = textCallback
 end
+--- After using the "effectDisplay" console command, text will be drawn on each effect for debugging
+-- purposes. Use this function to specify a callback function that will returns the string that
+-- should be drawn.
 function ____exports.setEffectDisplay(self, textCallback)
     debugDisplayTextCallbacks.effect = textCallback
 end
+--- After using the "npcDisplay" console command, text will be drawn on each NPC for debugging
+-- purposes. Use this function to specify a callback function that will returns the string that
+-- should be drawn.
 function ____exports.setNPCDisplay(self, textCallback)
     debugDisplayTextCallbacks.npc = textCallback
 end
+--- After using the "rockDisplay" console command, text will be drawn on each rock for debugging
+-- purposes. Use this function to specify a callback function that will returns the string that
+-- should be drawn.
 function ____exports.setRockDisplay(self, textCallback)
     debugDisplayTextCallbacks.rock = textCallback
 end
+--- After using the "pitDisplay" console command, text will be drawn on each pit for debugging
+-- purposes. Use this function to specify a callback function that will returns the string that
+-- should be drawn.
 function ____exports.setPitDisplay(self, textCallback)
     debugDisplayTextCallbacks.pit = textCallback
 end
+--- After using the "spikesDisplay" console command, text will be drawn on each spikes for debugging
+-- purposes. Use this function to specify a callback function that will returns the string that
+-- should be drawn.
 function ____exports.setSpikesDisplay(self, textCallback)
     debugDisplayTextCallbacks.spikes = textCallback
 end
+--- After using the "tntDisplay" console command, text will be drawn on each TNT for debugging
+-- purposes. Use this function to specify a callback function that will returns the string that
+-- should be drawn.
 function ____exports.setTNTDisplay(self, textCallback)
     debugDisplayTextCallbacks.tnt = textCallback
 end
+--- After using the "poopDisplay" console command, text will be drawn on each poop for debugging
+-- purposes. Use this function to specify a callback function that will returns the string that
+-- should be drawn.
 function ____exports.setPoopDisplay(self, textCallback)
     debugDisplayTextCallbacks.poop = textCallback
 end
+--- After using the "poopDisplay" console command, text will be drawn on each poop for debugging
+-- purposes. Use this function to specify a callback function that will returns the string that
+-- should be drawn.
 function ____exports.setDoorDisplay(self, textCallback)
     debugDisplayTextCallbacks.door = textCallback
 end
+--- After using the "pressurePlateDisplay" console command, text will be drawn on each pressure plate
+-- for debugging purposes. Use this function to specify a callback function that will returns the
+-- string that should be drawn.
 function ____exports.setPressurePlateDisplay(self, textCallback)
     debugDisplayTextCallbacks.pressurePlate = textCallback
 end
+--- Toggles the debug display for players. This is the function that runs when you use the
+-- "playerDisplay" custom console command.
 function ____exports.togglePlayerDisplay(self)
     v.run.player = not v.run.player
     printEnabled(nil, v.run.player, "player display")
 end
+--- Toggles the debug display for tears. This is the function that runs when you use the
+-- "tearDisplay" custom console command.
 function ____exports.toggleTearDisplay(self)
     v.run.tear = not v.run.tear
     printEnabled(nil, v.run.tear, "tear display")
 end
+--- Toggles the debug display for familiars. This is the function that runs when you use the
+-- "familiarDisplay" custom console command.
 function ____exports.toggleFamiliarDisplay(self)
     v.run.familiar = not v.run.familiar
     printEnabled(nil, v.run.familiar, "familiar display")
 end
+--- Toggles the debug display for bombs. This is the function that runs when you use the
+-- "bombDisplay" custom console command.
 function ____exports.toggleBombDisplay(self)
     v.run.bomb = not v.run.bomb
     printEnabled(nil, v.run.bomb, "bomb display")
 end
+--- Toggles the debug display for pickups. This is the function that runs when you use the
+-- "pickupDisplay" custom console command.
 function ____exports.togglePickupDisplay(self)
     v.run.pickup = not v.run.pickup
     printEnabled(nil, v.run.pickup, "pickup display")
 end
+--- Toggles the debug display for slots. This is the function that runs when you use the
+-- "slotDisplay" custom console command.
 function ____exports.toggleSlotDisplay(self)
     v.run.slot = not v.run.slot
     printEnabled(nil, v.run.slot, "slot display")
 end
+--- Toggles the debug display for lasers. This is the function that runs when you use the
+-- "laserDisplay" custom console command.
 function ____exports.toggleLaserDisplay(self)
     v.run.laser = not v.run.laser
     printEnabled(nil, v.run.laser, "laser display")
 end
+--- Toggles the debug display for knives. This is the function that runs when you use the
+-- "knifeDisplay" custom console command.
 function ____exports.toggleKnifeDisplay(self)
     v.run.knife = not v.run.knife
     printEnabled(nil, v.run.knife, "knife display")
 end
+--- Toggles the debug display for projectiles. This is the function that runs when you use the
+-- "projectileDisplay" custom console command.
 function ____exports.toggleProjectileDisplay(self)
     v.run.projectile = not v.run.projectile
     printEnabled(nil, v.run.projectile, "projectile display")
 end
+--- Toggles the debug display for effects. This is the function that runs when you use the
+-- "effectDisplay" custom console command.
 function ____exports.toggleEffectDisplay(self)
     v.run.effect = not v.run.effect
     printEnabled(nil, v.run.effect, "effect display")
 end
+--- Toggles the debug display for NPCs. This is the function that runs when you use the "npcDisplay"
+-- custom console command.
 function ____exports.toggleNPCDisplay(self)
     v.run.npc = not v.run.npc
     printEnabled(nil, v.run.npc, "NPC display")
 end
+--- Toggles the debug display for rocks. This is the function that runs when you use the
+-- "rockDisplay" custom console command.
 function ____exports.toggleRockDisplay(self)
     v.run.rock = not v.run.rock
     printEnabled(nil, v.run.rock, "rock display")
 end
+--- Toggles the debug display for pits. This is the function that runs when you use the "pitDisplay"
+-- custom console command.
 function ____exports.togglePitDisplay(self)
     v.run.pit = not v.run.pit
     printEnabled(nil, v.run.pit, "pit display")
 end
+--- Toggles the debug display for spikes. This is the function that runs when you use the
+-- "spikesDisplay" custom console command.
 function ____exports.toggleSpikesDisplay(self)
     v.run.spikes = not v.run.spikes
     printEnabled(nil, v.run.spikes, "spikes display")
 end
+--- Toggles the debug display for TNT. This is the function that runs when you use the "tntDisplay"
+-- custom console command.
 function ____exports.toggleTNTDisplay(self)
     v.run.tnt = not v.run.tnt
     printEnabled(nil, v.run.tnt, "TNT display")
 end
+--- Toggles the debug display for poop. This is the function that runs when you use the "poopDisplay"
+-- custom console command.
 function ____exports.togglePoopDisplay(self)
     v.run.poop = not v.run.poop
     printEnabled(nil, v.run.poop, "poop display")
 end
+--- Toggles the debug display for doors. This is the function that runs when you use the
+-- "doorDisplay" custom console command.
 function ____exports.toggleDoorDisplay(self)
     v.run.door = not v.run.door
     printEnabled(nil, v.run.door, "door display")
 end
+--- Toggles the debug display for pressure plates. This is the function that runs when you use the
+-- "pressurePlateDisplay" custom console command.
 function ____exports.togglePressurePlateDisplay(self)
     v.run.pressurePlate = not v.run.pressurePlate
     printEnabled(nil, v.run.pressurePlate, "pressure plate display")

package/features/deployJSONRoom.lua

@@ -94,6 +94,14 @@ function respawnPersistentEntities(self)
         )
     end
 end
+--- Helper function to remove all naturally spawning entities and grid entities from a room. Notably,
+-- this will not remove players (1), tears (2), familiars (3), lasers (7), knives (8), projectiles
+-- (9), blacklisted NPCs such as Dark Esau, charmed NPCs, friendly NPCs, persistent NPCs, most
+-- effects (1000), doors, and walls.
+-- 
+-- @param fillWithDecorations Optional. Set to true to fill every grid tile with an invisible
+-- decoration, which prevents vanilla entities in the room from
+-- respawning the next time that the player enters. Default is false.
 function ____exports.emptyRoom(self, fillWithDecorations)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     local roomListIndex = getRoomListIndex(nil)
@@ -415,10 +423,33 @@ v = {level = {
         function() return {} end
     )
 }}
+---
+-- @internal
 function ____exports.deployJSONRoomInit(self, mod)
     saveDataManager(nil, "deployJSONRoom", v)
     mod:AddCallback(ModCallback.POST_NEW_ROOM, postNewRoom)
 end
+--- Helper function to deconstruct a vanilla room and set up a custom room in its place.
+-- Specifically, this will clear the current room of all entities and grid entities, and then spawn
+-- all of the entries and grid entities in the provided JSON room.
+-- 
+-- This function is meant to be used in the PostNewRoom callback.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- 
+-- import customRooms from "./customRooms";
+-- 
+-- const firstJSONRoom = customRooms.rooms.room[0];
+-- deployJSONRoom(firstJSONRoom);
+-- ```
+-- 
+-- @param jsonRoom The JSON room to deploy. *
+-- @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 verbose Optional. If specified, will write entries to the "log.txt" file that describe
+-- what the function is doing. Default is false.
 function ____exports.deployJSONRoom(self, jsonRoom, seedOrRNG, verbose)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -445,6 +476,31 @@ function ____exports.deployJSONRoom(self, jsonRoom, seedOrRNG, verbose)
     fixPitGraphics(nil)
     fillRoomWithDecorations(nil)
 end
+--- Helper function to deconstruct a vanilla room and set up a custom room in its place.
+-- Specifically, this will clear the current room of all entities and grid entities, and then spawn
+-- all of the entries and grid entities in one of the provided JSON rooms.
+-- 
+-- This function is meant to be used in the PostNewRoom callback.
+-- 
+-- Note that this function does not simply choose a random element in the provided array; it will
+-- properly account for each room weight using the algorithm from:
+-- https://stackoverflow.com/questions/1761626/weighted-random-numbers
+-- 
+-- For example:
+-- 
+-- ```ts
+-- import customRooms from "./customRooms";
+-- 
+-- const jsonRooms = customRooms.rooms.room;
+-- deployRandomJSONRoom(jsonRooms);
+-- ```
+-- 
+-- @param jsonRooms An array of JSON rooms to randomly select from. In practice, this will be
+-- something like.
+-- @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 verbose Optional. If specified, will write entries to the "log.txt" file that describe
+-- what the function is doing. Default is false.
 function ____exports.deployRandomJSONRoom(self, jsonRooms, seedOrRNG, verbose)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)

package/features/disableInputs.lua

@@ -49,17 +49,31 @@ v = {run = {
     disableInputsWithWhitelistMap = __TS__New(Map),
     enableInputsWithBlacklistMap = __TS__New(Map)
 }}
+---
+-- @internal
 function ____exports.disableInputsInit(self, mod)
     saveDataManager(nil, "disableInputs", v)
     mod:AddCallback(ModCallback.INPUT_ACTION, isActionPressed, InputHook.IS_ACTION_PRESSED)
     mod:AddCallback(ModCallback.INPUT_ACTION, isActionTriggered, InputHook.IS_ACTION_TRIGGERED)
     mod:AddCallback(ModCallback.INPUT_ACTION, getActionValue, InputHook.GET_ACTION_VALUE)
 end
+--- Helper function to enable all inputs. Use this function to set things back to normal after having
+-- used one of the other helper functions to disable inputs.
+-- 
+-- @param key The name of the mod feature that is requesting the enable/disable. This is needed so
+-- that multiple mod features can work in tandem.
 function ____exports.enableAllInputs(self, key)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     v.run.disableInputsWithWhitelistMap:delete(key)
     v.run.enableInputsWithBlacklistMap:delete(key)
 end
+--- Helper function to disable all inputs. This is useful because `EntityPlayer.ControlsEnabled` can
+-- be changed by the game under certain conditions.
+-- 
+-- Use the `enableAllInputs` helper function to set things back to normal.
+-- 
+-- @param key The name of the mod feature that is requesting the enable/disable. This is needed so
+-- that multiple mod features can work in tandem.
 function ____exports.disableAllInputs(self, key)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     v.run.disableInputsWithWhitelistMap:set(
@@ -68,20 +82,51 @@ function ____exports.disableAllInputs(self, key)
     )
     v.run.enableInputsWithBlacklistMap:delete(key)
 end
+--- Helper function to enable all inputs besides the ones provided. This is useful because
+-- `EntityPlayer.ControlsEnabled` can be changed by the game under certain conditions.
+-- 
+-- Use the `enableAllInputs` helper function to set things back to normal.
+-- 
+-- @param key The name of the mod feature that is requesting the enable/disable. This is needed so
+-- that multiple mod features can work in tandem.
+-- @param blacklist A set of ButtonActions to disallow.
 function ____exports.enableAllInputsExceptFor(self, key, blacklist)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     v.run.disableInputsWithWhitelistMap:delete(key)
     v.run.enableInputsWithBlacklistMap:set(key, blacklist)
 end
+--- Helper function to disable all inputs besides the ones provided. This is useful because
+-- `EntityPlayer.ControlsEnabled` can be changed by the game under certain conditions.
+-- 
+-- Use the `enableAllInputs` helper function to set things back to normal.
+-- 
+-- @param key The name of the mod feature that is requesting the enable/disable. This is needed so
+-- that multiple mod features can work in tandem.
+-- @param whitelist A set of ButtonActions to allow.
 function ____exports.disableAllInputsExceptFor(self, key, whitelist)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     v.run.disableInputsWithWhitelistMap:set(key, whitelist)
     v.run.enableInputsWithBlacklistMap:delete(key)
 end
+--- Helper function to disable only the inputs used for moving the character (or moving the cursor in
+-- the UI). This is useful because `EntityPlayer.ControlsEnabled` can be changed by the game under
+-- certain conditions.
+-- 
+-- Use the `enableAllInputs` helper function to set things back to normal.
+-- 
+-- @param key The name of the mod feature that is requesting the enable/disable. This is needed so
+-- that multiple mod features can work in tandem.
 function ____exports.disableMovementInputs(self, key)
     local moveActions = getMoveActions(nil)
     ____exports.enableAllInputsExceptFor(nil, key, moveActions)
 end
+--- Helper function to disable only the inputs used for shooting tears. This is useful because
+-- `EntityPlayer.ControlsEnabled` can be changed by the game under certain conditions.
+-- 
+-- Use the `enableAllInputs` helper function to set things back to normal.
+-- 
+-- @param key The name of the mod feature that is requesting the enable/disable. This is needed so
+-- that multiple mod features can work in tandem.
 function ____exports.disableShootingInputs(self, key)
     local shootActions = getShootActions(nil)
     ____exports.enableAllInputsExceptFor(nil, key, shootActions)

package/features/disableSound.lua

@@ -22,10 +22,18 @@ end
 local FEATURE_NAME = "sound disabler"
 local musicWasEnabled = false
 v = {run = {disableSoundSet = __TS__New(Set)}}
+---
+-- @internal
 function ____exports.disableSoundsInit(self, mod)
     saveDataManager(nil, "disableSounds", v)
     mod:AddCallback(ModCallback.POST_RENDER, postRender)
 end
+--- Helper function to stop muting all sound effects and music.
+-- 
+-- Use this function to set things back to normal after having used `disableAllSounds`.
+-- 
+-- @param key The name of the mod feature that is requesting the enable/disable. This is needed so
+-- that multiple mod features can work in tandem.
 function ____exports.enableAllSound(self, key)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     if not v.run.disableSoundSet:has(key) then
@@ -37,6 +45,12 @@ function ____exports.enableAllSound(self, key)
     end
     stopAllSoundEffects(nil)
 end
+--- Helper function to disable all sound effects and music (by constantly musting them).
+-- 
+-- Use the `enableAllSounds` helper function to set things back to normal.
+-- 
+-- @param key The name of the mod feature that is requesting the enable/disable. This is needed so
+-- that multiple mod features can work in tandem.
 function ____exports.disableAllSound(self, key)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     if v.run.disableSoundSet.size == 0 then