isaacscript-common 13.3.2 → 13.3.3

package/src/core/upgradeMod.ts

@@ -31,7 +31,8 @@ import { loadShaderCrashFix } from "../shaderCrashFix";
  * @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.
+ *                      specified number of seconds (if the "--luadebug" launch flag is turned on)
+ *                      or milliseconds (if the "--luadebug" launch flag is turned off).
  * @returns The upgraded mod object.
  */
 export function upgradeMod(

package/src/functions/benchmark.ts

@@ -1,4 +1,3 @@
-import { SECOND_IN_MILLISECONDS } from "../core/constants";
 import { log } from "./log";
 
 /**
@@ -40,25 +39,3 @@ 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

@@ -1,37 +1,42 @@
-import { ModUpgraded } from "../classes/ModUpgraded";
-import { enableExtraConsoleCommands } from "../features/extraConsoleCommands/exports";
-import { removeFadeIn } from "../features/fadeInRemover";
-import { enableFastReset } from "../features/fastReset";
-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
- * should not be enabled when your mod goes to production (i.e. when it is uploaded to the Steam
- * Workshop).
+ * Helper function to get the current time for benchmarking / profiling purposes.
  *
- * The list of development features that are enabled are as follows:
+ * The return value will either be in seconds or milliseconds, depending on if the "--luadebug" flag
+ * is turned on or not.
  *
- * - `saveDataManagerSetGlobal` - Sets your local variables registered with the save data manager as
- *   global variables so you can access them from the in-game console.
- * - `setLogFunctionsGlobal` - Sets the various log functions global so that you can access them
- *   from the in-game console.
- * - `enableExtraConsoleCommands` - Enables many extra in-game console commands that make warping
- *   around easier (like e.g. `angel` to warp to the Angel Room).
- * - `enableFastReset` - Makes it so that the r key resets the game instantaneously.
- * - `removeFadeIn` - Removes the slow fade in that occurs at the beginning of the run, so that you
- *   can immediately start playing or testing.
+ * If the "--luadebug" flag is present, 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 more conventional `Isaac.GetTime` method, since it has one extra decimal point of precision.
+ *
+ * If the "--luadebug" flag is not present, then this function will use the `Isaac.GetTime` method,
+ * which returns the number of milliseconds since the computer's operating system was started (e.g.
+ * "739454963").
+ *
+ * @param useSocketIfAvailable Optional. Whether to use the `socket.gettime` method, if available.
+ *                             Default is true. If set to false, the `Isaac.GetTime()` method will
+ *                             always be used.
  */
-export function enableDevFeatures(mod: ModUpgraded): void {
-  saveDataManagerSetGlobal();
-  setLogFunctionsGlobal();
-  setTracebackFunctionsGlobal();
-  enableExtraConsoleCommands(mod);
-  enableFastReset();
-  removeFadeIn();
+export function getTime(useSocketIfAvailable = true): float {
+  if (useSocketIfAvailable) {
+    if (SandboxGetTime !== undefined) {
+      return SandboxGetTime();
+    }
+
+    if (isLuaDebugEnabled()) {
+      const [ok, requiredSocket] = pcall(require, "socket");
+      if (ok) {
+        const socket = requiredSocket as Socket;
+        return socket.gettime();
+      }
+    }
+  }
+
+  // We could divide the result by 1000 in order to unify the return type with `socket.gettime`.
+  // However, this causes floating point inaccuracies in the number when subtracting, so it is
+  // better to keep it as an integer.
+  return Isaac.GetTime();
 }
 
 /**
@@ -41,16 +46,17 @@ export function enableDevFeatures(mod: ModUpgraded): void {
  * enabled.
  */
 export function getTraceback(): string {
+  if (SandboxGetTraceback !== undefined) {
+    return SandboxGetTraceback();
+  }
+
+  // "debug" will be equal to undefined if the "--luadebug" launch flag is not present.
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
   if (debug !== undefined) {
     // The --luadebug launch flag is enabled.
     return debug.traceback();
   }
 
-  if (SandboxGetTraceback !== undefined) {
-    return SandboxGetTraceback();
-  }
-
   return 'stack traceback:\n(the "--luadebug" flag is not enabled)';
 }
 
@@ -75,29 +81,6 @@ export function isLuaDebugEnabled(): boolean {
   return _G.package !== undefined;
 }
 
-/**
- * Converts every `isaacscript-common` function that begins with "log" to a global function.
- *
- * This is useful when printing out variables from the in-game debug console.
- */
-export function setLogFunctionsGlobal(): void {
-  const globals = _G as Record<string, unknown>;
-
-  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;
-    }
-  }
-}
-
-export function setTracebackFunctionsGlobal(): void {
-  const globals = _G as Record<string, unknown>;
-
-  globals["getTraceback"] = getTraceback;
-  globals["traceback"] = traceback;
-}
-
 /**
  * Helper function to print a stack trace to the "log.txt" file, similar to JavaScript's
  * `console.trace` function.

package/src/functions/dev.ts

@@ -0,0 +1,32 @@
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { enableExtraConsoleCommands } from "../features/extraConsoleCommands/exports";
+import { removeFadeIn } from "../features/fadeInRemover";
+import { enableFastReset } from "../features/fastReset";
+import { saveDataManagerSetGlobal } from "../features/saveDataManager/exports";
+import { setLogFunctionsGlobal, setTracebackFunctionsGlobal } from "./globals";
+
+/**
+ * Helper function to enable some IsaacScript features that are useful when developing a mod. They
+ * should not be enabled when your mod goes to production (i.e. when it is uploaded to the Steam
+ * Workshop).
+ *
+ * The list of development features that are enabled are as follows:
+ *
+ * - `saveDataManagerSetGlobal` - Sets your local variables registered with the save data manager as
+ *   global variables so you can access them from the in-game console.
+ * - `setLogFunctionsGlobal` - Sets the various log functions global so that you can access them
+ *   from the in-game console.
+ * - `enableExtraConsoleCommands` - Enables many extra in-game console commands that make warping
+ *   around easier (like e.g. `angel` to warp to the Angel Room).
+ * - `enableFastReset` - Makes it so that the r key resets the game instantaneously.
+ * - `removeFadeIn` - Removes the slow fade in that occurs at the beginning of the run, so that you
+ *   can immediately start playing or testing.
+ */
+export function enableDevFeatures(mod: ModUpgraded): void {
+  saveDataManagerSetGlobal();
+  setLogFunctionsGlobal();
+  setTracebackFunctionsGlobal();
+  enableExtraConsoleCommands(mod);
+  enableFastReset();
+  removeFadeIn();
+}

