isaacscript-common 13.3.4 → 14.1.0

package/src/classes/ModUpgraded.ts

@@ -1,9 +1,21 @@
 import { ModCallback } from "isaac-typescript-definitions";
+import { getCallbacks } from "../callbacks";
+import { ISCFeature } from "../enums/ISCFeature";
 import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { ModCallbackCustom2 } from "../enums/ModCallbackCustom2";
+import { getFeatures } from "../features";
+import {
+  saveDataManager,
+  saveDataManagerRemove,
+} from "../features/saveDataManager/exports";
 import { getTime } from "../functions/debugFunctions";
 import { getParentFunctionDescription } from "../functions/log";
-import { AddCallbackParametersCustom } from "../interfaces/private/AddCallbackParameterCustom";
+import { getTSTLClassMethods, getTSTLClassName } from "../functions/tstlClass";
+import { AddCallbackParametersCustom } from "../interfaces/private/AddCallbackParametersCustom";
+import { AddCallbackParametersCustom2 } from "../interfaces/private/AddCallbackParametersCustom2";
 import { CALLBACK_REGISTER_FUNCTIONS } from "../objects/callbackRegisterFunctions";
+import { FunctionTuple } from "../types/FunctionTuple";
+import { Feature } from "./private/Feature";
 
 /**
  * `isaacscript-common` has many custom callbacks that you can use in your mods. Instead of
@@ -18,37 +30,54 @@ export class ModUpgraded implements Mod {
   // -----------------
 
   /**
-   * The vanilla mod object stores the name of the mod for some reason. (It is never used or
-   * referenced.
+   * The `RegisterMod` function stores the name of the mod on the mod object for some reason. (It is
+   * never used or referenced.)
    */
-  Name: string;
+  public Name: string;
 
   // ----------------
   // Custom variables
   // ----------------
 
   /** We store a copy of the original mod object so that we can re-implement its functions. */
-  Mod: Mod;
+  private mod: Mod;
 
-  Debug: boolean;
-  TimeThreshold: float | undefined;
+  private debug: boolean;
+  private timeThreshold: float | undefined;
+
+  private callbacks;
+
+  // Features must be marked as internal to prevent TypeDoc from complaining.
+  /** @internal */
+  private features;
+
+  // -----------
+  // Constructor
+  // -----------
 
   constructor(mod: Mod, debug: boolean, timeThreshold?: float) {
     this.Name = mod.Name;
-    this.Mod = mod;
-    this.Debug = debug;
-    this.TimeThreshold = timeThreshold;
+    this.mod = mod;
+    this.debug = debug;
+    this.timeThreshold = timeThreshold;
+    this.callbacks = getCallbacks();
+    this.features = getFeatures(this.callbacks);
   }
 
   // ---------------
   // Vanilla methods
   // ---------------
 
