isaacscript-common 6.20.2 → 6.21.0

package/src/features/customTrapdoor/exports.ts

@@ -25,7 +25,6 @@ import v from "./v";
  * - custom destination (or custom logic for after the player enters)
  * - custom graphics
  * - custom logic for opening/closing
- * - TODO: player jumping animation?
  *
  * You can use this function to take the player to your custom stage.
  *
@@ -34,10 +33,12 @@ import v from "./v";
  *
  * @param gridIndexOrPosition The location in the room to spawn the trapdoor.
  * @param destination Optional. Used to specify where the player will go after jumping into the
- *                    trapdoor. Can either be a tuple containing the stage and stage type, or a
- *                    string containing the name of a custom stage. If not specified at all, then
- *                    the "normal" destination corresponding to the current stage and room will be
- *                    used (e.g. the next floor).
+ *                    trapdoor. Can either be a tuple or undefined. For example, a destination of
+ *                    `[LevelStage.CAVES_1, StageType.ORIGINAL]` corresponds to Caves 1, and a
+ *                    destination of `["Slaughterhouse", 1]` corresponds to a custom stage of
+ *                    Slaughterhouse 1. If the destination is set to undefined, then the "normal"
+ *                    destination corresponding to the current stage and room will be used (e.g. the
+ *                    next floor).
  * @param anm2Path Optional. The path to the anm2 file to use. By default, the vanilla trapdoor anm2
  *                 of "gfx/grid/door_11_trapdoor.anm2" will be used. The specified anm2 file must
  *                 have animations called "Opened", "Closed", and "Open Animation".
@@ -46,7 +47,9 @@ import v from "./v";
  */
 export function spawnCustomTrapdoor(
   gridIndexOrPosition: int | Vector,
-  destination?: [stage: LevelStage, stageType: StageType] | string,
+  destination?:
+    | [stage: LevelStage, stageType: StageType]
+    | [customStageName: string, floorNum: int],
   anm2Path = "gfx/grid/door_11_trapdoor.anm2",
   spawnOpen?: boolean,
 ): GridEntity {

package/src/features/customTrapdoor/init.ts

@@ -1,7 +1,10 @@
 import {
   Direction,
+  EntityCollisionClass,
+  EntityGridCollisionClass,
   ModCallback,
   RoomTransitionAnim,
+  StageType,
 } from "isaac-typescript-definitions";
 import { game } from "../../cachedClasses";
 import { ModUpgraded } from "../../classes/ModUpgraded";
@@ -10,7 +13,7 @@ import { StageTravelState } from "../../enums/private/StageTravelState";
 import { movePlayersToCenter } from "../../functions/playerCenter";
 import { getAllPlayers } from "../../functions/playerIndex";
 import { getRoomGridIndex, getRoomListIndex } from "../../functions/roomData";
-import { teleport } from "../../functions/rooms";
+import { teleport } from "../../functions/roomTransition";
 import { setStage } from "../../functions/stage";
 import { isString } from "../../functions/types";
 import { setCustomStage } from "../customStage/exports";
@@ -140,6 +143,10 @@ function checkPausingOnBlackComplete() {
 
     for (const player of getAllPlayers()) {
       player.AnimateAppear();
+
+      // We need to restore the original collision classes.
+      player.EntityCollisionClass = EntityCollisionClass.ALL;
+      player.GridCollisionClass = EntityGridCollisionClass.GROUND;
     }
   });
 
@@ -171,11 +178,15 @@ function goToCustomDestination() {
     return;
   }
 
-  if (isString(v.run.destination)) {
-    setCustomStage("Slaughterhouse");
+  const [arg1, arg2] = v.run.destination;
+
+  if (isString(arg1)) {
+    // A string represents a custom stage.
+    const firstFloor = arg2 === 1;
+    setCustomStage("Slaughterhouse", firstFloor);
   } else {
-    const [stage, stageType] = v.run.destination;
-    setStage(stage, stageType);
+    // A number represents a vanilla `LevelStage`.
+    setStage(arg1, arg2 as StageType);
   }
 }
 

