isaacscript-common 4.2.5 → 4.3.0

package/enums/StageTravelEntityState.d.ts

@@ -0,0 +1,4 @@
+export declare enum StageTravelEntityState {
+    OPEN = 0,
+    CLOSED = 1
+}

package/enums/StageTravelEntityState.lua

@@ -0,0 +1,7 @@
+local ____exports = {}
+____exports.StageTravelEntityState = {}
+____exports.StageTravelEntityState.OPEN = 0
+____exports.StageTravelEntityState[____exports.StageTravelEntityState.OPEN] = "OPEN"
+____exports.StageTravelEntityState.CLOSED = 1
+____exports.StageTravelEntityState[____exports.StageTravelEntityState.CLOSED] = "CLOSED"
+return ____exports

package/enums/StageTravelState.d.ts

@@ -0,0 +1,6 @@
+export declare enum StageTravelState {
+    DISABLED = 0,
+    FADING_TO_BLACK = 1,
+    GOING_TO_NEW_FLOOR = 2,
+    FADING_IN = 3
+}

package/enums/StageTravelState.lua

@@ -0,0 +1,11 @@
+local ____exports = {}
+____exports.StageTravelState = {}
+____exports.StageTravelState.DISABLED = 0
+____exports.StageTravelState[____exports.StageTravelState.DISABLED] = "DISABLED"
+____exports.StageTravelState.FADING_TO_BLACK = 1
+____exports.StageTravelState[____exports.StageTravelState.FADING_TO_BLACK] = "FADING_TO_BLACK"
+____exports.StageTravelState.GOING_TO_NEW_FLOOR = 2
+____exports.StageTravelState[____exports.StageTravelState.GOING_TO_NEW_FLOOR] = "GOING_TO_NEW_FLOOR"
+____exports.StageTravelState.FADING_IN = 3
+____exports.StageTravelState[____exports.StageTravelState.FADING_IN] = "FADING_IN"
+return ____exports

package/enums/private/SaveDataKey.d.ts

@@ -4,4 +4,3 @@ export declare enum SaveDataKey {
     LEVEL = "level",
     ROOM = "room"
 }
-export declare const RESETTABLE_SAVE_DATA_KEYS: ReadonlySet<SaveDataKey>;

package/enums/private/SaveDataKey.lua

@@ -1,11 +1,7 @@
-local ____lualib = require("lualib_bundle")
-local Set = ____lualib.Set
-local __TS__New = ____lualib.__TS__New
 local ____exports = {}
 ____exports.SaveDataKey = {}
 ____exports.SaveDataKey.PERSISTENT = "persistent"
 ____exports.SaveDataKey.RUN = "run"
 ____exports.SaveDataKey.LEVEL = "level"
 ____exports.SaveDataKey.ROOM = "room"
-____exports.RESETTABLE_SAVE_DATA_KEYS = __TS__New(Set, {____exports.SaveDataKey.RUN, ____exports.SaveDataKey.LEVEL, ____exports.SaveDataKey.ROOM})
 return ____exports

package/features/{getCollectibleItemPoolType.lua → collectibleItemPoolType.lua}

@@ -28,8 +28,8 @@ local FEATURE_NAME = "get collectible item pool type"
 v = {run = {collectibleItemPoolTypeMap = __TS__New(Map)}}
 ---
 -- @internal
-function ____exports.getCollectibleItemPoolTypeInit(self, mod)
-    saveDataManager(nil, "getCollectibleItemPoolType", v)
+function ____exports.collectibleItemPoolTypeInit(self, mod)
+    saveDataManager(nil, "collectibleItemPoolType", v)
     mod:AddCallback(ModCallback.POST_PICKUP_INIT, postPickupInitCollectible, PickupVariant.COLLECTIBLE)
 end
 --- Helper function to get the item pool type that a given collectible came from. Since there is no

package/features/customTrapdoor/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const STAGE_TRAVEL_FEATURE_NAME = "stageTravel";
+/** This also applies to crawl spaces. The value was determined through trial and error. */
+export declare const TRAPDOOR_OPEN_DISTANCE = 60;
+export declare const TRAPDOOR_OPEN_DISTANCE_AFTER_BOSS: number;
+export declare const TRAPDOOR_BOSS_REACTION_FRAMES = 30;

package/features/customTrapdoor/constants.lua

