Grid Entities

Functions

convertXMLGridEntityType()

convertXMLGridEntityType(gridEntityXMLType, gridEntityXMLVariant): [GridEntityType, int] | undefined

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:70

Helper function to convert the grid entity type found in a room XML file to the corresponding grid entity type and variant normally used by the game. For example, GridEntityXMLType.ROCK is 1000 (in a room XML file), but GridEntityType.ROCK is equal to 2 (in-game).

Parameters

gridEntityXMLType

GridEntityXMLType

gridEntityXMLVariant

int

Returns

[GridEntityType, int] | undefined

doesGridEntityExist()

doesGridEntityExist(gridEntityType, variant?): boolean

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:97

Helper function to check if one or more of a specific kind of grid entity is present in the current room.

Parameters

gridEntityType

GridEntityType

The grid entity type to match.

variant?

number = -1

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

Returns

boolean

getAllGridIndexes()

getAllGridIndexes(): readonly int[]

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:124

Helper function to get every legal grid index for the current room.

Under the hood, this uses the Room.GetGridSize method.

Returns

readonly int[]

getCollidingEntitiesWithGridEntity()

getCollidingEntitiesWithGridEntity(gridEntity): readonly Entity[]

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:141

Gets the entities that have a hitbox that overlaps with any part of the square that the grid entity is on.

This function is useful because the vanilla collision callbacks do not work with grid entities. This is used by POST_GRID_ENTITY_COLLISION custom callback.

Note that this function will not work properly in the POST_NEW_ROOM callback since entities do not have collision yet in that callback.

Parameters

gridEntity

GridEntity

Returns

readonly Entity[]

getConstituentsFromGridEntityID()

getConstituentsFromGridEntityID(gridEntityID): [GridEntityType, int]

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:166

Helper function to get the grid entity type and variant from a GridEntityID.

Parameters

gridEntityID

GridEntityID

Returns

[GridEntityType, int]

getGridEntities()

getGridEntities(…gridEntityTypes): readonly GridEntity[]

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

Helper function to get every grid entity in the current room.

Use this function with no arguments to get every grid entity, or specify a variadic amount of arguments to match specific grid entity types.

For example:

for (const gridEntity of getGridEntities()) {
  print(gridEntity.GetType())
}

For example:

const rocks = getGridEntities(
  GridEntityType.ROCK,
  GridEntityType.BLOCK,
  GridEntityType.ROCK_TINTED,
);

Parameters

gridEntityTypes

…readonly GridEntityType[]

Returns

readonly GridEntity[]

Allow Empty Variadic

getGridEntitiesExcept()

getGridEntitiesExcept(…gridEntityTypes): readonly GridEntity[]

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:251

Helper function to get every grid entity in the current room except for certain specific types.

This function is variadic, meaning that you can specify as many grid entity types as you want to exclude.

Parameters

gridEntityTypes

…readonly GridEntityType[]

Returns

readonly GridEntity[]

getGridEntitiesInRadius()

getGridEntitiesInRadius(targetPosition, radius): readonly GridEntity[]

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:268

Helper function to get all grid entities in a given radius around a given point.

Parameters

targetPosition

Vector

radius

number

Returns

readonly GridEntity[]

getGridEntitiesMap()

getGridEntitiesMap(…gridEntityTypes): ReadonlyMap<int, GridEntity>

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:323

Helper function to get a map of every grid entity in the current room. The indexes of the map are equal to the grid index. The values of the map are equal to the grid entities.

Use this function with no arguments to get every grid entity, or specify a variadic amount of arguments to match specific grid entity types.

Parameters

gridEntityTypes

…readonly GridEntityType[]

Returns

ReadonlyMap<int, GridEntity>

Allow Empty Variadic

getGridEntityANM2Path()

getGridEntityANM2Path(gridEntityType): string | undefined

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:338

Helper function to get the ANM2 path for a grid entity type.

Parameters

gridEntityType

GridEntityType

Returns

string | undefined

getGridEntityCollisionPoints()

getGridEntityCollisionPoints(gridEntity): object

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:346

Helper function to get the top left and bottom right corners of a given grid entity.

Parameters

gridEntity

GridEntity

Returns

object

topLeft

topLeft: Vector

bottomRight

bottomRight: Vector

getGridEntityID()

getGridEntityID(gridEntity): GridEntityID

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:366

Helper function to get a string containing the grid entity’s type and variant.

Parameters

gridEntity

GridEntity

Returns

GridEntityID

getGridEntityIDFromConstituents()

getGridEntityIDFromConstituents(gridEntityType, variant): GridEntityID

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:376

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

Parameters

gridEntityType

GridEntityType

variant

int

Returns

GridEntityID

getMatchingGridEntities()

getMatchingGridEntities(gridEntityType, variant): readonly GridEntity[]

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:389

Helper function to get all of the grid entities in the room that specifically match the type and variant provided.

If you want to match every variant, use the getGridEntities function instead.

Parameters

gridEntityType

GridEntityType

variant

int

Returns

