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

Helper functions and features for IsaacScript mods.

import { EntityType } from "isaac-typescript-definitions";
import type { AnyEntity } from "../types/AnyEntity";
import type { EntityID } from "../types/EntityID";
/**
 * 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 Optional. Default is -1, which matches every entity type.
 * @param variant Optional. Default is -1, which matches every variant.
 * @param subType Optional. Default is -1, which matches every sub-type.
 * @param ignoreFriendly Optional. Default is false. Will throw a runtime error if set to true and
 *                       the `entityType` is equal to -1.
 */
export declare function countEntities(entityType?: EntityType | -1, variant?: number, subType?: number, ignoreFriendly?: boolean): int;
/**
 * Helper function to check if one or more matching entities exist in the current room. It uses the
 * `doesEntityExist` helper function to determine this.
 *
 * @param entityTypes 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.
 * @param ignoreFriendly Optional. Default is false.
 */
export declare function doesAnyEntityExist(entityTypes: readonly EntityType[] | ReadonlySet<EntityType>, ignoreFriendly?: boolean): boolean;
/**
 * 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.
 *
 * @param entityType Optional. Default is -1, which matches every entity type.
 * @param variant Optional. Default is -1, which matches every variant.
 * @param subType Optional. Default is -1, which matches every sub-type.
 * @param ignoreFriendly Optional. Default is false.
 */
export declare function doesEntityExist(entityType?: EntityType | -1, variant?: number, subType?: number, ignoreFriendly?: boolean): boolean;
/**
 * 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);
 * ```
 *
 * @param referenceEntity The entity that is close by.
 * @param entities The array of entities to look through.
 * @param filterFunc Optional. A function to filter for a specific type of entity, like e.g. an
 *                   enemy with a certain amount of HP left.
 */
export declare function getClosestEntityTo<T extends AnyEntity>(referenceEntity: Entity, entities: readonly T[], filterFunc?: (entity: T) => boolean): T | undefined;
/** Helper function to get the entity type, variant, and sub-type from an `EntityID`. */
export declare function getConstituentsFromEntityID(entityID: EntityID): [entityType: EntityType, variant: int, subType: int];
/**
 * 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 get the entities that match the type. Default
 *                   is -1, which matches every type.
 * @param variant Optional. If specified, will only get the entities that match the variant. Default
 *                is -1, which matches every variant.
 * @param subType Optional. If specified, will only get the entities that match the sub-type.
 *                Default is -1, which 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 the
 *                       `entityType` is specified.
 */
export declare function getEntities(entityType?: EntityType | -1, variant?: number, subType?: number, ignoreFriendly?: boolean): readonly Entity[];
/**
 * 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.
 */
export declare function getEntityFields(entity: Entity): LuaMap<string, boolean | number | string>;
/**
 * 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`.
 */
export declare function getEntityFromPtrHash(ptrHash: PtrHash): Entity | undefined;
/** Helper function to get a string containing the entity's type, variant, and sub-type. */
export declare function getEntityID(entity: Entity): EntityID;
/**
 * Helper function to get a formatted string in the format returned by the `getEntityID` function.
 */
export declare function getEntityIDFromConstituents(entityType: EntityType, variant: int, subType: int): EntityID;
/**
 * Helper function to compare two different arrays of entities. Returns the entities that are in the
 * second array but not in the first array.
 */
export declare function getFilteredNewEntities<T extends AnyEntity>(oldEntities: readonly T[], newEntities: readonly T[]): readonly T[];
/**
 * 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
 */
export declare function hasArmor(entity: Entity): boolean;
/**
 * 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.
 */
export declare function isActiveEnemy(entity: Entity): boolean;
/**
 * 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.
 *
 * @param entity The entity whose velocity to measure.
 * @param threshold Optional. The threshold from 0 to consider to be moving. Default is 0.01.
 */
export declare function isEntityMoving(entity: Entity, threshold?: number): boolean;
/**
 * 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.
 */
export declare function parseEntityID(entityID: string): [entityType: EntityType, variant: int, subType: int] | undefined;
/**
 * 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.
 */
export declare function parseEntityTypeVariantString(entityTypeVariantString: string): [entityType: EntityType, variant: int] | undefined;
/**
 * 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, which matches every variant.
 * @param entitySubType Optional. The sub-type to match. Default is -1, which 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.
 */
export declare function removeAllMatchingEntities(entityType: EntityType, entityVariant?: number, entitySubType?: number, cap?: int | undefined): readonly Entity[];
/**
 * 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.
 */
export declare function removeEntities<T extends AnyEntity>(entities: readonly T[], cap?: int): readonly T[];
/**
 * 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.
 */
export declare function rerollEnemy(entity: Entity): Entity | undefined;
/**
 * 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.
 */
export declare function setEntityDamageFlash(entity: Entity): void;
/**
 * Helper function to keep an entity's color the same values as it already is but set the opacity to
 * a specific value.
 *
 * @param entity The entity to set.
 * @param alpha A value between 0 and 1 that represents the fade amount.
 */
export declare function setEntityOpacity(entity: Entity, alpha: float): void;
export declare function setEntityRandomColor(entity: Entity): void;
/**
 * 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.
 *
 * @param entityType The `EntityType` of the entity to spawn.
 * @param variant The variant of the entity to spawn.
 * @param subType The sub-type of the entity to spawn.
 * @param positionOrGridIndex The position or grid index of the entity to spawn.
 * @param velocity Optional. The velocity of the entity to spawn. Default is `VectorZero`.
 * @param spawner Optional. The entity that will be the `SpawnerEntity`. Default is undefined.
 * @param seedOrRNG 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.
 */
export declare function spawn(entityType: EntityType, variant: int, subType: int, positionOrGridIndex: Vector | int, velocity?: Vector, spawner?: Entity | undefined, seedOrRNG?: Seed | RNG | undefined): Entity;
/**
 * Helper function to spawn the entity corresponding to an `EntityID`.
 *
 * @param entityID The `EntityID` of the entity to spawn.
 * @param positionOrGridIndex The position or grid index of the entity to spawn.
 * @param velocity Optional. The velocity of the entity to spawn. Default is `VectorZero`.
 * @param spawner Optional. The entity that will be the `SpawnerEntity`. Default is undefined.
 * @param seedOrRNG 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.
 */
export declare function spawnEntityID(entityID: EntityID, positionOrGridIndex: Vector | int, velocity?: Vector, spawner?: Entity | undefined, seedOrRNG?: Seed | RNG | undefined): Entity;
/**
 * 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.
 */
export declare function spawnWithSeed(entityType: EntityType, variant: int, subType: int, positionOrGridIndex: Vector | int, seedOrRNG: Seed | RNG, velocity?: Vector, spawner?: Entity | undefined): Entity;
//# sourceMappingURL=entities.d.ts.map