isaacscript-common 6.11.2 → 6.14.0

package/src/features/pause.ts

@@ -4,17 +4,36 @@ import {
   InputHook,
   ModCallback,
 } from "isaac-typescript-definitions";
+import { VectorZero } from "../constants";
+import {
+  getProjectiles,
+  getTears,
+  removeAllProjectiles,
+  removeAllTears,
+} from "../functions/entitiesSpecific";
+import { isTear } from "../functions/isaacAPIClass";
 import { logError } from "../functions/log";
+import { getAllPlayers } from "../functions/playerIndex";
 import { useActiveItemTemp } from "../functions/players";
 import { disableAllInputsExceptFor, enableAllInputs } from "./disableInputs";
 import { saveDataManager } from "./saveDataManager/exports";
 
 const FEATURE_NAME = "pause";
 
+interface InitialDescription {
+  position: Vector;
+  positionOffset: Vector;
+  velocity: Vector;
+  height: float;
+  fallingSpeed: float;
+  fallingAcceleration: float;
+}
+
 const v = {
   run: {
     isPseudoPaused: false,
     shouldUnpause: false,
+    initialDescriptions: new Map<PtrHash, InitialDescription>(),
   },
 };
 
@@ -37,8 +56,34 @@ function postUpdate() {
     return;
   }
 
-  const player = Isaac.GetPlayer();
-  useActiveItemTemp(player, CollectibleType.PAUSE);
+  const firstPlayer = Isaac.GetPlayer();
+  useActiveItemTemp(firstPlayer, CollectibleType.PAUSE);
+
+  stopTearsAndProjectilesFromMoving();
+}
+
+function stopTearsAndProjectilesFromMoving() {
+  const tearsAndProjectiles = [...getTears(), ...getProjectiles()];
+
+  for (const tearOrProjectile of tearsAndProjectiles) {
+    const ptrHash = GetPtrHash(tearOrProjectile);
+    const initialDescription = v.run.initialDescriptions.get(ptrHash);
+    if (initialDescription === undefined) {
+      continue;
+    }
+
+    tearOrProjectile.Position = initialDescription.position;
+    tearOrProjectile.PositionOffset = initialDescription.positionOffset;
+    tearOrProjectile.Velocity = VectorZero;
+    tearOrProjectile.Height = initialDescription.height;
+    tearOrProjectile.FallingSpeed = 0;
+    if (isTear(tearOrProjectile)) {
+      tearOrProjectile.FallingAcceleration =
+        initialDescription.fallingAcceleration;
+    } else {
+      tearOrProjectile.FallingAccel = initialDescription.fallingAcceleration;
+    }
+  }
 }
 
 // ModCallback.INPUT_ACTION (13)
@@ -57,8 +102,8 @@ function inputActionGetActionValue(
   }
   v.run.shouldUnpause = false;
 
-  // Returning a value of 1 for a single frame will be enough for the game to register an unpause
-  // but not enough for a tear to actually be fired.
+  // Returning a value of 1 for a single sub-frame will be enough for the game to register an
+  // unpause but not enough for a tear to actually be fired.
   return 1;
 }
 
