isaacscript-common 3.17.0 → 4.0.2

package/cachedClasses.ts

@@ -0,0 +1,39 @@
+/**
+ * A cached version of the class returned from the `Game()` constructor.
+ *
+ * Use this instead of invoking the constructor again for a miniscule performance increase.
+ *
+ * Caching the results of this constructor is safe, but caching other classes (like `Level` or
+ * `Room`) is not safe and can lead to the game crashing in certain situations.
+ */
+export const game = Game();
+
+/**
+ * A cached version of the class returned from the `Isaac.GetItemConfig()` constructor.
+ *
+ * Use this instead of invoking the constructor again for a miniscule performance increase.
+ *
+ * Caching the results of this constructor is safe, but caching other classes (like `Level` or
+ * `Room`) is not safe and can lead to the game crashing in certain situations.
+ */
+export const itemConfig = Isaac.GetItemConfig();
+
+/**
+ * A cached version of the class returned from the `MusicManager()` constructor.
+ *
+ * Use this instead of invoking the constructor again for a miniscule performance increase.
+ *
+ * Caching the results of this constructor is safe, but caching other classes (like `Level` or
+ * `Room`) is not safe and can lead to the game crashing in certain situations.
+ */
+export const musicManager = MusicManager();
+
+/**
+ * A cached version of the class returned from the `SFXManager()` constructor.
+ *
+ * Use this instead of invoking the constructor again for a miniscule performance increase.
+ *
+ * Caching the results of this constructor is safe, but caching other classes (like `Level` or
+ * `Room`) is not safe and can lead to the game crashing in certain situations.
+ */
+export const sfxManager = SFXManager();

package/callbacks/customRevive.lua

@@ -82,9 +82,10 @@ function checkWaitingForItemAnimation(self, player)
 end
 function postPlayerFatalDamage(self, player)
     if not hasSubscriptions(nil) then
-        return
+        return nil
     end
     playerIsAboutToDie(nil, player)
+    return nil
 end
 function preBerserkDeath(self, player)
     if not hasSubscriptions(nil) then

package/callbacks/customRevive.ts