@@ -0,0 +1,7 @@
+local ____exports = {}
+____exports.STAGE_TRAVEL_FEATURE_NAME = "stageTravel"
+--- This also applies to crawl spaces. The value was determined through trial and error.
+____exports.TRAPDOOR_OPEN_DISTANCE = 60
+____exports.TRAPDOOR_OPEN_DISTANCE_AFTER_BOSS = ____exports.TRAPDOOR_OPEN_DISTANCE * 2.5
+____exports.TRAPDOOR_BOSS_REACTION_FRAMES = 30
+return ____exports

package/features/customTrapdoor/exports.d.ts

@@ -0,0 +1,37 @@
+import { LevelStage, StageType } from "isaac-typescript-definitions";
+/**
+ * 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: animation
+ *
+ * You can use this function to take the player to your custom stage. (See the `registerCustomStage`
+ * helper function.)
+ *
+ * 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 Used to specify where the player will go after jumping into the trapdoor. Can
+ *                     either be a tuple containing the stage and stage type, a string containing
+ *                     the name of a custom stage, or a function that returns one of these things.
+ *                     You can also specify a function that returns undefined in order to perform
+ *                     some custom behavior and/or handle the traveling part yourself. By default,
+ *                     the destination will be set to the next floor like that of a vanilla
+ *                     trapdoor.
+ * @param _anm2 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.
+ * @param _shouldOpenFunc Optional. If the trapdoor is currently closed, this function will run on
+ *                        every frame to determine if it should open. By default, a function that
+ *                        emulates a vanilla trapdoor will be used.
+ * @param _shouldCloseFunc Optional. If the trapdoor is currently open, this function will run on
+ *                         every frame to determine if it should close. By default, a function that
+ *                         emulates a vanilla trapdoor will be used.
+ * @param _spawnOpen Optional. Whether or not to spawn the trapdoor in an open state. Can either be
+ *                   a boolean or a function returning a boolean. By default, a function that
+ *                   emulates a vanilla trapdoor will be used.
+ */
+export declare function spawnCustomTrapdoor(gridIndexOrPosition: int | Vector, _destination?: [stage: LevelStage, stageType: StageType] | string | ((gridEntity: GridEntity) => [stage: LevelStage, stageType: StageType] | string | undefined), _anm2?: string, _shouldOpenFunc?: (gridEntity: GridEntity) => boolean, _shouldCloseFunc?: (gridEntity: GridEntity) => boolean, _spawnOpen?: boolean | ((gridEntity: GridEntity) => boolean)): GridEntity;

package/features/customTrapdoor/exports.lua

