isaacscript-common 25.2.0 → 25.4.0

package/src/classes/features/other/TaintedLazarusPlayers.ts

@@ -3,33 +3,34 @@ import { Exported } from "../../../decorators";
 import { logError } from "../../../functions/logMisc";
 import { Feature } from "../../private/Feature";
 
+const v = {
+  run: {
+    queuedTaintedLazarus: [] as EntityPlayer[],
+    queuedDeadTaintedLazarus: [] as EntityPlayer[],
+
+    /**
+     * The `POST_PLAYER_INIT` callback fires for Dead Tainted Lazarus at the beginning of the run.
+     * However, the player index for the Dead Tainted Lazarus player object at that time does not
+     * actually correspond to the player index for the real player once Flip has been used. Thus, we
+     * revert to using PtrHash as an index for our map, which is consistent between the Dead Tainted
+     * Lazarus object in the `POST_PLAYER_INIT` callback and the "real" Dead Tainted Lazarus.
+     *
+     * We use `EntityPlayer` as the value for the map instead of `EntityPtr` because using the
+     * pointer does not work for some reason. (When we unwrap it after one or more flips have been
+     * used, the pointers no longer point to the original objects, even if we manually update the
+     * pointers in the `POST_FLIP` callback.)
+     */
+    subPlayerMap: new Map<PtrHash, EntityPlayer>(),
+  },
+};
+
 /**
  * This feature provides a way for end-users to get the `EntityPlayer` object for the other Tainted
  * Lazarus.
  */
 export class TaintedLazarusPlayers extends Feature {
   /** @internal */
-  public override v = {
-    run: {
-      queuedTaintedLazarus: [] as EntityPlayer[],
-      queuedDeadTaintedLazarus: [] as EntityPlayer[],
-
-      /**
-       * The `POST_PLAYER_INIT` callback fires for Dead Tainted Lazarus at the beginning of the run.
-       * However, the player index for the Dead Tainted Lazarus player object at that time does not
-       * actually correspond to the player index for the real player once Flip has been used. Thus,
-       * we revert to using PtrHash as an index for our map, which is consistent between the Dead
-       * Tainted Lazarus object in the `POST_PLAYER_INIT` callback and the "real" Dead Tainted
-       * Lazarus.
-       *
-       * We use `EntityPlayer` as the value for the map instead of `EntityPtr` because using the
-       * pointer does not work for some reason. (When we unwrap it after one or more flips have been
-       * used, the pointers no longer point to the original objects, even if we manually update the
-       * pointers in the `POST_FLIP` callback.)
-       */
-      subPlayerMap: new Map<PtrHash, EntityPlayer>(),
-    },
-  };
+  public override v = v;
 
   public override vConditionalFunc = (): boolean => false;
 
@@ -48,9 +49,9 @@ export class TaintedLazarusPlayers extends Feature {
     const character = player.GetPlayerType();
 
     if (character === PlayerType.LAZARUS_B) {
-      this.v.run.queuedTaintedLazarus.push(player);
+      v.run.queuedTaintedLazarus.push(player);
     } else if (character === PlayerType.LAZARUS_2_B) {
-      this.v.run.queuedDeadTaintedLazarus.push(player);
+      v.run.queuedDeadTaintedLazarus.push(player);
     } else {
       return;
     }
@@ -69,14 +70,14 @@ export class TaintedLazarusPlayers extends Feature {
    */
   private checkDequeue() {
     if (
-      this.v.run.queuedTaintedLazarus.length === 0 ||
-      this.v.run.queuedDeadTaintedLazarus.length === 0
+      v.run.queuedTaintedLazarus.length === 0 ||
+      v.run.queuedDeadTaintedLazarus.length === 0
     ) {
       return;
     }
 
-    const taintedLazarus = this.v.run.queuedTaintedLazarus.shift();
-    const deadTaintedLazarus = this.v.run.queuedDeadTaintedLazarus.shift();
+    const taintedLazarus = v.run.queuedTaintedLazarus.shift();
+    const deadTaintedLazarus = v.run.queuedDeadTaintedLazarus.shift();
 
     if (taintedLazarus === undefined || deadTaintedLazarus === undefined) {
       return;
@@ -92,8 +93,8 @@ export class TaintedLazarusPlayers extends Feature {
       return;
     }
 
-    this.v.run.subPlayerMap.set(taintedLazarusPtrHash, deadTaintedLazarus);
-    this.v.run.subPlayerMap.set(deadTaintedLazarusPtrHash, taintedLazarus);
+    v.run.subPlayerMap.set(taintedLazarusPtrHash, deadTaintedLazarus);
+    v.run.subPlayerMap.set(deadTaintedLazarusPtrHash, taintedLazarus);
   }
 
   /**
@@ -115,6 +116,6 @@ export class TaintedLazarusPlayers extends Feature {
     player: EntityPlayer,
   ): EntityPlayer | undefined {
     const ptrHash = GetPtrHash(player);
-    return this.v.run.subPlayerMap.get(ptrHash);
+    return v.run.subPlayerMap.get(ptrHash);
   }
 }

package/src/classes/features/other/customStages/streakText.ts

@@ -1,4 +1,4 @@
-import { ButtonAction, ControllerIndex } from "isaac-typescript-definitions";
+import { ButtonAction } from "isaac-typescript-definitions";
 import { CONTROLLER_INDEX_VALUES } from "../../../../arrays/cachedEnumValues";
 import { fonts, game } from "../../../../core/cachedClasses";
 import { KColorDefault, VectorOne } from "../../../../core/constants";
@@ -8,6 +8,7 @@ import {
   getScreenTopCenterPos,
 } from "../../../../functions/ui";
 import { CustomStage } from "../../../../interfaces/private/CustomStage";
+import { v } from "./v";
 
 /** Corresponds to "resources/gfx/ui/ui_streak.anm2". */
 const UI_STREAK_ANIMATION_END_FRAMES = {
@@ -81,43 +82,19 @@ const TEXT_OUT_SCALES = [
   Vector(3, 0.2),
 ] as const;
 
-interface StreakTextVars {
-  run: {
-    /** Whether we are on e.g. Caves 1 or Caves 2. */
-    firstFloor: boolean;
-
-    /** Values are the render frame that the controller first pressed the map button. */
-    controllerIndexPushingMapRenderFrame: Map<ControllerIndex, int>;
-
-    topStreakTextStartedRenderFrame: int | null;
-
-    topStreakText: {
-      animation: UIStreakAnimation;
-      frame: int;
-      pauseFrame: boolean;
-    };
-
-    bottomStreakText: {
-      animation: UIStreakAnimation;
-      frame: int;
-      pauseFrame: boolean;
-    };
-  };
-}
-
 // ModCallback.POST_RENDER (2)
-export function streakTextPostRender(v: StreakTextVars): void {
+export function streakTextPostRender(): void {
   // The top streak only plays when the player arrives on the floor (or continues a game from the
   // main menu.)
-  checkEndTopStreakText(v);
+  checkEndTopStreakText();
 
   // The bottom streak only plays when the player holds down the map button.
-  trackMapInputPressed(v);
-  checkStartBottomStreakText(v);
-  checkEndBottomStreakText(v);
+  trackMapInputPressed();
+  checkStartBottomStreakText();
+  checkEndBottomStreakText();
 }
 
-function checkEndTopStreakText(v: StreakTextVars) {
+function checkEndTopStreakText() {
   if (
     v.run.topStreakTextStartedRenderFrame === null ||
     v.run.topStreakText.animation !== UIStreakAnimation.TEXT_STAY
@@ -136,7 +113,7 @@ function checkEndTopStreakText(v: StreakTextVars) {
   }
 }
 
-function trackMapInputPressed(v: StreakTextVars) {
+function trackMapInputPressed() {
   for (const controllerIndex of CONTROLLER_INDEX_VALUES) {
     const gameFrameCount = game.GetFrameCount();
     const oldPushedMapFrame =
@@ -163,7 +140,7 @@ function trackMapInputPressed(v: StreakTextVars) {
  * If the map input has been pressed down for long enough, play the animation where the level streak
  * slides in from the left.
  */
-function checkStartBottomStreakText(v: StreakTextVars) {
+function checkStartBottomStreakText() {
   if (v.run.bottomStreakText.animation !== UIStreakAnimation.NONE) {
     return;
   }
@@ -188,7 +165,7 @@ function checkStartBottomStreakText(v: StreakTextVars) {
  * If the map input has been released, play the animation where the level streak slides out to the
  * right.
  */
-function checkEndBottomStreakText(v: StreakTextVars) {
+function checkEndBottomStreakText() {
   if (v.run.bottomStreakText.animation !== UIStreakAnimation.TEXT_STAY) {
     return;
   }
@@ -206,7 +183,6 @@ function checkEndBottomStreakText(v: StreakTextVars) {
 
 // ModCallback.GET_SHADER_PARAMS (22)
 export function streakTextGetShaderParams(
-  v: StreakTextVars,
   customStage: CustomStage,
   shaderName: string,
 ): void {
@@ -216,20 +192,14 @@ export function streakTextGetShaderParams(
 
   const topCenterPos = getScreenTopCenterPos();
   const topStreakPosition = topCenterPos.add(STREAK_SPRITE_TOP_OFFSET);
-  renderStreakText(v, customStage, v.run.topStreakText, topStreakPosition);
+  renderStreakText(customStage, v.run.topStreakText, topStreakPosition);
 
   const bottomCenterPos = getScreenBottomCenterPos();
   const bottomStreakPosition = bottomCenterPos.add(STREAK_SPRITE_BOTTOM_OFFSET);
-  renderStreakText(
-    v,
-    customStage,
-    v.run.bottomStreakText,
-    bottomStreakPosition,
-  );
+  renderStreakText(customStage, v.run.bottomStreakText, bottomStreakPosition);
 }
 
 function renderStreakText(
-  v: StreakTextVars,
   customStage: CustomStage,
   streakText: { animation: UIStreakAnimation; frame: int; pauseFrame: boolean },
   position: Vector,
@@ -301,7 +271,7 @@ function renderStreakText(
   );
 }
 
-export function topStreakTextStart(v: StreakTextVars): void {
+export function topStreakTextStart(): void {
   const level = game.GetLevel();
   const renderFrameCount = Isaac.GetFrameCount();
 

package/src/classes/features/other/customStages/v.ts

@@ -0,0 +1,31 @@
+import { ControllerIndex } from "isaac-typescript-definitions";
+import { UIStreakAnimation } from "../../../../enums/private/UIStreakAnimation";
+import { CustomStage } from "../../../../interfaces/private/CustomStage";
+
+export const v = {
+  run: {
+    currentCustomStage: null as CustomStage | null,
+
+    /** Whether we are on e.g. Caves 1 or Caves 2. */
+    firstFloor: true,
+
+    showingBossVersusScreen: false,
+
+    /** Values are the render frame that the controller first pressed the map button. */
+    controllerIndexPushingMapRenderFrame: new Map<ControllerIndex, int>(),
+
+    topStreakTextStartedRenderFrame: null as int | null,
+
+    topStreakText: {
+      animation: UIStreakAnimation.NONE,
+      frame: 0,
+      pauseFrame: false,
+    },
+
+    bottomStreakText: {
+      animation: UIStreakAnimation.NONE,
+      frame: 0,
+      pauseFrame: false,
+    },
+  },
+};

package/src/classes/features/other/customStages/versusScreen.ts

@@ -32,12 +32,7 @@ import {
   DEFAULT_BASE_STAGE_TYPE,
   ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH,
 } from "./constants";
-
-interface VersusScreenVars {
-  run: {
-    showingBossVersusScreen: boolean;
-  };
-}
+import { v } from "./v";
 
 const DEFAULT_STAGE_ID = StageID.BASEMENT;
 const VERSUS_SCREEN_ANIMATION_NAME = "Scene";
@@ -116,7 +111,6 @@ const versusScreenBackgroundSprite = Sprite();
 const versusScreenDirtSpotSprite = Sprite();
 
 export function playVersusScreenAnimation(
-  v: VersusScreenVars,
   customStage: CustomStage,
   disableAllSound: DisableAllSound,
   pause: Pause,
@@ -307,7 +301,6 @@ function getBossPNGPathsCustom(
 }
 
 function finishVersusScreenAnimation(
-  v: VersusScreenVars,
   pause: Pause,
   disableAllSound: DisableAllSound,
 ) {
@@ -325,7 +318,6 @@ function finishVersusScreenAnimation(
 
 // ModCallback.POST_RENDER (2)
 export function versusScreenPostRender(
-  v: VersusScreenVars,
   pause: Pause,
   disableAllSound: DisableAllSound,
 ): void {
@@ -337,7 +329,7 @@ export function versusScreenPostRender(
   // black screen as soon as the slide animation starts.
 
   if (versusScreenSprite.IsFinished(VERSUS_SCREEN_ANIMATION_NAME)) {
-    finishVersusScreenAnimation(v, pause, disableAllSound);
+    finishVersusScreenAnimation(pause, disableAllSound);
     return;
   }
 

package/src/enums/ModCallbackCustom.ts

@@ -428,6 +428,9 @@ export enum ModCallbackCustom {
    *
    * `POST_GAME_STARTED_REORDERED` --> `POST_NEW_LEVEL_REORDERED` --> `POST_NEW_ROOM_REORDERED`
    *
+   * - You can provide an optional third argument that will make the callback only fire if it
+   *   matches the `isContinued` value provided.
+   *
    * ```ts
    * function postGameStartedReordered(isContinued: boolean): void {}
    * ```
@@ -440,6 +443,9 @@ export enum ModCallbackCustom {
    * new run has started (or continued), but you can be sure that all new-run-related initialization
    * has been completed.
    *
+   * - You can provide an optional third argument that will make the callback only fire if it
+   *   matches the `isContinued` value provided.
+   *
    * ```ts
    * function postGameStartedReorderedLast(isContinued: boolean): void {}
    * ```

package/src/functions/decorators.ts

@@ -21,6 +21,7 @@
  */
 
 import { ModCallback } from "isaac-typescript-definitions";
+import { CallbackPriority } from "isaac-typescript-definitions/dist/src/enums/CallbackPriority";
 import {
   ModFeature,
   MOD_FEATURE_CALLBACKS_KEY,
@@ -38,19 +39,58 @@ import { getTSTLClassName } from "./tstlClass";
  * @ignore
  */
 // We tell TypeDoc to ignore this function because it generates a bunch of spam.
+// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
 export function Callback<T extends ModCallback>(
   modCallback: T,
   ...optionalArgs: AllButFirst<AddCallbackParameters[T]>
+) {
+  return PriorityCallback(
+    modCallback,
+    CallbackPriority.DEFAULT,
+    ...optionalArgs,
+  );
+}
+
+/**
+ * A decorator function that signifies that the decorated class method should be automatically
+ * registered with `ModUpgraded.AddCallbackCustom`.
+ *
+ * @ignore
+ */
+// We tell TypeDoc to ignore this function because it generates a bunch of spam.
+// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+export function CallbackCustom<T extends ModCallbackCustom>(
+  modCallbackCustom: T,
+  ...optionalArgs: AllButFirst<AddCallbackParametersCustom[T]>
+) {
+  return PriorityCallbackCustom(
+    modCallbackCustom,
+    CallbackPriority.DEFAULT,
+    ...optionalArgs,
+  );
+}
+
+/**
+ * A decorator function that signifies that the decorated class method should be automatically
+ * registered with `Mod.AddPriorityCallback`.
+ *
+ * @ignore
+ */
+// We tell TypeDoc to ignore this function because it generates a bunch of spam.
+export function PriorityCallback<T extends ModCallback>(
+  modCallback: T,
+  priority: CallbackPriority | int,
+  ...optionalArgs: AllButFirst<AddCallbackParameters[T]>
 ) {
   return <Class extends ModFeature, Fn extends AddCallbackParameters[T][0]>(
     target: Class,
     propertyKey: string,
     _descriptor: TypedPropertyDescriptor<Fn>,
   ): void => {
-    // First, prepare the arguments for the `Mod.AddCallback` method.
+    // First, prepare the arguments for the `Mod.AddPriorityCallback` method.
     const methodName = propertyKey as keyof Class;
     const method = target[methodName] as AddCallbackParameters[T][0];
-    const callbackTuple = [modCallback, method, optionalArgs];
+    const callbackTuple = [modCallback, priority, method, optionalArgs];
 
     // Since the decorator runs prior to instantiation, we only have access to get and set static
     // properties, which are located on the "constructor" table. Thus, we store the callback
@@ -84,8 +124,9 @@ export function Callback<T extends ModCallback>(
  * @ignore
  */
 // We tell TypeDoc to ignore this function because it generates a bunch of spam.
-export function CallbackCustom<T extends ModCallbackCustom>(
+export function PriorityCallbackCustom<T extends ModCallbackCustom>(
   modCallbackCustom: T,
+  priority: CallbackPriority | int,
   ...optionalArgs: AllButFirst<AddCallbackParametersCustom[T]>
 ) {
   return <
@@ -99,7 +140,7 @@ export function CallbackCustom<T extends ModCallbackCustom>(
     // First, prepare the arguments for the `Mod.AddCallbackCustom` method.
     const methodName = propertyKey as keyof Class;
     const method = target[methodName] as AddCallbackParametersCustom[T][0];
-    const callbackTuple: unknown[] = [modCallbackCustom, method, optionalArgs];
+    const callbackTuple = [modCallbackCustom, priority, method, optionalArgs];
 
     // Since the decorator runs prior to instantiation, we only have access to get and set static
     // properties, which are located on the "constructor" table. Thus, we store the callback

package/src/interfaces/SaveData.ts

@@ -1,5 +1,4 @@
 /* eslint-disable @typescript-eslint/explicit-member-accessibility */
-/* eslint-disable class-methods-use-this */
 /* eslint-disable max-classes-per-file */
 
 import { CopyableIsaacAPIClass } from "../objects/isaacAPIClassTypeToFunctions";

package/src/interfaces/private/AddCallbackParametersCustom.ts

@@ -211,10 +211,12 @@ export interface AddCallbackParametersCustom {
 
   [ModCallbackCustom.POST_GAME_STARTED_REORDERED]: [
     callback: (isContinued: boolean) => void,
+    isContinued?: boolean,
   ];
 
   [ModCallbackCustom.POST_GAME_STARTED_REORDERED_LAST]: [
     callback: (isContinued: boolean) => void,
+    isContinued?: boolean,
   ];
 
   [ModCallbackCustom.POST_GREED_MODE_WAVE]: [

package/src/shouldFire.ts

@@ -68,6 +68,16 @@ export function shouldFireBomb(
   );
 }
 
+export function shouldFireBoolean(
+  fireArgs: [fireArg: boolean],
+  optionalArgs: [optionalArg?: boolean],
+): boolean {
+  const [fireArg] = fireArgs;
+  const [optionalArg] = optionalArgs;
+
+  return optionalArg === undefined || optionalArg === fireArg;
+}
+
 export function shouldFireCollectible(
   fireArgs: [collectible: EntityPickupCollectible],
   optionalArgs: [collectibleType?: CollectibleType],