isaacscript-common/dist/functions/gridEntities.d.ts

Helper functions and features for IsaacScript mods.

import type { GridEntityXMLType } from "isaac-typescript-definitions";
import { GridEntityType } from "isaac-typescript-definitions";
import type { AnyGridEntity } from "../types/AnyGridEntity";
import type { GridEntityID } from "../types/GridEntityID";
/**
 * 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).
 */
export declare function convertXMLGridEntityType(gridEntityXMLType: GridEntityXMLType, gridEntityXMLVariant: int): [GridEntityType, int] | undefined;
/**
 * Helper function to check if one or more of a specific kind of grid entity is present in the
 * current room.
 *
 * @param gridEntityType The grid entity type to match.
 * @param variant Optional. Default is -1, which matches every variant.
 */
export declare function doesGridEntityExist(gridEntityType: GridEntityType, variant?: number): boolean;
/**
 * Helper function to get every legal grid index for the current room.
 *
 * Under the hood, this uses the `Room.GetGridSize` method.
 */
export declare function getAllGridIndexes(): readonly int[];
/**
 * 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.
 */
export declare function getCollidingEntitiesWithGridEntity(gridEntity: GridEntity): readonly Entity[];
/** Helper function to get the grid entity type and variant from a `GridEntityID`. */
export declare function getConstituentsFromGridEntityID(gridEntityID: GridEntityID): [gridEntityType: GridEntityType, variant: int];
/**
 * 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:
 *
 * ```ts
 * for (const gridEntity of getGridEntities()) {
 *   print(gridEntity.GetType())
 * }
 * ```
 *
 * For example:
 *
 * ```ts
 * const rocks = getGridEntities(
 *   GridEntityType.ROCK,
 *   GridEntityType.BLOCK,
 *   GridEntityType.ROCK_TINTED,
 * );
 * ```
 *
 * @allowEmptyVariadic
 */
export declare function getGridEntities(...gridEntityTypes: readonly GridEntityType[]): readonly GridEntity[];
/**
 * 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.
 */
export declare function getGridEntitiesExcept(...gridEntityTypes: readonly GridEntityType[]): readonly GridEntity[];
/** Helper function to get all grid entities in a given radius around a given point. */
export declare function getGridEntitiesInRadius(targetPosition: Vector, radius: number): readonly GridEntity[];
/**
 * 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.
 *
 * @allowEmptyVariadic
 */
export declare function getGridEntitiesMap(...gridEntityTypes: readonly GridEntityType[]): ReadonlyMap<int, GridEntity>;
/** Helper function to get the ANM2 path for a grid entity type. */
export declare function getGridEntityANM2Path(gridEntityType: GridEntityType): string | undefined;
/** Helper function to get the top left and bottom right corners of a given grid entity. */
export declare function getGridEntityCollisionPoints(gridEntity: GridEntity): {
    topLeft: Vector;
    bottomRight: Vector;
};
/** Helper function to get a string containing the grid entity's type and variant. */
export declare function getGridEntityID(gridEntity: GridEntity): GridEntityID;
/**
 * Helper function to get a formatted string in the format returned by the `getGridEntityID`
 * function.
 */
export declare function getGridEntityIDFromConstituents(gridEntityType: GridEntityType, variant: int): GridEntityID;
/**
 * 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.
 */
export declare function getMatchingGridEntities(gridEntityType: GridEntityType, variant: int): readonly GridEntity[];
/**
 * 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.
 */
export declare function getRockPNGPath(): string;
/**
 * 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).
 */
export declare function getSurroundingGridEntities(gridEntity: GridEntity): readonly GridEntity[];
/**
 * 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.
 */
export declare function getSurroundingGridIndexes(gridIndex: int): [
    topLeft: int,
    top: int,
    topRight: int,
    left: int,
    right: int,
    bottomLeft: int,
    bottom: int,
    bottomRight: int
];
/**
 * 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.
 */
export declare function getTopLeftWall(): GridEntity | undefined;
/**
 * 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.
 */
