isaacscript-common 2.0.34 → 2.3.0

package/.eslintrc.js

@@ -0,0 +1,70 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+/* eslint-disable @typescript-eslint/no-unsafe-call */
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+
+const path = require("path"); // eslint-disable-line @typescript-eslint/no-var-requires
+
+const REPO_ROOT = path.join(__dirname, "..", "..");
+const ESLINT_CONFIG_ISAACSCRIPT_PATH = path.join(
+  REPO_ROOT,
+  "packages",
+  "eslint-config-isaacscript",
+);
+
+module.exports = {
+  extends: [
+    path.join(ESLINT_CONFIG_ISAACSCRIPT_PATH, "mod.js"),
+    path.join(ESLINT_CONFIG_ISAACSCRIPT_PATH, "monorepo.js"),
+  ],
+
+  parserOptions: {
+    project: path.join(__dirname, "tsconfig.json"),
+  },
+
+  rules: {
+    /**
+     * Documentation:
+     * https://github.com/jrdrg/eslint-plugin-sort-exports
+     * Not defined in parent configs.
+     */
+    "sort-exports/sort-exports": [
+      "error",
+      {
+        sortDir: "asc",
+      },
+    ],
+  },
+
+  overrides: [
+    {
+      files: ["./src/callbacks/subscriptions/**"],
+      rules: {
+        "sort-exports/sort-exports": "off",
+      },
+    },
+    {
+      files: ["./src/features/*.ts"],
+      rules: {
+        "sort-exports/sort-exports": "off",
+      },
+    },
+    {
+      files: ["./src/maps/*.ts"],
+      rules: {
+        "sort-exports/sort-exports": "off",
+      },
+    },
+    {
+      files: ["./src/objects/*.ts"],
+      rules: {
+        "sort-exports/sort-exports": "off",
+      },
+    },
+    {
+      files: ["./src/sets/*.ts"],
+      rules: {
+        "sort-exports/sort-exports": "off",
+      },
+    },
+  ],
+};

package/README.md