package/src/features/customTrapdoor/touched.ts

@@ -114,8 +114,6 @@ function setPlayerAttributes(trapdoorPlayer: EntityPlayer, position: Vector) {
     // We don't want enemy attacks to move the players.
     player.EntityCollisionClass = EntityCollisionClass.NONE;
     player.GridCollisionClass = EntityGridCollisionClass.NONE;
-
-    player.SubType = -1;
   }
 }
 

package/src/features/customTrapdoor/v.ts

@@ -12,7 +12,7 @@ const v = {
 
     destination: null as
       | [stage: LevelStage, stageType: StageType]
-      | string
+      | [customStageName: string, floorNum: int]
       | null,
   },
 

package/src/features/extraConsoleCommands/commandsSubroutines.ts

@@ -10,7 +10,10 @@ import { HealthType } from "../../enums/HealthType";
 import { directionToVector } from "../../functions/direction";
 import { spawnGridEntityWithVariant } from "../../functions/gridEntities";
 import { getRoomGridIndexesForType } from "../../functions/levelGrid";
-import { logAllEntities, logAllGridEntities } from "../../functions/log";
+import {
+  logAllEntities,
+  logAllGridEntities,
+} from "../../functions/logEntities";
 import { addPlayerHealthType } from "../../functions/playerHealth";
 import { getRoomData, getRoomDescriptor } from "../../functions/roomData";
 import { changeRoom } from "../../functions/rooms";

package/src/features/saveDataManager/exports.ts

@@ -76,6 +76,9 @@ import { SAVE_DATA_MANAGER_FEATURE_NAME } from "./saveDataManagerConstants";
  *   can possibly run).
  * - Save data is recorded to disk in the `PRE_GAME_EXIT` callback.
  *
+ * You can put lots of data types on your variable objects, but not everything is supported. For the
+ * specific things that are supported, see the documentation for the `deepCopy` helper function.
+ *
  * Note that before using the save data manager, you must call the `upgradeMod` function. (Upgrade
  * your mod before registering any of your own callbacks so that the save data manager will run
  * before any of your code does.)

package/src/functions/collectibleSet.ts

