isaacscript-common 21.4.0 → 21.5.0

package/dist/src/types/{ModUpgraded.d.ts → private/ModUpgradedWithFeatures.d.ts}

@@ -1,10 +1,10 @@
-import { ModUpgradedBase } from "../classes/ModUpgradedBase";
-import { Feature } from "../classes/private/Feature";
-import { ISCFeature } from "../enums/ISCFeature";
-import { ISCFeatureToClass } from "../features";
-import { PublicInterface } from "./PublicInterface";
-import { TupleToIntersection } from "./TupleToIntersection";
-import { Writeable } from "./Writable";
+import { ModUpgraded } from "../../classes/ModUpgraded";
+import { Feature } from "../../classes/private/Feature";
+import { ISCFeature } from "../../enums/ISCFeature";
+import { ISCFeatureToClass } from "../../features";
+import { PublicInterface } from "../PublicInterface";
+import { TupleToIntersection } from "../TupleToIntersection";
+import { Writeable } from "../Writable";
 /**
  * `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
@@ -14,8 +14,12 @@ import { Writeable } from "./Writable";
  *
  * By specifying one or more optional features, end-users will get a version of `ModUpgraded` that
  * has extra methods corresponding to the features that were specified.
+ *
+ * This type is in the private directory because if it was exported, it would cause all of the
+ * internal feature classes to populate the auto-complete of end-user mods (which should never be
+ * directly imported by end-users).
  */