@@ -2,6 +2,6 @@
 
 [![npm version](https://img.shields.io/npm/v/isaacscript-common.svg)](https://www.npmjs.com/package/isaacscript-common)
 
-This repository contains helper functions and extra features for IsaacScript mods. You can browse the auto-generated documentation [here](https://isaacscript.github.io/isaacscript-common/index.html).
+This package contains helper functions and extra features for IsaacScript mods. Start by [browsing the auto-generated documentation](https://isaacscript.github.io/isaacscript-common).
 
 For more information about IsaacScript, see the [official website](https://isaacscript.github.io/).

package/build.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+
+set -e # Exit on any errors
+
+# Get the directory of this script
+# https://stackoverflow.com/questions/59895/getting-the-source-directory-of-a-bash-script-from-within
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+
+# Get the name of the repository:
+# https://stackoverflow.com/questions/23162299/how-to-get-the-last-part-of-dirname-in-bash/23162553
+REPO_NAME="$(basename "$DIR")"
+
+SECONDS=0
+
+cd "$DIR"
+
+OUT_DIR="$DIR/../../dist/packages/$REPO_NAME"
+
+rm -rf "$OUT_DIR"
+npx tstl
+
+# Copy the rest of the files needed for NPM.
+cp "$DIR/LICENSE" "$OUT_DIR/"
+cp "$DIR/package.json" "$OUT_DIR/"
+cp "$DIR/README.md" "$OUT_DIR/"
+
+echo "Successfully built in $SECONDS seconds."

package/docs.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+set -e # Exit on any errors
+
+# Get the directory of this script
+# https://stackoverflow.com/questions/59895/getting-the-source-directory-of-a-bash-script-from-within
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+
+# Get the name of the repository:
+# https://stackoverflow.com/questions/23162299/how-to-get-the-last-part-of-dirname-in-bash/23162553
+REPO_NAME="$(basename "$DIR")"
+
+SECONDS=0
+
+cd "$DIR"
+
+OUT_DIR="$DIR/../docs/docs/$REPO_NAME"
+rm -rf "$COMMON_DIR"
+npx typedoc # The options are stored in "typedoc.json".
+
+echo "Successfully generated docs for $REPO_NAME in $SECONDS seconds."

package/lint.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+
+set -e # Exit on any errors
+
+# Get the directory of this script:
+# https://stackoverflow.com/questions/59895/getting-the-source-directory-of-a-bash-script-from-within
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+
+SECONDS=0
+
+cd "$DIR"
+
+# Step 1 - Use Prettier to check formatting.
+npx prettier --ignore-path="$DIR/../../.prettierignore" --check .
+
+# Step 2 - Use ESLint to lint the TypeScript.
+# Since all ESLint errors are set to warnings, we set max warnings to 0 so that warnings will fail
+# in CI.
+npx eslint --max-warnings 0 .
+
+# Step 3 - Spell check every file using CSpell.
+# We use no-progress and no-summary because we want to only output errors.
+npx cspell --no-progress --no-summary
+
+# Step 4 - Check for unused exports
+# The "--error" flag makes it return an error code of 1 if unused exports are found.
+# We ignore exports defined in the index.ts file since those are intended to be consumed by
+# end-users.
+npx ts-prune --error --ignore index.ts
+
+# Step 5 - Validate that every doc page is included.
+npx ts-node --require "tsconfig-paths/register" "$DIR/scripts/docsEntryPointLint.ts"
+
+echo "Successfully linted in $SECONDS seconds."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "2.0.34",
+  "version": "2.3.0",
   "description": "Helper functions and features for IsaacScript mods.",
   "keywords": [
     "isaac",
@@ -22,6 +22,7 @@
   "main": "index",
   "types": "index.d.ts",
   "dependencies": {
-    "isaac-typescript-definitions": "^2.0.53"
-  }
-}
+    "isaac-typescript-definitions": "^2.0.54"
+  },
+  "gitHead": "0a29e1197248023ae0e836113acb4e84650f8148"
+}

package/project.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "library",
+  "targets": {
+    "build": {
+      "executor": "@nrwl/workspace:run-commands",
+      "options": {
+        "command": "bash packages/isaacscript-common/build.sh"
+      }
+    },
+    "lint": {
+      "executor": "@nrwl/workspace:run-commands",
+      "options": {
+        "command": "bash packages/isaacscript-common/lint.sh"
+      }
+    },
+    "publish": {
+      "executor": "@nrwl/workspace:run-commands",
+      "options": {
+        "command": "ts-node --require tsconfig-paths/register --project tools/tsconfig.json tools/publish.ts isaacscript-common"
+      },
+      "dependsOn": [
+        {
+          "projects": "self",
+          "target": "build"
+        }
+      ]
+    },
+    "version": {
+      "executor": "@jscutlery/semver:version",
+      "options": {
+        "preset": "conventional"
+      }
+    }
+  },
+  "tags": []
+}

package/release.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+set -e # Exit on any errors
+
+# Get the directory of this script:
+# https://stackoverflow.com/questions/59895/getting-the-source-directory-of-a-bash-script-from-within
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+
+# Get the name of the repository:
+# https://stackoverflow.com/questions/23162299/how-to-get-the-last-part-of-dirname-in-bash/23162553
+REPO_NAME="$(basename "$DIR")"
+
+REPO_ROOT="$DIR/../.."
+cd "$REPO_ROOT"
+
+"$REPO_ROOT/release.sh" "$REPO_NAME" "$@"

package/scripts/.eslintrc.js

@@ -0,0 +1,21 @@
+const path = require("path"); // eslint-disable-line @typescript-eslint/no-var-requires
+
+const REPO_ROOT = path.join(__dirname, "..", "..", "..");
+const ESLINT_CONFIG_ISAACSCRIPT_PATH = path.join(
+  REPO_ROOT,
+  "packages",
+  "eslint-config-isaacscript",
+);
+
+module.exports = {
+  extends: [
+    path.join(ESLINT_CONFIG_ISAACSCRIPT_PATH, "base.js"),
+    path.join(ESLINT_CONFIG_ISAACSCRIPT_PATH, "monorepo.js"),
+  ],
+
+  parserOptions: {
+    project: path.join(__dirname, "tsconfig.json"),
+  },
+
+  rules: {},
+};

package/scripts/docsEntryPointLint.ts

@@ -0,0 +1,135 @@
+import glob from "glob";
+import path from "path";
+
+const TYPEDOC_CONFIG_PATH = path.join(__dirname, "..", "typedoc.json");
+
+main();
+
+function main() {
+  let atLeastOneError = false;
+
+  const entryPoints = getEntryPoints();
+  const entryPointsSet = new Set(entryPoints);
+
+  const classesFilePaths = glob
+    .sync("../isaacscript-common/src/classes/*.ts")
+    .map((string) => string.replace(/^\.\.\/isaacscript-common\//, ""));
+  for (const filePath of classesFilePaths) {
+    if (!entryPointsSet.has(filePath)) {
+      console.error(
+        `Failed to find the following file in the entry point: ${filePath}`,
+      );
+      atLeastOneError = true;
+    }
+  }
+
+  const enumsFilePaths = glob
+    .sync("../isaacscript-common/src/enums/*.ts")
+    .map((string) => string.replace(/^\.\.\/isaacscript-common\//, ""));
+  for (const filePath of enumsFilePaths) {
+    if (filePath.endsWith("private")) {
+      continue;
+    }
+
+    if (!entryPointsSet.has(filePath)) {
+      console.error(
+        `Failed to find the following file in the entry point: ${filePath}`,
+      );
+      atLeastOneError = true;
+    }
+  }
+
+  const featuresFilePaths = glob
+    .sync("../isaacscript-common/src/features/*.ts")
+    .map((string) => string.replace(/^\.\.\/isaacscript-common\//, ""));
+  for (const filePath of featuresFilePaths) {
+    if (!entryPointsSet.has(filePath)) {
+      if (!filePath.endsWith(".ts")) {
+        continue;
+      }
+
+      console.error(
+        `Failed to find the following file in the entry point: ${filePath}`,
+      );
+      atLeastOneError = true;
+    }
+  }
+
+  const functionFilePaths = glob
+    .sync("../isaacscript-common/src/functions/*.ts")
+    .map((string) => string.replace(/^\.\.\/isaacscript-common\//, ""));
+  for (const filePath of functionFilePaths) {
+    if (filePath.endsWith("Tests.ts")) {
+      continue;
+    }
+
+    if (!entryPointsSet.has(filePath)) {
+      console.error(
+        `Failed to find the following file in the entry point: ${filePath}`,
+      );
+      atLeastOneError = true;
+    }
+  }
+
+  const interfacesFilePaths = glob
+    .sync("../isaacscript-common/src/interfaces/*.ts")
+    .map((string) => string.replace(/^\.\.\/isaacscript-common\//, ""));
+  for (const filePath of interfacesFilePaths) {
+    if (
+      filePath.endsWith("private") ||
+      filePath.endsWith("AddCallbackParameterCustom.ts")
+    ) {
+      continue;
+    }
+
+    if (!entryPointsSet.has(filePath)) {
+      console.error(
+        `Failed to find the following file in the entry point: ${filePath}`,
+      );
+      atLeastOneError = true;
+    }
+  }
+
+  // Only specific maps in the "maps" directory are exported. Thus, we do not check this directory.
+
+  const typesFilePaths = glob
+    .sync("../isaacscript-common/src/types/*.ts")
+    .map((string) => string.replace(/^\.\.\/isaacscript-common\//, ""));
+  for (const filePath of typesFilePaths) {
+    if (filePath.endsWith("private") || filePath.endsWith(".d.ts")) {
+      continue;
+    }
+
+    if (!entryPointsSet.has(filePath)) {
+      console.error(
+        `Failed to find the following file in the entry point: ${filePath}`,
+      );
+      atLeastOneError = true;
+    }
+  }
+
+  if (atLeastOneError) {
+    process.exit(1);
+  }
+}
+
+function getEntryPoints(): string[] {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires,import/no-dynamic-require,global-require
+  const typeDocConfig = require(TYPEDOC_CONFIG_PATH) as Record<string, unknown>;
+
+  if (typeof typeDocConfig !== "object") {
+    error(`Failed to read the config file: ${TYPEDOC_CONFIG_PATH}`);
+  }
+
+  const { entryPoints } = typeDocConfig;
+  if (!Array.isArray(entryPoints)) {
+    error(`Failed to read the "entryPoints" field: ${TYPEDOC_CONFIG_PATH}`);
+  }
+
+  return entryPoints as string[];
+}
+
+export function error(...args: unknown[]): never {
+  console.error(...args);
+  return process.exit(1);
+}

package/scripts/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../../tsconfig.node.json",
+
+  "include": [".eslintrc.js", "*.ts"],
+}

package/src/cachedClasses.ts

@@ -0,0 +1,39 @@
+/**
+ * A cached version of the class returned from the `Game()` constructor.
+ *
+ * Use this instead of invoking the constructor again for a miniscule performance increase.
+ *
+ * Caching the results of a this constructor is safe, but caching other classes (like `Level` or
+ * `Room`) is not safe and can lead to the game crashing in certain situations.
+ */
+export const game = Game();
+
+/**
+ * A cached version of the class returned from the `Isaac.GetItemConfig()` constructor.
+ *
+ * Use this instead of invoking the constructor again for a miniscule performance increase.
+ *
+ * Caching the results of a this constructor is safe, but caching other classes (like `Level` or
+ * `Room`) is not safe and can lead to the game crashing in certain situations.
+ */
+export const itemConfig = Isaac.GetItemConfig();
+
+/**
+ * A cached version of the class returned from the `MusicManager()` constructor.
+ *
+ * Use this instead of invoking the constructor again for a miniscule performance increase.
+ *
+ * Caching the results of a this constructor is safe, but caching other classes (like `Level` or
+ * `Room`) is not safe and can lead to the game crashing in certain situations.
+ */
+export const musicManager = MusicManager();
+
+/**
+ * A cached version of the class returned from the `SFXManager()` constructor.
+ *
+ * Use this instead of invoking the constructor again for a miniscule performance increase.
+ *
+ * Caching the results of a this constructor is safe, but caching other classes (like `Level` or
+ * `Room`) is not safe and can lead to the game crashing in certain situations.
+ */
+export const sfxManager = SFXManager();

package/src/callbacks/customRevive.ts

@@ -0,0 +1,206 @@
+import {
+  CollectibleType,
+  FamiliarVariant,
+  ModCallback,
+  PlayerType,
+  SoundEffect,
+} from "isaac-typescript-definitions";
+import { sfxManager } from "../cachedClasses";
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { runNextGameFrame } from "../features/runInNFrames";
+import { saveDataManager } from "../features/saveDataManager/exports";
+import { removeCollectibleFromItemTracker } from "../functions/collectibles";
+import { removeAllFamiliars } from "../functions/entitySpecific";
+import { log, logError } from "../functions/log";
+import { isCharacter } from "../functions/player";
+import { getPlayerFromIndex, getPlayerIndex } from "../functions/playerIndex";
+import { PlayerIndex } from "../types/PlayerIndex";
+import {
+  postCustomReviveFire,
+  postCustomReviveHasSubscriptions,
+} from "./subscriptions/postCustomRevive";
+import {
+  preCustomReviveFire,
+  preCustomReviveHasSubscriptions,
+} from "./subscriptions/preCustomRevive";
+
+const DEBUG = false;
+
+enum CustomReviveState {
+  DISABLED,
+
+  /**
+   * We can't immediately jump to waiting for an item animation because it is possible for a player
+   * to be holding an item above their head as they are dying (e.g. with Razor Blade).
+   */
+  WAITING_FOR_ROOM_TRANSITION,
+
+  WAITING_FOR_ITEM_ANIMATION,
+}
+
+const v = {
+  run: {
+    state: CustomReviveState.DISABLED,
+    revivalType: null as int | null,
+    dyingPlayerIndex: null as PlayerIndex | null,
+  },
+};
+
+/** @internal */
+export function customReviveCallbacksInit(mod: ModUpgraded): void {
+  saveDataManager("customRevive", v, hasSubscriptions);
+
+  mod.AddCallback(ModCallback.POST_RENDER, postRender); // 2
+  mod.AddCallback(ModCallback.POST_NEW_ROOM, postNewRoom); // 19
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED,
+    postPEffectUpdateReordered,
+  );
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_PLAYER_FATAL_DAMAGE,
+    postPlayerFatalDamage,
+  );
+  mod.AddCallbackCustom(ModCallbackCustom.PRE_BERSERK_DEATH, preBerserkDeath);
+}
+
+function hasSubscriptions() {
+  return (
+    preCustomReviveHasSubscriptions() || postCustomReviveHasSubscriptions()
+  );
+}
+
+// ModCallback.POST_RENDER (2)
+function postRender() {
+  if (v.run.state !== CustomReviveState.WAITING_FOR_ITEM_ANIMATION) {
+    return;
+  }
+
+  // The 1-up sound will fire before the item holding animation begins, so we mute it on every
+  // render frame.
+  sfxManager.Stop(SoundEffect.ONE_UP);
+}
+
+// ModCallback.POST_NEW_ROOM (19)
+function postNewRoom() {
+  if (v.run.state !== CustomReviveState.WAITING_FOR_ROOM_TRANSITION) {
+    return;
+  }
+
+  v.run.state = CustomReviveState.WAITING_FOR_ITEM_ANIMATION;
+  logStateChanged();
+}
+
+// ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED
+function postPEffectUpdateReordered(player: EntityPlayer) {
+  checkWaitingForItemAnimation(player);
+}
+
+function checkWaitingForItemAnimation(player: EntityPlayer) {
+  if (v.run.state !== CustomReviveState.WAITING_FOR_ITEM_ANIMATION) {
+    return;
+  }
+
+  if (v.run.dyingPlayerIndex === null) {
+    return;
+  }
+
+  const playerIndex = getPlayerIndex(player);
+  if (playerIndex !== v.run.dyingPlayerIndex) {
+    return;
+  }
+
+  let playerToCheckHoldingItem = player;
+  if (isCharacter(player, PlayerType.THE_SOUL_B)) {
+    const forgottenBody = player.GetOtherTwin();
+    if (forgottenBody !== undefined) {
+      playerToCheckHoldingItem = forgottenBody;
+    }
+  }
+
+  if (!playerToCheckHoldingItem.IsHoldingItem()) {
+    return;
+  }
+
+  // The player is now playing the animation where they hold the 1-Up item overhead. The
+  // `EntityPlayer.StopExtraAnimation` method will not work to stop this animation. End-users are
+  // expected to play a new animation in the PostCustomRevive callback, which will overwrite the
+  // 1-Up animation.
+
+  if (v.run.revivalType !== null) {
+    postCustomReviveFire(playerToCheckHoldingItem, v.run.revivalType);
+  }
+
+  v.run.state = CustomReviveState.DISABLED;
+  v.run.revivalType = null;
+  v.run.dyingPlayerIndex = null;
+  logStateChanged();
+}
+
+// ModCallbackCustom.POST_PLAYER_FATAL_DAMAGE
+function postPlayerFatalDamage(player: EntityPlayer) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  playerIsAboutToDie(player);
+}
+
+// ModCallbackCustom.PRE_BERSERK_DEATH
+function preBerserkDeath(player: EntityPlayer) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  playerIsAboutToDie(player);
+}
+
+/**
+ * The player is about to die, which will immediately delete the save data for the run. To prevent
+ * this from happening, we grant the 1-Up item.
+ */
+function playerIsAboutToDie(player: EntityPlayer) {
+  const revivalType = preCustomReviveFire(player);
+  if (revivalType === undefined) {
+    return;
+  }
+
+  v.run.state = CustomReviveState.WAITING_FOR_ROOM_TRANSITION;
+  v.run.revivalType = revivalType;
+  v.run.dyingPlayerIndex = getPlayerIndex(player);
+  logStateChanged();
+
+  player.AddCollectible(CollectibleType.ONE_UP, 0, false);
+  removeAllFamiliars(FamiliarVariant.ONE_UP);
+  removeCollectibleFromItemTracker(CollectibleType.ONE_UP);
+
+  // The player should always be dead one frame from now. If they are not, then something has gone
+  // wrong, probably with the `isDamageToPlayerFatal` function. Since end-user code is already
+  // assuming that a custom revive is occurring, explicitly kill the player.
+  const playerIndex = getPlayerIndex(player);
+  runNextGameFrame(() => {
+    const futurePlayer = getPlayerFromIndex(playerIndex);
+    if (futurePlayer === undefined) {
+      return;
+    }
+
+    if (futurePlayer.IsDead()) {
+      return;
+    }
+
+    logError(
+      "The player is still alive after initializing a custom revive. Explicitly killing the player.",
+    );
+    futurePlayer.Kill();
+  });
+}
+
+function logStateChanged() {
+  if (DEBUG) {
+    log(
+      `Custom revive state changed: ${CustomReviveState[v.run.state]} (${
+        v.run.state
+      })`,
+    );
+  }
+}