Entities

Functions

countEntities()

countEntities(entityType?, variant?, subType?, ignoreFriendly?): int

Defined in: packages/isaacscript-common/src/functions/entities.ts:39

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.

Parameters

entityType?

-1 | EntityType

Optional. Default is -1, which matches every entity type.

variant?

number = -1

Optional. Default is -1, which matches every variant.

subType?

number = -1

Optional. Default is -1, which matches every sub-type.

ignoreFriendly?

boolean = false

Optional. Default is false. Will throw a runtime error if set to true and the entityType is equal to -1.

Returns

int

---

doesAnyEntityExist()

doesAnyEntityExist(entityTypes, ignoreFriendly?): boolean

Defined in: packages/isaacscript-common/src/functions/entities.ts:82

Helper function to check if one or more matching entities exist in the current room. It uses the doesEntityExist helper function to determine this.

Parameters

entityTypes

ReadonlySet<EntityType> | readonly EntityType[]

An array or set of the entity types that you want to check for. Will return true if any of the provided entity types exist.

ignoreFriendly?

boolean = false

Optional. Default is false.

Returns

boolean

---

doesEntityExist()

doesEntityExist(entityType?, variant?, subType?, ignoreFriendly?): boolean

Defined in: packages/isaacscript-common/src/functions/entities.ts:106

Helper function to check if one or more of a specific kind of entity is present in the current room. It uses the countEntities helper function to determine this.

Parameters

entityType?

-1 | EntityType

Optional. Default is -1, which matches every entity type.

variant?

number = -1

Optional. Default is -1, which matches every variant.

subType?

number = -1

Optional. Default is -1, which matches every sub-type.

ignoreFriendly?

boolean = false

Optional. Default is false.

Returns

boolean

---

getClosestEntityTo()

getClosestEntityTo<T>(referenceEntity, entities, filterFunc?): T | undefined

Defined in: packages/isaacscript-common/src/functions/entities.ts:133

Given an array of entities, this helper function returns the closest one to a provided reference entity.

For example:

const player = Isaac.GetPlayer();
const gapers = getEntities(EntityType.GAPER);
const closestGaper = getClosestEntityTo(player, gapers);

Type Parameters

T

T extends AnyEntity

Parameters

referenceEntity

Entity

The entity that is close by.

entities

readonly T[]

The array of entities to look through.

filterFunc?

(entity) => boolean

Optional. A function to filter for a specific type of entity, like e.g. an enemy with a certain amount of HP left.

Returns

T | undefined

---

getConstituentsFromEntityID()

getConstituentsFromEntityID(entityID): [EntityType, int, int]

Defined in: packages/isaacscript-common/src/functions/entities.ts:156

Helper function to get the entity type, variant, and sub-type from an EntityID.

Parameters

entityID

EntityID

Returns

[EntityType, int, int]

---

getEntities()

getEntities(entityType?, variant?, subType?, ignoreFriendly?): readonly Entity[]

Defined in: packages/isaacscript-common/src/functions/entities.ts:229

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:

// Make all of the entities in the room invisible.
for (const entity of getEntities()) {
  entity.Visible = false;
}

Parameters

entityType?

-1 | EntityType

Optional. If specified, will only get the entities that match the type. Default is -1, which matches every type.

variant?

number = -1

Optional. If specified, will only get the entities that match the variant. Default is -1, which matches every variant.

subType?

number = -1

Optional. If specified, will only get the entities that match the sub-type. Default is -1, which matches every sub-type.

ignoreFriendly?

boolean = false

Optional. If set to true, it will exclude friendly NPCs from being returned. Default is false. Will only be taken into account if the entityType is specified.

Returns

readonly Entity[]

---

getEntityFields()

getEntityFields(entity): LuaMap<string, string | number | boolean>

Defined in: packages/isaacscript-common/src/functions/entities.ts:249

Helper function to get all the fields on an entity. For example, this is useful for comparing it to another entity later. (One option is to use the logTableDifferences function for this.)

This function will only get fields that are equal to booleans, numbers, or strings, or Vectors, as comparing other types is non-trivial.

Parameters

