isaacscript-common 2.3.2 → 3.1.1

package/functions/entity.lua

@@ -14,20 +14,33 @@ local ____random = require("functions.random")
 local getRandom = ____random.getRandom
 local ____rng = require("functions.rng")
 local newRNG = ____rng.newRNG
+--- Helper function to remove all of the entities in the supplied array.
+-- 
+-- @param entities The array of entities to remove.
+-- @param cap Optional. If specified, will only remove the given amount of entities.
+-- @returns An array of the entities that were removed.
 function ____exports.removeEntities(self, entities, cap)
     if #entities == 0 then
-        return false
+        return {}
     end
-    local numEntitiesRemoved = 0
+    local entitiesRemoved = {}
     for ____, entity in ipairs(entities) do
         entity:Remove()
-        numEntitiesRemoved = numEntitiesRemoved + 1
-        if cap ~= nil and numEntitiesRemoved >= cap then
-            return true
+        entitiesRemoved[#entitiesRemoved + 1] = entity
+        if cap ~= nil and #entitiesRemoved >= cap then
+            return entitiesRemoved
         end
     end
-    return true
+    return entitiesRemoved
 end
+--- Helper function to count the number of entities in room. Use this over the vanilla
+-- `Isaac.CountEntities` method to avoid having to specify a spawner and to handle ignoring charmed
+-- enemies.
+-- 
+-- @param entityType Default is -1. -1 matches every entity type.
+-- @param variant Default is -1. -1 matches every variant.
+-- @param subType Default is -1. -1 matches every sub-type.
+-- @param ignoreFriendly Default is false.
 function ____exports.countEntities(self, entityType, variant, subType, ignoreFriendly)
     if entityType == nil then
         entityType = -1
@@ -53,6 +66,16 @@ function ____exports.countEntities(self, entityType, variant, subType, ignoreFri
     )
     return #entities
 end
+--- Given an array of entities, this helper function returns the closest one to a provided reference
+-- entity.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const player = Isaac.GetPlayer();
+-- const gapers = getEntities(EntityType.GAPER);
+-- const closestGaper = getClosestEntityTo(player, gapers);
+-- ```
 function ____exports.getClosestEntityTo(self, referenceEntity, entities)
     local closestEntity
     local closestDistance = math.huge
@@ -65,6 +88,30 @@ function ____exports.getClosestEntityTo(self, referenceEntity, entities)
     end
     return closestEntity
 end
+--- Helper function to get all of the entities in the room or all of the entities that match a
+-- specific entity type / variant / sub-type.
+-- 
+-- Due to bugs with `Isaac.FindInRadius`, this function uses `Isaac.GetRoomEntities`, which is more
+-- expensive but also more robust. (If a matching entity type is provided, then `Isaac.FindByType`
+-- will be used instead.)
+-- 
+-- For example:
+-- 
+-- ```ts
+-- // Make all of the entities in the room invisible
+-- for (const entity of getEntities()) {
+--   entity.Visible = false;
+-- }
+-- ```
+-- 
+-- @param entityType Optional. If specified, will only return NPCs that match this entity type.
+-- @param variant Optional. If specified, will only return NPCs that match this variant. Default is
+-- -1. -1 matches every variant.
+-- @param subType Optional. If specified, will only return NPCs that match this sub-type. Default is
+-- -1. -1 matches every sub-type.
+-- @param ignoreFriendly Optional. If set to true, it will exclude friendly NPCs from being
+-- returned. Default is false. Will only be taken into account if
+-- `matchingEntityType` is specified.
 function ____exports.getEntities(self, entityType, variant, subType, ignoreFriendly)
     if variant == nil then
         variant = -1
@@ -80,9 +127,12 @@ function ____exports.getEntities(self, entityType, variant, subType, ignoreFrien
     end
     return Isaac.FindByType(entityType, variant, subType, ignoreFriendly)
 end
+--- Helper function to return a string containing the entity's type, variant, and sub-type.
 function ____exports.getEntityID(self, entity)
     return (((tostring(entity.Type) .. ".") .. tostring(entity.Variant)) .. ".") .. tostring(entity.SubType)
 end
+--- Helper function to compare two different arrays of entities. Returns the entities that are in the
+-- second array but not in the first array.
 function ____exports.getFilteredNewEntities(self, oldEntities, newEntities)
     local oldEntitiesSet = __TS__New(Set)
     for ____, entity in ipairs(oldEntities) do
@@ -97,15 +147,28 @@ function ____exports.getFilteredNewEntities(self, oldEntities, newEntities)
         end
     )
 end
+--- Helper function to measure an entity's velocity to see if it is moving.
+-- 
+-- @param entity The entity whose velocity to measure.
+-- @param threshold Optional. The threshold from 0 to consider to be moving. Default is 0.01.
 function ____exports.isEntityMoving(self, entity, threshold)
     if threshold == nil then
         threshold = 0.01
     end
     return entity.Velocity:Length() >= threshold
 end
+--- Helper function to determine if the specified entity type is an end-game story boss, like Isaac,
+-- Blue Baby, Mega Satan, The Beast, and so on. This is useful because certain effects should only
+-- apply to non-story bosses, like Vanishing Twin. Also see the `STORY_BOSSES` constant.
 function ____exports.isStoryBoss(self, entityType)
     return STORY_BOSSES_SET:has(entityType)
 end
+--- Helper function to parse a string that contains an entity type, a variant, and a sub-type,
+-- separated by periods.
+-- 
+-- For example, passing "45.0.1" would return an array of [45, 0, 1].
+-- 
+-- Returns undefined if the string cannot be parsed.
 function ____exports.parseEntityID(self, entityID)
     local entityIDArray = __TS__StringSplit(entityID, ".")
     if #entityIDArray ~= 3 then
@@ -126,6 +189,12 @@ function ____exports.parseEntityID(self, entityID)
     end
     return {entityType, variant, subType}
 end
+--- Helper function to parse a string that contains an entity type and a variant separated by a
+-- period.
+-- 
+-- For example, passing "45.0" would return an array of [45, 0].
+-- 
+-- Returns undefined if the string cannot be parsed.
 function ____exports.parseEntityTypeVariantString(self, entityTypeVariantString)
     local entityTypeVariantArray = __TS__StringSplit(entityTypeVariantString, ".")
     if #entityTypeVariantArray ~= 2 then
@@ -142,6 +211,13 @@ function ____exports.parseEntityTypeVariantString(self, entityTypeVariantString)
     end
     return {entityType, variant}
 end
+--- Helper function to remove all of the matching entities in the room.
+-- 
+-- @param entityType The entity type to match.
+-- @param entityVariant Optional. The variant to match. Default is -1. -1 matches every variant.
+-- @param entitySubType Optional. The sub-type to match. Default is -1. -1 matches every sub-type.
+-- @param cap Optional. If specified, will only remove the given amount of collectibles.
+-- @returns An array of the entities that were removed.
 function ____exports.removeAllMatchingEntities(self, entityType, entityVariant, entitySubType, cap)
     if entityVariant == nil then
         entityVariant = -1
@@ -155,6 +231,12 @@ function ____exports.removeAllMatchingEntities(self, entityType, entityVariant,
     local entities = ____exports.getEntities(nil, entityType, entityVariant, entitySubType)
     return ____exports.removeEntities(nil, entities, cap)
 end
+--- Helper function to reroll an enemy. Use this instead of the vanilla "Game.RerollEnemy" function
+-- if you want the rerolled enemy to be returned.
+-- 
+-- @param entity The entity to reroll.
+-- @returns If the game failed to reroll the enemy, returns undefined. Otherwise, returns the
+-- rerolled entity.
 function ____exports.rerollEnemy(self, entity)
     local oldEntities = ____exports.getEntities(nil)
     local wasRerolled = game:RerollEnemy(entity)
@@ -182,6 +264,10 @@ function ____exports.setEntityRandomColor(self, entity)
         false
     )
 end
+--- Helper function to spawn an entity. Use this instead of the `Isaac.Spawn` method if you do not
+-- need to specify the velocity or spawner.
+-- 
+-- Also see the `spawnWithSeed` helper function.
 function ____exports.spawn(self, entityType, variant, subType, position, velocity, spawner, seed)
     if velocity == nil then
         velocity = VectorZero
@@ -212,6 +298,8 @@ function ____exports.spawn(self, entityType, variant, subType, position, velocit
         seed
     )
 end
+--- Helper function to spawn an entity. Use this instead of the `Game.Spawn` method if you do not
+-- need to specify the velocity or spawner.
 function ____exports.spawnWithSeed(self, entityType, variant, subType, position, seed, velocity, spawner)
     if velocity == nil then
         velocity = VectorZero

package/functions/entitySpecific.d.ts

@@ -138,18 +138,18 @@ export declare function npcFireProjectiles(npc: EntityNPC, position: Vector, vel
  * @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 True if one or more bombs were removed, false otherwise.
+ * @returns An array of the bombs that were removed.
  */
-export declare function removeAllBombs(bombVariant?: BombVariant, subType?: int, cap?: int): boolean;
+export declare function removeAllBombs(bombVariant?: BombVariant, subType?: int, cap?: int): EntityBomb[];
 /**
  * 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 True if one or more effects were removed, false otherwise.
+ * @returns An array of the effects that were removed.
  */
-export declare function removeAllEffects(effectVariant?: EffectVariant, subType?: int, cap?: int): boolean;
+export declare function removeAllEffects(effectVariant?: EffectVariant, subType?: int, cap?: int): EntityEffect[];
 /**
  * Helper function to remove all of the familiars in the room.
  *
@@ -157,43 +157,43 @@ export declare function removeAllEffects(effectVariant?: EffectVariant, subType?
  *                        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 True if one or more familiars were removed, false otherwise.
+ * @returns An array of the familiars that were removed.
  */
-export declare function removeAllFamiliars(familiarVariant?: FamiliarVariant, subType?: int, cap?: int): boolean;
+export declare function removeAllFamiliars(familiarVariant?: FamiliarVariant, subType?: int, cap?: int): EntityFamiliar[];
 /**
  * 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 True if one or more knives were removed, false otherwise.
+ * @returns An array of the knives that were removed.
  */
-export declare function removeAllKnives(knifeVariant?: KnifeVariant, subType?: int, cap?: int): boolean;
+export declare function removeAllKnives(knifeVariant?: KnifeVariant, subType?: int, cap?: int): EntityKnife[];
 /**
  * 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 True if one or more lasers were removed, false otherwise.
+ * @returns An array of the lasers that were removed.
  */
-export declare function removeAllLasers(laserVariant?: LaserVariant, subType?: int, cap?: int): boolean;
+export declare function removeAllLasers(laserVariant?: LaserVariant, subType?: int, cap?: int): EntityLaser[];
 /**
  * Helper function to remove all NPCs in the room.
  *
  * @param cap Optional. If specified, will only remove the given amount of NPCs.
- * @returns True if one or more NPCs were removed, false otherwise.
+ * @returns An array of the NPCs that were removed.
  */
-export declare function removeAllNPCs(cap?: int): boolean;
+export declare function removeAllNPCs(cap?: int): EntityNPC[];
 /**
  * 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 True if one or more pickups were removed, false otherwise.
+ * @returns An array of the pickups that were removed.
  */
-export declare function removeAllPickups(pickupVariant?: PickupVariant, subType?: int, cap?: int): boolean;
+export declare function removeAllPickups(pickupVariant?: PickupVariant, subType?: int, cap?: int): EntityPickup[];
 /**
  * Helper function to remove all of the `EntityType.PROJECTILE` in the room.
  *
@@ -201,27 +201,27 @@ export declare function removeAllPickups(pickupVariant?: PickupVariant, subType?
  *                          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 True if one or more projectiles were removed, false otherwise.
+ * @returns An array of the projectiles that were removed.
  */
-export declare function removeAllProjectiles(projectileVariant?: ProjectileVariant, subType?: int, cap?: int): boolean;
+export declare function removeAllProjectiles(projectileVariant?: ProjectileVariant, subType?: int, cap?: int): EntityProjectile[];
 /**
  * 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 True if one or more slots were removed, false otherwise.
+ * @returns An array of the slots that were removed.
  */
-export declare function removeAllSlots(slotVariant?: SlotVariant, subType?: int, cap?: int): boolean;
+export declare function removeAllSlots(slotVariant?: SlotVariant, subType?: int, cap?: int): Entity[];
 /**
  * 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 True if one or more tears were removed, false otherwise.
+ * @returns An array of the tears that were removed.
  */
-export declare function removeAllTears(tearVariant?: TearVariant, subType?: int, cap?: int): boolean;
+export declare function removeAllTears(tearVariant?: TearVariant, subType?: int, cap?: int): EntityTear[];
 /** Helper function to spawn a `EntityType.BOMB` (4). */
 export declare function spawnBomb(bombVariant: BombVariant, subType: int, position: Vector, velocity?: Readonly<Vector>, spawner?: Entity | undefined, seed?: Seed | undefined): EntityBomb;
 /** Helper function to spawn a `EntityType.BOMB` (4) with a specific seed. */