readonly GridEntity[]

getRockPNGPath()

getRockPNGPath(): string

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:405

Helper function to get the PNG path for a rock. This depends on the current room’s backdrop. The values are taken from the “backdrops.xml” file.

All of the rock PNGs are in the “gfx/grid” directory.

Returns

string

getSurroundingGridEntities()

getSurroundingGridEntities(gridEntity): readonly GridEntity[]

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:416

Helper function to get the grid entities on the surrounding tiles from the provided grid entity.

For example, if a rock was surrounded by rocks on all sides, this would return an array of 8 rocks (e.g. top-left + top + top-right + left + right + bottom-left + bottom + right).

Parameters

gridEntity

GridEntity

Returns

readonly GridEntity[]

getSurroundingGridIndexes()

getSurroundingGridIndexes(gridIndex): [int, int, int, int, int, int, int, int]

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:442

Helper function to get the grid indexes on the surrounding tiles from the provided grid index.

There are always 8 grid indexes returned (e.g. top-left + top + top-right + left + right + bottom-left + bottom + right), even if the computed values would be negative or otherwise invalid.

Parameters

gridIndex

int

Returns

[int, int, int, int, int, int, int, int]

getTopLeftWall()

getTopLeftWall(): GridEntity | undefined

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:476

Helper function to get the top left wall in the current room.

This function can be useful in certain situations to determine if the room is currently loaded.

Returns

GridEntity | undefined

getTopLeftWallGridIndex()

getTopLeftWallGridIndex(): int

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:488

Helper function to get the grid index of the top left wall. (This will depend on what the current room shape is.)

This function can be useful in certain situations to determine if the room is currently loaded.

Returns

int

isGridEntityBreakableByExplosion()

isGridEntityBreakableByExplosion(gridEntity): boolean

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:503

Helper function to detect if a particular grid entity would “break” if it was touched by an explosion.

For example, rocks and pots are breakable by explosions, but blocks are not.

Parameters

gridEntity

GridEntity

Returns

boolean

isGridEntityBroken()

isGridEntityBroken(gridEntity): boolean

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:525

Helper function to see if the provided grid entity is in its respective broken state. See the GRID_ENTITY_TYPE_TO_BROKEN_STATE_MAP constant for more details.

Note that in the case of GridEntityType.LOCK (11), the state will turn to being broken before the actual collision for the entity is removed.

Parameters

gridEntity

GridEntity

Returns

boolean

isGridEntityXMLType()

isGridEntityXMLType(num): num is GridEntityXMLType

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:535

Helper function to see if an arbitrary number is a valid GridEntityXMLType. This is useful in the PRE_ROOM_ENTITY_SPAWN callback for narrowing the type of the first argument.

Parameters

num

number

Returns

num is GridEntityXMLType

isGridIndexAdjacentToDoor()

isGridIndexAdjacentToDoor(gridIndex): boolean

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:543

Helper function to check if the provided grid index has a door on it or if the surrounding 8 grid indexes have a door on it.

Parameters

gridIndex

int

Returns

boolean

isPoopGridEntityXMLType()

isPoopGridEntityXMLType(gridEntityXMLType): boolean

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:562

Helper function to see if a GridEntityXMLType is some kind of poop.

Parameters

gridEntityXMLType

GridEntityXMLType

Returns

boolean

isPostBossVoidPortal()

isPostBossVoidPortal(gridEntity): boolean

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:576

Helper function to detect whether a given Void Portal is one that randomly spawns after a boss is defeated or is one that naturally spawns in the room after Hush.

Under the hood, this is determined by looking at the VarData of the entity:

The VarData of Void Portals that are spawned after bosses will be equal to 1.
The VarData of the Void Portal in the room after Hush is equal to 0.

Parameters

gridEntity

GridEntity

Returns

boolean

removeAllGridEntitiesExcept()

removeAllGridEntitiesExcept(…gridEntityTypes): readonly GridEntity[]

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:605

Helper function to all grid entities in the room except for ones matching the grid entity types provided.

Note that this function will automatically update the room. (This means that you can spawn new grid entities on the same tile on the same frame, if needed.)

For example:

removeAllGridEntitiesExcept(
  GridEntityType.WALL,
  GridEntityType.DOOR,
);

Parameters

gridEntityTypes

…readonly GridEntityType[]

Returns

readonly GridEntity[]

The grid entities that were removed.

removeAllMatchingGridEntities()

removeAllMatchingGridEntities(…gridEntityType): readonly GridEntity[]

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:645

Helper function to remove all of the grid entities in the room that match the grid entity types provided.

Note that this function will automatically update the room. (This means that you can spawn new grid entities on the same tile on the same frame, if needed.)

For example:

removeAllMatchingGridEntities(
  GridEntityType.ROCK,
  GridEntityType.BLOCK,
  GridEntityType.ROCK_TINTED,
);

Parameters

gridEntityType

…readonly GridEntityType[]

Returns

readonly GridEntity[]

An array of the grid entities removed.

removeEntitiesSpawnedFromGridEntity()

