isaacscript-common 2.3.2 → 3.0.0

package/functions/trinketCacheFlag.lua

@@ -25,6 +25,7 @@ function initCacheFlagMap(self)
         CACHE_FLAG_TO_TRINKETS_MAP:set(cacheFlag, trinketsSet)
     end
 end
+--- Returns a set containing every trinket type with the given cache flag, including modded trinkets.
 function ____exports.getTrinketsForCacheFlag(self, cacheFlag)
     if CACHE_FLAG_TO_TRINKETS_MAP.size == 0 then
         initCacheFlagMap(nil)
@@ -36,6 +37,8 @@ function ____exports.getTrinketsForCacheFlag(self, cacheFlag)
     return copySet(nil, trinketsSet)
 end
 CACHE_FLAG_TO_TRINKETS_MAP = __TS__New(Map)
+--- Returns a map containing every trinket type that the player has that matches the provided
+-- CacheFlag. The values of the map correspond to the multiplier for that trinket.
 function ____exports.getPlayerTrinketsForCacheFlag(self, player, cacheFlag)
     local trinketsForCacheFlag = ____exports.getTrinketsForCacheFlag(nil, cacheFlag)
     local playerTrinkets = __TS__New(Map)

package/functions/trinketGive.lua

@@ -9,6 +9,11 @@ local ____trinkets = require("functions.trinkets")
 local getGoldenTrinketType = ____trinkets.getGoldenTrinketType
 local ____utils = require("functions.utils")
 local ____repeat = ____utils["repeat"]
+--- Helper function to temporarily removes a player's held trinkets, if any. This will not remove any
+-- smelted trinkets. Use this in combination with the `giveTrinketsBack` function to take away and
+-- give back trinkets on the same frame.
+-- 
+-- @returns Undefined if the player does not have any trinkets, or TrinketSituation if they do.
 function ____exports.temporarilyRemoveTrinkets(self, player)
     local trinketType1 = player:GetTrinket(TrinketSlot.SLOT_1)
     local trinketType2 = player:GetTrinket(TrinketSlot.SLOT_2)
@@ -23,6 +28,9 @@ function ____exports.temporarilyRemoveTrinkets(self, player)
     end
     return {trinketTypeRemoved = TrinketType.NULL, trinketType1 = trinketType1, trinketType2 = trinketType2, numSmeltedTrinkets = 0}
 end
+--- Helper function to restore the player's trinkets back to the way they were before the
+-- `temporarilyRemoveTrinket` function was used. It will re-smelt any smelted trinkets that were
+-- removed.
 function ____exports.giveTrinketsBack(self, player, trinketSituation)
     if trinketSituation == nil then
         return
@@ -50,6 +58,14 @@ function ____exports.giveTrinketsBack(self, player, trinketSituation)
         player:AddTrinket(trinketSituation.trinketType2, false)
     end
 end
+--- Helper function to smelt a trinket. Before smelting, this function will automatically remove the
+-- trinkets that the player is holding, if any, and then give them back after the new trinket is
+-- smelted.
+-- 
+-- @param player The player to smelt the trinkets to.
+-- @param trinketType The trinket type to smelt.
+-- @param numTrinkets Optional. If specified, will smelt the given number of trinkets. Use this to
+-- avoid calling this function multiple times. Default is 1.
 function ____exports.smeltTrinket(self, player, trinketType, numTrinkets)
     if numTrinkets == nil then
         numTrinkets = 1
@@ -65,6 +81,14 @@ function ____exports.smeltTrinket(self, player, trinketType, numTrinkets)
     )
     ____exports.giveTrinketsBack(nil, player, trinketSituation)
 end
+--- Helper function to temporarily remove a specific kind of trinket from the player. Use this in
+-- combination with the `giveTrinketsBack` function to take away and give back a trinket on the same
+-- frame. This function correctly handles multiple trinket slots and ensures that all copies of the
+-- trinket are removed, including smelted trinkets.
+-- 
+-- Note that one smelted golden trinket is the same as two smelted normal trinkets.
+-- 
+-- @returns Undefined if the player does not have the trinket, or TrinketSituation if they do.
 function ____exports.temporarilyRemoveTrinket(self, player, trinketType)
     if not player:HasTrinket(trinketType) then
         return nil