package/src/functions/globals.ts

@@ -1,5 +1,8 @@
-import { isLuaDebugEnabled } from "./debugFunctions";
+import { getTraceback, isLuaDebugEnabled, traceback } from "./debugFunctions";
+import * as logExports from "./log";
 import { log } from "./log";
+import * as logEntitiesExports from "./logEntities";
+import * as logMiscExports from "./logMisc";
 import { addSetsToSet, copySet } from "./set";
 import { twoDimensionalSort } from "./utils";
 
@@ -240,3 +243,26 @@ export function logNewGlobals(): void {
     log(`${i + 1}) ${key} - ${value}`);
   });
 }
+
+/**
+ * Converts every `isaacscript-common` function that begins with "log" to a global function.
+ *
+ * This is useful when printing out variables from the in-game debug console.
+ */
+export function setLogFunctionsGlobal(): void {
+  const globals = _G as Record<string, unknown>;
+
+  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;
+    }
+  }
+}
+
+export function setTracebackFunctionsGlobal(): void {
+  const globals = _G as Record<string, unknown>;
+
+  globals["getTraceback"] = getTraceback;
+  globals["traceback"] = traceback;
+}

package/src/functions/gridEntitiesSpecific.ts

@@ -43,10 +43,8 @@ export function getCrawlSpaces(
  *                   is -1, which matches every variant.
  */
 export function getPits(pitVariant: PitVariant = -1): GridEntityPit[] {
-  const gridEntities = getGridEntities();
-
   const pits: GridEntityPit[] = [];
-  for (const gridEntity of gridEntities) {
+  for (const gridEntity of getGridEntities()) {
     const pit = gridEntity.ToPit();
     if (pit !== undefined) {
       const gridEntityVariant = pit.GetVariant();
@@ -68,10 +66,8 @@ export function getPits(pitVariant: PitVariant = -1): GridEntityPit[] {
 export function getPoops(
   poopVariant: PoopGridEntityVariant = -1,
 ): GridEntityPoop[] {
-  const gridEntities = getGridEntities();
-
   const poops: GridEntityPoop[] = [];
-  for (const gridEntity of gridEntities) {
+  for (const gridEntity of getGridEntities()) {
     const poop = gridEntity.ToPoop();
     if (poop !== undefined) {
       const gridEntityVariant = poop.GetVariant();
@@ -93,10 +89,8 @@ export function getPoops(
 export function getPressurePlates(
   pressurePlateVariant: PressurePlateVariant = -1,
 ): GridEntityPressurePlate[] {
-  const gridEntities = getGridEntities();
-
   const pressurePlates: GridEntityPressurePlate[] = [];
-  for (const gridEntity of gridEntities) {
+  for (const gridEntity of getGridEntities()) {
     const pressurePlate = gridEntity.ToPressurePlate();
     if (pressurePlate !== undefined) {
       const gridEntityVariant = pressurePlate.GetVariant();
@@ -121,10 +115,8 @@ export function getPressurePlates(
  *                types of grid entities can be the `GridEntityRock` class.
  */
 export function getRocks(variant = -1): GridEntityRock[] {
-  const gridEntities = getGridEntities();
-
   const rocks: GridEntityRock[] = [];
-  for (const gridEntity of gridEntities) {
+  for (const gridEntity of getGridEntities()) {
     const rock = gridEntity.ToRock();
     if (rock !== undefined) {
       const gridEntityVariant = rock.GetVariant();
@@ -139,10 +131,8 @@ export function getRocks(variant = -1): GridEntityRock[] {
 
 /** Helper function to get all of the `GridEntitySpikes` in the room. */
 export function getSpikes(variant = -1): GridEntitySpikes[] {
-  const gridEntities = getGridEntities();
-
   const spikes: GridEntitySpikes[] = [];
-  for (const gridEntity of gridEntities) {
+  for (const gridEntity of getGridEntities()) {
     const spike = gridEntity.ToSpikes();
     if (spike !== undefined) {
       const gridEntityVariant = spike.GetVariant();
@@ -157,10 +147,8 @@ export function getSpikes(variant = -1): GridEntitySpikes[] {
 
 /** Helper function to get all of the `GridEntityTNT` in the room. */
 export function getTNT(variant = -1): GridEntityTNT[] {
-  const gridEntities = getGridEntities();
-
   const tntArray: GridEntityTNT[] = [];
-  for (const gridEntity of gridEntities) {
+  for (const gridEntity of getGridEntities()) {
     const tnt = gridEntity.ToTNT();
     if (tnt !== undefined) {
       const gridEntityVariant = tnt.GetVariant();

package/src/index.ts

@@ -68,6 +68,7 @@ export * from "./functions/curses";
 export * from "./functions/debugFunctions";
 export * from "./functions/deepCopy";
 export * from "./functions/deepCopyTests";
+export * from "./functions/dev";
 export * from "./functions/dimensions";
 export * from "./functions/direction";
 export * from "./functions/doors";