removeEntitiesSpawnedFromGridEntity(entities, gridEntity): void

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:668

Helper function to remove all entities that just spawned from a grid entity breaking. Specifically, this is any entities that overlap with the position of a grid entity and are on frame 0.

You must specify an array of entities to look through.

Parameters

entities

readonly Entity[]

gridEntity

GridEntity

Returns

void

removeGridEntities()

removeGridEntities<T>(gridEntities, updateRoom, cap?): readonly T[]

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:692

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

Type Parameters

T

T extends AnyGridEntity

Parameters

gridEntities

readonly T[]

The array of grid entities to remove.

updateRoom

boolean

Whether to update the room after the grid entities are removed. This is generally a good idea because if the room is not updated, you will be unable to spawn another grid entity on the same tile until a frame has passed. However, doing this is expensive, since it involves a call to Isaac.GetRoomEntities, so set this to false if you need to run this function multiple times.

cap?

int

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

Returns

readonly T[]

An array of the entities that were removed.

removeGridEntity()

removeGridEntity(gridEntityOrGridIndex, updateRoom): void

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:732

Helper function to remove a grid entity by providing the grid entity object or the grid index inside of the room.

If removing a Devil Statue or an Angel Statue, this will also remove the associated effect (EffectVariant.DEVIL (6) or EffectVariant.ANGEL (9), respectively.)

Parameters

gridEntityOrGridIndex

int | GridEntity

The grid entity or grid index to remove.

updateRoom

boolean

Whether to update the room after the grid entity is removed. This is generally a good idea because if the room is not updated, you will be unable to spawn another grid entity on the same tile until a frame has passed. However, doing this is expensive, since it involves a call to Isaac.GetRoomEntities, so set this to false if you need to run this function multiple times.

Returns

void

setGridEntityInvisible()

setGridEntityInvisible(gridEntity): void

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:782

Helper function to make a grid entity invisible. This is accomplished by resetting the sprite.

Note that this function is destructive such that once you make a grid entity invisible, it can no longer become visible. (This is because the information about the sprite is lost when it is reset.)

Parameters

gridEntity

GridEntity

Returns

void

setGridEntityType()

setGridEntityType(gridEntity, gridEntityType): void

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:794

Helper function to change the type of a grid entity to another type. Use this instead of the GridEntity.SetType method since that does not properly handle updating the sprite of the grid entity after the type is changed.

Setting the new type to GridEntityType.NULL (0) will have no effect.

Parameters

gridEntity

GridEntity

gridEntityType

GridEntityType

Returns

void

spawnGiantPoop()

spawnGiantPoop(topLeftGridIndex): boolean

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:824

Helper function to spawn a giant poop. This is performed by spawning each of the four quadrant grid entities in the appropriate positions.

Parameters

topLeftGridIndex

int

Returns

boolean

Whether spawning the four quadrants was successful.

spawnGridEntity()

spawnGridEntity(gridEntityType, gridIndexOrPosition, shouldRemoveExistingGridEntity?): GridEntity | undefined

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:906

Helper function to spawn a grid entity with a specific type.

This function assumes you want to give the grid entity a variant of 0. If you want to specify a variant, use the spawnGridEntityWithVariant helper function instead.

Use this instead of the Isaac.GridSpawn method since it:

handles giving pits collision
removes existing grid entities on the same tile, if any
allows you to specify either the grid index or the position

Parameters

gridEntityType

GridEntityType

The GridEntityType to use.

gridIndexOrPosition

int | Vector

The grid index or position in the room that you want to spawn the grid entity at. If a position is specified, the closest grid index will be used.

shouldRemoveExistingGridEntity?

boolean = true

Optional. Whether to remove the existing grid entity on the same tile, if it exists. Defaults to true. If false, this function will do nothing, since spawning a grid entity on top of another grid entity will not replace it.

Returns

GridEntity | undefined

spawnGridEntityWithVariant()

spawnGridEntityWithVariant(gridEntityType, variant, gridIndexOrPosition, shouldRemoveExistingGridEntity?): GridEntity | undefined

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:937

Helper function to spawn a grid entity with a specific variant.

Use this instead of the Isaac.GridSpawn method since it:

handles giving pits collision
removes existing grid entities on the same tile, if any
allows you to specify the grid index or the position

Parameters

gridEntityType

GridEntityType

The GridEntityType to use.

variant

int

The variant to use.

gridIndexOrPosition

int | Vector

The grid index or position in the room that you want to spawn the grid entity at. If a position is specified, the closest grid index will be used.

shouldRemoveExistingGridEntity?

boolean = true

Returns

GridEntity | undefined

spawnVoidPortal()

spawnVoidPortal(gridIndex): GridEntity | undefined

Defined in: packages/isaacscript-common/src/functions/gridEntities.ts:996

Helper function to spawn a Void Portal. This is more complicated than simply spawning a trapdoor with the appropriate variant, as the game does not give it the correct sprite automatically.

Parameters

gridIndex

int

Returns

GridEntity | undefined