isaacscript-common 15.2.0 → 15.3.0

package/src/classes/ModFeature.ts

@@ -1,5 +1,7 @@
 import { ModCallback } from "isaac-typescript-definitions";
 import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { isArray } from "../functions/array";
+import { deepCopy } from "../functions/deepCopy";
 import {
   getTSTLClassConstructor,
   getTSTLClassName,
@@ -11,10 +13,14 @@ import { ModUpgradedBase } from "./ModUpgradedBase";
 
 export const ADD_CALLBACK_ARGS_KEY = "__addCallbackArgs";
 export const ADD_CALLBACK_CUSTOM_ARGS_KEY = "__addCallbackCustomArgs";
+const WRAPPED_CALLBACK_METHODS_KEY = "__wrappedCallbackMethods";
+const WRAPPED_CUSTOM_CALLBACK_METHODS_KEY = "__wrappedCustomCallbacksMethods";
 
 type ModFeatureConstructor = TSTLClassMetatable["constructor"] & {
-  [ADD_CALLBACK_ARGS_KEY]: unknown[] | undefined;
-  [ADD_CALLBACK_CUSTOM_ARGS_KEY]: unknown[] | undefined;
+  [ADD_CALLBACK_ARGS_KEY]: unknown | undefined;
+  [ADD_CALLBACK_CUSTOM_ARGS_KEY]: unknown | undefined;
+  [WRAPPED_CALLBACK_METHODS_KEY]: Map<ModCallback, AnyFunction>;
+  [WRAPPED_CUSTOM_CALLBACK_METHODS_KEY]: Map<ModCallbackCustom, AnyFunction>;
 };
 
 /**
@@ -42,86 +48,83 @@ type ModFeatureConstructor = TSTLClassMetatable["constructor"] & {
  *   }
  * }
  * ```
+ *
+ * In almost all cases, you will want the callback functions to be immediately subscribed after
+ * instantiating the class. However, if this is not the case, you can pass `false` as the optional
+ * second argument to the constructor.
  */
-// eslint-disable-next-line @typescript-eslint/no-extraneous-class
+
 export class ModFeature {
-  constructor(mod: ModUpgradedBase) {
+  private mod: ModUpgradedBase;
+
+  constructor(mod: ModUpgradedBase, init = true) {
+    this.mod = mod;
+
+    if (init) {
+      this.init();
+    }
+  }
+
+  /**
+   * Runs the `Mod.AddCallback` and `ModUpgraded.AddCallbackCustom` methods for all of the decorated
+   * callbacks. Additionally, subscribes the `v` object to the save data manager, if present.
+   */
+  public init(init = true): void {
     const constructor = getTSTLClassConstructor(this);
     if (constructor === undefined) {
       error("Failed to get the TSTL class constructor for a mod feature.");
     }
 
-    const modFeatureConstructor = constructor as ModFeatureConstructor;
-    checkAddDecoratedCallbacks(mod, modFeatureConstructor, this);
-    checkAddDecoratedCallbacksCustom(mod, modFeatureConstructor, this);
-    checkRegisterSaveDataManager(mod, this);
+    const tstlClassName = getTSTLClassName(constructor);
+    if (tstlClassName === undefined) {
+      error("Failed to get the TSTL class name for a mod feature.");
+    }
+
+    initDecoratedCallbacks(this, constructor, tstlClassName, true, init);
+    initDecoratedCallbacks(this, constructor, tstlClassName, false, init);
+    initSaveDataManager(this, tstlClassName, init);
+  }
+
+  public uninit(): void {
+    this.init(false);
   }
 }
 
-function checkAddDecoratedCallbacks(
-  mod: ModUpgradedBase,
-  modFeatureConstructor: ModFeatureConstructor,
+function initDecoratedCallbacks(
   modFeature: ModFeature,
+  constructor: TSTLClassMetatable["constructor"],
+  tstlClassName: string,
+  vanilla: boolean,
+  init: boolean,
 ) {
-  const addCallbackArgs = modFeatureConstructor[ADD_CALLBACK_ARGS_KEY];
+  const modFeatureConstructor = constructor as ModFeatureConstructor;
+  const argsKey = vanilla
+    ? ADD_CALLBACK_ARGS_KEY
+    : ADD_CALLBACK_CUSTOM_ARGS_KEY;
+  const addCallbackArgs = modFeatureConstructor[argsKey];
   if (addCallbackArgs === undefined) {
     return;
   }
 
-  const tstlClassName = getTSTLClassName(modFeatureConstructor) ?? "Unknown";
+  if (!isArray(addCallbackArgs)) {
+    error(
+      `Failed to initialize/uninitialize the decorated callbacks on a mod feature since the callback arguments on the key of "${argsKey}" was not an array.`,
+    );
+  }
 
   for (const args of addCallbackArgs) {
-    const parameters = args as unknown[];
-    const modCallback = parameters.shift() as ModCallback | undefined;
-    if (modCallback === undefined) {
+    if (!isArray(args)) {
       error(
-        `Failed to get the ModCallback from the parameters for class: ${tstlClassName}`,
+        "Failed to initialize/uninitialize the decorated callbacks on a mod feature since one of the callback arguments was not an array.",
       );
     }
 
-    const callback = parameters.shift() as
-      | ((this: void, ...callbackArgs: unknown[]) => void)
-      | undefined;
-    if (callback === undefined) {
-      error(
-        `Failed to get the callback from the parameters for class: ${tstlClassName}`,
-      );
-    }
-
-    /**
-     * We need to wrap the callback in a new function so that we can explicitly pass the class as
-     * the first argument. (Otherwise, the method will not be able to properly access `this`.
-     */
-    const newCallback = (...callbackArgs: unknown[]) => {
-      callback(modFeature, ...callbackArgs);
-    };
-
-    // @ts-expect-error The compiler does not know that the arguments match the method.
-    mod.AddCallback(modCallback, newCallback, ...parameters);
-  }
-}
-
-function checkAddDecoratedCallbacksCustom(
-  mod: ModUpgradedBase,
-  modFeatureConstructor: ModFeatureConstructor,
-  modFeature: ModFeature,
-) {
-  const addCallbackCustomArgs =
-    modFeatureConstructor[ADD_CALLBACK_CUSTOM_ARGS_KEY];
-  if (addCallbackCustomArgs === undefined) {
-    return;
-  }
+    const parameters = deepCopy(args);
 
-  const tstlClassName = getTSTLClassName(modFeatureConstructor) ?? "Unknown";
-
-  for (const args of addCallbackCustomArgs) {
-    const parameters = args as unknown[];
-    const modCallbackCustom = parameters.shift() as
-      | ModCallbackCustom
-      | undefined;
-    if (modCallbackCustom === undefined) {
+    const modCallback = parameters.shift();
+    if (modCallback === undefined) {
       error(
-        `Failed to get the ModCallbackCustom from the parameters for class: ${tstlClassName}`,
+        `Failed to get the callback number from the parameters for class: ${tstlClassName}`,
       );
     }
 
@@ -130,26 +133,66 @@ function checkAddDecoratedCallbacksCustom(
       | undefined;
     if (callback === undefined) {
       error(
-        `Failed to get the callback from the parameters for class: ${tstlClassName}`,
+        `Failed to get the callback function from the parameters for class: ${tstlClassName}`,
       );
     }
 
-    /**
-     * We need to wrap the callback in a new function so that we can explicitly pass the class as
-     * the first argument. (Otherwise, the method will not be able to properly access `this`.
-     */
-    const newCallback = (...callbackArgs: unknown[]) => {
-      callback(modFeature, ...callbackArgs);
-    };
-
-    // @ts-expect-error The compiler does not know that the arguments match the method.
-    mod.AddCallbackCustom(modCallbackCustom, newCallback, ...parameters);
+    // eslint-disable-next-line prefer-destructuring, @typescript-eslint/dot-notation
+    const mod = modFeature["mod"];
+
+    if (init) {
+      // We need to wrap the callback in a new function so that we can explicitly pass the class as
+      // the first argument. (Otherwise, the method will not be able to properly access `this`.
+      const wrappedCallback = (...callbackArgs: unknown[]) => {
+        callback(modFeature, ...callbackArgs);
+      };
+
+      // We need to save the wrapped function for later (so we can unregister them).
+      if (vanilla) {
+        const modCallbackVanilla = modCallback as ModCallback;
+        const wrappedMethodsMap =
+          modFeatureConstructor[WRAPPED_CALLBACK_METHODS_KEY];
+        wrappedMethodsMap.set(modCallbackVanilla, wrappedCallback);
+      } else {
+        const modCallbackCustom = modCallback as ModCallbackCustom;
+        const wrappedMethodsMap =
+          modFeatureConstructor[WRAPPED_CUSTOM_CALLBACK_METHODS_KEY];
+        wrappedMethodsMap.set(modCallbackCustom, wrappedCallback);
+      }
+
+      if (vanilla) {
+        (mod.AddCallback as AnyFunction)(
+          modCallback,
+          wrappedCallback,
+          ...parameters,
+        );
+      } else {
+        (mod.AddCallbackCustom as AnyFunction)(
+          modCallback,
+          wrappedCallback,
+          ...parameters,
+        );
+      }
+    } else if (vanilla) {
+      const modCallbackVanilla = modCallback as ModCallback;
+      const wrappedMethodsMap =
+        modFeatureConstructor[WRAPPED_CALLBACK_METHODS_KEY];
+      const wrappedCallback = wrappedMethodsMap.get(modCallbackVanilla);
+      (mod.RemoveCallback as AnyFunction)(modCallback, wrappedCallback);
+    } else {
+      const modCallbackCustom = modCallback as ModCallbackCustom;
+      const wrappedMethodsMap =
+        modFeatureConstructor[WRAPPED_CUSTOM_CALLBACK_METHODS_KEY];
+      const wrappedCallback = wrappedMethodsMap.get(modCallbackCustom);
+      (mod.RemoveCallbackCustom as AnyFunction)(modCallback, wrappedCallback);
+    }
   }
 }
 
-function checkRegisterSaveDataManager(
-  mod: ModUpgradedBase,
+function initSaveDataManager(
   modFeature: ModFeature,
+  tstlClassName: string,
+  init: boolean,
 ) {
   // Do nothing if this class does not have any variables.
   const { v } = modFeature as unknown as Record<string, unknown>;
@@ -164,13 +207,27 @@ function checkRegisterSaveDataManager(
   }
 
   // Do nothing if we have not enabled the save data manager.
-  const { saveDataManager } = mod as unknown as Record<string, unknown>;
-  if (saveDataManager === undefined) {
+  // eslint-disable-next-line @typescript-eslint/dot-notation
+  const mod = modFeature["mod"] as unknown as Record<string, unknown>;
+  const saveDataManagerMethodName = init
+    ? "saveDataManager"
+    : "saveDataManagerRemove";
+  const saveDataManagerMethod = mod[saveDataManagerMethodName];
+  if (saveDataManagerMethod === undefined) {
     error(
       'Failed to initialize a mod feature class due to having a "v" object and not having the save data manager initialized. You must pass "ISCFeature.SAVE_DATA_MANAGER" to the "upgradeMod" function.',
     );
   }
 
-  const tstlClassName = getTSTLClassName(modFeature);
-  (saveDataManager as AnyFunction)(tstlClassName, v);
+  if (typeof saveDataManagerMethod !== "function") {
+    error(
+      `The "${saveDataManagerMethodName}" property of the "ModUpgraded" object was not a function.`,
+    );
+  }
+
+  if (init) {
+    saveDataManagerMethod(tstlClassName, v);
+  } else {
+    saveDataManagerMethod(tstlClassName);
+  }
 }

package/src/classes/callbacks/PostNPCInitFilter.ts

@@ -4,12 +4,6 @@ import { shouldFireNPC } from "../../shouldFire";
 import { CustomCallback } from "../private/CustomCallback";
 
 export class PostNPCInitFilter extends CustomCallback<ModCallbackCustom.POST_NPC_INIT_FILTER> {
-  public override v = {
-    room: {
-      firedSet: new Set<PtrHash>(),
-    },
-  };
-
   constructor() {
     super();
 

package/src/classes/callbacks/PostNPCUpdateFilter.ts

@@ -4,12 +4,6 @@ import { shouldFireNPC } from "../../shouldFire";
 import { CustomCallback } from "../private/CustomCallback";
 
 export class PostNPCUpdateFilter extends CustomCallback<ModCallbackCustom.POST_NPC_UPDATE_FILTER> {
-  public override v = {
-    room: {
-      firedSet: new Set<PtrHash>(),
-    },
-  };
-
   constructor() {
     super();
 

package/src/classes/features/callbackLogic/GameReorderedCallbacks.ts

@@ -19,7 +19,13 @@ import { Feature } from "../../private/Feature";
  * 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.
+ * `isaacscript-common` provides three new callbacks that change the order to this:
+ * - `POST_GAME_STARTED_REORDERED`
+ * - `POST_NEW_LEVEL_REORDERED`
+ * - `POST_NEW_ROOM_REORDERED`
+ *
+ * Additionally, there are some helper functions listed below that can deal with some edge cases
+ * that you may run into with these callbacks.
  */
 export class GameReorderedCallbacks extends Feature {
   private currentStage: int | null = null;
@@ -140,12 +146,13 @@ export class GameReorderedCallbacks extends Feature {
    * the next `POST_NEW_LEVEL`.
    *
    * 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 `POST_NEW_LEVEL` 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.
+   * frame. (For example, if you had a mod that made the player start the run in Caves instead of
+   * Basement.) However, due to how the callback reordering works, the `POST_NEW_LEVEL_REORDERED`
+   * 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.
    *
    * In order to use this function, you must upgrade your mod with
-   * `ISCFeature.CUSTOM_GRID_ENTITIES`.
+   * `ISCFeature.GAME_REORDERED_CALLBACKS`.
    */
   @Exported
   public forceNewLevelCallback(): void {
@@ -157,12 +164,13 @@ export class GameReorderedCallbacks extends Feature {
    * the next `POST_NEW_ROOM`.
    *
    * 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 `POST_NEW_ROOM` 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.
+   * frame. (For example, if you had a mod that made the player start the Treasure Room of Basement
+   * 1 instead of the normal starting room.) However, due to how the callback reordering works, the
+   * `POST_NEW_ROOM_REORDERED` 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.
    *
    * In order to use this function, you must upgrade your mod with
-   * `ISCFeature.CUSTOM_GRID_ENTITIES`.
+   * `ISCFeature.GAME_REORDERED_CALLBACKS`.
    */
   @Exported
   public forceNewRoomCallback(): void {
@@ -170,14 +178,14 @@ export class GameReorderedCallbacks extends Feature {
   }
 
   /**
-   * Helper function to manually set the variable that the reordered callback logic uses to track
+   * Helper function to manually set the variables that the reordered callback logic uses to track
    * the current stage and stage type.
    *
-   * This is useful because if the stage is changed with the `Game.SetStage` method, the reordered
-   * callbacks will stop working.
+   * This is useful because if the stage is changed with the `Game.SetStage` method (or the
+   * `setStage` helper function), the reordered callbacks will stop working.
    *
    * In order to use this function, you must upgrade your mod with
-   * `ISCFeature.CUSTOM_GRID_ENTITIES`.
+   * `ISCFeature.GAME_REORDERED_CALLBACKS`.
    */
   @Exported
   public reorderedCallbacksSetStage(

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

@@ -1,7 +1,3 @@
-// One of the functions below causes a false positive for ESLint:
-// https://github.com/gajus/eslint-plugin-jsdoc/issues/915
-/* eslint-disable jsdoc/check-param-names */
-
 import {
   EffectVariant,
   EntityType,

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

@@ -296,7 +296,7 @@ export class DebugDisplay extends Feature {
       this.mod.initFeature(feature);
     }
 
-    printEnabled(this.player.initialized, `${featureName} display`);
+    printEnabled(feature.initialized, `${featureName} display`);
   }
 
   /**

package/src/enums/ModCallbackCustom.ts

@@ -552,8 +552,8 @@ export enum ModCallbackCustom {
   /**
    * Fires when a new grid entity is initialized. Specifically, this is either:
    *
-   * - in the `POST_NEW_ROOM` callback (firing every time a room is entered, even if the entity was
-   *   previously there on a previous room entry)
+   * - in the `POST_NEW_ROOM_REORDERED` callback (firing every time a room is entered, even if the
+   *   entity was previously there on a previous room entry)
    * - in the `POST_UPDATE` callback (if the entity appeared mid-way through the room, like when the
    *   trapdoor appears after defeating It Lives!)
    *
@@ -658,8 +658,8 @@ export enum ModCallbackCustom {
   POST_GRID_ENTITY_UPDATE,
 
   /**
-   * Fires from the `POST_PEFFECT_UPDATE` callback when the player loses a Holy Mantle temporary
-   * collectible effect.
+   * Fires from the `POST_PEFFECT_UPDATE_REORDERED` callback when the player loses a Holy Mantle
+   * temporary collectible effect.
    *
    * This callback is useful because you might want to have code that happens when the player is hit
    * from an enemy. Normally, you would accomplish this via the `ENTITY_TAKE_DMG` callback, but that
@@ -682,8 +682,8 @@ export enum ModCallbackCustom {
   POST_HOLY_MANTLE_REMOVED,
 
   /**
-   * Fires from `POST_PEFFECT_UPDATE` callback when the player loses charge on their active
-   * collectible item, implying that the item was just used.
+   * Fires from `POST_PEFFECT_UPDATE_REORDERED` callback when the player loses charge on their
+   * active collectible item, implying that the item was just used.
    *
    * This callback is useful because the `USE_ITEM` callback does not fire when The Candle, Red
    * Candle, and Bob's Rotten Brain are discharged.
@@ -706,9 +706,9 @@ export enum ModCallbackCustom {
   POST_ITEM_DISCHARGE,
 
   /**
-   * Fires from the `POST_PEFFECT_UPDATE` callback when an item is no longer queued (i.e. when the
-   * animation of the player holding the item above their head is finished and the item is actually
-   * added to the player's inventory).
+   * Fires from the `POST_PEFFECT_UPDATE_REORDERED` callback when an item is no longer queued (i.e.
+   * when the animation of the player holding the item above their head is finished and the item is
+   * actually added to the player's inventory).
    *
    * Note that this callback will only fire once per Forgotten/Soul pair.
    *
@@ -1008,8 +1008,9 @@ export enum ModCallbackCustom {
   POST_PIT_UPDATE,
 
   /**
-   * Fires from the `POST_PEFFECT_UPDATE` callback when a player's health (i.e. hearts) is different
-   * than what it was on the previous frame. For more information, see the `PlayerHealth` enum.
+   * Fires from the `POST_PEFFECT_UPDATE_REORDERED` callback when a player's health (i.e. hearts) is
+   * different than what it was on the previous frame. For more information, see the `PlayerHealth`
+   * enum.
    *
    * When registering the callback with the `ModUpgraded.AddCallbackCustom` method:
    * - You can provide an optional third argument that will make the callback only fire if it
@@ -1030,8 +1031,8 @@ export enum ModCallbackCustom {
   POST_PLAYER_CHANGE_HEALTH,
 
   /**
-   * Fires from the `POST_PEFFECT_UPDATE` callback when one of the player's stats change from what
-   * they were on the previous frame.
+   * Fires from the `POST_PEFFECT_UPDATE_REORDERED` callback when one of the player's stats change
+   * from what they were on the previous frame.
    *
    * The type of `oldValue` and `newValue` will depend on what kind of stat it is. For example,
    * `StatType.FLYING` will be a boolean. (You can use the "Types" helper functions to narrow the
@@ -1061,7 +1062,8 @@ export enum ModCallbackCustom {
   POST_PLAYER_CHANGE_STAT,
 
   /**
-   * Fires from the `POST_PEFFECT_UPDATE` callback when a player entity changes its player type
+   * Fires from the `POST_PEFFECT_UPDATE_REORDERED` callback when a player entity changes its player
+   * type
    * (i.e. character) from what it was on the previous frame. For example, it will fire after using
    * Clicker, after dying with the Judas' Shadow collectible, etc.
    *
@@ -1084,9 +1086,9 @@ export enum ModCallbackCustom {
   POST_PLAYER_CHANGE_TYPE,
 
   /**
-   * Fires from the `POST_PEFFECT_UPDATE` callback when a player's collectible count is higher than
-   * what it was on the previous frame, or when the active items change, or when the build is
-   * rerolled.
+   * Fires from the `POST_PEFFECT_UPDATE_REORDERED` callback when a player's collectible count is
+   * higher than what it was on the previous frame, or when the active items change, or when the
+   * build is rerolled.
    *
    * When registering the callback with the `ModUpgraded.AddCallbackCustom` method:
    * - You can provide an optional third argument that will make the callback only fire if the
@@ -1102,9 +1104,9 @@ export enum ModCallbackCustom {
   POST_PLAYER_COLLECTIBLE_ADDED,
 
   /**
-   * Fires from the `POST_PEFFECT_UPDATE` callback when a player's collectible count is lower than
-   * what it was on the previous frame, or when the active items change, or when the build is
-   * rerolled.
+   * Fires from the `POST_PEFFECT_UPDATE_REORDERED` callback when a player's collectible count is
+   * lower than what it was on the previous frame, or when the active items change, or when the
+   * build is rerolled.
    *
    * When registering the callback with the `ModUpgraded.AddCallbackCustom` method:
    * - You can provide an optional third argument that will make the callback only fire if the
@@ -1304,8 +1306,9 @@ export enum ModCallbackCustom {
   POST_PROJECTILE_INIT_LATE,
 
   /**
-   * Fires from the `POST_PEFFECT_UPDATE` callback when a player first picks up a new item. The
-   * pickup returned in the callback is assumed to be the first pickup that no longer exists.
+   * Fires from the `POST_PEFFECT_UPDATE_REORDERED` callback when a player first picks up a new
+   * item. The pickup returned in the callback is assumed to be the first pickup that no longer
+   * exists.
    *
    * When registering the callback with the `ModUpgraded.AddCallbackCustom` method:
    * - You can provide an optional third argument that will make the callback only fire if it
@@ -1442,8 +1445,8 @@ export enum ModCallbackCustom {
   /**
    * Fires when a new slot entity is initialized. Specifically, this is either:
    *
-   * - in the `POST_NEW_ROOM` callback (firing every time a room is entered, even if the entity was
-   *   previously there on a previous room entry)
+   * - in the `POST_NEW_ROOM_REORDERED` callback (firing every time a room is entered, even if the
+   *   entity was previously there on a previous room entry)
    * - in the `POST_UPDATE` callback (if the entity appeared mid-way through the room, like when a
    *   Wheel of Fortune card is used)
    *
@@ -1579,7 +1582,7 @@ export enum ModCallbackCustom {
   POST_TNT_UPDATE,
 
   /**
-   * Fires from the `POST_PEFFECT_UPDATE` callback when a player gains or loses a new
+   * Fires from the `POST_PEFFECT_UPDATE_REORDERED` callback when a player gains or loses a new
    * transformation.
    *
    * Note that this callback will only fire once per Forgotten/Soul pair.
@@ -1615,9 +1618,9 @@ export enum ModCallbackCustom {
   POST_TRINKET_BREAK,
 
   /**
-   * Fires from the `POST_PEFFECT_UPDATE` callback on the frame before a Berserk effect ends when
-   * the player is predicted to die (e.g. they currently have no health left or they took damage in
-   * a "Lost" form).
+   * Fires from the `POST_PEFFECT_UPDATE_REORDERED` callback on the frame before a Berserk effect
+   * ends when the player is predicted to die (e.g. they currently have no health left or they took
+   * damage in a "Lost" form).
    *
    * When registering the callback with the `ModUpgraded.AddCallbackCustom` method:
    * - You can provide an optional third argument that will make the callback only fire if it
@@ -1673,8 +1676,8 @@ export enum ModCallbackCustom {
   PRE_GET_PEDESTAL,
 
   /**
-   * Fires from the `POST_PEFFECT_UPDATE` callback when an item becomes queued (i.e. when the player
-   * begins to hold the item above their head).
+   * Fires from the `POST_PEFFECT_UPDATE_REORDERED` callback when an item becomes queued (i.e. when
+   * the player begins to hold the item above their head).
    *
    * Note that this callback will only fire once per Forgotten/Soul pair.
    *