isaacscript-common 14.1.2 → 14.2.0

package/src/enums/ModCallbackCustom.ts

@@ -794,9 +794,11 @@ export enum ModCallbackCustom {
    * This callback is useful because many attributes cannot be set or retrieved properly in the
    * normal `POST_NPC_INIT` callback.
    *
-   * When registering the callback with the `ModUpgraded.AddCallbackCustom` method, you can provide
-   * an optional third argument that will make the callback only fire if it matches the `EntityType`
-   * provided.
+   * When registering the callback with the `ModUpgraded.AddCallbackCustom` method:
+   * - You can provide an optional third argument that will make the callback only fire if it
+   *   matches the `EntityType` provided.
+   * - You can provide an optional fourth argument that will make the callback only fire if it
+   *   matches the variant provided.
    *
    * ```ts
    * function postNPCInitLate(npc: EntityNPC): void {}
@@ -855,9 +857,11 @@ export enum ModCallbackCustom {
    *
    * Use this callback to know when a pickup is added to the player's inventory or health.
    *
-   * When registering the callback with the `ModUpgraded.AddCallbackCustom` method, you can provide
-   * an optional third argument that will make the callback only fire if it matches the
-   * `PickupVariant` provided.
+   * When registering the callback with the `ModUpgraded.AddCallbackCustom` method:
+   * - You can provide an optional third argument that will make the callback only fire if it
+   *   matches the `PickupVariant` provided.
+   * - You can provide an optional fourth argument that will make the callback only fire if it
+   *   matches the sub-type provided.
    *
    * ```ts
    * function postPickupCollect(pickup: EntityPickup, player: EntityPlayer): void {}
@@ -872,9 +876,11 @@ export enum ModCallbackCustom {
    * This callback is useful because pickups will despawn upon leaving the room and respawn upon
    * re-entering the room.
    *
-   * When registering the callback with the `ModUpgraded.AddCallbackCustom` method, you can provide
-   * an optional third argument that will make the callback only fire if it matches the
-   * `PickupVariant` provided.
+   * When registering the callback with the `ModUpgraded.AddCallbackCustom` method:
+   * - You can provide an optional third argument that will make the callback only fire if it
+   *   matches the `PickupVariant` provided.
+   * - You can provide an optional fourth argument that will make the callback only fire if it
+   *   matches the sub-type provided.
    *
    * ```ts
    * function postPickupInitFirst(pickup: EntityPickup): void {}
@@ -888,9 +894,11 @@ export enum ModCallbackCustom {
    * This callback is useful because many attributes cannot be set or retrieved properly in the
    * normal `POST_PICKUP_INIT` callback.
    *
-   * When registering the callback with the `ModUpgraded.AddCallbackCustom` method, you can provide
-   * an optional third argument that will make the callback only fire if it matches the
-   * `PickupVariant` provided.
+   * When registering the callback with the `ModUpgraded.AddCallbackCustom` method:
+   * - You can provide an optional third argument that will make the callback only fire if it
+   *   matches the `PickupVariant` provided.
+   * - You can provide an optional fourth argument that will make the callback only fire if it
+   *   matches the sub-type provided.
    *
    * ```ts
    * function postPickupInitLate(pickup: EntityPickup): void {}
@@ -902,9 +910,11 @@ export enum ModCallbackCustom {
    * Fires from the `POST_PICKUP_UPDATE` callback when a pickup's state has changed from what it was
    * on the previous frame. (In this context, "state" refers to the `EntityPickup.State` field.)
    *
-   * When registering the callback with the `ModUpgraded.AddCallbackCustom` method, you can provide
-   * an optional third argument that will make the callback only fire if it matches the
-   * `PickupVariant` provided.
+   * When registering the callback with the `ModUpgraded.AddCallbackCustom` method:
+   * - You can provide an optional third argument that will make the callback only fire if it
+   *   matches the `PickupVariant` provided.
+   * - You can provide an optional fourth argument that will make the callback only fire if it
+   *   matches the sub-type provided.
    *
    * ```ts
    * function postPickupStateChanged(
@@ -984,13 +994,13 @@ export enum ModCallbackCustom {
    *   matches the `PlayerType` provided.
    *
    * ```ts
-   * function postPlayerChangeStat(
+   * function postPlayerChangeStat<T extends StatType>(
    *   player: EntityPlayer,
-   *   statType: StatType,
+   *   statType: T,
    *   difference: int,
-   *   oldValue: number | boolean | BitFlags<TearFlag> | Color | Vector,
-   *   newValue: number | boolean | BitFlags<TearFlag> | Color | Vector,
-   * ): void {}
+   *   oldValue: StatTypeType[T],
+   *   newValue: StatTypeType[T],
+   * ) => void {}
    * ```
    */
   POST_PLAYER_CHANGE_STAT,
@@ -1282,6 +1292,10 @@ export enum ModCallbackCustom {
    * Fires from the `POST_UPDATE` callback when the clear state of a room changes (as according to
    * the `Room.IsClear` method).
    *
+   * For example, this callback fires when you defeat all the enemies in a room (clear --> not
+   * clear) or when you bomb an angel statue (not clear --> clear). This callback does not fire when
+   * you travel between a cleared room and an uncleared room.
+   *
    * When registering the callback with the `ModUpgraded.AddCallbackCustom` method, you can provide
    * an optional third argument that will make the callback only fire if the room clear state
    * matches the boolean provided.

package/src/enums/ModCallbackCustom2.ts

@@ -1,3 +1,12 @@
+/*
+eslint isaacscript/member-ordering: ["warn", {
+  enums: {
+    memberTypes: ["method", "field"],
+    order: "alphabetically"
+  },
+}]
+*/
+
 /** TODO */
 export enum ModCallbackCustom2 {
   POST_AMBUSH_FINISHED,
@@ -29,29 +38,68 @@ export enum ModCallbackCustom2 {
   POST_GRID_ENTITY_CUSTOM_COLLISION,
   POST_GRID_ENTITY_CUSTOM_INIT,
   POST_GRID_ENTITY_CUSTOM_REMOVE,
-  // POST_GRID_ENTITY_CUSTOM_RENDER,
+  POST_GRID_ENTITY_CUSTOM_RENDER,
   POST_GRID_ENTITY_CUSTOM_STATE_CHANGED,
   POST_GRID_ENTITY_CUSTOM_UPDATE,
   POST_GRID_ENTITY_INIT,
   POST_GRID_ENTITY_REMOVE,
-  // POST_GRID_ENTITY_RENDER,
+  POST_GRID_ENTITY_RENDER,
   POST_GRID_ENTITY_STATE_CHANGED,
   POST_GRID_ENTITY_UPDATE,
   POST_HOLY_MANTLE_REMOVED,
-
-  // ---------------------
-
+  POST_ITEM_DISCHARGE,
+  POST_ITEM_PICKUP,
   POST_KNIFE_INIT_LATE,
+  POST_LASER_INIT_LATE,
   POST_NEW_LEVEL_REORDERED,
   POST_NEW_ROOM_EARLY,
   POST_NEW_ROOM_REORDERED,
+  POST_NPC_INIT_LATE,
+  POST_NPC_STATE_CHANGED,
   POST_PEFFECT_UPDATE_REORDERED,
+  POST_PICKUP_COLLECT,
+  POST_PICKUP_INIT_FIRST,
+  POST_PICKUP_INIT_LATE,
+  POST_PICKUP_STATE_CHANGED,
   POST_PIT_RENDER,
+  POST_PIT_UPDATE,
+  POST_PLAYER_CHANGE_HEALTH,
+  POST_PLAYER_CHANGE_STAT,
+  POST_PLAYER_CHANGE_TYPE,
+  POST_PLAYER_COLLECTIBLE_ADDED,
+  POST_PLAYER_COLLECTIBLE_REMOVED,
   POST_PLAYER_FATAL_DAMAGE,
+  POST_PLAYER_INIT_FIRST,
+  POST_PLAYER_INIT_LATE,
   POST_PLAYER_RENDER_REORDERED,
   POST_PLAYER_UPDATE_REORDERED,
+  POST_POOP_RENDER,
+  POST_POOP_UPDATE,
+  POST_PRESSURE_PLATE_RENDER,
+  POST_PRESSURE_PLATE_UPDATE,
+  POST_PROJECTILE_INIT_LATE,
+  POST_PURCHASE,
+  POST_ROCK_RENDER,
+  POST_ROCK_UPDATE,
   POST_ROOM_CLEAR_CHANGED,
+  POST_SACRIFICE,
+  POST_SLOT_ANIMATION_CHANGED,
+  POST_SLOT_COLLISION,
+  POST_SLOT_DESTROYED,
+  POST_SLOT_INIT,
+  POST_SLOT_RENDER,
+  POST_SLOT_UPDATE,
   POST_SPIKES_RENDER,
+  POST_SPIKES_UPDATE,
+  POST_TEAR_INIT_LATE,
+  POST_TEAR_INIT_VERY_LATE,
+  POST_TNT_RENDER,
+  POST_TNT_UPDATE,
+  POST_TRANSFORMATION,
+
+  // ---------------------
+
   PRE_BERSERK_DEATH,
   PRE_CUSTOM_REVIVE,
+  PRE_ITEM_PICKUP,
 }

package/src/enums/{private/SerializationBrand.ts → SerializationBrand.ts}

@@ -6,12 +6,12 @@
  * constructor during deserialization.
  */
 export enum SerializationBrand {
-  // Specific TSTL class brands:
+  // Specific TSTL class brands.
   DEFAULT_MAP = "__TSTL_DEFAULT_MAP",
   MAP = "__TSTL_MAP",
   SET = "__TSTL_SET",
 
-  // Specific Isaac API class brands:
+  // Specific Isaac API class brands.
   BIT_SET_128 = "__BIT_SET_128",
   COLOR = "__COLOR",
   K_COLOR = "__K_COLOR",
@@ -36,4 +36,10 @@ export enum SerializationBrand {
    * to keep track of the mutation.
    */
   OBJECT_WITH_NUMBER_KEYS = "__TSTL_OBJECT_WITH_NUMBER_KEYS",
+
+  /**
+   * This brand represents a user-defined class other than a `DefaultMap`, `Map`, or `Set`. It will
+   * have a string value that corresponds to the name of the class.
+   */
+  TSTL_CLASS = "__TSTL_CLASS",
 }

package/src/features/customItemPool.ts

@@ -0,0 +1,133 @@
+import { CollectibleType, ItemPoolType } from "isaac-typescript-definitions";
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import { arrayRemoveIndexInPlace } from "../functions/array";
+import { copyMap } from "../functions/map";
+import { getRandomSeed } from "../functions/rng";
+import { getRandomIndexFromWeightedArray } from "../functions/weighted";
+import { WeightedArray } from "../types/WeightedArray";
+import { saveDataManager } from "./saveDataManager/exports";
+
+const FEATURE_NAME = "customItemPool";
+
+const customItemPoolMap = new Map<
+  ItemPoolType,
+  WeightedArray<CollectibleType>
+>();
+
+const v = {
+  run: {
+    customItemPools: new Map<ItemPoolType, WeightedArray<CollectibleType>>(),
+  },
+};
+
+/** @internal */
+export function customItemPoolsInit(mod: ModUpgraded): void {
+  saveDataManager(FEATURE_NAME, v);
+
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_GAME_STARTED_REORDERED,
+    postGameStartedReordered,
+  ); // 20
+}
+
+// ModCallbackCustom.POST_GAME_STARTED_REORDERED
+function postGameStartedReordered(isContinued: boolean) {
+  if (isContinued) {
+    return;
+  }
+
+  v.run.customItemPools = copyMap(customItemPoolMap);
+}
+
+/**
+ * Helper function to register a custom item pool. Use this function once when your mod first loads
+ * to declare the items that you want to be in the item pools. Then, in the middle of a run, you can
+ * use `getCustomItemPoolCollectible`.
+ *
+ * For example:
+ *
+ * ```ts
+ * const ItemPoolTypeCustom = {
+ *   FOO = 0 as ItemPoolType,
+ * } as const;
+ *
+ * const FOO_ITEM_POOL = [
+ *   [CollectibleType.SAD_ONION, 1],
+ *   [CollectibleType.INNER_EYE, 0.5],
+ * ];
+ *
+ * registerCustomItemPool(ItemPoolTypeCustom.FOO, FOO_ITEM_POOL);
+ * ```
+ *
+ * Note that custom item pools do not currently support partial weight decrementation on sight.
+ *
+ * @param itemPoolTypeCustom An integer that identifies what kind of item pool you are creating. It
+ *                           should correspond to a local enum value created in your mod. The
+ *                           integer can be any unique value and can safely overlap with the vanilla
+ *                           item pool type values.
+ * @param collectibles An array of weighted collectible tuples that represent the item pool that you
+ *                     are creating. The first element in he tuple is the `CollectibleType`, and the
+ *                     second element in the tuple is the float that represents the weight of the
+ *                     collectible.
+ */
+export function registerCustomItemPool(
+  itemPoolTypeCustom: ItemPoolType,
+  collectibles: WeightedArray<CollectibleType>,
+): void {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  if (customItemPoolMap.has(itemPoolTypeCustom)) {
+    error(
+      `Failed to register a custom item pool since the provided type of ${itemPoolTypeCustom} was already registered.`,
+    );
+  }
+
+  customItemPoolMap.set(itemPoolTypeCustom, collectibles);
+}
+
+/**
+ * Helper function to get a new collectible from a custom item pool created with the
+ * `registerCustomItemPool` function. This function has the same format as the
+ * `ItemPool.GetCollectible` method.
+ *
+ * By default, a collectible will not be removed from the pool once it is selected, unless the
+ * `decrease` argument is set to true (similar to how a vanilla item pool works).
+ *
+ * @param itemPoolTypeCustom An integer representing the custom item pool to use.
+ * @param decrease Optional. Whether or not to remove the selected collectible from the item pool.
+ *                 Default is true.
+ * @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. Default is `getRandomSeed()`.
+ * @param defaultItem Optional. The collectible to return if the item pool is depleted. Default is
+ *                    `CollectibleType.NULL`.
+ */
+export function getCustomItemPoolCollectible(
+  itemPoolTypeCustom: ItemPoolType,
+  decrease = false,
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+  defaultItem = CollectibleType.NULL,
+): CollectibleType {
+  const customItemPool = v.run.customItemPools.get(itemPoolTypeCustom);
+  if (customItemPool === undefined) {
+    error(`Failed to find the custom item pool of: ${itemPoolTypeCustom}`);
+  }
+
+  if (customItemPool.length === 0) {
+    return defaultItem;
+  }
+
+  const randomIndex = getRandomIndexFromWeightedArray(
+    customItemPool,
+    seedOrRNG,
+  );
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const tuple = customItemPool[randomIndex]!;
+
+  if (decrease) {
+    arrayRemoveIndexInPlace(customItemPool, randomIndex);
+  }
+
+  return tuple[0];
+}

package/src/features/deployJSONRoom.ts

@@ -221,8 +221,9 @@ function respawnPersistentEntities() {
  * Specifically, this will clear the current room of all entities and grid entities, and then spawn
  * all of the entries and grid entities in the provided JSON room.
  *
- * You can create JSON rooms by using the `convert-xml-to-json` tool (e.g. `npx convert-xml-to-json
- * my-rooms.xml`).
+ * A JSON room is simply an XML file converted to JSON. You can create JSON rooms by using the
+ * Basement Renovator room editor to create an XML file, and then convert it to JSON using the
+ * `convert-xml-to-json` tool (e.g. `npx convert-xml-to-json my-rooms.xml`).
  *
  * This function is meant to be used in the `POST_NEW_ROOM` callback.
  *
@@ -283,8 +284,9 @@ export function deployJSONRoom(
  * Specifically, this will clear the current room of all entities and grid entities, and then spawn
  * all of the entries and grid entities in one of the provided JSON rooms.
  *
- * You can create JSON rooms by using the `convert-xml-to-json` tool (e.g. `npx convert-xml-to-json
- * my-rooms.xml`).
+ * A JSON room is simply an XML file converted to JSON. You can create JSON rooms by using the
+ * Basement Renovator room editor to create an XML file, and then convert it to JSON using the
+ * `convert-xml-to-json` tool (e.g. `npx convert-xml-to-json my-rooms.xml`).
  *
  * This function is meant to be used in the `POST_NEW_ROOM` callback.
  *

package/src/features/fadeInRemover.ts

@@ -1,42 +1,24 @@
 import { ModCallback } from "isaac-typescript-definitions";
 import { game } from "../core/cachedClasses";
 import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
-import { saveDataManager } from "./saveDataManager/exports";
 
 const FEATURE_NAME = "fadeInRemover";
 const FADE_IN_SPEED = 1;
 
 let enabled = false;
 
-const v = {
-  run: {
-    removedFadeIn: false,
-  },
-};
-
 /** @internal */
 export function fadeInRemoverInit(mod: Mod): void {
-  saveDataManager(FEATURE_NAME, v, false);
-
-  mod.AddCallback(ModCallback.POST_RENDER, postRender); // 2
+  mod.AddCallback(ModCallback.POST_GAME_STARTED, postGameStarted); // 15
 }
 
-function postRender() {
-  if (!enabled) {
-    return;
-  }
-
-  if (shouldRemoveFadeIn()) {
-    v.run.removedFadeIn = true;
+// ModCallback.POST_GAME_STARTED (15)
+function postGameStarted(_isContinued: boolean) {
+  if (enabled) {
     game.Fadein(FADE_IN_SPEED);
   }
 }
 
-function shouldRemoveFadeIn() {
-  const gameFrameCount = game.GetFrameCount();
-  return !v.run.removedFadeIn && gameFrameCount === 0;
-}
-
 /**
  * Removes the fade-in that occurs at the beginning of a run. If this behavior is desired, call this
  * function once at the beginning of your mod.

package/src/features/saveDataManager/exports.ts

@@ -2,8 +2,10 @@ import { SaveDataKey } from "../../enums/SaveDataKey";
 import { SerializationType } from "../../enums/SerializationType";
 import { errorIfFeaturesNotInitialized } from "../../featuresInitialized";
 import { deepCopy } from "../../functions/deepCopy";
-import { isString } from "../../functions/types";
+import { getTSTLClassName } from "../../functions/tstlClass";
+import { isString, isTable } from "../../functions/types";
 import { SaveData } from "../../interfaces/SaveData";
+import { AnyClass } from "../../types/AnyClass";
 import { SAVE_DATA_MANAGER_FEATURE_NAME } from "./constants";
 import {
   forceSaveDataManagerLoad,
@@ -14,9 +16,16 @@ import {
   saveDataConditionalFuncMap,
   saveDataDefaultsMap,
   saveDataGlowingHourGlassMap,
+  saveDataManagerClassConstructors,
   saveDataMap,
 } from "./maps";
 
+const NON_USER_DEFINED_CLASS_NAMES: ReadonlySet<string> = new Set([
+  "Map",
+  "Set",
+  "DefaultMap",
+]);
+
 /**
  * This is the entry point to the save data manager, a system which provides two major features:
  *
@@ -114,12 +123,14 @@ import {
  *                        `EntityPtr`.
  */
 export function saveDataManager<Persistent, Run, Level>(
-  key: string, // This is the overload for the standard case with serializable data.
+  // This is the overload for the standard case with serializable data.
+  key: string,
   v: SaveData<Persistent, Run, Level>,
   conditionalFunc?: () => boolean,
 ): void;
 export function saveDataManager(
-  key: string, // This is the overload for the case when saving data is disabled.
+  // This is the overload for the case when saving data is disabled.
+  key: string,
   v: SaveData,
   conditionalFunc: false,
 ): void;
@@ -142,6 +153,10 @@ export function saveDataManager<Persistent, Run, Level>(
     );
   }
 
+  // First, recursively look through the new save data for any classes, so we can register them with
+  // the save data manager.
+  storeClassConstructorsFromObject(v as LuaMap);
+
   // Add the new save data to the map.
   saveDataMap.set(key, v);
 
@@ -169,6 +184,26 @@ export function saveDataManager<Persistent, Run, Level>(
   }
 }
 
+/** Recursively traverses an object, collecting all of the class constructors that it encounters. */
+function storeClassConstructorsFromObject(luaMap: LuaMap<AnyNotNil, unknown>) {
+  const tstlClassName = getTSTLClassName(luaMap);
+  if (
+    tstlClassName !== undefined &&
+    !NON_USER_DEFINED_CLASS_NAMES.has(tstlClassName)
+  ) {
+    saveDataManagerClassConstructors.set(
+      tstlClassName,
+      luaMap as unknown as AnyClass,
+    );
+  }
+
+  for (const [_key, value] of luaMap) {
+    if (isTable(value)) {
+      storeClassConstructorsFromObject(value);
+    }
+  }
+}
+
 /**
  * The save data manager will automatically load variables from disk at the appropriate times (i.e.
  * when a new run is started). Use this function to explicitly force the save data manager to load
@@ -279,3 +314,27 @@ export function saveDataManagerRemove(key: string): void {
   saveDataConditionalFuncMap.delete(key);
   saveDataGlowingHourGlassMap.delete(key);
 }
+
+/**
+ * By default, the save data manager will not be able to serialize classes that are nested inside of
+ * maps, sets, and arrays, because it does not have access to the corresponding class constructor.
+ * If you want to use nested classes in this way, then use this function to register a class
+ * constructor with the save data manager. If the save data manager finds a registered class of the
+ * same name when deserializing, it will automatically run the registered constructor (in addition
+ * to copying over the data fields).
+ *
+ * This function is variadic, which means you can pass as many classes as you want to register.
+ */
+export function saveDataManagerRegisterClass(...tstlClasses: AnyClass[]): void {
+  for (const tstlClass of tstlClasses) {
+    const { name } = tstlClass;
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (name === undefined) {
+      error(
+        "Failed to register a class with the save data manager due to not being able to derive the name of the class.",
+      );
+    }
+
+    saveDataManagerClassConstructors.set(name, tstlClass);
+  }
+}

package/src/features/saveDataManager/load.ts

@@ -1,20 +1,22 @@
 import { jsonDecode } from "../../functions/jsonHelpers";
 import { log } from "../../functions/log";
 import { logError } from "../../functions/logMisc";
+import { merge } from "../../functions/merge";
 import { iterateTableInOrder } from "../../functions/table";
 import { isString, isTable } from "../../functions/types";
 import { SaveData } from "../../interfaces/SaveData";
+import { AnyClass } from "../../types/AnyClass";
 import {
   SAVE_DATA_MANAGER_DEBUG,
   SAVE_DATA_MANAGER_FEATURE_NAME,
 } from "./constants";
-import { merge } from "./merge";
 
 const DEFAULT_MOD_DATA = "{}";
 
 export function loadFromDisk(
   mod: Mod,
   oldSaveData: LuaMap<string, SaveData>,
+  classConstructors: LuaMap<string, AnyClass>,
 ): void {
   if (!mod.HasData()) {
     // There is no "save#.dat" file for this save slot.
@@ -62,6 +64,7 @@ export function loadFromDisk(
         oldSaveDataForSubscriber as LuaMap<AnyNotNil, unknown>,
         saveData,
         subscriberName,
+        classConstructors,
       );
     },
     SAVE_DATA_MANAGER_DEBUG,

package/src/features/saveDataManager/main.ts

@@ -5,6 +5,7 @@ import { SaveDataKey } from "../../enums/SaveDataKey";
 import { SerializationType } from "../../enums/SerializationType";
 import { deepCopy } from "../../functions/deepCopy";
 import { logError } from "../../functions/logMisc";
+import { merge } from "../../functions/merge";
 import { onFirstFloor } from "../../functions/stage";
 import { clearTable, iterateTableInOrder } from "../../functions/table";
 import { SaveData } from "../../interfaces/SaveData";
@@ -20,9 +21,9 @@ import {
   saveDataConditionalFuncMap,
   saveDataDefaultsMap,
   saveDataGlowingHourGlassMap,
+  saveDataManagerClassConstructors,
   saveDataMap,
 } from "./maps";
-import { merge } from "./merge";
 import { saveToDisk } from "./save";
 
 const RESETTABLE_SAVE_DATA_KEYS: ReadonlySet<SaveDataKey> = new Set([
@@ -82,7 +83,7 @@ function postPlayerInit(): void {
 
   // We want to unconditionally load save data on every new run since there might be persistent data
   // that is not tied to an individual run.
-  loadFromDisk(mod, saveDataMap);
+  loadFromDisk(mod, saveDataMap, saveDataManagerClassConstructors);
 
   const gameFrameCount = game.GetFrameCount();
   const isContinued = gameFrameCount !== 0;
@@ -246,6 +247,7 @@ function restoreGlowingHourGlassBackup() {
           childTableBackup as LuaMap<AnyNotNil, unknown>,
           // Append an arbitrary suffix for better error messages.
           `${subscriberName}__glowingHourGlass`,
+          saveDataManagerClassConstructors,
         );
       }
     },
@@ -347,5 +349,5 @@ export function forceSaveDataManagerLoad(): void {
     return;
   }
 
-  loadFromDisk(mod, saveDataMap);
+  loadFromDisk(mod, saveDataMap, saveDataManagerClassConstructors);
 }

package/src/features/saveDataManager/maps.ts

@@ -1,4 +1,5 @@
 import { SaveData } from "../../interfaces/SaveData";
+import { AnyClass } from "../../types/AnyClass";
 
 /**
  * The save data map is indexed by subscriber name. We use Lua tables instead of TypeScriptToLua
@@ -7,7 +8,16 @@ import { SaveData } from "../../interfaces/SaveData";
  */
 export const saveDataMap = new LuaMap<string, SaveData>();
 
+/**
+ * When mod feature data is initialized, we copy the initial values into a separate map so that we
+ * can restore them later on.
+ */
 export const saveDataDefaultsMap = new LuaMap<string, SaveData>();
+
+/**
+ * Each mod feature can optionally provide a function that can control whether or not the save data
+ * is written to disk.
+ */
 export const saveDataConditionalFuncMap = new LuaMap<string, () => boolean>();
 
 /**
@@ -18,3 +28,9 @@ export const saveDataConditionalFuncMap = new LuaMap<string, () => boolean>();
  * to restore it.
  */
 export const saveDataGlowingHourGlassMap = new LuaMap<string, SaveData>();
+
+/**
+ * End-users can register their classes with the save data manager for proper serialization when
+ * contained in nested maps, sets, and arrays.
+ */
+export const saveDataManagerClassConstructors = new LuaMap<string, AnyClass>();