@@ -0,0 +1,215 @@
+// This provides the logic for:
+// - PRE_CUSTOM_REVIVE
+// - POST_CUSTOM_REVIVE
+
+import {
+  CollectibleType,
+  FamiliarVariant,
+  ModCallback,
+  PlayerType,
+  SoundEffect,
+} from "isaac-typescript-definitions";
+import { sfxManager } from "../cachedClasses";
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { runNextGameFrame } from "../features/runInNFrames";
+import { saveDataManager } from "../features/saveDataManager/exports";
+import { removeCollectibleFromItemTracker } from "../functions/collectibles";
+import { removeAllFamiliars } from "../functions/entitySpecific";
+import { log, logError } from "../functions/log";
+import { isCharacter } from "../functions/player";
+import { getPlayerFromIndex, getPlayerIndex } from "../functions/playerIndex";
+import { PlayerIndex } from "../types/PlayerIndex";
+import {
+  postCustomReviveFire,
+  postCustomReviveHasSubscriptions,
+} from "./subscriptions/postCustomRevive";
+import {
+  preCustomReviveFire,
+  preCustomReviveHasSubscriptions,
+} from "./subscriptions/preCustomRevive";
+
+const DEBUG = false;
+
+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,
+}
+
+const v = {
+  run: {
+    state: CustomReviveState.DISABLED,
+    revivalType: null as int | null,
+    dyingPlayerIndex: null as PlayerIndex | null,
+  },
+};
+
+/** @internal */
+export function customReviveCallbacksInit(mod: ModUpgraded): void {
+  saveDataManager("customRevive", v, hasSubscriptions);
+
+  mod.AddCallback(ModCallback.POST_RENDER, postRender); // 2
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_NEW_ROOM_REORDERED,
+    postNewRoomReordered,
+  );
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED,
+    postPEffectUpdateReordered,
+  );
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_PLAYER_FATAL_DAMAGE,
+    postPlayerFatalDamage,
+  );
+  mod.AddCallbackCustom(ModCallbackCustom.PRE_BERSERK_DEATH, preBerserkDeath);
+}
+
+function hasSubscriptions() {
+  return (
+    preCustomReviveHasSubscriptions() || postCustomReviveHasSubscriptions()
+  );
+}
+
+// ModCallback.POST_RENDER (2)
+function postRender() {
+  if (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
+function postNewRoomReordered() {
+  if (v.run.state !== CustomReviveState.WAITING_FOR_ROOM_TRANSITION) {
+    return;
+  }
+
+  v.run.state = CustomReviveState.WAITING_FOR_ITEM_ANIMATION;
+  logStateChanged();
+}
+
+// ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED
+function postPEffectUpdateReordered(player: EntityPlayer) {
+  checkWaitingForItemAnimation(player);
+}
+
+function checkWaitingForItemAnimation(player: EntityPlayer) {
+  if (v.run.state !== CustomReviveState.WAITING_FOR_ITEM_ANIMATION) {
+    return;
+  }
+
+  if (v.run.dyingPlayerIndex === null) {
+    return;
+  }
+
+  const playerIndex = getPlayerIndex(player);
+  if (playerIndex !== v.run.dyingPlayerIndex) {
+    return;
+  }
+
+  let playerToCheckHoldingItem = player;
+  if (isCharacter(player, PlayerType.THE_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 (v.run.revivalType !== null) {
+    postCustomReviveFire(playerToCheckHoldingItem, v.run.revivalType);
+  }
+
+  v.run.state = CustomReviveState.DISABLED;
+  v.run.revivalType = null;
+  v.run.dyingPlayerIndex = null;
+  logStateChanged();
+}
+
+// ModCallbackCustom.POST_PLAYER_FATAL_DAMAGE
+function postPlayerFatalDamage(player: EntityPlayer): boolean | undefined {
+  if (!hasSubscriptions()) {
+    return undefined;
+  }
+
+  playerIsAboutToDie(player);
+  return undefined;
+}
+
+// ModCallbackCustom.PRE_BERSERK_DEATH
+function preBerserkDeath(player: EntityPlayer) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  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.
+ */
+function playerIsAboutToDie(player: EntityPlayer) {
+  const revivalType = preCustomReviveFire(player);
+  if (revivalType === undefined) {
+    return;
+  }
+
+  v.run.state = CustomReviveState.WAITING_FOR_ROOM_TRANSITION;
+  v.run.revivalType = revivalType;
+  v.run.dyingPlayerIndex = getPlayerIndex(player);
+  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();
+  });
+}
+
+function logStateChanged() {
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (DEBUG) {
+    log(
+      `Custom revive state changed: ${CustomReviveState[v.run.state]} (${
+        v.run.state
+      })`,
+    );
+  }
+}

package/callbacks/itemPickup.ts

@@ -0,0 +1,101 @@
+// This provides the logic for:
+// - PRE_ITEM_PICKUP
+// - POST_ITEM_PICKUP
+
+import {
+  CollectibleType,
+  ItemType,
+  TrinketType,
+} from "isaac-typescript-definitions";
+import { DefaultMap } from "../classes/DefaultMap";
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { saveDataManager } from "../features/saveDataManager/exports";
+import { defaultMapGetPlayer } from "../functions/playerDataStructures";
+import {
+  newPickingUpItem,
+  PickingUpItem,
+  resetPickingUpItem,
+} from "../types/PickingUpItem";
+import { PlayerIndex } from "../types/PlayerIndex";
+import {
+  postItemPickupFire,
+  postItemPickupHasSubscriptions,
+} from "./subscriptions/postItemPickup";
+import {
+  preItemPickupFire,
+  preItemPickupHasSubscriptions,
+} from "./subscriptions/preItemPickup";
+
+const v = {
+  run: {
+    playersPickingUpItemMap: new DefaultMap<PlayerIndex, PickingUpItem>(() =>
+      newPickingUpItem(),
+    ),
+  },
+};
+
+/** @internal */
+export function itemPickupCallbacksInit(mod: ModUpgraded): void {
+  saveDataManager("itemPickup", v, hasSubscriptions);
+
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED,
+    postPEffectUpdateReordered,
+  );
+}
+
+function hasSubscriptions() {
+  return preItemPickupHasSubscriptions() || postItemPickupHasSubscriptions();
+}
+
+// ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED
+function postPEffectUpdateReordered(player: EntityPlayer) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  const pickingUpItem = defaultMapGetPlayer(
+    v.run.playersPickingUpItemMap,
+    player,
+  );
+
+  if (player.IsItemQueueEmpty()) {
+    queueEmpty(player, pickingUpItem);
+    // If a player enters a room with a trinket next to the entrance, the player will pick up the
+    // trinket, but it will not become queued (it will be deposited into their inventory
+    // immediately). Since we don't know what type of item the player is holding, don't account for
+    // this bug.
+  } else {
+    queueNotEmpty(player, pickingUpItem);
+  }
+}
+
+function queueEmpty(player: EntityPlayer, pickingUpItem: PickingUpItem) {
+  // eslint-disable-next-line isaacscript/strict-enums
+  if (pickingUpItem.itemType === ItemType.NULL || pickingUpItem.subType === 0) {
+    return;
+  }
+
+  postItemPickupFire(player, pickingUpItem);
+  resetPickingUpItem(pickingUpItem);
+}
+
+function queueNotEmpty(player: EntityPlayer, pickingUpItem: PickingUpItem) {
+  const queuedItem = player.QueuedItem.Item;
+  if (queuedItem === undefined || queuedItem.Type === ItemType.NULL) {
+    // This should never happen, since the `EntityPlayer.IsItemQueueEmpty` method returned true.
+    return;
+  }
+
+  if (
+    queuedItem.Type !== pickingUpItem.itemType ||
+    queuedItem.ID !== pickingUpItem.subType
+  ) {
+    // Record which item we are picking up.
+    pickingUpItem.itemType = queuedItem.Type;
+    pickingUpItem.subType = queuedItem.ID as CollectibleType | TrinketType;
+
+    preItemPickupFire(player, pickingUpItem);
+  }
+}

