isaacscript-common 15.1.0 → 15.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "15.1.0",
+  "version": "15.1.1",
   "description": "Helper functions and features for IsaacScript mods.",
   "keywords": [
     "isaac",

package/src/classes/ModFeature.ts

@@ -1,3 +1,5 @@
+import { ModCallback } from "isaac-typescript-definitions";
+import { ModCallbackCustom } from "../enums/ModCallbackCustom";
 import {
   getTSTLClassConstructor,
   getTSTLClassName,
@@ -20,10 +22,20 @@ type ModFeatureConstructor = TSTLClassMetatable["constructor"] & {
  * mod features from this class in order to enable the `@Callback` and `@CustomCallback` decorators
  * that automatically subscribe to callbacks.
  *
+ * If your feature has variables that are managed by the save data manager, put them as a `v` class
+ * member and they will automatically be registered with the save data manager when the class is
+ * instantiated.
+ *
  * For example:
  *
  * ```ts
  * export class MyFeature extends ModFeature {
+ *   v = {
+ *     run: {
+ *       foo: 123,
+ *     }
+ *   }
+ *
  *   @Callback(ModCallback.POST_GAME_STARTED)
  *   postGameStarted(isContinued: boolean): void {
  *     Isaac.DebugString(`Callback fired: POST_GAME_STARTED`);
@@ -40,8 +52,8 @@ export class ModFeature {
     }
 
     const modFeatureConstructor = constructor as ModFeatureConstructor;
-    checkAddDecoratedCallbacks(mod, modFeatureConstructor);
-    checkAddDecoratedCallbacksCustom(mod, modFeatureConstructor);
+    checkAddDecoratedCallbacks(mod, modFeatureConstructor, this);
+    checkAddDecoratedCallbacksCustom(mod, modFeatureConstructor, this);
     checkRegisterSaveDataManager(mod, this);
   }
 }
@@ -49,22 +61,50 @@ export class ModFeature {
 function checkAddDecoratedCallbacks(
   mod: ModUpgradedBase,
   modFeatureConstructor: ModFeatureConstructor,
+  modFeature: ModFeature,
 ) {
   const addCallbackArgs = modFeatureConstructor[ADD_CALLBACK_ARGS_KEY];
   if (addCallbackArgs === undefined) {
     return;
   }
 
+  const tstlClassName = getTSTLClassName(modFeatureConstructor) ?? "Unknown";
+
   for (const args of addCallbackArgs) {
+    const parameters = args as unknown[];
+    const modCallback = parameters.shift() as ModCallback | undefined;
+    if (modCallback === undefined) {
+      error(
+        `Failed to get the ModCallback from the parameters for class: ${tstlClassName}`,
+      );
+    }
+
+    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.
-    // eslint-disable-next-line isaacscript/strict-enums
-    mod.AddCallback(...args);
+    mod.AddCallback(modCallback, newCallback, ...parameters);
   }
 }
 
 function checkAddDecoratedCallbacksCustom(
   mod: ModUpgradedBase,
   modFeatureConstructor: ModFeatureConstructor,
+  modFeature: ModFeature,
 ) {
   const addCallbackCustomArgs =
     modFeatureConstructor[ADD_CALLBACK_CUSTOM_ARGS_KEY];
@@ -72,10 +112,38 @@ function checkAddDecoratedCallbacksCustom(
     return;
   }
 
+  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) {
+      error(
+        `Failed to get the ModCallbackCustom from the parameters for class: ${tstlClassName}`,
+      );
+    }
+
+    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.
-    // eslint-disable-next-line isaacscript/strict-enums
-    mod.AddCallbackCustom(...args);
+    mod.AddCallbackCustom(modCallbackCustom, newCallback, ...parameters);
   }
 }
 

package/src/functions/arrayLua.ts

@@ -61,7 +61,7 @@ export function forEach<T>(
 /**
  * Helper function for non-TypeScript users to check if an element is in an array.
  *
- * Since this takes O(N) time, using this function is usually a mistake, since you can use a `Map`
+ * Since this takes O(N) time, using this function is usually a mistake, since you can use a `Set`
  * data structure to get O(1) lookups.
  *
  * Internally, this just calls `array.includes`.

package/src/functions/decorators.ts

@@ -29,6 +29,7 @@ import {
 import { ModCallbackCustom } from "../enums/ModCallbackCustom";
 import { AddCallbackParametersCustom } from "../interfaces/private/AddCallbackParametersCustom";
 import { AllButFirst } from "../types/AllButFirst";
+import { getTSTLClassName } from "./tstlClass";
 
 /**
  * A decorator function that signifies that the decorated class method should be automatically
@@ -57,10 +58,17 @@ export function Callback<T extends ModCallback>(
     // 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
     // arguments for later.
-    const constructor = target.constructor as unknown as LuaTable<
-      AnyNotNil,
-      unknown
-    >;
+    const constructor = target.constructor as unknown as
+      | LuaTable<AnyNotNil, unknown>
+      | undefined;
+
+    if (constructor === undefined) {
+      const tstlClassName = getTSTLClassName(target) ?? "Unknown";
+      error(
+        `Failed to get the constructor for class "${tstlClassName}". Did you decorate a static method? You can only decorate non-static class methods, because the "Mod" object is not present before the class is instantiated.`,
+      );
+    }
+
     if (!constructor.has(ADD_CALLBACK_ARGS_KEY)) {
       constructor.set(ADD_CALLBACK_ARGS_KEY, []);
     }
@@ -100,10 +108,17 @@ export function CallbackCustom<T extends ModCallbackCustom>(
     // 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
     // arguments for later.
-    const constructor = target.constructor as unknown as LuaTable<
-      AnyNotNil,
-      unknown
-    >;
+    const constructor = target.constructor as unknown as
+      | LuaTable<AnyNotNil, unknown>
+      | undefined;
+
+    if (constructor === undefined) {
+      const tstlClassName = getTSTLClassName(target) ?? "Unknown";
+      error(
+        `Failed to get the constructor for class "${tstlClassName}". Did you decorate a static method? You can only decorate non-static class methods, because the "Mod" object is not present before the class is instantiated.`,
+      );
+    }
+
     if (!constructor.has(ADD_CALLBACK_CUSTOM_ARGS_KEY)) {
       constructor.set(ADD_CALLBACK_CUSTOM_ARGS_KEY, []);
     }

package/src/functions/tears.ts

@@ -3,6 +3,16 @@
  *   adds it to the player.
  * - This function should only be used inside the `EVALUATE_CACHE` callback.
  * - In this context, the "tears stat" represents what is shown on the in-game stat UI.
+ *
+ * For example:
+ *
+ * ```ts
+ * function evaluateCacheTears(player: EntityPlayer) {
+ *   const numFoo = player.GetNumCollectible(CollectibleTypeCustom.FOO);
+ *   const tearsStat = numFoo * FOO_TEARS_STAT;
+ *   addTearsStat(player, tearsStat);
+ * }
+ * ```
  */
 export function addTearsStat(player: EntityPlayer, tearsStat: float): void {
   const existingTearsStat = getTearsStat(player.MaxFireDelay);