isaacscript-common 6.11.1 → 6.13.0

package/src/enums/private/TrapdoorAnimation.ts

@@ -0,0 +1,5 @@
+export enum TrapdoorAnimation {
+  OPENED = "Opened",
+  CLOSED = "Closed",
+  OPEN_ANIMATION = "Open Animation",
+}

package/src/features/collectibleItemPoolType.ts

@@ -1,5 +1,5 @@
 // The item pool type of a collectible is not stored on the collectible. Thus, we scan for incoming
-// item pool types in the PreGetCollectible callback, and then assume that the next spawned
+// item pool types in the `PRE_GET_COLLECTIBLE` callback, and then assume that the next spawned
 // collectible has this item pool type.
 
 import {
@@ -45,8 +45,8 @@ function postPickupInitCollectible(pickup: EntityPickup) {
 
 /**
  * Helper function to get the item pool type that a given collectible came from. Since there is no
- * native method in the API to get this, we listen in the PreGetCollectible callback for item pool
- * types, and then assume that the next spawned collectible will match.
+ * native method in the API to get this, we listen in the `PRE_GET_COLLECTIBLE` callback for item
+ * pool types, and then assume that the next spawned collectible will match.
  */
 export function getCollectibleItemPoolType(
   collectible: EntityPickup,

package/src/features/customGridEntity.ts

@@ -19,6 +19,7 @@ import {
 import { getRoomListIndex } from "../functions/roomData";
 import { isVector } from "../functions/vector";
 import { CustomGridEntityData } from "../interfaces/CustomGridEntityData";
+import { runNextGameFrame } from "./runInNFrames";
 import { saveDataManager } from "./saveDataManager/exports";
 
 const FEATURE_NAME = "customGridEntity";
@@ -30,6 +31,10 @@ const v = {
       () => new Map(),
     ),
   },
+
+  room: {
+    manuallyUsingShovel: false,
+  },
 };
 
 /** @internal */
@@ -53,12 +58,54 @@ export function customGridEntityInit(mod: ModUpgraded): void {
 function preUseItemWeNeedToGoDeeper(
   _collectibleType: CollectibleType,
   _rng: RNG,
-  _player: EntityPlayer,
+  player: EntityPlayer,
   _useFlags: BitFlags<UseFlag>,
   _activeSlot: ActiveSlot,
   _customVarData: int,
 ): boolean | undefined {
-  return undefined;
+  // If a player uses We Need to Go Deeper on top of a custom grid entity, then they will always get
+  // a crawlspace, due to how custom grids are implemented with decorations. Thus, remove the custom
+  // grid entity to prevent this from happening if needed.
+  const room = game.GetRoom();
+  const roomListIndex = getRoomListIndex();
+  const roomCustomGridEntities = v.level.customGridEntities.get(roomListIndex);
+  if (roomCustomGridEntities === undefined) {
+    return undefined;
+  }
+
+  const gridIndex = room.GetGridIndex(player.Position);
+  const customGridEntity = roomCustomGridEntities.get(gridIndex);
+  if (customGridEntity === undefined) {
+    return undefined;
+  }
+
+  // If the custom grid entity has collision, then the player should not be able to be standing on
+  // top of it.
+  if (customGridEntity.gridCollisionClass !== GridCollisionClass.NONE) {
+    return undefined;
+  }
+
+  removeGridEntity(customGridEntity.gridIndex, false);
+
+  const playerPtr = EntityPtr(player);
+  runNextGameFrame(() => {
+    const futureEntity = playerPtr.Ref;
+    if (futureEntity === undefined) {
+      return;
+    }
+
+    const futurePlayer = futureEntity.ToPlayer();
+    if (futurePlayer === undefined) {
+      return;
+    }
+
+    v.room.manuallyUsingShovel = true;
+    futurePlayer.UseActiveItem(CollectibleType.WE_NEED_TO_GO_DEEPER);
+    v.room.manuallyUsingShovel = false;
+  });
+
+  // Cancel the original effect.
+  return true;
 }
 
 // ModCallbackCustom.POST_NEW_ROOM_REORDERED
@@ -81,12 +128,18 @@ function postNewRoomReordered() {
 
     const sprite = decoration.GetSprite();
     sprite.Load(data.anm2Path, true);
-    sprite.Play(data.defaultAnimation, true);
+    const animationToPlay =
+      data.defaultAnimation === undefined
+        ? sprite.GetDefaultAnimation()
+        : data.defaultAnimation;
+    sprite.Play(animationToPlay, true);
   }
 }
 
 /**
- * Helper function to spawn a custom grid entity.
+ * Helper function to spawn a custom grid entity. Custom grid entities are persistent in that they
+ * will reappear if the player leaves and re-enters the room. (It will be manually respawned in the
+ * `POST_NEW_ROOM` callback.)
  *
  * This is an IsaacScript feature because the vanilla game does not support any custom grid
  * entities. Under the hood, IsaacScript accomplishes this by using decorations with an arbitrary
@@ -103,17 +156,18 @@ function postNewRoomReordered() {
  * @param gridIndexOrPosition The grid index or position in the room that you want to spawn the grid
  *                            entity at. If a position is specified, the closest grid index will be
  *                            used.
- * @param anm2Path The path to the ANM2 file to use for the sprite.
- * @param defaultAnimation 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.
  * @param gridCollisionClass The collision class that you want the custom grid entity to have.
+ * @param anm2Path The path to the ANM2 file to use for the sprite.
+ * @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.
  */
 export function spawnCustomGridEntity(
   gridEntityTypeCustom: GridEntityType,
   gridIndexOrPosition: int | Vector,
-  anm2Path: string,
-  defaultAnimation: string,
   gridCollisionClass: GridCollisionClass,
+  anm2Path: string,
+  defaultAnimation?: string,
 ): GridEntity {
   errorIfFeaturesNotInitialized(FEATURE_NAME);
 
@@ -142,7 +196,11 @@ export function spawnCustomGridEntity(
 
   const sprite = decoration.GetSprite();
   sprite.Load(anm2Path, true);
-  sprite.Play(defaultAnimation, true);
+  const animationToPlay =
+    defaultAnimation === undefined
+      ? sprite.GetDefaultAnimation()
+      : defaultAnimation;
+  sprite.Play(animationToPlay, true);
 
   const customGridEntityData: CustomGridEntityData = {
     gridEntityTypeCustom,
@@ -216,3 +274,28 @@ export function removeCustomGrid(
 
   return decoration;
 }
+
+/**
+ * Helper function to get the custom grid entities in the current room. Returns an array of tuples
+ * containing the raw decoration grid entity and the associated entity data.
+ */
+export function getCustomGridEntities(): Array<
+  [gridEntity: GridEntity, data: CustomGridEntityData]
+> {
+  const roomListIndex = getRoomListIndex();
+  const roomCustomGridEntities = v.level.customGridEntities.get(roomListIndex);
+  if (roomCustomGridEntities === undefined) {
+    return [];
+  }
+
+  const room = game.GetRoom();
+  const customGridEntities: Array<[GridEntity, CustomGridEntityData]> = [];
+  for (const [gridIndex, data] of roomCustomGridEntities.entries()) {
+    const gridEntity = room.GetGridEntity(gridIndex);
+    if (gridEntity !== undefined) {
+      customGridEntities.push([gridEntity, data]);
+    }
+  }
+
+  return customGridEntities;
+}

package/src/features/customStage/exports.ts

@@ -1,10 +1,8 @@
 import {
-  Direction,
   EntityType,
   GridRoom,
   LevelStage,
   RoomShape,
-  RoomTransitionAnim,
   RoomType,
   StageType,
 } from "isaac-typescript-definitions";
@@ -12,12 +10,10 @@ import { game } from "../../cachedClasses";
 import { reorderedCallbacksSetStage } from "../../callbacks/reorderedCallbacks";
 import { getEntityIDFromConstituents } from "../../functions/entities";
 import { log, logError } from "../../functions/log";
-import { movePlayersToCenter } from "../../functions/playerCenter";
 import { newRNG } from "../../functions/rng";
 import { getRoomData } from "../../functions/roomData";
 import { getRooms } from "../../functions/rooms";
 import { getGotoCommand, setStage } from "../../functions/stage";
-import { runNextRoom } from "../runNextRoom";
 import { getRandomCustomStageRoom } from "./customStageUtils";
 import { topStreakTextStart } from "./streakText";
 import v, {
@@ -136,24 +132,9 @@ export function setCustomStage(name: string, verbose = false): void {
 
   // We must reload the current room in order for the `Level.SetStage` method to take effect.
   // Furthermore, we need to cancel the queued warp to the `GridRoom.DEBUG` room. We can accomplish
-  // both of these things by initiating a room transition to the starting room of the floor. (We
-  // assume that since we just warped to a new floor, we are already in the starting room.)
-  game.StartRoomTransition(
-    startingRoomGridIndex,
-    Direction.NO_DIRECTION,
-    RoomTransitionAnim.FADE,
-  );
-
-  // We do more setup once the room is reloaded from the transition.
-  runNextRoom(postRoomTransition);
-}
-
-function postRoomTransition() {
-  // After the room transition, the players will be placed next to a door, but they should be in the
-  // center of the room to emulate what happens on a vanilla stage.
-  movePlayersToCenter();
-
-  topStreakTextStart();
+  // both of these things by initiating a room transition to an arbitrary room. However, we rely on
+  // the parent function to do this, since for normal purposes, we need to initiate a room
+  // transition for pixelation purposes.
 }
 
 export function setCustomStageDebug(): void {

package/src/features/customStage/init.ts

@@ -1,6 +1,7 @@
 import {
   DoorSlotFlag,
   GridEntityType,
+  LevelCurse,
   ModCallback,
   RoomShape,
   RoomType,
@@ -8,6 +9,7 @@ import {
 import { ModUpgraded } from "../../classes/ModUpgraded";
 import { ModCallbackCustom } from "../../enums/ModCallbackCustom";
 import { isArray } from "../../functions/array";
+import { hasFlag, removeFlag } from "../../functions/flag";
 import { CustomStage, RoomTypeMap } from "../../interfaces/CustomStage";
 import {
   CustomStageLua,
@@ -49,6 +51,7 @@ export function customStageInit(mod: ModUpgraded): void {
   versusScreenInit();
 
   mod.AddCallback(ModCallback.POST_RENDER, postRender); // 2
+  mod.AddCallback(ModCallback.POST_CURSE_EVAL, postCurseEval); // 12
   mod.AddCallback(ModCallback.POST_GAME_STARTED, postGameStarted); // 15
   mod.AddCallback(ModCallback.GET_SHADER_PARAMS, getShaderParams); // 21
   mod.AddCallbackCustom(
@@ -137,6 +140,23 @@ function postRender() {
   versusScreenPostRender();
 }
 
+// ModCallback.POST_CURSE_EVAL (12)
+function postCurseEval(
+  curses: BitFlags<LevelCurse>,
+): BitFlags<LevelCurse> | undefined {
+  const customStage = v.run.currentCustomStage;
+  if (customStage === null) {
+    return undefined;
+  }
+
+  // Prevent XL floors on custom stages, since the streak text will not work properly.
+  if (hasFlag(curses, LevelCurse.MAZE)) {
+    return removeFlag(curses, LevelCurse.MAZE);
+  }
+
+  return undefined;
+}
+
 // ModCallback.POST_GAME_STARTED (15)
 function postGameStarted() {
   // We don't early return here because we need to unconditionally reset the sprites.

package/src/features/customStage/streakText.ts

@@ -287,7 +287,6 @@ function renderSprite(
   const adjustedX = centeredX + adjustment;
   const adjustedY = position.Y + STREAK_TEXT_BOTTOM_Y_OFFSET;
 
-  sprite.RenderLayer(0, position);
   font.DrawStringScaled(
     name,
     adjustedX,

package/src/features/customTrapdoor/blackSprite.ts

@@ -0,0 +1,22 @@
+import { VectorZero } from "../../constants";
+import { StageTravelState } from "../../enums/private/StageTravelState";
+import v from "./v";
+
+// In order to represent a black sprite, we just use the first frame of the boss versus screen
+// animation. However, we must lazy load the sprite in order to prevent issues with mods that
+// replace the vanilla files. (For some reason, loading the sprites will cause the overwrite to no
+// longer apply on the second and subsequent runs.)
+const blackSprite = Sprite();
+
+export function drawBlackSprite(): void {
+  if (v.run.state !== StageTravelState.PAUSING_ON_BLACK) {
+    return;
+  }
+
+  if (!blackSprite.IsLoaded()) {
+    blackSprite.Load("gfx/ui/boss/versusscreen.anm2", true);
+    blackSprite.SetFrame("Scene", 0);
+  }
+
+  blackSprite.RenderLayer(0, VectorZero);
+}

package/src/features/customTrapdoor/customTrapdoorConstants.ts

@@ -2,12 +2,22 @@ import { GridEntityType } from "isaac-typescript-definitions";
 
 export const CUSTOM_TRAPDOOR_FEATURE_NAME = "customTrapdoor";
 
+export const GridEntityTypeCustom = {
+  TRAPDOOR_CUSTOM: 1000 as GridEntityType,
+} as const;
+
 /** This also applies to crawl spaces. The value was determined through trial and error. */
 export const TRAPDOOR_OPEN_DISTANCE = 60;
 
 export const TRAPDOOR_OPEN_DISTANCE_AFTER_BOSS = TRAPDOOR_OPEN_DISTANCE * 2.5;
 export const TRAPDOOR_BOSS_REACTION_FRAMES = 30;
 
-export const GridEntityTypeCustom = {
-  TRAPDOOR_CUSTOM: 1000 as GridEntityType,
-} as const;
+export const TRAPDOOR_TOUCH_DISTANCE = 16.5;
+
+export const ANIMATIONS_THAT_PREVENT_STAGE_TRAVEL: ReadonlySet<string> =
+  new Set(["Happy", "Sad", "Jump"]);
+
+export const PIXELATION_TO_BLACK_FRAMES = 52;
+
+export const OTHER_PLAYER_TRAPDOOR_JUMP_DELAY_GAME_FRAMES = 6;
+export const OTHER_PLAYER_TRAPDOOR_JUMP_DURATION_GAME_FRAMES = 5;

package/src/features/customTrapdoor/exports.ts

@@ -1,23 +1,22 @@
 import {
   GridCollisionClass,
   LevelStage,
-  RoomType,
   StageType,
 } from "isaac-typescript-definitions";
 import { game } from "../../cachedClasses";
+import { TrapdoorAnimation } from "../../enums/private/TrapdoorAnimation";
 import { errorIfFeaturesNotInitialized } from "../../featuresInitialized";
 import { getNextStage, getNextStageType } from "../../functions/nextStage";
-import { anyPlayerCloserThan } from "../../functions/positionVelocity";
+import { getRoomListIndex } from "../../functions/roomData";
+import { isVector } from "../../functions/vector";
+import { CustomTrapdoorDescription } from "../../interfaces/private/CustomTrapdoorDescription";
 import { spawnCustomGridEntity } from "../customGridEntity";
-import { getRoomClearGameFrame } from "../roomClearFrame";
 import {
   CUSTOM_TRAPDOOR_FEATURE_NAME,
   GridEntityTypeCustom,
-  TRAPDOOR_BOSS_REACTION_FRAMES,
-  TRAPDOOR_OPEN_DISTANCE,
-  TRAPDOOR_OPEN_DISTANCE_AFTER_BOSS,
 } from "./customTrapdoorConstants";
-import { getCustomTrapdoorDescription } from "./v";
+import { shouldTrapdoorSpawnOpen } from "./openClose";
+import v from "./v";
 
 /**
  * Helper function to spawn a trapdoor grid entity that will have one or more of the following
@@ -26,7 +25,7 @@ import { getCustomTrapdoorDescription } from "./v";
  * - custom destination (or custom logic for after the player enters)
  * - custom graphics
  * - custom logic for opening/closing
- * - TODO: animation
+ * - TODO: player jumping animation?
  *
  * You can use this function to take the player to your custom stage.
  *
@@ -34,135 +33,67 @@ import { getCustomTrapdoorDescription } from "./v";
  * respawned every time the player re-enters the room.
  *
  * @param gridIndexOrPosition The location in the room to spawn the trapdoor.
- * @param _destination Used to specify where the player will go after jumping into the trapdoor. Can
- *                     either be a tuple containing the stage and stage type, a string containing
- *                     the name of a custom stage, or undefined. If undefined, nothing will happen
- *                     after the player jumps in the trapdoor. (Use undefined to perform some custom
- *                     behavior and/or handle the traveling part yourself.) You can also specify a
- *                     function that returns one of these things. By default, the destination will
- *                     be set to the next floor like that of a vanilla 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).
  * @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.
- * @param _shouldOpenFunc Optional. If the trapdoor is currently closed, this function will run on
- *                        every frame to determine if it should open. By default, a function that
- *                        emulates a vanilla trapdoor will be used.
- * @param _shouldCloseFunc Optional. If the trapdoor is currently open, this function will run on
- *                         every frame to determine if it should close. By default, a function that
- *                         emulates a vanilla trapdoor will be used.
- * @param _spawnOpen Optional. Whether or not to spawn the trapdoor in an open state. Can either be
- *                   a boolean or a function returning a boolean. By default, a function that
- *                   emulates a vanilla trapdoor will be used.
+ *                 of "gfx/grid/door_11_trapdoor.anm2" will be used. The specified anm2 file must
+ *                 have animations called "Opened", "Closed", and "Open Animation".
+ * @param spawnOpen Optional. Whether or not to spawn the trapdoor in an open state. By default,
+ *                  behavior will be used that emulates a vanilla trapdoor.
  */
 export function spawnCustomTrapdoor(
   gridIndexOrPosition: int | Vector,
-  _destination:
-    | [stage: LevelStage, stageType: StageType]
-    | string
-    | ((
-        gridEntity: GridEntity,
-      ) =>
-        | [stage: LevelStage, stageType: StageType]
-        | string
-        | undefined) = defaultDestinationFunc,
+  destination?: [stage: LevelStage, stageType: StageType] | string,
   anm2Path = "gfx/grid/door_11_trapdoor.anm2",
-  _shouldOpenFunc: (gridEntity: GridEntity) => boolean = defaultShouldOpenFunc,
-  _shouldCloseFunc: (
-    gridEntity: GridEntity,
-  ) => boolean = defaultShouldCloseFunc,
-  _spawnOpen:
-    | boolean
-    | ((gridEntity: GridEntity) => boolean) = defaultShouldSpawnOpenFunc,
+  spawnOpen?: boolean,
 ): GridEntity {
   errorIfFeaturesNotInitialized(CUSTOM_TRAPDOOR_FEATURE_NAME);
 
-  // TODO
-  return spawnCustomGridEntity(
+  const room = game.GetRoom();
+  const roomFrameCount = room.GetFrameCount();
+  const roomListIndex = getRoomListIndex();
+  const gridIndex = isVector(gridIndexOrPosition)
+    ? room.GetGridIndex(gridIndexOrPosition)
+    : gridIndexOrPosition;
+
+  const gridEntity = spawnCustomGridEntity(
     GridEntityTypeCustom.TRAPDOOR_CUSTOM,
     gridIndexOrPosition,
-    anm2Path,
-    "Closed",
     GridCollisionClass.NONE,
+    anm2Path,
+    TrapdoorAnimation.OPENED,
   );
-}
-
-function defaultDestinationFunc(): [stage: LevelStage, stageType: StageType] {
-  const nextStage = getNextStage();
-  const nextStageType = getNextStageType();
-
-  return [nextStage, nextStageType];
-}
-
-function defaultShouldOpenFunc(gridEntity: GridEntity): boolean {
-  const trapdoorDescription = getCustomTrapdoorDescription(gridEntity);
-  if (trapdoorDescription === undefined) {
-    return false;
-  }
-
-  const room = game.GetRoom();
-  const roomClear = room.IsClear();
-
-  return (
-    !anyPlayerCloserThan(gridEntity.Position, TRAPDOOR_OPEN_DISTANCE) &&
-    !isPlayerCloseAfterBoss(gridEntity.Position) &&
-    !shouldBeClosedFromStartingInRoomWithEnemies(
-      trapdoorDescription.firstSpawn,
-      roomClear,
-    )
-  );
-}
 
-function isPlayerCloseAfterBoss(position: Vector) {
-  const gameFrameCount = game.GetFrameCount();
-  const room = game.GetRoom();
-  const roomType = room.GetType();
-  const roomClearGameFrame = getRoomClearGameFrame();
-
-  // In order to prevent a player from accidentally entering a freshly-spawned trapdoor after
-  // killing the boss of the floor, we use a wider open distance for a short amount of frames.
-  if (
-    roomType !== RoomType.BOSS ||
-    roomClearGameFrame === undefined ||
-    gameFrameCount >= roomClearGameFrame + TRAPDOOR_BOSS_REACTION_FRAMES
-  ) {
-    return false;
+  const firstSpawn = roomFrameCount !== 0;
+  const open =
+    spawnOpen === undefined
+      ? shouldTrapdoorSpawnOpen(gridEntity, firstSpawn)
+      : spawnOpen;
+  const destinationToUse =
+    destination === undefined ? getDefaultDestination() : destination;
+
+  const roomTrapdoorMap = v.level.trapdoors.getAndSetDefault(roomListIndex);
+  const customTrapdoorDescription: CustomTrapdoorDescription = {
+    open,
+    destination: destinationToUse,
+    firstSpawn,
+  };
+  roomTrapdoorMap.set(gridIndex, customTrapdoorDescription);
+
+  if (!open) {
+    const sprite = gridEntity.GetSprite();
+    sprite.Play(TrapdoorAnimation.CLOSED, true);
   }
 
-  return anyPlayerCloserThan(position, TRAPDOOR_OPEN_DISTANCE_AFTER_BOSS);
+  return gridEntity;
 }
 
-function shouldBeClosedFromStartingInRoomWithEnemies(
-  firstSpawn: boolean,
-  roomClear: boolean,
-) {
-  return firstSpawn && !roomClear;
-}
-
-/** By default, trapdoors will never close if they are already open. */
-function defaultShouldCloseFunc(): boolean {
-  return false;
-}
-
-function defaultShouldSpawnOpenFunc(gridEntity: GridEntity): boolean {
-  const room = game.GetRoom();
-  const roomFrameCount = room.GetFrameCount();
-  const roomClear = room.IsClear();
-
-  // Trapdoors created after a room has already initialized should spawn closed by default:
-  // - Trapdoors created after bosses should spawn closed so that players do not accidentally jump
-  //   into them.
-  // - Trapdoors created by We Need to Go Deeper should spawn closed because the player will be
-  //   standing on top of them.
-  if (roomFrameCount > 0) {
-    return false;
-  }
-
-  // If we just entered a new room with enemies in it, spawn the trapdoor closed so that the player
-  // has to defeat the enemies first before using the trapdoor.
-  if (!roomClear) {
-    return false;
-  }
+function getDefaultDestination(): [stage: LevelStage, stageType: StageType] {
+  const nextStage = getNextStage();
+  const nextStageType = getNextStageType();
 
-  // If we just entered a new room that is already cleared, spawn the trapdoor closed if we are
-  // standing close to it, and open otherwise.
-  return defaultShouldOpenFunc(gridEntity);
+  return [nextStage, nextStageType];
 }