Overview
How to create custom challenges in the Binding of Isaac. No coding knowledge needed!
Preface
Hello all. This is a guide for making custom challenges that iterates on Techpriest’s wonderful custom challenge guide. I used his as a jumping off point for this guide, but seeing as he is not updating it anymore and it is out of date, I have decided to carry the torch of custom challenge guides for the Binding of Isaac, because I think they are really fun. I would also like to say that I have very little modding or coding experience. I will read the comments to this guide and answer what I can, but my knowledge is limited and I may be unable to answer certain questions. Also my guide will be focused on Windows OS because Repentance is not on Mac. Much of the information with this guide was assembled through trial and error, and there may be inaccuracies. I would greatly appreciate any of these pointed out, and I will correct them.
Requirements
- Binding of Isaac Repentence
- A text editor. I recommend Notepad++ because it’s free and perfectly suited to our purposes.
- Extremely basic computer knowledge (If I can do it you can too).
Step 1: Creating a Mod Folder
Your custom challenge will be located in a mod folder within the Binding of Isaac mods folder. To find this, simply right click on the game in your steam library, click properties, and then click “browse game files.” From here, go into the folder called mods. If you have any mods from the workshop installed, you should see them here. From here, we need to create a folder that will store our custom challenges. It can be called anything you like. It doesn’t really matter what it is called if you are not uploading your challenges to the workshop, but if you are you should title it something that indicates what type of challenge(s) are in it. Inside of your newly created mod folder, we will create another folder called “content.” Now within this folder, we will create a text document called “challenges” which we will save as an XML (eXtensible Markup Language) file. Inside this file we’ll need to do a few things to set it up. Our first line in our file should say:
<challenges version=”1″>
Then have a space for a second line, and our third (and final) line will say:
</challenges>
In between these two lines, we can make as many individual challenges as we want. Begin each challenge on a new line, and write <challenge first. Close each challenge with a /> at the end after we have written all of our challenge parameters.
Step 2: Creating Your First Challenge
Creating a challenge is surprisingly simple when it comes to how much code (don’t worry! you don’t need to have any prior experience, but you are coding!) you have to write. Challenge parameters are composed of several values that indicate which character you will play as, what items, trinkets, pills, cards, etc. you will start with and more. Each parameter will have a section in this guide that lists the relevant values with an explanation on what the parameter does. When I say “values” I mean either a number that is connected to a collectible’s ID (such as 1,2,3 etc.) or a Boolean operation which is to say a string that says either “true” or “false.” If this sounds overwhelming don’t worry. It’s actually very simple.
There are a few required parameters for every challenge. I’ll list them in the order that they appear in this screenshot, but the order of parameters in the challenge does not matter.
[i.imgur.com]
playertype is the parameter that sets which character you play as. A fill list is available later on in this guide. It is formatted like this: playertype=”0″
name is the name of the challenge. It is a string, which means you just write whatever you want the challenge to be called in quotations marks. The name of the challenge in this screenshot is Trick Rage.
id is the unique ID associated with the challenge. For our purposes, we won’t really use this for anything. This just needs to be a number that is unique to a given challenge. You can just start at 1 for your first challenge and go up from there. It is formatted like this: id=”1″
endstage sets what boss needs to be defeated to beat the challenge. This is probably the most complicated parameter because certain bosses require the use of an additional parameter. Here are the possible endstage values:
Mom = 6
Mom’s Heart/It Lives = 8
Isaac and Satan = 10 Note: an additional parameter is used to set whether or not the challenge has you defeat Isaac or Satan. It is a Boolean parameter where “true” sets it to Isaac and “false sets it to the lamb. It is called altpath so to set it for Isaac you would write endstage=”10″ altpath=”true”
??? and The Lamb = 11 This uses the same altpath parameter as the previous endstage, with “true” being for ??? and “false” being for the lamb.
Mother = 8 Note: an additional parameter is used to distinguish Mother from Mom’s Heart, which has the same value. To make Mother the end goal, write endstage=”8″ secretpath=”true” This will make it so that Isaac automatically is able to enter all of the secret doors, but will still have to manually collect the knife pieces. Note that certain challenges may be unable to collect the second knife piece, and softlocks can be avoided by having Isaac start with the knife piece.
Mega Satan: To make the last challenge mega Satan first choose whether you want the player to be in the chest or dark room for the mega satan fight using the altpath and endstage parameters we just discussed. Then write megasatan=”true” This will have Isaac automatically start with the two key pieces, which still retain their influence over Angel/Devil chances.
These are actually the only required parameters for a challenge to function! But your challenge isn’t going to be very interesting just with these. Here are a two important parameters almost every challenge will contain.
startingitems: This parameter, shockingly enough, dictates which items your character will start with. Each item in the game has an associated ID, which can be found on platinumgod.co.uk or the fan gamepedia wiki. I’d recommend the gamepedia over platinumgod because it also has the IDs of other useful things like trinkets, pills, and cards (more on them later). Commas separate lists so they will look something like this: startingitems=”1,2,3,4″
roomfilter: This parameter will disallow certain types of rooms from spawning. Note that you can’t filter every room as no valid rooms will exist and your game will crash. Commas separate lists here again and the rooms have the following IDs:
1 = Normal
2 = Shop
3 = Error
4 = Treasure Room
5 = Boss
6 = Miniboss
7 = Secret Room
8 = Super Secret Room
9 = Arcade
10 = Curse Room
11 = Arena
12 = Library
13 = Sacrifice Room
14 = Devil Room
15 = Angel Room
16 = Boss Arena
17 = Boss Rush
18 = Clean Bedroom
19 = Dirty Bedroom
20 = Vault
21 = Dice Room
22 = Black Market
23 = Greedexit (?) Likely has no effect
24 = Planetarium (untested)
25 = Teleporter (?) Likely has no effect
26 = Teleporterexit (?) Likely has no effect
27 = Secretexit (?) Likely has no effect
28 = Blue (Can only be entered normally with blue key)
29 = Ultra Secret (untested)
So if you want to stop treasure rooms and angel rooms from spawning, you would write roomfilter=”4,15″
With this knowledge, you can create challenges with a name and ID that have you play as a specific character, with specific starting items, a specific goal, and specific rooms filtered out. Already there is a lot you can do with this knowledge. However, there is still a lot more you can do while still not needing to know anything about coding or looking through game files. The next section will be a detailed list of other challenge parameters and how to use them.
Full attribute list and values
In this section I will list the values for parameters I didn’t already discuss earlier. I won’t list Items and Trinkets here because of how many there are, but their IDs are readily available on the gamepedia wiki and on platinumgod.co.uk.
playertype:
0 = Isaac (default)
1 = Magdalene
2 = Cain
3 = Judas
4 = ??? (Blue Baby)
5 = Eve
6 = Samson
7 = Azazel
8 = Lazarus
9 = Eden
10 = The Lost
11 = Lazarus II
12 = Black Judas
13 = Lilith
14 = Keeper
15 = Apollyon
16 = The Forgotten
17 = The Soul (Note: 16 and 17 are effectively the same character. Choosing a value of 17 will have the player start as the soul rather than the forgotten, but the rest of their mechanics are identical)
18 = Bethany
19 = Jacob and Esau
20 = Tainted Isaac
21 = Tainted Magdalene
22 = Tainted Cain
23 = Tainted Judas
25 = Tainted ??? (Blue Baby)
26 = Tainted Eve
27 = Tainted Samson
28 = Tainted Azazel
29 = Tainted Lazarus
30 = Tainted Eden
31 = Tainted Lost
32 = Tainted Lilith
33 = Tainted Keeper
34 = Tainted Apollyon
35 = Tainted Forgotten
36 = Tainted Bethany
37 = Tainted Jacob
startingtrinkets sets what trinkets you start with. It is formatted like this: startingtrinkets=”1,2,3,4″ with comas separating. Note that you can only start with one trinket unless you have an item that lets you hold 2, in which case you can start with 2. Other trinkets will NOT spawn into the game. The value for the numbers can be found on the Binding of Isaac Wiki or platinumgod.co.uk. For example, Swallowed Penny’s ID is 1.
startingpill sets what pills you start with. It is formatted like this: startingpill=”1,2,3,4″ with comas separating. Note that you can only start with one pill unless you have an item that lets you hold 2, in which case you can start with 2. Other pills will NOT spawn into the game. This attribute is mutually exclusive with startingcard. The values for pills are as follows:
-1 = No pill (default).
0 = Bad Gas
1 = Bad Trip
2 = Balls of Steel
3 = Bombs are Key
4 = Explosive Diarrhea
5 = Full Health
6 = Health Down
7 = Health Up
8 = I found Pills
9 = Puberty
10 = Pretty Fly
11 = Range Down
12 = Range Up
13 = Speed Down
14 = Speed Up
15 = Tears Down
16 = Tears Up
17 = Luck Down
18 = Luck Up
19 = Telepills
20 = 48 Hour Energy!
21 = Hematemesis
22 = Paralysis
23 = I can see forever!
24 = Pheromones
25 = Amnesia
26 = Lemon Party
27 = R U A Wizard?
28 = Percs!
29 = Addicted!
30 = Re-Lax
31 = ???
32 = One makes you larger
33 = One makes you small
34 = Infested!
35 = Infested?
36 = Power Pill!
37 = Retro Vision!
38 = Friends Till The End!
39 = X-Lax
40 = Something’s wrong…
41 = I’m Drowsy…
42 = I’m Excited!!!
43 = Gulp!
44 = Horf!
45 = Feels like I’m walking on sunshine!
46 = Vurp!
47 = Shot Speed Up
48 = Shot Speed Down
49 = Experimental Pill
It seems as though the effect IDs for golden and horse pills are currently unknown.
startingcard sets what cards you start with. It is formatted like this: startingcard=”1,2,3,4′ with comas separating. Note that you can only start with one card unless you have an item that lets you hold 2, in which case you can start with 2. Other cards will NOT spawn into the game. This attribute is mutually exclusive with startingpill. For Example, The Magician’s value is 3. Note that any q-slot item that is not a pill (such as runes and soul stones) falls under this category. The values for cards are as follows:
-1 = Random
0 = No card (default)
1 = The Fool
2 = The Magician
3 = The High Priestess
4 = The Empress
5 = The Emperor
6 = The Hierophant
7 = The Lovers
8 = The Chariot
9 = Justice
10 = The Hermit
11 = Wheel of Fortune
12 = Strength
13 = The Hanged Man
14 = Death
15 = Temperance
16 = The Devil
17 = The Tower
18 = The Stars
19 = The Moon
20 = The Sun
21 = Judgement
22 = The World
23 = 2 of Clubs
24 = 2 of Diamonds
25 = 2 of Spades
26 = 2 of Hearts
27 = Ace of Clubs
28 = Ace of Diamonds
29 = Ace of Spades
30 = Ace of Hearts
31 = Joker
32 = Hagalaz
33 = Jera
34 = Ehwaz
35 = Dagaz
36 = Ansuz
37 = Perthro
38 = Berkano
39 = Algiz
40 = Blank Rune
41 = Black Rune
42 = Chaos Card
43 = Credit Card
44 = Rules Card
45 = A Card Against Humanity
46 = Suicide King
47 = Get Out Of Jail Free Card
48 = ? Card
49 = Dice Shard
50 = Emergency Contact
51 = Holy Card
52 = Huge Growth
53 = Ancient Recall
54 = Era Walk
55 = Rune Shard
56 = The Fool?
57 = The Magician?
58 = The High Priestess?
59 = The Empress?
60 = The Emperor?
61 = The Hierophant?
62 = The Lovers?
63 = The Chariot?
64 = Justice?
65 = The Hermit?
66 = Wheel of Fortune?
67 = Strength?
68 = The Hanged Man?
69 = Death?
70 = Temperance?
71 = The Devil?
72 = The Tower?
73 = The Stars?
74 = The Moon?
75 = The Sun?
76 = Judgement?
77 = The World?
78 = Cracked Key
79 = Queen of Hearts
80 = Wild Card
81 = Soul of Isaac
82 = Soul of Magdalene
83 = Soul of Cain
84 = Soul of Judas
85 = Soul of ??? (Blue Baby)
86 = Soul of Eve
87 = Soul of Samson
88 = Soul of Azazel
89 = Soul of Lazarus
90 = Soul of Eden
91 = Soul of the Lost
92 = Soul of Lilith
93 = Soul of the Keeper
94 = Soul of Apollyon
95 = Soul of the Forgotten
96 = Soul of Bethany
97 = Soul of Jacob and Esau
cursefilter: this parameter will disallow certain curses from spawning. Each curse has an associated value which stacks additively. This means that you will have one number for this parameter even if you use multiple curses. For example, to filter curse of Darkness and Labyrinth, the value would be 3. The values are as follows:
1 = Darkness
2 = Labyrinth
4 = Lost
8 = Unknown
16 = Cursed
32 = Maze
64 = Blind
getcurse: this is basically the opposite of curse filter. This value will cause curse(es) to spawn on every floor. It has the same values and rules as cursefilter, so to force darkness and labyrinth on every floor, the number would be 3.
achievements: this parameter will force certain achievements to be unlocked before players can play your challenge. The IDs are found in the game files, so if you’re using this parameter your knowledge likely surpasses my own.
canshoot: very important parameter that enables the blindfold. It’s Boolean, so to enable it write canshoot=”false” Interestingly enough cannot remove Lilith’s blindfold.
redhp. Add more red hp hearts. 2 = 1 container.
maxhp. Add more health containers. 2 = 1 container.
soulhp. Add more soul hearts. 2 = 1 container.
blackhp. Add more black hearts. 2 = 1 container.
coins. Add coins. Value is identical to amount of coins added.
maxdamage. Limits maximum damage. Cannot be lower than 100.
adddamage. Add more damage.
minfirerate. Minimal fire rate.
minshotspeed. Minimal shoot speed.
bigrange. Used only in PONG challenge. Makes range ridiculously high.
difficulty. Sets the difficulty. Valid values are:
0 = Normal. (default)
1 = Hard.
A note on Jacob and Esau:
Jacob and Esau are fully custom-challenge friendly, which is great because they allow for a lot of thematic challanges. To make a parameter effect Esau simply add a 2 to the end of it i.e. startingitems2=”1,2,3,4″ The parameters mentioned earlier only effect Jacob (so DON’T put startingitems1=) to have them apply to him.
Step 3: Publication (If You Want)
Now that you know a lot about challenges and have made some of your own, you might want to publish them to the workshop. Well, you’re in luck because you’re 90% of the way there already because of what we set up in step 1!
Before you publish your challenge, make sure you have beaten it without cheating once or twice to avoid angry comments. This is also necessary because you need to play with your mod at least once to generate a metadata.xml file, which we need for the workshop.
Now we go to Isaac’s folder, which we already know how to find from step one. Then go to the tools folder instead of the mods folder. From here, start up the ModUploader.exe. Now you drag the metadata.xml folder that can be found inside your specific mod folder (it should be the only other file in it besides our content/challenges files. From here, you can edit the description to your liking and include change notes. Under the tags, check the challenges box, then click upload mod. Then you’re done!
Closing Thoughts
By now, I hope you have created your first challenge and maybe even uploaded it to the workshop so your friends and the broader Isaac community can play it. It’s not that hard, is it? Still, as with anything related to modding, I’m sure you have questions and unknowns. I’ll answer what I can, but as I said earlier, I’m not a coder. So here are a few pieces of advice from a fellow non-coder:
- Syntax matters, like, a lot. If your game is crashing on launch after you have edited your challenge file, make sure every challenge has a at the end of it /> and that each parameter is spelled and formatted correctly, with strings, values, and Boolean oppositions in quotation marks following a = after the desired parameter with no spaces between anything.
- The easiest way to learn is to see what others are doing. Download a challenge pack from the workshop and view their challenges.xml file to see how they have set things up. I will also upload my own challenge pack to the workshop and link it below, so you can see how I have formatted things.
Link to my challenge pack on the workshop:
Happy modding!