isaacscript-common 6.11.2 → 6.12.0

package/dist/features/pause.lua

@@ -1,15 +1,30 @@
 local ____lualib = require("lualib_bundle")
-local Set = ____lualib.Set
+local Map = ____lualib.Map
 local __TS__New = ____lualib.__TS__New
+local __TS__SparseArrayNew = ____lualib.__TS__SparseArrayNew
+local __TS__SparseArrayPush = ____lualib.__TS__SparseArrayPush
+local __TS__SparseArraySpread = ____lualib.__TS__SparseArraySpread
+local Set = ____lualib.Set
 local ____exports = {}
-local postUpdate, inputActionGetActionValue, v
+local postUpdate, stopTearsAndProjectilesFromMoving, inputActionGetActionValue, v
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local ButtonAction = ____isaac_2Dtypescript_2Ddefinitions.ButtonAction
 local CollectibleType = ____isaac_2Dtypescript_2Ddefinitions.CollectibleType
 local InputHook = ____isaac_2Dtypescript_2Ddefinitions.InputHook
 local ModCallback = ____isaac_2Dtypescript_2Ddefinitions.ModCallback
+local ____constants = require("constants")
+local VectorZero = ____constants.VectorZero
+local ____entitiesSpecific = require("functions.entitiesSpecific")
+local getProjectiles = ____entitiesSpecific.getProjectiles
+local getTears = ____entitiesSpecific.getTears
+local removeAllProjectiles = ____entitiesSpecific.removeAllProjectiles
+local removeAllTears = ____entitiesSpecific.removeAllTears
+local ____isaacAPIClass = require("functions.isaacAPIClass")
+local isTear = ____isaacAPIClass.isTear
 local ____log = require("functions.log")
 local logError = ____log.logError
+local ____playerIndex = require("functions.playerIndex")
+local getAllPlayers = ____playerIndex.getAllPlayers
 local ____players = require("functions.players")
 local useActiveItemTemp = ____players.useActiveItemTemp
 local ____disableInputs = require("features.disableInputs")
@@ -21,8 +36,37 @@ function postUpdate(self)
     if not v.run.isPseudoPaused then
         return
     end
-    local player = Isaac.GetPlayer()
-    useActiveItemTemp(nil, player, CollectibleType.PAUSE)
+    local firstPlayer = Isaac.GetPlayer()
+    useActiveItemTemp(nil, firstPlayer, CollectibleType.PAUSE)
+    stopTearsAndProjectilesFromMoving(nil)
+end
+function stopTearsAndProjectilesFromMoving(self)
+    local ____array_0 = __TS__SparseArrayNew(table.unpack(getTears(nil)))
+    __TS__SparseArrayPush(
+        ____array_0,
+        table.unpack(getProjectiles(nil))
+    )
+    local tearsAndProjectiles = {__TS__SparseArraySpread(____array_0)}
+    for ____, tearOrProjectile in ipairs(tearsAndProjectiles) do
+        do
+            local ptrHash = GetPtrHash(tearOrProjectile)
+            local initialDescription = v.run.initialDescriptions:get(ptrHash)
+            if initialDescription == nil then
+                goto __continue6
+            end
+            tearOrProjectile.Position = initialDescription.position
+            tearOrProjectile.PositionOffset = initialDescription.positionOffset
+            tearOrProjectile.Velocity = VectorZero
+            tearOrProjectile.Height = initialDescription.height
+            tearOrProjectile.FallingSpeed = 0
+            if isTear(nil, tearOrProjectile) then
+                tearOrProjectile.FallingAcceleration = initialDescription.fallingAcceleration
+            else
+                tearOrProjectile.FallingAccel = initialDescription.fallingAcceleration
+            end
+        end
+        ::__continue6::
+    end
 end
 function inputActionGetActionValue(self, _entity, _inputHook, buttonAction)
     if buttonAction ~= ButtonAction.SHOOT_RIGHT then
