CustomStageTSConfig

Interfaces

CustomStageTSConfig

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:13

This is the format of a custom stage in the “isaacscript” section of the “tsconfig.json” file.

The contents of this interface are used to create a “tsconfig-isaacscript-section-schema.json” schema with the “ts-json-schema-generator” library.

The contents of this interface are validated at run-time against the schema.

The CustomStageLua interface extends this, adding room metadata.

Properties

name

readonly name: string

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:15

Mandatory. The name of the custom stage.

xmlPath

readonly xmlPath: string

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:21

Mandatory. The path to the XML file that contains the rooms for the custom stage (created with Basement Renovator).

roomVariantPrefix

readonly roomVariantPrefix: number

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:35

Mandatory. An arbitrarily chosen prefix in the range of 101-999 that will be unique to this stage.

Use a value of 100 when testing locally. When publishing to the workshop or otherwise distributing your mod, make sure that you have chosen a prefix that does not conflict with any other mods. You can find a list of registered room variant prefixes on the IsaacScript website: https://isaacscript.github.io/main/custom-stages

Minimum

100

Maximum

999

baseStage?

readonly optional baseStage?: number

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:56

Optional. An integer between 2 and 13, corresponding to the LevelStage enum. This is the number of the stage that will be warped to and used as a basis for the stage by the level generation algorithm.

For example, if you wanted to have a custom stage with a small amount of rooms per floor, then you should choose 2 as a base. (This would copy the number of rooms that would appear in Basement 2.) And if you wanted to have a custom stage with the maximum amount of rooms, then you should choose 13 as a base. (This would copy the number of rooms that would appear on The Void.)

It is not possible to use Basement 1 as a base stage due to conflicts with the Game.SetStage method.

If not specified, LevelStage.BASEMENT_2 (2) will be used.

Minimum

2

Maximum

13

baseStageType?

readonly optional baseStageType?: number

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:68

Optional. An integer between 0 and 5, corresponding to the StageType enum. This is the number of the stage type that will be warped to and used as a basis for the stage by the level generation algorithm.

If not specified, StageType.ORIGINAL (0) will be used.

Minimum

0

Maximum

5

music?

readonly optional music?: string

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:76

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.

backdropPNGPaths?

readonly optional backdropPNGPaths?: object

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:83

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 used.

nFloors

readonly nFloors: readonly string[]

An array that contains the full paths to the graphic files that are used for the floor in narrow rooms. (The “n” stands for “narrow”).

You must have at least one path in this array, but you can specify more than one to randomly add extra variety (like the vanilla stages do).

For an example of this, see the vanilla file “resources/gfx/backdrop/01_basement_nfloor.png”.

lFloors

readonly lFloors: readonly string[]

An array that contains the full paths to the graphic files that are used for the floor in L rooms.

You must have at least one path in this array, but you can specify more than one to randomly add extra variety (like the vanilla stages do).

For an example of this, see the vanilla file “resources/gfx/backdrop/01_lbasementfloor.png”.

walls

readonly walls: readonly string[]

An array that contains the full paths to the graphic files that are used for the walls of the floor.

You must have at least one path in this array, but you can specify more than one to randomly add extra variety (like the vanilla stages do).

For an example of this, see the vanilla file “resources/gfx/backdrop/01_basement.png”. (In the vanilla file, they concatenate all four variations together into one PNG file. However, for the custom stages feature, you must separate each wall variation into a separate file.)

corners

readonly corners: readonly string[]

An array that contains the full paths to the graphic files for the stage’s corners.

You must have at least one path in this array, but you can specify more than one to randomly add extra variety (like the vanilla stages do).