@@ -0,0 +1,120 @@
+local ____exports = {}
+local defaultDestinationFunc, defaultShouldOpenFunc, isPlayerCloseAfterBoss, shouldBeClosedFromStartingInRoomWithEnemies, defaultShouldCloseFunc, defaultShouldSpawnOpenFunc
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local GridEntityType = ____isaac_2Dtypescript_2Ddefinitions.GridEntityType
+local RoomType = ____isaac_2Dtypescript_2Ddefinitions.RoomType
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+local ____gridEntity = require("functions.gridEntity")
+local spawnGrid = ____gridEntity.spawnGrid
+local ____nextStage = require("functions.nextStage")
+local getNextStage = ____nextStage.getNextStage
+local getNextStageType = ____nextStage.getNextStageType
+local ____positionVelocity = require("functions.positionVelocity")
+local anyPlayerCloserThan = ____positionVelocity.anyPlayerCloserThan
+local ____roomClearFrame = require("features.roomClearFrame")
+local getRoomClearGameFrame = ____roomClearFrame.getRoomClearGameFrame
+local ____constants = require("features.customTrapdoor.constants")
+local TRAPDOOR_BOSS_REACTION_FRAMES = ____constants.TRAPDOOR_BOSS_REACTION_FRAMES
+local TRAPDOOR_OPEN_DISTANCE = ____constants.TRAPDOOR_OPEN_DISTANCE
+local TRAPDOOR_OPEN_DISTANCE_AFTER_BOSS = ____constants.TRAPDOOR_OPEN_DISTANCE_AFTER_BOSS
+local ____v = require("features.customTrapdoor.v")
+local getCustomTrapdoorDescription = ____v.getCustomTrapdoorDescription
+function defaultDestinationFunc(self)
+    local nextStage = getNextStage(nil)
+    local nextStageType = getNextStageType(nil)
+    return {nextStage, nextStageType}
+end
+function defaultShouldOpenFunc(self, gridEntity)
+    local entityDescription = getCustomTrapdoorDescription(nil, gridEntity)
+    if entityDescription == nil then
+        return false
+    end
+    local room = game:GetRoom()
+    local roomClear = room:IsClear()
+    return not anyPlayerCloserThan(nil, gridEntity.Position, TRAPDOOR_OPEN_DISTANCE) and not isPlayerCloseAfterBoss(nil, gridEntity.Position) and not shouldBeClosedFromStartingInRoomWithEnemies(nil, entityDescription.initial, roomClear)
+end
+function isPlayerCloseAfterBoss(self, position)
+    local gameFrameCount = game:GetFrameCount()
+    local room = game:GetRoom()
+    local roomType = room:GetType()
+    local roomClearGameFrame = getRoomClearGameFrame(nil)
+    if roomType ~= RoomType.BOSS or roomClearGameFrame == nil or gameFrameCount >= roomClearGameFrame + TRAPDOOR_BOSS_REACTION_FRAMES then
+        return false
+    end
+    return anyPlayerCloserThan(nil, position, TRAPDOOR_OPEN_DISTANCE_AFTER_BOSS)
+end
+function shouldBeClosedFromStartingInRoomWithEnemies(self, initial, roomClear)
+    return initial and not roomClear
+end
+function defaultShouldCloseFunc(self)
+    return false
+end
+function defaultShouldSpawnOpenFunc(self, gridEntity)
+    local room = game:GetRoom()
+    local roomFrameCount = room:GetFrameCount()
+    local roomClear = room:IsClear()
+    if roomFrameCount > 0 then
+        return false
+    end
+    if not roomClear then
+        return false
+    end
+    return defaultShouldOpenFunc(nil, gridEntity)
+end
+--- 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: animation
+-- 
+-- You can use this function to take the player to your custom stage. (See the `registerCustomStage`
+-- helper function.)
+-- 
+-- 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 Used to specify where the player will go after jumping into the trapdoor. Can
+-- either be a tuple containing the stage and stage type, a string containing
+-- the name of a custom stage, or a function that returns one of these things.
+-- You can also specify a function that returns undefined in order to perform
+-- some custom behavior and/or handle the traveling part yourself. By default,
+-- the destination will be set to the next floor like that of a vanilla
+-- trapdoor.
+-- @param _anm2 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.
+-- @param _shouldOpenFunc Optional. If the trapdoor is currently closed, this function will run on
+-- every frame to determine if it should open. By default, a function that
+-- emulates a vanilla trapdoor will be used.
+-- @param _shouldCloseFunc Optional. If the trapdoor is currently open, this function will run on
+-- every frame to determine if it should close. By default, a function that
+-- emulates a vanilla trapdoor will be used.
+-- @param _spawnOpen Optional. Whether or not to spawn the trapdoor in an open state. Can either be
+-- a boolean or a function returning a boolean. By default, a function that
+-- emulates a vanilla trapdoor will be used.
+function ____exports.spawnCustomTrapdoor(self, gridIndexOrPosition, _destination, _anm2, _shouldOpenFunc, _shouldCloseFunc, _spawnOpen)
+    if _destination == nil then
+        _destination = defaultDestinationFunc
+    end
+    if _anm2 == nil then
+        _anm2 = "gfx/grid/door_11_trapdoor.anm2"
+    end
+    if _shouldOpenFunc == nil then
+        _shouldOpenFunc = defaultShouldOpenFunc
+    end
+    if _shouldCloseFunc == nil then
+        _shouldCloseFunc = defaultShouldCloseFunc
+    end
+    if _spawnOpen == nil then
+        _spawnOpen = defaultShouldSpawnOpenFunc
+    end
+    local decoration = spawnGrid(nil, GridEntityType.DECORATION, gridIndexOrPosition)
+    if decoration == nil then
+        error("Failed to spawn a custom trapdoor.")
+    end
+    return decoration
+end
+return ____exports

package/features/customTrapdoor/init.d.ts

@@ -0,0 +1 @@
+export declare function stageTravelInit(): void;

package/features/customTrapdoor/init.lua