-export type ModUpgraded<T extends readonly ISCFeature[] = []> = ModUpgradedBase & ISCFeaturesToKeys<T>;
+export type ModUpgradedWithFeatures<T extends readonly ISCFeature[] = []> = ModUpgraded & ISCFeaturesToKeys<T>;
 /**
  * We want to only extract the class public methods, so we omit the keys of the `Feature` base
  * class.
@@ -29,4 +33,4 @@ type ISCFeatureTupleToClassTuple<T extends ISCFeature[]> = {
     [Key in keyof T]: PublicInterface<ISCFeatureToClass[T[Key]]>;
 };
 export {};
-//# sourceMappingURL=ModUpgraded.d.ts.map
+//# sourceMappingURL=ModUpgradedWithFeatures.d.ts.map

package/dist/src/types/private/ModUpgradedWithFeatures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModUpgradedWithFeatures.d.ts","sourceRoot":"","sources":["../../../../src/types/private/ModUpgradedWithFeatures.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,uBAAuB,CAAC,CAAC,SAAS,SAAS,UAAU,EAAE,GAAG,EAAE,IACtE,WAAW,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC;AAErC;;;GAGG;AACH,KAAK,iBAAiB,CAAC,CAAC,SAAS,SAAS,UAAU,EAAE,IAAI,IAAI,CAC5D,mBAAmB,CAAC,2BAA2B,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,EAC9D,MAAM,OAAO,CACd,CAAC;AAEF;;;GAGG;AACH,KAAK,2BAA2B,CAAC,CAAC,SAAS,UAAU,EAAE,IAAI;KACxD,GAAG,IAAI,MAAM,CAAC,GAAG,eAAe,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CAC7D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "21.4.0",
+  "version": "21.5.0",
   "description": "Helper functions and features for IsaacScript mods.",
   "keywords": [
     "isaac",

package/src/classes/ModFeature.ts

@@ -8,7 +8,7 @@ import {
 import { isFunction, isNumber, isTable } from "../functions/types";
 import { TSTLClassMetatable } from "../interfaces/TSTLClassMetatable";
 import { AnyFunction } from "../types/AnyFunction";
-import { ModUpgradedBase } from "./ModUpgradedBase";
+import { ModUpgraded } from "./ModUpgraded";
 
 export const MOD_FEATURE_CALLBACKS_KEY = "__callbacks";
 export const MOD_FEATURE_CUSTOM_CALLBACKS_KEY = "__customCallbacks";
@@ -62,7 +62,7 @@ type ModFeatureConstructor = TSTLClassMetatable["constructor"] & {
  */
 
 export class ModFeature {
-  private mod: ModUpgradedBase;
+  private mod: ModUpgraded;
 
   /**
    * An optional method that allows for conditional callback execution. If specified, any class
@@ -105,7 +105,7 @@ export class ModFeature {
    */
   public initialized = false;
 
-  constructor(mod: ModUpgradedBase, init = true) {
+  constructor(mod: ModUpgraded, init = true) {
     this.mod = mod;
 
     if (init) {
@@ -234,7 +234,7 @@ function initDecoratedCallbacks(
 function addCallback(
   modFeature: ModFeature,
   modFeatureConstructor: ModFeatureConstructor,
-  mod: ModUpgradedBase,
+  mod: ModUpgraded,
   modCallback: ModCallback | ModCallbackCustom,
   callback: Function, // eslint-disable-line @typescript-eslint/ban-types
   parameters: unknown[],
@@ -297,7 +297,7 @@ function addCallback(
 
 function removeCallback(
   modFeatureConstructor: ModFeatureConstructor,
-  mod: ModUpgradedBase,
+  mod: ModUpgraded,
   modCallback: ModCallback | ModCallbackCustom,
   vanilla: boolean,
 ) {

package/src/classes/{ModUpgradedBase.ts → ModUpgraded.ts}

@@ -24,10 +24,11 @@ import { Feature } from "./private/Feature";
  *
  * To upgrade your mod, use the `upgradeMod` helper function.
  *
- * `ModUpgradedBase` provides the core functionality of the `ModUpgraded` class. (It does not
- * include the methods for the individual ISC features.)
+ * By specifying one or more optional features when upgrading your mod, you will get a version of
+ * `ModUpgraded` that has extra methods corresponding to the features that were specified. (This
+ * corresponds to the internal-type `ModUpgradedWithFeatures` type, which extends `ModUpgraded`.)
  */
-export class ModUpgradedBase implements Mod {
+export class ModUpgraded implements Mod {
   // -----------------
   // Vanilla variables
   // -----------------
@@ -69,11 +70,6 @@ export class ModUpgradedBase implements Mod {
   // Vanilla methods
   // ---------------
 
-  /**
-   * Registers a function to be executed when an in-game event happens. For example, the
-   * `ModCallback.POST_UPDATE` event corresponds to being executed once at the end of every game
-   * logic frame.
-   */
   public AddCallback<T extends ModCallback | string>(
     modCallback: T,
     ...args: T extends ModCallback ? AddCallbackParameters[T] : unknown[]
@@ -141,25 +137,14 @@ export class ModUpgradedBase implements Mod {
     }
   }
 
-  /** Returns whether or not a corresponding "save#.dat" file exists for the current mod. */
   public HasData(): boolean {
     return this.mod.HasData();
   }
 
-  /**
-   * Returns a string containing all of the data inside of the corresponding "save#.dat" file for
-   * this mod.
-   */
   public LoadData(): string {
     return this.mod.LoadData();
   }
 
-  /**
-   * Unregisters a function that was previously registered with the `AddCallback` method.
-   *
-   * This method does not care about the tertiary argument. In other words, regardless of the
-   * conditions of how you registered the callback, it will be removed.
-   */
   public RemoveCallback<T extends ModCallback>(
     modCallback: T,
     callback: AddCallbackParameters[T][0],
@@ -167,14 +152,10 @@ export class ModUpgradedBase implements Mod {
     this.mod.RemoveCallback(modCallback, callback);
   }
 
-  /** Deletes the corresponding "save#.dat" file for this mod, if it exists. */
   public RemoveData(): void {
     this.mod.RemoveData();
   }
 
-  /**
-   * Creates or updates the corresponding "save#.dat" file for this mod with the provided string.
-   */
   public SaveData(data: string): void {
     this.mod.SaveData(data);
   }
@@ -184,23 +165,46 @@ export class ModUpgradedBase implements Mod {
   // ---------------------
 
   /**
-   * Registers a function to be executed when an in-game event happens. This method is specifically
-   * for events that are provided by the IsaacScript standard library. For example, the
-   * `ModCallbackCustom.POST_BOMB_EXPLODE` event corresponds to when a bomb explodes.
+   * Registers a function to be executed when an in-game event happens.
+   *
+   * This method is specifically for events that are provided by the IsaacScript standard library.
+   * For example, the `ModCallbackCustom.POST_BOMB_EXPLODE` event corresponds to when a bomb
+   * explodes.
    */
   public AddCallbackCustom<T extends ModCallbackCustom>(
     modCallbackCustom: T,
     ...args: AddCallbackParametersCustom[T]
+  ): void {
+    this.AddPriorityCallbackCustom(
+      modCallbackCustom,
+      CallbackPriority.DEFAULT,
+      ...args,
+    );
+  }
+
+  /**
+   * The same as the `ModUpgraded.AddCallbackCustom` method, but allows setting a custom priority.
+   * By default, callbacks are added with a priority of 0, so this allows you to add early or late
+   * callbacks as necessary. See the `CallbackPriority` enum.
+   */
+  public AddPriorityCallbackCustom<T extends ModCallbackCustom>(
+    modCallbackCustom: T,
+    priority: CallbackPriority | int,
+    ...args: AddCallbackParametersCustom[T]
   ): void {
     const callbackClass = this.callbacks[modCallbackCustom];
     // @ts-expect-error The compiler is not smart enough to figure out that the parameters match.
-    callbackClass.addSubscriber(...args);
+    callbackClass.addSubscriber(priority, ...args);
     this.initFeature(callbackClass);
   }
 
   /**
    * Unregisters a function that was previously registered with the `AddCallbackCustom` method.
    *
+   * This method is specifically for events that are provided by the IsaacScript standard library.
+   * For example, the `ModCallbackCustom.POST_BOMB_EXPLODE` event corresponds to when a bomb
+   * explodes.
+   *
    * This method does not care about the tertiary argument. In other words, regardless of the
    * conditions of how you registered the callback, it will be removed.
    */
@@ -294,8 +298,9 @@ export class ModUpgradedBase implements Mod {
       for (const callbackTuple of feature.callbacksUsed) {
         const [modCallback, callbackFunc, optionalArgs] = callbackTuple;
         // TypeScript is not smart enough to know that the arguments match the function.
-        (this.AddCallback as AnyFunction)(
+        (this.AddPriorityCallback as AnyFunction)(
           modCallback,
+          CallbackPriority.IMPORTANT,
           callbackFunc,
           ...(optionalArgs ?? []),
         );
@@ -398,15 +403,6 @@ export class ModUpgradedBase implements Mod {
 
     return getExportedMethodsFromFeature(featureClass);
   }
-
-  /**
-   * This is mostly the same as the `AddCustomCallback` method, but we initialize the custom
-   * callback without actually registering a subscription.
-   */
-  private initCustomCallbackEarly(modCallbackCustom: ModCallbackCustom) {
-    const callbackClass = this.callbacks[modCallbackCustom];
-    this.initFeature(callbackClass);
-  }
 }
 
 /**

package/src/classes/features/other/DebugDisplay.ts

@@ -1,5 +1,5 @@
 import { Exported } from "../../../decorators";
-import { printEnabled } from "../../../functions/utils";
+import { printEnabled } from "../../../functions/console";
 import { ModUpgradedInterface } from "../../../interfaces/private/ModUpgradedInterface";
 import { Feature } from "../../private/Feature";
 import { DebugDisplayBomb } from "./debugDisplay/DebugDisplayBomb";

package/src/classes/features/other/ExtraConsoleCommands.ts

@@ -8,9 +8,9 @@ import {
 } from "isaac-typescript-definitions";
 import { Exported } from "../../../decorators";
 import { ModCallbackCustom } from "../../../enums/ModCallbackCustom";
+import { isVanillaConsoleCommand } from "../../../functions/console";
 import { addFlag, bitFlags } from "../../../functions/flag";
 import { getMapPartialMatch } from "../../../functions/map";
-import { isVanillaConsoleCommand } from "../../../functions/utils";
 import { Feature } from "../../private/Feature";
 import * as commands from "./extraConsoleCommands/commands";
 import { v } from "./extraConsoleCommands/v";

package/src/classes/features/other/extraConsoleCommands/commands.ts

@@ -75,6 +75,7 @@ import { getCardName } from "../../../../functions/cards";
 import { getCharacterName } from "../../../../functions/characters";
 import { addCharge, getTotalCharge } from "../../../../functions/charge";
 import { isValidCollectibleType } from "../../../../functions/collectibles";
+import { printEnabled } from "../../../../functions/console";
 import { runDeepCopyTests } from "../../../../functions/deepCopyTests";
 import { getNPCs } from "../../../../functions/entitiesSpecific";
 import { addFlag } from "../../../../functions/flag";
@@ -114,7 +115,7 @@ import {
   asCollectibleType,
   asTrinketType,
 } from "../../../../functions/types";
-import { iRange, printEnabled } from "../../../../functions/utils";
+import { iRange } from "../../../../functions/utils";
 import { CARD_NAME_TO_TYPE_MAP } from "../../../../maps/cardNameToTypeMap";
 import { CHARACTER_NAME_TO_TYPE_MAP } from "../../../../maps/characterNameToTypeMap";
 import { COLLECTIBLE_NAME_TO_TYPE_MAP } from "../../../../maps/collectibleNameToTypeMap";

package/src/classes/private/CustomCallback.ts

@@ -1,4 +1,6 @@
+import { CallbackPriority } from "isaac-typescript-definitions/dist/src/enums/CallbackPriority";
 import { ModCallbackCustom } from "../../enums/ModCallbackCustom";
+import { sortObjectArrayByKey } from "../../functions/sort";
 import { AddCallbackParametersCustom } from "../../interfaces/private/AddCallbackParametersCustom";
 import { AllButFirst } from "../../types/AllButFirst";
 import { AnyFunction } from "../../types/AnyFunction";
@@ -7,14 +9,16 @@ import { Feature } from "./Feature";
 export type FireArgs<T extends ModCallbackCustom> = Parameters<
   AddCallbackParametersCustom[T][0]
 >;
+
 export type OptionalArgs<T extends ModCallbackCustom> = AllButFirst<
   AddCallbackParametersCustom[T]
 >;
 
-type Subscription<T extends ModCallbackCustom> = [
-  callbackFunc: AddCallbackParametersCustom[T][0],
-  optionalArgs: AllButFirst<AddCallbackParametersCustom[T]>,
-];
+interface Subscription<T extends ModCallbackCustom> {
+  priority: CallbackPriority | int;
+  callbackFunc: AddCallbackParametersCustom[T][0];
+  optionalArgs: AllButFirst<AddCallbackParametersCustom[T]>;
+}
 
 /**
  * The base class for a custom callback. Individual custom callbacks (and validation callbacks) will
@@ -26,11 +30,17 @@ export abstract class CustomCallback<
   private subscriptions: Array<Subscription<T>> = [];
 
   public addSubscriber(
+    priority: CallbackPriority | int,
     callbackFunc: AddCallbackParametersCustom[T][0],
     ...optionalArgs: AllButFirst<AddCallbackParametersCustom[T]>
   ): void {
-    const subscription: Subscription<T> = [callbackFunc, optionalArgs];
+    const subscription: Subscription<T> = {
+      priority,
+      callbackFunc,
+      optionalArgs,
+    };
     this.subscriptions.push(subscription);
+    this.subscriptions.sort(sortObjectArrayByKey("priority"));
   }
 
   /**
@@ -40,7 +50,7 @@ export abstract class CustomCallback<
   public removeSubscriber(callback: AddCallbackParametersCustom[T][0]): void {
     const subscriptionIndexMatchingCallback = this.subscriptions.findIndex(
       (subscription) => {
-        const subscriptionCallback = subscription[0];
+        const subscriptionCallback = subscription.callbackFunc;
         return callback === subscriptionCallback;
       },
     );
@@ -53,7 +63,7 @@ export abstract class CustomCallback<
     ...fireArgs: FireArgs<T>
   ): ReturnType<AddCallbackParametersCustom[T][0]> => {
     for (const subscription of this.subscriptions) {
-      const [callbackFunc, optionalArgs] = subscription;
+      const { callbackFunc, optionalArgs } = subscription;
 
       if (this.shouldFire(fireArgs, optionalArgs)) {
         // TypeScript is not smart enough to know that the arguments match the function.

package/src/core/upgradeMod.ts

@@ -1,10 +1,9 @@
-import { ModUpgradedBase } from "../classes/ModUpgradedBase";
+import { ModUpgraded } from "../classes/ModUpgraded";
 import { ISCFeature } from "../enums/ISCFeature";
-import { ModCallbackCustom } from "../enums/ModCallbackCustom";
 import { patchErrorFunction } from "../patchErrorFunctions";
 import { applyShaderCrashFix } from "../shaderCrashFix";
 import { AnyFunction } from "../types/AnyFunction";
-import { ModUpgraded } from "../types/ModUpgraded";
+import { ModUpgradedWithFeatures } from "../types/private/ModUpgradedWithFeatures";
 
 type ISCFeatureTuple<T extends readonly ISCFeature[]> =
   ISCFeature extends T["length"]
@@ -31,28 +30,68 @@ type ISCFeatureTuple<T extends readonly ISCFeature[]> =
  * @param modVanilla The mod object returned by the `RegisterMod` function.
  * @param features Optional. An array containing the optional standard library features that you
  *                 want to enable, if any. Default is an empty array.
- * @param customCallbacksUsed Optional. An array containing the custom callbacks that you will be
- *                            subscribing to after you upgrade your mod. Specifying this will
- *                            immediately initialize the callbacks (as opposed to lazy-initializing
- *                            them when you first subscribe to the callback). This is only necessary
- *                            if you the order of callback firing is important for your mod. (For
- *                            example, you may want the `POST_NEW_ROOM` part of the
- *                            `POST_GRID_ENTITY_INIT` callback to fire before your own
- *                            `POST_NEW_ROOM` callbacks.)
  * @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 (if the "--luadebug" launch flag is turned on)
  *                      or milliseconds (if the "--luadebug" launch flag is turned off).
  * @returns The upgraded mod object.
+ * @notExported
+ * @rename upgradeMod
  */
+// We duplicate the definition for `upgradeMod` because the original one has to be marked internal.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function upgradeModDocumentation(
+  modVanilla: Mod,
+  features: ISCFeature[] = [],
+  debug = false,
+  timeThreshold?: float,
+): ModUpgraded {
+  print(modVanilla);
+  print(features);
+  print(debug);
+  print(timeThreshold);
+
+  const mod = RegisterMod("", 1);
+  return new ModUpgraded(mod, false);
+}
+
+/**
+ * Use this function to enable the custom callbacks and other optional features provided by
+ * `isaacscript-common`.
+ *
+ * For example:
+ *
+ * ```ts
+ * const modVanilla = RegisterMod("My Mod", 1);
+ * const mod = upgradeMod(modVanilla);
+ *
+ * // Subscribe to vanilla callbacks.
+ * mod.AddCallback(ModCallback.POST_UPDATE, postUpdate);
+ *
+ * // Subscribe to custom callbacks.
+ * mod.AddCallbackCustom(ModCallbackCustom.POST_ITEM_PICKUP, postItemPickup);
+ * ```
+ *
+ * @param modVanilla The mod object returned by the `RegisterMod` function.
+ * @param features Optional. An array containing the optional standard library features that you
+ *                 want to enable, if any. Default is an empty array.
+ * @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 (if the "--luadebug" launch flag is turned on)
+ *                      or milliseconds (if the "--luadebug" launch flag is turned off).
+ * @returns The upgraded mod object.
+ * @internal
+ */
+// This has to be marked internal or else it will cause all of the feature classes to be included in
+// the output of `api-extractor`.
 export function upgradeMod<T extends readonly ISCFeature[] = never[]>(
   modVanilla: Mod,
   features: ISCFeatureTuple<T> = [] as unknown as ISCFeatureTuple<T>,
-  customCallbacksUsed: ModCallbackCustom[] | readonly ModCallbackCustom[] = [],
   debug = false,
   timeThreshold?: float,
-): ModUpgraded<T> {
+): ModUpgradedWithFeatures<T> {
   // First, validate that all of the features exist (for Lua users who don't have type-safety).
   for (const feature of features) {
     const featureType = type(feature);
@@ -65,16 +104,15 @@ export function upgradeMod<T extends readonly ISCFeature[] = never[]>(
 
   patchErrorFunction();
 
-  const mod = new ModUpgradedBase(modVanilla, debug, timeThreshold);
+  const mod = new ModUpgraded(modVanilla, debug, timeThreshold);
   applyShaderCrashFix(mod);
   initOptionalFeatures(mod, features as ISCFeature[]);
-  initCallbacksEarly(mod, customCallbacksUsed);
 
-  return mod as ModUpgraded<T>;
+  return mod as ModUpgradedWithFeatures<T>;
 }
 
 /** Initialize every optional feature that the end-user specified. */
-function initOptionalFeatures(mod: ModUpgradedBase, features: ISCFeature[]) {
+function initOptionalFeatures(mod: ModUpgraded, features: ISCFeature[]) {
   for (const feature of features) {
     // We intentionally access the private method here, so we use the string index escape hatch:
     // https://github.com/microsoft/TypeScript/issues/19335
@@ -89,15 +127,3 @@ function initOptionalFeatures(mod: ModUpgradedBase, features: ISCFeature[]) {
     }
   }
 }
-
-function initCallbacksEarly(
-  mod: ModUpgradedBase,
-  callbacks: ModCallbackCustom[] | readonly ModCallbackCustom[],
-) {
-  for (const modCallbackCustom of callbacks) {
-    // We intentionally access the private method here, so we use the string index escape hatch:
-    // https://github.com/microsoft/TypeScript/issues/19335
-    // eslint-disable-next-line @typescript-eslint/dot-notation
-    mod["initCustomCallbackEarly"](modCallbackCustom);
-  }
-}

package/src/features.ts

@@ -56,7 +56,7 @@ import { TaintedLazarusPlayers } from "./classes/features/other/TaintedLazarusPl
 import { Feature } from "./classes/private/Feature";
 import { ISCFeature } from "./enums/ISCFeature";
 import { ModCallbackCustom } from "./enums/ModCallbackCustom";
-import { validateInterfaceMatchesEnum } from "./functions/utils";
+import { validateInterfaceMatchesEnum } from "./functions/enums";
 import { ModUpgradedInterface } from "./interfaces/private/ModUpgradedInterface";
 
 export interface ISCFeatureToClass {

package/src/functions/console.ts

@@ -0,0 +1,15 @@
+import { CONSOLE_COMMANDS_SET } from "../sets/consoleCommandsSet";
+
+/**
+ * Helper function to see if a particular command is a vanilla console command. This is useful
+ * because the `EXECUTE_CMD` callback will not fire for any vanilla commands.
+ */
+export function isVanillaConsoleCommand(commandName: string): boolean {
+  return CONSOLE_COMMANDS_SET.has(commandName);
+}
+
+/** Helper function to print whether something was enabled or disabled to the in-game console. */
+export function printEnabled(enabled: boolean, description: string): void {
+  const enabledText = enabled ? "Enabled" : "Disabled";
+  print(`${enabledText} ${description}.`);
+}

package/src/functions/deepCopy.ts

@@ -15,6 +15,7 @@ import {
   isSerializedIsaacAPIClass,
   serializeIsaacAPIClass,
 } from "./serialization";
+import { sortTwoDimensionalArray } from "./sort";
 import {
   getTSTLClassName,
   isDefaultMap,
@@ -23,7 +24,7 @@ import {
   newTSTLClass,
 } from "./tstlClass";
 import { asString, isNumber, isPrimitive } from "./types";
-import { getTraversalDescription, twoDimensionalSort } from "./utils";
+import { getTraversalDescription } from "./utils";
 
 /**
  * `deepCopy` is a semi-generic deep cloner. It will recursively copy all of the values so that none
@@ -642,7 +643,7 @@ function getCopiedEntries(
   }
 
   if (SAVE_DATA_MANAGER_DEBUG) {
-    entries.sort(twoDimensionalSort);
+    entries.sort(sortTwoDimensionalArray);
   }
 
   // During serialization, we brand some Lua tables with a special identifier to signify that it has

package/src/functions/enums.ts

@@ -186,3 +186,36 @@ export function validateEnumContiguous<T>(
     }
   }
 }
+
+/**
+ * Helper function to validate that an interface contains all of the keys of an enum. You must
+ * specify both generic parameters in order for this to work properly (i.e. the interface and then
+ * the enum).
+ *
+ * For example:
+ *
+ * ```ts
+ * enum MyEnum {
+ *   Value1,
+ *   Value2,
+ *   Value3,
+ * }
+ *
+ * interface MyEnumToType {
+ *   [MyEnum.Value1]: boolean;
+ *   [MyEnum.Value2]: number;
+ *   [MyEnum.Value3]: string;
+ * }
+ *
+ * validateInterfaceMatchesEnum<MyEnumToType, MyEnum>();
+ * ```
+ *
+ * This function is only meant to be used with interfaces (i.e. types that will not exist at
+ * run-time). If you are generating an object that will contain all of the keys of an enum, use the
+ * `satisfies` operator with the `Record` type instead.
+ */
+export function validateInterfaceMatchesEnum<
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  T extends Record<Enum, unknown>,
+  Enum extends string | number,
+>(): void {}

package/src/functions/globals.ts

@@ -5,7 +5,7 @@ import { log } from "./log";
 import * as logEntitiesExports from "./logEntities";
 import * as logMiscExports from "./logMisc";
 import { addSetsToSet, copySet } from "./set";
-import { twoDimensionalSort } from "./utils";
+import { sortTwoDimensionalArray } from "./sort";
 
 const DEFAULT_GLOBALS = new ReadonlySet<string>([
   "ActionTriggers",
@@ -226,7 +226,7 @@ export function getNewGlobals(): ReadonlyArray<[AnyNotNil, unknown]> {
     }
   }
 
-  newGlobals.sort(twoDimensionalSort);
+  newGlobals.sort(sortTwoDimensionalArray);
 
   return newGlobals;
 }

package/src/functions/log.ts

@@ -65,3 +65,12 @@ export function log(
       : `${parentFunctionDescription} - ${msg}`;
   Isaac.DebugString(debugMsg);
 }
+
+/**
+ * Helper function to log a message to the "log.txt" file and to print it to the screen at the same
+ * time.
+ */
+export function logAndPrint(msg: string): void {
+  log(msg);
+  print(msg);
+}

package/src/functions/mergeTests.ts

@@ -1,10 +1,10 @@
 import { DefaultMap } from "../classes/DefaultMap";
 import { SerializationType } from "../enums/SerializationType";
 import { deepCopy } from "./deepCopy";
+import { logAndPrint } from "./log";
 import { merge } from "./merge";
 import { isRNG, newRNG } from "./rng";
 import { isSerializedIsaacAPIClass } from "./serialization";
-import { logAndPrint } from "./utils";
 import { isVector, serializeVector } from "./vector";
 
 /**

package/src/functions/modFeatures.ts

@@ -1,5 +1,5 @@
 import { ModFeature } from "../classes/ModFeature";
-import { ModUpgraded } from "../types/ModUpgraded";
+import { ModUpgraded } from "../classes/ModUpgraded";
 
 /**
  * Helper function to instantiate an array of mod features all at once. Use this function if your