isaacscript-common 2.3.2 → 3.1.1

package/classes/DefaultMap.d.ts

@@ -1,79 +1,110 @@
 /**
- * A function that creates the value for your default map. For example, if it was a default map
- * containing maps, the factory function would be: `() => new Map()`
+ * A function that creates the default value for your `DefaultMap`. For example, if it was a
+ * `DefaultMap` containing maps, the factory function would be: `() => new Map()`
  */
 export declare type FactoryFunction<V, Args extends unknown[]> = (...extraArgs: Args) => V;
-declare type FirstArg<K, V, Args extends unknown[]> = Iterable<[K, V]> | V | FactoryFunction<V, Args>;
-declare type SecondArg<V, Args extends unknown[]> = V | FactoryFunction<V, Args>;
 /**
- * An extended `Map` with some new methods:
+ * `DefaultMap` is a data structure that makes working with default values easier.
  *
- * - `getAndSetDefault` - If the key exists, this will return the same thing as the `get` method.
- *   Otherwise, it will set a default value to the key, and then return the default value.
- * - `getDefaultValue` - Returns the default value to be used for a new key. (If a factory function
- *   was provided during instantiation, this will execute the factory function.)
- * - `getConstructorArg` - Helper method for cloning the map. Returns either the default value or
- *   the reference to the factory function.
+ * It is a common pattern to look up a value in a `Map`, and then, if the value does not exist, set
+ * a default value for the key, and then return the default value. `DefaultMap` abstracts this
+ * operation away by providing the `getAndSetDefault` method.
  *
- * When instantiating a new DefaultMap, you must specify either a default value or a function that
- * returns a default value.
+ * Using a `DefaultMap` is nice because it makes code more declarative, since you specify what the
+ * default value is alongside the types of the keys/values.
  *
- * For example:
+ * When instantiating a new `DefaultMap`, you must specify default value as the first argument. (The
+ * default value is the initial value that will be assigned to every new entry in the
+ * `getAndSetDefault` method.) For example:
  *
  * ```ts
  * // Initializes a new empty DefaultMap with a default value of "foo".
- * const defaultMapWithPrimitive = new DefaultMap<string, string>("foo");
+ * const defaultMapWithString = new DefaultMap<string, string>("foo");
  *
- * // Initializes a new empty DefaultMap with a default value of a new Map.
- * const defaultMapWithFactory = new DefaultMap<string, Map<string, string>>(() => {
- *   return new Map();
- * })
+ * const value = defaultMapWithString.getAndSetDefault("bar");
+ * // value is now "foo" and an entry for "bar" is now set.
+ * ```
  *
- * // Initializes a DefaultMap with some initial values and a default value of "bar".
- * const defaultMapWithInitialValues = new DefaultMap<string, string>([
- *   ["a1", "a2"],
- *   ["b1", "b2"],
- * ], "bar");
+ * Sometimes, instead of having a static initial value for every entry in the map, you will want a
+ * dynamic initial value that is contingent upon the key or some other variable. In these cases, you
+ * can instead specify that the `DefaultMap` should run a function that will return the initial
+ * value. (This is referred to as a "factory function".) For example:
+ *
+ * ```ts
+ * // Initializes a new empty DefaultMap with a default value based on "someGlobalVariable".
+ * const factoryFunction = () => someGlobalVariable ? 0 : 1;
+ * const defaultMapWithFactoryFunction = new DefaultMap<string, string>(factoryFunction);
  * ```
  *
- * If specified, the first argument of a factory function must always be equal to the key:
+ * Note that in TypeScript and Lua, booleans, numbers, and strings are "passed by value". This means
+ * that when the `DefaultMap` creates a new entry, if the default value is one of these 3 types, the
+ * values will be copied. On the other hand, arrays and maps and other complex data structures are
+ * "passed by reference". This means that when the `DefaultMap` creates a new entry, if the default
+ * value is an array, then it would not be copied. Instead, the same shared array would be assigned
+ * to every entry. Thus, to solve this problem, any variable that is passed by reference must be
+ * created using a factory function to ensure that each copy is unique. For example:
  *
  * ```ts
- * const defaultMapWithConditionalDefaultValue = new DefaultMap<number, number>((key: number) => {
- *   return isOdd(key) ? 0 : 1;
- * });
+ * // Initializes a new empty DefaultMap with a default value of a new empty array.
+ * const factoryFunction = () => [] as ;
+ * const defaultMapWithArray = new DefaultMap<string, string[]>(factoryFunction);
  * ```
  *
- * You can also specify a factory function that takes a generic amount of arguments beyond the
- * first:
+ * In the previous two examples, the factory functions did not have any arguments. But you can also
+ * specify a factory function that takes one or more arguments:
  *
  * ```ts
  * const factoryFunction = (arg: boolean) => arg ? 0 : 1;
- * const defaultMapWithExtraArgs = new DefaultMap<string, string, [arg: boolean]>(factoryFunction);
+ * const defaultMapWithArg = new DefaultMap<string, string, [arg: boolean]>(factoryFunction);
  * ```
+ *
+ * Similar to a normal `Map`, you can also include an initializer list in the constructor as the
+ * second argument:
+ *
+ * ```ts
+ * // Initializes a DefaultMap with a default value of "foo" and some initial values.
+ * const defaultMapWithInitialValues = new DefaultMap<string, string>("foo", [
+ *   ["a1", "a2"],
+ *   ["b1", "b2"],
+ * ], );
+ * ```
+ *
+ * Finally, note that `DefaultMap` has the following additional utility methods:
+ *
+ * - `getAndSetDefault` - The method that is called inside the overridden `get` method. In most
+ *   cases, you can use the overridden `get` method instead of calling this function directly.
+ *   However, if a factory function was provided during instantiation, and the factory function has
+ *   one or more arguments, then you must call this method instead (and provide the corresponding
+ *   arguments).
+ * - `getWithoutDefault` - Calls the original `Map.get` function (without setting the default
+ *   value).
+ * - `getDefaultValue` - Returns the default value to be used for a new key. (If a factory function
+ *   was provided during instantiation, this will execute the factory function.)
+ * - `getConstructorArg` - Helper method for cloning the map. Returns either the default value or
+ *   the reference to the factory function.
  */