@@ -0,0 +1,11 @@
+local ____exports = {}
+local ____exports = require("features.saveDataManager.exports")
+local saveDataManager = ____exports.saveDataManager
+local ____constants = require("features.customTrapdoor.constants")
+local STAGE_TRAVEL_FEATURE_NAME = ____constants.STAGE_TRAVEL_FEATURE_NAME
+local ____v = require("features.customTrapdoor.v")
+local v = ____v.default
+function ____exports.stageTravelInit(self)
+    saveDataManager(nil, STAGE_TRAVEL_FEATURE_NAME, v)
+end
+return ____exports

package/features/customTrapdoor/v.d.ts

@@ -0,0 +1,14 @@
+/// <reference types="isaac-typescript-definitions" />
+import { StageTravelState } from "../../enums/StageTravelState";
+import { StageTravelEntityDescription } from "../../interfaces/StageTravelEntityDescription";
+declare const v: {
+    run: {
+        state: StageTravelState;
+    };
+    room: {
+        /** Indexed by grid index. */
+        trapdoors: Map<number, StageTravelEntityDescription>;
+    };
+};
+export default v;
+export declare function getCustomTrapdoorDescription(gridEntity: GridEntity): StageTravelEntityDescription | undefined;

package/features/customTrapdoor/v.lua

@@ -0,0 +1,16 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local __TS__New = ____lualib.__TS__New
+local ____exports = {}
+local ____StageTravelState = require("enums.StageTravelState")
+local StageTravelState = ____StageTravelState.StageTravelState
+local v = {
+    run = {state = StageTravelState.DISABLED},
+    room = {trapdoors = __TS__New(Map)}
+}
+____exports.default = v
+function ____exports.getCustomTrapdoorDescription(self, gridEntity)
+    local gridIndex = gridEntity:GetGridIndex()
+    return v.room.trapdoors:get(gridIndex)
+end
+return ____exports

package/features/ponyDetection.d.ts

@@ -3,4 +3,9 @@
  * Helper function to see if the player is under the effects of A Pony or White Pony charge.
  * Detecting this is difficult, as the temporary effect will disappear upon entering a new room.
  */
-export declare function isPonyActive(player: EntityPlayer): boolean;
+export declare function isPlayerUsingPony(player: EntityPlayer): boolean;
+/**
+ * Helper function to see if any player is under the effects of A Pony or White Pony charge.
+ * Detecting this is difficult, as the temporary effect will disappear upon entering a new room.
+ */
+export declare function anyPlayerUsingPony(): boolean;

package/features/ponyDetection.lua

@@ -1,6 +1,7 @@
 local ____lualib = require("lualib_bundle")
 local Set = ____lualib.Set
 local __TS__New = ____lualib.__TS__New
+local __TS__ArraySome = ____lualib.__TS__ArraySome
 local ____exports = {}
 local postPEffectUpdateReordered, FLAGS_WHEN_PONY_IS_ACTIVE, v
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
@@ -16,6 +17,8 @@ local ____playerDataStructures = require("functions.playerDataStructures")
 local setAddPlayer = ____playerDataStructures.setAddPlayer
 local setDeletePlayer = ____playerDataStructures.setDeletePlayer
 local setHasPlayer = ____playerDataStructures.setHasPlayer
+local ____playerIndex = require("functions.playerIndex")
+local getPlayers = ____playerIndex.getPlayers
 local ____exports = require("features.saveDataManager.exports")
 local saveDataManager = ____exports.saveDataManager
 function postPEffectUpdateReordered(self, player)
@@ -46,8 +49,18 @@ function ____exports.ponyDetectionInit(self, mod)
 end
 --- Helper function to see if the player is under the effects of A Pony or White Pony charge.
 -- Detecting this is difficult, as the temporary effect will disappear upon entering a new room.
-function ____exports.isPonyActive(self, player)
+function ____exports.isPlayerUsingPony(self, player)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     return setHasPlayer(nil, v.run.playersIsPonyActive, player)
 end
+--- Helper function to see if any player is under the effects of A Pony or White Pony charge.
+-- Detecting this is difficult, as the temporary effect will disappear upon entering a new room.
+function ____exports.anyPlayerUsingPony(self)
+    errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
+    local players = getPlayers(nil)
+    return __TS__ArraySome(
+        players,
+        function(____, player) return ____exports.isPlayerUsingPony(nil, player) end
+    )
+end
 return ____exports

