Custom Challenges

Introduction

Custom Challenges are player-made challenges that can be accessed by pressing TAB in the in-game Challenges menu.
These challenges can be defined in a challenges.xml file placed in a mod's content folder.
- An example of such a folder is C:/Users/Your Username/Documents/My Games/Binding of Isaac Afterbirth+ Mods/Your Mod/content.

General Format

The challenges.xml file uses <challenge> elements placed in a root <challenges> element.
Here's a general template that can be used in order to create custom challenges:

<challenges version="1">
    <challenge name="My Custom Challenge" />
</challenges>

Multiple <challenge> elements can be added, each one a new line.
Each challenge is defined by using a set of attributes between the <challenge> tags that control the game's mechanics, such as starting items, trinkets, cards, pills, end stage, amount of heart containers, curses, rooms that will be spawned, etc.

Attributes

This is the full set of attributes that can be used to define the custom challenge rules.

Attribute	Value type	Explanation	Default value	Possible Values
name	string	The name that's going to show in the Custom Challenges menu.	n/a	Arbitrary unique string.
id	integer	Unique challenge ID. This is used if you want to apply special behavior to the challenge using a mod, i.e. via Lua scripts. The ID must be a unique number that's not used by any other default or custom challenge.	`0`	Arbitrary unique integer (i.e. whole number).
startingitems	integer list	Item ids that the player will receive in the beginning. Each id must be separated with a comma (no spaces).	n/a	See Items for all item IDs.
startingtrinkets	integer list	Trinket ids that the player will receive in the beginning. Each ID must be separated with a comma (no spaces).	n/a	See Trinkets for all trinket IDs.
startingpill	integer	Effect ID of the pill that the player will receive in the beginning.	`-1`	See Pills for all IDs. `-1` means no pill.
startingcard	integer	ID of the card that the player will receive in the beginning. This can also be a rune or other card-like pickup.	`0`	See Cards and Runes for all IDs. `0` means no card/rune. `-1` can be used for a random tarot card.
playertype	integer	ID of the character that will be used in the challenge.	`0`	See the Characters list below for all IDs. `0` means Isaac.
endstage	integer	The final stage of the challenge. This is where the trophy will spawn. The trophy will also spawn on any next floor in case the player manages to continue.	`0`	See the End Stage list below.
roomfilter	integer list	List of room IDs (separated by commas) not to be generated.	n/a	See the Room Filters list below for all IDs. `roomfilter="4"` means no Treasure Rooms. `roomfilter="4,2"` means no Shops or Treasure Rooms.
cursefilter	integer	Bitmask for curses that won't appear in the challenge.	`0`	Either a single curse number, or a number which combines all banned curses. See Curses list below for details.
getcurse	integer	Bitmask for curses that will be forced all the time.	`0`	Either a single curse number, or a number which combines all forced curses. See Curses list below for details.
achievements	integer list	List of achievement IDs required in order to play the challenge. Each ID must be separated with a comma (no spaces).	n/a	IDs correspond to the in-game secret numbers, listed in the Achievements table
altpath	boolean	Alternative floor for light/dark path (Isaac/Satan).	`false`	`true` = go to The Chest `false` = go to The Dark Room
canshoot	boolean	If set to `false` the player will be blindfolded and unable to shoot.	`true`	`true` = Player can shoot tears `false` = Player cannot shoot, and must rely on familiars, melee weapons, or other destructive items.
redhp	integer	Fills a specified amount of red heart containers. This does not add new containers. Uses half hearts as a measure so 1 full heart container is equal to 2. This number can be negative.	`0`	An integer between `-24` (12 empty heart containers) and `24` (12 full heart containers). E.g., to make a character who starts with 3 empty red hearts, use `-6`.
maxhp	integer	Adds a specified amount of red heart containers. Uses half hearts as a measure so 1 full heart container is equal to 2.	`0`	Between `0` (no red hearts) and `24` (12 red hearts)
soulhp	integer	Adds a specified amount of soul hearts. Uses half hearts as a measure so 1 full heart container is equal to 2.	`0`	Between `0` (no soul hearts) and `24` (12 soul hearts)
blackhp	integer	Adds a specified amount of black hearts. Uses half hearts as a measure so 1 full heart container is equal to 2.	`0`	Between `0` (no black hearts) and `24` (12 black hearts)
coins	integer	Adds a specified amount of coins.	`0`	Between `0` and `99`, or up to `999` if the player starts with Deep Pockets (ID: 416)
maxdamage	boolean	Setting this to true will fix the player's damage to `100`, preventing any damage-modifying items from affecting it.	`false`	`true` = Cap max damage at 100 `false` = No cap
adddamage	float	Modifies the player's damage by a specified amount.	`0.0`	Any floating point number (i.e., a decimal number, such as `1.5` or `2.0`)
minfirerate	float	Fixes the player's tear delay to a specified amount, preventing any tear-delay-modifying items from affecting it	`0.0`	Any floating point number (i.e., a decimal number, such as `1.5` or `2.0`)
minshotspeed	boolean	Setting this to true will fix the player's shot speed to `1`, preventing any shot-speed-modifying items from affecting it.	`false`	`true` = Cap max shot speed at 1 `false` = No cap
bigrange	boolean	If set to `true`, adds +10 range to the player.	`false`	`true` = Add +10 range `false` = No change
difficulty	integer	Game difficulty (`0` = normal; `1` = hard).	`0`	`0` = Normal Mode `1` = Hard Mode
megasatan	boolean	If set to true, the challenge will to go to Mega Satan. This will also give Key Piece 1 and Key Piece 2 required to open the door.	`false`	`true` = Player must defeat Mega Satan. The end stage must be set to `11` (Dark Room), with `endstage="11"` `false` = No change
secretpath	boolean	If set to true, the challenge will be forced to use the Repentance alt path. The player will still be required to manually collect Knife Piece 1 and Knife Piece 2.	`false`	`true` = Player must defeat Mother. The end stage must be set to `8` (Corpse), with `endstage="8"` `false` = No change

