isaacscript-common 7.0.0 → 7.1.0

package/dist/objects/callbackRegisterFunctions.lua

@@ -103,6 +103,8 @@ local ____postPitUpdate = require("callbacks.subscriptions.postPitUpdate")
 local postPitUpdateRegister = ____postPitUpdate.postPitUpdateRegister
 local ____postPlayerChangeHealth = require("callbacks.subscriptions.postPlayerChangeHealth")
 local postPlayerChangeHealthRegister = ____postPlayerChangeHealth.postPlayerChangeHealthRegister
+local ____postPlayerChangeStat = require("callbacks.subscriptions.postPlayerChangeStat")
+local postPlayerChangeStatRegister = ____postPlayerChangeStat.postPlayerChangeStatRegister
 local ____postPlayerChangeType = require("callbacks.subscriptions.postPlayerChangeType")
 local postPlayerChangeTypeRegister = ____postPlayerChangeType.postPlayerChangeTypeRegister
 local ____postPlayerCollectibleAdded = require("callbacks.subscriptions.postPlayerCollectibleAdded")
@@ -228,6 +230,7 @@ ____exports.CALLBACK_REGISTER_FUNCTIONS = {
     [ModCallbackCustom.POST_PIT_RENDER] = postPitRenderRegister,
     [ModCallbackCustom.POST_PIT_UPDATE] = postPitUpdateRegister,
     [ModCallbackCustom.POST_PLAYER_CHANGE_HEALTH] = postPlayerChangeHealthRegister,
+    [ModCallbackCustom.POST_PLAYER_CHANGE_STAT] = postPlayerChangeStatRegister,
     [ModCallbackCustom.POST_PLAYER_CHANGE_TYPE] = postPlayerChangeTypeRegister,
     [ModCallbackCustom.POST_PLAYER_COLLECTIBLE_ADDED] = postPlayerCollectibleAddedRegister,
     [ModCallbackCustom.POST_PLAYER_COLLECTIBLE_REMOVED] = postPlayerCollectibleRemovedRegister,

package/dist/objects/isaacAPIClassTypeToBrand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"isaacAPIClassTypeToBrand.d.ts","sourceRoot":"","sources":["../../src/objects/isaacAPIClassTypeToBrand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,4CAA4C,CAAC;AACvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAEzE,eAAO,MAAM,6BAA6B,EAAE;IAC1C,QAAQ,EAAE,GAAG,IAAI,yBAAyB,GAAG,kBAAkB;CAMvD,CAAC"}
+{"version":3,"file":"isaacAPIClassTypeToBrand.d.ts","sourceRoot":"","sources":["../../src/objects/isaacAPIClassTypeToBrand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,4CAA4C,CAAC;AACvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAEzE,eAAO,MAAM,6BAA6B,EAAE;IAC1C,QAAQ,EAAE,GAAG,IAAI,yBAAyB,GAAG,kBAAkB;CAOvD,CAAC"}

package/dist/objects/isaacAPIClassTypeToBrand.lua

@@ -3,5 +3,11 @@ local ____CopyableIsaacAPIClassType = require("enums.private.CopyableIsaacAPICla
 local CopyableIsaacAPIClassType = ____CopyableIsaacAPIClassType.CopyableIsaacAPIClassType
 local ____SerializationBrand = require("enums.private.SerializationBrand")
 local SerializationBrand = ____SerializationBrand.SerializationBrand
-____exports.ISAAC_API_CLASS_TYPE_TO_BRAND = {[CopyableIsaacAPIClassType.COLOR] = SerializationBrand.COLOR, [CopyableIsaacAPIClassType.K_COLOR] = SerializationBrand.K_COLOR, [CopyableIsaacAPIClassType.RNG] = SerializationBrand.RNG, [CopyableIsaacAPIClassType.VECTOR] = SerializationBrand.VECTOR}
+____exports.ISAAC_API_CLASS_TYPE_TO_BRAND = {
+    [CopyableIsaacAPIClassType.BIT_SET_128] = SerializationBrand.BIT_SET_128,
+    [CopyableIsaacAPIClassType.COLOR] = SerializationBrand.COLOR,
+    [CopyableIsaacAPIClassType.K_COLOR] = SerializationBrand.K_COLOR,
+    [CopyableIsaacAPIClassType.RNG] = SerializationBrand.RNG,
+    [CopyableIsaacAPIClassType.VECTOR] = SerializationBrand.VECTOR
+}
 return ____exports

package/dist/objects/isaacAPIClassTypeToFunctions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"isaacAPIClassTypeToFunctions.d.ts","sourceRoot":"","sources":["../../src/objects/isaacAPIClassTypeToFunctions.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,yBAAyB,EAAE,MAAM,4CAA4C,CAAC;AA0BvF,UAAU,0BAA0B;IAClC,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,IAAI,OAAO,CAAC;IACrD,IAAI,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,GAAG,CAAC;IAC3B,SAAS,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,GAAG,CAAC;IAChC,WAAW,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,GAAG,CAAC;CACnC;AAED,eAAO,MAAM,iCAAiC,EAAE;IAC9C,QAAQ,EAAE,GAAG,IAAI,yBAAyB,GAAG,0BAA0B;CA0B/D,CAAC"}
+{"version":3,"file":"isaacAPIClassTypeToFunctions.d.ts","sourceRoot":"","sources":["../../src/objects/isaacAPIClassTypeToFunctions.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,yBAAyB,EAAE,MAAM,4CAA4C,CAAC;AAgCvF,UAAU,0BAA0B;IAClC,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,IAAI,OAAO,CAAC;IACrD,IAAI,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,GAAG,CAAC;IAC3B,SAAS,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,GAAG,CAAC;IAChC,WAAW,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,GAAG,CAAC;CACnC;AAED,eAAO,MAAM,iCAAiC,EAAE;IAC9C,QAAQ,EAAE,GAAG,IAAI,yBAAyB,GAAG,0BAA0B;CAgC/D,CAAC"}

package/dist/objects/isaacAPIClassTypeToFunctions.lua

@@ -1,6 +1,11 @@
 local ____exports = {}
 local ____CopyableIsaacAPIClassType = require("enums.private.CopyableIsaacAPIClassType")
 local CopyableIsaacAPIClassType = ____CopyableIsaacAPIClassType.CopyableIsaacAPIClassType
+local ____bitSet128 = require("functions.bitSet128")
+local copyBitSet128 = ____bitSet128.copyBitSet128
+local deserializeBitSet128 = ____bitSet128.deserializeBitSet128
+local isSerializedBitSet128 = ____bitSet128.isSerializedBitSet128
+local serializeBitSet128 = ____bitSet128.serializeBitSet128
 local ____color = require("functions.color")
 local copyColor = ____color.copyColor
 local deserializeColor = ____color.deserializeColor
@@ -21,5 +26,11 @@ local copyVector = ____vector.copyVector
 local deserializeVector = ____vector.deserializeVector
 local isSerializedVector = ____vector.isSerializedVector
 local serializeVector = ____vector.serializeVector
-____exports.ISAAC_API_CLASS_TYPE_TO_FUNCTIONS = {[CopyableIsaacAPIClassType.COLOR] = {isSerialized = isSerializedColor, copy = copyColor, serialize = serializeColor, deserialize = deserializeColor}, [CopyableIsaacAPIClassType.K_COLOR] = {isSerialized = isSerializedKColor, copy = copyKColor, serialize = serializeKColor, deserialize = deserializeKColor}, [CopyableIsaacAPIClassType.RNG] = {isSerialized = isSerializedRNG, copy = copyRNG, serialize = serializeRNG, deserialize = deserializeRNG}, [CopyableIsaacAPIClassType.VECTOR] = {isSerialized = isSerializedVector, copy = copyVector, serialize = serializeVector, deserialize = deserializeVector}}
+____exports.ISAAC_API_CLASS_TYPE_TO_FUNCTIONS = {
+    [CopyableIsaacAPIClassType.BIT_SET_128] = {isSerialized = isSerializedBitSet128, copy = copyBitSet128, serialize = serializeBitSet128, deserialize = deserializeBitSet128},
+    [CopyableIsaacAPIClassType.COLOR] = {isSerialized = isSerializedColor, copy = copyColor, serialize = serializeColor, deserialize = deserializeColor},
+    [CopyableIsaacAPIClassType.K_COLOR] = {isSerialized = isSerializedKColor, copy = copyKColor, serialize = serializeKColor, deserialize = deserializeKColor},
+    [CopyableIsaacAPIClassType.RNG] = {isSerialized = isSerializedRNG, copy = copyRNG, serialize = serializeRNG, deserialize = deserializeRNG},
+    [CopyableIsaacAPIClassType.VECTOR] = {isSerialized = isSerializedVector, copy = copyVector, serialize = serializeVector, deserialize = deserializeVector}
+}
 return ____exports

package/package.json

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

package/src/callbacks/postPlayerChangeHealth.ts

@@ -55,7 +55,13 @@ function postPEffectUpdateReordered(player: EntityPlayer) {
       storedHealthValue !== currentHealthValue
     ) {
       const difference = currentHealthValue - storedHealthValue;
-      postPlayerChangeHealthFire(player, healthType, difference);
+      postPlayerChangeHealthFire(
+        player,
+        healthType,
+        difference,
+        storedHealthValue,
+        currentHealthValue,
+      );
     }
   }
 }

package/src/callbacks/postPlayerChangeStat.ts

@@ -0,0 +1,68 @@
+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 { getPlayerStat, isNumber } from "../functions";
+import { getEnumValues } from "../functions/enums";
+import { getPlayerIndex } from "../functions/playerIndex";
+import { PlayerIndex } from "../types/PlayerIndex";
+import {
+  postPlayerChangeStatFire,
+  postPlayerChangeStatHasSubscriptions,
+} from "./subscriptions/postPlayerChangeStat";
+
+const v = {
+  run: {
+    playersStatMap: new DefaultMap<
+      PlayerIndex,
+      Map<StatType, number | boolean | BitFlags<TearFlag> | Color | Vector>
+    >(() => 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 && storedStatValue !== currentStatValue) {
+      const isNumberStat =
+        isNumber(storedStatValue) && isNumber(currentStatValue);
+      const difference = isNumberStat ? currentStatValue - storedStatValue : 0;
+      postPlayerChangeStatFire(
+        player,
+        statType,
+        difference,
+        storedStatValue,
+        currentStatValue,
+      );
+    }
+  }
+}

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/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,
+
+  /** Corresponds to `CacheFlag.SIZE` (1 << 11) and `EntityPlayer.SizeMulti`. */
+  SIZE,
+
+  // `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/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

package/src/functions/familiars.ts

@@ -11,8 +11,8 @@ import { getFamiliars } from "./entitiesSpecific";
  * specify an incorrect RNG object. (The vanilla method is bugged in that it does not increment the
  * RNG object; see the documentation of the method for more details.)
  *
- * This function is meant to be called in the EvaluateCache callback (when the cache flag is equal
- * to `CacheFlag.FAMILIARS`).
+ * This function is meant to be called in the `EVALUATE_CACHE` callback (when the cache flag is
+ * equal to `CacheFlag.FAMILIARS`).
  *
  * Note that this function is only meant to be used in special circumstances where the familiar
  * count is completely custom and does not correspond to the amount of collectibles. For the general
@@ -56,8 +56,8 @@ export function checkFamiliar(
  * Use this helper function instead of invoking the `EntityPlayer.CheckFamiliar` method directly so
  * that the target count is handled automatically.
  *
- * This function is meant to be called in the EvaluateCache callback (when the cache flag is equal
- * to `CacheFlag.FAMILIARS`).
+ * This function is meant to be called in the `EVALUATE_CACHE` callback (when the cache flag is
+ * equal to `CacheFlag.FAMILIARS`).
  *
  * Use this function when the amount of familiars should be equal to the amount of associated
  * collectibles that the player has (plus any extras from having used Box of Friends or Monster

package/src/functions/flag.ts

@@ -42,7 +42,7 @@ export function addFlag<T extends BitFlag | BitFlag128>(
  * Helper function for casting a flag enum value to a `BitFlags` object.
  *
  * This is useful because the compiler will prevent you from assigning a specific flag to a
- * `BitFlags` property. (It does this to ensure type safety, since `BitFlags` can represent a zero
+ * `BitFlags` field. (It does this to ensure type safety, since `BitFlags` can represent a zero
  * value or a composition of N flags.)
  *
  * For example:

package/src/functions/index.ts

@@ -3,6 +3,7 @@
 export * from "./ambush";
 export * from "./array";
 export * from "./benchmark";
+export * from "./bitSet128";
 export * from "./bitwise";
 export * from "./bombs";
 export * from "./bosses";
@@ -63,6 +64,7 @@ export * from "./playerDataStructures";
 export * from "./playerHealth";
 export * from "./playerIndex";
 export * from "./players";
+export * from "./playerStats";
 export * from "./pocketItems";
 export * from "./positionVelocity";
 export * from "./pressurePlate";

package/src/functions/indexTypeDoc.ts

@@ -3,6 +3,7 @@
 export * as Ambush from "./ambush";
 export * as Array from "./array";
 export * as Benchmark from "./benchmark";
+export * as BitSet128 from "./bitSet128";
 export * as Bitwise from "./bitwise";
 export * as Bombs from "./bombs";
 export * as Bosses from "./bosses";
@@ -63,6 +64,7 @@ export * as PlayerDataStructures from "./playerDataStructures";
 export * as PlayerHealth from "./playerHealth";
 export * as PlayerIndex from "./playerIndex";
 export * as Players from "./players";
+export * as PlayerStats from "./playerStats";
 export * as PocketItems from "./pocketItems";
 export * as PositionVelocity from "./positionVelocity";
 export * as PressurePlate from "./pressurePlate";