package/features/roomClearFrame.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="isaac-typescript-definitions" />
+/**
+ * Helper function to get the game frame (i.e. `Game.GetFrameCount`) of the last time that this room
+ * was cleared. Returns undefined if the room has never been cleared.
+ */
+export declare function getRoomClearGameFrame(): int | undefined;
+/**
+ * Helper function to get the room frame (i.e. `Room.GetFrameCount`) of the last time that this room
+ * was cleared. Returns undefined if the room has never been cleared.
+ */
+export declare function getRoomClearRoomFrame(): int | undefined;

package/features/roomClearFrame.lua

@@ -0,0 +1,38 @@
+local ____exports = {}
+local postRoomClearChangedTrue, 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 ____exports = require("features.saveDataManager.exports")
+local saveDataManager = ____exports.saveDataManager
+function postRoomClearChangedTrue(self)
+    local gameFrameCount = game:GetFrameCount()
+    local room = game:GetRoom()
+    local roomFrameCount = room:GetFrameCount()
+    v.room.roomClearGameFrame = gameFrameCount
+    v.room.roomClearRoomFrame = roomFrameCount
+end
+local FEATURE_NAME = "room clear frame"
+v = {room = {roomClearGameFrame = nil, roomClearRoomFrame = nil}}
+---
+-- @internal
+function ____exports.roomClearFrameInit(self, mod)
+    saveDataManager(nil, "roomClearFrame", v)
+    mod:AddCallbackCustom(ModCallbackCustom.POST_ROOM_CLEAR_CHANGED, postRoomClearChangedTrue, true)
+end
+--- Helper function to get the game frame (i.e. `Game.GetFrameCount`) of the last time that this room
+-- was cleared. Returns undefined if the room has never been cleared.
+function ____exports.getRoomClearGameFrame(self)
+    errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
+    return v.room.roomClearGameFrame
+end
+--- Helper function to get the room frame (i.e. `Room.GetFrameCount`) of the last time that this room
+-- was cleared. Returns undefined if the room has never been cleared.
+function ____exports.getRoomClearRoomFrame(self)
+    errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
+    return v.room.roomClearGameFrame
+end
+return ____exports

package/features/saveDataManager/main.lua

@@ -1,7 +1,9 @@
 local ____lualib = require("lualib_bundle")
 local Map = ____lualib.Map
+local Set = ____lualib.Set
+local __TS__New = ____lualib.__TS__New
 local ____exports = {}
-local postPlayerInit, preGameExit, postNewLevel, postNewRoomEarly, restoreDefaultsAll, restoreDefaults, clearAndCopyAllElements, mod, loadedDataOnThisRun
+local postPlayerInit, preGameExit, postNewLevel, postNewRoomEarly, restoreDefaultsAll, restoreDefaults, clearAndCopyAllElements, RESETTABLE_SAVE_DATA_KEYS, mod, loadedDataOnThisRun
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local ModCallback = ____isaac_2Dtypescript_2Ddefinitions.ModCallback
 local ____cachedClasses = require("cachedClasses")
@@ -9,7 +11,6 @@ local game = ____cachedClasses.game
 local ____ModCallbackCustom = require("enums.ModCallbackCustom")
 local ModCallbackCustom = ____ModCallbackCustom.ModCallbackCustom
 local ____SaveDataKey = require("enums.private.SaveDataKey")
-local RESETTABLE_SAVE_DATA_KEYS = ____SaveDataKey.RESETTABLE_SAVE_DATA_KEYS
 local SaveDataKey = ____SaveDataKey.SaveDataKey
 local ____SerializationType = require("enums.SerializationType")
 local SerializationType = ____SerializationType.SerializationType
@@ -102,6 +103,7 @@ function clearAndCopyAllElements(self, oldTable, newTable)
         oldTable[key] = value
     end
 end
+RESETTABLE_SAVE_DATA_KEYS = __TS__New(Set, {SaveDataKey.RUN, SaveDataKey.LEVEL, SaveDataKey.ROOM})
 mod = nil
 loadedDataOnThisRun = false
 ---

package/features/stageHistory.d.ts

@@ -0,0 +1,15 @@
+import { LevelStage, StageType } from "isaac-typescript-definitions";
+/** Helper function to get all of the stages that a player has visited thus far on this run. */
+export declare function getStageHistory(): ReadonlyArray<[
+    stage: LevelStage,
+    stageType: StageType
+]>;
+/**
+ * Helper function to check if a player has previous visited a particular stage (or stage + stage
+ * type combination) on this run.
+ *
+ * @param stage The stage to check for.
+ * @param stageType Optional. If provided, will check for a specific stage and stage type
+ *                  combination.
+ */
+export declare function hasVisitedStage(stage: LevelStage, stageType?: StageType): boolean;

