isaacscript-common 6.13.0 → 6.16.0

package/dist/objects/isaacAPIClassTypeToFunctions.lua

@@ -0,0 +1,25 @@
+local ____exports = {}
+local ____CopyableIsaacAPIClassType = require("enums.private.CopyableIsaacAPIClassType")
+local CopyableIsaacAPIClassType = ____CopyableIsaacAPIClassType.CopyableIsaacAPIClassType
+local ____color = require("functions.color")
+local copyColor = ____color.copyColor
+local deserializeColor = ____color.deserializeColor
+local isSerializedColor = ____color.isSerializedColor
+local serializeColor = ____color.serializeColor
+local ____kColor = require("functions.kColor")
+local copyKColor = ____kColor.copyKColor
+local deserializeKColor = ____kColor.deserializeKColor
+local isSerializedKColor = ____kColor.isSerializedKColor
+local serializeKColor = ____kColor.serializeKColor
+local ____rng = require("functions.rng")
+local copyRNG = ____rng.copyRNG
+local deserializeRNG = ____rng.deserializeRNG
+local isSerializedRNG = ____rng.isSerializedRNG
+local serializeRNG = ____rng.serializeRNG
+local ____vector = require("functions.vector")
+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}}
+return ____exports

package/dist/types/IsaacAPIClass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IsaacAPIClass.d.ts","sourceRoot":"","sources":["../../src/types/IsaacAPIClass.ts"],"names":[],"mappings":";AAAA,oBAAY,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACpD,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACvC,CAAC"}

package/dist/types/SerializedIsaacAPIClass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SerializedIsaacAPIClass.d.ts","sourceRoot":"","sources":["../../src/types/SerializedIsaacAPIClass.ts"],"names":[],"mappings":";AAAA,oBAAY,uBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC9D,QAAQ,CAAC,8BAA8B,EAAE,MAAM,CAAC;CACjD,CAAC"}

package/dist/types/TSTLClass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TSTLClass.d.ts","sourceRoot":"","sources":["../../src/types/TSTLClass.ts"],"names":[],"mappings":";AAAA,oBAAY,SAAS,GAAG,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG;IACnD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "6.13.0",
+  "version": "6.16.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.0.34"
+    "isaac-typescript-definitions": "^3.1.0"
   }
 }

package/src/callbacks/postGridEntityCustomCollision.ts

@@ -0,0 +1,74 @@
+import { GridCollisionClass, ModCallback } from "isaac-typescript-definitions";
+import { DefaultMap } from "../classes/DefaultMap";
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { getCustomGridEntities } from "../features/customGridEntity";
+import { saveDataManager } from "../features/saveDataManager/exports";
+import { getCollidingEntitiesWithGridEntity } from "../functions/gridEntities";
+import {
+  postGridEntityCustomCollisionFire,
+  postGridEntityCustomCollisionHasSubscriptions,
+} from "./subscriptions/postGridEntityCustomCollision";
+
+const v = {
+  room: {
+    /** Indexed by grid entity pointer hash. */
+    collidingEntitiesMap: new DefaultMap<PtrHash, Set<PtrHash>>(
+      () => new Set(),
+    ),
+  },
+};
+
+/** @internal */
+export function postGridEntityCustomCollisionInit(mod: ModUpgraded): void {
+  saveDataManager("postGridEntityCustomCollisionInit", v, hasSubscriptions);
+
+  mod.AddCallback(ModCallback.POST_UPDATE, postUpdate); // 1
+}
+
+function hasSubscriptions() {
+  return postGridEntityCustomCollisionHasSubscriptions();
+}
+
+// ModCallback.POST_UPDATE (1)
+function postUpdate() {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  const customGridEntities = getCustomGridEntities();
+  for (const [gridEntity, data] of customGridEntities) {
+    if (gridEntity.CollisionClass === GridCollisionClass.NONE) {
+      continue;
+    }
+
+    // The following code is copied from the `POST_GRID_ENTITY_COLLISION` callback.
+    const gridEntityPtrHash = GetPtrHash(gridEntity);
+    const oldCollidingEntities =
+      v.room.collidingEntitiesMap.getAndSetDefault(gridEntityPtrHash);
+
+    // Check for new colliding entities.
+    const collidingEntities = getCollidingEntitiesWithGridEntity(gridEntity);
+    for (const entity of collidingEntities) {
+      const entityPtrHash = GetPtrHash(entity);
+      if (!oldCollidingEntities.has(entityPtrHash)) {
+        oldCollidingEntities.add(entityPtrHash);
+        postGridEntityCustomCollisionFire(
+          gridEntity,
+          data.gridEntityTypeCustom,
+          entity,
+        );
+      }
+    }
+
+    // Remove old colliding entities.
+    const collidingEntitiesPtrHashes = collidingEntities.map((entity) =>
+      GetPtrHash(entity),
+    );
+    const collidingEntitiesPtrHashSet = new Set(collidingEntitiesPtrHashes);
+    for (const oldCollidingEntityPtrHash of oldCollidingEntities.values()) {
+      if (!collidingEntitiesPtrHashSet.has(oldCollidingEntityPtrHash)) {
+        oldCollidingEntities.delete(oldCollidingEntityPtrHash);
+      }
+    }
+  }
+}