package/functions/trinkets.lua

@@ -28,17 +28,41 @@ local ____sprite = require("functions.sprite")
 local clearSprite = ____sprite.clearSprite
 local ____utils = require("functions.utils")
 local irange = ____utils.irange
+--- Add this to a `TrinketType` to get the corresponding golden trinket type.
+-- 
+-- Corresponds to the vanilla `PillColor.TRINKET_GOLDEN_FLAG` value.
+-- 
+-- 1 << 15
 local GOLDEN_TRINKET_ADJUSTMENT = 32768
 local TRINKET_SPRITE_LAYER = 0
+--- Helper function to get the corresponding golden trinket type from a normal trinket type.
+-- 
+-- For example, passing `TrinketType.SWALLOWED_PENNY` would result in 32769, which is the value that
+-- corresponds to the golden trinket sub-type for Swallowed Penny.
 function ____exports.getGoldenTrinketType(self, trinketType)
     return trinketType + GOLDEN_TRINKET_ADJUSTMENT
 end
+--- Helper function to get an array that represents every modded trinket type.
+-- 
+-- Returns an empty array if there are no modded trinket types.
 function ____exports.getModdedTrinketTypes(self)
     if LAST_VANILLA_TRINKET_TYPE == LAST_TRINKET_TYPE then
         return {}
     end
     return irange(nil, FIRST_MODDED_TRINKET_TYPE, LAST_TRINKET_TYPE)
 end
+--- Returns the slot number corresponding to where a trinket can be safely inserted.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const player = Isaac.GetPlayer();
+-- const trinketSlot = getOpenTrinketSlotNum(player);
+-- if (trinketSlot !== undefined) {
+--   // They have one or more open trinket slots
+--   player.AddTrinket(TrinketType.SWALLOWED_PENNY);
+-- }
+-- ```
 function ____exports.getOpenTrinketSlot(self, player)
     local maxTrinkets = player:GetMaxTrinkets()
     local trinketType1 = player:GetTrinket(TrinketSlot.SLOT_1)
@@ -54,6 +78,8 @@ function ____exports.getOpenTrinketSlot(self, player)
     end
     return error("The player has an unknown number of trinket slots: " .. tostring(maxTrinkets))
 end
+--- Helper function to get the in-game description for a trinket. Returns "Unknown" if the provided
+-- trinket type was not valid.
 function ____exports.getTrinketDescription(self, trinketType)
     local trinketDescription = TRINKET_DESCRIPTION_MAP:get(trinketType)
     if trinketDescription ~= nil then
@@ -65,6 +91,15 @@ function ____exports.getTrinketDescription(self, trinketType)
     end
     return DEFAULT_TRINKET_DESCRIPTION
 end
+--- Helper function to get the name of a trinket. Returns "Unknown" if the provided trinket type is
+-- not valid.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const trinketType = TrinketType.SWALLOWED_PENNY;
+-- const trinketName = getTrinketName(trinketType); // trinketName is "Swallowed Penny"
+-- ```
 function ____exports.getTrinketName(self, trinketType)
     local trinketName = TRINKET_NAME_MAP:get(trinketType)
     if trinketName ~= nil then
@@ -76,12 +111,19 @@ function ____exports.getTrinketName(self, trinketType)
     end
     return DEFAULT_TRINKET_NAME
 end
+--- Helper function to get an array that contains every trinket type.
 function ____exports.getTrinketTypes(self)
     return irange(nil, FIRST_TRINKET_TYPE, LAST_TRINKET_TYPE)
 end
+--- Helper function to get an array that represents every vanilla trinket type.
 function ____exports.getVanillaTrinketTypes(self)
     return irange(nil, FIRST_TRINKET_TYPE, LAST_VANILLA_TRINKET_TYPE)
 end
+--- Returns whether or not the player can hold an additional trinket, beyond what they are currently
+-- carrying. This takes into account items that modify the max number of trinkets, like Mom's Purse.
+-- 
+-- If the player is the Tainted Soul, this always returns false, since that character cannot pick up
+-- items. (Only Tainted Forgotten can pick up items.)
 function ____exports.hasOpenTrinketSlot(self, player)
     if isCharacter(nil, player, PlayerType.THE_SOUL_B) then
         return false