-  AddCallback<T extends ModCallback>(
+  /**
+   * Registers a function to be executed when an in-game event happens. For example, the
+   * `ModCallback.POST_UPDATE` event corresponds to being executed once at the end of every game
+   * logic frame.
+   */
+  public AddCallback<T extends ModCallback>(
     modCallback: T,
     ...args: AddCallbackParameters[T]
   ): void {
-    if (this.Debug) {
+    if (this.debug) {
       const callback = args[0];
       const optionalArg = args[1];
 
@@ -60,69 +89,92 @@ export class ModUpgraded implements Mod {
           : `${parentFunctionDescription} - ${callbackName}`;
 
       /**
-       * We don't use the "log" helper function since it will always show the same "unknown" prefix.
+       * We don't use the "log" helper function here since it will always show the same "unknown"
+       * prefix.
        */
-      const callbackWithLogger = (...callbackArgs: unknown[]) => {
+      const callbackWithLogger: typeof callback = (
+        ...callbackArgs: Parameters<typeof callback>
+      ) => {
         const startTime = getTime();
         Isaac.DebugString(`${signature} - START`);
 
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-expect-error
-        callback(...callbackArgs);
+        // @ts-expect-error The compiler is not smart enough to know that the callback args should
+        // match the callback.
+        const returnValue = callback(...callbackArgs);
 
         const endTime = getTime();
         const elapsedTime = endTime - startTime;
         if (
-          this.TimeThreshold === undefined ||
-          this.TimeThreshold <= elapsedTime
+          this.timeThreshold === undefined ||
+          this.timeThreshold <= elapsedTime
         ) {
           Isaac.DebugString(`${signature} - END - time: ${elapsedTime}`);
         } else {
           Isaac.DebugString(`${signature} - END`);
         }
+
+        return returnValue;
       };
 
-      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-      // @ts-expect-error
-      this.Mod.AddCallback(modCallback, callbackWithLogger, optionalArg);
+      const newArgs = [
+        callbackWithLogger,
+        optionalArg,
+      ] as unknown as AddCallbackParameters[T];
+      this.mod.AddCallback(modCallback, ...newArgs);
     } else {
-      this.Mod.AddCallback(modCallback, ...args);
+      this.mod.AddCallback(modCallback, ...args);
     }
   }
 
-  HasData(): boolean {
-    return this.Mod.HasData();
+  /** Returns whether or not a corresponding "save#.dat" file exists for the current mod. */
+  public HasData(): boolean {
+    return this.mod.HasData();
   }
 
-  LoadData(): string {
-    return this.Mod.LoadData();
+  /**
+   * Returns a string containing all of the data inside of the corresponding "save#.dat" file for
+   * this mod.
+   */
+  public LoadData(): string {
+    return this.mod.LoadData();
   }
 
   /**
-   * This method does not care about the tertiary argument. Regardless of the conditions of how you
-   * registered the callback, it will be removed.
+   * Unregisters a function that was previously registered with the `AddCallback` method.
+   *
+   * This method does not care about the tertiary argument. In other words, regardless of the
+   * conditions of how you registered the callback, it will be removed.
    */
-  RemoveCallback<T extends ModCallback>(
+  public RemoveCallback<T extends ModCallback>(
     modCallback: T,
     callback: AddCallbackParameters[T][0],
   ): void {
-    this.Mod.RemoveCallback(modCallback, callback);
+    this.mod.RemoveCallback(modCallback, callback);
   }
 
-  RemoveData(): void {
-    this.Mod.RemoveData();
+  /** Deletes the corresponding "save#.dat" file for this mod, if it exists. */
+  public RemoveData(): void {
+    this.mod.RemoveData();
   }
 
-  SaveData(data: string): void {
-    this.Mod.SaveData(data);
+  /**
+   * Creates or updates the corresponding "save#.dat" file for this mod with the provided string.
+   */
+  public SaveData(data: string): void {
+    this.mod.SaveData(data);
   }
 
-  // --------------
-  // Custom methods
-  // --------------
+  // ---------------------
+  // Custom public methods
+  // ---------------------
 
+  /**
+   * Registers a function to be executed when an in-game event happens. This method is specifically
+   * for events that are provided by the IsaacScript standard library. For example, the
+   * `ModCallbackCustom.POST_BOMB_EXPLODE` event corresponds to when a bomb explodes.
+   */
   // eslint-disable-next-line class-methods-use-this
-  AddCallbackCustom<T extends ModCallbackCustom>(
+  public AddCallbackCustom<T extends ModCallbackCustom>(
     modCallbackCustom: T,
     ...args: AddCallbackParametersCustom[T]
   ): void {
@@ -131,14 +183,122 @@ export class ModUpgraded implements Mod {
     callbackRegisterFunction(...args);
   }
 
+  /** Adds a callback in the new callback system format. This method is only temporary. */
+  public AddCallbackCustom2<T extends ModCallbackCustom2>(
+    modCallbackCustom: T,
+    ...args: AddCallbackParametersCustom2[T]
+  ): void {
+    const callbackClass = this.callbacks[modCallbackCustom];
+    // @ts-expect-error The compiler is not smart enough to figure out that the parameters match.
+    callbackClass.add(...args);
+    this.initFeature(callbackClass);
+  }
+
   /**
-   * This method does not care about the tertiary argument. Regardless of the conditions of how you
-   * registered the callback, it will be removed.
+   * Unregisters a function that was previously registered with the `AddCallbackCustom` method.
+   *
+   * This method does not care about the tertiary argument. In other words, regardless of the
+   * conditions of how you registered the callback, it will be removed.
    */
-  RemoveCallbackCustom<T extends ModCallbackCustom>(
-    modCallback: T,
-    callback: AddCallbackParametersCustom[T][0],
+  public RemoveCallbackCustom<T extends ModCallbackCustom2>(
+    modCallbackCustom: T,
+    callback: AddCallbackParametersCustom2[T][0],
   ): void {
-    print(this, modCallback, callback); // TODO
+    const callbackClass = this.callbacks[modCallbackCustom];
+    // @ts-expect-error The compiler is not smart enough to figure out that the parameters match.
+    callbackClass.remove(callback);
+    if (!callbackClass.hasSubscriptions()) {
+      this.uninitFeature(callbackClass);
+    }
+  }
+
+  /**
+   * This method should only be used by the `upgradeMod` function. Returns the class methods from
+   * the features that were added.
+   */
+  public initOptionalFeature(feature: ISCFeature): FunctionTuple[] {
+    const featureClass = this.features[feature];
+    this.initFeature(featureClass);
+
+    return getTSTLClassMethods(featureClass);
+  }
+
+  // ----------------------
+  // Custom private methods
+  // ----------------------
+
+  /** This is used to initialize both custom callbacks and "extra features". */
+  private initFeature(feature: Feature): void {
+    if (feature.initialized) {
+      return;
+    }
+    feature.initialized = true;
+
+    if (feature.featuresUsed !== undefined) {
+      for (const featureUsed of feature.featuresUsed) {
+        const featureClass = this.features[featureUsed];
+        this.initFeature(featureClass);
+      }
+    }
+
+    if (feature.callbacksUsed !== undefined) {
+      for (const callbackTuple of feature.callbacksUsed) {
+        const [modCallback, callbackArgs] = callbackTuple;
+        this.AddCallback(modCallback, ...callbackArgs);
+      }
+    }
+
+    if (feature.customCallbacksUsed !== undefined) {
+      for (const callbackTuple of feature.customCallbacksUsed) {
+        const [modCallback, callbackArgs] = callbackTuple;
+        this.AddCallbackCustom2(modCallback, ...callbackArgs);
+      }
+    }
+
+    if (feature.v !== undefined) {
+      const className = getTSTLClassName(feature);
+      if (className === undefined) {
+        error("Failed to get the name of a feature.");
+      }
+      saveDataManager(className, feature.v);
+    }
+  }
+
+  private uninitFeature(feature: Feature): void {
+    if (!feature.initialized) {
+      return;
+    }
+    feature.initialized = false;
+
+    if (feature.featuresUsed !== undefined) {
+      for (const featureUsed of feature.featuresUsed) {
+        const featureClass = this.features[featureUsed];
+        this.uninitFeature(featureClass);
+      }
+    }
+
+    if (feature.callbacksUsed !== undefined) {
+      for (const callbackTuple of feature.callbacksUsed) {
+        const [modCallback, callbackArgs] = callbackTuple;
+        const callback = callbackArgs[0];
+        this.RemoveCallback(modCallback, callback);
+      }
+    }
+
+    if (feature.customCallbacksUsed !== undefined) {
+      for (const callbackTuple of feature.customCallbacksUsed) {
+        const [modCallback, callbackArgs] = callbackTuple;
+        const callback = callbackArgs[0];
+        this.RemoveCallbackCustom(modCallback, callback);
+      }
+    }
+
+    if (feature.v !== undefined) {
+      const className = getTSTLClassName(feature);
+      if (className === undefined) {
+        error("Failed to get the name of a feature.");
+      }
+      saveDataManagerRemove(className);
+    }
   }
 }

package/src/classes/callbacks/PostAmbushFinished.ts

@@ -0,0 +1,39 @@
+import { ModCallback } from "isaac-typescript-definitions";
+import { game } from "../../core/cachedClasses";
+import { ModCallbackCustom2 } from "../../enums/ModCallbackCustom2";
+import { getAmbushType } from "../../functions/ambush";
+import { CustomCallbackAmbush } from "./validation/CustomCallbackAmbush";
+
+export class PostAmbushFinished extends CustomCallbackAmbush<ModCallbackCustom2.POST_AMBUSH_FINISHED> {
+  public override v = {
+    room: {
+      ambushDone: false,
+    },
+  };
+
+  constructor() {
+    super();
+
+    this.callbacksUsed = [
+      [ModCallback.POST_UPDATE, [this.postUpdate]], // 1
+    ];
+  }
+
+  private postUpdate = (): void => {
+    if (this.v.room.ambushDone) {
+      return;
+    }
+
+    const room = game.GetRoom();
+    const ambushDone = room.IsAmbushDone();
+    if (!ambushDone) {
+      return;
+    }
+    this.v.room.ambushDone = true;
+
+    const ambushType = getAmbushType();
+    if (ambushType !== undefined) {
+      this.fire(ambushType);
+    }
+  };
+}

package/src/classes/callbacks/PostAmbushStarted.ts

@@ -0,0 +1,39 @@
+import { ModCallback } from "isaac-typescript-definitions";
+import { game } from "../../core/cachedClasses";
+import { ModCallbackCustom2 } from "../../enums/ModCallbackCustom2";
+import { getAmbushType } from "../../functions/ambush";
+import { CustomCallbackAmbush } from "./validation/CustomCallbackAmbush";
+
+export class PostAmbushStarted extends CustomCallbackAmbush<ModCallbackCustom2.POST_AMBUSH_STARTED> {
+  public override v = {
+    room: {
+      ambushActive: false,
+    },
+  };
+
+  constructor() {
+    super();
+
+    this.callbacksUsed = [
+      [ModCallback.POST_UPDATE, [this.postUpdate]], // 1
+    ];
+  }
+
+  private postUpdate = (): void => {
+    if (this.v.room.ambushActive) {
+      return;
+    }
+
+    const room = game.GetRoom();
+    const ambushActive = room.IsAmbushActive();
+    if (!ambushActive) {
+      return;
+    }
+    this.v.room.ambushActive = true;
+
+    const ambushType = getAmbushType();
+    if (ambushType !== undefined) {
+      this.fire(ambushType);
+    }
+  };
+}

package/src/classes/callbacks/PostBombExploded.ts

@@ -0,0 +1,21 @@
+import { ModCallback } from "isaac-typescript-definitions";
+import { BOMB_EXPLODE_FRAME } from "../../core/constants";
+import { ModCallbackCustom2 } from "../../enums/ModCallbackCustom2";
+import { CustomCallbackBomb } from "./validation/CustomCallbackBomb";
+
+export class PostBombExploded extends CustomCallbackBomb<ModCallbackCustom2.POST_BOMB_EXPLODED> {
+  constructor() {
+    super();
+
+    this.callbacksUsed = [
+      [ModCallback.POST_BOMB_UPDATE, [this.postBombUpdate]], // 58
+    ];
+  }
+
+  // ModCallback.POST_BOMB_UPDATE (58)
+  private postBombUpdate = (bomb: EntityBomb): void => {
+    if (bomb.FrameCount === BOMB_EXPLODE_FRAME) {
+      this.fire(bomb);
+    }
+  };
+}

package/src/classes/callbacks/PostBombInitLate.ts

@@ -0,0 +1,28 @@
+import { ModCallback } from "isaac-typescript-definitions";
+import { ModCallbackCustom2 } from "../../enums/ModCallbackCustom2";
+import { CustomCallbackBomb } from "./validation/CustomCallbackBomb";
+
+export class PostBombInitLate extends CustomCallbackBomb<ModCallbackCustom2.POST_BOMB_INIT_LATE> {
+  public override v = {
+    room: {
+      firedSet: new Set<PtrHash>(),
+    },
+  };
+
+  constructor() {
+    super();
+
+    this.callbacksUsed = [
+      [ModCallback.POST_BOMB_UPDATE, [this.postBombUpdate]], // 58
+    ];
+  }
+
+  // ModCallback.POST_BOMB_UPDATE (58)
+  private postBombUpdate = (bomb: EntityBomb): void => {
+    const ptrHash = GetPtrHash(bomb);
+    if (!this.v.room.firedSet.has(ptrHash)) {
+      this.v.room.firedSet.add(ptrHash);
+      this.fire(bomb);
+    }
+  };
+}

package/src/classes/callbacks/PostBoneSwing.ts

@@ -0,0 +1,61 @@
+import { KnifeVariant, ModCallback } from "isaac-typescript-definitions";
+import { ModCallbackCustom2 } from "../../enums/ModCallbackCustom2";
+import { CustomCallback } from "../private/CustomCallback";
+
+const BONE_SWING_ANIMATIONS: ReadonlySet<string> = new Set([
+  "Swing",
+  "Swing2",
+  "Spin",
+]);
+
+export class PostBoneSwing extends CustomCallback<ModCallbackCustom2.POST_BONE_SWING> {
+  public override v = {
+    room: {
+      boneClubAnimations: new Map<PtrHash, string>(),
+    },
+  };
+
+  constructor() {
+    super();
+
+    this.callbacksUsed = [
+      [ModCallback.POST_KNIFE_RENDER, [this.postKnifeRender]], // 52
+    ];
+  }
+
+  // ModCallback.POST_KNIFE_RENDER (52)
+  private postKnifeRender = (knife: EntityKnife): void => {
+    // The tertiary argument of the `POST_KNIFE_RENDER` callback takes sub-types instead of knife
+    // variants.
+    if (knife.Variant === KnifeVariant.BONE_CLUB) {
+      this.postKnifeRenderBoneClub(knife);
+    }
+  };
+
+  // ModCallback.POST_KNIFE_RENDER (52)
+  // KnifeVariant.BONE_CLUB (1)
+  private postKnifeRenderBoneClub(knife: EntityKnife): void {
+    const sprite = knife.GetSprite();
+    const animation = sprite.GetAnimation();
+    const ptrHash = GetPtrHash(knife);
+
+    const animationOnLastFrame = this.v.room.boneClubAnimations.get(ptrHash);
+    this.v.room.boneClubAnimations.set(ptrHash, animation);
+
+    if (
+      animationOnLastFrame !== undefined &&
+      animation !== animationOnLastFrame
+    ) {
+      this.boneClubAnimationChanged(knife, animation);
+    }
+  }
+
+  private boneClubAnimationChanged(
+    knife: EntityKnife,
+    animation: string,
+  ): void {
+    if (BONE_SWING_ANIMATIONS.has(animation)) {
+      this.fire(knife);
+    }
+  }
+}

package/src/classes/callbacks/PostCollectibleEmpty.ts

@@ -0,0 +1,72 @@
+import {
+  CollectibleType,
+  ModCallback,
+  PickupVariant,
+} from "isaac-typescript-definitions";
+import { ModCallbackCustom2 } from "../../enums/ModCallbackCustom2";
+import {
+  CustomCallback,
+  FireArgs,
+  OptionalArgs,
+} from "../private/CustomCallback";
+
+type T = ModCallbackCustom2.POST_COLLECTIBLE_EMPTY;
+
+export class PostCollectibleEmpty extends CustomCallback<T> {
+  public override v = {
+    room: {
+      collectibleTypeMap: new Map<PtrHash, CollectibleType>(),
+    },
+  };
+
+  constructor() {
+    super();
+
+    this.callbacksUsed = [
+      [
+        ModCallback.POST_PICKUP_UPDATE,
+        [this.postPickupUpdateCollectible, PickupVariant.COLLECTIBLE],
+      ], // 35
+    ];
+  }
+
+  // eslint-disable-next-line class-methods-use-this
+  protected override shouldFire(
+    fireArgs: FireArgs<T>,
+    optionalArgs: OptionalArgs<T>,
+  ): boolean {
+    const [callbackCollectibleType] = optionalArgs;
+    if (callbackCollectibleType === undefined) {
+      return true;
+    }
+
+    const [_collectible, oldCollectibleType] = fireArgs;
+    return oldCollectibleType === callbackCollectibleType;
+  }
+
+  // ModCallback.POST_PICKUP_UPDATE (35)
+  // PickupVariant.COLLECTIBLE (100)
+  private postPickupUpdateCollectible = (pickup: EntityPickup): void => {
+    const collectible = pickup as EntityPickupCollectible;
+
+    const ptrHash = GetPtrHash(collectible);
+    let oldCollectibleType = this.v.room.collectibleTypeMap.get(ptrHash);
+    if (oldCollectibleType === undefined) {
+      oldCollectibleType = collectible.SubType;
+    }
+    this.v.room.collectibleTypeMap.set(ptrHash, collectible.SubType);
+
+    if (oldCollectibleType !== collectible.SubType) {
+      this.collectibleTypeChanged(collectible, oldCollectibleType);
+    }
+  };
+
+  private collectibleTypeChanged(
+    collectible: EntityPickupCollectible,
+    oldCollectibleType: CollectibleType,
+  ): void {
+    if (collectible.SubType === CollectibleType.NULL) {
+      this.fire(collectible, oldCollectibleType);
+    }
+  }
+}

package/src/classes/callbacks/PostCollectibleInitFirst.ts

@@ -0,0 +1,37 @@
+import { ModCallback, PickupVariant } from "isaac-typescript-definitions";
+import { ModCallbackCustom2 } from "../../enums/ModCallbackCustom2";
+import { getCollectibleIndex } from "../../functions/collectibles";
+import { CollectibleIndex } from "../../types/CollectibleIndex";
+import { CustomCallbackCollectible } from "./validation/CustomCallbackCollectible";
+
+export class PostCollectibleInitFirst extends CustomCallbackCollectible<ModCallbackCustom2.POST_COLLECTIBLE_INIT_FIRST> {
+  public override v = {
+    run: {
+      seenCollectibles: new Set<CollectibleIndex>(),
+    },
+  };
+
+  constructor() {
+    super();
+
+    this.callbacksUsed = [
+      [
+        ModCallback.POST_PICKUP_INIT,
+        [this.postPickupInitCollectible, PickupVariant.COLLECTIBLE],
+      ], // 34
+    ];
+  }
+
+  // ModCallback.POST_PICKUP_INIT (34)
+  // PickupVariant.COLLECTIBLE (100)
+  private postPickupInitCollectible = (pickup: EntityPickup): void => {
+    const collectible = pickup as EntityPickupCollectible;
+    const collectibleIndex = getCollectibleIndex(collectible);
+    if (this.v.run.seenCollectibles.has(collectibleIndex)) {
+      return;
+    }
+
+    this.v.run.seenCollectibles.add(collectibleIndex);
+    this.fire(collectible);
+  };
+}