isaacscript-common 13.3.4 → 14.1.0

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

@@ -0,0 +1,256 @@
+import { ModCallback } from "isaac-typescript-definitions";
+import { game } from "../../../core/cachedClasses";
+import { arrayRemoveInPlace } from "../../../functions/array";
+import { Feature } from "../../private/Feature";
+
+/** Used for `runInNFrames` functions. */
+type QueuedFunctionTuple = [frameCountToFire: int, func: () => void];
+
+/**
+ * Used for `setInterval` functions.
+ *
+ * The return value is whether or not to continue the function from firing.
+ */
+type IntervalFunctionTuple = [
+  frameCountToFire: int,
+  func: () => boolean,
+  numIntervalFrames: int,
+];
+
+export class RunInNFrames extends Feature {
+  public override v = {
+    run: {
+      queuedGameFunctionTuples: [] as QueuedFunctionTuple[],
+      queuedRenderFunctionTuples: [] as QueuedFunctionTuple[],
+
+      intervalGameFunctionTuples: [] as IntervalFunctionTuple[],
+      intervalRenderFunctionTuples: [] as IntervalFunctionTuple[],
+    },
+  };
+
+  constructor() {
+    super();
+
+    this.callbacksUsed = [
+      [ModCallback.POST_UPDATE, [this.postUpdate]], // 1
+      [ModCallback.POST_RENDER, [this.postRender]], // 2
+    ];
+  }
+
+  // ModCallback.POST_UPDATE (1)
+  private postUpdate = (): void => {
+    const gameFrameCount = game.GetFrameCount();
+
+    checkExecuteQueuedFunctions(
+      gameFrameCount,
+      this.v.run.queuedGameFunctionTuples,
+    );
+    checkExecuteIntervalFunctions(
+      gameFrameCount,
+      this.v.run.intervalGameFunctionTuples,
+    );
+  };
+
+  // ModCallback.POST_RENDER (2)
+  private postRender = (): void => {
+    const renderFrameCount = Isaac.GetFrameCount();
+
+    checkExecuteQueuedFunctions(
+      renderFrameCount,
+      this.v.run.queuedRenderFunctionTuples,
+    );
+    checkExecuteIntervalFunctions(
+      renderFrameCount,
+      this.v.run.intervalRenderFunctionTuples,
+    );
+  };
+
+  // --------------
+  // Public methods
+  // --------------
+
+  /**
+   * Supply a function to run N game frames from now in the `POST_UPDATE` callback.
+   *
+   * For a usage example, see the documentation for the `runNextGameFrame`, which is used in a
+   * similar way.
+   *
+   * Note that this function will not handle saving and quitting. If a player saving and quitting
+   * before the deferred function fires would cause a bug in your mod, then you should handle
+   * deferred functions manually using serializable data.
+   */
+  public runInNGameFrames(func: () => void, gameFrames: int): void {
+    const gameFrameCount = game.GetFrameCount();
+    const functionFireFrame = gameFrameCount + gameFrames;
+    const tuple: QueuedFunctionTuple = [functionFireFrame, func];
+    this.v.run.queuedGameFunctionTuples.push(tuple);
+  }
+
+  /**
+   * Supply a function to run N render frames from now in the `POST_RENDER` callback.
+   *
+   * For a usage example, see the documentation for the `runNextGameFrame`, which is used in a
+   * similar way.
+   *
+   * Note that this function will not handle saving and quitting. If a player saving and quitting
+   * before the deferred function fires would cause a bug in your mod, then you should handle
+   * deferred functions manually using serializable data.
+   */
+  public runInNRenderFrames(func: () => void, renderFrames: int): void {
+    const renderFrameCount = Isaac.GetFrameCount();
+    const functionFireFrame = renderFrameCount + renderFrames;
+    const tuple: QueuedFunctionTuple = [functionFireFrame, func];
+    this.v.run.queuedRenderFunctionTuples.push(tuple);
+  }
+
+  /**
+   * Supply a function to run on the next `POST_UPDATE` callback.
+   *
+   * For example:
+   *
+   * ```ts
+   * const NUM_EXPLODER_EXPLOSIONS = 5;
+   *
+   * function useItemExploder(player: EntityPlayer) {
+   *   playSound("exploderBegin");
+   *   explode(player, NUM_EXPLODER_EXPLOSIONS);
+   * }
+   *
+   * function explode(player: EntityPlayer, numFramesLeft: int) {
+   *   Isaac.Explode(player, undefined, 1);
+   *   numFramesLeft -= 1;
+   *   if (numFramesLeft === 0) {
+   *     runNextFrame(() => {
+   *       explode(player, numFramesLeft);
+   *     });
+   *   }
+   * }
+   * ```
+   *
+   * Note that this function will not handle saving and quitting. If a player saving and quitting
+   * before the deferred function fires would cause a bug in your mod, then you should handle
+   * deferred functions manually using serializable data.
+   */
+  public runNextGameFrame(func: () => void): void {
+    this.runInNGameFrames(func, 1);
+  }
+
+  /**
+   * Supply a function to run on the next `POST_RENDER` callback.
+   *
+   * For a usage example, see the documentation for the `runNextGameFrame`, which is used in a
+   * similar way.
+   *
+   * Note that this function will not handle saving and quitting.
+   */
+  public runNextRenderFrame(func: () => void): void {
+    this.runInNRenderFrames(func, 1);
+  }
+
+  /**
+   * Supply a function to be repeatedly run on an interval of N game frames in the `POST_UPDATE`
+   * callback. The function will continue to be fired until `false` is returned from the function.
+   *
+   * This is similar to the `setInterval` vanilla JavaScript function, except there is no
+   * corresponding `clearInterval` function. (Instead, the return value from the supplied function
+   * is used to stop the interval.)
+   *
+   * Note that this function will not handle saving and quitting. You must manually restart any
+   * intervals if the player saves and quits in the middle of a run.
+   *
+   * @param func The function to repeatedly run on an interval.
+   * @param gameFrames The amount of game frames to wait between each run.
+   * @param runImmediately Whether or not to execute the function right now before waiting for the
+   *                       interval.
+   */
+  public setIntervalGameFrames(
+    func: () => boolean,
+    gameFrames: int,
+    runImmediately: boolean,
+  ): void {
+    const gameFrameCount = game.GetFrameCount();
+    const functionFireFrame = gameFrameCount + gameFrames;
+    const tuple: IntervalFunctionTuple = [functionFireFrame, func, gameFrames];
+    this.v.run.intervalGameFunctionTuples.push(tuple);
+
+    if (runImmediately) {
+      func();
+    }
+  }
+
+  /**
+   * Supply a function to be repeatedly run on an interval of N render frames in the `POST_RENDER`
+   * callback. The function will continue to be fired until `false` is returned from the function.
+   *
+   * This is similar to the `setInterval` vanilla JavaScript function, except there is no
+   * corresponding `clearInterval` function. (Instead, the return value from the supplied function
+   * is used to stop the interval.)
+   *
+   * Note that this function will not handle saving and quitting. You must manually restart any
+   * intervals if the player saves and quits in the middle of a run.
+   *
+   * @param func The function to repeatedly run on an interval.
+   * @param renderFrames The amount of game frames to wait between each run.
+   * @param runImmediately Whether or not to execute the function right now before waiting for the
+   *                       interval.
+   */
+  public setIntervalRenderFrames(
+    func: () => boolean,
+    renderFrames: int,
+    runImmediately: boolean,
+  ): void {
+    const renderFrameCount = Isaac.GetFrameCount();
+    const functionFireFrame = renderFrameCount + renderFrames;
+    const tuple: IntervalFunctionTuple = [
+      functionFireFrame,
+      func,
+      renderFrames,
+    ];
+    this.v.run.intervalGameFunctionTuples.push(tuple);
+
+    if (runImmediately) {
+      func();
+    }
+  }
+}
+
+function checkExecuteQueuedFunctions(
+  frameCount: int,
+  functionTuples: QueuedFunctionTuple[],
+) {
+  const firingFunctions = functionTuples.filter(
+    ([frameCountToFire]) => frameCount >= frameCountToFire,
+  );
+
+  for (const tuple of firingFunctions) {
+    const [_frameCountToFire, func] = tuple;
+    func();
+    arrayRemoveInPlace(functionTuples, tuple);
+  }
+}
+
+function checkExecuteIntervalFunctions(
+  frameCount: int,
+  functionTuples: IntervalFunctionTuple[],
+) {
+  const firingFunctions = functionTuples.filter(
+    ([frameCountToFire]) => frameCount >= frameCountToFire,
+  );
+
+  for (const tuple of firingFunctions) {
+    const [_frameCountToFire, func, numIntervalFrames] = tuple;
+    const returnValue = func();
+    arrayRemoveInPlace(functionTuples, tuple);
+
+    // Queue the next interval (as long as the function did not return false).
+    if (returnValue) {
+      const nextFireFrame = frameCount + numIntervalFrames;
+      const newTuple: IntervalFunctionTuple = [
+        nextFireFrame,
+        func,
+        numIntervalFrames,
+      ];
+      functionTuples.push(newTuple);
+    }
+  }
+}