@@ -92,6 +134,16 @@ end
 function ____exports.isGoldenTrinket(self, trinketType)
     return trinketType > GOLDEN_TRINKET_ADJUSTMENT
 end
+--- Helper function to change the sprite of a trinket entity.
+-- 
+-- For more information about removing the trinket sprite, see the documentation for the
+-- "clearSprite" helper function.
+-- 
+-- @param trinket The trinket whose sprite you want to modify.
+-- @param pngPath Equal to either the spritesheet path to load (e.g.
+-- "gfx/items/trinkets/trinket_001_swallowedpenny.png") or undefined. If undefined,
+-- the sprite will be removed, making it appear like the collectible has already been
+-- taken by the player.
 function ____exports.setTrinketSprite(self, trinket, pngPath)
     if not isTrinket(nil, trinket) then
         local entityID = getEntityID(nil, trinket)

package/functions/tstlClass.lua

@@ -9,6 +9,8 @@ local ____exports = {}
 local newTSTLClassFromMetatable
 local ____DefaultMap = require("classes.DefaultMap")
 local DefaultMap = ____DefaultMap.DefaultMap
+--- Returns whether or not this is a class that is provided as part of the TypeScriptToLua
+-- transpiler, such as a `Map` or a `Set`.
 function ____exports.isVanillaTSTLClass(self, object)
     return __TS__InstanceOf(object, Map) or __TS__InstanceOf(object, Set) or __TS__InstanceOf(object, WeakMap) or __TS__InstanceOf(object, WeakSet)
 end
@@ -19,9 +21,12 @@ function newTSTLClassFromMetatable(self, metatable)
     return newClass
 end
 local TSTL_CLASS_METATABLE_KEYS = __TS__New(Set, {"____constructor", "__index", "constructor"})
+--- Returns whether or not this is a class that is provided by the `isaacscript-common` library, such
+-- as a `DefaultMap`.
 function ____exports.isIsaacScriptCommonClass(self, object)
     return __TS__InstanceOf(object, DefaultMap)
 end
+--- TypeScriptToLua classes are Lua tables that have a metatable with a certain amount of keys.
 function ____exports.isUserDefinedTSTLClass(self, object)
     if ____exports.isVanillaTSTLClass(nil, object) or ____exports.isIsaacScriptCommonClass(nil, object) then
         return false
@@ -46,6 +51,10 @@ function ____exports.isUserDefinedTSTLClass(self, object)
     end
     return numKeys == TSTL_CLASS_METATABLE_KEYS.size
 end
+--- Initializes a new TypeScriptToLua class in the situation where you do not know what kind of class
+-- it is. This function requires that you provide an instantiated class of the same type, as it will
+-- use the class constructor that is present on the other object's metatable to initialize the new
+-- class.
 function ____exports.newTSTLClass(self, oldClass)
     local metatable = getmetatable(oldClass)
     if metatable == nil then

package/functions/ui.lua

@@ -14,6 +14,14 @@ function ____exports.getScreenBottomRightPos(self)
     local screenHeight = Isaac.GetScreenHeight()
     return Vector(screenWidth, screenHeight)
 end
+--- In the options menu, players have the ability to set a HUD offset. However, mods do not have
+-- access to this value. To get around this, Mod Config Menu provides a separate HUD offset setting
+-- on the first page of the menu. This is intended to be set by end-users to match their vanilla HUD
+-- offset setting so that mods can render UI elements to the screen in the correct position.
+-- 
+-- @returns If the user does not have Mod Config Menu enabled, or does not have this option set,
+-- then this function will return `Vector.Zero.` Otherwise, it will return a Vector that
+-- represents a HUD offset that should be added to the position of a UI element.
 function ____exports.getHUDOffsetVector(self)
     local defaultVector = copyVector(nil, VectorZero)
     local hudOffset = math.floor(Options.HUDOffset * 10)
@@ -30,6 +38,8 @@ function ____exports.getHUDOffsetVector(self)
     end
     return Vector(x, y)
 end
+--- Returns how many hearts are in the heart UI row. If the player has more than 6 hearts, this
+-- function will return 6.
 function ____exports.getHeartRowLength(self, player)
     local maxHearts = player:GetMaxHearts()
     local soulHearts = player:GetSoulHearts()
