isaacscript-common 6.11.1 → 6.13.0

package/src/features/customTrapdoor/init.ts

@@ -0,0 +1,217 @@
+import {
+  Direction,
+  ModCallback,
+  RoomTransitionAnim,
+} from "isaac-typescript-definitions";
+import { game } from "../../cachedClasses";
+import { ModUpgraded } from "../../classes/ModUpgraded";
+import { ModCallbackCustom } from "../../enums/ModCallbackCustom";
+import { StageTravelState } from "../../enums/private/StageTravelState";
+import { movePlayersToCenter } from "../../functions/playerCenter";
+import { getAllPlayers } from "../../functions/playerIndex";
+import { getRoomGridIndex, getRoomListIndex } from "../../functions/roomData";
+import { setStage } from "../../functions/stage";
+import { isString } from "../../functions/types";
+import { setCustomStage } from "../customStage/exports";
+import { topStreakTextStart } from "../customStage/streakText";
+import { enableAllInputs } from "../disableInputs";
+import { runNextGameFrame } from "../runInNFrames";
+import { runNextRoom } from "../runNextRoom";
+import { saveDataManager } from "../saveDataManager/exports";
+import { drawBlackSprite } from "./blackSprite";
+import {
+  CUSTOM_TRAPDOOR_FEATURE_NAME,
+  GridEntityTypeCustom,
+  PIXELATION_TO_BLACK_FRAMES,
+} from "./customTrapdoorConstants";
+import { checkCustomTrapdoorOpenClose } from "./openClose";
+import { checkCustomTrapdoorPlayerTouched } from "./touched";
+import v from "./v";
+
+export function customTrapdoorInit(mod: ModUpgraded): void {
+  saveDataManager(CUSTOM_TRAPDOOR_FEATURE_NAME, v);
+
+  mod.AddCallback(ModCallback.POST_RENDER, postRender); // 2
+  mod.AddCallback(ModCallback.POST_PEFFECT_UPDATE, postPEffectUpdate); // 4
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_GRID_ENTITY_CUSTOM_UPDATE,
+    postGridEntityCustomUpdateTrapdoor,
+    GridEntityTypeCustom.TRAPDOOR_CUSTOM,
+  );
+}
+
+// ModCallback.POST_RENDER (2)
+function postRender() {
+  checkAllPlayersJumpComplete();
+  checkPixelationToBlackComplete();
+  checkPausingOnBlackComplete();
+  checkAllPlayersLayingDownComplete();
+  drawBlackSprite();
+}
+
+function checkAllPlayersJumpComplete() {
+  if (v.run.state !== StageTravelState.PLAYERS_JUMPING_DOWN) {
+    return;
+  }
+
+  if (anyPlayerPlayingExtraAnimation()) {
+    return;
+  }
+
+  const renderFrameCount = Isaac.GetFrameCount();
+  const roomGridIndex = getRoomGridIndex();
+
+  v.run.state = StageTravelState.PIXELATION_TO_BLACK;
+  v.run.stateRenderFrame = renderFrameCount;
+
+  // In order to display the pixelation effect that should happen when we go to a new floor, we need
+  // to start a room transition. We arbitrarily pick the current room for this purpose.
+  game.StartRoomTransition(
+    roomGridIndex,
+    Direction.NO_DIRECTION,
+    RoomTransitionAnim.PIXELATION,
+  );
+}
+
+function checkPixelationToBlackComplete() {
+  if (
+    v.run.state !== StageTravelState.PIXELATION_TO_BLACK ||
+    v.run.stateRenderFrame === null
+  ) {
+    return;
+  }
+
+  const hud = game.GetHUD();
+  const renderFrameCount = Isaac.GetFrameCount();
+  const roomGridIndex = getRoomGridIndex();
+
+  const renderFrameScreenBlack =
+    v.run.stateRenderFrame + PIXELATION_TO_BLACK_FRAMES;
+  if (renderFrameCount < renderFrameScreenBlack) {
+    return;
+  }
+
+  v.run.state = StageTravelState.PAUSING_ON_BLACK;
+  v.run.stateRenderFrame = renderFrameCount;
+
+  hud.SetVisible(false);
+  goToCustomDestination();
+
+  // Start another pixelation effect. This time, we will keep the screen black with the sprite, and
+  // then remove the black sprite once the pixelation effect is halfway complete.
+  game.StartRoomTransition(
+    roomGridIndex,
+    Direction.NO_DIRECTION,
+    RoomTransitionAnim.PIXELATION,
+  );
+}
+
+function checkPausingOnBlackComplete() {
+  if (
+    v.run.state !== StageTravelState.PAUSING_ON_BLACK ||
+    v.run.stateRenderFrame === null
+  ) {
+    return;
+  }
+
+  const hud = game.GetHUD();
+  const renderFrameCount = Isaac.GetFrameCount();
+
+  const renderFrameScreenBlack =
+    v.run.stateRenderFrame + PIXELATION_TO_BLACK_FRAMES;
+  if (renderFrameCount < renderFrameScreenBlack) {
+    return;
+  }
+
+  v.run.state = StageTravelState.PIXELATION_TO_ROOM;
+
+  hud.SetVisible(true);
+
+  runNextRoom(() => {
+    // 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();
+
+    v.run.state = StageTravelState.PLAYERS_LAYING_DOWN;
+
+    for (const player of getAllPlayers()) {
+      player.AnimateAppear();
+    }
+  });
+
+  // In vanilla, the streak text appears about when the pixelation has faded and while Isaac is
+  // still laying on the ground. Unfortunately, we cannot exactly replicate the vanilla timing,
+  // because the level text will bug out and smear the background if we play it from a `POST_RENDER`
+  // callback. Thus, we run it on the next game frame as a workaround.
+  runNextGameFrame(() => {
+    topStreakTextStart();
+  });
+}
+
+function checkAllPlayersLayingDownComplete() {
+  if (v.run.state !== StageTravelState.PLAYERS_LAYING_DOWN) {
+    return;
+  }
+
+  if (anyPlayerPlayingExtraAnimation()) {
+    return;
+  }
+
+  v.run.state = StageTravelState.NONE;
+
+  enableAllInputs(CUSTOM_TRAPDOOR_FEATURE_NAME);
+}
+
+function goToCustomDestination() {
+  if (v.run.destination === null) {
+    return;
+  }
+
+  if (isString(v.run.destination)) {
+    setCustomStage("Slaughterhouse");
+  } else {
+    const [stage, stageType] = v.run.destination;
+    setStage(stage, stageType);
+  }
+}
+
+function anyPlayerPlayingExtraAnimation() {
+  const players = getAllPlayers();
+  return players.some((player) => !player.IsExtraAnimationFinished());
+}
+
+// ModCallback.POST_PEFFECT_UPDATE (4)
+function postPEffectUpdate(player: EntityPlayer) {
+  checkJumpComplete(player);
+}
+
+function checkJumpComplete(player: EntityPlayer) {
+  if (v.run.state !== StageTravelState.PLAYERS_JUMPING_DOWN) {
+    return;
+  }
+
+  // In this state, the players are jumping down the hole (i.e. playing the "Trapdoor" animation).
+  // When it completes, they will return to normal (i.e. just standing on top of the trapdoor).
+  // Thus, make them invisible at the end of the animation. (They will automatically be set to
+  // visible again once we travel to the next floor.)
+  const sprite = player.GetSprite();
+  if (sprite.IsFinished("Trapdoor")) {
+    player.Visible = false;
+  }
+}
+
+// ModCallbackCustom.POST_GRID_ENTITY_CUSTOM_UPDATE
+// GridEntityTypeCustom.TRAPDOOR_CUSTOM
+function postGridEntityCustomUpdateTrapdoor(gridEntity: GridEntity) {
+  const roomListIndex = getRoomListIndex();
+  const gridIndex = gridEntity.GetGridIndex();
+
+  const roomTrapdoorMap = v.level.trapdoors.getAndSetDefault(roomListIndex);
+  const trapdoorDescription = roomTrapdoorMap.get(gridIndex);
+  if (trapdoorDescription === undefined) {
+    return;
+  }
+
+  checkCustomTrapdoorOpenClose(gridEntity, trapdoorDescription);
+  checkCustomTrapdoorPlayerTouched(gridEntity, trapdoorDescription);
+}