package/src/callbacks/postGridEntityCustomRender.ts

@@ -1,29 +1,13 @@
-import { GridEntityType, ModCallback } from "isaac-typescript-definitions";
+import { ModCallback } from "isaac-typescript-definitions";
 import { ModUpgraded } from "../classes/ModUpgraded";
 import { getCustomGridEntities } from "../features/customGridEntity";
-import { saveDataManager } from "../features/saveDataManager/exports";
 import {
   postGridEntityCustomRenderFire,
   postGridEntityCustomRenderHasSubscriptions,
 } from "./subscriptions/postGridEntityCustomRender";
 
-type GridEntityTuple = [
-  gridEntityType: GridEntityType,
-  gridEntityVariant: int,
-  state: int,
-];
-
-const v = {
-  room: {
-    /** Indexed by grid index. */
-    initializedGridEntities: new Map<int, GridEntityTuple>(),
-  },
-};
-
 /** @internal */
 export function postGridEntityCustomRenderInit(mod: ModUpgraded): void {
-  saveDataManager("postGridEntityCustomRender", v, hasSubscriptions);
-
   mod.AddCallback(ModCallback.POST_RENDER, postRender); // 2
 }
 

package/src/callbacks/postGridEntityCustomUpdate.ts

@@ -1,29 +1,13 @@
-import { GridEntityType, ModCallback } from "isaac-typescript-definitions";
+import { ModCallback } from "isaac-typescript-definitions";
 import { ModUpgraded } from "../classes/ModUpgraded";
 import { getCustomGridEntities } from "../features/customGridEntity";
-import { saveDataManager } from "../features/saveDataManager/exports";
 import {
   postGridEntityCustomUpdateFire,
   postGridEntityCustomUpdateHasSubscriptions,
 } from "./subscriptions/postGridEntityCustomUpdate";
 
-type GridEntityTuple = [
-  gridEntityType: GridEntityType,
-  gridEntityVariant: int,
-  state: int,
-];
-
-const v = {
-  room: {
-    /** Indexed by grid index. */
-    initializedGridEntities: new Map<int, GridEntityTuple>(),
-  },
-};
-
 /** @internal */
 export function postGridEntityCustomUpdateInit(mod: ModUpgraded): void {
-  saveDataManager("postGridEntityCustomUpdate", v, hasSubscriptions);
-
   mod.AddCallback(ModCallback.POST_UPDATE, postUpdate); // 1
 }
 

package/src/callbacks/subscriptions/postGridEntityCustomBroken.ts

