isaacscript-common 6.10.2 → 6.11.2

package/src/features/customStage/streakText.ts

@@ -88,8 +88,6 @@ const TEXT_OUT_SCALES = [
  * "loadGraphics", but still manage playing its animations in the code below.
  */
 const topStreakSprite = Sprite();
-topStreakSprite.Load("resources/gfx/ui/ui_streak.anm2", false);
-topStreakSprite.PlaybackSpeed = TEXT_PLAYBACK_SPEED;
 
 /**
  * We do not actually need to render this sprite at all. It's only purpose is to be an invisible
@@ -97,8 +95,19 @@ topStreakSprite.PlaybackSpeed = TEXT_PLAYBACK_SPEED;
  * "loadGraphics", but still manage playing its animations in the code below.
  */
 const bottomStreakSprite = Sprite();
-bottomStreakSprite.Load("resources/gfx/ui/ui_streak.anm2", false);
-bottomStreakSprite.PlaybackSpeed = TEXT_PLAYBACK_SPEED;
+
+/**
+ * We must load the sprites in an init function 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.)
+ */
+export function streakTextInit(): void {
+  topStreakSprite.Load("resources/gfx/ui/ui_streak.anm2", false);
+  topStreakSprite.PlaybackSpeed = TEXT_PLAYBACK_SPEED;
+
+  bottomStreakSprite.Load("resources/gfx/ui/ui_streak.anm2", false);
+  bottomStreakSprite.PlaybackSpeed = TEXT_PLAYBACK_SPEED;
+}
 
 // ModCallback.POST_RENDER (2)
 export function streakTextPostRender(): void {
@@ -278,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/customStage/versusScreen.ts

@@ -66,30 +66,38 @@ const PLAYER_PORTRAIT_PNG_PATH_PREFIX = "gfx/ui/stage";
 const VANILLA_VERSUS_PLAYBACK_SPEED = 0.5;
 
 const versusScreenSprite = Sprite();
-versusScreenSprite.Load("gfx/ui/boss/versusscreen.anm2", false);
-
-// In vanilla, the "overlay.png" file has a white background. We must convert it to a PNG that uses
-// a transparent background in order for the background behind it to be visible. We use the same
-// "overlay.png" file as StageAPI uses for this purpose.
-versusScreenSprite.ReplaceSpritesheet(
-  OVERLAY_ANM2_LAYER,
-  `${ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH}/overlay.png`,
-);
-versusScreenSprite.LoadGraphics();
 
 /**
  * Unfortunately, we must split the background layer into an entirely different sprite so that we
  * can color it with the `Color` property.
  */
 const versusScreenBackgroundSprite = Sprite();
-versusScreenBackgroundSprite.Load("gfx/ui/boss/versusscreen.anm2", true);
 
 /**
  * Unfortunately, we must split the dirt layer into an entirely different sprite so that we can
  * color it with the `Color` property.
  */
 const versusScreenDirtSpotSprite = Sprite();
-versusScreenDirtSpotSprite.Load("gfx/ui/boss/versusscreen.anm2", true);
+
+/**
+ * We must load the sprites in an init function 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.)
+ */
+export function versusScreenInit(): void {
+  // In vanilla, the "overlay.png" file has a white background. We must convert it to a PNG that
+  // uses a transparent background in order for the background behind it to be visible. We use the
+  // same "overlay.png" file as StageAPI uses for this purpose.
+  versusScreenSprite.Load("gfx/ui/boss/versusscreen.anm2", false);
+  versusScreenSprite.ReplaceSpritesheet(
+    OVERLAY_ANM2_LAYER,
+    `${ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH}/overlay.png`,
+  );
+  versusScreenSprite.LoadGraphics();
+
+  versusScreenBackgroundSprite.Load("gfx/ui/boss/versusscreen.anm2", true);
+  versusScreenDirtSpotSprite.Load("gfx/ui/boss/versusscreen.anm2", true);
+}
 
 export function playVersusScreenAnimation(customStage: CustomStage): void {
   const room = game.GetRoom();

package/src/features/customTrapdoor/blackSprite.ts

@@ -0,0 +1,16 @@
+import { VectorZero } from "../../constants";
+import { StageTravelState } from "../../enums/private/StageTravelState";
+import { ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH } from "../customStage/customStageConstants";
+import v from "./v";
+
+const sprite = Sprite();
+sprite.Load(`${ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH}/black.anm2`, true);
+sprite.SetFrame("Default", 0);
+
+export function drawBlackSprite(): void {
+  if (v.run.state !== StageTravelState.PAUSING_ON_BLACK) {
+    return;
+  }
+
+  sprite.RenderLayer(0, VectorZero);
+}

package/src/features/customTrapdoor/customTrapdoorConstants.ts

@@ -0,0 +1,23 @@
+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 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 = 10;
+export const OTHER_PLAYER_TRAPDOOR_JUMP_DURATION_GAME_FRAMES = 8;

package/src/features/customTrapdoor/exports.ts

@@ -0,0 +1,99 @@
+import {
+  GridCollisionClass,
+  LevelStage,
+  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 { getRoomListIndex } from "../../functions/roomData";
+import { isVector } from "../../functions/vector";
+import { CustomTrapdoorDescription } from "../../interfaces/private/CustomTrapdoorDescription";
+import { spawnCustomGridEntity } from "../customGridEntity";
+import {
+  CUSTOM_TRAPDOOR_FEATURE_NAME,
+  GridEntityTypeCustom,
+} from "./customTrapdoorConstants";
+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
+ * attributes:
+ *
+ * - 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.
+ *
+ * Under the hood, the custom trapdoor is represented by a decoration grid entity and is manually
+ * respawned every time the player re-enters the room.
+ *
+ * @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).
+ * @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".
+ * @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,
+  anm2Path = "gfx/grid/door_11_trapdoor.anm2",
+  spawnOpen?: boolean,
+): GridEntity {
+  errorIfFeaturesNotInitialized(CUSTOM_TRAPDOOR_FEATURE_NAME);
+
+  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,
+    GridCollisionClass.NONE,
+    anm2Path,
+    TrapdoorAnimation.OPENED,
+  );
+
+  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 gridEntity;
+}
+
+function getDefaultDestination(): [stage: LevelStage, stageType: StageType] {
+  const nextStage = getNextStage();
+  const nextStageType = getNextStageType();
+
+  return [nextStage, nextStageType];
+}

package/src/features/customTrapdoor/init.ts

@@ -0,0 +1,215 @@
+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,
+  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_UPDATE,
+    postGridEntityUpdateTrapdoor,
+  );
+}
+
+// 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_UPDATE
+// GridEntityType.TRAPDOOR (17)
+function postGridEntityUpdateTrapdoor(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);
+}