@@ -35,7 +79,11 @@ function inputActionGetActionValue(self, _entity, _inputHook, buttonAction)
     return 1
 end
 local FEATURE_NAME = "pause"
-v = {run = {isPseudoPaused = false, shouldUnpause = false}}
+v = {run = {
+    isPseudoPaused = false,
+    shouldUnpause = false,
+    initialDescriptions = __TS__New(Map)
+}}
 ---
 -- @internal
 function ____exports.pauseInit(self, mod)
@@ -48,15 +96,41 @@ end
 -- 
 -- 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`)
 function ____exports.pause(self)
     if v.run.isPseudoPaused then
         logError("Failed to pseudo-pause the game, since it was already pseudo-paused.")
         return
     end
     v.run.isPseudoPaused = true
-    local whitelist = __TS__New(Set, {ButtonAction.MENU_CONFIRM})
+    v.run.initialDescriptions:clear()
+    local ____array_1 = __TS__SparseArrayNew(table.unpack(getTears(nil)))
+    __TS__SparseArrayPush(
+        ____array_1,
+        table.unpack(getProjectiles(nil))
+    )
+    local tearsAndProjectiles = {__TS__SparseArraySpread(____array_1)}
+    for ____, tearOrProjectile in ipairs(tearsAndProjectiles) do
+        local ptrHash = GetPtrHash(tearOrProjectile)
+        local initialDescription = {
+            position = tearOrProjectile.Position,
+            positionOffset = tearOrProjectile.PositionOffset,
+            velocity = tearOrProjectile.Velocity,
+            height = tearOrProjectile.Height,
+            fallingSpeed = tearOrProjectile.FallingSpeed,
+            fallingAcceleration = isTear(nil, tearOrProjectile) and tearOrProjectile.FallingAcceleration or tearOrProjectile.FallingAccel
+        }
+        v.run.initialDescriptions:set(ptrHash, initialDescription)
+    end
+    local firstPlayer = Isaac.GetPlayer()
+    useActiveItemTemp(nil, firstPlayer, CollectibleType.PAUSE)
+    local whitelist = __TS__New(Set, {ButtonAction.MENU_CONFIRM, ButtonAction.CONSOLE})
     disableAllInputsExceptFor(nil, FEATURE_NAME, whitelist)
+    for ____, player in ipairs(getAllPlayers(nil)) do
+        player.ControlsEnabled = false
+        player.Velocity = VectorZero
+    end
+    stopTearsAndProjectilesFromMoving(nil)
 end
 --- Helper function to put things back to normal after the `pause` function was used.
 function ____exports.unpause(self)
@@ -65,7 +139,12 @@ function ____exports.unpause(self)
         return
     end
     v.run.isPseudoPaused = false
-    enableAllInputs(nil, FEATURE_NAME)
     v.run.shouldUnpause = true
+    enableAllInputs(nil, FEATURE_NAME)
+    for ____, player in ipairs(getAllPlayers(nil)) do
+        player.ControlsEnabled = true
+    end
+    removeAllTears(nil)
+    removeAllProjectiles(nil)
 end
 return ____exports

package/dist/features/persistentEntities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persistentEntities.d.ts","sourceRoot":"","sources":["../../src/features/persistentEntities.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,UAAU,EAEX,MAAM,8BAA8B,CAAC;AAiGtC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,GAAG,EACZ,OAAO,EAAE,GAAG,EACZ,QAAQ,EAAE,MAAM,GACf,CAAC,MAAM,EAAE,GAAG,CAAC,CAcf;AAwBD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,qBAAqB,EAAE,GAAG,EAC1B,YAAY,UAAO,GAClB,IAAI,CAiBN"}
+{"version":3,"file":"persistentEntities.d.ts","sourceRoot":"","sources":["../../src/features/persistentEntities.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,UAAU,EAEX,MAAM,8BAA8B,CAAC;AAkGtC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,GAAG,EACZ,OAAO,EAAE,GAAG,EACZ,QAAQ,EAAE,MAAM,GACf,CAAC,MAAM,EAAE,GAAG,CAAC,CAcf;AAwBD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,qBAAqB,EAAE,GAAG,EAC1B,YAAY,UAAO,GAClB,IAAI,CAiBN"}

package/dist/features/persistentEntities.lua

@@ -7,8 +7,6 @@ local postEntityRemove, postNewRoomReordered, spawnAndTrack, v
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local EntityFlag = ____isaac_2Dtypescript_2Ddefinitions.EntityFlag
 local ModCallback = ____isaac_2Dtypescript_2Ddefinitions.ModCallback
-local ____cachedClasses = require("cachedClasses")
-local game = ____cachedClasses.game
 local ____ModCallbackCustom = require("enums.ModCallbackCustom")
 local ModCallbackCustom = ____ModCallbackCustom.ModCallbackCustom
 local ____featuresInitialized = require("featuresInitialized")
@@ -17,6 +15,8 @@ local ____entities = require("functions.entities")
 local spawn = ____entities.spawn
 local ____roomData = require("functions.roomData")
 local getRoomListIndex = ____roomData.getRoomListIndex
+local ____roomHistory = require("features.roomHistory")
+local getLatestRoomDescription = ____roomHistory.getLatestRoomDescription
 local ____exports = require("features.saveDataManager.exports")
 local saveDataManager = ____exports.saveDataManager
 function postEntityRemove(self, entity)
@@ -26,16 +26,16 @@ function postEntityRemove(self, entity)
         return
     end
     local index = tuple[1]
-    local level = game:GetLevel()
-    local previousRoomGridIndex = level:GetPreviousRoomIndex()
-    local previousRoomListIndex = getRoomListIndex(nil, previousRoomGridIndex)
-    v.level.persistentEntities:set(index, {
+    local previousRoomDescription = getLatestRoomDescription(nil)
+    local previousRoomListIndex = previousRoomDescription.roomListIndex
+    local persistentEntityDescription = {
         entityType = entity.Type,
         variant = entity.Variant,
         subType = entity.SubType,
         roomListIndex = previousRoomListIndex,
         position = entity.Position
-    })
+    }
+    v.level.persistentEntities:set(index, persistentEntityDescription)
 end
 function postNewRoomReordered(self)
     local roomListIndex = getRoomListIndex(nil)

package/dist/features/pickupIndex.d.ts

@@ -0,0 +1,19 @@
+/// <reference types="isaac-typescript-definitions" />
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { PickupIndex } from "../types/PickupIndex";
+export declare function pickupIndexInit(mod: ModUpgraded): void;
+/**
+ * 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 declare function getPickupIndex(pickup: EntityPickup): PickupIndex;
+//# sourceMappingURL=pickupIndex.d.ts.map

package/dist/features/pickupIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pickupIndex.d.ts","sourceRoot":"","sources":["../../src/features/pickupIndex.ts"],"names":[],"mappings":";AAOA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAQrD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAgCnD,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAatD;AA0KD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,WAAW,CAahE"}

package/dist/features/pickupIndex.lua

@@ -0,0 +1,197 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local __TS__New = ____lualib.__TS__New
+local __TS__Iterator = ____lualib.__TS__Iterator
+local ____exports = {}
+local postPickupInit, postEntityRemovePickup, checkDespawningFromPlayerLeavingRoom, trackDespawningPickupMetadata, postNewRoomReordered, getStoredPickupIndex, getPostAscentPickupIndex, v
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local EntityType = ____isaac_2Dtypescript_2Ddefinitions.EntityType
+local ModCallback = ____isaac_2Dtypescript_2Ddefinitions.ModCallback
+local RoomType = ____isaac_2Dtypescript_2Ddefinitions.RoomType
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+local ____DefaultMap = require("classes.DefaultMap")
+local DefaultMap = ____DefaultMap.DefaultMap
+local ____ModCallbackCustom = require("enums.ModCallbackCustom")
+local ModCallbackCustom = ____ModCallbackCustom.ModCallbackCustom
+local ____featuresInitialized = require("featuresInitialized")
+local errorIfFeaturesNotInitialized = ____featuresInitialized.errorIfFeaturesNotInitialized
+local ____entities = require("functions.entities")
+local getEntityID = ____entities.getEntityID
+local ____entitiesSpecific = require("functions.entitiesSpecific")
+local getPickups = ____entitiesSpecific.getPickups
+local ____roomData = require("functions.roomData")
+local getRoomListIndex = ____roomData.getRoomListIndex
+local ____stage = require("functions.stage")
+local onAscent = ____stage.onAscent
+local ____vector = require("functions.vector")
+local vectorEquals = ____vector.vectorEquals
+local ____roomHistory = require("features.roomHistory")
+local getLatestRoomDescription = ____roomHistory.getLatestRoomDescription
+local ____exports = require("features.saveDataManager.exports")
+local saveDataManager = ____exports.saveDataManager
+function postPickupInit(self, pickup)
+    local ptrHash = GetPtrHash(pickup)
+    if v.room.pickupIndexes:has(ptrHash) then
+        return
+    end
+    local room = game:GetRoom()
+    local isFirstVisit = room:IsFirstVisit()
+    local roomFrameCount = room:GetFrameCount()
+    if not isFirstVisit and roomFrameCount <= 0 then
+        return
+    end
+    local ____v_run_0, ____pickupCounter_1 = v.run, "pickupCounter"
+    ____v_run_0[____pickupCounter_1] = ____v_run_0[____pickupCounter_1] + 1
+    v.room.pickupIndexes:set(ptrHash, v.run.pickupCounter)
+    v.run.currentRoomListIndex = getRoomListIndex(nil)
+end
+function postEntityRemovePickup(self, entity)
+    checkDespawningFromPlayerLeavingRoom(nil, entity)
+end
+function checkDespawningFromPlayerLeavingRoom(self, entity)
+    local ptrHash = GetPtrHash(entity)
+    local pickupIndex = v.room.pickupIndexes:get(ptrHash)
+    if pickupIndex == nil then
+        return
+    end
+    local roomListIndex = getRoomListIndex(nil)
+    if roomListIndex == v.run.currentRoomListIndex then
+        return
+    end
+    trackDespawningPickupMetadata(nil, entity, pickupIndex)
+end
+function trackDespawningPickupMetadata(self, entity, pickupIndex)
+    local previousRoomDescription = getLatestRoomDescription(nil)
+    local previousRoomListIndex = previousRoomDescription.roomListIndex
+    local pickupDescriptions = v.level.pickupData:getAndSetDefault(previousRoomListIndex)
+    local pickupDescription = {position = entity.Position, initSeed = entity.InitSeed}
+    pickupDescriptions:set(pickupIndex, pickupDescription)
+    if onAscent(nil) then
+        return
+    end
+    local room = game:GetRoom()
+    local roomType = room:GetType()
+    repeat
+        local ____switch13 = roomType
+        local ____cond13 = ____switch13 == RoomType.TREASURE
+        if ____cond13 then
+            do
+                v.run.pickupDataTreasureRooms:set(pickupIndex, pickupDescription)
+                break
+            end
+        end
+        ____cond13 = ____cond13 or ____switch13 == RoomType.BOSS
+        if ____cond13 then
+            do
+                v.run.pickupDataBossRooms:set(pickupIndex, pickupDescription)
+                break
+            end
+        end
+        do
+            do
+                break
+            end
+        end
+    until true
+end
+function postNewRoomReordered(self)
+    local room = game:GetRoom()
+    local isFirstVisit = room:IsFirstVisit()
+    if isFirstVisit then
+        return
+    end
+    local roomListIndex = getRoomListIndex(nil)
+    local pickupDescriptions = v.level.pickupData:getAndSetDefault(roomListIndex)
+    for ____, pickup in ipairs(getPickups(nil)) do
+        local pickupIndex = getStoredPickupIndex(nil, pickup, pickupDescriptions)
+        if pickupIndex == nil then
+            pickupIndex = getPostAscentPickupIndex(nil, pickup)
+        end
+        if pickupIndex == nil then
+            local entityID = getEntityID(nil, pickup)
+            error("Failed to find a pickup index corresponding to existing pickup: " .. entityID)
+        end
+        local ptrHash = GetPtrHash(pickup)
+        v.room.pickupIndexes:set(ptrHash, pickupIndex)
+    end
+end
+function getStoredPickupIndex(self, pickup, pickupDescriptions)
+    for ____, ____value in __TS__Iterator(pickupDescriptions:entries()) do
+        local pickupIndex = ____value[1]
+        local pickupDescription = ____value[2]
+        if vectorEquals(nil, pickupDescription.position, pickup.Position) and pickupDescription.initSeed == pickup.InitSeed then
+            return pickupIndex
+        end
+    end
+    return nil
+end
+function getPostAscentPickupIndex(self, pickup)
+    if not onAscent(nil) then
+        return nil
+    end
+    local room = game:GetRoom()
+    local roomType = room:GetType()
+    repeat
+        local ____switch29 = roomType
+        local ____cond29 = ____switch29 == RoomType.TREASURE
+        if ____cond29 then
+            do
+                return getStoredPickupIndex(nil, pickup, v.run.pickupDataTreasureRooms)
+            end
+        end
+        ____cond29 = ____cond29 or ____switch29 == RoomType.BOSS
+        if ____cond29 then
+            do
+                return getStoredPickupIndex(nil, pickup, v.run.pickupDataBossRooms)
+            end
+        end
+        do
+            do
+                return nil
+            end
+        end
+    until true
+end
+local FEATURE_NAME = "pickupIndex"
+v = {
+    run = {
+        pickupCounter = 0,
+        currentRoomListIndex = 0,
+        pickupDataTreasureRooms = __TS__New(Map),
+        pickupDataBossRooms = __TS__New(Map)
+    },
+    level = {pickupData = __TS__New(
+        DefaultMap,
+        function() return __TS__New(Map) end
+    )},
+    room = {pickupIndexes = __TS__New(Map)}
+}
+function ____exports.pickupIndexInit(self, mod)
+    saveDataManager(nil, FEATURE_NAME, v)
+    mod:AddCallback(ModCallback.POST_PICKUP_INIT, postPickupInit)
+    mod:AddCallback(ModCallback.POST_ENTITY_REMOVE, postEntityRemovePickup, EntityType.PICKUP)
+    mod:AddCallbackCustom(ModCallbackCustom.POST_NEW_ROOM_REORDERED, postNewRoomReordered)
+end
+--- 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.
+function ____exports.getPickupIndex(self, pickup)
+    errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
+    local ptrHash = GetPtrHash(pickup)
+    local pickupIndex = v.room.pickupIndexes:get(ptrHash)
+    if pickupIndex == nil then
+        local entityID = getEntityID(nil, pickup)
+        error((("Failed to get a pickup index for entity " .. entityID) .. " with hash: ") .. tostring(ptrHash))
+    end
+    return pickupIndex
+end
+return ____exports

package/dist/features/roomHistory.d.ts

@@ -0,0 +1,24 @@
+import { RoomDescription } from "../interfaces/RoomDescription";
+/**
+ * Helper function to get information about all of the rooms that a player has visited thus far on
+ * this run.
+ */
+export declare function getRoomHistory(): readonly RoomDescription[];
+/**
+ * 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 declare function getPreviousRoomDescription(): RoomDescription;
+/**
+ * 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 declare function getLatestRoomDescription(): RoomDescription;
+//# sourceMappingURL=roomHistory.d.ts.map

package/dist/features/roomHistory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roomHistory.d.ts","sourceRoot":"","sources":["../../src/features/roomHistory.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAiDhE;;;GAGG;AACH,wBAAgB,cAAc,IAAI,SAAS,eAAe,EAAE,CAG3D;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,IAAI,eAAe,CAe5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,eAAe,CAS1D"}

package/dist/features/roomHistory.lua

@@ -0,0 +1,89 @@
+local ____exports = {}
+local postNewRoomEarly, v
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+local ____ModCallbackCustom = require("enums.ModCallbackCustom")
+local ModCallbackCustom = ____ModCallbackCustom.ModCallbackCustom
+local ____featuresInitialized = require("featuresInitialized")
+local errorIfFeaturesNotInitialized = ____featuresInitialized.errorIfFeaturesNotInitialized
+local ____array = require("functions.array")
+local getLastElement = ____array.getLastElement
+local ____roomData = require("functions.roomData")
+local getRoomGridIndex = ____roomData.getRoomGridIndex
+local getRoomListIndex = ____roomData.getRoomListIndex
+local getRoomName = ____roomData.getRoomName
+local getRoomStageID = ____roomData.getRoomStageID
+local getRoomSubType = ____roomData.getRoomSubType
+local getRoomVariant = ____roomData.getRoomVariant
+local ____exports = require("features.saveDataManager.exports")
+local saveDataManager = ____exports.saveDataManager
+function postNewRoomEarly(self)
+    local level = game:GetLevel()
+    local stage = level:GetStage()
+    local stageType = level:GetStageType()
+    local room = game:GetRoom()
+    local roomType = room:GetType()
+    local stageID = getRoomStageID(nil)
+    local roomVariant = getRoomVariant(nil)
+    local roomSubType = getRoomSubType(nil)
+    local roomName = getRoomName(nil)
+    local roomGridIndex = getRoomGridIndex(nil)
+    local roomListIndex = getRoomListIndex(nil)
+    local roomDescription = {
+        stage = stage,
+        stageType = stageType,
+        stageID = stageID,
+        roomType = roomType,
+        roomVariant = roomVariant,
+        roomSubType = roomSubType,
+        roomName = roomName,
+        roomGridIndex = roomGridIndex,
+        roomListIndex = roomListIndex
+    }
+    local ____v_run_roomHistory_0 = v.run.roomHistory
+    ____v_run_roomHistory_0[#____v_run_roomHistory_0 + 1] = roomDescription
+end
+local FEATURE_NAME = "roomHistory"
+v = {run = {roomHistory = {}}}
+---
+-- @internal
+function ____exports.roomHistoryInit(self, mod)
+    saveDataManager(nil, FEATURE_NAME, v)
+    mod:AddCallbackCustom(ModCallbackCustom.POST_NEW_ROOM_EARLY, postNewRoomEarly)
+end
+--- Helper function to get information about all of the rooms that a player has visited thus far on
+-- this run.
+function ____exports.getRoomHistory(self)
+    errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
+    return v.run.roomHistory
+end
+--- 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.
+function ____exports.getPreviousRoomDescription(self)
+    local previousRoomDescription = v.run.roomHistory[#v.run.roomHistory - 2 + 1]
+    if previousRoomDescription ~= nil then
+        return previousRoomDescription
+    end
+    local startingRoomDescription = v.run.roomHistory[1]
+    if startingRoomDescription ~= nil then
+        return startingRoomDescription
+    end
+    error("Failed to find a room description for any rooms thus far on this run.")
+end
+--- 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.
+function ____exports.getLatestRoomDescription(self)
+    local latestRoomDescription = getLastElement(nil, v.run.roomHistory)
+    if latestRoomDescription == nil then
+        error("Failed to get the latest room description since the room history array was empty.")
+    end
+    return latestRoomDescription
+end
+return ____exports

package/dist/functions/collectibles.d.ts

@@ -24,38 +24,51 @@ export declare function getCollectibleDevilHeartPrice(collectibleType: Collectib
  */
 export declare function getCollectibleGfxFilename(collectibleType: CollectibleType): string;
 /**
- * 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.

package/dist/functions/collectibles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collectibles.d.ts","sourceRoot":"","sources":["../../src/functions/collectibles.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"collectibles.d.ts","sourceRoot":"","sources":["../../src/functions/collectibles.ts"],"names":[],"mappings":"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"}