Characters (`playertype`)

A list of character IDs, for use with the playertype attribute.

Character	playertype ID
Isaac	0
Magdalene	1
Cain	2
Judas	3
???	4
Eve	5
Samson	6
Azazel	7
Lazarus	8
Eden	9
The Lost	10
Lazarus Risen	11
Dark Judas	12
Lilith	13
Keeper	14
Apollyon	15
The Forgotten	16
The Soul	17
Bethany	18
Jacob	19
Esau	20
Tainted Isaac	21
Tainted Magdalene	22
Tainted Cain	23
Tainted Judas	24
Tainted ???	25
Tainted Eve	26
Tainted Samson	27
Tainted Azazel	28
Tainted Lazarus	29
Tainted Eden	30
Tainted Lost	31
Tainted Lilith	32
Tainted Keeper	33
Tainted Apollyon	34
Tainted Forgotten	35
Tainted Bethany	36
Tainted Jacob	37
Dead Tainted Lazarus	38
Tainted Jacob 2	39
Tainted Soul	40

End Stage (`endstage`)

A list of stage IDs, which correspond to various chapters, for use with the endstage attribute.

This attribute sets the final stage of the challenge. This is where the trophy will spawn, after the floor boss is defeated. The trophy will also spawn on any next floor in case the player manages to continue.

Stages	endstage ID	Chapter
Basement Cellar Burning Basement Downpour Dross	`1` / `2`	Chapter 1
Caves Catacombs Flooded Caves Mines Ashpit	`3` / `4`	Chapter 2
Depths Necropolis Dank Depths Mausoleum Gehenna	`5` / `6`	Chapter 3
Womb Utero Scarred Womb Corpse	`7` / `8`	Chapter 4
???	`9`	Chapter 4.5
Cathedral Sheol	`10`	Chapter 5
Chest Dark Room	`11`	Chapter 6
The Void	`12`	Endgame
Home	`13`	Endgame

Room Filters (`roomfilter`)

A list of room IDs, for use with the roomfilter attribute.

This attribute sets a list of rooms IDs, separated by commas, which should not be generated.

For example, to disable both Treasure Rooms and Shops, use roomfilter="2,4"

Room	ID
Normal	1
Shop	2
I AM ERROR	3
Treasure	4
Boss	5
Miniboss	6
Secret Room	7
Super Secret Room	8
Arcade	9
Curse	10
Challenge (Normal)	11
Library	12
Sacrifice	13
Devil Room	14
Angel Room	15
Boss Challenge	16
Boss Rush	17
Clean Bedroom	18
Dirty Bedroom	19
Vault	20
Dice Room	21
Black Market	22
Greed Mode Exit	23
Planetarium	24
Teleporter	25
Teleporter Exit	26
Secret Exit	27
Blue	28
Ultra Secret	29

Curses (`cursefilter` & `getcurse`)

A list of curse bitmasks, for use with the cursefilter and getcurse attributes.

Unlike other attributes which accept a comma-separated list, the two curse attributes accept a single number, which is the combined total of all applicable curses.

For example, to apply Curse of the Labyrinth (2) and Curse of the Maze (32), the attribute value would be 34 (which is 32 + 2).

Curse	Bitmask
Curse of Darkness	1
Curse of the Labyrinth	2
Curse of the Lost	4
Curse of the Unknown	8
Curse of the Cursed	16
Curse of the Maze	32
Curse of the Blind	64
Curse of the Giant	128

Bugs

Bug!	Using "roomfilter" to prevent Treasure Rooms from spawning will still make a Treasure Room spawn in Downpour/Dross 2. This is due of the fact that a Treasure Room must be generated in the mirrored world in order to spawn Knife Piece 1.

Bug!	Using the "canshoot" attribute in combination with "secretpath" can lead to a softlock in the Knife Piece 2 area because the player will not be able to shoot along with not having any items from the challenge itself. Often times room layouts will contain a poop that needs to be broken in order to open up a path.