@@ -58,7 +58,7 @@ function initCollectibleArraysAndSets() {
  * collectibles.
  *
  * Use this if you need to iterate over the collectibles in order. If you need to do O(1) lookups,
- * then use the `getCollectibleArray` helper function instead.
+ * then use the `getCollectibleSet` helper function instead.
  */
 export function getCollectibleArray(): readonly CollectibleType[] {
   // Lazy initialize the arrays/sets.

package/src/functions/doors.ts

@@ -181,6 +181,12 @@ export function getOppositeDoorSlot(doorSlot: DoorSlot): DoorSlot | undefined {
   return OPPOSITE_DOOR_SLOTS[doorSlot];
 }
 
+/**
+ * Helper function to get the door that leads to the "secret exit" off-grid room that takes you to
+ * the Repentance floor.
+ *
+ * Returns undefined if the room has no Repentance doors.
+ */
 export function getRepentanceDoor(): GridEntityDoor | undefined {
   const doors = getDoors();
   return doors.find((door) => isRepentanceDoor(door));
@@ -330,6 +336,10 @@ export function isHiddenSecretRoomDoor(door: GridEntityDoor): boolean {
   return isSecretRoomDoor(door) && animation === "Hidden";
 }
 
+/**
+ * Helper function to check if the provided door leads to the "secret exit" off-grid room that takes
+ * you to the Repentance floor.
+ */
 export function isRepentanceDoor(door: GridEntityDoor): boolean {
   // eslint-disable-next-line isaacscript/strict-enums
   return door.TargetRoomIndex === GridRoom.SECRET_EXIT;

package/src/functions/log.ts

@@ -1,10 +1,7 @@
 import {
   DamageFlag,
-  EffectVariant,
   EntityFlag,
-  EntityType,
   GameStateFlag,
-  GridEntityType,
   GridRoom,
   HeartSubType,
   LevelStateFlag,
@@ -17,10 +14,9 @@ import {
 import { game, sfxManager } from "../cachedClasses";
 import { arrayToString } from "./array";
 import { getCollectibleName } from "./collectibles";
-import { getEntities, getEntityID } from "./entities";
+import { getEntityID } from "./entities";
 import { getEnumEntries } from "./enums";
 import { hasFlag } from "./flag";
-import { getGridEntities, getGridEntityID } from "./gridEntities";
 import { getIsaacAPIClassName } from "./isaacAPIClass";
 import { getPlayerHealth } from "./playerHealth";
 import { getEffectsList, getPlayerName } from "./players";
@@ -32,18 +28,6 @@ import { isTable, isUserdata } from "./types";
 import { printConsole } from "./utils";
 import { vectorToString } from "./vector";
 
-const IGNORE_EFFECT_VARIANTS: ReadonlySet<EffectVariant> = new Set([
-  EffectVariant.BLOOD_EXPLOSION, // 2
-  EffectVariant.BLOOD_PARTICLE, // 5
-  EffectVariant.TINY_BUG, // 21
-  EffectVariant.TINY_FLY, // 33
-  EffectVariant.WATER_DROPLET, // 41
-  EffectVariant.WALL_BUG, // 68
-  EffectVariant.FALLING_EMBER, // 87
-  EffectVariant.LIGHT, // 121
-  EffectVariant.TADPOLE, // 158
-]);
-
 /**
  * Helper function to prefix the name of the function and the line number before a debug message.
  */
@@ -84,106 +68,6 @@ export function log(this: void, msg: string): void {
   Isaac.DebugString(debugMsg);
 }
 
-/** Helper function for printing out every entity (or filtered entity) in the current room. */
-export function logAllEntities(
-  this: void,
-  includeBackgroundEffects: boolean,
-  entityTypeFilter?: EntityType,
-): void {
-  let msg = "Entities in the room";
-  if (entityTypeFilter !== undefined) {
-    msg += ` (filtered to entity type ${entityTypeFilter})`;
-  } else if (!includeBackgroundEffects) {
-    msg += " (not including background effects)";
-  }
-  msg += ":\n";
-
-  const entities = getEntities();
-  let numMatchedEntities = 0;
-  entities.forEach((entity, i) => {
-    // If a filter was specified, exclude all entities outside of the filter.
-    if (entityTypeFilter !== undefined && entity.Type !== entityTypeFilter) {
-      return;
-    }
-
-    const effect = entity.ToEffect();
-    if (
-      !includeBackgroundEffects &&
-      effect !== undefined &&
-      IGNORE_EFFECT_VARIANTS.has(effect.Variant)
-    ) {
-      return;
-    }
-
-    msg += getEntityLogLine(entity, i + 1);
-    numMatchedEntities++;
-  });
-
-  if (numMatchedEntities === 0) {
-    msg += "(no entities matched)\n";
-  } else {
-    msg += `(${numMatchedEntities} total ${
-      numMatchedEntities === 1 ? "entity" : "entities"
-    })\n`;
-  }
-
-  log(msg);
-}
-
-/**
- * Helper function for printing out every grid entity (or filtered grid entity) in the current room.
- */
-export function logAllGridEntities(
-  this: void,
-  includeWalls: boolean,
-  gridEntityTypeFilter?: GridEntityType,
-): void {
-  let msg = "Grid entities in the room";
-  if (gridEntityTypeFilter !== undefined) {
-    msg += ` (filtered to grid entity type ${gridEntityTypeFilter})`;
-  } else if (!includeWalls) {
-    msg += " (not including walls)";
-  }
-  msg += ":\n";
-
-  const gridEntities = getGridEntities();
-  let numMatchedEntities = 0;
-  gridEntities.forEach((gridEntity) => {
-    const gridEntityIndex = gridEntity.GetGridIndex();
-    const gridEntityType = gridEntity.GetType();
-
-    // If a filter was specified, exclude all entities outside of the filter.
-    if (
-      gridEntityTypeFilter !== undefined &&
-      gridEntityType !== gridEntityTypeFilter
-    ) {
-      return;
-    }
-
-    if (
-      !includeWalls &&
-      gridEntityType === GridEntityType.WALL &&
-      gridEntityTypeFilter !== GridEntityType.WALL
-    ) {
-      return;
-    }
-
-    msg += getGridEntityLogLine(gridEntity, gridEntityIndex);
-
-    numMatchedEntities++;
-  });
-
-  if (numMatchedEntities === 0) {
-    msg += "(no grid entities matched)\n";
-  } else {
-    msg += `(${numMatchedEntities} total grid ${
-      numMatchedEntities === 1 ? "entity" : "entities"
-    })\n`;
-  }
-
-  log(msg);
-}
-
 export function logArray<T>(this: void, array: T[] | readonly T[]): void {
   const arrayString = arrayToString(array);
   log(`Array: ${arrayString}`);
@@ -203,92 +87,6 @@ export function logDamageFlags(
   logFlags(flags, DamageFlag, "damage");
 }
 
-/** Helper function for logging an array of specific entities. */
-export function logEntities(this: void, entities: Entity[]): void {
-  for (const entity of entities) {
-    logEntity(entity);
-  }
-}
-
-/** Helper function to log information about a specific entity. */
-export function logEntity(this: void, entity: Entity): void {
-  const msg = getEntityLogLine(entity);
-  log(msg);
-}
-
-function getEntityLogLine(entity: Entity, num?: int): string {
-  let msg = num === undefined ? "" : `${num}) `;
-
-  msg += getEntityID(entity);
-
-  const bomb = entity.ToBomb();
-  if (bomb !== undefined) {
-    msg += " (bomb)";
-  }
-
-  const effect = entity.ToEffect();
-  if (effect !== undefined) {
-    msg += ` (effect) (State: ${effect.State})`;
-  }
-
-  const familiar = entity.ToFamiliar();
-  if (familiar !== undefined) {
-    msg += ` (familiar) (State: ${familiar.State})`;
-  }
-
-  const knife = entity.ToKnife();
-  if (knife !== undefined) {
-    msg += " (knife)";
-  }
-
-  const laser = entity.ToLaser();
-  if (laser !== undefined) {
-    msg += " (laser)";
-  }
-
-  const npc = entity.ToNPC();
-  if (npc !== undefined) {
-    msg += ` (NPC) (State: ${npc.State})`;
-  }
-
-  const pickup = entity.ToPickup();
-  if (pickup !== undefined) {
-    msg += ` (pickup) (State: ${pickup.State})`;
-  }
-
-  const player = entity.ToPlayer();
-  if (player !== undefined) {
-    msg += " (player)";
-  }
-
-  const projectile = entity.ToProjectile();
-  if (projectile !== undefined) {
-    msg += " (projectile)";
-  }
-
-  const tear = entity.ToTear();
-  if (tear !== undefined) {
-    msg += " (tear)";
-  }
-
-  msg += "\n";
-  msg += `  - Index: ${entity.Index}\n`;
-  msg += `  - InitSeed: ${entity.InitSeed}\n`;
-  msg += `  - DropSeed: ${entity.DropSeed}\n`;
-  msg += `  - Position: (${entity.Position.X}, ${entity.Position.Y})\n`;
-  msg += `  - Velocity: (${entity.Velocity.X}, ${entity.Velocity.Y})\n`;
-  msg += `  - HP: ${entity.HitPoints} / ${entity.MaxHitPoints}\n`;
-  msg += `  - Parent: ${entity.Parent}\n`;
-  msg += `  - Child: ${entity.Child}\n`;
-  msg += `  - SpawnerEntity: ${entity.SpawnerEntity}\n`;
-  msg += `  - SpawnerType / SpawnerVariant: ${entity.SpawnerType}.${entity.SpawnerVariant}\n`;
-  if (npc !== undefined) {
-    msg += `  - CanShutDoors: ${npc.CanShutDoors}\n`;
-  }
-
-  return msg;
-}
-
 /** Helper function for printing out every entity flag that is turned on. Useful when debugging. */
 export function logEntityFlags(
   this: void,
@@ -363,76 +161,6 @@ export function logGameStateFlags(this: void): void {
   }
 }
 
-/** Helper function for logging an array of specific grid entities. */
-export function logGridEntities(this: void, gridEntities: GridEntity[]): void {
-  for (const gridEntity of gridEntities) {
-    logGridEntity(gridEntity);
-  }
-}
-
-/** Helper function for log information about a specific grid entity. */
-export function logGridEntity(this: void, gridEntity: GridEntity): void {
-  const msg = getGridEntityLogLine(gridEntity);
-  log(msg);
-}
-
-function getGridEntityLogLine(gridEntity: GridEntity, num?: int): string {
-  const gridEntityDesc = gridEntity.GetSaveState();
-
-  let msg = num === undefined ? "" : `${num}) `;
-
-  msg += getGridEntityID(gridEntity);
-
-  const door = gridEntity.ToDoor();
-  if (door !== undefined) {
-    msg += " (door)";
-  }
-
-  const pit = gridEntity.ToPit();
-  if (pit !== undefined) {
-    msg += " (pit)";
-  }
-
-  const poop = gridEntity.ToPoop();
-  if (poop !== undefined) {
-    msg += " (poop)";
-  }
-
-  const pressurePlate = gridEntity.ToPressurePlate();
-  if (pressurePlate !== undefined) {
-    msg += " (pressurePlate)";
-  }
-
-  const rock = gridEntity.ToRock();
-  if (rock !== undefined) {
-    msg += " (rock)";
-  }
-
-  const spikes = gridEntity.ToSpikes();
-  if (spikes !== undefined) {
-    msg += " (spikes)";
-  }
-
-  const tnt = gridEntity.ToTNT();
-  if (tnt !== undefined) {
-    msg += " (TNT)";
-  }
-
-  msg += `  - State: ${gridEntity.State}\n`;
-  msg += `  - VarData: ${gridEntity.VarData}\n`;
-  msg += `  - Position: (${gridEntity.Position.X}, ${gridEntity.Position.Y})\n`;
-  msg += `  - SpawnSeed: ${gridEntityDesc.SpawnSeed}\n`;
-  msg += `  - VariableSeed: ${gridEntityDesc.VariableSeed})\n`;
-  if (door !== undefined) {
-    msg += `  - Slot: ${door.Slot}\n`;
-    msg += `  - Direction: ${door.Direction}\n`;
-    msg += `  - TargetRoomIndex: ${door.TargetRoomIndex}\n`;
-    msg += `  - TargetRoomType: ${door.TargetRoomType}\n`;
-  }
-
-  return msg;
-}
-
 export function logKColor(this: void, kColor: KColor): void {
   log(
     `Color: R${kColor.Red}, G${kColor.Green}, B${kColor.Blue}, A${kColor.Alpha}`,
@@ -764,20 +492,14 @@ export function setLogFunctionsGlobal(): void {
   const globals = _G as Record<string, unknown>;
 
   globals["log"] = log;
-  globals["logAllEntities"] = logAllEntities;
-  globals["logAllGridEntities"] = logAllGridEntities;
   globals["logArray"] = logArray;
   globals["logColor"] = logColor;
   globals["logDamageFlags"] = logDamageFlags;
-  globals["logEntities"] = logEntities;
-  globals["logEntity"] = logEntity;
   globals["logEntityID"] = logEntityID;
   globals["logEntityFlags"] = logEntityFlags;
   globals["logError"] = logError;
   globals["logFlags"] = logFlags;
   globals["logGameStateFlags"] = logGameStateFlags;
-  globals["logGridEntities"] = logGridEntities;
-  globals["logGridEntity"] = logGridEntity;
   globals["logKColor"] = logKColor;
   globals["logLevelStateFlags"] = logLevelStateFlags;
   globals["logMap"] = logMap;