isaacscript-common 20.13.1 → 20.14.1

package/src/classes/features/other/CustomStages.ts

@@ -9,7 +9,7 @@ import {
   RoomType,
   StageType,
 } from "isaac-typescript-definitions";
-import { game } from "../../../core/cachedClasses";
+import { game, musicManager } from "../../../core/cachedClasses";
 import * as metadataJSON from "../../../customStageMetadata.json"; // This will correspond to "customStageMetadata.lua" at run-time.
 import { Exported } from "../../../decorators";
 import { ISCFeature } from "../../../enums/ISCFeature";
@@ -28,6 +28,7 @@ import {
   getRoomDataForTypeVariant,
   getRoomsInsideGrid,
 } from "../../../functions/rooms";
+import { getMusicForStage } from "../../../functions/sound";
 import { setStage } from "../../../functions/stage";
 import { asNumber } from "../../../functions/types";
 import {
@@ -457,22 +458,23 @@ export class CustomStages extends Feature {
       level.SetStage(LevelStage.BASEMENT_1, StageType.ORIGINAL);
     }
 
-    let baseStage =
+    let baseStage: LevelStage =
       customStage.baseStage === undefined
         ? DEFAULT_BASE_STAGE
-        : customStage.baseStage;
+        : (customStage.baseStage as LevelStage);
     if (!firstFloor) {
-      baseStage++;
+      baseStage++; // eslint-disable-line isaacscript/strict-enums
     }
 
-    const baseStageType =
+    const baseStageType: StageType =
       customStage.baseStageType === undefined
         ? DEFAULT_BASE_STAGE_TYPE
-        : customStage.baseStageType;
+        : (customStage.baseStageType as StageType);
 
+    // eslint-disable-next-line isaacscript/strict-enums
     const reseed = asNumber(stage) >= baseStage;
 
-    setStage(baseStage as LevelStage, baseStageType as StageType, reseed);
+    setStage(baseStage, baseStageType, reseed);
 
     this.setStageRoomsData(customStage, rng, verbose);
 
@@ -495,6 +497,16 @@ export class CustomStages extends Feature {
       });
     }
 
+    // The bugged stage will not have any music associated with it, so we must manually start to
+    // play a track.
+    const music =
+      customStage.music === undefined
+        ? getMusicForStage(baseStage, baseStageType)
+        : Isaac.GetMusicIdByName(customStage.music);
+    this.runInNFrames.runNextGameFrame(() => {
+      musicManager.Play(music);
+    });
+
     // 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 an arbitrary room.

package/src/classes/features/other/extraConsoleCommands/commands.ts

