isaacscript-common 4.0.0 → 4.0.3

package/callbacks/postTransformation.ts

@@ -0,0 +1,59 @@
+import { PlayerForm } 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 { getEnumValues } from "../functions/enums";
+import { defaultMapGetPlayer } from "../functions/playerDataStructures";
+import { PlayerIndex } from "../types/PlayerIndex";
+import {
+  postTransformationFire,
+  postTransformationHasSubscriptions,
+} from "./subscriptions/postTransformation";
+
+const PLAYER_FORMS: readonly PlayerForm[] = getEnumValues(PlayerForm);
+
+const v = {
+  run: {
+    playersTransformationsMap: new DefaultMap<
+      PlayerIndex,
+      DefaultMap<PlayerForm, boolean>
+    >(() => new DefaultMap(false)),
+  },
+};
+
+/** @internal */
+export function postTransformationInit(mod: ModUpgraded): void {
+  saveDataManager("postTransformation", v, hasSubscriptions);
+
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED,
+    postPEffectUpdateReordered,
+  );
+}
+
+function hasSubscriptions() {
+  return postTransformationHasSubscriptions();
+}
+
+// ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED
+function postPEffectUpdateReordered(player: EntityPlayer) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  const playerTransformationsMap = defaultMapGetPlayer(
+    v.run.playersTransformationsMap,
+    player,
+  );
+
+  for (const playerForm of PLAYER_FORMS) {
+    const hasForm = player.HasPlayerForm(playerForm);
+    const storedForm = playerTransformationsMap.getAndSetDefault(playerForm);
+
+    if (hasForm !== storedForm) {
+      playerTransformationsMap.set(playerForm, hasForm);
+      postTransformationFire(player, playerForm, hasForm);
+    }
+  }
+}

package/callbacks/postTrinketBreak.lua

@@ -23,11 +23,11 @@ function hasSubscriptions(self)
 end
 function entityTakeDmgPlayer(self, tookDamage, _damageAmount, _damageFlags, _damageSource, _damageCountdownFrames)
     if not hasSubscriptions(nil) then
-        return
+        return nil
     end
     local player = tookDamage:ToPlayer()
     if player == nil then
-        return
+        return nil
     end
     local trinketMap = defaultMapGetPlayer(nil, v.run.playersTrinketMap, player)
     for ____, trinketType in ipairs(TRINKETS_THAT_CAN_BREAK) do
@@ -46,6 +46,7 @@ function entityTakeDmgPlayer(self, tookDamage, _damageAmount, _damageFlags, _dam
         end
         ::__continue8::
     end
+    return nil
 end
 function postPEffectUpdateReordered(self, player)
     if not hasSubscriptions(nil) then

package/callbacks/postTrinketBreak.ts

@@ -0,0 +1,112 @@
+import {
+  DamageFlag,
+  EntityType,
+  ModCallback,
+  PickupVariant,
+  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 { PlayerIndex } from "../types/PlayerIndex";
+import {
+  postTrinketBreakFire,
+  postTrinketBreakHasSubscriptions,
+} from "./subscriptions/postTrinketBreak";
+
+const TRINKETS_THAT_CAN_BREAK: readonly TrinketType[] = [
+  TrinketType.WISH_BONE,
+  TrinketType.WALNUT,
+];
+
+const v = {
+  run: {
+    playersTrinketMap: new DefaultMap<
+      PlayerIndex,
+      DefaultMap<TrinketType, int>
+    >(() => new DefaultMap(0)),
+  },
+};
+
+/** @internal */
+export function postTrinketBreakInit(mod: ModUpgraded): void {
+  saveDataManager("postTrinketBreak", v, hasSubscriptions);
+
+  mod.AddCallback(
+    ModCallback.ENTITY_TAKE_DMG,
+    entityTakeDmgPlayer,
+    EntityType.PLAYER,
+  ); // 11
+
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED,
+    postPEffectUpdateReordered,
+  );
+}
+
+function hasSubscriptions() {
+  return postTrinketBreakHasSubscriptions();
+}
+
+// ModCallback.ENTITY_TAKE_DMG (11)
+// EntityType.PLAYER (1)
+function entityTakeDmgPlayer(
+  tookDamage: Entity,
+  _damageAmount: float,
+  _damageFlags: BitFlags<DamageFlag>,
+  _damageSource: EntityRef,
+  _damageCountdownFrames: int,
+): boolean | undefined {
+  if (!hasSubscriptions()) {
+    return undefined;
+  }
+
+  const player = tookDamage.ToPlayer();
+  if (player === undefined) {
+    return undefined;
+  }
+
+  const trinketMap = defaultMapGetPlayer(v.run.playersTrinketMap, player);
+
+  for (const trinketType of TRINKETS_THAT_CAN_BREAK) {
+    const numTrinketsHeld = player.GetTrinketMultiplier(trinketType);
+    const oldNumTrinketsHeld = trinketMap.getAndSetDefault(trinketType);
+    if (numTrinketsHeld >= oldNumTrinketsHeld) {
+      continue;
+    }
+
+    trinketMap.set(trinketType, numTrinketsHeld);
+
+    // Ensure that the trinket was not dropped on the ground.
+    const numTrinketsOnGround = Isaac.CountEntities(
+      undefined,
+      EntityType.PICKUP,
+      PickupVariant.TRINKET,
+      trinketType,
+    );
+    if (numTrinketsOnGround > 0) {
+      continue;
+    }
+
+    postTrinketBreakFire(player, trinketType);
+  }
+
+  return undefined;
+}
+
+// ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED
+function postPEffectUpdateReordered(player: EntityPlayer) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  // On every frame, keep track of how many trinkets we have.
+  const trinketMap = defaultMapGetPlayer(v.run.playersTrinketMap, player);
+
+  for (const trinketType of TRINKETS_THAT_CAN_BREAK) {
+    const numTrinkets = player.GetTrinketMultiplier(trinketType);
+    trinketMap.set(trinketType, numTrinkets);
+  }
+}