package/src/features/customTrapdoor/openClose.ts

@@ -0,0 +1,103 @@
+import { RoomType } from "isaac-typescript-definitions";
+import { game } from "../../cachedClasses";
+import { TrapdoorAnimation } from "../../enums/private/TrapdoorAnimation";
+import { anyPlayerCloserThan } from "../../functions/positionVelocity";
+import { CustomTrapdoorDescription } from "../../interfaces/private/CustomTrapdoorDescription";
+import { getRoomClearGameFrame } from "../roomClearFrame";
+import {
+  TRAPDOOR_BOSS_REACTION_FRAMES,
+  TRAPDOOR_OPEN_DISTANCE,
+  TRAPDOOR_OPEN_DISTANCE_AFTER_BOSS,
+} from "./customTrapdoorConstants";
+
+export function checkCustomTrapdoorOpenClose(
+  gridEntity: GridEntity,
+  trapdoorDescription: CustomTrapdoorDescription,
+): void {
+  /** By default, trapdoors will never close if they are already open. */
+  if (trapdoorDescription.open) {
+    return;
+  }
+
+  if (shouldTrapdoorOpen(gridEntity, trapdoorDescription.firstSpawn)) {
+    open(gridEntity, trapdoorDescription);
+  }
+}
+
+function shouldTrapdoorOpen(
+  gridEntity: GridEntity,
+  firstSpawn: boolean,
+): boolean {
+  const room = game.GetRoom();
+  const roomClear = room.IsClear();
+
+  return (
+    !anyPlayerCloserThan(gridEntity.Position, TRAPDOOR_OPEN_DISTANCE) &&
+    !isPlayerCloseAfterBoss(gridEntity.Position) &&
+    !shouldBeClosedFromStartingInRoomWithEnemies(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;
+  }
+
+  return anyPlayerCloserThan(position, TRAPDOOR_OPEN_DISTANCE_AFTER_BOSS);
+}
+
+function shouldBeClosedFromStartingInRoomWithEnemies(
+  firstSpawn: boolean,
+  roomClear: boolean,
+) {
+  return firstSpawn && !roomClear;
+}
+
+function open(
+  gridEntity: GridEntity,
+  trapdoorDescription: CustomTrapdoorDescription,
+) {
+  trapdoorDescription.open = true;
+
+  const sprite = gridEntity.GetSprite();
+  sprite.Play(TrapdoorAnimation.OPEN_ANIMATION, true);
+}
+
+export function shouldTrapdoorSpawnOpen(
+  gridEntity: GridEntity,
+  firstSpawn: boolean,
+): 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;
+  }
+
+  // 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 shouldTrapdoorOpen(gridEntity, firstSpawn);
+}