-export declare class DefaultMap<K, V, Args extends unknown[] = []> extends Map<K, V> {
+export declare class DefaultMap<Key, Value, Args extends unknown[] = []> extends Map<Key, Value> {
     private defaultValue;
     private defaultValueFactory;
     /**
      * See the main `DefaultMap` documentation:
      * https://isaacscript.github.io/isaacscript-common/classes/classes_DefaultMap.DefaultMap
      */
-    constructor(iterableOrDefaultValueOrDefaultValueFactory: FirstArg<K, V, Args>, defaultValueOrDefaultValueFactory?: SecondArg<V, Args>);
+    constructor(defaultValueOrFactoryFunction: Value | FactoryFunction<Value, Args>, initializerArray?: Iterable<[Key, Value]>);
     /**
-     * If the key exists, this will return the same thing as the `get` method. Otherwise, it will set
-     * a default value to the key, and then return the default value.
+     * If the key exists, this will return the same thing as the normal `Map.get` method. Otherwise,
+     * it will set a default value for the provided key, and then return the default value.
      */
-    getAndSetDefault(key: K, ...extraArgs: Args): V;
+    getAndSetDefault(key: Key, ...extraArgs: Args): Value;
+    getWithoutDefault(key: Key): Value | undefined;
     /**
      * Returns the default value to be used for a new key. (If a factory function was provided during
      * instantiation, this will execute the factory function.)
      */
-    getDefaultValue(...extraArgs: Args): V;
+    getDefaultValue(...extraArgs: Args): Value;
     /**
      * Helper method for cloning the map. Returns either the default value or a reference to the
      * factory function.
      */
-    getConstructorArg(): V | FactoryFunction<V, Args>;
+    getConstructorArg(): Value | FactoryFunction<Value, Args>;
 }
-export {};

package/classes/DefaultMap.lua

@@ -4,58 +4,106 @@ local Map = ____lualib.Map
 local __TS__ClassExtends = ____lualib.__TS__ClassExtends
 local __TS__TypeOf = ____lualib.__TS__TypeOf
 local ____exports = {}
-local parseArguments, parseArgumentsOne, parseArgumentsTwo, parseDefaultValueOrDefaultValueFactory
-function parseArguments(self, firstArg, secondArg)
-    return secondArg == nil and parseArgumentsOne(nil, firstArg) or parseArgumentsTwo(nil, firstArg, secondArg)
-end
-function parseArgumentsOne(self, firstArg)
-    local arg = firstArg
-    local ____parseDefaultValueOrDefaultValueFactory_result_1 = parseDefaultValueOrDefaultValueFactory(nil, arg)
-    local defaultValue = ____parseDefaultValueOrDefaultValueFactory_result_1.defaultValue
-    local defaultValueFactory = ____parseDefaultValueOrDefaultValueFactory_result_1.defaultValueFactory
-    return {iterable = nil, defaultValue = defaultValue, defaultValueFactory = defaultValueFactory}
-end
-function parseArgumentsTwo(self, firstArg, secondArg)
-    local firstArgType = type(firstArg)
-    if firstArgType ~= "table" then
-        error("A DefaultMap constructor with two arguments must have the first argument be the initializer list.")
-    end
-    local ____parseDefaultValueOrDefaultValueFactory_result_2 = parseDefaultValueOrDefaultValueFactory(nil, secondArg)
-    local defaultValue = ____parseDefaultValueOrDefaultValueFactory_result_2.defaultValue
-    local defaultValueFactory = ____parseDefaultValueOrDefaultValueFactory_result_2.defaultValueFactory
-    return {iterable = firstArg, defaultValue = defaultValue, defaultValueFactory = defaultValueFactory}
-end
-function parseDefaultValueOrDefaultValueFactory(self, arg)
-    if type(arg) == "function" then
-        return {defaultValue = nil, defaultValueFactory = arg}
-    end
-    if type(arg) == "boolean" or type(arg) == "number" or type(arg) == "string" then
-        return {defaultValue = arg, defaultValueFactory = nil}
-    end
-    return error("A DefaultMap was instantiated with an unknown type of: " .. __TS__TypeOf(arg))
-end
+--- `DefaultMap` is a data structure that makes working with default values easier.
+-- 
+-- It is a common pattern to look up a value in a `Map`, and then, if the value does not exist, set
+-- a default value for the key, and then return the default value. `DefaultMap` abstracts this
+-- operation away by providing the `getAndSetDefault` method.
+-- 
+-- Using a `DefaultMap` is nice because it makes code more declarative, since you specify what the
+-- default value is alongside the types of the keys/values.
+-- 
+-- When instantiating a new `DefaultMap`, you must specify default value as the first argument. (The
+-- default value is the initial value that will be assigned to every new entry in the
+-- `getAndSetDefault` method.) For example:
+-- 
+-- ```ts
+-- // Initializes a new empty DefaultMap with a default value of "foo".
+-- const defaultMapWithString = new DefaultMap<string, string>("foo");
+-- 
+-- const value = defaultMapWithString.getAndSetDefault("bar");
+-- // value is now "foo" and an entry for "bar" is now set.
+-- ```
+-- 
+-- Sometimes, instead of having a static initial value for every entry in the map, you will want a
+-- dynamic initial value that is contingent upon the key or some other variable. In these cases, you
+-- can instead specify that the `DefaultMap` should run a function that will return the initial
+-- value. (This is referred to as a "factory function".) For example:
+-- 
+-- ```ts
+-- // Initializes a new empty DefaultMap with a default value based on "someGlobalVariable".
+-- const factoryFunction = () => someGlobalVariable ? 0 : 1;
+-- const defaultMapWithFactoryFunction = new DefaultMap<string, string>(factoryFunction);
+-- ```
+-- 
+-- Note that in TypeScript and Lua, booleans, numbers, and strings are "passed by value". This means
+-- that when the `DefaultMap` creates a new entry, if the default value is one of these 3 types, the
+-- values will be copied. On the other hand, arrays and maps and other complex data structures are
+-- "passed by reference". This means that when the `DefaultMap` creates a new entry, if the default
+-- value is an array, then it would not be copied. Instead, the same shared array would be assigned
+-- to every entry. Thus, to solve this problem, any variable that is passed by reference must be
+-- created using a factory function to ensure that each copy is unique. For example:
+-- 
+-- ```ts
+-- // Initializes a new empty DefaultMap with a default value of a new empty array.
+-- const factoryFunction = () => [] as ;
+-- const defaultMapWithArray = new DefaultMap<string, string[]>(factoryFunction);
+-- ```
+-- 
+-- In the previous two examples, the factory functions did not have any arguments. But you can also
+-- specify a factory function that takes one or more arguments:
+-- 
+-- ```ts
+-- const factoryFunction = (arg: boolean) => arg ? 0 : 1;
+-- const defaultMapWithArg = new DefaultMap<string, string, [arg: boolean]>(factoryFunction);
+-- ```
+-- 
+-- Similar to a normal `Map`, you can also include an initializer list in the constructor as the
+-- second argument:
+-- 
+-- ```ts
+-- // Initializes a DefaultMap with a default value of "foo" and some initial values.
+-- const defaultMapWithInitialValues = new DefaultMap<string, string>("foo", [
+--   ["a1", "a2"],
+--   ["b1", "b2"],
+-- ], );
+-- ```
+-- 
+-- Finally, note that `DefaultMap` has the following additional utility methods:
+-- 
+-- - `getAndSetDefault` - The method that is called inside the overridden `get` method. In most
+--   cases, you can use the overridden `get` method instead of calling this function directly.
+--   However, if a factory function was provided during instantiation, and the factory function has
+--   one or more arguments, then you must call this method instead (and provide the corresponding
+--   arguments).
+-- - `getWithoutDefault` - Calls the original `Map.get` function (without setting the default
+--   value).
+-- - `getDefaultValue` - Returns the default value to be used for a new key. (If a factory function
+--   was provided during instantiation, this will execute the factory function.)
+-- - `getConstructorArg` - Helper method for cloning the map. Returns either the default value or
+--   the reference to the factory function.
 ____exports.DefaultMap = __TS__Class()
 local DefaultMap = ____exports.DefaultMap
 DefaultMap.name = "DefaultMap"
 __TS__ClassExtends(DefaultMap, Map)
-function DefaultMap.prototype.____constructor(self, iterableOrDefaultValueOrDefaultValueFactory, defaultValueOrDefaultValueFactory)
-    local ____parseArguments_result_0 = parseArguments(nil, iterableOrDefaultValueOrDefaultValueFactory, defaultValueOrDefaultValueFactory)
-    local iterable = ____parseArguments_result_0.iterable
-    local defaultValue = ____parseArguments_result_0.defaultValue
-    local defaultValueFactory = ____parseArguments_result_0.defaultValueFactory
-    if defaultValue == nil and defaultValueFactory == nil then
-        error("A DefaultMap must be instantiated with either a default value or a function that returns a default value.")
+function DefaultMap.prototype.____constructor(self, defaultValueOrFactoryFunction, initializerArray)
+    local argType = __TS__TypeOf(defaultValueOrFactoryFunction)
+    local argIsPrimitive = argType == "boolean" or argType == "number" or argType == "string"
+    local argIsFunction = argType == "function"
+    if not argIsPrimitive and not argIsFunction then
+        error(("Failed to instantiate a DefaultMap since the provided default value was of type \"" .. argType) .. "\". This error usually means that you are trying to use an array (or some other non-primitive data structure that is passed by reference) as the default value. Instead, return the data structure in a factory function, like \"() => []\". See the DefaultMap documentation for more details.")
     end
-    if iterable == nil then
-        Map.prototype.____constructor(self)
+    Map.prototype.____constructor(self, initializerArray)
+    if argIsFunction then
+        self.defaultValue = nil
+        self.defaultValueFactory = defaultValueOrFactoryFunction
     else
-        Map.prototype.____constructor(self, iterable)
+        self.defaultValue = defaultValueOrFactoryFunction
+        self.defaultValueFactory = nil
     end
-    self.defaultValue = defaultValue
-    self.defaultValueFactory = defaultValueFactory
 end
 function DefaultMap.prototype.getAndSetDefault(self, key, ...)
-    local value = self:get(key)
+    local value = Map.prototype.get(self, key)
     if value ~= nil then
         return value
     end
@@ -63,6 +111,9 @@ function DefaultMap.prototype.getAndSetDefault(self, key, ...)
     self:set(key, defaultValue)
     return defaultValue
 end
+function DefaultMap.prototype.getWithoutDefault(self, key)
+    return Map.prototype.get(self, key)
+end
 function DefaultMap.prototype.getDefaultValue(self, ...)
     if self.defaultValue ~= nil then
         return self.defaultValue

package/classes/ModUpgraded.d.ts

@@ -2,9 +2,9 @@ import { ModCallback } from "isaac-typescript-definitions";
 import { ModCallbackCustom } from "../enums/ModCallbackCustom";
 import { AddCallbackParameterCustom } from "../interfaces/AddCallbackParameterCustom";
 /**
- * `isaacscript-common` has many custom callbacks that you can use in your mods. Instead of
- * hijacking the vanilla `Mod` object, we provide a `ModUpgraded` object for you to use, which
- * extends the base class and adds a new method of `AddCallbackCustom`.
+ * `isaacscript-common` has many {@link ModCallbackCustom custom callbacks} that you can use in your
+ * mods. Instead of hijacking the vanilla `Mod` object, we provide a `ModUpgraded` object for you to
+ * use, which extends the base class and adds a new method of `AddCallbackCustom`.
  *
  * To upgrade your mod, use the `upgradeMod` helper function.
  */

package/classes/ModUpgraded.lua

@@ -3,6 +3,11 @@ local __TS__Class = ____lualib.__TS__Class
 local ____exports = {}
 local ____callbackRegisterFunctions = require("objects.callbackRegisterFunctions")
 local CALLBACK_REGISTER_FUNCTIONS = ____callbackRegisterFunctions.CALLBACK_REGISTER_FUNCTIONS
+--- `isaacscript-common` has many {@link ModCallbackCustomcustom callbacks} that you can use in your
+-- mods. Instead of hijacking the vanilla `Mod` object, we provide a `ModUpgraded` object for you to
+-- use, which extends the base class and adds a new method of `AddCallbackCustom`.
+-- 
+-- To upgrade your mod, use the `upgradeMod` helper function.
 ____exports.ModUpgraded = __TS__Class()
 local ModUpgraded = ____exports.ModUpgraded
 ModUpgraded.name = "ModUpgraded"

package/constants.lua

@@ -8,38 +8,79 @@ local TrinketSlot = ____isaac_2Dtypescript_2Ddefinitions.TrinketSlot
 local ____enums = require("functions.enums")
 local getEnumLength = ____enums.getEnumLength
 local getLastEnumValue = ____enums.getLastEnumValue
+--- The distance of the laser when Azazel does not have any range up items yet. For more info, see
+-- the documentation for the `getAzazelBrimstoneDistance` function.
 ____exports.AZAZEL_DEFAULT_BRIMSTONE_DISTANCE = 75.125
+--- The path to the png file for collectible items during Curse of the Blind, making them appear with
+-- a red question mark.
 ____exports.BLIND_ITEM_PNG_PATH = "gfx/items/collectibles/questionmark.png"
+--- Bombs explode when their frame count is equal to this value.
 ____exports.BOMB_EXPLODE_FRAME = 45
 ____exports.DEFAULT_ITEM_POOL_TYPE = ItemPoolType.TREASURE
+--- This is also the distance that a player spawns from the door that they enter a room from.
 ____exports.DISTANCE_OF_GRID_TILE = 40
 ____exports.DOOR_HITBOX_RADIUS = 11
+--- When Eggies take fatal damage, they go into NpcState.STATE_SUICIDE and spawn 14 Swarm Spiders
+-- while their StateFrame ticks upwards. The 14th spider appears when the StateFrame is at this
+-- value.
 ____exports.EGGY_STATE_FRAME_OF_FINAL_SPIDER = 45
+--- A non-existent or completely transparent PNG file for use in clearing sprites. For more
+-- information, see the documentation for the `clearSprite` helper function.
 ____exports.EMPTY_PNG_PATH = "gfx/none.png"
+--- The random items that appear when the player has TMTRAINER are generated on the fly as they are
+-- encountered by the player. The first TMTRAINER item takes the final possible 32 bit number. The
+-- second TMTRAINER item subtracts one from that, and so on.
 ____exports.FIRST_GLITCHED_COLLECTIBLE_TYPE = (1 << 32) - 1
 ____exports.GAME_FRAMES_PER_SECOND = 30
 ____exports.GRID_INDEX_CENTER_OF_1X1_ROOM = 67
 ____exports.ISAAC_FRAMES_PER_SECOND = 60
+--- The floor is represented by a 13x13 grid. Room indexes start at 0. The first column is
+-- represented by grid indexes 0, 13, 26, and so on.
 ____exports.LEVEL_GRID_COLUMN_HEIGHT = 13
+--- The floor is represented by a 13x13 grid. Room indexes start at 0. The first row is represented
+-- by grid indexes from 0 to 12. The second row is represented by grid indexes from 13 to 25, and so
+-- on.
 ____exports.LEVEL_GRID_ROW_WIDTH = 13
+--- The floor is represented by a 13x13 grid. Room indexes start at 0. The first row is represented
+-- by grid indexes from 0 to 12. The second row is represented by grid indexes from 13 to 25, and so
+-- on. The maximum room index possible is 168. (It is not 169 because we start at 0 instead of 1.)
 ____exports.MAX_LEVEL_GRID_INDEX = 168
+--- The game has a limit on the number of currently spawned familiars and will refuse to spawn any
+-- more if it reaches the limit. Blue flies and blue spiders have a lower priority and will be
+-- deleted to make room for other familiars.
 ____exports.MAX_NUM_FAMILIARS = 64
+--- The game can only handle up to four different players.
 ____exports.MAX_NUM_INPUTS = 4
+--- With Birthright, it is possible for Magdalene to have 18 heart containers.
 ____exports.MAX_PLAYER_HEART_CONTAINERS = 18
+--- As the player continues to move in a direction, they will accelerate. When going from one wall to
+-- another in a 2x2 room at 2.0 speed (the maximum that the speed stat can rise to), the amount of
+-- units moved per update frame will climb to around 9.797 as they hit the opposite wall. The
+-- constant specifies a value of 9.8 to be safe.
 ____exports.MAX_PLAYER_SPEED_IN_UNITS = 9.8
 ____exports.MAX_PLAYER_TRINKET_SLOTS = getEnumLength(nil, TrinketSlot)
 ____exports.FIRST_ROOM_TYPE = RoomType.DEFAULT
 ____exports.LAST_ROOM_TYPE = getLastEnumValue(nil, RoomType)
+--- The maximum speed stat that a player can have. Any additional speed beyond this will not take
+-- effect.
 ____exports.MAX_SPEED_STAT = 2
 ____exports.FIRST_STAGE = LevelStage.BASEMENT_1
 ____exports.LAST_STAGE = getLastEnumValue(nil, LevelStage)
+--- Corresponds to the maximum value for `EntityPlayer.SamsonBerserkCharge`.
 ____exports.MAX_TAINTED_SAMSON_BERSERK_CHARGE = 100000
 ____exports.NUM_DIMENSIONS = getEnumLength(nil, Dimension) - 1
 ____exports.SECOND_IN_MILLISECONDS = 1000
 ____exports.MINUTE_IN_MILLISECONDS = 60 * ____exports.SECOND_IN_MILLISECONDS
 ____exports.ONE_BY_ONE_ROOM_GRID_SIZE = 135
+--- After taking damage, `EntityPlayer.SamsonBerserkCharge` is incremented by this amount.
 ____exports.TAINTED_SAMSON_BERSERK_CHARGE_FROM_TAKING_DAMAGE = 10000
+--- This is the number of draw coordinates that each heart spans on the UI in the upper left hand
+-- corner.
 ____exports.UI_HEART_WIDTH = 12
+--- This is a safer version of the `Vector.One` constant. (Other mods can mutate this `Vector.One`,
+-- so it is not safe to use.)
 ____exports.VectorOne = Vector(1, 1)
+--- This is a safer version of the `Vector.Zero` constant. (Other mods can mutate `Vector.Zero`
+-- vector, so it is not safe to use.)
 ____exports.VectorZero = Vector(0, 0)
 return ____exports

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"