isaacscript-common 7.4.2 → 7.5.1

package/src/callbacks/postGridEntity.ts

@@ -1,13 +1,19 @@
 // This provides the logic for the following callbacks:
 // - `POST_GRID_ENTITY_INIT`
+// - `POST_GRID_ENTITY_CUSTOM_INIT`
 // - `POST_GRID_ENTITY_UPDATE`
+// - `POST_GRID_ENTITY_CUSTOM_UPDATE`
 // - `POST_GRID_ENTITY_REMOVE`
+// - `POST_GRID_ENTITY_CUSTOM_REMOVE`
 // - `POST_GRID_ENTITY_STATE_CHANGED`
+// - `POST_GRID_ENTITY_CUSTOM_STATE_CHANGED`
 // - `POST_GRID_ENTITY_BROKEN`
+// - `POST_GRID_ENTITY_CUSTOM_BROKEN`
 
 import { GridEntityType, ModCallback } from "isaac-typescript-definitions";
 import { ModUpgraded } from "../classes/ModUpgraded";
 import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { getCustomGridEntityType } from "../features/customGridEntity";
 import { saveDataManager } from "../features/saveDataManager/exports";
 import {
   getGridEntitiesMap,
@@ -17,6 +23,26 @@ import {
   postGridEntityBrokenFire,
   postGridEntityBrokenHasSubscriptions,
 } from "./subscriptions/postGridEntityBroken";
+import {
+  postGridEntityCustomBrokenFire,
+  postGridEntityCustomBrokenHasSubscriptions,
+} from "./subscriptions/postGridEntityCustomBroken";
+import {
+  postGridEntityCustomInitFire,
+  postGridEntityCustomInitHasSubscriptions,
+} from "./subscriptions/postGridEntityCustomInit";
+import {
+  postGridEntityCustomRemoveFire,
+  postGridEntityCustomRemoveHasSubscriptions,
+} from "./subscriptions/postGridEntityCustomRemove";
+import {
+  postGridEntityCustomStateChangedFire,
+  postGridEntityCustomStateChangedHasSubscriptions,
+} from "./subscriptions/postGridEntityCustomStateChanged";
+import {
+  postGridEntityCustomUpdateFire,
+  postGridEntityCustomUpdateHasSubscriptions,
+} from "./subscriptions/postGridEntityCustomUpdate";
 import {
   postGridEntityInitFire,
   postGridEntityInitHasSubscriptions,
@@ -60,10 +86,15 @@ export function postGridEntityCallbacksInit(mod: ModUpgraded): void {
 function hasSubscriptions() {
   return (
     postGridEntityInitHasSubscriptions() ||
+    postGridEntityCustomInitHasSubscriptions() ||
     postGridEntityUpdateHasSubscriptions() ||
+    postGridEntityCustomUpdateHasSubscriptions() ||
     postGridEntityRemoveHasSubscriptions() ||
+    postGridEntityCustomRemoveHasSubscriptions() ||
     postGridEntityStateChangedHasSubscriptions() ||
-    postGridEntityBrokenHasSubscriptions()
+    postGridEntityCustomStateChangedHasSubscriptions() ||
+    postGridEntityBrokenHasSubscriptions() ||
+    postGridEntityCustomBrokenHasSubscriptions()
   );
 }
 
@@ -82,7 +113,13 @@ function postUpdate() {
   for (const [gridIndex, gridEntity] of gridEntitiesMap.entries()) {
     checkGridEntityStateChanged(gridIndex, gridEntity);
     checkNewGridEntity(gridIndex, gridEntity);
-    postGridEntityUpdateFire(gridEntity);
+
+    const gridEntityTypeCustom = getCustomGridEntityType(gridIndex);
+    if (gridEntityTypeCustom === undefined) {
+      postGridEntityUpdateFire(gridEntity);
+    } else {
+      postGridEntityCustomUpdateFire(gridEntity, gridEntityTypeCustom);
+    }
   }
 }
 
@@ -98,11 +135,17 @@ function checkGridEntitiesRemoved(gridEntitiesMap: Map<int, GridEntity>) {
       gridEntity.GetType() !== storedGridEntityType
     ) {
       v.room.initializedGridEntities.delete(gridIndex);
-      postGridEntityRemoveFire(
-        gridIndex,
-        storedGridEntityType,
-        storedGridEntityVariant,
-      );
+
+      const gridEntityTypeCustom = getCustomGridEntityType(gridIndex);
+      if (gridEntityTypeCustom === undefined) {
+        postGridEntityRemoveFire(
+          gridIndex,
+          storedGridEntityType,
+          storedGridEntityVariant,
+        );
+      } else {
+        postGridEntityCustomRemoveFire(gridIndex, gridEntityTypeCustom);
+      }
     }
   }
 }
@@ -119,10 +162,26 @@ function checkGridEntityStateChanged(gridIndex: int, gridEntity: GridEntity) {
   const newState = gridEntity.State;
   if (oldState !== newState) {
     updateTupleInMap(gridEntity);
-    postGridEntityStateChangedFire(gridEntity, oldState, newState);
+
+    const gridEntityTypeCustom = getCustomGridEntityType(gridEntity);
+
+    if (gridEntityTypeCustom === undefined) {
+      postGridEntityStateChangedFire(gridEntity, oldState, newState);
+    } else {
+      postGridEntityCustomStateChangedFire(
+        gridEntity,
+        gridEntityTypeCustom,
+        oldState,
+        newState,
+      );
+    }
 
     if (isGridEntityBroken(gridEntity)) {
-      postGridEntityBrokenFire(gridEntity);
+      if (gridEntityTypeCustom === undefined) {
+        postGridEntityBrokenFire(gridEntity);
+      } else {
+        postGridEntityCustomBrokenFire(gridEntity, gridEntityTypeCustom);
+      }
     }
   }
 }
@@ -133,7 +192,13 @@ function checkNewGridEntity(gridIndex: int, gridEntity: GridEntity) {
 
   if (gridEntityTuple === undefined || gridEntityTuple[0] !== gridEntityType) {
     updateTupleInMap(gridEntity);
-    postGridEntityInitFire(gridEntity);
+
+    const gridEntityTypeCustom = getCustomGridEntityType(gridEntity);
+    if (gridEntityTypeCustom === undefined) {
+      postGridEntityInitFire(gridEntity);
+    } else {
+      postGridEntityCustomInitFire(gridEntity, gridEntityTypeCustom);
+    }
   }
 }
 

package/src/callbacks/postPlayerChangeStat.ts

@@ -1,8 +1,7 @@
-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 { StatType } from "../enums/StatType";
 import { saveDataManager } from "../features/saveDataManager/exports";
 import { isBitSet128 } from "../functions/bitSet128";
 import { colorEquals, isColor } from "../functions/color";
@@ -10,14 +9,14 @@ import { getEnumValues } from "../functions/enums";
 import { getPlayerIndex } from "../functions/playerIndex";
 import { getPlayerStat } from "../functions/playerStats";
 import { isBoolean, isNumber } from "../functions/types";
+import { isVector, vectorEquals } from "../functions/vector";
 import { PlayerIndex } from "../types/PlayerIndex";
+import { PossibleStatType } from "../types/PossibleStatType";
 import {
   postPlayerChangeStatFire,
   postPlayerChangeStatHasSubscriptions,
 } from "./subscriptions/postPlayerChangeStat";
 
-type PossibleStatType = number | boolean | BitFlags<TearFlag> | Color;
-
 const v = {
   run: {
     playersStatMap: new DefaultMap<
@@ -100,6 +99,11 @@ function statEquals(
     return colorEquals(oldValue, newValue);
   }
 
+  const isVectorStat = isVector(oldValue) && isVector(newValue);
+  if (isVectorStat) {
+    return vectorEquals(oldValue, newValue);
+  }
+
   error(
     'Failed to determine the type of a stat in the "POST_PLAYER_CHANGE_STAT" callback.',
   );

package/src/callbacks/subscriptions/postGridEntityCustomBroken.ts

@@ -10,6 +10,10 @@ export type PostGridEntityCustomBrokenRegisterParameters = [
 
 const subscriptions: PostGridEntityCustomBrokenRegisterParameters[] = [];
 
+export function postGridEntityCustomBrokenHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
 export function postGridEntityCustomBrokenRegister(
   ...args: PostGridEntityCustomBrokenRegisterParameters
 ): void {

package/src/callbacks/subscriptions/postGridEntityCustomInit.ts

@@ -0,0 +1,38 @@
+import { GridEntityType } from "isaac-typescript-definitions";
+
+export type PostGridEntityCustomInitRegisterParameters = [
+  callback: (
+    gridEntity: GridEntity,
+    gridEntityTypeCustom: GridEntityType,
+  ) => void,
+  gridEntityTypeCustom?: GridEntityType,
+];
+
+const subscriptions: PostGridEntityCustomInitRegisterParameters[] = [];
+
+export function postGridEntityCustomInitHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+export function postGridEntityCustomInitRegister(
+  ...args: PostGridEntityCustomInitRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+export function postGridEntityCustomInitFire(
+  gridEntity: GridEntity,
+  gridEntityTypeCustom: GridEntityType,
+): void {
+  for (const [callback, callbackGridEntityTypeCustom] of subscriptions) {
+    // Handle the optional 2nd callback argument.
+    if (
+      callbackGridEntityTypeCustom !== undefined &&
+      callbackGridEntityTypeCustom !== gridEntityTypeCustom
+    ) {
+      continue;
+    }
+
+    callback(gridEntity, gridEntityTypeCustom);
+  }
+}

package/src/callbacks/subscriptions/postGridEntityCustomRemove.ts

@@ -0,0 +1,35 @@
+import { GridEntityType } from "isaac-typescript-definitions";
+
+export type PostGridEntityCustomRemoveRegisterParameters = [
+  callback: (gridIndex: int, gridEntityTypeCustom: GridEntityType) => void,
+  gridEntityTypeCustom?: GridEntityType,
+];
+
+const subscriptions: PostGridEntityCustomRemoveRegisterParameters[] = [];
+
+export function postGridEntityCustomRemoveHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+export function postGridEntityCustomRemoveRegister(
+  ...args: PostGridEntityCustomRemoveRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+export function postGridEntityCustomRemoveFire(
+  gridIndex: int,
+  gridEntityTypeCustom: GridEntityType,
+): void {
+  for (const [callback, callbackGridEntityTypeCustom] of subscriptions) {
+    // Handle the optional 2nd callback argument.
+    if (
+      callbackGridEntityTypeCustom !== undefined &&
+      callbackGridEntityTypeCustom !== gridEntityTypeCustom
+    ) {
+      continue;
+    }
+
+    callback(gridIndex, gridEntityTypeCustom);
+  }
+}

package/src/callbacks/subscriptions/postGridEntityCustomStateChanged.ts

@@ -0,0 +1,42 @@
+import { GridEntityType } from "isaac-typescript-definitions";
+
+export type PostGridEntityCustomStateChangedRegisterParameters = [
+  callback: (
+    gridEntity: GridEntity,
+    gridEntityTypeCustom: GridEntityType,
+    oldState: int,
+    newState: int,
+  ) => void,
+  gridEntityTypeCustom?: GridEntityType,
+];
+
+const subscriptions: PostGridEntityCustomStateChangedRegisterParameters[] = [];
+
+export function postGridEntityCustomStateChangedHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+export function postGridEntityCustomStateChangedRegister(
+  ...args: PostGridEntityCustomStateChangedRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+export function postGridEntityCustomStateChangedFire(
+  gridEntity: GridEntity,
+  gridEntityTypeCustom: GridEntityType,
+  oldState: int,
+  newState: int,
+): void {
+  for (const [callback, callbackGridEntityTypeCustom] of subscriptions) {
+    // Handle the optional 2nd callback argument.
+    if (
+      callbackGridEntityTypeCustom !== undefined &&
+      callbackGridEntityTypeCustom !== gridEntityTypeCustom
+    ) {
+      continue;
+    }
+
+    callback(gridEntity, gridEntityTypeCustom, oldState, newState);
+  }
+}

package/src/callbacks/subscriptions/postPlayerChangeStat.ts

@@ -1,18 +1,15 @@
-import {
-  PlayerType,
-  PlayerVariant,
-  TearFlag,
-} from "isaac-typescript-definitions";
+import { PlayerType, PlayerVariant } from "isaac-typescript-definitions";
 import { StatType } from "../../enums/StatType";
 import { StatTypeType } from "../../interfaces/StatTypeType";
+import { PossibleStatType } from "../../types/PossibleStatType";
 
 export type PostPlayerChangeStatRegisterParameters = [
   callback: (
     player: EntityPlayer,
     statType: StatType,
     difference: int,
-    oldValue: number | boolean | BitFlags<TearFlag> | Color | Vector,
-    newValue: number | boolean | BitFlags<TearFlag> | Color | Vector,
+    oldValue: PossibleStatType,
+    newValue: PossibleStatType,
   ) => void,
   playerVariant?: PlayerVariant,
   character?: PlayerType,

package/src/classes/DefaultMap.ts

@@ -1,7 +1,8 @@
 import { isFunction, isPrimitive } from "../functions/types";
 
 /**
- * `DefaultMap` is a data structure that makes working with default values easier.
+ * `DefaultMap` is a data structure that makes working with default values easier. It extends a
+ * `Map` and adds additional methods.
  *
  * It is a common pattern to look up a value in a `Map`, and then, if the value does not exist, set
  * a default value for the key, and then return the default value. `DefaultMap` abstracts this
@@ -89,7 +90,7 @@ export class DefaultMap<Key, Value, Args extends unknown[] = []> extends Map<
 
   /**
    * See the main `DefaultMap` documentation:
-   * https://isaacscript.github.io/isaacscript-common/classes/classes_DefaultMap.DefaultMap
+   * https://isaacscript.github.io/isaacscript-common/other/classes/DefaultMap
    */
   constructor(
     defaultValueOrFactoryFunction: Value | FactoryFunction<Value, Args>,

package/src/enums/ModCallbackCustom.ts

@@ -216,7 +216,7 @@ export enum ModCallbackCustom {
 
   /**
    * Fires from the `POST_EFFECT_UPDATE` callback when an effect's state has changed from what it
-   * was on the previous frame.
+   * was on the previous frame. (In this context, "state" refers to the `EntityEffect.State` field.)
    *
    * When registering the callback, takes an optional second argument that will make the callback
    * only fire if it matches the `EffectVariant` provided.
@@ -258,7 +258,8 @@ export enum ModCallbackCustom {
 
   /**
    * Fires from the `POST_FAMILIAR_UPDATE` callback when a familiar's state has changed from what it
-   * was on the previous frame.
+   * was on the previous frame. (In this context, "state" refers to the `EntityFamiliar.State`
+   * field.)
    *
    * When registering the callback, takes an optional second argument that will make the callback
    * only fire if it matches the `FamiliarVariant` provided.
@@ -337,7 +338,8 @@ export enum ModCallbackCustom {
 
   /**
    * Fires from the `POST_UPDATE` callback when a grid entity changes to a state that corresponds to
-   * the broken state for the respective grid entity type.
+   * the broken state for the respective grid entity type. (For example, this will fire for a
+   * `GridEntityType.ROCK` (2) when its state changes to `RockState.BROKEN` (2).)
    *
    * When registering the callback, takes an optional second argument that will make the callback
    * only fire if it matches the `GridEntityType` provided.
@@ -364,12 +366,8 @@ export enum ModCallbackCustom {
   POST_GRID_ENTITY_COLLISION,
 
   /**
-   * Fires from the `POST_UPDATE` callback when a grid entity created with the
-   * `spawnCustomGridEntity` helper function is hit by an explosion.
-   *
-   * In most cases, you will want to remove the grid entity inside of this callback in order to
-   * prevent further "broken" callbacks from firing. (This would not be the case if you were trying
-   * to emulate a super tinted rock that takes multiple explosions to destroy, for example.)
+   * The same as the `POST_GRID_ENTITY_BROKEN` callback, but only fires for grid entities created
+   * with the `spawnCustomGridEntity` helper function.
    *
    * When registering the callback, takes an optional second argument that will make the callback
    * only fire if it matches the `GridEntityType` provided.
@@ -384,24 +382,57 @@ export enum ModCallbackCustom {
   POST_GRID_ENTITY_CUSTOM_BROKEN,
 
   /**
-   * Fires from the `POST_UPDATE` callback a new entity collides with a grid entity created with the
-   * `spawnCustomGridEntity` helper function.
+   * The same as the `POST_GRID_ENTITY_COLLISION` callback, but only fires for grid entities created
+   * with the `spawnCustomGridEntity` helper function.
    *
    * When registering the callback, takes an optional second argument that will make the callback
    * only fire if it matches the `GridEntityType` provided.
    *
    * ```ts
-   * function postGridEntityCustomRender(
+   * function postGridEntityCustomCollision(
    *   gridEntity: GridEntity,
    *   gridEntityTypeCustom: GridEntityType,
+   *   entity: Entity,
    * ): void {}
    * ```
    */
   POST_GRID_ENTITY_CUSTOM_COLLISION,
 
   /**
-   * Fires from the `POST_RENDER` callback on every frame that a grid entity created with the
-   * `spawnCustomGridEntity` helper function exists.
+   * The same as the `POST_GRID_ENTITY_INIT` callback, but only fires for grid entities created with
+   * the `spawnCustomGridEntity` helper function.
+   *
+   * When registering the callback, takes an optional second argument that will make the callback
+   * only fire if it matches the `GridEntityType` provided.
+   *
+   * ```ts
+   * function postGridEntityCustomInit(
+   *   gridEntity: GridEntity,
+   *   gridEntityTypeCustom: GridEntityType,
+   * ): void {}
+   * ```
+   */
+  POST_GRID_ENTITY_CUSTOM_INIT,
+
+  /**
+   * The same as the `POST_GRID_ENTITY_REMOVE` callback, but only fires for grid entities created
+   * with the `spawnCustomGridEntity` helper function.
+   *
+   * When registering the callback, takes an optional second argument that will make the callback
+   * only fire if it matches the `GridEntityType` provided.
+   *
+   * ```ts
+   * function postGridEntityCustomRemove(
+   *   gridIndex: int,
+   *   gridEntityTypeCustom: GridEntityType,
+   * ): void {}
+   * ```
+   */
+  POST_GRID_ENTITY_CUSTOM_REMOVE,
+
+  /**
+   * The same as the `POST_GRID_ENTITY_RENDER` callback, but only fires for grid entities created
+   * with the `spawnCustomGridEntity` helper function.
    *
    * When registering the callback, takes an optional second argument that will make the callback
    * only fire if it matches the `GridEntityType` provided.
@@ -416,8 +447,26 @@ export enum ModCallbackCustom {
   POST_GRID_ENTITY_CUSTOM_RENDER,
 
   /**
-   * Fires from the `POST_UPDATE` callback on every frame that a grid entity created with the
-   * `spawnCustomGridEntity` helper function exists.
+   * The same as the `POST_GRID_ENTITY_STATE_CHANGED` callback, but only fires for grid entities
+   * created with the `spawnCustomGridEntity` helper function.
+   *
+   * When registering the callback, takes an optional second argument that will make the callback
+   * only fire if it matches the `GridEntityType` provided.
+   *
+   * ```ts
+   * function postGridEntityCustomStateChanged(
+   *   gridEntity: GridEntity,
+   *   gridEntityTypeCustom: GridEntityType,
+   *   oldState: int,
+   *   newState: int,
+   * ): void {}
+   * ```
+   */
+  POST_GRID_ENTITY_CUSTOM_STATE_CHANGED,
+
+  /**
+   * The same as the `POST_GRID_ENTITY_UPDATE` callback, but only fires for grid entities created
+   * with the `spawnCustomGridEntity` helper function.
    *
    * When registering the callback, takes an optional second argument that will make the callback
    * only fire if it matches the `GridEntityType` provided.
@@ -452,6 +501,8 @@ export enum ModCallbackCustom {
    * Fires from the `POST_UPDATE` callback when a new grid entity is removed. Specifically, this on
    * the frame after it no longer exists (where it did exist a frame ago).
    *
+   * (Leaving a room with a grid entity does not count as "removing" it.)
+   *
    * When registering the callback, takes an optional second argument that will make the callback
    * only fire if it matches the `GridEntityType` provided.
    *
@@ -479,7 +530,8 @@ export enum ModCallbackCustom {
   POST_GRID_ENTITY_RENDER,
 
   /**
-   * Fires from the `POST_UPDATE` callback when a grid entity changes its state.
+   * Fires from the `POST_UPDATE` callback when a grid entity changes its state. (In this context,
+   * "state" refers to the `GridEntity.State` field.)
    *
    * When registering the callback, takes an optional second argument that will make the callback
    * only fire if it matches the `GridEntityType` provided.
@@ -670,7 +722,7 @@ export enum ModCallbackCustom {
 
   /**
    * Fires from the `POST_NPC_UPDATE` callback when an NPC's state has changed from what it was on
-   * the previous frame.
+   * the previous frame. (In this context, "state" refers to the `EntityNPC.State` field.)
    *
    * - When registering the callback, takes an optional second argument that will make the callback
    *   only fire if it matches the `EntityType` provided.
@@ -758,7 +810,7 @@ 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.
+   * on the previous frame. (In this context, "state" refers to the `EntityPickup.State` field.)
    *
    * When registering the callback, takes an optional second argument that will make the callback
    * only fire if it matches the `PickupVariant` provided.
@@ -1110,7 +1162,8 @@ export enum ModCallbackCustom {
   POST_ROCK_UPDATE,
 
   /**
-   * Fires from the `POST_UPDATE` callback when the clear state of a room changes.
+   * Fires from the `POST_UPDATE` callback when the clear state of a room changes (as according to
+   * the `Room.IsClear` method).
    *
    * When registering the callback, takes an optional second argument that will make the callback
    * only fire if the room clear state matches the boolean provided.

package/src/enums/StatType.ts

@@ -39,9 +39,9 @@ export enum StatType {
   /** 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.)
+  /** Corresponds to `CacheFlag.SIZE` (1 << 11) and `EntityPlayer.SpriteScale`. */
+  SIZE,
+
   // - `CacheFlag.COLOR` (1 << 12) does not have a corresponding `EntityPlayer` field.
   // - `CacheFlag.PICKUP_VISION` (1 << 13) does not have a corresponding `EntityPlayer` field.
 }