isaacscript-common/dist/classes/features/callbackLogic/CustomGridEntities.d.ts

Helper functions and features for IsaacScript mods.

import { GridCollisionClass, GridEntityType } from "isaac-typescript-definitions";
import type { GridEntityCustomData } from "../../../interfaces/GridEntityCustomData";
import { Feature } from "../../private/Feature";
export declare class CustomGridEntities extends Feature {
    private readonly runInNFrames;
    private readonly preUseItemWeNeedToGoDeeper;
    private readonly postNewRoomReordered;
    /**
     * Helper function to spawn a custom grid entity. Custom grid entities are persistent in that they
     * will reappear if the player leaves and re-enters the room. (It will be manually respawned in
     * the `POST_NEW_ROOM` callback.)
     *
     * In order to use this function, you must upgrade your mod with
     * `ISCFeature.CUSTOM_GRID_ENTITIES`.
     *
     * Custom grid entities are built on top of real grid entities. You can use any existing grid
     * entity type as a base. For example, if you want to create a custom rock that would be breakable
     * like a normal rock, then you should specify `GridEntityType.ROCK` as the base grid entity type.
     *
     * Once a custom grid entity is spawned, you can take advantage of the custom grid callbacks such
     * as `POST_GRID_ENTITY_CUSTOM_UPDATE`. Note that the "normal" grid entities callbacks will not
     * fire for custom entities. For example, if you had a custom grid entity based on
     * `GridEntityType.ROCK`, and you also had a subscription to the `POST_GRID_ENTITY_UPDATE`
     * callback, the callback would only fire for normal rocks and not the custom entity.
     *
     * Custom grid entities are an IsaacScript feature because the vanilla game does not support any
     * custom grid entities.
     *
     * For example, this would be code to create a custom rock called a "Silver Rock" that produces a
     * dime when destroyed:
     *
     * ```ts
     * // This is local to the mod and can safely overlap with the values of `GridEntityType` (or
     * // values chosen by other mods).
     * const GridEntityTypeCustom = {
     *   SILVER_ROCK: 0 as GridEntityType,
     * } as const;
     *
     * // This is copied from "gfx/grid/grid_rock.anm2" with some tweaks to make it look special.
     * const SILVER_ROCK_ANM2_PATH = "gfx/grid/grid_rock_silver.anm2";
     *
     * export function silverRockInit(mod: ModUpgraded): void {
     *   mod.AddCallbackCustom(
     *     ModCallbackCustom.POST_GRID_ENTITY_CUSTOM_BROKEN,
     *     postGridEntityCustomBrokenSilverRock,
     *     GridEntityTypeCustom.SILVER_ROCK,
     *   );
     * }
     *
     * function postGridEntityCustomBrokenSilverRock(gridEntity: GridEntity) {
     *   spawnCoin(CoinSubType.DIME, gridEntity.Position);
     * }
     *
     * export function spawnSilverRock(mod: ModUpgraded, gridIndex: int): GridEntity {
     *   return mod.spawnCustomGridEntity(
     *     GridEntityTypeCustom.SILVER_ROCK,
     *     gridIndex,
     *     undefined,
     *     SILVER_ROCK_ANM2_PATH,
     *     undefined,
     *     GridEntityType.ROCK,
     *   );
     * }
     * ```
     *
     * @param gridEntityTypeCustom An integer that identifies what kind of grid entity you are
     *                             creating. It should correspond to a local enum value created in
     *                             your mod. The integer can be any unique value and will not
     *                             correspond to the actual grid entity type used. (This integer is
     *                             used in the various custom grid entity callbacks.)
     * @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 gridCollisionClass Optional. The collision class that you want the custom grid entity to
     *                           have. If not specified, the grid collision class from the base grid
     *                           entity will be used.
     * @param anm2Path Optional. The path to the ANM2 file to use for the sprite. If not specified,
     *                 the normal sprite from the base grid entity will be used.
     * @param defaultAnimation Optional. The name of the animation to play after the sprite is
     *                         initialized and after the player re-enters a room with this grid entity
     *                         in it. If not specified, the default animation in the anm2 will be
     *                         used.
     * @param baseGridEntityType Optional. The type of the grid entity to use as a "base" for this
     *                           custom grid entity. Default is `GridEntityType.DECORATION`.
     * @param baseGridEntityVariant Optional. The variant of the grid entity to use as a "base" for
     *                              this custom grid entity. Default is 0.
     * @public
     */
    spawnCustomGridEntity(gridEntityTypeCustom: GridEntityType, gridIndexOrPosition: int | Vector, gridCollisionClass?: GridCollisionClass, anm2Path?: string, defaultAnimation?: string, baseGridEntityType?: GridEntityType, baseGridEntityVariant?: number): GridEntity;
    /**
     * Helper function to remove a custom grid entity created by the `spawnCustomGrid` function.
     *
     * In order to use this function, you must upgrade your mod with
     * `ISCFeature.CUSTOM_GRID_ENTITIES`.
     *
     * @param gridIndexOrPositionOrGridEntity You can specify the custom grid entity to remove by
     *                                providing the grid index, the room position, or the grid entity
     *                                itself.
     * @param updateRoom Optional. Whether to update the room after the grid entity is removed.
     *                   Default is true. 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 it to false if you need to run this
     *                   function multiple times.
     * @returns The grid entity that was removed. Returns undefined if no grid entity was found at the
     *          given location or if the given grid entity was not a custom grid entity.
     * @public
     */
    removeCustomGridEntity(gridIndexOrPositionOrGridEntity: int | Vector | GridEntity, updateRoom?: boolean): GridEntity | undefined;
    /**
     * Helper function to get the custom grid entities in the current room. Returns an array of tuples
     * containing the raw decoration grid entity and the associated entity data.
     *
     * In order to use this function, you must upgrade your mod with
     * `ISCFeature.CUSTOM_GRID_ENTITIES`.
     *
     * @public
     */
    getCustomGridEntities(): ReadonlyArray<{
        gridEntity: GridEntity;
        data: GridEntityCustomData;
    }>;
    /**
     * Helper function to get the custom `GridEntityType` from a `GridEntity` or grid index. Returns
     * undefined if the provided `GridEntity` is not a custom grid entity, or if there was not a grid
     * entity on the provided grid index.
     *
     * In order to use this function, you must upgrade your mod with
     * `ISCFeature.CUSTOM_GRID_ENTITIES`.
     *
     * @public
     */
    getCustomGridEntityType(gridEntityOrGridIndex: GridEntity | int): GridEntityType | undefined;
    /**
     * Helper function to check if a `GridEntity` is a custom grid entity or if a grid index has a
     * custom grid entity.
     *
     * In order to use this function, you must upgrade your mod with
     * `ISCFeature.CUSTOM_GRID_ENTITIES`.
     *
     * @public
     */
    isCustomGridEntity(gridEntityOrGridIndex: GridEntity | int): boolean;
}
//# sourceMappingURL=CustomGridEntities.d.ts.map