isaacscript-common 3.17.0 → 4.0.2

package/callbacks/subscriptions/postTransformation.ts

@@ -0,0 +1,40 @@
+import { PlayerForm } from "isaac-typescript-definitions";
+
+export type PostTransformationRegisterParameters = [
+  callback: (
+    player: EntityPlayer,
+    playerForm: PlayerForm,
+    hasForm: boolean,
+  ) => void,
+  playerForm?: PlayerForm,
+];
+
+const subscriptions: PostTransformationRegisterParameters[] = [];
+
+/** @internal */
+export function postTransformationHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+/** @internal */
+export function postTransformationRegister(
+  ...args: PostTransformationRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+/** @internal */
+export function postTransformationFire(
+  player: EntityPlayer,
+  playerForm: PlayerForm,
+  hasForm: boolean,
+): void {
+  for (const [callback, callbackPlayerForm] of subscriptions) {
+    // Handle the optional 2nd callback argument.
+    if (callbackPlayerForm !== undefined && callbackPlayerForm !== playerForm) {
+      continue;
+    }
+
+    callback(player, playerForm, hasForm);
+  }
+}

package/callbacks/subscriptions/postTrinketBreak.ts

@@ -0,0 +1,38 @@
+import { TrinketType } from "isaac-typescript-definitions";
+
+export type PostTrinketBreakRegisterParameters = [
+  callback: (player: EntityPlayer, trinketType: TrinketType) => void,
+  trinketType?: TrinketType,
+];
+
+const subscriptions: PostTrinketBreakRegisterParameters[] = [];
+
+/** @internal */
+export function postTrinketBreakHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+/** @internal */
+export function postTrinketBreakRegister(
+  ...args: PostTrinketBreakRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+/** @internal */
+export function postTrinketBreakFire(
+  player: EntityPlayer,
+  trinketType: TrinketType,
+): void {
+  for (const [callback, callbackTrinketType] of subscriptions) {
+    // Handle the optional 2nd callback argument.
+    if (
+      callbackTrinketType !== undefined &&
+      callbackTrinketType !== trinketType
+    ) {
+      continue;
+    }
+
+    callback(player, trinketType);
+  }
+}

package/callbacks/subscriptions/preBerserkDeath.d.ts

@@ -1,6 +1,6 @@
 import { PlayerType, PlayerVariant } from "isaac-typescript-definitions";
 export declare type PreBerserkDeathRegisterParameters = [
-    callback: (player: EntityPlayer) => boolean | void,
+    callback: (player: EntityPlayer) => void,
     playerVariant?: PlayerVariant,
     character?: PlayerType
 ];

package/callbacks/subscriptions/preBerserkDeath.ts

@@ -0,0 +1,42 @@
+import { PlayerType, PlayerVariant } from "isaac-typescript-definitions";
+
+export type PreBerserkDeathRegisterParameters = [
+  callback: (player: EntityPlayer) => void,
+  playerVariant?: PlayerVariant,
+  character?: PlayerType,
+];
+
+const subscriptions: PreBerserkDeathRegisterParameters[] = [];
+
+/** @internal */
+export function preBerserkDeathHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+/** @internal */
+export function preBerserkDeathRegister(
+  ...args: PreBerserkDeathRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+/** @internal */
+export function preBerserkDeathFire(player: EntityPlayer): void {
+  const character = player.GetPlayerType();
+
+  for (const [callback, playerVariant, callbackCharacter] of subscriptions) {
+    // Handle the optional 2nd callback argument.
+    if (playerVariant !== undefined && playerVariant !== player.Variant) {
+      continue;
+    }
+
+    // Handle the optional 3rd callback argument.
+    if (callbackCharacter !== undefined && callbackCharacter !== character) {
+      continue;
+    }
+
+    callback(player);
+  }
+
+  return undefined;
+}

package/callbacks/subscriptions/preCustomRevive.d.ts

@@ -1,6 +1,6 @@
 import { PlayerType, PlayerVariant } from "isaac-typescript-definitions";
 export declare type PreCustomReviveRegisterParameters = [
-    callback: (player: EntityPlayer) => int | void,
+    callback: (player: EntityPlayer) => int | undefined,
     playerVariant?: PlayerVariant,
     character?: PlayerType
 ];

package/callbacks/subscriptions/preCustomRevive.ts

@@ -0,0 +1,46 @@
+import { PlayerType, PlayerVariant } from "isaac-typescript-definitions";
+
+export type PreCustomReviveRegisterParameters = [
+  callback: (player: EntityPlayer) => int | undefined,
+  playerVariant?: PlayerVariant,
+  character?: PlayerType,
+];
+
+const subscriptions: PreCustomReviveRegisterParameters[] = [];
+
+/** @internal */
+export function preCustomReviveHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+/** @internal */
+export function preCustomReviveRegister(
+  ...args: PreCustomReviveRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+/** @internal */
+export function preCustomReviveFire(player: EntityPlayer): int | undefined {
+  const character = player.GetPlayerType();
+
+  for (const [callback, playerVariant, callbackCharacter] of subscriptions) {
+    // Handle the optional 2nd callback argument.
+    if (playerVariant !== undefined && playerVariant !== player.Variant) {
+      continue;
+    }
+
+    // Handle the optional 3rd callback argument.
+    if (callbackCharacter !== undefined && callbackCharacter !== character) {
+      continue;
+    }
+
+    const revivalType = callback(player);
+
+    if (revivalType !== undefined) {
+      return revivalType;
+    }
+  }
+
+  return undefined;
+}

package/callbacks/subscriptions/preItemPickup.ts

@@ -0,0 +1,64 @@
+import {
+  CollectibleType,
+  ItemType,
+  TrinketType,
+} from "isaac-typescript-definitions";
+import {
+  PickingUpItem,
+  PickingUpItemCollectible,
+  PickingUpItemTrinket,
+} from "../../types/PickingUpItem";
+
+export type PreItemPickupRegisterParameters =
+  | [callback: (player: EntityPlayer, pickingUpItem: PickingUpItem) => void]
+  | [
+      callback: (
+        player: EntityPlayer,
+        pickingUpItem: PickingUpItemCollectible,
+      ) => void,
+      itemType: ItemType.PASSIVE | ItemType.ACTIVE | ItemType.FAMILIAR,
+      collectibleType?: CollectibleType,
+    ]
+  | [
+      callback: (
+        player: EntityPlayer,
+        pickingUpItem: PickingUpItemTrinket,
+      ) => void,
+      itemType: ItemType.TRINKET,
+      trinketType?: TrinketType,
+    ];
+
+const subscriptions: PreItemPickupRegisterParameters[] = [];
+
+/** @internal */
+export function preItemPickupHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+/** @internal */
+export function preItemPickupRegister(
+  ...args: PreItemPickupRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+/** @internal */
+export function preItemPickupFire(
+  player: EntityPlayer,
+  pickingUpItem: PickingUpItem,
+): void {
+  for (const [callback, itemType, subType] of subscriptions) {
+    // Handle the optional 2nd callback argument.
+    if (itemType !== undefined && itemType !== pickingUpItem.itemType) {
+      continue;
+    }
+
+    // Handle the optional 3rd callback argument.
+    if (subType !== undefined && subType !== pickingUpItem.subType) {
+      continue;
+    }
+
+    // @ts-expect-error TypeScript isn't smart enough to treat the above checks as type narrowing.
+    callback(player, pickingUpItem);
+  }
+}

package/callbacks/subscriptions/preNewLevel.ts

@@ -0,0 +1,24 @@
+export type PreNewLevelRegisterParameters = [
+  callback: (player: EntityPlayer) => void,
+];
+
+const subscriptions: PreNewLevelRegisterParameters[] = [];
+
+/** @internal */
+export function preNewLevelHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+/** @internal */
+export function preNewLevelRegister(
+  ...args: PreNewLevelRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+/** @internal */
+export function preNewLevelFire(player: EntityPlayer): void {
+  for (const [callback] of subscriptions) {
+    callback(player);
+  }
+}

package/classes/DefaultMap.ts

@@ -0,0 +1,174 @@
+/* eslint-disable sort-exports/sort-exports */
+
+import { isFunction, isPrimitive } from "../functions/types";
+
+// eslint-disable-next-line isaacscript/complete-sentences-jsdoc
+/**
+ * A function that creates the default value for your `DefaultMap`. For example, if it was a
+ * `DefaultMap` containing maps, the factory function would be: `() => new Map()`
+ */
+export type FactoryFunction<V, Args extends unknown[]> = (
+  ...extraArgs: Args
+) => V;
+
+/**
+ * `DefaultMap` is a data structure that makes working with default values easier.
+ *
+ * It is a common pattern to look up a value in a `Map`, and then, if the value does not exist, set
+ * a default value for the key, and then return the default value. `DefaultMap` abstracts this
+ * operation away by providing the `getAndSetDefault` method.
+ *
+ * Using a `DefaultMap` is nice because it makes code more declarative, since you specify what the
+ * default value is alongside the types of the keys/values.
+ *
+ * When instantiating a new `DefaultMap`, you must specify default value as the first argument. (The
+ * default value is the initial value that will be assigned to every new entry in the
+ * `getAndSetDefault` method.) For example:
+ *
+ * ```ts
+ * // Initializes a new empty DefaultMap with a default value of "foo".
+ * const defaultMapWithString = new DefaultMap<string, string>("foo");
+ *
+ * const value = defaultMapWithString.getAndSetDefault("bar");
+ * // value is now "foo" and an entry for "bar" is now set.
+ * ```
+ *
+ * Sometimes, instead of having a static initial value for every entry in the map, you will want a
+ * dynamic initial value that is contingent upon the key or some other variable. In these cases, you
+ * can instead specify that the `DefaultMap` should run a function that will return the initial
+ * value. (This is referred to as a "factory function".) For example:
+ *
+ * ```ts
+ * // Initializes a new empty DefaultMap with a default value based on "someGlobalVariable".
+ * const factoryFunction = () => someGlobalVariable ? 0 : 1;
+ * const defaultMapWithFactoryFunction = new DefaultMap<string, string>(factoryFunction);
+ * ```
+ *
+ * Note that in TypeScript and Lua, booleans, numbers, and strings are "passed by value". This means
+ * that when the `DefaultMap` creates a new entry, if the default value is one of these 3 types, the
+ * values will be copied. On the other hand, arrays and maps and other complex data structures are
+ * "passed by reference". This means that when the `DefaultMap` creates a new entry, if the default
+ * value is an array, then it would not be copied. Instead, the same shared array would be assigned
+ * to every entry. Thus, to solve this problem, any variable that is passed by reference must be
+ * created using a factory function to ensure that each copy is unique. For example:
+ *
+ * ```ts
+ * // Initializes a new empty DefaultMap with a default value of a new empty array.
+ * const factoryFunction = () => [];
+ * const defaultMapWithArray = new DefaultMap<string, string[]>(factoryFunction);
+ * ```
+ *
+ * In the previous two examples, the factory functions did not have any arguments. But you can also
+ * specify a factory function that takes one or more arguments:
+ *
+ * ```ts
+ * const factoryFunction = (arg: boolean) => arg ? 0 : 1;
+ * const defaultMapWithArg = new DefaultMap<string, string, [arg: boolean]>(factoryFunction);
+ * ```
+ *
+ * Similar to a normal `Map`, you can also include an initializer list in the constructor as the
+ * second argument:
+ *
+ * ```ts
+ * // Initializes a DefaultMap with a default value of "foo" and some initial values.
+ * const defaultMapWithInitialValues = new DefaultMap<string, string>("foo", [
+ *   ["a1", "a2"],
+ *   ["b1", "b2"],
+ * ], );
+ * ```
+ *
+ * Finally, note that `DefaultMap` has the following additional utility methods:
+ *
+ * - `getAndSetDefault` - The method that is called inside the overridden `get` method. In most
+ *   cases, you can use the overridden `get` method instead of calling this function directly.
+ *   However, if a factory function was provided during instantiation, and the factory function has
+ *   one or more arguments, then you must call this method instead (and provide the corresponding
+ *   arguments).
+ * - `getWithoutDefault` - Calls the original `Map.get` function (without setting the default
+ *   value).
+ * - `getDefaultValue` - Returns the default value to be used for a new key. (If a factory function
+ *   was provided during instantiation, this will execute the factory function.)
+ * - `getConstructorArg` - Helper method for cloning the map. Returns either the default value or
+ *   the reference to the factory function.
+ */
+export class DefaultMap<Key, Value, Args extends unknown[] = []> extends Map<
+  Key,
+  Value
+> {
+  private defaultValue: Value | undefined;
+  private defaultValueFactory: FactoryFunction<Value, Args> | undefined;
+
+  /**
+   * See the main `DefaultMap` documentation:
+   * https://isaacscript.github.io/isaacscript-common/classes/classes_DefaultMap.DefaultMap
+   */
+  constructor(
+    defaultValueOrFactoryFunction: Value | FactoryFunction<Value, Args>,
+    initializerArray?: Iterable<[Key, Value]>,
+  ) {
+    const argIsPrimitive = isPrimitive(defaultValueOrFactoryFunction);
+    const argIsFunction = isFunction(defaultValueOrFactoryFunction);
+    if (!argIsPrimitive && !argIsFunction) {
+      error(
+        `Failed to instantiate a DefaultMap since the provided default value was of type "${typeof defaultValueOrFactoryFunction}". This error usually means that you are trying to use an array (or some other non-primitive data structure that is passed by reference) as the default value. Instead, return the data structure in a factory function, like "() => []". See the DefaultMap documentation for more details.`,
+      );
+    }
+
+    super(initializerArray);
+
+    if (argIsFunction) {
+      this.defaultValue = undefined;
+      this.defaultValueFactory = defaultValueOrFactoryFunction;
+    } else {
+      this.defaultValue = defaultValueOrFactoryFunction as Value;
+      this.defaultValueFactory = undefined;
+    }
+  }
+
+  /**
+   * If the key exists, this will return the same thing as the normal `Map.get` method. Otherwise,
+   * it will set a default value for the provided key, and then return the default value.
+   */
+  getAndSetDefault(key: Key, ...extraArgs: Args): Value {
+    const value = super.get(key);
+    if (value !== undefined) {
+      return value;
+    }
+
+    const defaultValue = this.getDefaultValue(...extraArgs);
+    this.set(key, defaultValue);
+    return defaultValue;
+  }
+
+  /**
+   * Returns the default value to be used for a new key. (If a factory function was provided during
+   * instantiation, this will execute the factory function.)
+   */
+  getDefaultValue(...extraArgs: Args): Value {
+    if (this.defaultValue !== undefined) {
+      return this.defaultValue;
+    }
+
+    if (this.defaultValueFactory !== undefined) {
+      return this.defaultValueFactory(...extraArgs);
+    }
+
+    return error("A DefaultMap was incorrectly instantiated.");
+  }
+
+  /**
+   * Helper method for cloning the map. Returns either the default value or a reference to the
+   * factory function.
+   */
+  getConstructorArg(): Value | FactoryFunction<Value, Args> {
+    if (this.defaultValue !== undefined) {
+      return this.defaultValue;
+    }
+
+    if (this.defaultValueFactory !== undefined) {
+      return this.defaultValueFactory;
+    }
+
+    return error("A DefaultMap was incorrectly instantiated.");
+  }
+}

package/classes/ModUpgraded.d.ts

@@ -2,9 +2,9 @@ import { ModCallback } from "isaac-typescript-definitions";
 import { ModCallbackCustom } from "../enums/ModCallbackCustom";
 import { AddCallbackParameterCustom } from "../interfaces/AddCallbackParameterCustom";
 /**
- * `isaacscript-common` has many {@link ModCallbackCustom custom callbacks} that you can use in your
- * mods. Instead of hijacking the vanilla `Mod` object, we provide a `ModUpgraded` object for you to
- * use, which extends the base class and adds a new method of `AddCallbackCustom`.
+ * `isaacscript-common` has many custom callbacks that you can use in your mods. Instead of
+ * hijacking the vanilla `Mod` object, we provide a `ModUpgraded` object for you to use, which
+ * extends the base class and adds a new method of `AddCallbackCustom`.
  *
  * To upgrade your mod, use the `upgradeMod` helper function.
  */
@@ -16,7 +16,11 @@ export declare class ModUpgraded implements Mod {
     AddCallback<T extends ModCallback>(modCallback: T, ...args: AddCallbackParameter[T]): void;
     HasData(): boolean;
     LoadData(): string;
-    RemoveCallback(callbackID: ModCallback, callback: () => void): void;
+    /**
+     * This method does not care about the tertiary argument. Regardless of the conditions of how you
+     * registered the callback, it will be removed.
+     */
+    RemoveCallback<T extends ModCallback>(modCallback: T, callback: AddCallbackParameter[T][0]): void;
     RemoveData(): void;
     SaveData(data: string): void;
     AddCallbackCustom<T extends ModCallbackCustom>(modCallbackCustom: T, ...args: AddCallbackParameterCustom[T]): void;

package/classes/ModUpgraded.lua

@@ -3,9 +3,9 @@ local __TS__Class = ____lualib.__TS__Class
 local ____exports = {}
 local ____callbackRegisterFunctions = require("objects.callbackRegisterFunctions")
 local CALLBACK_REGISTER_FUNCTIONS = ____callbackRegisterFunctions.CALLBACK_REGISTER_FUNCTIONS
---- `isaacscript-common` has many {@link ModCallbackCustomcustom callbacks} that you can use in your
--- mods. Instead of hijacking the vanilla `Mod` object, we provide a `ModUpgraded` object for you to
--- use, which extends the base class and adds a new method of `AddCallbackCustom`.
+--- `isaacscript-common` has many custom callbacks that you can use in your mods. Instead of
+-- hijacking the vanilla `Mod` object, we provide a `ModUpgraded` object for you to use, which
+-- extends the base class and adds a new method of `AddCallbackCustom`.
 -- 
 -- To upgrade your mod, use the `upgradeMod` helper function.
 ____exports.ModUpgraded = __TS__Class()
@@ -24,8 +24,8 @@ end
 function ModUpgraded.prototype.LoadData(self)
     return self.Mod:LoadData()
 end
-function ModUpgraded.prototype.RemoveCallback(self, callbackID, callback)
-    self.Mod:RemoveCallback(callbackID, callback)
+function ModUpgraded.prototype.RemoveCallback(self, modCallback, callback)
+    self.Mod:RemoveCallback(modCallback, callback)
 end
 function ModUpgraded.prototype.RemoveData(self)
     self.Mod:RemoveData()
@@ -35,9 +35,6 @@ function ModUpgraded.prototype.SaveData(self, data)
 end
 function ModUpgraded.prototype.AddCallbackCustom(self, modCallbackCustom, ...)
     local callbackRegisterFunction = CALLBACK_REGISTER_FUNCTIONS[modCallbackCustom]
-    if callbackRegisterFunction == nil then
-        error("Failed to find a callback registration function for custom callback: " .. tostring(modCallbackCustom))
-    end
     callbackRegisterFunction(nil, ...)
 end
 return ____exports

package/classes/ModUpgraded.ts

@@ -0,0 +1,84 @@
+import { ModCallback } from "isaac-typescript-definitions";
+import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { AddCallbackParameterCustom } from "../interfaces/AddCallbackParameterCustom";
+import { CALLBACK_REGISTER_FUNCTIONS } from "../objects/callbackRegisterFunctions";
+
+/**
+ * `isaacscript-common` has many custom callbacks that you can use in your mods. Instead of
+ * hijacking the vanilla `Mod` object, we provide a `ModUpgraded` object for you to use, which
+ * extends the base class and adds a new method of `AddCallbackCustom`.
+ *
+ * To upgrade your mod, use the `upgradeMod` helper function.
+ */
+export class ModUpgraded implements Mod {
+  // -----------------
+  // Vanilla variables
+  // -----------------
+
+  Name: string; // The vanilla mod object stores this for some reason
+
+  // ----------------
+  // Custom variables
+  // ----------------
+
+  /** We store a copy of the original mod object so that we can re-implement its functions. */
+  Mod: Mod;
+
+  constructor(mod: Mod) {
+    this.Name = mod.Name;
+
+    this.Mod = mod;
+  }
+
+  // ---------------
+  // Vanilla methods
+  // ---------------
+
+  AddCallback<T extends ModCallback>(
+    modCallback: T,
+    ...args: AddCallbackParameter[T]
+  ): void {
+    this.Mod.AddCallback(modCallback, ...args);
+  }
+
+  HasData(): boolean {
+    return this.Mod.HasData();
+  }
+
+  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.
+   */
+  RemoveCallback<T extends ModCallback>(
+    modCallback: T,
+    callback: AddCallbackParameter[T][0],
+  ): void {
+    this.Mod.RemoveCallback(modCallback, callback);
+  }
+
+  RemoveData(): void {
+    this.Mod.RemoveData();
+  }
+
+  SaveData(data: string): void {
+    this.Mod.SaveData(data);
+  }
+
+  // --------------
+  // Custom methods
+  // --------------
+
+  // eslint-disable-next-line class-methods-use-this
+  AddCallbackCustom<T extends ModCallbackCustom>(
+    modCallbackCustom: T,
+    ...args: AddCallbackParameterCustom[T]
+  ): void {
+    const callbackRegisterFunction =
+      CALLBACK_REGISTER_FUNCTIONS[modCallbackCustom];
+    callbackRegisterFunction(...args);
+  }
+}