package/src/classes/private/CustomCallback.ts

@@ -0,0 +1,82 @@
+import { ModCallbackCustom2 } from "../../enums/ModCallbackCustom2";
+import { AddCallbackParametersCustom2 } from "../../interfaces/private/AddCallbackParametersCustom2";
+import { AllButFirst } from "../../types/private/AllButFirst";
+import { Feature } from "./Feature";
+
+export type FireArgs<T extends ModCallbackCustom2> = Parameters<
+  AddCallbackParametersCustom2[T][0]
+>;
+export type OptionalArgs<T extends ModCallbackCustom2> = AllButFirst<
+  AddCallbackParametersCustom2[T]
+>;
+
+/**
+ * The base class for a custom callback. Individual custom callbacks (and validation callbacks) will
+ * extend from this class.
+ */
+export abstract class CustomCallback<
+  T extends ModCallbackCustom2,
+> extends Feature {
+  private subscriptions: Array<AddCallbackParametersCustom2[T]> = [];
+
+  public hasSubscriptions(): boolean {
+    return this.subscriptions.length > 0;
+  }
+
+  public add(...args: AddCallbackParametersCustom2[T]): void {
+    this.subscriptions.push(args);
+  }
+
+  /**
+   * If the submitted function does not match any of the existing subscriptions, this method will do
+   * nothing.
+   */
+  public remove(callback: AddCallbackParametersCustom2[T][0]): void {
+    const subscriptionIndexMatchingCallback = this.subscriptions.findIndex(
+      (subscription) => {
+        const subscriptionCallback = subscription[0];
+        return callback === subscriptionCallback;
+      },
+    );
+    if (subscriptionIndexMatchingCallback !== -1) {
+      this.subscriptions.splice(subscriptionIndexMatchingCallback, 1);
+    }
+  }
+
+  public fire = (
+    ...fireArgs: FireArgs<T>
+  ): ReturnType<AddCallbackParametersCustom2[T][0]> => {
+    for (const [callback, ...optionalArgsArray] of this.subscriptions) {
+      // The TypeScript compiler is bugged with the spread operator here, as it converts the
+      // optional arguments to an array instead of a tuple.
+      const optionalArgs = optionalArgsArray as OptionalArgs<T>;
+
+      if (this.shouldFire(fireArgs, optionalArgs)) {
+        // The TypeScript compiler is not smart enough to know that the fire args match the callback
+        // signature.
+        const callbackCasted = callback as (
+          ...args: FireArgs<T>
+        ) => ReturnType<AddCallbackParametersCustom2[T][0]>;
+        const value = callbackCasted(...fireArgs);
+        if (value !== undefined) {
+          return value;
+        }
+      }
+    }
+
+    return undefined as ReturnType<AddCallbackParametersCustom2[T][0]>;
+  };
+
+  /**
+   * This method needs to be overwritten for any callback that has optional filtration arguments.
+   */
+  // eslint-disable-next-line class-methods-use-this
+  protected shouldFire(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    fireArgs: FireArgs<T>,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    optionalArgs: OptionalArgs<T>,
+  ): boolean {
+    return true;
+  }
+}

