isaacscript-common 13.2.0 → 13.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "13.2.0",
+  "version": "13.3.1",
   "description": "Helper functions and features for IsaacScript mods.",
   "keywords": [
     "isaac",
@@ -22,6 +22,6 @@
   "main": "dist/src/index",
   "types": "dist/src/index.d.ts",
   "dependencies": {
-    "isaac-typescript-definitions": "^7.2.7"
+    "isaac-typescript-definitions": "^7.2.9"
   }
 }

package/src/callbacks/customRevive.ts

@@ -16,7 +16,8 @@ import { runNextGameFrame } from "../features/runInNFrames";
 import { saveDataManager } from "../features/saveDataManager/exports";
 import { removeCollectibleFromItemTracker } from "../functions/collectibles";
 import { removeAllFamiliars } from "../functions/entitiesSpecific";
-import { log, logError } from "../functions/log";
+import { log } from "../functions/log";
+import { logError } from "../functions/logMisc";
 import { getPlayerFromIndex, getPlayerIndex } from "../functions/playerIndex";
 import { isCharacter } from "../functions/players";
 import { PlayerIndex } from "../types/PlayerIndex";

package/src/callbacks/postNewRoomEarly.ts

@@ -8,7 +8,7 @@ import {
   getTopLeftWallGridIndex,
   spawnGridEntity,
 } from "../functions/gridEntities";