package/features/stageHistory.lua

@@ -0,0 +1,62 @@
+local ____lualib = require("lualib_bundle")
+local __TS__ArraySome = ____lualib.__TS__ArraySome
+local ____exports = {}
+local postNewLevelReordered, 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 ____exports = require("features.saveDataManager.exports")
+local saveDataManager = ____exports.saveDataManager
+function postNewLevelReordered(self)
+    local level = game:GetLevel()
+    local stage = level:GetStage()
+    local stageType = level:GetStageType()
+    local ____v_run_stageHistory_0 = v.run.stageHistory
+    ____v_run_stageHistory_0[#____v_run_stageHistory_0 + 1] = {stage, stageType}
+end
+local FEATURE_NAME = "stage history"
+v = {run = {stageHistory = {}}}
+---
+-- @internal
+function ____exports.stageHistoryInit(self, mod)
+    saveDataManager(nil, "stageHistory", v)
+    mod:AddCallbackCustom(ModCallbackCustom.POST_NEW_LEVEL_REORDERED, postNewLevelReordered)
+end
+--- Helper function to get all of the stages that a player has visited thus far on this run.
+function ____exports.getStageHistory(self)
+    errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
+    return v.run.stageHistory
+end
+--- Helper function to check if a player has previous visited a particular stage (or stage + stage
+-- type combination) on this run.
+-- 
+-- @param stage The stage to check for.
+-- @param stageType Optional. If provided, will check for a specific stage and stage type
+-- combination.
+function ____exports.hasVisitedStage(self, stage, stageType)
+    errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
+    if stageType == nil then
+        return __TS__ArraySome(
+            v.run.stageHistory,
+            function(____, ____bindingPattern0)
+                local previousStage
+                previousStage = ____bindingPattern0[1]
+                return previousStage == stage
+            end
+        )
+    end
+    return __TS__ArraySome(
+        v.run.stageHistory,
+        function(____, ____bindingPattern0)
+            local previousStageType
+            local previousStage
+            previousStage = ____bindingPattern0[1]
+            previousStageType = ____bindingPattern0[2]
+            return previousStage == stage and previousStageType == stageType
+        end
+    )
+end
+return ____exports

package/functions/character.d.ts

@@ -42,7 +42,7 @@ export declare function getCharacterDeathAnimationName(character: PlayerType): s
  * Mother's Kiss; use the `getPlayerMaxHeartContainers` helper function for that.
  */
 export declare function getCharacterMaxHeartContainers(character: PlayerType): int;
-/** Helper function to get the name of a character. Returns "unknown" for modded characters. */
+/** Helper function to get the name of a character. Returns "Unknown" for modded characters. */
 export declare function getCharacterName(character: PlayerType): string;
 export declare function isModdedCharacter(character: PlayerType): boolean;
 export declare function isVanillaCharacter(character: PlayerType): boolean;

package/functions/character.lua

@@ -5,7 +5,6 @@ local ____constantsFirstLast = require("constantsFirstLast")
 local LAST_VANILLA_CHARACTER = ____constantsFirstLast.LAST_VANILLA_CHARACTER
 local ____characterNames = require("objects.characterNames")
 local CHARACTER_NAMES = ____characterNames.CHARACTER_NAMES
-local DEFAULT_CHARACTER_NAME = ____characterNames.DEFAULT_CHARACTER_NAME
 local ____charactersThatStartWithAnActiveItemSet = require("sets.charactersThatStartWithAnActiveItemSet")
 local CHARACTERS_THAT_START_WITH_AN_ACTIVE_ITEM_SET = ____charactersThatStartWithAnActiveItemSet.CHARACTERS_THAT_START_WITH_AN_ACTIVE_ITEM_SET
 local ____charactersWithBlackHeartFromEternalHeartSet = require("sets.charactersWithBlackHeartFromEternalHeartSet")
@@ -18,6 +17,9 @@ local ____charactersWithNoSoulHeartsSet = require("sets.charactersWithNoSoulHear
 local CHARACTERS_WITH_NO_SOUL_HEARTS_SET = ____charactersWithNoSoulHeartsSet.CHARACTERS_WITH_NO_SOUL_HEARTS_SET
 local ____lostStyleCharactersSet = require("sets.lostStyleCharactersSet")
 local LOST_STYLE_CHARACTERS_SET = ____lostStyleCharactersSet.LOST_STYLE_CHARACTERS_SET
+function ____exports.isModdedCharacter(self, character)
+    return not ____exports.isVanillaCharacter(nil, character)
+end
 function ____exports.isVanillaCharacter(self, character)
     return character <= LAST_VANILLA_CHARACTER
 end
@@ -82,15 +84,11 @@ function ____exports.getCharacterMaxHeartContainers(self, character)
     end
     return 12
 end
---- Helper function to get the name of a character. Returns "unknown" for modded characters.
+--- Helper function to get the name of a character. Returns "Unknown" for modded characters.
 function ____exports.getCharacterName(self, character)
-    if ____exports.isVanillaCharacter(nil, character) then
-        return "unknown"
+    if ____exports.isModdedCharacter(nil, character) then
+        return "Unknown"
     end
-    local characterName = CHARACTER_NAMES[character]
-    return characterName == nil and DEFAULT_CHARACTER_NAME or characterName
-end
-function ____exports.isModdedCharacter(self, character)
-    return not ____exports.isVanillaCharacter(nil, character)
+    return CHARACTER_NAMES[character]
 end
 return ____exports

package/functions/gridEntity.d.ts

@@ -48,6 +48,11 @@ export declare function getGridEntities(...gridEntityTypes: GridEntityType[]): G
 export declare function getGridEntitiesMap(...gridEntityTypes: GridEntityType[]): Map<int, GridEntity>;
 /** Helper function to return a string containing the grid entity's type and variant. */
 export declare function getGridEntityID(gridEntity: GridEntity): string;
+/**
+ * Helper function to get all of the grid entities in the room that specifically match the type and
+ * variant provided.
+ */
+export declare function getMatchingGridEntities(gridEntityType: GridEntityType, variant: int): GridEntity[];
 export declare function getSurroundingGridEntities(gridEntity: GridEntity): GridEntity[];
 export declare function getTopLeftWall(): GridEntity | undefined;
 /**

package/functions/gridEntity.lua

@@ -214,6 +214,15 @@ function ____exports.getGridEntityID(self, gridEntity)
     local gridEntityVariant = gridEntity:GetVariant()
     return (tostring(gridEntityType) .. ".") .. tostring(gridEntityVariant)
 end
+--- Helper function to get all of the grid entities in the room that specifically match the type and
+-- variant provided.
+function ____exports.getMatchingGridEntities(self, gridEntityType, variant)
+    local gridEntities = ____exports.getGridEntities(nil, gridEntityType)
+    return __TS__ArrayFilter(
+        gridEntities,
+        function(____, gridEntity) return gridEntity:GetVariant() == variant end
+    )
+end
 function ____exports.getSurroundingGridEntities(self, gridEntity)
     local room = game:GetRoom()
     local gridWidth = room:GetGridWidth()

package/functions/gridEntitySpecific.d.ts

@@ -1,9 +1,9 @@
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
-/// <reference types="isaac-typescript-definitions" />
+import { CrawlSpaceState, TrapdoorVariant } from "isaac-typescript-definitions";
+/**
+ * Helper function to get all of the grid entities of type `GridEntityType.TRAPDOOR` in the room.
+ * Specify a specific trapdoor variant to select only trapdoors of that variant.
+ */
+export declare function getCrawlSpaces(crawlSpaceVariant?: CrawlSpaceState): GridEntity[];
 /** Helper function to get all of the `GridEntityPit` in the room. */
 export declare function getPits(): GridEntityPit[];
 /** Helper function to get all of the `GridEntityPoop` in the room. */
@@ -16,6 +16,11 @@ export declare function getRocks(): GridEntityRock[];
 export declare function getSpikes(): GridEntitySpikes[];
 /** Helper function to get all of the `GridEntityTNT` in the room. */
 export declare function getTNT(): GridEntityTNT[];
+/**
+ * Helper function to get all of the grid entities of type `GridEntityType.TRAPDOOR` in the room.
+ * Specify a specific trapdoor variant to select only trapdoors of that variant.
+ */
+export declare function getTrapdoors(trapdoorVariant?: TrapdoorVariant): GridEntity[];
 /**
  * Helper function to determine if all of the pressure plates in the current room are pushed.
  * Returns true if there are no pressure plates in the room.