@@ -38,6 +48,9 @@ function ____exports.getHeartRowLength(self, player)
     local heartRowLength = combinedHearts / 2
     return math.min(heartRowLength, 6)
 end
+--- Helper function to get the width of the first player's hearts on the UI. This is useful for
+-- drawing UI elements to the right of where the player's hearts are. Make sure to use this in
+-- combination with the the `getHUDOffsetVector` helper function.
 function ____exports.getHeartsUIWidth(self)
     local level = game:GetLevel()
     local curses = level:GetCurses()
@@ -81,6 +94,9 @@ function ____exports.getScreenTopRightPos(self)
     local bottomRight = ____exports.getScreenBottomRightPos(nil)
     return Vector(bottomRight.X, 0)
 end
+--- Get how many hearts are currently being shown on the hearts UI.
+-- 
+-- This function is originally from piber20 Helper.
 function ____exports.getVisibleHearts(self, player)
     local effectiveMaxHearts = player:GetEffectiveMaxHearts()
     local soulHearts = player:GetSoulHearts()

package/functions/utils.d.ts

@@ -65,6 +65,7 @@ export declare function hexToKColor(hexString: string, alpha: float): KColor;
  * If only one argument is specified, then it will assume that the start is 0.
  */
 export declare function irange(start: int, end?: int): int[];