-import { logError } from "../functions/log";
+import { logError } from "../functions/logMisc";
 import {
   postNewRoomEarlyFire,
   postNewRoomEarlyHasSubscriptions,

package/src/classes/ModUpgraded.ts

@@ -1,12 +1,15 @@
 import { ModCallback } from "isaac-typescript-definitions";
 import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { getTime } from "../functions/benchmark";
+import { getParentFunctionDescription } from "../functions/log";
 import { AddCallbackParameterCustom } from "../interfaces/private/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`.
+ * extends the base class and adds a new method of `AddCallbackCustom`. (There is no corresponding
+ * `RemoveCallbackCustom`.)
  *
  * To upgrade your mod, use the `upgradeMod` helper function.
  */
@@ -28,10 +31,14 @@ export class ModUpgraded implements Mod {
   /** 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;
+  Debug: boolean;
+  TimeThreshold: float | undefined;
 
+  constructor(mod: Mod, debug: boolean, timeThreshold?: float) {
+    this.Name = mod.Name;
     this.Mod = mod;
+    this.Debug = debug;
+    this.TimeThreshold = timeThreshold;
   }
 
   // ---------------
@@ -42,7 +49,46 @@ export class ModUpgraded implements Mod {
     modCallback: T,
     ...args: AddCallbackParameter[T]
   ): void {
-    this.Mod.AddCallback(modCallback, ...args);
+    if (this.Debug) {
+      const callback = args[0];
+      const optionalArg = args[1];
+
+      const parentFunctionDescription = getParentFunctionDescription();
+      const callbackName = `ModCallback.${ModCallback[modCallback]}`;
+      const signature =
+        parentFunctionDescription === undefined
+          ? callbackName
+          : `${parentFunctionDescription} - ${callbackName}`;
+
+      /**
+       * We don't use the "log" helper function since it will always show the same "unknown" prefix.
+       */
+      const callbackWithLogger = (...callbackArgs: unknown[]) => {
+        const startTime = getTime();
+        Isaac.DebugString(`${signature} - START`);
+
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-expect-error
+        callback(...callbackArgs);
+
+        const endTime = getTime();
+        const elapsedTime = endTime - startTime;
+        if (
+          this.TimeThreshold === undefined ||
+          this.TimeThreshold >= elapsedTime
+        ) {
+          Isaac.DebugString(`${signature} - END - time: ${elapsedTime}`);
+        } else {
+          Isaac.DebugString(`${signature} - END`);
+        }
+      };
+
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-expect-error
+      this.Mod.AddCallback(modCallback, callbackWithLogger, optionalArg);
+    } else {
+      this.Mod.AddCallback(modCallback, ...args);
+    }
   }
 
   HasData(): boolean {

package/src/core/upgradeMod.ts

@@ -28,10 +28,18 @@ import { loadShaderCrashFix } from "../shaderCrashFix";
  * ```
  *
  * @param modVanilla The mod object returned by the `RegisterMod` function.
+ * @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
+ *                      specified number of seconds.
  * @returns The upgraded mod object.
  */
-export function upgradeMod(modVanilla: Mod): ModUpgraded {
-  const mod = new ModUpgraded(modVanilla);
+export function upgradeMod(
+  modVanilla: Mod,
+  debug = false,
+  timeThreshold?: float,
+): ModUpgraded {
+  const mod = new ModUpgraded(modVanilla, debug, timeThreshold);
 
   if (!areFeaturesInitialized()) {
     setFeaturesInitialized();

package/src/features/customStage/exports.ts

@@ -16,7 +16,7 @@ import {
 import { reorderedCallbacksSetStageInternal } from "../../callbacks/reorderedCallbacks";
 import { game } from "../../core/cachedClasses";
 import { doorSlotFlagsToDoorSlots } from "../../functions/doors";
-import { logError } from "../../functions/log";
+import { logError } from "../../functions/logMisc";
 import { newRNG } from "../../functions/rng";
 import {
   getRoomDataForTypeVariant,

package/src/features/extraConsoleCommands/listCommands.ts

@@ -83,7 +83,7 @@ import {
   logRoom,
   logSeedEffects,
   logSounds,
-} from "../../functions/log";
+} from "../../functions/logMisc";
 import { getMapPartialMatch } from "../../functions/map";
 import { runMergeTests } from "../../functions/mergeTests";
 import {

package/src/features/pause.ts

@@ -12,7 +12,7 @@ import {
   removeAllTears,
 } from "../functions/entitiesSpecific";
 import { isTear } from "../functions/isaacAPIClass";
-import { logError } from "../functions/log";
+import { logError } from "../functions/logMisc";
 import { getAllPlayers } from "../functions/playerIndex";
 import { useActiveItemTemp } from "../functions/players";
 import { disableAllInputsExceptFor, enableAllInputs } from "./disableInputs";

package/src/features/saveDataManager/load.ts

@@ -1,5 +1,6 @@
 import { jsonDecode } from "../../functions/jsonHelpers";
-import { log, logError } from "../../functions/log";
+import { log } from "../../functions/log";
+import { logError } from "../../functions/logMisc";
 import { iterateTableInOrder } from "../../functions/table";
 import { isString, isTable } from "../../functions/types";
 import { SaveData } from "../../interfaces/SaveData";

package/src/features/saveDataManager/main.ts

@@ -5,7 +5,7 @@ import { ModCallbackCustom } from "../../enums/ModCallbackCustom";
 import { SaveDataKey } from "../../enums/SaveDataKey";
 import { SerializationType } from "../../enums/SerializationType";
 import { deepCopy } from "../../functions/deepCopy";
-import { logError } from "../../functions/log";
+import { logError } from "../../functions/logMisc";
 import { onFirstFloor } from "../../functions/stage";
 import { clearTable, iterateTableInOrder } from "../../functions/table";
 import { SaveData } from "../../interfaces/SaveData";

package/src/features/taintedLazarusPlayers.ts

@@ -4,7 +4,7 @@
 import { ModCallback, PlayerType } from "isaac-typescript-definitions";
 import { ModUpgraded } from "../classes/ModUpgraded";
 import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
-import { logError } from "../functions/log";
+import { logError } from "../functions/logMisc";
 import { saveDataManager } from "./saveDataManager/exports";
 
 const FEATURE_NAME = "taintedLazarusPlayers";

package/src/functions/benchmark.ts

@@ -1,3 +1,4 @@
+import { SECOND_IN_MILLISECONDS } from "../core/constants";
 import { log } from "./log";
 
 /**
@@ -39,3 +40,25 @@ export function benchmark(
 
   return averages;
 }
+
+/**
+ * Helper function to get the current time in seconds for benchmarking / profiling purposes.
+ *
+ * - If the "--luadebug" flag is enabled, then this function will use the `socket.gettime` method,
+ *   which returns the epoch timestamp in seconds (e.g. "1640320492.5779"). This is preferable over
+ *   the `Isaac.GetTime` method, since it has one extra decimal point of precision.
+ * - If the "--luadebug" flag is disabled, then this function will use the `Isaac.GetTime` method,
+ *   which returns the number of seconds since the computer's operating system was started (e.g.
+ *   "739454.963"). (The milliseconds return value of `Isaac.GetTime` is converted to seconds to
+ *   align with the return value of `socket.gettime`.)
+ */
+export function getTime(): float {
+  const [ok, requiredSocket] = pcall(require, "socket");
+  if (ok) {
+    const socket = requiredSocket as Socket;
+    return socket.gettime();
+  }
+
+  // The "--luadebug" launch option is not enabled.
+  return Isaac.GetTime() / SECOND_IN_MILLISECONDS;
+}

package/src/functions/debugFunctions.ts

@@ -6,6 +6,7 @@ import { saveDataManagerSetGlobal } from "../features/saveDataManager/exports";
 import * as logExports from "./log";
 import { log } from "./log";
 import * as logEntitiesExports from "./logEntities";
+import * as logMiscExports from "./logMisc";
 
 /**
  * Helper function to enable some IsaacScript features that are useful when developing a mod. They
@@ -27,6 +28,7 @@ import * as logEntitiesExports from "./logEntities";
 export function enableDevFeatures(mod: ModUpgraded): void {
   saveDataManagerSetGlobal();
   setLogFunctionsGlobal();
+  setTracebackFunctionsGlobal();
   enableExtraConsoleCommands(mod);
   enableFastReset();
   removeFadeIn();
@@ -45,8 +47,8 @@ export function getTraceback(): string {
     return debug.traceback();
   }
 
-  if (sandboxGetTraceback !== undefined) {
-    return sandboxGetTraceback();
+  if (SandboxGetTraceback !== undefined) {
+    return SandboxGetTraceback();
   }
 
   return 'stack traceback:\n(the "--luadebug" flag is not enabled)';
@@ -81,13 +83,19 @@ export function isLuaDebugEnabled(): boolean {
 export function setLogFunctionsGlobal(): void {
   const globals = _G as Record<string, unknown>;
 
-  for (const [logFuncName, logFunc] of Object.entries(logExports)) {
-    globals[logFuncName] = logFunc;
+  for (const exports of [logExports, logMiscExports, logEntitiesExports]) {
+    // eslint-disable-next-line isaacscript/no-object-any
+    for (const [logFuncName, logFunc] of Object.entries(exports)) {
+      globals[logFuncName] = logFunc;
+    }
   }
+}
 
-  for (const [logFuncName, logFunc] of Object.entries(logEntitiesExports)) {
-    globals[logFuncName] = logFunc;
-  }
+export function setTracebackFunctionsGlobal(): void {
+  const globals = _G as Record<string, unknown>;
+
+  globals["getTraceback"] = getTraceback;
+  globals["traceback"] = traceback;
 }
 
 /**
@@ -101,21 +109,3 @@ export function traceback(): void {
   const tracebackOutput = getTraceback();
   log(tracebackOutput);
 }
-
-// If the debug functions will provide useful output, make them global by default.
-if (isLuaDebugEnabled() || sandboxGetTraceback !== undefined) {
-  setDebugFunctionsGlobal();
-}
-
-function setDebugFunctionsGlobal() {
-  // "debug" is not always defined like the Lua definitions imply.
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-  if (_G.debug === undefined && sandboxGetTraceback === undefined) {
-    return;
-  }
-
-  const globals = _G as Record<string, unknown>;
-
-  globals["getTraceback"] = getTraceback;
-  globals["traceback"] = traceback;
-}

package/src/functions/globals.ts

@@ -205,7 +205,7 @@ export function getDefaultGlobals(): ReadonlySet<string> {
 }
 
 function isRacingPlusSandboxEnabled() {
-  return getParentFunctionDescription !== undefined;
+  return SandboxGetParentFunctionDescription !== undefined;
 }
 
 /**

package/src/functions/hex.ts

@@ -1,4 +1,4 @@
-import { logError } from "./log";
+import { logError } from "./logMisc";
 
 const HEX_STRING_LENGTH = 6;
 

package/src/functions/jsonHelpers.ts

@@ -1,5 +1,5 @@
 import * as jsonLua from "../lib/jsonLua";
-import { logError } from "./log";
+import { logError } from "./logMisc";
 
 function tryDecode(this: void, jsonString: string) {
   return jsonLua.decode(jsonString) as LuaMap<AnyNotNil, unknown>;