isaacscript-common 2.3.2 → 3.1.1

package/functions/entitySpecific.lua

@@ -8,6 +8,16 @@ local getEntities = ____entity.getEntities
 local getFilteredNewEntities = ____entity.getFilteredNewEntities
 local removeEntities = ____entity.removeEntities
 local spawn = ____entity.spawn
+--- Helper function to get all of the `EntityType.BOMB` in the room.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- // Make all of the bombs in the room invisible
+-- for (const bomb of getBombs()) {
+--   bomb.Visible = false;
+-- }
+-- ```
 function ____exports.getBombs(self, bombVariant, subType)
     if bombVariant == nil then
         bombVariant = -1
@@ -25,6 +35,16 @@ function ____exports.getBombs(self, bombVariant, subType)
     end
     return bombs
 end
+--- Helper function to get all of the `EntityType.EFFECT` in the room.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- // Make all of the effects in the room invisible
+-- for (const effect of getEffects()) {
+--   effect.Visible = false;
+-- }
+-- ```
 function ____exports.getEffects(self, effectVariant, subType)
     if effectVariant == nil then
         effectVariant = -1
@@ -42,6 +62,16 @@ function ____exports.getEffects(self, effectVariant, subType)
     end
     return effects
 end
+--- Helper function to get all of the familiars in the room.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- // Make all of the familiars in the room invisible
+-- for (const familiar of getFamiliars()) {
+--   familiar.Visible = false;
+-- }
+-- ```
 function ____exports.getFamiliars(self, familiarVariant, subType)
     if familiarVariant == nil then
         familiarVariant = -1
@@ -59,6 +89,16 @@ function ____exports.getFamiliars(self, familiarVariant, subType)
     end
     return familiars
 end
+--- Helper function to get all of the `EntityType.KNIFE` in the room.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- // Make all of the knives in the room invisible
+-- for (const knife of getKnives()) {
+--   knife.Visible = false;
+-- }
+-- ```
 function ____exports.getKnives(self, knifeVariant, subType)
     if knifeVariant == nil then
         knifeVariant = -1
@@ -76,6 +116,16 @@ function ____exports.getKnives(self, knifeVariant, subType)
     end
     return knives
 end
+--- Helper function to get all of the `EntityType.LASER` in the room.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- // Make all of the lasers in the room invisible
+-- for (const laser of getLasers()) {
+--   laser.Visible = false;
+-- }
+-- ```
 function ____exports.getLasers(self, laserVariant, subType)
     if laserVariant == nil then
         laserVariant = -1
@@ -93,6 +143,7 @@ function ____exports.getLasers(self, laserVariant, subType)
     end
     return lasers
 end
+--- The same thing as the `getEntities` function, but returns only NPCs.
 function ____exports.getNPCs(self, entityType, variant, subType, ignoreFriendly)
     if ignoreFriendly == nil then
         ignoreFriendly = false
@@ -113,6 +164,16 @@ function ____exports.getNPCs(self, entityType, variant, subType, ignoreFriendly)
     end
     return npcs
 end
+--- Helper function to get all of the pickups in the room.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- // Make all of the pickups in the room invisible
+-- for (const pickup of getPickups()) {
+--   pickup.Visible = false;
+-- }
+-- ```
 function ____exports.getPickups(self, pickupVariant, subType)
     if pickupVariant == nil then
         pickupVariant = -1
@@ -130,6 +191,16 @@ function ____exports.getPickups(self, pickupVariant, subType)
     end
     return pickups
 end