+export declare function isPrimitive(variable: unknown): boolean;
 /**
  * Since this is a UI element, we do not want to draw it in water reflections. `renderOffset` will
  * be a non-zero value in reflections.

package/functions/utils.lua

@@ -1,13 +1,54 @@
 local ____lualib = require("lualib_bundle")
 local __TS__StringReplace = ____lualib.__TS__StringReplace
 local __TS__StringSubstr = ____lualib.__TS__StringSubstr
+local __TS__TypeOf = ____lualib.__TS__TypeOf
 local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local RenderMode = ____isaac_2Dtypescript_2Ddefinitions.RenderMode
 local ____cachedClasses = require("cachedClasses")
 local game = ____cachedClasses.game
 local HEX_STRING_LENGTH = 6
+--- Helper function to get type safety on a switch statement.
+-- 
+-- Very useful to be future-safe against people adding values to a type or an enum.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- enum Situation {
+--   ONE,
+--   TWO,
+--   THREE,
+--   // FOUR, // If we uncomment this line, the program will no longer compile
+-- }
+-- 
+-- function handleSituation(situation: Situation) {
+--   switch (situation) {
+--     case Situation.ONE: {
+--       return 41;
+--     }
+-- 
+--     case Situation.TWO: {
+--       return 68;
+--     }
+-- 
+--     case Situation.THREE: {
+--       return 12;
+--     }
+-- 
+--     default: {
+--       return ensureAllCases(situation);
+--     }
+--   }
+-- }
+-- ```
 ____exports.ensureAllCases = function(____, obj) return obj end
+--- Helper function to return an array with the elements from start to end. It is inclusive at the
+-- start and exclusive at the end. (The "e" stands for exclusive.)
+-- 
+-- For example, `erange(1, 3)` will return `[1, 2]`.
+-- 
+-- If only one argument is specified, then it will assume that the start is 0.
 function ____exports.erange(self, start, ____end)
     if ____end == nil then
         ____end = start
@@ -23,6 +64,8 @@ function ____exports.erange(self, start, ____end)
     end
     return array
 end
+--- Helper function to log what is happening in functions that recursively move through nested data
+-- structures.
 function ____exports.getTraversalDescription(self, key, traversalDescription)
     if traversalDescription ~= "" then
         traversalDescription = traversalDescription .. " --> "
@@ -30,6 +73,9 @@ function ____exports.getTraversalDescription(self, key, traversalDescription)
     traversalDescription = traversalDescription .. tostring(key)
     return traversalDescription
 end
+--- Converts a hex string like "#33aa33" to a KColor object.
+-- 
+-- @param hexString A hex string like "#ffffff" or "ffffff". (The "#" character is optional.)
 function ____exports.hexToKColor(self, hexString, alpha)
     hexString = __TS__StringReplace(hexString, "#", "")
     if #hexString ~= HEX_STRING_LENGTH then
@@ -53,6 +99,12 @@ function ____exports.hexToKColor(self, hexString, alpha)
     local base = 255
     return KColor(R / base, G / base, B / base, alpha)
 end
+--- Helper function to return an array with the elements from start to end, inclusive. (The "i"
+-- stands for inclusive.)
+-- 
+-- For example, `irange(1, 3)` will return `[1, 2, 3]`.
+-- 
+-- If only one argument is specified, then it will assume that the start is 0.
 function ____exports.irange(self, start, ____end)
     if ____end == nil then
         ____end = start
@@ -68,18 +120,46 @@ function ____exports.irange(self, start, ____end)
     end
     return array
 end
+function ____exports.isPrimitive(self, variable)
+    local ____type = __TS__TypeOf(variable)
+    return ____type == "boolean" or ____type == "number" or ____type == "string"
+end
+--- Since this is a UI element, we do not want to draw it in water reflections. `renderOffset` will
+-- be a non-zero value in reflections.
 function ____exports.isReflectionRender(self)
     local room = game:GetRoom()
     local renderMode = room:GetRenderMode()
     return renderMode == RenderMode.WATER_REFLECT
 end
+--- Helper function to print something to the in-game console. Use this instead of invoking the
+-- `Isaac.ConsoleOutput` method directly because it will automatically insert a newline at the end
+-- of the message (which `Isaac.ConsoleOutput` does not do by default).
 function ____exports.printConsole(self, msg)
     Isaac.ConsoleOutput(msg .. "\n")
 end
+--- Helper function to print whether something was enabled or disabled to the in-game console.
 function ____exports.printEnabled(self, enabled, description)
     local enabledText = enabled and "Enabled" or "Disabled"
     ____exports.printConsole(nil, ((enabledText .. " ") .. description) .. ".")
 end
+--- Helper function to repeat code N times. This is faster to type and cleaner than using a for loop.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const player = Isaac.GetPlayer();
+-- repeat(10, () => {
+--   player.AddCollectible(CollectibleType.STEVEN);
+-- });
+-- ```
+-- 
+-- The repeated function is passed the index of the iteration, if needed:
+-- 
+-- ```ts
+-- repeat(3, (i) => {
+--   print(i); // Prints "0", "1", "2"
+-- });
+-- ```
 ____exports["repeat"] = function(self, n, func)
     do
         local i = 0
@@ -89,6 +169,14 @@ ____exports["repeat"] = function(self, n, func)
         end
     end
 end
+--- Helper function to signify that the enclosing code block is not yet complete. Using this function
+-- is similar to writing a "TODO" comment, but it has the benefit of preventing ESLint errors due to
+-- early returns.
+-- 
+-- When you see this function, it simply means that the programmer intends to add in more code to
+-- this spot later.
+-- 
+-- This function does not actually do anything. (It is an "empty" function.)
 function ____exports.todo(self)
 end
 return ____exports

package/functions/vector.lua

@@ -15,11 +15,17 @@ local getNumbersFromTable = ____table.getNumbersFromTable
 local tableHasKeys = ____table.tableHasKeys
 local ____utils = require("functions.utils")
 local ensureAllCases = ____utils.ensureAllCases
+--- Helper function to check if something is an instantiated Vector object.
 function ____exports.isVector(self, object)
     return isIsaacAPIClassOfType(nil, object, OBJECT_NAME)
 end
 local KEYS = {"X", "Y"}
 OBJECT_NAME = "Vector"
+--- Helper function to copy a `Vector` object.
+-- 
+-- @param vector The vector to copy. In the case of deserialization, this will actually be a Lua
+-- table instead of an instantiated Vector class.
+-- @param serializationType Default is `SerializationType.NONE`.
 function ____exports.copyVector(self, vector, serializationType)
     if serializationType == nil then
         serializationType = SerializationType.NONE
@@ -76,6 +82,8 @@ function ____exports.copyVector(self, vector, serializationType)
         end
     until true
 end
+--- Used to determine is the given table is a serialized `Vector` object created by the save data
+-- manager and/or the `deepCopy` function.
 function ____exports.isSerializedVector(self, object)
     local objectType = type(object)
     if objectType ~= "table" then
@@ -91,6 +99,7 @@ end
 function ____exports.vectorEquals(self, vector1, vector2)
     return isaacAPIClassEquals(nil, vector1, vector2, KEYS)
 end
+--- Helper function for finding out which way a vector is pointing.
 function ____exports.vectorToDirection(self, vector)
     local degrees = vector:GetAngleDegrees()
     if degrees > -45 and degrees < 45 then

package/lualib_bundle.lua

@@ -753,7 +753,7 @@ local function __TS__AsyncAwaiter(generator)
     return __TS__New(
         __TS__Promise,
         function(____, resolve, reject)
-            local adopt, fulfilled, rejected, step, asyncCoroutine
+            local adopt, fulfilled, step, resolved, asyncCoroutine
             function adopt(self, value)
                 local ____temp_0
                 if __TS__InstanceOf(value, __TS__Promise) then
@@ -764,57 +764,44 @@ local function __TS__AsyncAwaiter(generator)
                 return ____temp_0
             end
             function fulfilled(self, value)
-                local success, errorOrErrorHandler, resultOrError = coroutine.resume(asyncCoroutine, value)
+                local success, resultOrError = coroutine.resume(asyncCoroutine, value)
                 if success then
-                    step(nil, resultOrError, errorOrErrorHandler)
+                    step(nil, resultOrError)
                 else
-                    reject(nil, errorOrErrorHandler)
+                    reject(nil, resultOrError)
                 end
             end
-            function rejected(self, handler)
-                if handler then
-                    return function(____, value)
-                        local success, hasReturnedOrError, returnedValue = pcall(handler, value)
-                        if success then
-                            if hasReturnedOrError then
-                                resolve(nil, returnedValue)
-                            else
-                                step(nil, hasReturnedOrError, handler)
-                            end
-                        else
-                            reject(nil, hasReturnedOrError)
-                        end
-                    end
-                else
-                    return function(____, value)
-                        reject(nil, value)
-                    end
+            function step(self, result)
+                if resolved then
+                    return
                 end
-            end
-            function step(self, result, errorHandler)
                 if coroutine.status(asyncCoroutine) == "dead" then
                     resolve(nil, result)
                 else
                     local ____self_1 = adopt(nil, result)
-                    ____self_1["then"](
-                        ____self_1,
-                        fulfilled,
-                        rejected(nil, errorHandler)
-                    )
+                    ____self_1["then"](____self_1, fulfilled, reject)
                 end
             end
+            resolved = false
             asyncCoroutine = coroutine.create(generator)
-            local success, errorOrErrorHandler, resultOrError = coroutine.resume(asyncCoroutine)
+            local success, resultOrError = coroutine.resume(
+                asyncCoroutine,
+                function(____, v)
+                    resolved = true
+                    local ____self_2 = adopt(nil, v)
+                    ____self_2["then"](____self_2, resolve, reject)
+                end
+            )
             if success then
-                step(nil, resultOrError, errorOrErrorHandler)
+                step(nil, resultOrError)
             else
-                reject(nil, errorOrErrorHandler)
+                reject(nil, resultOrError)
             end
         end
     )
 end
-local function __TS__Await(errorHandler, thing)
-    return coroutine.yield(errorHandler, thing)
+local function __TS__Await(thing)
+    return coroutine.yield(thing)
 end
 
 local function __TS__ClassExtends(target, base)

package/maps/cardMap.lua

@@ -4,6 +4,7 @@ local __TS__New = ____lualib.__TS__New
 local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local Card = ____isaac_2Dtypescript_2Ddefinitions.Card
+--- Maps card names to card sub-types.
 ____exports.CARD_MAP = __TS__New(Map, {
     {"fool", Card.FOOL},
     {"magician", Card.MAGICIAN},

package/maps/characterMap.lua

@@ -2,6 +2,7 @@ local ____lualib = require("lualib_bundle")
 local Map = ____lualib.Map
 local __TS__New = ____lualib.__TS__New
 local ____exports = {}
+--- Maps character names to character sub-types.
 ____exports.CHARACTER_MAP = __TS__New(Map, {
     {"isaac", 0},
     {"magdalene", 1},

package/maps/defaultPlayerStatMap.lua

@@ -7,6 +7,7 @@ local CacheFlag = ____isaac_2Dtypescript_2Ddefinitions.CacheFlag
 local ____tears = require("functions.tears")
 local getTearsStat = ____tears.getTearsStat
 local DEFAULT_MAX_FIRE_DELAY = 10
+--- The default fire delay is represented in the tear stat, not the `MaxFireDelay` value.
 ____exports.DEFAULT_PLAYER_STAT_MAP = __TS__New(
     Map,
     {

package/maps/gridEntityXMLMap.lua

@@ -12,6 +12,8 @@ local PressurePlateVariant = ____isaac_2Dtypescript_2Ddefinitions.PressurePlateV
 local RockVariant = ____isaac_2Dtypescript_2Ddefinitions.RockVariant
 local StatueVariant = ____isaac_2Dtypescript_2Ddefinitions.StatueVariant
 local TrapdoorVariant = ____isaac_2Dtypescript_2Ddefinitions.TrapdoorVariant
+--- This maps the GridEntityXMLType (i.e. the type contained in the room XML/STB file) to the
+-- GridEntityType and the variant used by the game.
 ____exports.GRID_ENTITY_XML_MAP = __TS__New(Map, {
     {GridEntityXMLType.ROCK, {GridEntityType.ROCK, RockVariant.NORMAL}},
     {GridEntityXMLType.ROCK_BOMB, {GridEntityType.ROCK_BOMB, 0}},

package/maps/pillEffectMap.lua

@@ -4,6 +4,7 @@ local __TS__New = ____lualib.__TS__New
 local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local PillEffect = ____isaac_2Dtypescript_2Ddefinitions.PillEffect
+--- Maps pill effect names to the values of the `PillEffect` enum.
 ____exports.PILL_EFFECT_MAP = __TS__New(Map, {
     {"badGas", PillEffect.BAD_GAS},
     {"gas", PillEffect.BAD_GAS},

package/maps/roomShapeToTopLeftWallGridIndexMap.lua

@@ -5,6 +5,8 @@ local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local RoomShape = ____isaac_2Dtypescript_2Ddefinitions.RoomShape
 ____exports.DEFAULT_TOP_LEFT_WALL_GRID_INDEX = 0
+--- Only used for special room shapes where the top left wall grid index is not equal to
+-- `DEFAULT_TOP_LEFT_WALL_GRID_INDEX`.
 ____exports.ROOM_SHAPE_TO_TOP_LEFT_WALL_GRID_INDEX_MAP = __TS__New(Map, {
     {RoomShape.IH, 30},
     {RoomShape.IV, 4},

package/maps/roomTypeMap.lua

@@ -4,6 +4,7 @@ local __TS__New = ____lualib.__TS__New
 local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local RoomType = ____isaac_2Dtypescript_2Ddefinitions.RoomType
+--- Maps room type names to room types.
 ____exports.ROOM_TYPE_MAP = __TS__New(Map, {
     {"null", RoomType.NULL},
     {"default", RoomType.DEFAULT},

package/objects/LRoomShapeToRectangles.lua

@@ -4,6 +4,8 @@ local RoomShape = ____isaac_2Dtypescript_2Ddefinitions.RoomShape
 local ____constants = require("constants")
 local VectorZero = ____constants.VectorZero
 local TWO_BY_TWO_BOTTOM_RIGHT = Vector(25, 13)
+--- "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)".)
 ____exports.L_ROOM_SHAPE_TO_RECTANGLES = {
     [RoomShape.LTL] = {
         Vector(13, 0),

package/objects/colors.lua

@@ -1,4 +1,8 @@
 local ____exports = {}
+--- A collection of common colors that can be reused.
+-- 
+-- Note that if you want to further modify these colors, you should copy them first with the
+-- `copyColor` function.
 ____exports.COLORS = {
     Black = Color(1, 1, 1),
     Red = Color(1, 0, 0),

package/objects/roomShapeBounds.lua

@@ -7,6 +7,8 @@ local NARROW_CONTENTS_WIDTH = ____roomShapeVolumes.NARROW_CONTENTS_WIDTH
 local ONE_BY_ONE_CONTENTS_HEIGHT = ____roomShapeVolumes.ONE_BY_ONE_CONTENTS_HEIGHT
 local ONE_BY_ONE_CONTENTS_WIDTH = ____roomShapeVolumes.ONE_BY_ONE_CONTENTS_WIDTH
 local TWO_BY_TWO_BOUNDS = Vector(ONE_BY_ONE_CONTENTS_WIDTH * 2, ONE_BY_ONE_CONTENTS_HEIGHT * 2)
+--- The size of a room shape's contents. This does not include the tiles that the walls are on. L
+-- rooms use the same bounds as a 2x2 room.
 ____exports.ROOM_SHAPE_BOUNDS = {
     [RoomShape.SHAPE_1x1] = Vector(ONE_BY_ONE_CONTENTS_WIDTH, ONE_BY_ONE_CONTENTS_HEIGHT),
     [RoomShape.IH] = Vector(ONE_BY_ONE_CONTENTS_WIDTH, NARROW_CONTENTS_HEIGHT),

package/objects/roomShapeLayoutSizes.lua

@@ -8,6 +8,10 @@ local ONE_BY_ONE_LAYOUT_SIZE = Vector(ONE_BY_ONE_CONTENTS_WIDTH, ONE_BY_ONE_CONT
 local TWO_BY_ONE_VERTICAL_LAYOUT_SIZE = Vector(ONE_BY_ONE_CONTENTS_WIDTH, ONE_BY_ONE_CONTENTS_HEIGHT * 2)
 local TWO_BY_ONE_HORIZONTAL_LAYOUT_SIZE = Vector(ONE_BY_ONE_CONTENTS_WIDTH * 2, ONE_BY_ONE_CONTENTS_HEIGHT)
 local TWO_BY_TWO_LAYOUT_SIZE = Vector(ONE_BY_ONE_CONTENTS_WIDTH * 2, ONE_BY_ONE_CONTENTS_HEIGHT * 2)
+--- The dimensions of a room shape's layout. This is NOT the size of the room's actual contents! For
+-- that, use `ROOM_SHAPE_BOUNDS`.
+-- 
+-- For example, a horizontal narrow room has a layout size of equal to that of a 1x1 room.
 ____exports.ROOM_SHAPE_LAYOUT_SIZES = {
     [RoomShape.SHAPE_1x1] = ONE_BY_ONE_LAYOUT_SIZE,
     [RoomShape.IH] = ONE_BY_ONE_LAYOUT_SIZE,

package/objects/roomShapeToBottomRightPosition.lua

@@ -3,6 +3,8 @@ local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitio
 local RoomShape = ____isaac_2Dtypescript_2Ddefinitions.RoomShape
 local TWO_BY_TWO_BOTTOM_RIGHT_POSITION = Vector(25, 13)
 local ONE_BY_TWO_VERTICAL_BOTTOM_RIGHT_POSITION = Vector(12, 13)
+--- "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)".)
 ____exports.ROOM_SHAPE_TO_BOTTOM_RIGHT_POSITION = {
     [RoomShape.SHAPE_1x1] = Vector(12, 6),
     [RoomShape.IH] = Vector(12, 4),

package/objects/roomShapeToDoorSlotsToGridIndexDelta.lua

@@ -11,6 +11,8 @@ local LEFT = -1
 local UP = -LEVEL_GRID_ROW_WIDTH
 local RIGHT = 1
 local DOWN = LEVEL_GRID_ROW_WIDTH
+--- Deltas are considered to be from the safe grid index of the room (i.e. the top left corner, or
+-- top right corner in the case of `RoomShape.LTL`).
 ____exports.ROOM_SHAPE_TO_DOOR_SLOTS_TO_GRID_INDEX_DELTA = {
     [RoomShape.SHAPE_1x1] = __TS__New(Map, {{DoorSlot.LEFT_0, LEFT}, {DoorSlot.UP_0, UP}, {DoorSlot.RIGHT_0, RIGHT}, {DoorSlot.DOWN_0, DOWN}}),
     [RoomShape.IH] = __TS__New(Map, {{DoorSlot.LEFT_0, LEFT}, {DoorSlot.RIGHT_0, RIGHT}}),