isaacscript-common 14.0.0 → 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

@@ -1,11 +1,7 @@
 import { ModCallbackCustom2 } from "../../enums/ModCallbackCustom2";
 import { AddCallbackParametersCustom2 } from "../../interfaces/private/AddCallbackParametersCustom2";
-import { SaveData } from "../../interfaces/SaveData";
 import { AllButFirst } from "../../types/private/AllButFirst";
-import {
-  CallbackTuple,
-  CustomCallbackTuple,
-} from "../../types/private/CallbackTuple";
+import { Feature } from "./Feature";
 
 export type FireArgs<T extends ModCallbackCustom2> = Parameters<
   AddCallbackParametersCustom2[T][0]
@@ -18,21 +14,16 @@ export type OptionalArgs<T extends ModCallbackCustom2> = AllButFirst<
  * 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> {
-  /** This is manually managed by the `ModUpgraded` class. */
-  initialized = false;
+export abstract class CustomCallback<
+  T extends ModCallbackCustom2,
+> extends Feature {
+  private subscriptions: Array<AddCallbackParametersCustom2[T]> = [];
 
-  subscriptions: Array<AddCallbackParametersCustom2[T]> = [];
-
-  otherCallbacksUsed?: CallbackTuple[];
-  otherCustomCallbacksUsed?: CustomCallbackTuple[];
-  v?: SaveData;
-
-  hasSubscriptions(): boolean {
+  public hasSubscriptions(): boolean {
     return this.subscriptions.length > 0;
   }
 
-  add(...args: AddCallbackParametersCustom2[T]): void {
+  public add(...args: AddCallbackParametersCustom2[T]): void {
     this.subscriptions.push(args);
   }
 
@@ -40,7 +31,7 @@ export abstract class CustomCallback<T extends ModCallbackCustom2> {
    * If the submitted function does not match any of the existing subscriptions, this method will do
    * nothing.
    */
-  remove(callback: AddCallbackParametersCustom2[T][0]): void {
+  public remove(callback: AddCallbackParametersCustom2[T][0]): void {
     const subscriptionIndexMatchingCallback = this.subscriptions.findIndex(
       (subscription) => {
         const subscriptionCallback = subscription[0];
@@ -52,23 +43,35 @@ export abstract class CustomCallback<T extends ModCallbackCustom2> {
     }
   }
 
-  fire(...fireArgs: FireArgs<T>): void {
-    for (const [callback, ...optionalArgs] of this.subscriptions) {
-      // @ts-expect-error The compiler is not smart enough to know that the arguments should match
-      // the method.
+  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)) {
-        // @ts-expect-error The compiler is not smart enough to know that the arguments should match
-        // the callback.
-        callback(...fireArgs);
+        // 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
-  shouldFire(
+  protected shouldFire(
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     fireArgs: FireArgs<T>,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars

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,5 +1,8 @@
 import { postNewRoomEarlyCallbackInit } from "../callbacks/postNewRoomEarly";
 import { ModUpgraded } from "../classes/ModUpgraded";
+import { Feature } from "../classes/private/Feature";
+import { ISCFeature } from "../enums/ISCFeature";
+import { ISCFeatureToClass } from "../features";
 import {
   saveDataManagerInit,
   SAVE_DATA_MANAGER_CALLBACKS,
@@ -13,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
@@ -32,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
@@ -39,42 +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. 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);
+  for (const feature of features) {
+    const tstlClassMethods = mod.initOptionalFeature(feature);
+
+    // 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>;
+}
 
-    // We initialize custom callbacks next since some features use custom callbacks.
-    initCustomCallbacks(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);
 
-    initFeatures(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/ModCallbackCustom2.ts

@@ -8,10 +8,50 @@ export enum ModCallbackCustom2 {
   POST_COLLECTIBLE_EMPTY,
   POST_COLLECTIBLE_INIT_FIRST,
   POST_CURSED_TELEPORT,
+  POST_CUSTOM_REVIVE,
+  POST_DICE_ROOM_ACTIVATED,
+  POST_DOOR_RENDER,
+  POST_DOOR_UPDATE,
+  POST_EFFECT_INIT_LATE,
+  POST_EFFECT_STATE_CHANGED,
+  POST_ESAU_JR,
+  POST_FAMILIAR_INIT_LATE,
+  POST_FAMILIAR_STATE_CHANGED,
+  POST_FIRST_ESAU_JR,
+  POST_FIRST_FLIP,
+  POST_FLIP,
+  POST_GAME_STARTED_REORDERED,
+  POST_GAME_STARTED_REORDERED_LAST,
+  POST_GREED_MODE_WAVE,
+  POST_GRID_ENTITY_BROKEN,
+  POST_GRID_ENTITY_COLLISION,
+  POST_GRID_ENTITY_CUSTOM_BROKEN,
+  POST_GRID_ENTITY_CUSTOM_COLLISION,
+  POST_GRID_ENTITY_CUSTOM_INIT,
+  POST_GRID_ENTITY_CUSTOM_REMOVE,
+  // POST_GRID_ENTITY_CUSTOM_RENDER,
+  POST_GRID_ENTITY_CUSTOM_STATE_CHANGED,
+  POST_GRID_ENTITY_CUSTOM_UPDATE,
+  POST_GRID_ENTITY_INIT,
+  POST_GRID_ENTITY_REMOVE,
+  // POST_GRID_ENTITY_RENDER,
+  POST_GRID_ENTITY_STATE_CHANGED,
+  POST_GRID_ENTITY_UPDATE,
+  POST_HOLY_MANTLE_REMOVED,
+
+  // ---------------------
 
   POST_KNIFE_INIT_LATE,
+  POST_NEW_LEVEL_REORDERED,
   POST_NEW_ROOM_EARLY,
+  POST_NEW_ROOM_REORDERED,
+  POST_PEFFECT_UPDATE_REORDERED,
   POST_PIT_RENDER,
+  POST_PLAYER_FATAL_DAMAGE,
+  POST_PLAYER_RENDER_REORDERED,
+  POST_PLAYER_UPDATE_REORDERED,
   POST_ROOM_CLEAR_CHANGED,
   POST_SPIKES_RENDER,
+  PRE_BERSERK_DEATH,
+  PRE_CUSTOM_REVIVE,
 }

package/src/features/customGridEntity.ts

@@ -18,6 +18,7 @@ import {
   removeGridEntity,
   spawnGridEntityWithVariant,
 } from "../functions/gridEntities";
+import { getPlayerFromPtr } from "../functions/players";
 import { getRoomListIndex } from "../functions/roomData";
 import { isNumber } from "../functions/types";
 import { isVector } from "../functions/vector";
@@ -91,14 +92,9 @@ function preUseItemWeNeedToGoDeeper(
 
   removeGridEntity(customGridEntity.gridIndex, false);
 
-  const playerPtr = EntityPtr(player);
+  const entityPtr = EntityPtr(player);
   runNextGameFrame(() => {
-    const futureEntity = playerPtr.Ref;
-    if (futureEntity === undefined) {
-      return;
-    }
-
-    const futurePlayer = futureEntity.ToPlayer();
+    const futurePlayer = getPlayerFromPtr(entityPtr);
     if (futurePlayer === undefined) {
       return;
     }

package/src/features/customTrapdoor/touched.ts

@@ -123,7 +123,7 @@ function setPlayerAttributes(trapdoorPlayer: EntityPlayer, position: Vector) {
 }
 
 function dropTaintedForgotten(player: EntityPlayer) {
-  if (isCharacter(player, PlayerType.THE_FORGOTTEN_B)) {
+  if (isCharacter(player, PlayerType.FORGOTTEN_B)) {
     const taintedSoul = player.GetOtherTwin();
     if (taintedSoul !== undefined) {
       taintedSoul.ThrowHeldEntity(VectorZero);

package/src/features/deployJSONRoom.ts

@@ -41,6 +41,7 @@ import {
 } from "../functions/gridEntities";
 import { getRandomJSONEntity, getRandomJSONRoom } from "../functions/jsonRoom";
 import { log } from "../functions/log";
+import { getPlayerFromPtr } from "../functions/players";
 import { getRandomSeed, isRNG, newRNG } from "../functions/rng";
 import { getRoomListIndex } from "../functions/roomData";
 import { gridCoordinatesToWorldPosition } from "../functions/roomGrid";
@@ -134,14 +135,9 @@ function preUseItemWeNeedToGoDeeper(
     removeGridEntity(decoration, false);
   }
 
-  const playerPtr = EntityPtr(player);
+  const entityPtr = EntityPtr(player);
   runNextGameFrame(() => {
-    const futureEntity = playerPtr.Ref;
-    if (futureEntity === undefined) {
-      return;
-    }
-
-    const futurePlayer = futureEntity.ToPlayer();
+    const futurePlayer = getPlayerFromPtr(entityPtr);
     if (futurePlayer === undefined) {
       return;
     }