package/callbacks/postAmbush.ts

@@ -0,0 +1,73 @@
+// This provides the logic for:
+// - POST_AMBUSH_STARTED
+// - POST_AMBUSH_FINISHED
+
+import { ModCallback, RoomType } from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { AmbushType } from "../enums/AmbushType";
+import { saveDataManager } from "../features/saveDataManager/exports";
+import { getRoomType } from "../functions/roomData";
+import {
+  postAmbushFinishedFire,
+  postAmbushFinishedHasSubscriptions,
+} from "./subscriptions/postAmbushFinished";
+import {
+  postAmbushStartedFire,
+  postAmbushStartedHasSubscriptions,
+} from "./subscriptions/postAmbushStarted";
+
+const v = {
+  room: {
+    ambushActive: false,
+    ambushDone: false,
+  },
+};
+
+/** @internal */
+export function postAmbushCallbacksInit(mod: Mod): void {
+  saveDataManager("postAmbushCallbacks", v, hasSubscriptions);
+
+  mod.AddCallback(ModCallback.POST_UPDATE, postUpdate); // 1
+}
+
+function hasSubscriptions() {
+  return (
+    postAmbushStartedHasSubscriptions() || postAmbushFinishedHasSubscriptions()
+  );
+}
+
+// ModCallback.POST_UPDATE (1)
+function postUpdate() {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  const room = game.GetRoom();
+
+  if (!v.room.ambushActive) {
+    const ambushActive = room.IsAmbushActive();
+    if (ambushActive) {
+      v.room.ambushActive = true;
+
+      const ambushType = getAmbushType();
+      postAmbushStartedFire(ambushType);
+    }
+  }
+
+  if (!v.room.ambushDone) {
+    const ambushDone = room.IsAmbushDone();
+    if (ambushDone) {
+      v.room.ambushDone = true;
+
+      const ambushType = getAmbushType();
+      postAmbushFinishedFire(ambushType);
+    }
+  }
+}
+
+function getAmbushType(): AmbushType {
+  const roomType = getRoomType();
+  return roomType === RoomType.BOSS_RUSH
+    ? AmbushType.BOSS_RUSH
+    : AmbushType.CHALLENGE_ROOM;
+}

package/callbacks/postBombExploded.ts

@@ -0,0 +1,26 @@
+import { ModCallback } from "isaac-typescript-definitions";
+import { BOMB_EXPLODE_FRAME } from "../constants";
+import {
+  postBombExplodedFire,
+  postBombExplodedHasSubscriptions,
+} from "./subscriptions/postBoneExploded";
+
+/** @internal */
+export function postBombExplodedInit(mod: Mod): void {
+  mod.AddCallback(ModCallback.POST_BOMB_UPDATE, postBombUpdate); // 58
+}
+
+function hasSubscriptions() {
+  return postBombExplodedHasSubscriptions();
+}
+
+// ModCallback.POST_BOMB_UPDATE (58)
+function postBombUpdate(bomb: EntityBomb) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  if (bomb.FrameCount === BOMB_EXPLODE_FRAME) {
+    postBombExplodedFire(bomb);
+  }
+}

package/callbacks/postBombInitLate.ts

@@ -0,0 +1,36 @@
+import { ModCallback } from "isaac-typescript-definitions";
+import { saveDataManager } from "../features/saveDataManager/exports";
+import {
+  postBombInitLateFire,
+  postBombInitLateHasSubscriptions,
+} from "./subscriptions/postBombInitLate";
+
+const v = {
+  room: {
+    firedSet: new Set<PtrHash>(),
+  },
+};
+
+/** @internal */
+export function postBombInitLateInit(mod: Mod): void {
+  saveDataManager("postBombInitLate", v, hasSubscriptions);
+
+  mod.AddCallback(ModCallback.POST_BOMB_UPDATE, postBombUpdate); // 58
+}
+
+function hasSubscriptions() {
+  return postBombInitLateHasSubscriptions();
+}
+
+// ModCallback.POST_BOMB_UPDATE (58)
+function postBombUpdate(bomb: EntityBomb) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  const index = GetPtrHash(bomb);
+  if (!v.room.firedSet.has(index)) {
+    v.room.firedSet.add(index);
+    postBombInitLateFire(bomb);
+  }
+}