package/callbacks/preBerserkDeath.ts

@@ -0,0 +1,49 @@
+import { CollectibleType } from "isaac-typescript-definitions";
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { getPlayerNumHitsRemaining } from "../functions/player";
+import { isChildPlayer } from "../functions/playerIndex";
+import { willPlayerRevive } from "../functions/revive";
+import {
+  preBerserkDeathFire,
+  preBerserkDeathHasSubscriptions,
+} from "./subscriptions/preBerserkDeath";
+
+/** @internal */
+export function preBerserkDeathInit(mod: ModUpgraded): void {
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED,
+    postPEffectUpdateReordered,
+  );
+}
+
+function hasSubscriptions() {
+  return preBerserkDeathHasSubscriptions();
+}
+
+// ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED
+function postPEffectUpdateReordered(player: EntityPlayer) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  // This callback should not trigger for the Strawman Keeper and other players that are "child"
+  // players.
+  if (isChildPlayer(player)) {
+    return;
+  }
+
+  const effects = player.GetEffects();
+  const berserkEffect = effects.GetCollectibleEffect(CollectibleType.BERSERK);
+  const numHitsRemaining = getPlayerNumHitsRemaining(player);
+
+  // If the Berserk effect will end on the next frame and we have no hearts left.
+  if (
+    berserkEffect !== undefined &&
+    berserkEffect.Cooldown === 1 &&
+    numHitsRemaining === 0 &&
+    !willPlayerRevive(player)
+  ) {
+    preBerserkDeathFire(player);
+  }
+}

package/callbacks/preNewLevel.ts

@@ -0,0 +1,55 @@
+import { ModCallback } from "isaac-typescript-definitions";
+import { getLastFrameOfAnimation } from "../functions/sprite";
+import { getEffectiveStage } from "../functions/stage";
+import {
+  preNewLevelFire,
+  preNewLevelHasSubscriptions,
+} from "./subscriptions/preNewLevel";
+
+const TRAVELING_TO_NEXT_FLOOR_ANIMATIONS: ReadonlySet<string> = new Set([
+  "Trapdoor",
+  "LightTravel",
+]);
+
+/**
+ * Since there can be multiple players, use this variable to ensure that we only fire the custom
+ * callback once per stage.
+ */
+let firedOnStage: int | null = null;
+
+/** @internal */
+export function preNewLevelInit(mod: Mod): void {
+  mod.AddCallback(ModCallback.POST_PLAYER_RENDER, postPlayerRender); // 32
+}
+
+function hasSubscriptions() {
+  return preNewLevelHasSubscriptions();
+}
+
+// ModCallback.POST_PLAYER_RENDER (32)
+function postPlayerRender(player: EntityPlayer) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  const effectiveStage = getEffectiveStage();
+  if (effectiveStage === firedOnStage) {
+    return;
+  }
+
+  const sprite = player.GetSprite();
+  const animation = sprite.GetAnimation();
+  if (!TRAVELING_TO_NEXT_FLOOR_ANIMATIONS.has(animation)) {
+    return;
+  }
+
+  // We can't use the `Sprite.IsFinished` method to detect when we are at the end of the animation
+  // because the player will stop rendering at that point. Thus, revert to checking for the final
+  // frame manually.
+  const frame = sprite.GetFrame();
+  const finalFrame = getLastFrameOfAnimation(sprite);
+  if (frame === finalFrame) {
+    firedOnStage = effectiveStage;
+    preNewLevelFire(player);
+  }
+}