entity

Entity

Returns

LuaMap<string, string | number | boolean>

---

getEntityFromPtrHash()

getEntityFromPtrHash(ptrHash): Entity | undefined

Defined in: packages/isaacscript-common/src/functions/entities.ts:285

Helper function to get an entity from a PtrHash. Note that doing this is very expensive, so you should only use this function when debugging. (Normally, if you need to work backwards from a reference, you would use an EntityPtr instead of a PtrHash.

Parameters

ptrHash

PtrHash

Returns

Entity | undefined

---

getEntityID()

getEntityID(entity): EntityID

Defined in: packages/isaacscript-common/src/functions/entities.ts:291

Helper function to get a string containing the entity’s type, variant, and sub-type.

Parameters

entity

Entity

Returns

EntityID

---

getEntityIDFromConstituents()

getEntityIDFromConstituents(entityType, variant, subType): EntityID

Defined in: packages/isaacscript-common/src/functions/entities.ts:298

Helper function to get a formatted string in the format returned by the getEntityID function.

Parameters

entityType

EntityType

variant

int

subType

int

Returns

EntityID

---

getFilteredNewEntities()

getFilteredNewEntities<T>(oldEntities, newEntities): readonly T[]

Defined in: packages/isaacscript-common/src/functions/entities.ts:310

Helper function to compare two different arrays of entities. Returns the entities that are in the second array but not in the first array.

Type Parameters

T

T extends AnyEntity

Parameters

oldEntities

readonly T[]

newEntities

readonly T[]

Returns

readonly T[]

---

hasArmor()

hasArmor(entity): boolean

Defined in: packages/isaacscript-common/src/functions/entities.ts:332

Helper function to see if a particular entity has armor. In this context, armor refers to the damage scaling mechanic. For example, Ultra Greed has armor, but a Gaper does not.

For more on armor, see the wiki: https://bindingofisaacrebirth.fandom.com/wiki/Damage_Scaling

Parameters

entity

Entity

Returns

boolean

---

isActiveEnemy()

isActiveEnemy(entity): boolean

Defined in: packages/isaacscript-common/src/functions/entities.ts:342

Helper function to detect if a particular entity is an active enemy. Use this over the Entity.IsActiveEnemy method since it is bugged with friendly enemies, Grimaces, Ultra Greed, and Mother.

Parameters

entity

Entity

Returns

boolean

---

isEntityMoving()

isEntityMoving(entity, threshold?): boolean

Defined in: packages/isaacscript-common/src/functions/entities.ts:425

Helper function to measure an entity’s velocity to see if it is moving.

Use this helper function over checking if the velocity length is equal to 0 because entities can look like they are completely immobile but yet still have a non zero velocity. Thus, using a threshold is needed.

Parameters

entity

Entity

The entity whose velocity to measure.

threshold?

number = 0.01

Optional. The threshold from 0 to consider to be moving. Default is 0.01.

Returns

boolean

---

parseEntityID()

parseEntityID(entityID): [EntityType, int, int] | undefined

Defined in: packages/isaacscript-common/src/functions/entities.ts:437

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.

Parameters

entityID

string

Returns

[EntityType, int, int] | undefined

---

parseEntityTypeVariantString()

parseEntityTypeVariantString(entityTypeVariantString): [EntityType, int] | undefined

Defined in: packages/isaacscript-common/src/functions/entities.ts:478

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.

Parameters

entityTypeVariantString

string

Returns

[EntityType, int] | undefined

---

removeAllMatchingEntities()

removeAllMatchingEntities(entityType, entityVariant?, entitySubType?, cap?): readonly Entity[]

Defined in: packages/isaacscript-common/src/functions/entities.ts:512

Helper function to remove all of the matching entities in the room.

Parameters

entityType

EntityType

The entity type to match.

entityVariant?

number = -1

Optional. The variant to match. Default is -1, which matches every variant.

entitySubType?

number = -1

Optional. The sub-type to match. Default is -1, which matches every sub-type.

cap?

int

Optional. If specified, will only remove the given amount of collectibles.

Returns

readonly Entity[]

An array of the entities that were removed.

---

removeEntities()

removeEntities<T>(entities, cap?): readonly T[]

Defined in: packages/isaacscript-common/src/functions/entities.ts:529

Helper function to remove all of the entities in the supplied array.

Type Parameters

T

T extends AnyEntity

Parameters

entities

readonly T[]

The array of entities to remove.

cap?

int

Optional. If specified, will only remove the given amount of entities.

Returns

readonly T[]

An array of the entities that were removed.

---

rerollEnemy()

rerollEnemy(entity): Entity | undefined

Defined in: packages/isaacscript-common/src/functions/entities.ts:558

Helper function to reroll an enemy. Use this instead of the vanilla “Game.RerollEnemy” function if you want the rerolled enemy to be returned.

Parameters

entity

Entity

The entity to reroll.

Returns

Entity | undefined

If the game failed to reroll the enemy, returns undefined. Otherwise, returns the rerolled entity.

---

setEntityDamageFlash()

setEntityDamageFlash(entity): void

Defined in: packages/isaacscript-common/src/functions/entities.ts:581

Helper function to make an entity flash red like it is taking damage. This is useful when you want to make it appear as if an entity is taking damage without actually dealing any damage to it.

Parameters

entity

Entity

Returns

void

---

setEntityOpacity()

setEntityOpacity(entity, alpha): void

Defined in: packages/isaacscript-common/src/functions/entities.ts:592

Helper function to keep an entity’s color the same values as it already is but set the opacity to a specific value.

Parameters

entity

Entity

The entity to set.

alpha

float

A value between 0 and 1 that represents the fade amount.

Returns

void

---

setEntityRandomColor()

setEntityRandomColor(entity): void

Defined in: packages/isaacscript-common/src/functions/entities.ts:597

Parameters

entity

Entity

Returns

void

---

spawn()

spawn(entityType, variant, subType, positionOrGridIndex, velocity?, spawner?, seedOrRNG?): Entity

Defined in: packages/isaacscript-common/src/functions/entities.ts:625

Helper function to spawn an entity. Always use this instead of the Isaac.Spawn method, since using that method can crash the game.

Also see the spawnWithSeed helper function.

Parameters

entityType

EntityType

The EntityType of the entity to spawn.

variant

int

The variant of the entity to spawn.

subType

int

The sub-type of the entity to spawn.

positionOrGridIndex

int | Vector

The position or grid index of the entity to spawn.

velocity?

Vector = VectorZero

Optional. The velocity of the entity to spawn. Default is VectorZero.

spawner?

Entity

Optional. The entity that will be the SpawnerEntity. Default is undefined.

seedOrRNG?

RNG | Seed

Optional. The seed or RNG object to use to generate the InitSeed of the entity. Default is undefined, which will make the entity spawn with a random seed.

Returns

Entity

---

spawnEntityID()

spawnEntityID(entityID, positionOrGridIndex, velocity?, spawner?, seedOrRNG?): Entity

Defined in: packages/isaacscript-common/src/functions/entities.ts:674

Helper function to spawn the entity corresponding to an EntityID.

Parameters

entityID

EntityID

The EntityID of the entity to spawn.

positionOrGridIndex

int | Vector

The position or grid index of the entity to spawn.

velocity?

Vector = VectorZero

Optional. The velocity of the entity to spawn. Default is VectorZero.

spawner?

Entity

Optional. The entity that will be the SpawnerEntity. Default is undefined.

seedOrRNG?

RNG | Seed

Optional. The seed or RNG object to use to generate the InitSeed of the entity. Default is undefined, which will make the entity spawn with a random seed using the Isaac.Spawn method.

Returns

Entity

---

spawnWithSeed()

spawnWithSeed(entityType, variant, subType, positionOrGridIndex, seedOrRNG, velocity?, spawner?): Entity

Defined in: packages/isaacscript-common/src/functions/entities.ts:697

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.

Parameters

entityType

EntityType

variant

int

subType

int

positionOrGridIndex

int | Vector

seedOrRNG

RNG | Seed

velocity?

Vector = VectorZero

spawner?

Entity

Returns

Entity