isaacscript-common 20.3.2 → 20.4.1

package/src/enums/ISCFeature.ts

@@ -10,6 +10,7 @@ export enum ISCFeature {
   ITEM_PICKUP_DETECTION,
   PLAYER_COLLECTIBLE_DETECTION,
   PLAYER_REORDERED_CALLBACKS,
+  SLOT_DESTROYED_DETECTION,
   SLOT_RENDER_DETECTION,
   SLOT_UPDATE_DETECTION,
 

package/src/enums/ModCallbackCustom.ts

@@ -1636,8 +1636,34 @@ export enum ModCallbackCustom {
   POST_SLOT_COLLISION,
 
   /**
-   * Fires from the `POST_RENDER` callback when a slot plays the animation that indicates that it
-   * has broken.
+   * Fires from the `POST_SLOT_UPDATE` or the `POST_ENTITY_REMOVE` callback when a slot machine is
+   * destroyed or a beggar is removed.
+   *
+   * This callback will fire in four different kinds of situations:
+   *
+   * 1. When slot machine entities (e.g. `SlotVariant.SLOT_MACHINE` and
+   *    `SlotVariant.BLOOD_DONATION_MACHINE`) are destroyed with an explosion. When this happens,
+   *    they typically stay in the room and can be pushed around. This state is detected via a
+   *    change in the `GridCollisionClass`.
+   * 2. When slot machine entities pay out with a collectible item. When this happens, they
+   *    immediately despawn without playing any special animation.
+   * 3. When beggars are destroyed with an explosion. When this happens, they immediately despawn
+   *    without playing any special animation.
+   * 4. When beggars pay out with a collectible item. When this happens, they despawn after playing
+   *    the "Teleport" animation. (This is not technically a "destruction" event, but the callback
+   *    will fire for this to remain consistent with the other types of slot entities.)
+   *
+   * Depending on the specific types of slot removal that you need to detect, you can filter using:
+   *
+   * 1. The `isSlotMachine` helper function to differentiate between slot machines and beggars.
+   * 2. The passed callback argument of `SlotDestructionType` to differentiate between bombed slots
+   *    and slots that paid out with a collectible item.
+   *
+   * Note that when a Crane Game explodes after paying out three collectibles, the
+   * `SlotDestructionType` will be equal to `SlotDestructionType.NORMAL` instead of
+   * `SlotDestructionType.COLLECTIBLE_PAYOUT` like you might expect. (This is because it only
+   * explodes after a short delay, and when doing so, it produces rewards in the same way that would
+   * happen if you bombed it.)
    *
    * When registering the callback with the `ModUpgraded.AddCallbackCustom` method:
    * - You can provide an optional third argument that will make the callback only fire if it

package/src/enums/SlotDestructionType.ts

@@ -1,5 +1,19 @@
 /** This is used in the `POST_SLOT_DESTROYED` custom callback. */
 export enum SlotDestructionType {
+  /**
+   * When a machine or a beggar is blown up by a bomb or is otherwise removed without spawning a
+   * collectible.
+   *
+   * Note that the destruction type for a Crane Game will be `SlotDestructionType.NORMAL`, even if
+   * it destroyed via spawning three separate collectibles.
+   */
   NORMAL,
+
+  /**
+   * When a machine or a beggar is removed while spawning a collectible reward.
+   *
+   * Note that the destruction type for a Crane Game will be `SlotDestructionType.NORMAL`, even if
+   * it destroyed via spawning three separate collectibles.
+   */
   COLLECTIBLE_PAYOUT,
 }

package/src/features.ts

@@ -10,6 +10,7 @@ import { GridEntityUpdateDetection } from "./classes/features/callbackLogic/Grid
 import { ItemPickupDetection } from "./classes/features/callbackLogic/ItemPickupDetection";
 import { PlayerCollectibleDetection } from "./classes/features/callbackLogic/PlayerCollectibleDetection";
 import { PlayerReorderedCallbacks } from "./classes/features/callbackLogic/PlayerReorderedCallbacks";
+import { SlotDestroyedDetection } from "./classes/features/callbackLogic/SlotDestroyedDetection";
 import { SlotRenderDetection } from "./classes/features/callbackLogic/SlotRenderDetection";
 import { SlotUpdateDetection } from "./classes/features/callbackLogic/SlotUpdateDetection";
 import { CharacterHealthConversion } from "./classes/features/other/CharacterHealthConversion";
@@ -71,6 +72,7 @@ export interface ISCFeatureToClass {
   [ISCFeature.ITEM_PICKUP_DETECTION]: ItemPickupDetection;
   [ISCFeature.PLAYER_COLLECTIBLE_DETECTION]: PlayerCollectibleDetection;
   [ISCFeature.PLAYER_REORDERED_CALLBACKS]: PlayerReorderedCallbacks;
+  [ISCFeature.SLOT_DESTROYED_DETECTION]: SlotDestroyedDetection;
   [ISCFeature.SLOT_RENDER_DETECTION]: SlotRenderDetection;
   [ISCFeature.SLOT_UPDATE_DETECTION]: SlotUpdateDetection;
 
@@ -222,6 +224,10 @@ export function getFeatures(
       callbacks[ModCallbackCustom.POST_PLAYER_RENDER_REORDERED],
       callbacks[ModCallbackCustom.POST_PLAYER_UPDATE_REORDERED],
     ),
+    [ISCFeature.SLOT_DESTROYED_DETECTION]: new SlotDestroyedDetection(
+      callbacks[ModCallbackCustom.POST_SLOT_DESTROYED],
+      roomHistory,
+    ),
     [ISCFeature.SLOT_RENDER_DETECTION]: new SlotRenderDetection(
       callbacks[ModCallbackCustom.POST_SLOT_RENDER],
       callbacks[ModCallbackCustom.POST_SLOT_ANIMATION_CHANGED],

package/src/functions/deepCopyTests.ts

@@ -6,7 +6,6 @@ import { deepCopy } from "./deepCopy";
 import { log } from "./log";
 import { isDefaultMap, isTSTLMap, isTSTLSet } from "./tstlClass";
 import { isNumber, isString, isTable } from "./types";
-import { printConsole } from "./utils";
 
 /**
  * Run the suite of tests that prove that the "deepCopy" helper function works properly.
@@ -41,7 +40,7 @@ export function runDeepCopyTests(): void {
 
   const successText = "All deep copy tests passed!";
   log(successText);
-  printConsole(successText);
+  print(successText);
 }
 
 function copiedObjectIsTable() {

package/src/functions/logMisc.ts

@@ -28,7 +28,6 @@ import { iterateTableInOrder } from "./table";
 import { getTrinketName } from "./trinkets";
 import { isDefaultMap, isTSTLMap, isTSTLSet } from "./tstlClass";
 import { isTable, isUserdata } from "./types";
-import { printConsole } from "./utils";
 import { vectorToString } from "./vector";
 
 /** Helper function to enumerate all of the values in an array. */
@@ -85,7 +84,7 @@ export function logEntityID(entity: Entity): void {
 export function logError(msg: string): void {
   const errorMsg = `Error: ${msg}`;
   log(errorMsg);
-  printConsole(errorMsg);
+  print(errorMsg);
 }
 
 /** Helper function for printing out every flag that is turned on. Useful when debugging. */

package/src/functions/mergeTests.ts

@@ -1,11 +1,10 @@
 import { DefaultMap } from "../classes/DefaultMap";
 import { SerializationType } from "../enums/SerializationType";
 import { deepCopy } from "./deepCopy";
-import { log } from "./log";
 import { merge } from "./merge";
 import { isRNG, newRNG } from "./rng";
 import { isSerializedIsaacAPIClass } from "./serialization";
-import { printConsole } from "./utils";
+import { logAndPrint } from "./utils";
 import { isVector, serializeVector } from "./vector";
 
 /**
@@ -29,8 +28,7 @@ export function runMergeTests(): void {
   oldTableHasRNGSerialized();
 
   const successText = "All merge tests passed!";
-  log(successText);
-  printConsole(successText);
+  logAndPrint(successText);
 }
 
 function oldTableHasUpdatedValue() {

package/src/functions/slots.ts

@@ -0,0 +1,23 @@
+import { SlotVariant } from "isaac-typescript-definitions";
+import { isSlot } from "./entityTypes";
+
+const SLOT_MACHINE_VARIANTS: ReadonlySet<SlotVariant> = new Set([
+  SlotVariant.SLOT_MACHINE, // 1
+  SlotVariant.BLOOD_DONATION_MACHINE, // 2,
+  SlotVariant.FORTUNE_TELLING_MACHINE, // 3
+  SlotVariant.DONATION_MACHINE, // 8
+  SlotVariant.SHOP_RESTOCK_MACHINE, // 10
+  SlotVariant.GREED_DONATION_MACHINE, // 11
+  SlotVariant.MOMS_DRESSING_TABLE, // 12
+  SlotVariant.CRANE_GAME, // 16
+  SlotVariant.CONFESSIONAL, // 17
+]);
+
+/** Returns true for the specific variants of `EntityType.SLOT` that are machines. */
+export function isSlotMachine(entity: Entity): boolean {
+  if (!isSlot(entity)) {
+    return false;
+  }
+
+  return SLOT_MACHINE_VARIANTS.has(entity.Variant);
+}

package/src/functions/utils.ts

@@ -1,6 +1,7 @@
 import { RenderMode } from "isaac-typescript-definitions";
 import { game } from "../core/cachedClasses";
 import { CONSOLE_COMMANDS_SET } from "../sets/consoleCommandsSet";
+import { log } from "./log";
 
 /**
  * Helper function to return an array of integers with the specified range, inclusive on the lower
@@ -103,18 +104,18 @@ export function isVanillaConsoleCommand(commandName: string): boolean {
 }
 
 /**
- * Helper function to print something to the in-game console. Use this instead of invoking the
- * `Isaac.ConsoleOutput` method directly because it will automatically insert a newline at the end
- * of the message (which `Isaac.ConsoleOutput` does not do by default).
+ * Helper function to log a message to the "log.txt" file and to print it to the screen at the same
+ * time.
  */
-export function printConsole(msg: string): void {
-  Isaac.ConsoleOutput(`${msg}\n`);
+export function logAndPrint(msg: string): void {
+  log(msg);
+  print(msg);
 }
 
 /** Helper function to print whether something was enabled or disabled to the in-game console. */
 export function printEnabled(enabled: boolean, description: string): void {
   const enabledText = enabled ? "Enabled" : "Disabled";
-  printConsole(`${enabledText} ${description}.`);
+  print(`${enabledText} ${description}.`);
 }
 
 /**

package/src/index.ts

@@ -103,6 +103,7 @@ export * from "./functions/run";
 export * from "./functions/seeds";
 export * from "./functions/serialization";
 export * from "./functions/set";
+export * from "./functions/slots";
 export * from "./functions/sound";
 export * from "./functions/spawnCollectible";
 export * from "./functions/sprites";

package/src/interfaces/RoomDescription.ts

@@ -8,6 +8,7 @@ import {
 
 /** This is used by the room history feature of the standard library. */
 export interface RoomDescription {
+  startSeedString: string;
   stage: LevelStage;
   stageType: StageType;
   stageID: StageID;