package/src/features/customTrapdoor/touched.ts

@@ -0,0 +1,195 @@
+import {
+  ButtonAction,
+  EntityCollisionClass,
+  EntityGridCollisionClass,
+  EntityPartition,
+  PlayerType,
+} from "isaac-typescript-definitions";
+import { VectorZero } from "../../constants";
+import { StageTravelState } from "../../enums/private/StageTravelState";
+import { easeOutSine } from "../../functions/easing";
+import {
+  getAllPlayers,
+  getOtherPlayers,
+  isChildPlayer,
+} from "../../functions/playerIndex";
+import { isCharacter } from "../../functions/players";
+import { CustomTrapdoorDescription } from "../../interfaces/private/CustomTrapdoorDescription";
+import { disableAllInputsExceptFor } from "../disableInputs";
+import { isPlayerUsingPony } from "../ponyDetection";
+import { runInNGameFrames, runNextRenderFrame } from "../runInNFrames";
+import {
+  ANIMATIONS_THAT_PREVENT_STAGE_TRAVEL,
+  CUSTOM_TRAPDOOR_FEATURE_NAME,
+  OTHER_PLAYER_TRAPDOOR_JUMP_DELAY_GAME_FRAMES,
+  OTHER_PLAYER_TRAPDOOR_JUMP_DURATION_GAME_FRAMES,
+  TRAPDOOR_TOUCH_DISTANCE,
+} from "./customTrapdoorConstants";
+import v from "./v";
+
+export function checkCustomTrapdoorPlayerTouched(
+  gridEntity: GridEntity,
+  trapdoorDescription: CustomTrapdoorDescription,
+): void {
+  if (v.run.state !== StageTravelState.NONE) {
+    return;
+  }
+
+  if (!trapdoorDescription.open) {
+    return;
+  }
+
+  const playersTouching = Isaac.FindInRadius(
+    gridEntity.Position,
+    TRAPDOOR_TOUCH_DISTANCE,
+    EntityPartition.PLAYER,
+  );
+  for (const playerEntity of playersTouching) {
+    const player = playerEntity.ToPlayer();
+    if (player === undefined) {
+      continue;
+    }
+
+    if (
+      // We don't want a Pony dash to transition to a new floor or a crawl space.
+      !isPlayerUsingPony(player) &&
+      !isChildPlayer(player) &&
+      canPlayerInteractWithTrapdoor(player)
+    ) {
+      playerTouchedCustomTrapdoor(gridEntity, trapdoorDescription, player);
+      return; // Prevent two players from touching the same entity.
+    }
+  }
+}
+
+function canPlayerInteractWithTrapdoor(player: EntityPlayer) {
+  // Players cannot interact with stage travel entities when items are queued or while playing
+  // certain animations.
+  const sprite = player.GetSprite();
+  const animation = sprite.GetAnimation();
+  return (
+    !player.IsHoldingItem() &&
+    !ANIMATIONS_THAT_PREVENT_STAGE_TRAVEL.has(animation)
+  );
+}
+
+function playerTouchedCustomTrapdoor(
+  gridEntity: GridEntity,
+  trapdoorDescription: CustomTrapdoorDescription,
+  player: EntityPlayer,
+) {
+  v.run.state = StageTravelState.PLAYERS_JUMPING_DOWN;
+  v.run.destination = trapdoorDescription.destination;
+
+  const whitelist = new Set([ButtonAction.CONSOLE]);
+  disableAllInputsExceptFor(CUSTOM_TRAPDOOR_FEATURE_NAME, whitelist);
+  setPlayerAttributes(player, gridEntity.Position);
+  dropTaintedForgotten(player);
+
+  player.PlayExtraAnimation("Trapdoor");
+
+  const otherPlayers = getOtherPlayers(player);
+  otherPlayers.forEach((otherPlayer, i) => {
+    const gameFramesToWaitBeforeJumping =
+      OTHER_PLAYER_TRAPDOOR_JUMP_DELAY_GAME_FRAMES * (i + 1);
+    const otherPlayerPtr = EntityPtr(otherPlayer);
+    runInNGameFrames(() => {
+      startDelayedJump(otherPlayerPtr, gridEntity.Position);
+    }, gameFramesToWaitBeforeJumping);
+  });
+}
+
+function setPlayerAttributes(trapdoorPlayer: EntityPlayer, position: Vector) {
+  // Snap the player to the exact position of the trapdoor so that they cleanly jump down the hole.
+  trapdoorPlayer.Position = position;
+
+  for (const player of getAllPlayers()) {
+    // Disable the controls to prevent the player from moving, shooting, and so on. (We also disable
+    // the inputs in the `INPUT_ACTION` callback, but that does not prevent mouse inputs.)
+    player.ControlsEnabled = false;
+
+    // Freeze all players.
+    player.Velocity = VectorZero;
+
+    // We don't want enemy attacks to move the players.
+    player.EntityCollisionClass = EntityCollisionClass.NONE;
+    player.GridCollisionClass = EntityGridCollisionClass.NONE;
+
+    player.SubType = -1;
+  }
+}
+
+function dropTaintedForgotten(player: EntityPlayer) {
+  if (isCharacter(player, PlayerType.THE_FORGOTTEN_B)) {
+    const taintedSoul = player.GetOtherTwin();
+    if (taintedSoul !== undefined) {
+      taintedSoul.ThrowHeldEntity(VectorZero);
+    }
+  }
+}
+
+function startDelayedJump(entityPtr: EntityPtr, trapdoorPosition: Vector) {
+  const entity = entityPtr.Ref;
+  if (entity === undefined) {
+    return;
+  }
+
+  const player = entity.ToPlayer();
+  if (player === undefined) {
+    return;
+  }
+
+  player.PlayExtraAnimation("Trapdoor");
+
+  adjustPlayerPositionToTrapdoor(entityPtr, player.Position, trapdoorPosition);
+}
+
+function adjustPlayerPositionToTrapdoor(
+  entityPtr: EntityPtr,
+  startPos: Vector,
+  endPos: Vector,
+) {
+  if (v.run.state !== StageTravelState.PLAYERS_JUMPING_DOWN) {
+    return;
+  }
+
+  const entity = entityPtr.Ref;
+  if (entity === undefined) {
+    return;
+  }
+
+  const player = entity.ToPlayer();
+  if (player === undefined) {
+    return;
+  }
+
+  runNextRenderFrame(() => {
+    adjustPlayerPositionToTrapdoor(entityPtr, startPos, endPos);
+  });
+
+  const sprite = player.GetSprite();
+  if (sprite.IsFinished("Trapdoor")) {
+    player.Position = endPos;
+    player.Velocity = VectorZero;
+    return;
+  }
+
+  const frame = sprite.GetFrame();
+  if (frame >= OTHER_PLAYER_TRAPDOOR_JUMP_DURATION_GAME_FRAMES) {
+    // We have already arrived at the trapdoor.
+    player.Position = endPos;
+    player.Velocity = VectorZero;
+    return;
+  }
+
+  // Make the player jump towards the trapdoor. We use an easing function so that the distance
+  // traveled is not linear, emulating what the game does.
+  const totalDifference = endPos.sub(startPos);
+  const progress = frame / OTHER_PLAYER_TRAPDOOR_JUMP_DURATION_GAME_FRAMES;
+  const easeProgress = easeOutSine(progress);
+  const differenceForThisFrame = totalDifference.mul(easeProgress);
+  const targetPosition = startPos.add(differenceForThisFrame);
+
+  player.Position = targetPosition;
+  player.Velocity = VectorZero;
+}