export declare function getTopLeftWallGridIndex(): int;
/**
 * 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.
 */
export declare function isGridEntityBreakableByExplosion(gridEntity: GridEntity): boolean;
/**
 * 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.
 */
export declare function isGridEntityBroken(gridEntity: GridEntity): boolean;
/**
 * 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.
 */
export declare function isGridEntityXMLType(num: number): num is GridEntityXMLType;
/**
 * 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.
 */
export declare function isGridIndexAdjacentToDoor(gridIndex: int): boolean;
/** Helper function to see if a `GridEntityXMLType` is some kind of poop. */
export declare function isPoopGridEntityXMLType(gridEntityXMLType: GridEntityXMLType): boolean;
/**
 * 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.
 */
export declare function isPostBossVoidPortal(gridEntity: GridEntity): boolean;
/**
 * 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:
 *
 * ```ts
 * removeAllGridEntitiesExcept(
 *   GridEntityType.WALL,
 *   GridEntityType.DOOR,
 * );
 * ```
 *
 * @returns The grid entities that were removed.
 */
export declare function removeAllGridEntitiesExcept(...gridEntityTypes: readonly GridEntityType[]): readonly GridEntity[];
/**
 * 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:
 *
 * ```ts
 * removeAllMatchingGridEntities(
 *   GridEntityType.ROCK,
 *   GridEntityType.BLOCK,
 *   GridEntityType.ROCK_TINTED,
 * );
 * ```
 *
 * @returns An array of the grid entities removed.
 */
export declare function removeAllMatchingGridEntities(...gridEntityType: readonly GridEntityType[]): readonly GridEntity[];
/**
 * 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.
 */
export declare function removeEntitiesSpawnedFromGridEntity(entities: readonly Entity[], gridEntity: GridEntity): void;
/**
 * Helper function to remove all of the grid entities in the supplied array.
 *
 * @param gridEntities The array of grid entities to remove.
 * @param updateRoom 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.
 * @param cap Optional. If specified, will only remove the given amount of entities.
 * @returns An array of the entities that were removed.
 */
export declare function removeGridEntities<T extends AnyGridEntity>(gridEntities: readonly T[], updateRoom: boolean, cap?: int): readonly T[];
/**
 * 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.)
 *
 * @param gridEntityOrGridIndex The grid entity or grid index to remove.
 * @param updateRoom 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.
 */
export declare function removeGridEntity(gridEntityOrGridIndex: GridEntity | int, updateRoom: boolean): void;
/**
 * 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.)
 */
export declare function setGridEntityInvisible(gridEntity: GridEntity): void;
/**
 * 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.
 */
export declare function setGridEntityType(gridEntity: GridEntity, gridEntityType: GridEntityType): void;
/**
 * Helper function to spawn a giant poop. This is performed by spawning each of the four quadrant
 * grid entities in the appropriate positions.
 *
 * @returns Whether spawning the four quadrants was successful.
 */
export declare function spawnGiantPoop(topLeftGridIndex: int): boolean;
/**
 * 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
 *
 * @param gridEntityType The `GridEntityType` to use.
 * @param gridIndexOrPosition 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.
 * @param removeExistingGridEntity 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.
 */
export declare function spawnGridEntity(gridEntityType: GridEntityType, gridIndexOrPosition: int | Vector, removeExistingGridEntity?: boolean): GridEntity | undefined;
/**
 * 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
 *
 * @param gridEntityType The `GridEntityType` to use.
 * @param variant The variant to use.
 * @param gridIndexOrPosition 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.
 * @param removeExistingGridEntity 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.
 */
export declare function spawnGridEntityWithVariant(gridEntityType: GridEntityType, variant: int, gridIndexOrPosition: int | Vector, removeExistingGridEntity?: boolean): GridEntity | undefined;
/**
 * 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.
 */
export declare function spawnVoidPortal(gridIndex: int): GridEntity | undefined;
//# sourceMappingURL=gridEntities.d.ts.map