isaacscript-common 6.6.1-dev.1 → 6.6.1-dev.5

package/src/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/src/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/src/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/src/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/src/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/src/classes/DefaultMap.ts

@@ -0,0 +1,172 @@
+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);
+    }
+
+    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;
+    }
+
+    error("A DefaultMap was incorrectly instantiated.");
+  }
+}

package/src/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);
+  }
+}

package/src/constants.ts

@@ -0,0 +1,189 @@
+import {
+  CollectibleType,
+  Dimension,
+  ItemPoolType,
+  LevelStage,
+  RoomType,
+  TrinketSlot,
+} from "isaac-typescript-definitions";
+import { NUM_NORMAL_PILL_COLORS } from "./constantsFirstLast";
+import { getEnumLength, getLastEnumValue } from "./functions/enums";
+
+/**
+ * The distance of the laser when Azazel does not have any range up items yet. For more info, see
+ * the documentation for the `getAzazelBrimstoneDistance` function.
+ */
+export const AZAZEL_DEFAULT_BRIMSTONE_DISTANCE = 75.125;
+
+/**
+ * The path to the png file for collectible items during Curse of the Blind, making them appear with
+ * a red question mark.
+ */
+export const BLIND_ITEM_PNG_PATH = "gfx/items/collectibles/questionmark.png";
+
+/** Bombs explode when their frame count is equal to this value. */
+export const BOMB_EXPLODE_FRAME = 45;
+
+/** This is the initial value of the `EntityPickup.Wait` property after a collectible is spawned. */
+export const COLLECTIBLE_INITIAL_WAIT = 20;
+
+export const DEFAULT_ITEM_POOL_TYPE = ItemPoolType.TREASURE;
+
+/** This is also the distance that a player spawns from the door that they enter a room from. */
+export const DISTANCE_OF_GRID_TILE = 40;
+
+export const DOOR_HITBOX_RADIUS = 11;
+
+/**
+ * When Eggies take fatal damage, they go into NpcState.STATE_SUICIDE and spawn 14 Swarm Spiders
+ * while their StateFrame ticks upwards. The 14th spider appears when the StateFrame is at this
+ * value.
+ */
+export const EGGY_STATE_FRAME_OF_FINAL_SPIDER = 45;
+
+/**
+ * A non-existent or completely transparent PNG file for use in clearing sprites. For more
+ * information, see the documentation for the `clearSprite` helper function.
+ */
+export const EMPTY_PNG_PATH = "gfx/none.png";
+
+/**
+ * The random items that appear when the player has TMTRAINER are generated on the fly as they are
+ * encountered by the player. The first TMTRAINER item takes the final possible 32 bit number. The
+ * second TMTRAINER item subtracts one from that, and so on.
+ */
+export const FIRST_GLITCHED_COLLECTIBLE_TYPE = ((1 << 32) -
+  1) as CollectibleType;
+
+/** Game frames are what is returned by the `Game.GetFrameCount` method. */
+export const GAME_FRAMES_PER_SECOND = 30;
+
+/** Render frames are what is returned by the `Isaac.GetFrameCount` method. */
+export const RENDER_FRAMES_PER_SECOND = 60;
+
+export const GRID_INDEX_CENTER_OF_1X1_ROOM = 67;
+
+/**
+ * The floor is represented by a 13x13 grid. Room indexes start at 0. The first column is
+ * represented by grid indexes 0, 13, 26, and so on.
+ */
+export const LEVEL_GRID_COLUMN_HEIGHT = 13;
+
+/**
+ * The floor is represented by a 13x13 grid. Room indexes start at 0. The first row is represented
+ * by grid indexes from 0 to 12. The second row is represented by grid indexes from 13 to 25, and so
+ * on.
+ */
+export const LEVEL_GRID_ROW_WIDTH = 13;
+
+/**
+ * The floor is represented by a 13x13 grid. Room indexes start at 0. The first row is represented
+ * by grid indexes from 0 to 12. The second row is represented by grid indexes from 13 to 25, and so
+ * on. The maximum room index possible is 168. (It is not 169 because we start at 0 instead of 1.)
+ */
+export const MAX_LEVEL_GRID_INDEX = 168;
+
+/**
+ * The game has a limit on the number of currently spawned familiars and will refuse to spawn any
+ * more if it reaches the limit. Blue flies and blue spiders have a lower priority and will be
+ * deleted to make room for other familiars.
+ */
+export const MAX_NUM_FAMILIARS = 64;
+
+/** The game can only handle up to four different players. */
+export const MAX_NUM_INPUTS = 4;
+
+/** With Birthright, it is possible for Magdalene to have 18 heart containers. */
+export const MAX_PLAYER_HEART_CONTAINERS = 18;
+
+/**
+ * As the player continues to move in a direction, they will accelerate. When going from one wall to
+ * another in a 2x2 room at 2.0 speed (the maximum that the speed stat can rise to), the amount of
+ * units moved per update frame will climb to around 9.797 as they hit the opposite wall. The
+ * constant specifies a value of 9.8 to be safe.
+ */
+export const MAX_PLAYER_SPEED_IN_UNITS = 9.8;
+
+export const MAX_PLAYER_TRINKET_SLOTS = getEnumLength(TrinketSlot);
+
+/** If you set `EntityPlayer.ShotSpeed` lower than this value, it will have no effect. */
+export const MIN_PLAYER_SHOT_SPEED_STAT = 0.6;
+
+/** If you set `EntityPlayer.Speed` lower than this value, it will have no effect. */
+export const MIN_PLAYER_SPEED_STAT = 0.1;
+
+export const FIRST_ROOM_TYPE = RoomType.DEFAULT;
+export const LAST_ROOM_TYPE = getLastEnumValue(RoomType);
+
+/**
+ * The maximum speed stat that a player can have. Any additional speed beyond this will not take
+ * effect.
+ */
+export const MAX_SPEED_STAT = 2.0;
+
+/** This is in the center of the room. */
+export const NEW_FLOOR_STARTING_POSITION_NORMAL_MODE = Vector(320, 280);
+
+/** This is near the top door. */
+export const NEW_FLOOR_STARTING_POSITION_GREED_MODE = Vector(320, 280);
+
+/**
+ * This is next to the bottom door. Presumably, the player does not start in the center of the room
+ * (like they do when getting to a new stage) so that the controls graphic is more visible.
+ */
+export const NEW_RUN_PLAYER_STARTING_POSITION = Vector(320, 380);
+
+export const FIRST_STAGE = LevelStage.BASEMENT_1;
+export const LAST_STAGE = getLastEnumValue(LevelStage);
+
+/** Corresponds to the maximum value for `EntityPlayer.SamsonBerserkCharge`. */
+export const MAX_TAINTED_SAMSON_BERSERK_CHARGE = 100000;
+
+export const NUM_DIMENSIONS = getEnumLength(Dimension) - 1; // Account for "Dimension.CURRENT"
+
+/**
+ * The pill pool for each run is comprised of one effect for each unique pill color (minus gold and
+ * horse pills.)
+ */
+export const NUM_PILLS_IN_POOL = NUM_NORMAL_PILL_COLORS;
+
+export const SECOND_IN_MILLISECONDS = 1000;
+export const MINUTE_IN_MILLISECONDS = 60 * SECOND_IN_MILLISECONDS;
+
+export const ONE_BY_ONE_ROOM_GRID_SIZE = 135;
+
+/** After taking damage, `EntityPlayer.SamsonBerserkCharge` is incremented by this amount. */
+export const TAINTED_SAMSON_BERSERK_CHARGE_FROM_TAKING_DAMAGE = 10000;
+
+/**
+ * This is the number of draw coordinates that each heart spans on the UI in the upper left hand
+ * corner.
+ */
+export const UI_HEART_WIDTH = 12;
+
+/**
+ * This is a safer version of the `Vector.One` constant. (Other mods can mutate `Vector.One`, so it
+ * is not safe to use.)
+ */
+export const VectorOne: Readonly<Vector> = Vector(1, 1);
+
+/**
+ * This is a safer version of the `Vector.Zero` constant. (Other mods can mutate `Vector.Zero`, so
+ * it is not safe to use.)
+ */
+export const VectorZero: Readonly<Vector> = Vector(0, 0);
+
+/**
+ * This is a safer version of the `Color.Default` constant. (Other mods can mutate `Color.Default`,
+ * so it is not safe to use.)
+ *
+ * If you need to mutate this, make a copy first with the `copyColor` helper function.
+ */
+export const ColorDefault: Readonly<Color> = Color(1, 1, 1);
+
+/**
+ * Equal to `KColor(1, 1, 1, 1)`.
+ *
+ * If you need to mutate this, make a copy first with the `copyKColor` helper function.
+ */
+export const KColorDefault: Readonly<KColor> = KColor(1, 1, 1, 1);