+--- Helper function to get all of the `EntityType.PROJECTILE` in the room.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- // Make all of the projectiles in the room invisible
+-- for (const projectile of getProjectiles()) {
+--   projectile.Visible = false;
+-- }
+-- ```
 function ____exports.getProjectiles(self, projectileVariant, subType)
     if projectileVariant == nil then
         projectileVariant = -1
@@ -147,6 +218,16 @@ function ____exports.getProjectiles(self, projectileVariant, subType)
     end
     return projectiles
 end
+--- Helper function to get all of the `EntityType.SLOT` in the room.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- // Make all of the slots in the room invisible
+-- for (const slot of getSlots()) {
+--   slot.Visible = false;
+-- }
+-- ```
 function ____exports.getSlots(self, slotVariant, subType)
     if slotVariant == nil then
         slotVariant = -1
@@ -157,6 +238,16 @@ function ____exports.getSlots(self, slotVariant, subType)
     local slots = getEntities(nil, EntityType.SLOT, slotVariant, subType)
     return slots
 end
+--- Helper function to get all of the `EntityType.TEAR` in the room.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- // Make all of the tears in the room invisible
+-- for (const tear of getTears()) {
+--   tear.Visible = false;
+-- }
+-- ```
 function ____exports.getTears(self, tearVariant, subType)
     if tearVariant == nil then
         tearVariant = -1
@@ -174,6 +265,17 @@ function ____exports.getTears(self, tearVariant, subType)
     end
     return tears
 end
+--- The base game `EntityNPC.FireProjectiles` method does not return anything, which is a problem in
+-- situations where you need to work with the fired projectiles. This function invokes that method,
+-- and then returns the projectiles that were spawned.
+-- 
+-- @param npc The EntityNPC firing projectiles.
+-- @param position The starting position of the projectiles.
+-- @param velocity The starting velocity of the projectiles.
+-- @param projectilesMode A ProjectilesMode enum value defining how to fire the projectiles.
+-- @param projectileParams A ProjectileParams object containing various parameters for the
+-- projectiles.
+-- @returns An array of EntityProjectiles containing all fired projectiles.
 function ____exports.npcFireProjectiles(self, npc, position, velocity, projectilesMode, projectileParams)
     local oldEntities = ____exports.getProjectiles(nil)
     npc:FireProjectiles(position, velocity, projectilesMode, projectileParams)
@@ -181,46 +283,107 @@ function ____exports.npcFireProjectiles(self, npc, position, velocity, projectil
     local filteredNewEntities = getFilteredNewEntities(nil, oldEntities, newEntities)
     return filteredNewEntities
 end
+--- Helper function to remove all of the `EntityType.BOMB` in the room.
+-- 
+-- @param bombVariant Optional. If specified, will only remove bombs that match this variant.
+-- @param subType Optional. If specified, will only remove bombs that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of bombs.
+-- @returns An array of the bombs that were removed.
 function ____exports.removeAllBombs(self, bombVariant, subType, cap)
     local bombs = ____exports.getBombs(nil, bombVariant, subType)
     return removeEntities(nil, bombs, cap)
 end
+--- Helper function to remove all of the effects in the room.
+-- 
+-- @param effectVariant Optional. If specified, will only remove effects that match this variant.
+-- @param subType Optional. If specified, will only remove effects that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of effects.
+-- @returns An array of the effects that were removed.
 function ____exports.removeAllEffects(self, effectVariant, subType, cap)
     local effects = ____exports.getEffects(nil, effectVariant, subType)
     return removeEntities(nil, effects, cap)
 end
+--- Helper function to remove all of the familiars in the room.
+-- 
+-- @param familiarVariant Optional. If specified, will only remove familiars that match this
+-- variant.
+-- @param subType Optional. If specified, will only remove familiars that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of familiars.
+-- @returns An array of the familiars that were removed.
 function ____exports.removeAllFamiliars(self, familiarVariant, subType, cap)
     local familiars = ____exports.getFamiliars(nil, familiarVariant, subType)
     return removeEntities(nil, familiars, cap)
 end
+--- Helper function to remove all of the `EntityType.KNIFE` in the room.
+-- 
+-- @param knifeVariant Optional. If specified, will only remove knives that match this variant.
+-- @param subType Optional. If specified, will only remove knives that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of knives.
+-- @returns An array of the knives that were removed.
 function ____exports.removeAllKnives(self, knifeVariant, subType, cap)
     local knives = ____exports.getKnives(nil, knifeVariant, subType)
     return removeEntities(nil, knives, cap)
 end
+--- Helper function to remove all of the `EntityType.LASER` in the room.
+-- 
+-- @param laserVariant Optional. If specified, will only remove lasers that match this variant.
+-- @param subType Optional. If specified, will only remove lasers that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of lasers.
+-- @returns An array of the lasers that were removed.
 function ____exports.removeAllLasers(self, laserVariant, subType, cap)
     local lasers = ____exports.getLasers(nil, laserVariant, subType)
     return removeEntities(nil, lasers, cap)
 end
+--- Helper function to remove all NPCs in the room.
+-- 
+-- @param cap Optional. If specified, will only remove the given amount of NPCs.
+-- @returns An array of the NPCs that were removed.
 function ____exports.removeAllNPCs(self, cap)
     local npcs = ____exports.getNPCs(nil)
     return removeEntities(nil, npcs, cap)
 end
+--- Helper function to remove all of the pickups in the room.
+-- 
+-- @param pickupVariant Optional. If specified, will only remove pickups that match this variant.
+-- @param subType Optional. If specified, will only remove pickups that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of pickups.
+-- @returns An array of the pickups that were removed.
 function ____exports.removeAllPickups(self, pickupVariant, subType, cap)
     local pickups = ____exports.getPickups(nil, pickupVariant, subType)
     return removeEntities(nil, pickups, cap)
 end
+--- Helper function to remove all of the `EntityType.PROJECTILE` in the room.
+-- 
+-- @param projectileVariant Optional. If specified, will only remove projectiles that match this
+-- variant.
+-- @param subType Optional. If specified, will only remove projectiles that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of projectiles.
+-- @returns An array of the projectiles that were removed.
 function ____exports.removeAllProjectiles(self, projectileVariant, subType, cap)
     local projectiles = ____exports.getProjectiles(nil, projectileVariant, subType)
     return removeEntities(nil, projectiles, cap)
 end
+--- Helper function to remove all of the `EntityType.SLOT` in the room.
+-- 
+-- @param slotVariant Optional. If specified, will only remove slots that match this variant.
+-- @param subType Optional. If specified, will only remove slots that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of slots.
+-- @returns An array of the slots that were removed.
 function ____exports.removeAllSlots(self, slotVariant, subType, cap)
     local slots = ____exports.getSlots(nil, slotVariant, subType)
     return removeEntities(nil, slots, cap)
 end
+--- Helper function to remove all of the `EntityType.TEAR` in the room.
+-- 
+-- @param tearVariant Optional. If specified, will only remove tears that match this variant.
+-- @param subType Optional. If specified, will only remove tears that match this sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of tears.
+-- @returns An array of the tears that were removed.
 function ____exports.removeAllTears(self, tearVariant, subType, cap)
     local tears = ____exports.getTears(nil, tearVariant, subType)
     return removeEntities(nil, tears, cap)
 end
+--- Helper function to spawn a `EntityType.BOMB` (4).
 function ____exports.spawnBomb(self, bombVariant, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -247,6 +410,7 @@ function ____exports.spawnBomb(self, bombVariant, subType, position, velocity, s
     end
     return bomb
 end
+--- Helper function to spawn a `EntityType.BOMB` (4) with a specific seed.
 function ____exports.spawnBombWithSeed(self, bombVariant, subType, position, seed, velocity, spawner)
     if velocity == nil then
         velocity = VectorZero
@@ -264,6 +428,7 @@ function ____exports.spawnBombWithSeed(self, bombVariant, subType, position, see
         seed
     )
 end
+--- Helper function to spawn a `EntityType.EFFECT` (1000).
 function ____exports.spawnEffect(self, effectVariant, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -290,6 +455,7 @@ function ____exports.spawnEffect(self, effectVariant, subType, position, velocit
     end
     return effect
 end
+--- Helper function to spawn a `EntityType.EFFECT` (1000) with a specific seed.
 function ____exports.spawnEffectWithSeed(self, effectVariant, subType, position, seed, velocity, spawner)
     if velocity == nil then
         velocity = VectorZero
@@ -307,6 +473,7 @@ function ____exports.spawnEffectWithSeed(self, effectVariant, subType, position,
         seed
     )
 end
+--- Helper function to spawn a `EntityType.FAMILIAR` (3).
 function ____exports.spawnFamiliar(self, familiarVariant, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -333,6 +500,7 @@ function ____exports.spawnFamiliar(self, familiarVariant, subType, position, vel
     end
     return familiar
 end
+--- Helper function to spawn a `EntityType.FAMILIAR` (3) with a specific seed.
 function ____exports.spawnFamiliarWithSeed(self, familiarVariant, subType, position, seed, velocity, spawner)
     if velocity == nil then
         velocity = VectorZero
@@ -350,6 +518,7 @@ function ____exports.spawnFamiliarWithSeed(self, familiarVariant, subType, posit
         seed
     )
 end
+--- Helper function to spawn a `EntityType.KNIFE` (8).
 function ____exports.spawnKnife(self, knifeVariant, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -376,6 +545,7 @@ function ____exports.spawnKnife(self, knifeVariant, subType, position, velocity,
     end
     return knife
 end
+--- Helper function to spawn a `EntityType.KNIFE` (8) with a specific seed.
 function ____exports.spawnKnifeWithSeed(self, knifeVariant, subType, position, seed, velocity, spawner)
     if velocity == nil then
         velocity = VectorZero
@@ -393,6 +563,7 @@ function ____exports.spawnKnifeWithSeed(self, knifeVariant, subType, position, s
         seed
     )
 end
+--- Helper function to spawn a `EntityType.LASER` (7).
 function ____exports.spawnLaser(self, laserVariant, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -419,6 +590,7 @@ function ____exports.spawnLaser(self, laserVariant, subType, position, velocity,
     end
     return laser
 end
+--- Helper function to spawn a `EntityType.LASER` (7) with a specific seed.
 function ____exports.spawnLaserWithSeed(self, laserVariant, subType, position, seed, velocity, spawner)
     if velocity == nil then
         velocity = VectorZero
@@ -436,6 +608,7 @@ function ____exports.spawnLaserWithSeed(self, laserVariant, subType, position, s
         seed
     )
 end
+--- Helper function to spawn an NPC.
 function ____exports.spawnNPC(self, entityType, variant, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -462,6 +635,7 @@ function ____exports.spawnNPC(self, entityType, variant, subType, position, velo
     end
     return npc
 end
+--- Helper function to spawn an NPC with a specific seed.
 function ____exports.spawnNPCWithSeed(self, entityType, variant, subType, position, seed, velocity, spawner)
     if velocity == nil then
         velocity = VectorZero
@@ -480,6 +654,7 @@ function ____exports.spawnNPCWithSeed(self, entityType, variant, subType, positi
         seed
     )
 end
+--- Helper function to spawn a `EntityType.PICKUP` (5).
 function ____exports.spawnPickup(self, pickupVariant, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -506,6 +681,7 @@ function ____exports.spawnPickup(self, pickupVariant, subType, position, velocit
     end
     return pickup
 end
+--- Helper function to spawn a `EntityType.PICKUP` (5) with a specific seed.
 function ____exports.spawnPickupWithSeed(self, pickupVariant, subType, position, seed, velocity, spawner)
     if velocity == nil then
         velocity = VectorZero
@@ -523,6 +699,7 @@ function ____exports.spawnPickupWithSeed(self, pickupVariant, subType, position,
         seed
     )
 end
+--- Helper function to spawn a `EntityType.PROJECTILE` (9).
 function ____exports.spawnProjectile(self, projectileVariant, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -549,6 +726,7 @@ function ____exports.spawnProjectile(self, projectileVariant, subType, position,
     end
     return projectile
 end
+--- Helper function to spawn a `EntityType.PROJECTILE` (9) with a specific seed.
 function ____exports.spawnProjectileWithSeed(self, projectileVariant, subType, position, seed, velocity, spawner)
     if velocity == nil then
         velocity = VectorZero
@@ -566,6 +744,7 @@ function ____exports.spawnProjectileWithSeed(self, projectileVariant, subType, p
         seed
     )
 end
+--- Helper function to spawn a `EntityType.SLOT` (6).
 function ____exports.spawnSlot(self, slotVariant, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -587,6 +766,7 @@ function ____exports.spawnSlot(self, slotVariant, subType, position, velocity, s
         seed
     )
 end
+--- Helper function to spawn a `EntityType.SLOT` (6) with a specific seed.
 function ____exports.spawnSlotWithSeed(self, slotVariant, subType, position, seed, velocity, spawner)
     if velocity == nil then
         velocity = VectorZero
@@ -604,6 +784,7 @@ function ____exports.spawnSlotWithSeed(self, slotVariant, subType, position, see
         seed
     )
 end
+--- Helper function to spawn a `EntityType.TEAR` (2).
 function ____exports.spawnTear(self, tearVariant, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -630,6 +811,7 @@ function ____exports.spawnTear(self, tearVariant, subType, position, velocity, s
     end
     return tear
 end
+--- Helper function to spawn a `EntityType.EntityType` (2) with a specific seed.
 function ____exports.spawnTearWithSeed(self, tearVariant, subType, position, seed, velocity, spawner)
     if velocity == nil then
         velocity = VectorZero

package/functions/entityTypes.d.ts

@@ -1,3 +1,3 @@
 /// <reference types="isaac-typescript-definitions" />
-/** For EntityType.SLOT (6) */
+/** For `EntityType.SLOT` (6) */
 export declare function isSlot(entity: Entity): entity is EntitySlot;

package/functions/entityTypes.lua

@@ -1,6 +1,7 @@
 local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local EntityType = ____isaac_2Dtypescript_2Ddefinitions.EntityType
+--- For `EntityType.SLOT` (6)
 function ____exports.isSlot(self, entity)
     return entity.Type == EntityType.SLOT
 end

package/functions/enums.d.ts

@@ -1,4 +1,6 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 /**
  * TypeScriptToLua will transpile TypeScript enums to Lua tables that have a double mapping. Thus,
  * when you iterate over them, you will get both the names of the enums and the values of the enums,

package/functions/enums.lua

@@ -6,6 +6,21 @@ local ____array = require("functions.array")
 local getRandomArrayElement = ____array.getRandomArrayElement
 local ____rng = require("functions.rng")
 local getRandomSeed = ____rng.getRandomSeed
+--- TypeScriptToLua will transpile TypeScript enums to Lua tables that have a double mapping. Thus,
+-- when you iterate over them, you will get both the names of the enums and the values of the enums,
+-- in a random order. Use this helper function to get the entries of the enum with the reverse
+-- mappings filtered out.
+-- 
+-- This function will return the enum values in a sorted order, which may not necessarily be the
+-- same order as which they were declared in.
+-- 
+-- This function will work properly for both number enums and string enums. (Reverse mappings are
+-- not created for string enums.)
+-- 
+-- Also see the `getEnumKeys` and `getEnumValues` helper functions.
+-- 
+-- For a more in depth explanation, see:
+-- https://isaacscript.github.io/gotchas#iterating-over-enums
 function ____exports.getEnumEntries(self, transpiledEnum)
     local enumEntries = {}
     for key, value in pairs(transpiledEnum) do
@@ -27,6 +42,20 @@ function ____exports.getEnumEntries(self, transpiledEnum)
     )
     return enumEntries
 end
+--- TypeScriptToLua will transpile TypeScript enums to Lua tables that have a double mapping. Thus,
+-- when you iterate over them, you will get both the names of the enums and the values of the enums,
+-- in a random order. If all you need are the keys of an enum, use this helper function.
+-- 
+-- This function will return the enum keys in a sorted order, which may not necessarily be the same
+-- order as which they were declared in.
+-- 
+-- This function will work properly for both number enums and string enums. (Reverse mappings are
+-- not created for string enums.)
+-- 
+-- Also see the `getEnumEntries` and `getEnumValues` helper functions.
+-- 
+-- For a more in depth explanation, see:
+-- https://isaacscript.github.io/gotchas#iterating-over-enums
 function ____exports.getEnumKeys(self, transpiledEnum)
     local enumEntries = ____exports.getEnumEntries(nil, transpiledEnum)
     return __TS__ArrayMap(
@@ -39,10 +68,25 @@ function ____exports.getEnumKeys(self, transpiledEnum)
         end
     )
 end
+--- Helper function to get the amount of entries inside of an enum.
 function ____exports.getEnumLength(self, transpiledEnum)
     local enumEntries = ____exports.getEnumEntries(nil, transpiledEnum)
     return #enumEntries
 end
+--- TypeScriptToLua will transpile TypeScript enums to Lua tables that have a double mapping. Thus,
+-- when you iterate over them, you will get both the names of the enums and the values of the enums,
+-- in a random order. If all you need are the values of an enum, use this helper function.
+-- 
+-- This function will return the enum values in a sorted order, which may not necessarily be the
+-- same order as which they were declared in.
+-- 
+-- This function will work properly for both number enums and string enums. (Reverse mappings are
+-- not created for string enums.)
+-- 
+-- Also see the `getEnumEntries` and `getEnumKeys` helper functions.
+-- 
+-- For a more in depth explanation, see:
+-- https://isaacscript.github.io/gotchas#iterating-over-enums
 function ____exports.getEnumValues(self, transpiledEnum)
     local enumEntries = ____exports.getEnumEntries(nil, transpiledEnum)
     return __TS__ArrayMap(
@@ -63,6 +107,12 @@ function ____exports.getLastEnumValue(self, transpiledEnum)
     end
     return lastElement
 end
+--- Helper function to get a random value from the provided enum.
+-- 
+-- @param transpiledEnum The enum to get the value from.
+-- @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+-- `RNG.Next` method will be called. Default is `getRandomSeed()`.
+-- @param exceptions Optional. An array of elements to skip over if selected.
 function ____exports.getRandomEnumValue(self, transpiledEnum, seedOrRNG, exceptions)
     if seedOrRNG == nil then
         seedOrRNG = getRandomSeed(nil)
@@ -73,6 +123,18 @@ function ____exports.getRandomEnumValue(self, transpiledEnum, seedOrRNG, excepti
     local enumValues = ____exports.getEnumValues(nil, transpiledEnum)
     return getRandomArrayElement(nil, enumValues, seedOrRNG, exceptions)
 end
+--- Helper function to check every value of a custom enum for -1. This is helpful as a run-time check
+-- because many methods of the Isaac class return -1 if they fail.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- enum EntityTypeCustom {
+--   FOO = Isaac.GetEntityTypeByName("Foo"),
+-- }
+-- 
+-- validateCustomEnum("EntityTypeCustom", EntityTypeCustom);
+-- ```
 function ____exports.validateCustomEnum(self, transpiledEnumName, transpiledEnum)
     for ____, ____value in ipairs(____exports.getEnumEntries(nil, transpiledEnum)) do
         local key = ____value[1]