package/callbacks/postBoneSwing.ts

@@ -0,0 +1,64 @@
+import { KnifeVariant, ModCallback } from "isaac-typescript-definitions";
+import { saveDataManager } from "../features/saveDataManager/exports";
+import {
+  postBoneSwingFire,
+  postBoneSwingHasSubscriptions,
+} from "./subscriptions/postBoneSwing";
+
+const BONE_SWING_ANIMATIONS: ReadonlySet<string> = new Set([
+  "Swing",
+  "Swing2",
+  "Spin",
+]);
+
+const v = {
+  room: {
+    boneClubAnimations: new Map<PtrHash, string>(),
+  },
+};
+
+/** @internal */
+export function postBoneSwingInit(mod: Mod): void {
+  saveDataManager("postBoneSwing", v, hasSubscriptions);
+
+  mod.AddCallback(ModCallback.POST_KNIFE_RENDER, postKnifeRender); // 52
+}
+
+function hasSubscriptions() {
+  return postBoneSwingHasSubscriptions();
+}
+
+// ModCallback.POST_KNIFE_RENDER (52)
+function postKnifeRender(knife: EntityKnife) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  // The PostKnifeRender callback cannot be registered with knife variants for some reason.
+  if (knife.Variant !== KnifeVariant.BONE_CLUB) {
+    return;
+  }
+
+  postKnifeRenderBoneClub(knife);
+}
+
+function postKnifeRenderBoneClub(boneClub: EntityKnife) {
+  const sprite = boneClub.GetSprite();
+  const animation = sprite.GetAnimation();
+  const ptrHash = GetPtrHash(boneClub);
+  const animationOnLastFrame = v.room.boneClubAnimations.get(ptrHash);
+  v.room.boneClubAnimations.set(ptrHash, animation);
+
+  if (
+    animationOnLastFrame !== undefined &&
+    animation !== animationOnLastFrame
+  ) {
+    boneClubAnimationChanged(boneClub, animation);
+  }
+}
+
+function boneClubAnimationChanged(boneClub: EntityKnife, animation: string) {
+  if (BONE_SWING_ANIMATIONS.has(animation)) {
+    postBoneSwingFire(boneClub);
+  }
+}

package/callbacks/postCollectibleInitFirst.ts

@@ -0,0 +1,40 @@
+import { ModCallback, PickupVariant } from "isaac-typescript-definitions";
+import { saveDataManager } from "../features/saveDataManager/exports";
+import { getCollectibleIndex } from "../functions/collectibles";
+import { CollectibleIndex } from "../types/CollectibleIndex";
+import {
+  postCollectibleInitFirstFire,
+  postCollectibleInitFirstHasSubscriptions,
+} from "./subscriptions/postCollectibleInitFirst";
+
+const v = {
+  run: {
+    seenCollectibles: new Set<CollectibleIndex>(),
+  },
+};
+
+/** @internal */
+export function postCollectibleInitFirstInit(mod: Mod): void {
+  saveDataManager("postCollectibleInitFirst", v, hasSubscriptions);
+
+  mod.AddCallback(
+    ModCallback.POST_PICKUP_INIT,
+    postPickupInitCollectible,
+    PickupVariant.COLLECTIBLE,
+  ); // 34
+}
+
+function hasSubscriptions() {
+  return postCollectibleInitFirstHasSubscriptions();
+}
+
+function postPickupInitCollectible(pickup: EntityPickup) {
+  const collectible = pickup as EntityPickupCollectible;
+  const collectibleIndex = getCollectibleIndex(collectible);
+  if (v.run.seenCollectibles.has(collectibleIndex)) {
+    return;
+  }
+
+  v.run.seenCollectibles.add(collectibleIndex);
+  postCollectibleInitFirstFire(collectible);
+}

package/callbacks/postCursedTeleport.lua

@@ -30,10 +30,11 @@ function hasSubscriptions(self)
 end
 function entityTakeDmgPlayer(self, tookDamage, _damageAmount, damageFlags, _damageSource, _damageCountdownFrames)
     if not hasSubscriptions(nil) then
-        return
+        return nil
     end
     incrementNumSacrifices(nil, damageFlags)
     setDamageFrame(nil, tookDamage, damageFlags)
+    return nil
 end
 function setDamageFrame(self, tookDamage, damageFlags)
     local gameFrameCount = game:GetFrameCount()