package/callbacks/reorderedCallbacks.lua

@@ -19,6 +19,7 @@ function hasSubscriptions(self)
 end
 function useItemGlowingHourGlass(self)
     usedGlowingHourGlass = true
+    return nil
 end
 function postGameStartedVanilla(self, isContinued)
     if not hasSubscriptions(nil) then

package/callbacks/reorderedCallbacks.ts

@@ -0,0 +1,168 @@
+/* eslint-disable sort-exports/sort-exports */
+
+// This provides the logic for:
+// - POST_GAME_STARTED_REORDERED
+// - POST_NEW_LEVEL_REORDERED
+// - POST_NEW_ROOM_REORDERED
+
+// By default, callbacks fire in the following order:
+// - POST_NEW_ROOM --> POST_NEW_LEVEL --> POST_GAME_STARTED
+
+// It is easier to write mod code if the callbacks run in a more logical order:
+// - POST_GAME_STARTED --> POST_NEW_LEVEL --> POST_NEW_ROOM
+
+// Manually reorganize the callback execution so that this is the case.
+
+import { CollectibleType, ModCallback } from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import {
+  postGameStartedReorderedFire,
+  postGameStartedReorderedHasSubscriptions,
+} from "./subscriptions/postGameStartedReordered";
+import {
+  postNewLevelReorderedFire,
+  postNewLevelReorderedHasSubscriptions,
+} from "./subscriptions/postNewLevelReordered";
+import {
+  postNewRoomReorderedFire,
+  postNewRoomReorderedHasSubscriptions,
+} from "./subscriptions/postNewRoomReordered";
+
+let currentStage = null as int | null;
+let currentStageType = null as int | null;
+let usedGlowingHourGlass = false;
+let forceNewLevel = false;
+let forceNewRoom = false;
+
+/** @internal */
+export function reorderedCallbacksInit(mod: Mod): void {
+  mod.AddCallback(
+    ModCallback.POST_USE_ITEM,
+    useItemGlowingHourGlass,
+    CollectibleType.GLOWING_HOUR_GLASS,
+  ); // 3
+  mod.AddCallback(ModCallback.POST_GAME_STARTED, postGameStartedVanilla); // 15
+  mod.AddCallback(ModCallback.POST_NEW_LEVEL, postNewLevelVanilla); // 18
+  mod.AddCallback(ModCallback.POST_NEW_ROOM, postNewRoomVanilla); // 19
+}
+
+function hasSubscriptions() {
+  return (
+    postGameStartedReorderedHasSubscriptions() ||
+    postNewLevelReorderedHasSubscriptions() ||
+    postNewRoomReorderedHasSubscriptions()
+  );
+}
+
+// ModCallback.POST_USE_ITEM (3)
+// CollectibleType.GLOWING_HOUR_GLASS (422)
+function useItemGlowingHourGlass(): boolean | undefined {
+  // If Glowing Hour Glass is used on the first room of a floor, it will send the player to the
+  // previous floor without triggering the PostNewLevel callback. Manually check for this.
+  usedGlowingHourGlass = true;
+
+  return undefined;
+}
+
+// ModCallback.POST_GAME_STARTED (15)
+function postGameStartedVanilla(isContinued: boolean) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  postGameStartedReorderedFire(isContinued);
+  recordCurrentStage();
+  postNewLevelReorderedFire();
+  postNewRoomReorderedFire();
+}
+
+// ModCallback.POST_NEW_LEVEL (18)
+function postNewLevelVanilla() {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  const gameFrameCount = game.GetFrameCount();
+
+  if (gameFrameCount === 0 && !forceNewLevel) {
+    // Wait for the PostGameStarted callback to fire.
+    return;
+  }
+  forceNewLevel = false;
+
+  recordCurrentStage();
+  postNewLevelReorderedFire();
+  postNewRoomReorderedFire();
+}
+
+// ModCallback.POST_NEW_ROOM (19)
+function postNewRoomVanilla() {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  const gameFrameCount = game.GetFrameCount();
+  const level = game.GetLevel();
+  const stage = level.GetStage();
+  const stageType = level.GetStageType();
+
+  if (usedGlowingHourGlass) {
+    usedGlowingHourGlass = false;
+
+    if (currentStage !== stage || currentStageType !== stageType) {
+      // The player has used the Glowing Hour Glass to take them to the previous floor (which does
+      // not trigger the PostNewLevel callback). Emulate what happens in the PostNewLevel callback.
+      recordCurrentStage();
+      postNewLevelReorderedFire();
+      postNewRoomReorderedFire();
+      return;
+    }
+  }
+
+  if (
+    (gameFrameCount === 0 ||
+      currentStage !== stage ||
+      currentStageType !== stageType) &&
+    !forceNewRoom
+  ) {
+    return;
+  }
+  forceNewRoom = false;
+
+  postNewRoomReorderedFire();
+}
+
+function recordCurrentStage() {
+  const level = game.GetLevel();
+  const stage = level.GetStage();
+  const stageType = level.GetStageType();
+
+  currentStage = stage;
+  currentStageType = stageType;
+}
+
+/**
+ * This is a utility function for users of the `ModCallbackCustom.POST_NEW_LEVEL_REORDERED` custom
+ * callback.
+ *
+ * If some specific cases, mods can change the current level during run initialization on the 0th
+ * frame. However, due to how the callback reordering works, the custom PostNewLevel callback will
+ * never fire on the 0th frame. To get around this, call this function before changing levels to
+ * temporarily force the callback to fire.
+ */
+export function forceNewLevelCallback(): void {
+  forceNewLevel = true;
+}
+
+/**
+ * This is a utility function for users of the `ModCallbackCustom.POST_NEW_ROOM_REORDERED` custom
+ * callback.
+ *
+ * If some specific cases, mods can change the current room during run initialization on the 0th
+ * frame. However, due to how the callback reordering works, the custom PostNewRoom callback will
+ * never fire on the 0th frame. To get around this, call this function before changing rooms to
+ * temporarily force the callback to fire.
+ */
+export function forceNewRoomCallback(): void {
+  forceNewRoom = true;
+}