package/functions/familiars.lua

@@ -3,6 +3,33 @@ local ____cachedClasses = require("cachedClasses")
 local itemConfig = ____cachedClasses.itemConfig
 local ____familiarsThatShootPlayerTearsSet = require("sets.familiarsThatShootPlayerTearsSet")
 local FAMILIARS_THAT_SHOOT_PLAYER_TEARS_SET = ____familiarsThatShootPlayerTearsSet.FAMILIARS_THAT_SHOOT_PLAYER_TEARS_SET
+--- Helper function to add and remove familiars based on a target amount that you specify.
+-- 
+-- This is a convenience wrapper around the `EntityPlayer.CheckFamiliar` method. Use this helper
+-- function instead so that you do not have to retrieve the `ItemConfigItem` and so that you do not
+-- specify an incorrect RNG object. (The vanilla method is bugged in that it does not increment the
+-- RNG object; see the documentation of the method for more details.)
+-- 
+-- This function is meant to be called in the EvaluateCache callback (when the cache flag is equal
+-- to `CacheFlag.FAMILIARS`).
+-- 
+-- Note that this function is only meant to be used in special circumstances where the familiar
+-- count is completely custom and does not correspond to the amount of collectibles. For the general
+-- case, use the `checkFamiliarFromCollectibles` helper function instead.
+-- 
+-- Note that this will spawn familiars with a completely random `InitSeed`. When calculating random
+-- events for this familiar, you should use a data structure that maps familiar `InitSeed` to RNG
+-- objects that are initialized based on the seed from
+-- `EntityPlayer.GetCollectibleRNG(collectibleType)`.
+-- 
+-- @param player The player that owns the familiars.
+-- @param collectibleType The collectible type of the collectible associated with this familiar.
+-- @param targetCount The number of familiars that should exist. This function will add or remove
+-- familiars until it matches the target count.
+-- @param familiarVariant The variant of the familiar to spawn or remove.
+-- @param familiarSubType Optional. The sub-type of the familiar to spawn or remove. If not
+-- specified, it will search for existing familiars of all sub-types, and
+-- spawn new familiars with a sub-type of 0.
 function ____exports.checkFamiliar(self, player, collectibleType, targetCount, familiarVariant, familiarSubType)
     local itemConfigItem = itemConfig:GetCollectible(collectibleType)
     player:CheckFamiliar(
@@ -13,6 +40,31 @@ function ____exports.checkFamiliar(self, player, collectibleType, targetCount, f
         familiarSubType
     )
 end
+--- Helper function to add and remove familiars based on the amount of associated collectibles that a
+-- player has.
+-- 
+-- Use this helper function instead of invoking the `EntityPlayer.CheckFamiliar` method directly so
+-- that the target count is handled automatically.
+-- 
+-- This function is meant to be called in the EvaluateCache callback (when the cache flag is equal
+-- to `CacheFlag.FAMILIARS`).
+-- 
+-- Use this function when the amount of familiars should be equal to the amount of associated
+-- collectibles that the player has (plus any extras from having used Box of Friends or Monster
+-- Manual). If you instead need to have a custom amount of familiars, use the `checkFamiliars`
+-- function instead.
+-- 
+-- Note that this will spawn familiars with a completely random `InitSeed`. When calculating random
+-- events for this familiar, you should use a data structure that maps familiar `InitSeed` to RNG
+-- objects that are initialized based on the seed from
+-- `EntityPlayer.GetCollectibleRNG(collectibleType)`.
+-- 
+-- @param player The player that owns the familiars and collectibles.
+-- @param collectibleType The collectible type of the collectible associated with this familiar.
+-- @param familiarVariant The variant of the familiar to spawn or remove.
+-- @param familiarSubType Optional. The sub-type of the familiar to spawn or remove. If not
+-- specified, it will search for existing familiars of all sub-types, and
+-- spawn new familiars with a sub-type of 0.
 function ____exports.checkFamiliarFromCollectibles(self, player, collectibleType, familiarVariant, familiarSubType)
     local numCollectibles = player:GetCollectibleNum(collectibleType)
     local effects = player:GetEffects()