@@ -68,7 +113,7 @@ function inputActionGetActionValue(
  *
  * Under the hood, this function:
  * - uses the Pause collectible on every game frame
- * - disables any player inputs (except for `ButtonAction.MENU_CONFIRM`)
+ * - disables any player inputs (except for `ButtonAction.MENU_CONFIRM` and `ButtonAction.CONSOLE`)
  */
 export function pause(): void {
   if (v.run.isPseudoPaused) {
@@ -79,8 +124,43 @@ export function pause(): void {
   }
   v.run.isPseudoPaused = true;
 
-  const whitelist = new Set([ButtonAction.MENU_CONFIRM]);
+  // Tears/projectiles in the room will move slightly on every frame, even when the Pause
+  // collectible is active. Thus, we manually reset the initial positions and heights on every
+  // frame.
+  v.run.initialDescriptions.clear();
+  const tearsAndProjectiles = [...getTears(), ...getProjectiles()];
+  for (const tearOrProjectile of tearsAndProjectiles) {
+    const ptrHash = GetPtrHash(tearOrProjectile);
+    const initialDescription: InitialDescription = {
+      position: tearOrProjectile.Position,
+      positionOffset: tearOrProjectile.PositionOffset,
+      velocity: tearOrProjectile.Velocity,
+      height: tearOrProjectile.Height,
+      fallingSpeed: tearOrProjectile.FallingSpeed,
+      fallingAcceleration: isTear(tearOrProjectile)
+        ? tearOrProjectile.FallingAcceleration
+        : tearOrProjectile.FallingAccel,
+    };
+    v.run.initialDescriptions.set(ptrHash, initialDescription);
+  }
+
+  const firstPlayer = Isaac.GetPlayer();
+  useActiveItemTemp(firstPlayer, CollectibleType.PAUSE);
+
+  const whitelist = new Set([ButtonAction.MENU_CONFIRM, ButtonAction.CONSOLE]);
   disableAllInputsExceptFor(FEATURE_NAME, whitelist);
+
+  for (const player of getAllPlayers()) {
+    // Disable the controls to prevent the players 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;
+
+    // Prevent the players from leaving the room. (If we don't reset the velocity, they can continue
+    // to move towards a door.)
+    player.Velocity = VectorZero;
+  }
+
+  stopTearsAndProjectilesFromMoving();
 }
 
 /** Helper function to put things back to normal after the `pause` function was used. */
@@ -92,7 +172,17 @@ export function unpause(): void {
     return;
   }
   v.run.isPseudoPaused = false;
+  v.run.shouldUnpause = true;
 
   enableAllInputs(FEATURE_NAME);
-  v.run.shouldUnpause = true;
+  for (const player of getAllPlayers()) {
+    player.ControlsEnabled = true;
+  }
+
+  // After a vanilla pause, the tears will not resume their normal velocity and will "stick" to the
+  // air. Even if we try to help the tears along by explicitly resetting all of the velocity-related
+  // variables to their initial values, this will not make a difference. Thus, revert to removing
+  // all of the tears and projectiles in the room.
+  removeAllTears();
+  removeAllProjectiles();
 }

package/src/features/persistentEntities.ts

@@ -3,12 +3,12 @@ import {
   EntityType,
   ModCallback,
 } from "isaac-typescript-definitions";
-import { game } from "../cachedClasses";
 import { ModUpgraded } from "../classes/ModUpgraded";
 import { ModCallbackCustom } from "../enums/ModCallbackCustom";
 import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
 import { spawn } from "../functions/entities";
 import { getRoomListIndex } from "../functions/roomData";
+import { getLatestRoomDescription } from "./roomHistory";
 import { saveDataManager } from "./saveDataManager/exports";
 
 interface PersistentEntityDescription {
@@ -64,18 +64,19 @@ function postEntityRemove(entity: Entity) {
   const index = tuple[0];
 
   // The persistent entity is despawning, presumably because the player is in the process of leaving
-  // the room. Keep track of the position for later. We use the previous room list index because at
-  // this point, the PostNewRoom callback has already fired and we are in a new room.
-  const level = game.GetLevel();
-  const previousRoomGridIndex = level.GetPreviousRoomIndex();
-  const previousRoomListIndex = getRoomListIndex(previousRoomGridIndex);
-  v.level.persistentEntities.set(index, {
+  // the room. Keep track of the position for later. We use the previous room list index because
+  // even though the `POST_NEW_ROOM` callback was not fired yet, we have already traveled to the
+  // next room.
+  const previousRoomDescription = getLatestRoomDescription();
+  const previousRoomListIndex = previousRoomDescription.roomListIndex;
+  const persistentEntityDescription: PersistentEntityDescription = {
     entityType: entity.Type,
     variant: entity.Variant,
     subType: entity.SubType,
     roomListIndex: previousRoomListIndex,
     position: entity.Position,
-  });
+  };
+  v.level.persistentEntities.set(index, persistentEntityDescription);
 }
 
 // ModCallbackCustom.POST_NEW_ROOM_REORDERED

package/src/features/pickupIndex.ts

@@ -0,0 +1,257 @@
+import {
+  EntityType,
+  ModCallback,
+  RoomType,
+} from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { DefaultMap } from "../classes/DefaultMap";
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import { getEntityID } from "../functions/entities";
+import { getPickups } from "../functions/entitiesSpecific";
+import { getRoomListIndex } from "../functions/roomData";
+import { onAscent } from "../functions/stage";
+import { vectorEquals } from "../functions/vector";
+import { PickupIndex } from "../types/PickupIndex";
+import { getLatestRoomDescription } from "./roomHistory";
+import { saveDataManager } from "./saveDataManager/exports";
+
+interface PickupDescription {
+  position: Vector;
+  initSeed: Seed;
+}
+
+const FEATURE_NAME = "pickupIndex";
+
+const v = {
+  run: {
+    pickupCounter: 0 as PickupIndex,
+    currentRoomListIndex: 0,
+
+    pickupDataTreasureRooms: new Map<PickupIndex, PickupDescription>(),
+    pickupDataBossRooms: new Map<PickupIndex, PickupDescription>(),
+  },
+
+  level: {
+    /** Indexed by room list index. */
+    pickupData: new DefaultMap<int, Map<PickupIndex, PickupDescription>>(
+      () => new Map(),
+    ),
+  },
+
+  room: {
+    pickupIndexes: new Map<PtrHash, PickupIndex>(),
+  },
+};
+
+export function pickupIndexInit(mod: ModUpgraded): void {
+  saveDataManager(FEATURE_NAME, v);
+
+  mod.AddCallback(ModCallback.POST_PICKUP_INIT, postPickupInit); // 34
+  mod.AddCallback(
+    ModCallback.POST_ENTITY_REMOVE,
+    postEntityRemovePickup,
+    EntityType.PICKUP,
+  ); // 67
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_NEW_ROOM_REORDERED,
+    postNewRoomReordered,
+  );
+}
+
+// ModCallback.POST_PICKUP_INIT (34)
+function postPickupInit(pickup: EntityPickup) {
+  const ptrHash = GetPtrHash(pickup);
+
+  // In certain situations, pickups can be morphed, and this should not incur a new pickup counter.
+  // (For example, the collectible rotation with Tainted Isaac.)
+  if (v.room.pickupIndexes.has(ptrHash)) {
+    return;
+  }
+
+  // If we are re-entering a room that previously had a pickup, then we don't need to make a new
+  // index, because we will re-use the existing one.
+  const room = game.GetRoom();
+  const isFirstVisit = room.IsFirstVisit();
+  const roomFrameCount = room.GetFrameCount();
+  if (!isFirstVisit && roomFrameCount <= 0) {
+    return;
+  }
+
+  v.run.pickupCounter++;
+  v.room.pickupIndexes.set(ptrHash, v.run.pickupCounter);
+
+  // Additionally, keep track of which room we are storing the pointer hashes for.
+  v.run.currentRoomListIndex = getRoomListIndex();
+}
+
+// ModCallback.POST_ENTITY_REMOVE (67)
+// EntityType.PICKUP (5)
+function postEntityRemovePickup(entity: Entity) {
+  checkDespawningFromPlayerLeavingRoom(entity);
+}
+
+function checkDespawningFromPlayerLeavingRoom(entity: Entity) {
+  const ptrHash = GetPtrHash(entity);
+  const pickupIndex = v.room.pickupIndexes.get(ptrHash);
+  if (pickupIndex === undefined) {
+    return;
+  }
+
+  const roomListIndex = getRoomListIndex();
+  if (roomListIndex === v.run.currentRoomListIndex) {
+    // This is a pickup that is despawning in the current room. For example, it could be a heart
+    // pickup that the player picked up. Thus, we do not need to keep track of it's metadata.
+    return;
+  }
+
+  trackDespawningPickupMetadata(entity, pickupIndex);
+}
+
+/**
+ * This is a pickup that is despawning because the player is in the process of leaving the room.
+ * Keep track of the metadata for later. We need to use the previous room list index because even
+ * though the `POST_NEW_ROOM` callback was not fired yet, we have already traveled to the next room.
+ */
+function trackDespawningPickupMetadata(
+  entity: Entity,
+  pickupIndex: PickupIndex,
+) {
+  const previousRoomDescription = getLatestRoomDescription();
+  const previousRoomListIndex = previousRoomDescription.roomListIndex;
+  const pickupDescriptions = v.level.pickupData.getAndSetDefault(
+    previousRoomListIndex,
+  );
+
+  const pickupDescription: PickupDescription = {
+    position: entity.Position,
+    initSeed: entity.InitSeed,
+  };
+  pickupDescriptions.set(pickupIndex, pickupDescription);
+
+  // If the despawning pickup was in a Treasure Room or Boss Room, then it is possible that the
+  // pickup could re-appear during The Ascent. If this is the case, we store the metadata on a
+  // separate map to reference later.
+  if (onAscent()) {
+    return;
+  }
+
+  const room = game.GetRoom();
+  const roomType = room.GetType();
+
+  switch (roomType) {
+    case RoomType.TREASURE: {
+      v.run.pickupDataTreasureRooms.set(pickupIndex, pickupDescription);
+      break;
+    }
+
+    case RoomType.BOSS: {
+      v.run.pickupDataBossRooms.set(pickupIndex, pickupDescription);
+      break;
+    }
+
+    default: {
+      break;
+    }
+  }
+}
+
+// ModCallbackCustom.POST_NEW_ROOM_REORDERED
+function postNewRoomReordered() {
+  const room = game.GetRoom();
+  const isFirstVisit = room.IsFirstVisit();
+
+  if (isFirstVisit) {
+    return;
+  }
+
+  const roomListIndex = getRoomListIndex();
+  const pickupDescriptions = v.level.pickupData.getAndSetDefault(roomListIndex);
+
+  for (const pickup of getPickups()) {
+    let pickupIndex = getStoredPickupIndex(pickup, pickupDescriptions);
+    if (pickupIndex === undefined) {
+      pickupIndex = getPostAscentPickupIndex(pickup);
+    }
+
+    if (pickupIndex === undefined) {
+      const entityID = getEntityID(pickup);
+      error(
+        `Failed to find a pickup index corresponding to existing pickup: ${entityID}`,
+      );
+    }
+
+    const ptrHash = GetPtrHash(pickup);
+    v.room.pickupIndexes.set(ptrHash, pickupIndex);
+  }
+}
+
+function getStoredPickupIndex(
+  pickup: Entity,
+  pickupDescriptions: Map<PickupIndex, PickupDescription>,
+): PickupIndex | undefined {
+  for (const [pickupIndex, pickupDescription] of pickupDescriptions.entries()) {
+    if (
+      vectorEquals(pickupDescription.position, pickup.Position) &&
+      pickupDescription.initSeed === pickup.InitSeed
+    ) {
+      return pickupIndex;
+    }
+  }
+
+  return undefined;
+}
+
+function getPostAscentPickupIndex(pickup: EntityPickup) {
+  // If we have not found the pickup index yet, we might be re-entering a post-Ascent Treasure Room
+  // or Boss Room.
+  if (!onAscent()) {
+    return undefined;
+  }
+
+  const room = game.GetRoom();
+  const roomType = room.GetType();
+
+  switch (roomType) {
+    case RoomType.TREASURE: {
+      return getStoredPickupIndex(pickup, v.run.pickupDataTreasureRooms);
+    }
+
+    case RoomType.BOSS: {
+      return getStoredPickupIndex(pickup, v.run.pickupDataBossRooms);
+    }
+
+    default: {
+      return undefined;
+    }
+  }
+}
+
+/**
+ * Mods often have to track variables relating to a pickups. Finding an index for these kinds of
+ * data structures is difficult, since pickups are respawned every time a player re-enters a room,
+ * so the `PtrHash` will change.
+ *
+ * Use this function to get a unique index for a pickup to use in these data structures.
+ *
+ * Specifically, `PickupIndex` is a number that represents the spawn order of the pickup on the
+ * current run. For example, the first pickup spawned will have an index of 1, the second one will
+ * have an index of 2, and so on.
+ *
+ * Tracking pickups requires stateful tracking, so using pickup indexes requires an upgraded mod.
+ */
+export function getPickupIndex(pickup: EntityPickup): PickupIndex {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  const ptrHash = GetPtrHash(pickup);
+  const pickupIndex = v.room.pickupIndexes.get(ptrHash);
+  if (pickupIndex === undefined) {
+    const entityID = getEntityID(pickup);
+    error(
+      `Failed to get a pickup index for entity ${entityID} with hash: ${ptrHash}`,
+    );
+  }
+
+  return pickupIndex;
+}

package/src/features/playerInventory.ts

@@ -76,8 +76,8 @@ function useItemD4(
 
 // ModCallback.POST_GAME_STARTED (15)
 function postGameStarted() {
-  // We don't use the PostPlayerInit callback because some items are not given to the player at that
-  // point.
+  // We don't use the `POST_PLAYER_INIT` callback because some items are not given to the player at
+  // that point.
   for (const player of getAllPlayers()) {
     const playerIndex = getPlayerIndex(player);
     if (!v.run.playersInventory.has(playerIndex)) {

package/src/features/roomHistory.ts

@@ -0,0 +1,113 @@
+import { game } from "../cachedClasses";
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import { getLastElement } from "../functions/array";
+import {
+  getRoomGridIndex,
+  getRoomListIndex,
+  getRoomName,
+  getRoomStageID,
+  getRoomSubType,
+  getRoomVariant,
+} from "../functions/roomData";
+import { RoomDescription } from "../interfaces/RoomDescription";
+import { saveDataManager } from "./saveDataManager/exports";
+
+const FEATURE_NAME = "roomHistory";
+
+const v = {
+  run: {
+    roomHistory: [] as RoomDescription[],
+  },
+};
+
+/** @internal */
+export function roomHistoryInit(mod: ModUpgraded): void {
+  saveDataManager(FEATURE_NAME, v);
+
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_NEW_ROOM_EARLY,
+    postNewRoomEarly,
+  );
+}
+
+// ModCallbackCustom.POST_NEW_ROOM_EARLY
+function postNewRoomEarly() {
+  const level = game.GetLevel();
+  const stage = level.GetStage();
+  const stageType = level.GetStageType();
+  const room = game.GetRoom();
+  const roomType = room.GetType();
+  const stageID = getRoomStageID();
+  const roomVariant = getRoomVariant();
+  const roomSubType = getRoomSubType();
+  const roomName = getRoomName();
+  const roomGridIndex = getRoomGridIndex();
+  const roomListIndex = getRoomListIndex();
+
+  const roomDescription: RoomDescription = {
+    stage,
+    stageType,
+    stageID,
+    roomType,
+    roomVariant,
+    roomSubType,
+    roomName,
+    roomGridIndex,
+    roomListIndex,
+  };
+  v.run.roomHistory.push(roomDescription);
+}
+
+/**
+ * Helper function to get information about all of the rooms that a player has visited thus far on
+ * this run.
+ */
+export function getRoomHistory(): readonly RoomDescription[] {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  return v.run.roomHistory;
+}
+
+/**
+ * Helper function to get information about the room that was previously visited.
+ *
+ * In the special case of only one room having been visited thus far (i.e. the starting room of the
+ * run), the starting room will be returned.
+ */
+export function getPreviousRoomDescription(): RoomDescription {
+  const previousRoomDescription =
+    v.run.roomHistory[v.run.roomHistory.length - 2];
+  if (previousRoomDescription !== undefined) {
+    return previousRoomDescription;
+  }
+
+  const startingRoomDescription = v.run.roomHistory[0];
+  if (startingRoomDescription !== undefined) {
+    return startingRoomDescription;
+  }
+
+  error(
+    "Failed to find a room description for any rooms thus far on this run.",
+  );
+}
+
+/**
+ * Helper function to get information about the most recent room that is stored in the room history
+ * array.
+ *
+ * This is useful in the `POST_ENTITY_REMOVE` callback, since if an entity is despawning due to a
+ * player having left the room, the current room will have changed already, but the `POST_NEW_ROOM`
+ * callback will not have fired yet, and there will not be an entry in the room history array for
+ * the current room.
+ */
+export function getLatestRoomDescription(): RoomDescription {
+  const latestRoomDescription = getLastElement(v.run.roomHistory);
+  if (latestRoomDescription === undefined) {
+    error(
+      "Failed to get the latest room description since the room history array was empty.",
+    );
+  }
+
+  return latestRoomDescription;
+}

package/src/features/saveDataManager/main.ts

@@ -65,8 +65,8 @@ function postPlayerInit() {
     restoreDefaultsAll();
   }
 
-  // On continued runs, the PostNewLevel callback will not fire, so we do not have to worry about
-  // saved data based on level getting overwritten.
+  // On continued runs, the `POST_NEW_LEVEL` callback will not fire, so we do not have to worry
+  // about saved data based on level getting overwritten.
 }
 
 // ModCallback.PRE_GAME_EXIT (17)

package/src/features/taintedLazarusPlayers.ts

@@ -58,11 +58,11 @@ function postPlayerInit(player: EntityPlayer) {
 /**
  * Indexes are the `PtrHash`, values are the `EntityPtr` of the *other* Lazarus.
  *
- * When starting a run, the PostPlayerInit callback will fire first for Dead Tainted Lazarus, then
- * for Tainted Lazarus. When continuing a run, the PostPlayerInit callback will fire first for the
- * character that is currently active. Thus, since the order of the characters is not certain, we
- * insert each of their pointers into a queue, and then only populate the map when we have one
- * Tainted Lazarus and one Dead Tainted Lazarus.
+ * When starting a run, the `POST_PLAYER_INIT` callback will fire first for Dead Tainted Lazarus,
+ * then for Tainted Lazarus. When continuing a run, the `POST_PLAYER_INIT` callback will fire first
+ * for the character that is currently active. Thus, since the order of the characters is not
+ * certain, we insert each of their pointers into a queue, and then only populate the map when we
+ * have one Tainted Lazarus and one Dead Tainted Lazarus.
  */
 function checkDequeue() {
   if (

package/src/functions/collectibles.ts

@@ -176,38 +176,51 @@ export function getCollectibleGfxFilename(
 }
 
 /**
- * Mods often have to track variables relating to a collectible. Finding an index for these kinds of
- * data structures is difficult, since collectibles are respawned every time a player re-enters a
- * room, so the `PtrHash` will change. Instead, we use a 4-tuple of the room list index, the grid
- * index of the collectible in the room, the collectible's SubType, and the collectible's InitSeed.
+ * Mods may have to keep track of data relating to a collectible. Finding an index for these kinds
+ * of data structures is difficult, since collectibles are respawned every time a player re-enters a
+ * room (like all other pickups), so the `PtrHash` will change.
+ *
+ * Use this function to get a unique index for a collectible to use in these data structures.
+ *
+ * If your mod is upgraded, then you should use the `getPickupIndex` function instead, as it is more
+ * general purpose and less prone to error (but relies on stateful tracking of pickups as the run
+ * progresses).
+ *
+ * Collectibles are a special case of pickups: they cannot be pushed around. (They actually can be
+ * pushed, but usually will stay on the same grid index.) Thus, it is possible to generate a
+ * somewhat reliable non-stateful index for collectibles. We use a 4-tuple of the room list index,
+ * the grid index of the collectible in the room, the collectible's `SubType`, and the collectible's
+ * `InitSeed`.
  *
  * Collectibles that are shifted by Tainted Isaac's mechanic will have unique collectible indexes
- * because the SubType is different. (The collectible entities share the same InitSeed.)
+ * because the `SubType` is different. (The collectible entities share the same `InitSeed` and
+ * `PtrHash`.)
  *
  * Collectibles that are rolled (with e.g. a D6) will have unique collectible indexes because the
- * SubType and InitSeed are different. If you want to track collectibles independently of any
+ * `SubType` and `InitSeed` are different. If you want to track collectibles independently of any
  * rerolls, then you can use the `PtrHash` as an index instead. (The `PtrHash` will not persist
  * between rooms, however.)
  *
  * Note that:
  * - The grid index is a necessary part of the collectible index because Diplopia and Crooked Penny
- *   can cause two or more collectibles with the same SubType and InitSeed to exist in the same
+ *   can cause two or more collectibles with the same `SubType` and `InitSeed` to exist in the same
  *   room.
  * - This index will fail in the case where the player uses Diplopia or a successful Crooked Penny
  *   seven or more times in the same room, since that will cause two or more collectibles with the
- *   same grid index, SubType, and InitSeed to exist.
- * - The SubType is a necessary part of the collectible index because Tainted Isaac will
- *   continuously cause collectibles to morph into new sub-types with the same InitSeed.
+ *   same grid index, `SubType`, and `InitSeed` to exist. (More than seven is required in non-1x1
+ *   rooms.)
+ * - The `SubType` is a necessary part of the collectible index because Tainted Isaac will
+ *   continuously cause collectibles to morph into new sub-types with the same `InitSeed`.
  * - Using a collectible's position as part of the index is problematic, since players can push a
  *   pedestal. (Even using the grid index does not solve this problem, since it is possible in
  *   certain cases for collectibles to be spawned at a position that is not aligned with the grid,
  *   and the pedestal pushed to an adjacent tile, but this case should be extremely rare.)
  * - Mega Chests spawn two collectibles on the exact same position. However, both of them will have
- *   different InitSeeds, so this is not a problem for this indexing scheme.
+ *   a different `InitSeed`, so this is not a problem for this indexing scheme.
  * - The indexing scheme used is different for collectibles that are inside of a Treasure Room or
  *   Boss Room, in order to handle the case of the player seeing the same collectible again in a
- *   post-Ascent Treasure Room or Boss Room. A 5-tuple of stage, stage type, grid index, SubType,
- *   and InitSeed is used in this case. (Using the room list index or the room grid index is not
+ *   post-Ascent Treasure Room or Boss Room. A 5-tuple of stage, stage type, grid index, `SubType`,
+ *   and `InitSeed` is used in this case. (Using the room list index or the room grid index is not
  *   suitable for this purpose, since both of these values can change in the post-Ascent rooms.)
  *   Even though Treasure Rooms and Boss Rooms are grouped together in this scheme, there probably
  *   will not be collectibles with the same grid index, SubType, and InitSeed.