package/callbacks/subscriptions/postAmbushFinished.ts

@@ -0,0 +1,32 @@
+import { AmbushType } from "../../enums/AmbushType";
+
+export type PostAmbushFinishedRegisterParameters = [
+  callback: (ambushType: AmbushType) => void,
+  ambushType?: AmbushType,
+];
+
+const subscriptions: PostAmbushFinishedRegisterParameters[] = [];
+
+/** @internal */
+export function postAmbushFinishedHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+/** @internal */
+export function postAmbushFinishedRegister(
+  ...args: PostAmbushFinishedRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+/** @internal */
+export function postAmbushFinishedFire(ambushType: AmbushType): void {
+  for (const [callback, callbackAmbushType] of subscriptions) {
+    // Handle the optional 2nd callback argument.
+    if (callbackAmbushType !== undefined && callbackAmbushType !== ambushType) {
+      continue;
+    }
+
+    callback(ambushType);
+  }
+}

package/callbacks/subscriptions/postAmbushStarted.ts

@@ -0,0 +1,32 @@
+import { AmbushType } from "../../enums/AmbushType";
+
+export type PostAmbushStartedRegisterParameters = [
+  callback: (ambushType: AmbushType) => void,
+  ambushType?: AmbushType,
+];
+
+const subscriptions: PostAmbushStartedRegisterParameters[] = [];
+
+/** @internal */
+export function postAmbushStartedHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+/** @internal */
+export function postAmbushStartedRegister(
+  ...args: PostAmbushStartedRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+/** @internal */
+export function postAmbushStartedFire(ambushType: AmbushType): void {
+  for (const [callback, callbackAmbushType] of subscriptions) {
+    // Handle the optional 2nd callback argument.
+    if (callbackAmbushType !== undefined && callbackAmbushType !== ambushType) {
+      continue;
+    }
+
+    callback(ambushType);
+  }
+}

package/callbacks/subscriptions/postBombInitLate.ts

@@ -0,0 +1,32 @@
+import { BombVariant } from "isaac-typescript-definitions";
+
+export type PostBombInitRegisterParameters = [
+  callback: (bomb: EntityBomb) => void,
+  bombVariant?: BombVariant,
+];
+
+const subscriptions: PostBombInitRegisterParameters[] = [];
+
+/** @internal */
+export function postBombInitLateHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+/** @internal */
+export function postBombInitLateRegister(
+  ...args: PostBombInitRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+/** @internal */
+export function postBombInitLateFire(bomb: EntityBomb): void {
+  for (const [callback, bombVariant] of subscriptions) {
+    // Handle the optional 2nd callback argument.
+    if (bombVariant !== undefined && bombVariant !== bomb.Variant) {
+      continue;
+    }
+
+    callback(bomb);
+  }
+}

package/callbacks/subscriptions/postBoneExploded.ts

@@ -0,0 +1,32 @@
+import { BombVariant } from "isaac-typescript-definitions";
+
+export type PostBombExplodedRegisterParameters = [
+  callback: (bomb: EntityBomb) => void,
+  bombVariant?: BombVariant,
+];
+
+const subscriptions: PostBombExplodedRegisterParameters[] = [];
+
+/** @internal */
+export function postBombExplodedHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+/** @internal */
+export function postBombExplodedRegister(
+  ...args: PostBombExplodedRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+/** @internal */
+export function postBombExplodedFire(bomb: EntityBomb): void {
+  for (const [callback, bombVariant] of subscriptions) {
+    // Handle the optional 2nd callback argument.
+    if (bombVariant !== undefined && bombVariant !== bomb.Variant) {
+      continue;
+    }
+
+    callback(bomb);
+  }
+}

package/callbacks/subscriptions/postBoneSwing.ts

@@ -0,0 +1,24 @@
+export type PostBoneSwingRegisterParameters = [
+  callback: (boneClub: EntityKnife) => void,
+];
+
+const subscriptions: PostBoneSwingRegisterParameters[] = [];
+
+/** @internal */
+export function postBoneSwingHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+/** @internal */
+export function postBoneSwingRegister(
+  ...args: PostBoneSwingRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+/** @internal */
+export function postBoneSwingFire(boneClub: EntityKnife): void {
+  for (const [callback] of subscriptions) {
+    callback(boneClub);
+  }
+}

package/callbacks/subscriptions/postCollectibleInitFirst.ts

@@ -0,0 +1,37 @@
+import { CollectibleType } from "isaac-typescript-definitions";
+
+export type PostCollectibleInitFirstRegisterParameters = [
+  callback: (collectible: EntityPickup) => void,
+  collectibleType?: CollectibleType,
+];
+
+const subscriptions: PostCollectibleInitFirstRegisterParameters[] = [];
+
+/** @internal */
+export function postCollectibleInitFirstHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+/** @internal */
+export function postCollectibleInitFirstRegister(
+  ...args: PostCollectibleInitFirstRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+/** @internal */
+export function postCollectibleInitFirstFire(
+  collectible: EntityPickupCollectible,
+): void {
+  for (const [callback, collectibleType] of subscriptions) {
+    // Handle the optional 2nd callback argument.
+    if (
+      collectibleType !== undefined &&
+      collectibleType !== collectible.SubType
+    ) {
+      continue;
+    }
+
+    callback(collectible);
+  }
+}

package/callbacks/subscriptions/postCursedTeleport.ts

@@ -0,0 +1,24 @@
+export type PostCursedTeleportRegisterParameters = [
+  callback: (player: EntityPlayer) => void,
+];
+
+const subscriptions: PostCursedTeleportRegisterParameters[] = [];
+
+/** @internal */
+export function postCursedTeleportHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+/** @internal */
+export function postCursedTeleportRegister(
+  ...args: PostCursedTeleportRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+/** @internal */
+export function postCursedTeleportFire(player: EntityPlayer): void {
+  for (const [callback] of subscriptions) {
+    callback(player);
+  }
+}