isaacscript-common 14.0.0 → 14.1.1

package/src/classes/callbacks/validation/CustomCallbackSpikes.ts

@@ -1,4 +1,4 @@
-import { MatchingCallbackCustom } from "packages/isaacscript-common/src/types/private/MatchingCallbackCustom";
+import { MatchingCallbackCustom } from "../../../types/private/MatchingCallbackCustom";
 import {
   CustomCallback,
   FireArgs,
@@ -12,7 +12,7 @@ export class CustomCallbackSpikes<
   T extends ModCallbackCustomSpikes,
 > extends CustomCallback<T> {
   // eslint-disable-next-line class-methods-use-this
-  override shouldFire(
+  protected override shouldFire(
     fireArgs: FireArgs<T>,
     optionalArgs: OptionalArgs<T>,
   ): boolean {

package/src/classes/features/callbackLogic/CustomGridEntities.ts

@@ -0,0 +1,398 @@
+import {
+  ActiveSlot,
+  CollectibleType,
+  GridCollisionClass,
+  GridEntityType,
+  ModCallback,
+  UseFlag,
+} from "isaac-typescript-definitions";
+import { game } from "../../../core/cachedClasses";
+import { ISCFeature } from "../../../enums/ISCFeature";
+import { ModCallbackCustom2 } from "../../../enums/ModCallbackCustom2";
+import {
+  removeGridEntity,
+  spawnGridEntityWithVariant,
+} from "../../../functions/gridEntities";
+import { getPlayerFromPtr } from "../../../functions/players";
+import { getRoomListIndex } from "../../../functions/roomData";
+import { isNumber } from "../../../functions/types";
+import { isVector } from "../../../functions/vector";
+import { GridEntityCustomData } from "../../../interfaces/GridEntityCustomData";
+import { DefaultMap } from "../../DefaultMap";
+import { Feature } from "../../private/Feature";
+import { RunInNFrames } from "../other/RunInNFrames";
+
+export class CustomGridEntities extends Feature {
+  public override v = {
+    level: {
+      /** Indexed by room list index and grid index. */
+      customGridEntities: new DefaultMap<int, Map<int, GridEntityCustomData>>(
+        () => new Map(),
+      ),
+    },
+
+    room: {
+      genericPropPtrHashes: new Set<PtrHash>(),
+      manuallyUsingShovel: false,
+    },
+  };
+
+  private runInNFrames: RunInNFrames;
+
+  constructor(runInNFrames: RunInNFrames) {
+    super();
+
+    this.featuresUsed = [ISCFeature.RUN_IN_N_FRAMES];
+
+    this.callbacksUsed = [
+      [
+        ModCallback.PRE_USE_ITEM,
+        [this.preUseItemWeNeedToGoDeeper, CollectibleType.WE_NEED_TO_GO_DEEPER],
+      ], // 23
+    ];
+
+    this.customCallbacksUsed = [
+      [ModCallbackCustom2.POST_NEW_ROOM_REORDERED, [this.postNewRoomReordered]],
+    ];
+
+    this.runInNFrames = runInNFrames;
+  }
+
+  // ModCallback.PRE_USE_ITEM (23)
+  // CollectibleType.WE_NEED_TO_GO_DEEPER (84)
+  private preUseItemWeNeedToGoDeeper = (
+    _collectibleType: CollectibleType,
+    _rng: RNG,
+    player: EntityPlayer,
+    _useFlags: BitFlags<UseFlag>,
+    _activeSlot: ActiveSlot,
+    _customVarData: int,
+  ): boolean | undefined => {
+    // If a player uses We Need to Go Deeper on top of a custom grid entity, then they will always
+    // get a crawlspace, due to how custom grids are implemented with decorations. Thus, remove the
+    // custom grid entity to prevent this from happening if needed.
+    const room = game.GetRoom();
+    const roomListIndex = getRoomListIndex();
+    const roomCustomGridEntities =
+      this.v.level.customGridEntities.get(roomListIndex);
+    if (roomCustomGridEntities === undefined) {
+      return undefined;
+    }
+
+    const gridIndex = room.GetGridIndex(player.Position);
+    const customGridEntity = roomCustomGridEntities.get(gridIndex);
+    if (customGridEntity === undefined) {
+      return undefined;
+    }
+
+    // If the custom grid entity has collision, then the player should not be able to be standing on
+    // top of it.
+    if (customGridEntity.gridCollisionClass !== GridCollisionClass.NONE) {
+      return undefined;
+    }
+
+    removeGridEntity(customGridEntity.gridIndex, false);
+
+    const entityPtr = EntityPtr(player);
+    this.runInNFrames.runNextGameFrame(() => {
+      const futurePlayer = getPlayerFromPtr(entityPtr);
+      if (futurePlayer === undefined) {
+        return;
+      }
+
+      this.v.room.manuallyUsingShovel = true;
+      futurePlayer.UseActiveItem(CollectibleType.WE_NEED_TO_GO_DEEPER);
+      this.v.room.manuallyUsingShovel = false;
+    });
+
+    // Cancel the original effect.
+    return true;
+  };
+
+  // ModCallbackCustom.POST_NEW_ROOM_REORDERED
+  private postNewRoomReordered = (): void => {
+    // When we re-enter a room, the graphics for any custom entities will be reverted back to that
+    // of a normal decoration. Thus, we must re-apply the anm2.
+    const roomListIndex = getRoomListIndex();
+    const roomCustomGridEntities =
+      this.v.level.customGridEntities.get(roomListIndex);
+    if (roomCustomGridEntities === undefined) {
+      return;
+    }
+
+    const room = game.GetRoom();
+    for (const [gridIndex, data] of roomCustomGridEntities.entries()) {
+      const decoration = room.GetGridEntity(gridIndex);
+      if (decoration === undefined) {
+        roomCustomGridEntities.delete(gridIndex);
+        continue;
+      }
+
+      if (data.anm2Path !== undefined) {
+        const sprite = decoration.GetSprite();
+        sprite.Load(data.anm2Path, true);
+        const animationToPlay =
+          data.defaultAnimation === undefined
+            ? sprite.GetDefaultAnimation()
+            : data.defaultAnimation;
+        sprite.Play(animationToPlay, true);
+      }
+    }
+  };
+
+  /**
+   * 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.)
+   *
+   * 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`.
+   * 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.DECORATION,
+    baseGridEntityVariant = 0,
+  ): GridEntity {
+    const room = game.GetRoom();
+    const roomListIndex = getRoomListIndex();
+    const gridIndex = isVector(gridIndexOrPosition)
+      ? room.GetGridIndex(gridIndexOrPosition)
+      : gridIndexOrPosition;
+
+    const customGridEntity = spawnGridEntityWithVariant(
+      baseGridEntityType,
+      baseGridEntityVariant,
+      gridIndexOrPosition,
+    );
+    if (customGridEntity === undefined) {
+      error("Failed to spawn a custom grid entity.");
+    }
+
+    if (gridCollisionClass !== undefined) {
+      customGridEntity.CollisionClass = gridCollisionClass;
+    }
+
+    if (anm2Path !== undefined) {
+      const sprite = customGridEntity.GetSprite();
+      sprite.Load(anm2Path, true);
+      const animationToPlay =
+        defaultAnimation === undefined
+          ? sprite.GetDefaultAnimation()
+          : defaultAnimation;
+      sprite.Play(animationToPlay, true);
+    }
+
+    const customGridEntityData: GridEntityCustomData = {
+      gridEntityTypeCustom,
+      roomListIndex,
+      gridIndex,
+      anm2Path,
+      defaultAnimation,
+      gridCollisionClass,
+    };
+
+    const roomCustomGridEntities =
+      this.v.level.customGridEntities.getAndSetDefault(roomListIndex);
+    roomCustomGridEntities.set(gridIndex, customGridEntityData);
+
+    return customGridEntity;
+  }
+
+  /**
+   * Helper function to remove a custom grid entity created by the `spawnCustomGrid` function.
+   *
+   * @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 or not 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 = true,
+  ): GridEntity | undefined {
+    const room = game.GetRoom();
+    const roomListIndex = getRoomListIndex();
+
+    let decoration: GridEntity;
+    if (typeof gridIndexOrPositionOrGridEntity === "number") {
+      const gridIndex = gridIndexOrPositionOrGridEntity;
+      const gridEntity = room.GetGridEntity(gridIndex);
+      if (gridEntity === undefined) {
+        return undefined;
+      }
+
+      decoration = gridEntity;
+    } else if (isVector(gridIndexOrPositionOrGridEntity)) {
+      const position = gridIndexOrPositionOrGridEntity;
+      const gridEntity = room.GetGridEntityFromPos(position);
+      if (gridEntity === undefined) {
+        return undefined;
+      }
+
+      decoration = gridEntity;
+    } else {
+      decoration = gridIndexOrPositionOrGridEntity;
+    }
+
+    const gridIndex = decoration.GetGridIndex();
+    const roomCustomGridEntities =
+      this.v.level.customGridEntities.getAndSetDefault(roomListIndex);
+    const exists = roomCustomGridEntities.has(gridIndex);
+    if (!exists) {
+      return undefined;
+    }
+
+    roomCustomGridEntities.delete(gridIndex);
+    removeGridEntity(decoration, updateRoom);
+
+    return decoration;
+  }
+
+  /**
+   * 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.
+   */
+  public getCustomGridEntities(): Array<
+    [gridEntity: GridEntity, data: GridEntityCustomData]
+  > {
+    const roomListIndex = getRoomListIndex();
+    const roomCustomGridEntities =
+      this.v.level.customGridEntities.get(roomListIndex);
+    if (roomCustomGridEntities === undefined) {
+      return [];
+    }
+
+    const room = game.GetRoom();
+    const customGridEntities: Array<[GridEntity, GridEntityCustomData]> = [];
+    for (const [gridIndex, data] of roomCustomGridEntities.entries()) {
+      const gridEntity = room.GetGridEntity(gridIndex);
+      if (gridEntity !== undefined) {
+        customGridEntities.push([gridEntity, data]);
+      }
+    }
+
+    return customGridEntities;
+  }
+
+  /**
+   * 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.
+   */
+  public getCustomGridEntityType(
+    gridEntityOrGridIndex: GridEntity | int,
+  ): GridEntityType | undefined {
+    if (!this.initialized) {
+      return undefined;
+    }
+
+    const gridIndex = isNumber(gridEntityOrGridIndex)
+      ? gridEntityOrGridIndex
+      : gridEntityOrGridIndex.GetGridIndex();
+
+    const roomListIndex = getRoomListIndex();
+    const roomCustomGridEntities =
+      this.v.level.customGridEntities.get(roomListIndex);
+    if (roomCustomGridEntities === undefined) {
+      return undefined;
+    }
+
+    for (const [_gridIndex, data] of roomCustomGridEntities.entries()) {
+      if (data.gridIndex === gridIndex) {
+        return data.gridEntityTypeCustom;
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Helper function to check if a `GridEntity` is a custom grid entity or if a grid index has a
+   * custom grid entity.
+   */
+  public isCustomGridEntity(gridEntityOrGridIndex: GridEntity | int): boolean {
+    const gridEntityTypeCustom = this.getCustomGridEntityType(
+      gridEntityOrGridIndex,
+    );
+    return gridEntityTypeCustom !== undefined;
+  }
+}

package/src/classes/features/callbackLogic/CustomRevive.ts

@@ -0,0 +1,214 @@
+// This provides the logic for the following callbacks:
+// - `PRE_CUSTOM_REVIVE`
+// - `POST_CUSTOM_REVIVE`
+
+import {
+  CollectibleType,
+  FamiliarVariant,
+  ModCallback,
+  PlayerType,
+  SoundEffect,
+} from "isaac-typescript-definitions";
+import { sfxManager } from "../../../core/cachedClasses";
+import { ModCallbackCustom2 } from "../../../enums/ModCallbackCustom2";
+import { runNextGameFrame } from "../../../features/runInNFrames";
+import { removeCollectibleFromItemTracker } from "../../../functions/collectibles";
+import { removeAllFamiliars } from "../../../functions/entitiesSpecific";
+import { log } from "../../../functions/log";
+import { logError } from "../../../functions/logMisc";
+import {
+  getPlayerFromIndex,
+  getPlayerIndex,
+} from "../../../functions/playerIndex";
+import { isCharacter } from "../../../functions/players";
+import { PlayerIndex } from "../../../types/PlayerIndex";
+import { PostCustomRevive } from "../../callbacks/PostCustomRevive";
+import { PreCustomRevive } from "../../callbacks/PreCustomRevive";
+import { Feature } from "../../private/Feature";
+
+const DEBUG = false as boolean;
+
+enum CustomReviveState {
+  DISABLED,
+
+  /**
+   * We can't immediately jump to waiting for an item animation because it is possible for a player
+   * to be holding an item above their head as they are dying (e.g. with Razor Blade).
+   */
+  WAITING_FOR_ROOM_TRANSITION,
+
+  WAITING_FOR_ITEM_ANIMATION,
+}
+
+export class CustomRevive extends Feature {
+  public override v = {
+    run: {
+      state: CustomReviveState.DISABLED,
+      revivalType: null as int | null,
+      dyingPlayerIndex: null as PlayerIndex | null,
+    },
+  };
+
+  private preCustomRevive: PreCustomRevive;
+  private postCustomRevive: PostCustomRevive;
+
+  constructor(
+    preCustomRevive: PreCustomRevive,
+    postCustomRevive: PostCustomRevive,
+  ) {
+    super();
+
+    this.callbacksUsed = [
+      [ModCallback.POST_RENDER, [this.postRender]], // 2
+    ];
+
+    this.customCallbacksUsed = [
+      [ModCallbackCustom2.POST_NEW_ROOM_REORDERED, [this.postNewRoomReordered]],
+      [
+        ModCallbackCustom2.POST_PEFFECT_UPDATE_REORDERED,
+        [this.postPEffectUpdateReordered],
+      ],
+      [
+        ModCallbackCustom2.POST_PLAYER_FATAL_DAMAGE,
+        [this.postPlayerFatalDamage],
+      ],
+      [ModCallbackCustom2.PRE_BERSERK_DEATH, [this.preBerserkDeath]],
+    ];
+
+    this.preCustomRevive = preCustomRevive;
+    this.postCustomRevive = postCustomRevive;
+  }
+
+  // ModCallback.POST_RENDER (2)
+  private postRender = (): void => {
+    if (this.v.run.state !== CustomReviveState.WAITING_FOR_ITEM_ANIMATION) {
+      return;
+    }
+
+    // The 1-up sound will fire before the item holding animation begins, so we mute it on every
+    // render frame.
+    sfxManager.Stop(SoundEffect.ONE_UP);
+  };
+
+  // ModCallbackCustom.POST_NEW_ROOM_REORDERED
+  private postNewRoomReordered = (): void => {
+    if (this.v.run.state !== CustomReviveState.WAITING_FOR_ROOM_TRANSITION) {
+      return;
+    }
+
+    this.v.run.state = CustomReviveState.WAITING_FOR_ITEM_ANIMATION;
+    this.logStateChanged();
+  };
+
+  // ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED
+  private postPEffectUpdateReordered = (player: EntityPlayer): void => {
+    this.checkWaitingForItemAnimation(player);
+  };
+
+  private checkWaitingForItemAnimation(player: EntityPlayer): void {
+    if (this.v.run.state !== CustomReviveState.WAITING_FOR_ITEM_ANIMATION) {
+      return;
+    }
+
+    if (this.v.run.dyingPlayerIndex === null) {
+      return;
+    }
+
+    const playerIndex = getPlayerIndex(player);
+    if (playerIndex !== this.v.run.dyingPlayerIndex) {
+      return;
+    }
+
+    let playerToCheckHoldingItem = player;
+    if (isCharacter(player, PlayerType.SOUL_B)) {
+      const forgottenBody = player.GetOtherTwin();
+      if (forgottenBody !== undefined) {
+        playerToCheckHoldingItem = forgottenBody;
+      }
+    }
+
+    if (!playerToCheckHoldingItem.IsHoldingItem()) {
+      return;
+    }
+
+    // The player is now playing the animation where they hold the 1-Up item overhead. The
+    // `EntityPlayer.StopExtraAnimation` method will not work to stop this animation. End-users are
+    // expected to play a new animation in the PostCustomRevive callback, which will overwrite the
+    // 1-Up animation.
+
+    if (this.v.run.revivalType !== null) {
+      this.postCustomRevive.fire(
+        playerToCheckHoldingItem,
+        this.v.run.revivalType,
+      );
+    }
+
+    this.v.run.state = CustomReviveState.DISABLED;
+    this.v.run.revivalType = null;
+    this.v.run.dyingPlayerIndex = null;
+    this.logStateChanged();
+  }
+
+  // ModCallbackCustom.POST_PLAYER_FATAL_DAMAGE
+  private postPlayerFatalDamage = (
+    player: EntityPlayer,
+  ): boolean | undefined => {
+    this.playerIsAboutToDie(player);
+    return undefined;
+  };
+
+  // ModCallbackCustom.PRE_BERSERK_DEATH
+  private preBerserkDeath = (player: EntityPlayer): void => {
+    this.playerIsAboutToDie(player);
+  };
+
+  /**
+   * The player is about to die, which will immediately delete the save data for the run. To prevent
+   * this from happening, we grant the 1-Up item.
+   */
+  private playerIsAboutToDie(player: EntityPlayer): void {
+    const revivalType = this.preCustomRevive.fire(player);
+    if (revivalType === undefined) {
+      return;
+    }
+
+    this.v.run.state = CustomReviveState.WAITING_FOR_ROOM_TRANSITION;
+    this.v.run.revivalType = revivalType;
+    this.v.run.dyingPlayerIndex = getPlayerIndex(player);
+    this.logStateChanged();
+
+    player.AddCollectible(CollectibleType.ONE_UP, 0, false);
+    removeAllFamiliars(FamiliarVariant.ONE_UP);
+    removeCollectibleFromItemTracker(CollectibleType.ONE_UP);
+
+    // The player should always be dead one frame from now. If they are not, then something has gone
+    // wrong, probably with the `isDamageToPlayerFatal` function. Since end-user code is already
+    // assuming that a custom revive is occurring, explicitly kill the player.
+    const playerIndex = getPlayerIndex(player);
+    runNextGameFrame(() => {
+      const futurePlayer = getPlayerFromIndex(playerIndex);
+      if (futurePlayer === undefined) {
+        return;
+      }
+
+      if (futurePlayer.IsDead()) {
+        return;
+      }
+
+      logError(
+        "The player is still alive after initializing a custom revive. Explicitly killing the player.",
+      );
+      futurePlayer.Kill();
+    });
+  }
+
+  private logStateChanged(): void {
+    if (DEBUG) {
+      log(
+        `Custom revive state changed: ${CustomReviveState[this.v.run.state]} (${
+          this.v.run.state
+        })`,
+      );
+    }
+  }
+}