isaacscript-common 6.23.0 → 7.1.1

package/src/callbacks/postPlayerChangeStat.ts

@@ -0,0 +1,110 @@
+import { TearFlag } from "isaac-typescript-definitions";
+import { DefaultMap } from "../classes/DefaultMap";
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { StatType } from "../enums";
+import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { saveDataManager } from "../features/saveDataManager/exports";
+import {
+  colorEquals,
+  getPlayerStat,
+  isBitSet128,
+  isBoolean,
+  isColor,
+  isNumber,
+} from "../functions";
+import { getEnumValues } from "../functions/enums";
+import { getPlayerIndex } from "../functions/playerIndex";
+import { PlayerIndex } from "../types/PlayerIndex";
+import {
+  postPlayerChangeStatFire,
+  postPlayerChangeStatHasSubscriptions,
+} from "./subscriptions/postPlayerChangeStat";
+
+type PossibleStatType = number | boolean | BitFlags<TearFlag> | Color;
+
+const v = {
+  run: {
+    playersStatMap: new DefaultMap<
+      PlayerIndex,
+      Map<StatType, PossibleStatType>
+    >(() => new Map()),
+  },
+};
+
+export function postPlayerChangeStatInit(mod: ModUpgraded): void {
+  saveDataManager("postPlayerChangeStat", v, hasSubscriptions);
+
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED,
+    postPEffectUpdateReordered,
+  );
+}
+
+function hasSubscriptions() {
+  return postPlayerChangeStatHasSubscriptions();
+}
+
+// ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED
+function postPEffectUpdateReordered(player: EntityPlayer) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  // We call the "getPlayerIndex" function with the "differentiateForgottenAndSoul" argument. If we
+  // don't differentiate between The Forgotten and The Soul, the callback will fire every time the
+  // player switches between the two.
+  const playerIndex = getPlayerIndex(player, true);
+  const playerStatMap = v.run.playersStatMap.getAndSetDefault(playerIndex);
+
+  for (const statType of getEnumValues(StatType)) {
+    const storedStatValue = playerStatMap.get(statType);
+    const currentStatValue = getPlayerStat(player, statType);
+    playerStatMap.set(statType, currentStatValue);
+
+    if (storedStatValue === undefined) {
+      continue;
+    }
+
+    if (!statEquals(storedStatValue, currentStatValue)) {
+      const isNumberStat =
+        isNumber(storedStatValue) && isNumber(currentStatValue);
+      const difference = isNumberStat ? currentStatValue - storedStatValue : 0;
+      postPlayerChangeStatFire(
+        player,
+        statType,
+        difference,
+        storedStatValue,
+        currentStatValue,
+      );
+    }
+  }
+}
+
+function statEquals(
+  oldValue: PossibleStatType,
+  newValue: PossibleStatType,
+): boolean {
+  const isNumberStat = isNumber(oldValue) && isNumber(newValue);
+  if (isNumberStat) {
+    return oldValue === newValue;
+  }
+
+  const isBooleanStat = isBoolean(oldValue) && isBoolean(newValue);
+  if (isBooleanStat) {
+    return oldValue === newValue;
+  }
+
+  const isBitSet128Stat = isBitSet128(oldValue) && isBitSet128(newValue);
+  if (isBitSet128Stat) {
+    return oldValue === newValue; // The class has the "__eq" meta-method.
+  }
+
+  const isColorStat = isColor(oldValue) && isColor(newValue);
+  if (isColorStat) {
+    return colorEquals(oldValue, newValue);
+  }
+
+  error(
+    'Failed to determine the type of a stat in the "POST_PLAYER_CHANGE_STAT" callback.',
+  );
+}

package/src/callbacks/subscriptions/postPlayerChangeHealth.ts

@@ -6,6 +6,8 @@ export type PostPlayerChangeHealthRegisterParameters = [
     player: EntityPlayer,
     healthType: HealthType,
     difference: int,
+    oldValue: int,
+    newValue: int,
   ) => void,
   playerVariant?: PlayerVariant,
   character?: PlayerType,