For an example of this, see the vanilla file “resources/gfx/backdrop/01_basement.png”. (In the vanilla file, they concatenate both variations together into one PNG file and put it in the top right hand corner. The corners are shown in the top right hand corner of the file, with two different variations concatenated together. However, for the custom stages feature, you must separate each corner variation into a separate file (and put it in a different file from the walls).

decorationsPNGPath?

readonly optional decorationsPNGPath?: string

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:145

Optional. The full path to the spritesheet that contains the graphics of the decorations for the floor.

If not specified, the vanilla Basement decorations spritesheet will be used. For reference, this is located at: resources/gfx/grid/props_01_basement.png

If you want to have custom animations for your decorations, then do not use this field and use decorationsANM2Path instead.

decorationsANM2Path?

readonly optional decorationsANM2Path?: string

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:157

Optional. The full path to the anm2 file that contains the custom animations for the decorations of the floor.

If not specified, the vanilla Basement decorations spritesheet will be used. For reference, this is located at: resources/gfx/grid/props_01_basement.png

If you do not want to have custom animations for your decorations, then do not use this field and use decorationsPNGPath instead.

rocksPNGPath?

readonly optional rocksPNGPath?: string

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:174

Optional. The full path to the spritesheet that contains the graphics of the rocks/blocks/urns for the floor.

If specified, it is assumed that you have your own custom rock alt type, and all vanilla rewards/enemies that spawn from urns will be automatically removed. Use the POST_GRID_ENTITY_BROKEN callback to make your own custom rewards. Or, if you want to emulate a vanilla urn/mushroom/skull/polyp/bucket, use the spawnRockAltReward helper function.

If not specified, the vanilla Basement rocks spritesheet will be used. For reference, this is located at: resources-dlc3/gfx/grid/rocks_basement.png

If you want to have custom animations for your rocks, then do not use this field and use rocksANM2Path instead.

rocksANM2Path?

readonly optional rocksANM2Path?: string

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:191

Optional. The full path to the anm2 file that contains the custom animations for the rocks/blocks/urns of the floor.

If specified, it is assumed that you have your own custom rock alt type, and all vanilla rewards/enemies that spawn from urns will be automatically removed. Use the POST_GRID_ENTITY_BROKEN callback to make your own custom rewards. Or, if you want to emulate a vanilla urn/mushroom/skull/polyp/bucket, use the spawnRockAltReward helper function.

If not specified, the vanilla Basement rocks spritesheet will be used. For reference, this is located at: resources-dlc3/gfx/grid/rocks_basement.png

If you do not want to have custom animations for your rocks, then do not use this field and use rocksPNGPath instead.

pitsPNGPath?

readonly optional pitsPNGPath?: string

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:203

Optional. The full path to the spritesheet that contains the graphics of the pits for the floor.

If not specified, the vanilla Basement pits spritesheet will be used. For reference, this is located at: resources/gfx/grid/grid_pit.png

If you do not want to have custom animations for your pits, then do not use this field and use pitsANM2Path instead.

pitsANM2Path?

readonly optional pitsANM2Path?: string

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:215

Optional. The full path to the anm2 file that contains the custom animations for the pits of the floor.

If not specified, the vanilla Basement pits spritesheet will be used. For reference, this is located at: resources/gfx/grid/grid_pit.png

If you do not want to have custom animations for your pits, then do not use this field and use pitsPNGPath instead.

doorPNGPaths?

readonly optional doorPNGPaths?: object

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:221

Optional. A collection of paths that contain graphics for the doors of the floor. If not specified, the doors for Basement will be used.

normal?

readonly optional normal?: string

Optional. The full path to the spritesheet that contains the graphics of the normal doors for the floor.

If not specified, the vanilla Basement door spritesheet will be used. For reference, this is located at: resources/gfx/grid/door_01_normaldoor.png

treasureRoom?

readonly optional treasureRoom?: string

Optional. The full path to the spritesheet that contains the graphics of the Treasure Room doors for the floor.

If not specified, the vanilla Basement door spritesheet will be used. For reference, this is located at: resources/gfx/grid/door_02_treasureroomdoor.png

bossRoom?

readonly optional bossRoom?: string

Optional. The full path to the spritesheet that contains the graphics of the Boss Room doors for the floor.

If not specified, the vanilla Basement door spritesheet will be used. For reference, this is located at: resources/gfx/grid/door_10_bossroomdoor.png

secretRoom?

readonly optional secretRoom?: string

Optional. The full path to the spritesheet that contains the graphics of the Secret Room and Super Secret Room doors for the floor.

If not specified, the vanilla Basement door spritesheet will be used. For reference, this is located at: resources/gfx/grid/door_08_holeinwall.png

arcade?

readonly optional arcade?: string

Optional. The full path to the spritesheet that contains the graphics of the arcade doors for the floor.

If not specified, the vanilla Basement door spritesheet will be used. For reference, this is located at: resources/gfx/grid/door_05_arcaderoomdoor.png

curseRoom?

readonly optional curseRoom?: string

Optional. The full path to the spritesheet that contains the graphics of the Curse Room doors for the floor.

If not specified, the vanilla Basement door spritesheet will be used. For reference, this is located at: resources/gfx/grid/door_04_selfsacrificeroomdoor.png

normalChallengeRoom?

readonly optional normalChallengeRoom?: string

Optional. The full path to the spritesheet that contains the graphics of the normal Challenge Room doors for the floor.

If not specified, the vanilla Basement door spritesheet will be used. For reference, this is located at: resources/gfx/grid/door_03_ambushroomdoor.png

bossChallengeRoom?

readonly optional bossChallengeRoom?: string

Optional. The full path to the spritesheet that contains the graphics of the Boss Challenge Room doors for the floor.

If not specified, the vanilla Basement door spritesheet will be used. For reference, this is located at: resources/gfx/grid/door_09_bossambushroomdoor.png

devilRoom?

readonly optional devilRoom?: string

Optional. The full path to the spritesheet that contains the graphics of the Devil Room doors for the floor.

If not specified, the vanilla Basement door spritesheet will be used. For reference, this is located at: resources/gfx/grid/door_07_devilroomdoor.png

angelRoom?

readonly optional angelRoom?: string

Optional. The full path to the spritesheet that contains the graphics of the Angel Room doors for the floor.

If not specified, the vanilla Basement door spritesheet will be used. For reference, this is located at: resources/gfx/grid/door_07_holyroomdoor.png

bossRush?

readonly optional bossRush?: string

Optional. The full path to the spritesheet that contains the graphics of the Boss Rush doors for the floor.

If not specified, the vanilla Basement door spritesheet will be used. For reference, this is located at: resources/gfx/grid/door_15_bossrushdoor.png

chestRoom?

readonly optional chestRoom?: string

Optional. The full path to the spritesheet that contains the graphics of the Chest Room doors for the floor.

If not specified, the vanilla Basement door spritesheet will be used. For reference, this is located at: resources/gfx/grid/door_02b_chestroomdoor.png

shadows?

readonly optional shadows?: object

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:337

Optional. An array of shadow objects that describe the graphics for the custom shadows of the floor. (In this context, “shadows” are the outlines from things on the roof. For example, in Basement, a shadow of a sideways V is used, among others.) If not specified, no extra shadows will be drawn.

1x1?

readonly optional 1x1?: readonly CustomStageShadow[]

Optional. An array containing the shadows that will be used in rooms of shape RoomShape.SHAPE_1x1 (1), RoomShape.IH (2), and RoomShape.IV (3).

If more than one shadow is specified, one will be randomly chosen for each room.

If not specified, no extra shadows will be drawn in these room shapes.

1x2?

readonly optional 1x2?: readonly CustomStageShadow[]

Optional. An array containing the shadows that will be used in rooms of shape RoomShape.SHAPE_1x2 (4) and RoomShape.IIV (5).

If more than one shadow is specified, one will be randomly chosen for each room.

If not specified, no extra shadows will be drawn in these room shapes.

2x1?

readonly optional 2x1?: readonly CustomStageShadow[]

Optional. An array containing the shadows that will be used in rooms of shape RoomShape.SHAPE_2x1 (6) and RoomShape.IIH (7).

If more than one shadow is specified, one will be randomly chosen for each room.

If not specified, no extra shadows will be drawn in these room shapes.

2x2?

readonly optional 2x2?: readonly CustomStageShadow[]

Optional. An array containing the shadows that will be used in rooms of shape RoomShape.SHAPE_2x2 (8), RoomShape.LTL (9), RoomShape.LTR (10), RoomShape.LBL (11), and RoomShape.LBR (12).

If more than one shadow is specified, one will be randomly chosen for each room.

If not specified, no extra shadows will be drawn in these room shapes.

bossPool?

readonly optional bossPool?: readonly CustomStageBossPoolEntry[]

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:384

Optional. An array containing the bosses that should be used for the stage. This can include both vanilla bosses and modded bosses.

versusScreen?

readonly optional versusScreen?: object

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:392

Optional. A collection of colors used for in the boss “versus” screen for all of the bosses.

Note that these graphics will only be applied if one or more bosses are specified in the bossPool field.

backgroundColor?

readonly optional backgroundColor?: object

Optional. An object representing the color to use for the background of the boss “versus” screen. If not specified, the color for Basement 1 will be used.

For a list of the colors that correspond to the vanilla stages, see versusScreenBackgroundColors.ts.

backgroundColor.r

readonly r: number

Minimum

0

Maximum

1

backgroundColor.g

readonly g: number

Minimum

0

Maximum

1

backgroundColor.b

readonly b: number

Minimum

0

Maximum

1

backgroundColor.a

readonly a: number

Minimum

0

Maximum

1

dirtSpotColor?

readonly optional dirtSpotColor?: object

Optional. An object representing the color to use for the dirt spots in the boss “versus” screen. (There are two dirt spots; one for the player and one for the boss.) If not specified, the color for Basement 1 will be used.

For a list of the colors that correspond to the vanilla stages, see versusScreenDirtSpotColors.ts.

dirtSpotColor.r

readonly r: number

Minimum

0

Maximum

1

dirtSpotColor.g

readonly g: number

Minimum

0

Maximum

1

dirtSpotColor.b

readonly b: number

Minimum

0

Maximum

1

dirtSpotColor.a

readonly a: number

Minimum

0

Maximum

1

---

CustomStageShadow

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:466

A description of a custom stage shadow. (In this context, “shadows” are the outlines from things on the roof. For example, in Basement, a shadow of a sideways V is used, among others.)

Properties

pngPath

readonly pngPath: string

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:473

The full path to the shadow overlay PNG file.

For an example of a vanilla shadow overlay, see: resources/gfx/overlays/basement/1x1_overlay_1.png

color?

readonly optional color?: object

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:481

Optional. An object representing the color used for the shadow.

If not specified, an object of { r: 0, g: 0, b: 0, a: 0.25 } will be used (which corresponds to 75% faded black).

r

readonly r: number

Minimum

0

Maximum

1

g

g: number

Minimum

0

Maximum

1

b

b: number

Minimum

0

Maximum

1

a

a: number

Minimum

0

Maximum

1

---

CustomStageBossPoolEntry

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:512

An object that represents a possible boss for a custom stage. This can be for a vanilla boss or a custom boss.

Properties

name

readonly name: string

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:517

The name of the boss. This should correspond to the entry for the boss in the “entities2.xml” file.

subType

readonly subType: number

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:535

The arbitrary sub-type chosen for this boss, ranging between 1 and 999. You must set the boss rooms for this boss to this sub-type in Basement Renovator by right-clicking on the room on the right-hand-side.

It does not matter if the arbitrary sub-type overlaps with any of the vanilla BossID values (e.g. vanilla Boss Room sub-types in “00.special_rooms.stb”). It also does not matter if this value overlaps with the values from other mods.

If you are creating an entry for a vanilla boss, it is recommended that you match the sub-type with the corresponding vanilla BossID value. This will make things a bit easier to understand for people working on your mod, but is not a hard requirement.

Minimum

1

Maximum

999

weight

readonly weight: number

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:542

The weight of the boss. This is used when randomly selecting which boss to use for the floor. For example, use a value of 1 if you want this boss to be equally likely as any other boss, 0.5 if you want it to be half as likely, 2 if you want it to be twice as likely, and so on.

versusScreen?

readonly optional versusScreen?: object

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:545

Optional. A collection of sprites used for the boss on the “versus” screen.

namePNGPath

readonly namePNGPath: string

Mandatory. The full path to the spritesheet that contains the graphics of the name of the boss that will be displayed on the top of the boss “versus” screen.

If not specified, a sprite showing “???” will be used.

portraitPNGPath

readonly portraitPNGPath: string

Mandatory. The full path to the spritesheet that contains the portrait of the boss that will be displayed on the right side of the boss “versus” screen.

If not specified, a sprite showing “???” will be used.

---

CustomStageRoomMetadata

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:587

Metadata about a custom stage room. Each custom stage object contains an array with metadata for each room.

Properties

type

readonly type: number

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:588

variant

readonly variant: number

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:589

subType

readonly subType: number

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:590

shape

readonly shape: number

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:591

doorSlotFlags

readonly doorSlotFlags: number

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:592

weight

readonly weight: number

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:593

Type Aliases

CustomStageLua

CustomStageLua = Immutable<CustomStageLuaUnsafe>

Defined in: packages/isaacscript-common/src/interfaces/CustomStageTSConfig.ts:581

An object that represents a custom stage. The “customStageMetadata.lua” file contains an array of these objects. Besides the room metadata, the data is the same as what is specified inside the “tsconfig.json” file.

The CustomStage interface extends this, adding more data.