package/src/classes/private/Feature.ts

@@ -0,0 +1,24 @@
+import { ISCFeature } from "../../enums/ISCFeature";
+import { SaveData } from "../../interfaces/SaveData";
+import {
+  CallbackTuple,
+  CustomCallbackTuple,
+} from "../../types/private/CallbackTuple";
+
+/**
+ * The IsaacScript standard library contains many optional features, such as the ability to create
+ * custom pickups. All features are optional and are only initialized when needed. This class
+ * contains elements to facilitate that.
+ *
+ * Additionally, all custom callbacks extend from this class.
+ */
+export class Feature {
+  public initialized = false;
+
+  public v?: SaveData;
+  public featuresUsed?: ISCFeature[];
+  public callbacksUsed?: CallbackTuple[];
+  public customCallbacksUsed?: CustomCallbackTuple[];
+
+  public exportedMethods: string[] = [];
+}

package/src/core/upgradeMod.ts

@@ -1,6 +1,13 @@
 import { postNewRoomEarlyCallbackInit } from "../callbacks/postNewRoomEarly";
 import { ModUpgraded } from "../classes/ModUpgraded";
-import { saveDataManagerInit } from "../features/saveDataManager/main";
+import { Feature } from "../classes/private/Feature";
+import { ISCFeature } from "../enums/ISCFeature";
+import { ISCFeatureToClass } from "../features";
+import {
+  saveDataManagerInit,
+  SAVE_DATA_MANAGER_CALLBACKS,
+  SAVE_DATA_MANAGER_CUSTOM_CALLBACKS,
+} from "../features/saveDataManager/main";
 import {
   areFeaturesInitialized,
   setFeaturesInitialized,
@@ -9,6 +16,24 @@ import { initCustomCallbacks } from "../initCustomCallbacks";
 import { initFeatures } from "../initFeatures";
 import { patchErrorFunction } from "../patchErrorFunctions";
 import { loadShaderCrashFix } from "../shaderCrashFix";
+import { LowercaseKeys } from "../types/LowercaseKeys";
+import { UnionToIntersection } from "../types/UnionToIntersection";
+
+/**
+ * By specifying one or more optional features, end-users will get a version of `ModUpgraded` that
+ * has extra methods corresponding to the features.
+ *
+ * We have to explicitly account for the empty array case, since `never` will cause mess up the
+ * union.
+ */
+type ModUpgradedWithFeatures<T extends ISCFeature> = [T] extends [never]
+  ? ModUpgraded
+  : Omit<
+      ModUpgraded & UnionToIntersection<ISCFeatureToClass[T]>,
+      KeysToScrubFromModClass
+    >;
+
+type KeysToScrubFromModClass = keyof Feature | LowercaseKeys<ModUpgraded>;
 
 /**
  * Use this function to enable the custom callbacks and other optional features provided by
@@ -28,6 +53,8 @@ import { loadShaderCrashFix } from "../shaderCrashFix";
  * ```
  *
  * @param modVanilla The mod object returned by the `RegisterMod` function.
+ * @param features Optional. An array containing the optional standard library features that you
+ *                 want to enable, if any. Default is an empty array.
  * @param debug Optional. Whether to log additional output when a callback is fired. Default is
  *              false.
  * @param timeThreshold Optional. If provided, will only log callbacks that take longer than the
@@ -35,32 +62,65 @@ import { loadShaderCrashFix } from "../shaderCrashFix";
  *                      or milliseconds (if the "--luadebug" launch flag is turned off).
  * @returns The upgraded mod object.
  */
-export function upgradeMod(
+export function upgradeMod<T extends ISCFeature = never>(
   modVanilla: Mod,
+  features: T[] = [],
   debug = false,
   timeThreshold?: float,
-): ModUpgraded {
+): ModUpgradedWithFeatures<T> {
   const mod = new ModUpgraded(modVanilla, debug, timeThreshold);
 
-  if (!areFeaturesInitialized()) {
-    setFeaturesInitialized();
+  if (areFeaturesInitialized()) {
+    error(
+      "Failed to upgrade the mod since a mod has already been initialized. (You can only upgrade one mod per IsaacScript project.)",
+    );
+  }
+  setFeaturesInitialized();
 
-    patchErrorFunction();
-    loadShaderCrashFix(modVanilla);
+  patchErrorFunction();
+  loadShaderCrashFix(modVanilla);
 
-    // We initialize the `POST_NEW_ROOM_EARLY` callback first since it is used by the save data
-    // manager.
-    postNewRoomEarlyCallbackInit(mod);
+  legacyInit(mod); // TODO: remove
 
-    // We initialized the save data manager second since it is used by the other custom callbacks
-    // and features.
-    saveDataManagerInit(mod);
+  for (const feature of features) {
+    const tstlClassMethods = mod.initOptionalFeature(feature);
 
-    // We initialize custom callbacks next since some features use custom callbacks.
-    initCustomCallbacks(mod);
+    // If the optional feature provides helper functions, attach them to the base mod object. (This
+    // provides a convenient API for end-users.)
+    const modRecord = mod as unknown as Record<
+      string,
+      (...args: unknown[]) => unknown
+    >;
+    for (const [funcName, func] of tstlClassMethods) {
+      modRecord[funcName] = func;
+    }
+  }
+
+  return mod as ModUpgradedWithFeatures<T>;
+}
 
-    initFeatures(mod);
+/** Initialize features in the old way. */
+function legacyInit(mod: ModUpgraded) {
+  // We initialize the `POST_NEW_ROOM_EARLY` callback first since it is used by the save data
+  // manager.
+  postNewRoomEarlyCallbackInit(mod);
+
+  // We initialized the save data manager second since it is used by the other custom callbacks and
+  // features. We can't pass the instantiated `ModUpgraded` class to the "saveDataManagerInit"
+  // function since it causes a circular dependency. Thus, we emulate the initialization process
+  // that the `ModUpgraded.AddCallbackCustom` method uses.
+  saveDataManagerInit(mod);
+  for (const callbackTuple of SAVE_DATA_MANAGER_CALLBACKS) {
+    const [modCallback, callbackArgs] = callbackTuple;
+    mod.AddCallback(modCallback, ...callbackArgs);
+  }
+  for (const callbackTuple of SAVE_DATA_MANAGER_CUSTOM_CALLBACKS) {
+    const [modCallback, callbackArgs] = callbackTuple;
+    mod.AddCallbackCustom(modCallback, ...callbackArgs);
   }
 
-  return mod;
+  // We initialize custom callbacks next since some features use custom callbacks.
+  initCustomCallbacks(mod);
+
+  initFeatures(mod);
 }

package/src/decorators.ts

@@ -0,0 +1,13 @@
+import { Feature } from "./classes/private/Feature";
+
+/**
+ * A decorator function that signifies that the decorated class method should be added to the
+ * `ModUpgraded` object.
+ *
+ * This is only meant to be used internally.
+ */
+export function Exported() {
+  return <T extends Feature>(target: T, propertyKey: keyof T): void => {
+    target.exportedMethods.push(propertyKey as string);
+  };
+}

package/src/enums/ISCFeature.ts

@@ -0,0 +1,47 @@
+/* eslint-disable isaacscript/format-line-comments */
+/* eslint-disable isaacscript/complete-sentences-line-comments */
+
+export enum ISCFeature {
+  // Callback logic
+  CUSTOM_REVIVE = "CustomRevive",
+  ESAU_JR_DETECTION = "EsauJrDetection",
+  FLIP_DETECTION = "FlipDetection",
+  GRID_ENTITY_COLLISION_DETECTION = "GridEntityCollisionDetection",
+  GRID_ENTITY_DETECTION = "GridEntityDetection",
+  GAME_REORDERED_CALLBACKS = "GameReorderedCallbacks",
+  PLAYER_REORDERED_CALLBACKS = "PlayerReorderedCallbacks",
+
+  // Extra features
+  // CHARACTER_HEALTH_CONVERSION = "characterHealthConversion",
+  // CHARACTER_STATS = "characterStats",
+  // COLLECTIBLE_ITEM_POOL_TYPE = "collectibleItemPoolType",
+  CUSTOM_GRID_ENTITIES = "CustomGridEntities",
+  // CUSTOM_HOTKEYS = "customHotkeys",
+  // CUSTOM_PICKUP = "customPickup",
+  // CUSTOM_STAGE = "customStage",
+  // CUSTOM_TRAPDOOR = "customTrapdoor",
+  // DEBUG_DISPLAY = "debugDisplay",
+  // DEPLOY_JSON_ROOM = "deployJSONRoom",
+  // DISABLE_ALL_SOUND = "displayAllSound",
+  // DISABLE_INPUTS = "disableInputs",
+  // FADE_IN_REMOVER = "fadeInRemover",
+  // FAST_RESET = "fastReset",
+  // FIRST_LAST = "firstLast",
+  // FORGOTTEN_SWITCH = "forgottenSwitch",
+  // EXTRA_CONSOLE_COMMANDS = "extraConsoleCommands",
+  // PAUSE = "pause",
+  // PERSISTENT_ENTITIES = "persistentEntities",
+  // PICKUP_INDEX = "pickupIndex",
+  // PLAYER_INVENTORY = "playerInventory",
+  // PONY_DETECTION = "ponyDetection",
+  // PREVENT_CHILD_ENTITIES = "preventChildEntities",
+  // PREVENT_COLLECTIBLE_ROTATION = "preventCollectibleRotation",
+  // ROOM_CLEAR_FRAME = "roomClearFrame",
+  // ROOM_HISTORY = "roomHistory",
+  RUN_IN_N_FRAMES = "runInNFrames",
+  // RUN_NEXT_ROOM = "runNextRoom",
+  // SAVE_DATA_MANAGER = "saveDataManager",
+  // SIREN_HELPERS = "sirenHelpers",
+  // STAGE_HISTORY = "stageHistory",
+  // TAINTED_LAZARUS_PLAYERS = "taintedLazarusPlayers",
+}

package/src/enums/LadderSubTypeCustom.ts

@@ -0,0 +1,17 @@
+/**
+ * For `EntityType.EFFECT` (1000), `EffectVariant.LADDER` (8).
+ *
+ * Note that vanilla ladders only use a sub-type of 0. The `isaacscript-common` library uses ladders
+ * to represent custom objects, since they are non-interacting and will not automatically despawn
+ * after time passes, unlike most other effects.
+ *
+ * This enum tracks the kinds of custom objects that are represented by vanilla ladders. We start
+ * assigning sub-types after 100 as to not interfere with any possible modded ladder variants.
+ */
+export enum LadderSubTypeCustom {
+  LADDER = 0,
+
+  CUSTOM_BACKDROP = 101,
+  CUSTOM_SHADOW = 102,
+  CUSTOM_PICKUP = 103,
+}