@@ -27,6 +29,8 @@ export function postPlayerChangeHealthFire(
   player: EntityPlayer,
   healthType: HealthType,
   difference: int,
+  oldValue: int,
+  newValue: int,
 ): void {
   const character = player.GetPlayerType();
 
@@ -41,6 +45,6 @@ export function postPlayerChangeHealthFire(
       continue;
     }
 
-    callback(player, healthType, difference);
+    callback(player, healthType, difference, oldValue, newValue);
   }
 }

package/src/callbacks/subscriptions/postPlayerChangeStat.ts

@@ -0,0 +1,55 @@
+import {
+  PlayerType,
+  PlayerVariant,
+  TearFlag,
+} from "isaac-typescript-definitions";
+import { StatType } from "../../enums/StatType";
+import { StatTypeType } from "../../interfaces/StatTypeType";
+
+export type PostPlayerChangeStatRegisterParameters = [
+  callback: (
+    player: EntityPlayer,
+    statType: StatType,
+    difference: int,
+    oldValue: number | boolean | BitFlags<TearFlag> | Color | Vector,
+    newValue: number | boolean | BitFlags<TearFlag> | Color | Vector,
+  ) => void,
+  playerVariant?: PlayerVariant,
+  character?: PlayerType,
+];
+
+const subscriptions: PostPlayerChangeStatRegisterParameters[] = [];
+
+export function postPlayerChangeStatHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+export function postPlayerChangeStatRegister(
+  ...args: PostPlayerChangeStatRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+export function postPlayerChangeStatFire<T extends StatType>(
+  player: EntityPlayer,
+  statType: T,
+  difference: int,
+  oldValue: StatTypeType[T],
+  newValue: StatTypeType[T],
+): void {
+  const character = player.GetPlayerType();
+
+  for (const [callback, playerVariant, callbackCharacter] of subscriptions) {
+    // Handle the optional 2nd callback argument.
+    if (playerVariant !== undefined && playerVariant !== player.Variant) {
+      continue;
+    }
+
+    // Handle the optional 3rd callback argument.
+    if (callbackCharacter !== undefined && callbackCharacter !== character) {
+      continue;
+    }
+
+    callback(player, statType, difference, oldValue, newValue);
+  }
+}

package/src/classes/DefaultMap.ts

@@ -5,9 +5,7 @@ import { isFunction, isPrimitive } from "../functions/types";
  * A function that creates the default value for your `DefaultMap`. For example, if it was a
  * `DefaultMap` containing maps, the factory function would be: `() => new Map()`
  */
-export type FactoryFunction<V, Args extends unknown[]> = (
-  ...extraArgs: Args
-) => V;
+export type FactoryFunction<V, Args extends unknown[]> = (...args: Args) => V;
 
 /**
  * `DefaultMap` is a data structure that makes working with default values easier.
@@ -127,13 +125,13 @@ export class DefaultMap<Key, Value, Args extends unknown[] = []> extends Map<
    * If the key exists, this will return the same thing as the normal `Map.get` method. Otherwise,
    * it will set a default value for the provided key, and then return the default value.
    */
-  getAndSetDefault(key: Key, ...extraArgs: Args): Value {
+  getAndSetDefault(key: Key, ...args: Args): Value {
     const value = super.get(key);
     if (value !== undefined) {
       return value;
     }
 
-    const defaultValue = this.getDefaultValue(...extraArgs);
+    const defaultValue = this.getDefaultValue(...args);
     this.set(key, defaultValue);
     return defaultValue;
   }
@@ -142,13 +140,13 @@ export class DefaultMap<Key, Value, Args extends unknown[] = []> extends Map<
    * Returns the default value to be used for a new key. (If a factory function was provided during
    * instantiation, this will execute the factory function.)
    */
-  getDefaultValue(...extraArgs: Args): Value {
+  getDefaultValue(...args: Args): Value {
     if (this.defaultValue !== undefined) {
       return this.defaultValue;
     }
 
     if (this.defaultValueFactory !== undefined) {
-      return this.defaultValueFactory(...extraArgs);
+      return this.defaultValueFactory(...args);
     }
 
     error("A DefaultMap was incorrectly instantiated.");
@@ -170,3 +168,34 @@ export class DefaultMap<Key, Value, Args extends unknown[] = []> extends Map<
     error("A DefaultMap was incorrectly instantiated.");
   }
 }
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+function test() {
+  // Boolean
+  const myDefaultMapBoolean = new DefaultMap<string, boolean>(false);
+  const myDefaultMapBooleanFactory = new DefaultMap<string, boolean>(
+    () => false,
+  );
+  const myDefaultMapBooleanWithoutParams = new DefaultMap(false);
+
+  // Number
+  const myDefaultMapNumber = new DefaultMap<string, number>(123);
+  const myDefaultMapNumberFactory = new DefaultMap<string, number>(() => 123);
+  const myDefaultMapNumberWithoutParams = new DefaultMap(123);
+
+  // String
+  const myDefaultMapString = new DefaultMap<string, string>("foo");
+  const myDefaultMapStringFactory = new DefaultMap<string, string>(() => "foo");
+  const myDefaultMapStringWithoutParams = new DefaultMap("foo");
+
+  // Array
+  const myDefaultMapArray = new DefaultMap<string, string[]>(() => []);
+  const myDefaultMapArrayWithoutParams = new DefaultMap(() => []);
+
+  // Map
+  const myDefaultMapMap = new DefaultMap<string, Map<string, string>>(
+    () => new Map(),
+  );
+  const myDefaultMapMapWithoutParams = new DefaultMap(() => new Map());
+}
+/* eslint-enable @typescript-eslint/no-unused-vars */

package/src/core/constants.ts

@@ -36,7 +36,7 @@ export const BLIND_ITEM_PNG_PATH = "gfx/items/collectibles/questionmark.png";
 /** Bombs explode when their frame count is equal to this value. */
 export const BOMB_EXPLODE_FRAME = 45;
 
-/** This is the initial value of the `EntityPickup.Wait` property after a collectible is spawned. */
+/** This is the initial value of the `EntityPickup.Wait` field after a collectible is spawned. */
 export const COLLECTIBLE_INITIAL_WAIT = 20;
 
 export const DEFAULT_ITEM_POOL_TYPE = ItemPoolType.TREASURE;

package/src/enums/ModCallbackCustom.ts

@@ -798,8 +798,8 @@ export enum ModCallbackCustom {
   POST_PIT_UPDATE,
 
   /**
-   * Fires from the `POST_PEFFECT_UPDATE` callback when a player entity gains or loses any health
-   * (i.e. hearts). For more information, see the `PlayerHealth` enum.
+   * Fires from the `POST_PEFFECT_UPDATE` callback when a player's health (i.e. hearts) is different
+   * than what it was on the previous frame. For more information, see the `PlayerHealth` enum.
    *
    * - When registering the callback, takes an optional second argument that will make the callback
    *   only fire if the player matches the `PlayerVariant` provided.
@@ -811,15 +811,47 @@ export enum ModCallbackCustom {
    *   player: EntityPlayer,
    *   healthType: HealthType,
    *   difference: int,
+   *   oldValue: int,
+   *   newValue: int,
    * ): void {}
    * ```
    */
   POST_PLAYER_CHANGE_HEALTH,
 
+  /**
+   * Fires from the `POST_PEFFECT_UPDATE` callback when one of the player's stats change from what
+   * they were on the previous frame.
+   *
+   * The type of `oldValue` and `newValue` will depend on what kind of stat it is. For example,
+   * `StatType.FLYING` will be a boolean. (You can use the "Types" helper functions to narrow the
+   * type.)
+   *
+   * For `StatType.TEAR_FLAG`, `StatType.TEAR_COLOR`, `StatType.FLYING`, and `StatType.SIZE`, the
+   * `difference` argument will always be a value of 0, since the type of these stats are not
+   * numbers. (For these cases, you should examine the `oldValue` and `newValue` arguments
+   * accordingly.)
+   *
+   * - When registering the callback, takes an optional second argument that will make the callback
+   *   only fire if the player matches the `PlayerVariant` provided.
+   * - When registering the callback, takes an optional third argument that will make the callback
+   *   only fire if the player matches the `PlayerType` provided.
+   *
+   * ```ts
+   * function postPlayerChangeStat(
+   *   player: EntityPlayer,
+   *   statType: StatType,
+   *   difference: int,
+   *   oldValue: number | boolean | BitFlags<TearFlag> | Color | Vector,
+   *   newValue: number | boolean | BitFlags<TearFlag> | Color | Vector,
+   * ): void {}
+   * ```
+   */
+  POST_PLAYER_CHANGE_STAT,
+
   /**
    * Fires from the `POST_PEFFECT_UPDATE` callback when a player entity changes its player type
-   * (i.e. character). For example, it will fire after using Clicker, after dying with the Judas'
-   * Shadow collectible, etc.
+   * (i.e. character) from what it was on the previous frame. For example, it will fire after using
+   * Clicker, after dying with the Judas' Shadow collectible, etc.
    *
    * Notably, it does not fire after the player uses the Flip item or the Esau Jr. item, because
    * those items cause separate player entities to be created. Use the `POST_FLIP` and

package/src/enums/StatType.ts

@@ -0,0 +1,47 @@
+/** This represents the kinds of stats that a player can have. */
+export enum StatType {
+  /** Corresponds to `CacheFlag.DAMAGE` (1 << 0) and `EntityPlayer.Damage`. */
+  DAMAGE,
+
+  /** Corresponds to `CacheFlag.FIRE_DELAY` (1 << 1) and `EntityPlayer.MaxFireDelay`. */
+  FIRE_DELAY,
+
+  /** Corresponds to `CacheFlag.SHOT_SPEED` (1 << 2) and `EntityPlayer.ShotSpeed`. */
+  SHOT_SPEED,
+
+  /** Corresponds to `CacheFlag.RANGE` (1 << 3) and `EntityPlayer.TearHeight`. */
+  TEAR_HEIGHT,
+
+  /** Corresponds to `CacheFlag.RANGE` (1 << 3) and `EntityPlayer.TearRange`. */
+  TEAR_RANGE,
+
+  /** Corresponds to `CacheFlag.RANGE` (1 << 3) and `EntityPlayer.TearFallingAcceleration`. */
+  TEAR_FALLING_ACCELERATION,
+
+  /** Corresponds to `CacheFlag.RANGE` (1 << 3) and `EntityPlayer.TearFallingSpeed`. */
+  TEAR_FALLING_SPEED,
+
+  /** Corresponds to `CacheFlag.SPEED` (1 << 4) and `EntityPlayer.MoveSpeed`. */
+  MOVE_SPEED,
+
+  /** Corresponds to `CacheFlag.TEAR_FLAG` (1 << 5) and `EntityPlayer.TearFlags`. */
+  TEAR_FLAG,
+
+  /** Corresponds to `CacheFlag.TEAR_COLOR` (1 << 6) and `EntityPlayer.TearColor`. */
+  TEAR_COLOR,
+
+  /** Corresponds to `CacheFlag.FLYING` (1 << 7) and `EntityPlayer.CanFly`. */
+  FLYING,
+
+  // - `CacheFlag.WEAPON` (1 << 8) does not have a corresponding `EntityPlayer` field.
+  // - `CacheFlag.FAMILIARS` (1 << 9) does not have a corresponding `EntityPlayer` field.
+
+  /** Corresponds to `CacheFlag.LUCK` (1 << 10) and `EntityPlayer.Luck`. */
+  LUCK,
+
+  // - `CacheFlag.SIZE` (1 << 12) does not have a corresponding `EntityPlayer` field. (After picking
+  //   up Magic Mushroom, the values of `EntityPlayer.Size` and `EntityPlayer.SizeMulti` do not
+  //   change.)
+  // - `CacheFlag.COLOR` (1 << 12) does not have a corresponding `EntityPlayer` field.
+  // - `CacheFlag.PICKUP_VISION` (1 << 13) does not have a corresponding `EntityPlayer` field.
+}

package/src/enums/index.ts

@@ -6,3 +6,4 @@ export * from "./PocketItemType";
 export * from "./RockAltType";
 export * from "./SerializationType";
 export * from "./SlotDestructionType";
+export * from "./StatType";

package/src/enums/indexTypeDoc.ts

@@ -6,3 +6,4 @@ export * as PocketItemType from "./PocketItemType";
 export * as RockAltType from "./RockAltType";
 export * as SerializationType from "./SerializationType";
 export * as SlotDestructionType from "./SlotDestructionType";
+export * as StatType from "./StatType";

package/src/enums/private/CopyableIsaacAPIClassType.ts

@@ -1,5 +1,9 @@
-/** This must match the enumeration in the JSDoc comments for `deepCopy` and `merge`. */
+/**
+ * - This must match the JSDoc comments for `deepCopy` and `merge`.
+ * - This must match the `SerializableIsaacAPIClass` type union.
+ */
 export enum CopyableIsaacAPIClassType {
+  BIT_SET_128 = "BitSet128",
   COLOR = "Color",
   K_COLOR = "KColor",
   RNG = "RNG",

package/src/enums/private/SerializationBrand.ts

@@ -12,6 +12,7 @@ export enum SerializationBrand {
   SET = "__TSTL_SET",
 
   // Specific Isaac API class brands:
+  BIT_SET_128 = "__BIT_SET_128",
   COLOR = "__COLOR",
   K_COLOR = "__K_COLOR",
   RNG = "__RNG",

package/src/features/customStage/versusScreen.ts

@@ -76,13 +76,13 @@ const versusScreenSprite = Sprite();
 
 /**
  * Unfortunately, we must split the background layer into an entirely different sprite so that we
- * can color it with the `Color` property.
+ * can color it with the `Color` field.
  */
 const versusScreenBackgroundSprite = Sprite();
 
 /**
  * Unfortunately, we must split the dirt layer into an entirely different sprite so that we can
- * color it with the `Color` property.
+ * color it with the `Color` field.
  */
 const versusScreenDirtSpotSprite = Sprite();
 

package/src/features/disableInputs.ts

@@ -12,16 +12,10 @@ const FEATURE_NAME = "disableInputs";
 const v = {
   run: {
     /** Indexed by the requesting feature key. */
-    disableInputsWithWhitelistMap: new Map<
-      string,
-      Set<ButtonAction> | ReadonlySet<ButtonAction>
-    >(),
+    disableInputsWithWhitelistMap: new Map<string, ReadonlySet<ButtonAction>>(),
 
     /** Indexed by the requesting feature key. */
-    enableInputsWithBlacklistMap: new Map<
-      string,
-      Set<ButtonAction> | ReadonlySet<ButtonAction>
-    >(),
+    enableInputsWithBlacklistMap: new Map<string, ReadonlySet<ButtonAction>>(),
   },
 };
 
@@ -154,7 +148,7 @@ export function enableAllInputsExceptFor(
  */
 export function disableAllInputsExceptFor(
   key: string,
-  whitelist: Set<ButtonAction>,
+  whitelist: Set<ButtonAction> | ReadonlySet<ButtonAction>,
 ): void {
   errorIfFeaturesNotInitialized(FEATURE_NAME);
 

package/src/features/runInNFrames.ts

@@ -31,7 +31,7 @@ const v = {
 };
 
 export function runInNFramesInit(mod: Mod): void {
-  saveDataManager(FEATURE_NAME, v, () => false); // Functions are not serializable.
+  saveDataManager(FEATURE_NAME, v, false); // Functions are not serializable.
 
   mod.AddCallback(ModCallback.POST_UPDATE, postUpdate); // 1
   mod.AddCallback(ModCallback.POST_RENDER, postRender); // 2

package/src/features/runNextRoom.ts

@@ -13,7 +13,7 @@ const v = {
 };
 
 export function runNextRoomInit(mod: ModUpgraded): void {
-  saveDataManager(FEATURE_NAME, v, () => false); // Functions are not serializable.
+  saveDataManager(FEATURE_NAME, v, false); // Functions are not serializable.
 
   mod.AddCallbackCustom(
     ModCallbackCustom.POST_NEW_ROOM_REORDERED,

package/src/features/saveDataManager/exports.ts

@@ -113,7 +113,7 @@ export function saveDataManager<Persistent, Run, Level>(
 ): void;
 export function saveDataManager(
   key: string, // This is the overload for the case when saving data is disabled.
-  v: SaveData<unknown, unknown, unknown>,
+  v: SaveData,
   conditionalFunc: false,
 ): void;
 export function saveDataManager<Persistent, Run, Level>(

package/src/features/saveDataManager/merge.ts

@@ -25,6 +25,7 @@ import { isSerializationBrand } from "./serializationBrands";
  * - TSTL `Set`
  * - TSTL classes
  * - `DefaultMap`
+ * - Isaac `BitSet128` objects
  * - Isaac `Color` objects
  * - Isaac `KColor` objects
  * - Isaac `RNG` objects

package/src/functions/bitSet128.ts

@@ -0,0 +1,96 @@
+import { SerializationBrand } from "../enums/private/SerializationBrand";
+import { isIsaacAPIClassOfType } from "./isaacAPIClass";
+import { copyValuesToTable, getNumbersFromTable, tableHasKeys } from "./table";
+import { isTable } from "./types";
+
+export type SerializedBitSet128 = LuaMap<string, unknown> & {
+  readonly __serializedBitSet128Brand: symbol;
+};
+
+const OBJECT_NAME = "BitSet128";
+const KEYS = ["l", "h"];
+
+/** Helper function to copy a `BitSet128` Isaac API class. */
+export function copyBitSet128(bitSet128: BitSet128): BitSet128 {
+  if (!isBitSet128(bitSet128)) {
+    error(
+      `Failed to copy a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`,
+    );
+  }
+
+  const lowBits = bitSet128.l;
+  const highBits = bitSet128.h;
+
+  return BitSet128(lowBits, highBits);
+}
+
+/**
+ * Helper function to convert a `SerializedBitSet128` object to a normal `BitSet128` object. (This
+ * is used by the save data manager when reading data from the "save#.dat" file.)
+ */
+export function deserializeBitSet128(
+  bitSet128: SerializedBitSet128,
+): BitSet128 {
+  if (!isTable(bitSet128)) {
+    error(
+      `Failed to deserialize a ${OBJECT_NAME} object since the provided object was not a Lua table.`,
+    );
+  }
+
+  const [l, h] = getNumbersFromTable(
+    bitSet128 as LuaMap<string, unknown>,
+    OBJECT_NAME,
+    ...KEYS,
+  );
+
+  if (l === undefined) {
+    error(
+      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: l`,
+    );
+  }
+  if (h === undefined) {
+    error(
+      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: h`,
+    );
+  }
+
+  return BitSet128(l, h);
+}
+
+/** Helper function to check if something is an instantiated `BitSet128` object. */
+export function isBitSet128(object: unknown): object is BitSet128 {
+  return isIsaacAPIClassOfType(object, OBJECT_NAME);
+}
+
+/**
+ * Used to determine is the given table is a serialized `BitSet128` object created by the save data
+ * manager and/or the `deepCopy` function.
+ */
+export function isSerializedBitSet128(
+  object: unknown,
+): object is SerializedBitSet128 {
+  if (!isTable(object)) {
+    return false;
+  }
+
+  return (
+    tableHasKeys(object, ...KEYS) && object.has(SerializationBrand.BIT_SET_128)
+  );
+}
+
+/**
+ * Helper function to convert a `BitSet128` object to a `SerializedBitSet128` object. (This is used
+ * by the save data manager when writing data from the "save#.dat" file.)
+ */
+export function serializeBitSet128(bitSet128: BitSet128): SerializedBitSet128 {
+  if (!isBitSet128(bitSet128)) {
+    error(
+      `Failed to serialize a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`,
+    );
+  }
+
+  const bitSet128Table = new LuaMap<string, unknown>();
+  copyValuesToTable(bitSet128, KEYS, bitSet128Table);
+  bitSet128Table.set(SerializationBrand.BIT_SET_128, "");
+  return bitSet128Table as SerializedBitSet128;
+}

package/src/functions/collectibles.ts

@@ -614,8 +614,8 @@ export function setCollectibleSprite(
 }
 
 /**
- * Helper function to change the collectible on a pedestal. Simply updating the `SubType` property
- * is not sufficient because the sprite will not change.
+ * Helper function to change the collectible on a pedestal. Simply updating the `SubType` field is
+ * not sufficient because the sprite will not change.
  */
 export function setCollectibleSubType(
   collectible: EntityPickup,

package/src/functions/color.ts

@@ -9,8 +9,8 @@ export type SerializedColor = LuaMap<string, unknown> & {
   readonly __serializedColorBrand: symbol;
 };
 
-const KEYS = ["R", "G", "B", "A", "RO", "GO", "BO"];
 const OBJECT_NAME = "Color";
+const KEYS = ["R", "G", "B", "A", "RO", "GO", "BO"];
 
 export function colorEquals(color1: Color, color2: Color): boolean {
   return isaacAPIClassEquals(color1, color2, KEYS);
@@ -91,7 +91,7 @@ export function getRandomColor(
   return Color(r, g, b, alpha);
 }
 
-/** Helper function to check if something is an instantiated Color object. */
+/** Helper function to check if something is an instantiated `Color` object. */
 export function isColor(object: unknown): object is Color {
   return isIsaacAPIClassOfType(object, OBJECT_NAME);
 }
@@ -107,6 +107,7 @@ export function isSerializedColor(object: unknown): object is SerializedColor {
 
   return tableHasKeys(object, ...KEYS) && object.has(SerializationBrand.COLOR);
 }
+
 /**
  * Helper function to convert a `Color` object to a `SerializedColor` object. (This is used by the
  * save data manager when writing data from the "save#.dat" file.)

package/src/functions/deepCopy.ts

@@ -42,6 +42,7 @@ const COPYABLE_ISAAC_API_CLASS_TYPES_SET = new Set<string>(
  * - TSTL `Set`
  * - TSTL classes
  * - `DefaultMap`
+ * - Isaac `BitSet128` objects
  * - Isaac `Color` objects
  * - Isaac `KColor` objects
  * - Isaac `RNG` objects
@@ -233,7 +234,7 @@ function deepCopyDefaultMap(
       // throw a run-time error to immediately alert the end-user that their data structure is
       // invalid.
       error(
-        'Failed to deep copy a DefaultMap because it was instantiated with a factory function and was also inside of another map. You cannot use a nested DefaultMap in this way because factory functions are not serializable. (In other words, there is no way to copy the function that you are using for the DefaultMap into the "save#.dat" file.) Instead, refactor your data structure so that the DefaultMap is not nested.',
+        "Failed to deep copy a DefaultMap because it was instantiated with a factory function and was also inside of an array, map, or set. For more information, see: https://isaacscript.github.io/main/gotchas#failed-to-deep-copy-a-defaultmap",
       );
     } else {
       // In most cases, the DefaultMap will be attached to a normal table element. In this case, if