@@ -79,6 +79,7 @@ import { addFlag } from "../../../../functions/flag";
 import { spawnGridEntity } from "../../../../functions/gridEntities";
 import { getRoomGridIndexesForType } from "../../../../functions/levelGrid";
 import {
+  logMusic,
   logPlayerEffects,
   logRoom,
   logSeedEffects,
@@ -961,6 +962,12 @@ export function miniboss(): void {
   warpToRoomType(RoomType.MINI_BOSS);
 }
 
+/** Logs the currently playing music track to the "log.txt" file. */
+export function music(): void {
+  logMusic();
+  print('Logged the currently playing music track to the "log.txt" file.');
+}
+
 /** Alias for the "disableCurses" command. */
 export function noCurses(): void {
   disableCurses();

package/src/functions/logMisc.ts

@@ -6,13 +6,14 @@ import {
   GridRoom,
   HeartSubType,
   LevelStateFlag,
+  Music,
   ProjectileFlag,
   SeedEffect,
   SoundEffect,
   TearFlag,
   UseFlag,
 } from "isaac-typescript-definitions";
-import { game, sfxManager } from "../core/cachedClasses";
+import { game, musicManager, sfxManager } from "../core/cachedClasses";
 import { arrayToString, isArray } from "./array";
 import { getCollectibleName } from "./collectibles";
 import { getEntityID } from "./entities";
@@ -194,6 +195,13 @@ export function logMap(this: void, map: Map<AnyNotNil, unknown>): void {
   log(`  The size of the map was: ${map.size}`);
 }
 
+export function logMusic(this: void): void {
+  const currentMusic = musicManager.GetCurrentMusicID();
+  log(
+    `Currently playing music track: ${Music[currentMusic]} (${currentMusic})`,
+  );
+}
+
 export function logPlayerEffects(this: void, player: EntityPlayer): void {
   const effects = getEffectsList(player);
 

package/src/functions/sound.ts

@@ -1,9 +1,54 @@
-import { SoundEffect } from "isaac-typescript-definitions";
-import { sfxManager } from "../core/cachedClasses";
+import {
+  LevelStage,
+  Music,
+  SoundEffect,
+  StageType,
+} from "isaac-typescript-definitions";
+import { game, sfxManager } from "../core/cachedClasses";
+import { STAGE_TO_MUSIC } from "../objects/stageToMusic";
 import { getEnumValues } from "./enums";
 
-export function stopAllSoundEffects(): void {
+/**
+ * Helper function to get the corresponding music value for a stage and stage type combination.
+ *
+ * @param stage Optional. The stage to get the music for. If not specified, the current stage will
+ *              be used.
+ * @param stageType Optional. The stage type to get the music for. If not specified, the current
+ *                  stage type will be used.
+ */
+export function getMusicForStage(
+  stage?: LevelStage,
+  stageType?: StageType,
+): Music {
+  const level = game.GetLevel();
+
+  if (stage === undefined) {
+    stage = level.GetStage();
+  }
+
+  if (stageType === undefined) {
+    stageType = level.GetStageType();
+  }
+
+  const stageTypeToMusic = STAGE_TO_MUSIC[stage];
+  return stageTypeToMusic[stageType];
+}
+
+/**
+ * Helper function to manually stop every vanilla sound effect. If you also want to stop custom
+ * sound effects in addition to vanilla ones, then pass the `SoundEffectCustom` enum for your mod.
+ *
+ * @param soundEffectCustom Optional. The enum that represents all of the custom sound effects for
+ *                          your mod.
+ */
+export function stopAllSoundEffects(soundEffectCustom?: unknown): void {
   for (const soundEffect of getEnumValues(SoundEffect)) {
     sfxManager.Stop(soundEffect);
   }
+
+  if (soundEffectCustom !== undefined) {
+    for (const soundEffect of getEnumValues(soundEffectCustom)) {
+      sfxManager.Stop(soundEffect as SoundEffect);
+    }
+  }
 }

package/src/functions/ui.ts

@@ -4,9 +4,10 @@ import { UI_HEART_WIDTH, VectorZero } from "../core/constants";
 import { copyVector } from "./vector";
 
 /**
- * In the options menu, players have the ability to set a HUD offset. This uses the current HUD
- * offset to generate a vector that should be added to the corresponding position that you want to
- * draw a UI element.
+ * In the options menu, players have the ability to set a HUD offset (which gets written to the
+ * `HudOffset` attribute in the "options.ini" file). This function uses the current HUD offset to
+ * generate a vector that should be added to the corresponding position that you want to draw a UI
+ * element at.
  *
  * For example:
  * - If the user does not have a HUD offset configured, this function will return `Vector(0, 0)`.

package/src/interfaces/CustomStageTSConfig.ts

@@ -70,6 +70,14 @@ export interface CustomStageTSConfig {
    */
   baseStageType?: number;
 
+  /**
+   * Optional. A string that represents the name of the music track from the "content/music.xml"
+   * file that corresponds to this custom stage. It will be manually played upon entering the stage.
+   *
+   * If not specified, the same music track as the base stage will be used.
+   */
+  music?: string;
+
   /**
    * Optional. An object containing the paths to the backdrop graphics for the stage. (A backdrop is
    * the graphics for the walls and floor.) If not specified, the graphics for Basement will be

package/src/objects/stageToMusic.ts

@@ -0,0 +1,99 @@
+import { LevelStage, Music, StageType } from "isaac-typescript-definitions";
+import { HasAllEnumKeys } from "../types/HasAllEnumKeys";
+
+const BASEMENT_TO_MUSIC = {
+  [StageType.ORIGINAL]: Music.BASEMENT,
+  [StageType.WRATH_OF_THE_LAMB]: Music.CELLAR,
+  [StageType.AFTERBIRTH]: Music.BURNING_BASEMENT,
+  [StageType.GREED_MODE]: Music.BASEMENT,
+  [StageType.REPENTANCE]: Music.DOWNPOUR,
+  [StageType.REPENTANCE_B]: Music.DROSS,
+} as const satisfies HasAllEnumKeys<StageType, Music>;
+
+const CAVES_TO_MUSIC = {
+  [StageType.ORIGINAL]: Music.CAVES,
+  [StageType.WRATH_OF_THE_LAMB]: Music.CATACOMBS,
+  [StageType.AFTERBIRTH]: Music.FLOODED_CAVES,
+  [StageType.GREED_MODE]: Music.CAVES,
+  [StageType.REPENTANCE]: Music.MINES,
+  [StageType.REPENTANCE_B]: Music.ASHPIT,
+} as const satisfies HasAllEnumKeys<StageType, Music>;
+
+const DEPTHS_TO_MUSIC = {
+  [StageType.ORIGINAL]: Music.DEPTHS,
+  [StageType.WRATH_OF_THE_LAMB]: Music.NECROPOLIS,
+  [StageType.AFTERBIRTH]: Music.DANK_DEPTHS,
+  [StageType.GREED_MODE]: Music.DEPTHS,
+  [StageType.REPENTANCE]: Music.MAUSOLEUM,
+  [StageType.REPENTANCE_B]: Music.GEHENNA,
+} as const satisfies HasAllEnumKeys<StageType, Music>;
+
+const WOMB_TO_MUSIC = {
+  [StageType.ORIGINAL]: Music.WOMB,
+  [StageType.WRATH_OF_THE_LAMB]: Music.UTERO,
+  [StageType.AFTERBIRTH]: Music.SCARRED_WOMB,
+  [StageType.GREED_MODE]: Music.WOMB,
+  [StageType.REPENTANCE]: Music.CORPSE,
+  [StageType.REPENTANCE_B]: Music.MORTIS,
+} as const satisfies HasAllEnumKeys<StageType, Music>;
+
+const BLUE_WOMB_TO_MUSIC = {
+  [StageType.ORIGINAL]: Music.BLUE_WOMB,
+  [StageType.WRATH_OF_THE_LAMB]: Music.BLUE_WOMB,
+  [StageType.AFTERBIRTH]: Music.BLUE_WOMB,
+  [StageType.GREED_MODE]: Music.BLUE_WOMB,
+  [StageType.REPENTANCE]: Music.BLUE_WOMB,
+  [StageType.REPENTANCE_B]: Music.BLUE_WOMB,
+} as const satisfies HasAllEnumKeys<StageType, Music>;
+
+const SHEOL_CATHEDRAL_TO_MUSIC = {
+  [StageType.ORIGINAL]: Music.SHEOL,
+  [StageType.WRATH_OF_THE_LAMB]: Music.CATHEDRAL,
+  [StageType.AFTERBIRTH]: Music.SHEOL,
+  [StageType.GREED_MODE]: Music.SHEOL,
+  [StageType.REPENTANCE]: Music.SHEOL,
+  [StageType.REPENTANCE_B]: Music.SHEOL,
+} as const satisfies HasAllEnumKeys<StageType, Music>;
+
+const DARK_ROOM_CHEST_TO_MUSIC = {
+  [StageType.ORIGINAL]: Music.DARK_ROOM,
+  [StageType.WRATH_OF_THE_LAMB]: Music.CHEST,
+  [StageType.AFTERBIRTH]: Music.DARK_ROOM,
+  [StageType.GREED_MODE]: Music.DARK_ROOM,
+  [StageType.REPENTANCE]: Music.DARK_ROOM,
+  [StageType.REPENTANCE_B]: Music.DARK_ROOM,
+} as const satisfies HasAllEnumKeys<StageType, Music>;
+
+const THE_VOID_TO_MUSIC = {
+  [StageType.ORIGINAL]: Music.VOID,
+  [StageType.WRATH_OF_THE_LAMB]: Music.VOID,
+  [StageType.AFTERBIRTH]: Music.VOID,
+  [StageType.GREED_MODE]: Music.VOID,
+  [StageType.REPENTANCE]: Music.VOID,
+  [StageType.REPENTANCE_B]: Music.VOID,
+} as const satisfies HasAllEnumKeys<StageType, Music>;
+
+const HOME_TO_MUSIC = {
+  [StageType.ORIGINAL]: Music.ISAACS_HOUSE,
+  [StageType.WRATH_OF_THE_LAMB]: Music.ISAACS_HOUSE,
+  [StageType.AFTERBIRTH]: Music.ISAACS_HOUSE,
+  [StageType.GREED_MODE]: Music.ISAACS_HOUSE,
+  [StageType.REPENTANCE]: Music.ISAACS_HOUSE,
+  [StageType.REPENTANCE_B]: Music.ISAACS_HOUSE,
+} as const satisfies HasAllEnumKeys<StageType, Music>;
+
+export const STAGE_TO_MUSIC = {
+  [LevelStage.BASEMENT_1]: BASEMENT_TO_MUSIC,
+  [LevelStage.BASEMENT_2]: BASEMENT_TO_MUSIC,
+  [LevelStage.CAVES_1]: CAVES_TO_MUSIC,
+  [LevelStage.CAVES_2]: CAVES_TO_MUSIC,
+  [LevelStage.DEPTHS_1]: DEPTHS_TO_MUSIC,
+  [LevelStage.DEPTHS_2]: DEPTHS_TO_MUSIC,
+  [LevelStage.WOMB_1]: WOMB_TO_MUSIC,
+  [LevelStage.WOMB_2]: WOMB_TO_MUSIC,
+  [LevelStage.BLUE_WOMB]: BLUE_WOMB_TO_MUSIC,
+  [LevelStage.SHEOL_CATHEDRAL]: SHEOL_CATHEDRAL_TO_MUSIC,
+  [LevelStage.DARK_ROOM_CHEST]: DARK_ROOM_CHEST_TO_MUSIC,
+  [LevelStage.THE_VOID]: THE_VOID_TO_MUSIC,
+  [LevelStage.HOME]: HOME_TO_MUSIC,
+} as const satisfies HasAllEnumKeys<LevelStage, Record<StageType, Music>>;