@@ -0,0 +1,41 @@
+import { GridEntityType } from "isaac-typescript-definitions";
+
+export type PostGridEntityCustomBrokenRegisterParameters = [
+  callback: (
+    gridEntity: GridEntity,
+    gridEntityTypeCustom: GridEntityType,
+  ) => void,
+  gridEntityTypeCustom?: GridEntityType,
+];
+
+const subscriptions: PostGridEntityCustomBrokenRegisterParameters[] = [];
+
+/** @internal */
+export function postGridEntityCustomBrokenHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+/** @internal */
+export function postGridEntityCustomBrokenRegister(
+  ...args: PostGridEntityCustomBrokenRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+/** @internal */
+export function postGridEntityCustomBrokenFire(
+  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/postGridEntityCustomCollision.ts

@@ -0,0 +1,43 @@
+import { GridEntityType } from "isaac-typescript-definitions";
+
+export type PostGridEntityCustomCollisionRegisterParameters = [
+  callback: (
+    gridEntity: GridEntity,
+    gridEntityTypeCustom: GridEntityType,
+    entity: Entity,
+  ) => void,
+  gridEntityTypeCustom?: GridEntityType,
+];
+
+const subscriptions: PostGridEntityCustomCollisionRegisterParameters[] = [];
+
+/** @internal */
+export function postGridEntityCustomCollisionHasSubscriptions(): boolean {
+  return subscriptions.length > 0;
+}
+
+/** @internal */
+export function postGridEntityCustomCollisionRegister(
+  ...args: PostGridEntityCustomCollisionRegisterParameters
+): void {
+  subscriptions.push(args);
+}
+
+/** @internal */
+export function postGridEntityCustomCollisionFire(
+  gridEntity: GridEntity,
+  gridEntityTypeCustom: GridEntityType,
+  entity: Entity,
+): void {
+  for (const [callback, callbackGridEntityTypeCustom] of subscriptions) {
+    // Handle the optional 2nd callback argument.
+    if (
+      callbackGridEntityTypeCustom !== undefined &&
+      callbackGridEntityTypeCustom !== gridEntityTypeCustom
+    ) {
+      continue;
+    }
+
+    callback(gridEntity, gridEntityTypeCustom, entity);
+  }
+}

package/src/enums/ModCallbackCustom.ts

@@ -363,6 +363,42 @@ 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.)
+   *
+   * When registering the callback, takes an optional second argument that will make the callback
+   * only fire if it matches the `GridEntityType` provided.
+   *
+   * ```ts
+   * function postGridEntityCustomBroken(
+   *   gridEntity: GridEntity,
+   *   gridEntityTypeCustom: GridEntityType,
+   * ): void {}
+   * ```
+   */
+  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.
+   *
+   * 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(
+   *   gridEntity: GridEntity,
+   *   gridEntityTypeCustom: GridEntityType,
+   * ): 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.
@@ -371,7 +407,7 @@ export enum ModCallbackCustom {
    * only fire if it matches the `GridEntityType` provided.
    *
    * ```ts
-   * function postGridEntityRenderCustom(
+   * function postGridEntityCustomRender(
    *   gridEntity: GridEntity,
    *   gridEntityTypeCustom: GridEntityType,
    * ): void {}
@@ -387,7 +423,7 @@ export enum ModCallbackCustom {
    * only fire if it matches the `GridEntityType` provided.
    *
    * ```ts
-   * function postGridEntityUpdateCustom(
+   * function postGridEntityCustomUpdate(
    *   gridEntity: GridEntity,
    *   gridEntityTypeCustom: GridEntityType,
    * ): void {}

package/src/enums/private/SerializationBrand.ts

@@ -2,7 +2,7 @@
  * During serialization, we write an arbitrary string key to the object with a value of an empty
  * string. This is used during deserialization to instantiate the correct type of object.
  *
- * Note that we do not bother branding TSTL classes because we have no way to invoke the proper
+ * Note that we do not bother branding TSTL classes because we have no way to run the proper
  * constructor during deserialization.
  */
 export enum SerializationBrand {

package/src/features/customGridEntity.ts

@@ -1,17 +1,22 @@
 import {
   ActiveSlot,
   CollectibleType,
+  DamageFlag,
+  EntityType,
   GridCollisionClass,
   GridEntityType,
   ModCallback,
   UseFlag,
 } from "isaac-typescript-definitions";
 import { game } from "../cachedClasses";
+import { postGridEntityCustomBrokenFire } from "../callbacks/subscriptions/postGridEntityCustomBroken";
 import { DefaultMap } from "../classes/DefaultMap";
 import { ModUpgraded } from "../classes/ModUpgraded";
 import { DecorationVariant } from "../enums/DecorationVariant";
 import { ModCallbackCustom } from "../enums/ModCallbackCustom";
 import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import { spawnNPC } from "../functions/entitiesSpecific";
+import { hasFlag } from "../functions/flag";
 import {
   removeGridEntity,
   spawnGridEntityWithVariant,
@@ -33,6 +38,7 @@ const v = {
   },
 
   room: {
+    dummyPtrHashes: new Set<PtrHash>(),
     manuallyUsingShovel: false,
   },
 };
@@ -41,6 +47,12 @@ const v = {
 export function customGridEntityInit(mod: ModUpgraded): void {
   saveDataManager(FEATURE_NAME, v);
 
+  mod.AddCallback(
+    ModCallback.ENTITY_TAKE_DMG,
+    entityTakeDmgDummy,
+    EntityType.DUMMY,
+  ); // 11
+
   mod.AddCallback(
     ModCallback.PRE_USE_ITEM,
     preUseItemWeNeedToGoDeeper,
@@ -53,6 +65,51 @@ export function customGridEntityInit(mod: ModUpgraded): void {
   );
 }
 
+// ModCallback.ENTITY_TAKE_DMG (11)
+// EntityType.DUMMY (964)
+function entityTakeDmgDummy(
+  tookDamage: Entity,
+  _damageAmount: float,
+  damageFlags: BitFlags<DamageFlag>,
+  _damageSource: EntityRef,
+  _damageCountdownFrames: int,
+): boolean | undefined {
+  const ptrHash = GetPtrHash(tookDamage);
+  if (!v.room.dummyPtrHashes.has(ptrHash)) {
+    return undefined;
+  }
+
+  if (!hasFlag(damageFlags, DamageFlag.EXPLOSION)) {
+    return false;
+  }
+
+  const room = game.GetRoom();
+  const roomListIndex = getRoomListIndex();
+  const roomCustomGridEntities = v.level.customGridEntities.get(roomListIndex);
+  if (roomCustomGridEntities === undefined) {
+    return false;
+  }
+
+  const gridIndex = room.GetGridIndex(tookDamage.Position);
+  const data = roomCustomGridEntities.get(gridIndex);
+  if (data === undefined) {
+    return false;
+  }
+
+  const gridEntity = room.GetGridEntity(gridIndex);
+  if (gridEntity === undefined) {
+    error(
+      `Failed to get the grid entity for a custom grid entity that broke at grid index: ${gridIndex}`,
+    );
+  }
+
+  postGridEntityCustomBrokenFire(gridEntity, data.gridEntityTypeCustom);
+
+  // Even though the custom grid entity is now broke, we do not want to remove it, as the end-user
+  // could intend for it to persist with different graphics.
+  return false;
+}
+
 // ModCallback.PRE_USE_ITEM (23)
 // CollectibleType.WE_NEED_TO_GO_DEEPER (84)
 function preUseItemWeNeedToGoDeeper(
@@ -161,6 +218,10 @@ function postNewRoomReordered() {
  * @param defaultAnimation Optional. The name of the animation to play after the sprite is
  *                         initialized and after the player re-enters a room with this grid entity
  *                         in it. If not specified, the default animation in the anm2 will be used.
+ * @param breakable Optional. Whether or not an explosion will be able to break this grid entity.
+ *                  False by default. Use the `POST_GRID_ENTITY_CUSTOM_BROKEN` callback to detect
+ *                  when it breaks. Due to technical limitations, you can only set the grid entity
+ *                  to be breakable if it has a collision class.
  */
 export function spawnCustomGridEntity(
   gridEntityTypeCustom: GridEntityType,
@@ -168,9 +229,16 @@ export function spawnCustomGridEntity(
   gridCollisionClass: GridCollisionClass,
   anm2Path: string,
   defaultAnimation?: string,
+  breakable = false,
 ): GridEntity {
   errorIfFeaturesNotInitialized(FEATURE_NAME);
 
+  if (breakable && gridCollisionClass === GridCollisionClass.NONE) {
+    error(
+      "Failed to spawn a custom grid entity because it is not possible to have breakable custom grid entities with a collision class of: GridCollisionClass.NONE (0)",
+    );
+  }
+
   const room = game.GetRoom();
   const roomListIndex = getRoomListIndex();
   const gridIndex = isVector(gridIndexOrPosition)
@@ -215,6 +283,14 @@ export function spawnCustomGridEntity(
     v.level.customGridEntities.getAndSetDefault(roomListIndex);
   roomCustomGridEntities.set(gridIndex, customGridEntityData);
 
+  // We check to see if an explosion touches a custom grid entity by spawning a Dummy on top, and
+  // the monitoring for explosions in the `ENTITY_TAKE_DMG` callback.
+  if (breakable) {
+    const position = room.GetGridPosition(gridIndex);
+    const dummy = spawnNPC(EntityType.DUMMY, 0, 0, position);
+    dummy.Visible = false;
+  }
+
   return decoration;
 }
 
@@ -228,8 +304,8 @@ export function spawnCustomGridEntity(
  *                   Default is true. This is generally a good idea because if the room is not
  *                   updated, you will be unable to spawn another grid entity on the same tile until
  *                   a frame has passed. However, doing this is expensive, since it involves a call
- *                   to `Isaac.GetRoomEntities`, so set it to false if you need to invoke this
- *                   function multiple times.
+ *                   to `Isaac.GetRoomEntities`, so set it to false if you need to run this function
+ *                   multiple times.
  * @returns The grid entity that was removed. Returns undefined if no grid entity was found at the
  *          given location or if the given grid entity was not a custom grid entity.
  */

package/src/features/extraConsoleCommands/exports.ts

@@ -24,9 +24,10 @@ export function enableExtraConsoleCommands(mod: ModUpgraded): void {
  *
  * The standard library comes with many existing console commands that are useful for debugging, but
  * you can also add your own commands that are useful for your particular mod. It's easier to add
- * commands to the existing command system than to add logic manually to the ExecuteCmd callback.
+ * commands to the existing command system than to add your own logic manually to the `EXECUTE_CMD`
+ * callback.
  *
- * Before using this function, you must first invoke `enableExtraConsoleCommands`.
+ * Before using this function, you must first run the `enableExtraConsoleCommands` function.
  */
 export function addConsoleCommand(
   commandName: string,
@@ -59,7 +60,7 @@ export function addConsoleCommand(
  * The standard library comes with many existing console commands that are useful for debugging. If
  * you want to disable one of them, use this function.
  *
- * Before using this function, you must first invoke `enableExtraConsoleCommands`.
+ * Before using this function, you must first run the `enableExtraConsoleCommands` function.
  */
 export function removeConsoleCommand(commandName: string): void {
   if (!isExtraConsoleCommandsInitialized()) {

package/src/features/extraConsoleCommands/init.ts

@@ -267,6 +267,7 @@ function initMap() {
     "tearsDisplay",
     commandsDisplay.tearsDisplay,
   );
+  extraConsoleCommandsFunctionMap.set("tests", commands.tests);
   extraConsoleCommandsFunctionMap.set("tntDisplay", commandsDisplay.tntDisplay);
   extraConsoleCommandsFunctionMap.set(
     "tntsDisplay",

package/src/features/extraConsoleCommands/listCommands.ts

@@ -15,8 +15,8 @@
  * `enableExtraConsoleCommands`. (See the "Extra Console Commands (Init)" page for more details.)
  *
  * Each command has a corresponding function of the same name, but these functions are not actually
- * exported for end-user consumption (in order to cut down on namespace conflicts and because the
- * names of the functions are not very descriptive).
+ * exported for end-user consumption. (This is to cut down on namespace conflicts and because the
+ * names of the functions are not very descriptive.)
  *
  * @module
  */

package/src/functions/collectibles.ts

@@ -323,6 +323,10 @@ export function getCollectibleName(collectibleType: CollectibleType): string {
   return DEFAULT_COLLECTIBLE_NAME;
 }
 
+/**
+ * Helper function to get the "pedestal type" of a collectible. For example, it might be sitting on
+ * top of a broken Blood Donation Machine, or it might be sitting on top of an opened Spiked Chest.
+ */
 export function getCollectiblePedestalType(
   collectible: EntityPickup,
 ): CollectiblePedestalType {
@@ -338,8 +342,8 @@ export function getCollectiblePedestalType(
 }
 
 /**
- * Helper function to get the path to a collectible's quality. Returns 0 if the provided collectible
- * type was not valid.
+ * Helper function to get a collectible's quality. For example, Mom's Knife has a quality of 4.
+ * Returns 0 if the provided collectible type was not valid.
  */
 export function getCollectibleQuality(collectibleType: CollectibleType): int {
   const itemConfigItem = itemConfig.GetCollectible(collectibleType);