package/src/features/customTrapdoor/v.ts

@@ -1,20 +1,26 @@
+import { LevelStage, StageType } from "isaac-typescript-definitions";
+import { DefaultMap } from "../../classes/DefaultMap";
 import { StageTravelState } from "../../enums/private/StageTravelState";
 import { CustomTrapdoorDescription } from "../../interfaces/private/CustomTrapdoorDescription";
 
 const v = {
   run: {
     state: StageTravelState.NONE,
+
+    /** The render frame that this state was reached. */
+    stateRenderFrame: null as int | null,
+
+    destination: null as
+      | [stage: LevelStage, stageType: StageType]
+      | string
+      | null,
   },
 
-  room: {
-    /** Indexed by grid index. */
-    trapdoors: new Map<int, CustomTrapdoorDescription>(),
+  level: {
+    /** Indexed by room list index and grid index. */
+    trapdoors: new DefaultMap<int, Map<int, CustomTrapdoorDescription>>(
+      () => new Map(),
+    ),
   },
 };
-
-export function getCustomTrapdoorDescription(
-  gridEntity: GridEntity,
-): CustomTrapdoorDescription | undefined {
-  const gridIndex = gridEntity.GetGridIndex();
-  return v.room.trapdoors.get(gridIndex);
-}
+export default v;

package/src/features/deployJSONRoom.ts

@@ -161,7 +161,7 @@ function preUseItemWeNeedToGoDeeper(
     fillRoomWithDecorations();
   });
 
-  // Cancel the effect.
+  // Cancel the original effect.
   return true;
 }
 
@@ -225,7 +225,7 @@ function respawnPersistentEntities() {
  * Specifically, this will clear the current room of all entities and grid entities, and then spawn
  * all of the entries and grid entities in the provided JSON room.
  *
- * This function is meant to be used in the PostNewRoom callback.
+ * This function is meant to be used in the `POST_NEW_ROOM` callback.
  *
  * For example:
  *
@@ -277,7 +277,7 @@ export function deployJSONRoom(
  * Specifically, this will clear the current room of all entities and grid entities, and then spawn
  * all of the entries and grid entities in one of the provided JSON rooms.
  *
- * This function is meant to be used in the PostNewRoom callback.
+ * This function is meant to be used in the `POST_NEW_ROOM` callback.
  *
  * Note that this function does not simply choose a random element in the provided array; it will
  * properly account for each room weight using the algorithm from:
@@ -355,8 +355,8 @@ export function emptyRoom(fillWithDecorations: boolean): void {
 }
 
 /**
- * We remove entities in the PostNewRoom callback instead of in the PreRoomEntitySpawn callback so
- * that they will not re-appear when we re-enter the room.
+ * We remove entities in the `POST_NEW_ROOM` callback instead of in the PreRoomEntitySpawn callback
+ * so that they will not re-appear when we re-enter the room.
  */
 function removeSpecificNPCs() {
   const room = game.GetRoom();