Before I start I would like to state this:

Any modification done to your copy of Binding of Isaac is done at your own risk. I am not responsible for any damages done to you or your device as a result from following this guide. Do not come to me and hold me accountable. Thanks.

With that out of the way, let's begin!

EDIT: As of today (17/12/2017), this guide is now unmaintained! If it still works for you, good. If it doesn't, figure it out yourself. I've lost interest in TBOI and haven't had the chance to work on this guide again.

• A copy of the Binding of Isaac Afterbirth+.
  
• A good text editor. Here are my recommendations:
  
  • Windows users: Notepad ++[notepad-plus-plus.org]
    
  • Mac users: Textwrangler[www.barebones.com]
    
  • Linux users: gedit if you have a GUI, nano if you are on the CLI.
• Some basic computer knowledge.

To start out, we need to find the location of your mods folder. This is different on each OS. To find it, all you need to do is right click the game on steam, select "Properties..." and then "Browse game files". A directory will open up. Inside this directory is a file called "savedatapath.txt".

Open that file to find the path to your mods folder. Go to that folder and continue to the next step.

First, create a new folder. You can name it anything you like. For my demonstration mod, I call it Zodiac.



Next, enter the folder.


Create a new file in this folder called "main.lua". Make sure that the extension is lua (because Windows and Mac hide extensions by default) and not txt!

Open this file in your favorite text editor and paste the following line into it:


Replace YOURMOD with the name you would like to be shown in the mod selector.

And that's it! Next time you open Isaac, your mod will be shown in the mod selector!

Alright! Let's get down to it! Time to make our first challenge!

First, you need to create a new directory called 'content' in your mod folder (without quotes!). Inside that directory, create a new file called 'challenges.xml' (once again, no quotes!). Open that file with your text editor.

Now, paste the following lines into the document:


This tells the game that we're working on a challenge file.

In between these lines, we're going to define all the challenges we're gonna make. To start creating a challenge, paste the following line between those lines we pasted earlier:


Each time you add this, you will add a new challenge. Of course, without anything else this will fail to work. Let's start off by defining the absolute basics for a challenge:


What I just added were the absolute basics of a challenge. I did this by defining certain attributes to the challenge element. That may sound complicated, but it just means that everything I add to a challenge looks like this:


So back to what I added.

• id: This one has to be added for technical reasons only. The only rule is that within your mod, it must be unique. It defines the order in which your mod will show up in the challenge list.
  
• name: The name of the challenge. This is the name it will have in the challenge list.
  
• endstage: What stage the challenge will end on. See the Reference at the end of the guide for what number means what. In this case, the stage will end at Mom.

Let's add one final thing: Starting items. Defining these is of course what makes a challenge unique! To add a starting item, add the following attribute to your mod:


Put your cursor between the quotation marks. To add an item, all you have to do is making a comma separated list of all the item ids you want to add between the quotes. For a list of ItemIDs, use Platinum God["platinumgod.co.uk"].

Item IDs are in the top left corner when you mouse over an item.

Back to my Zodiac challenge, the file looks like this:


A quick rundown of what is different from my explanation:

• I set endstage to 12. This is the Chest/??? Fight.
  
• The Item IDs listed in startingitems are the 12 Zodiac signs avaiable as items in the game. IDs can be found on Platinum God.

And that should cover the basics of creating a challenge. Next up, we look at the other attributes you can define.

To add an attribute, do it like so:

Replace attribute with the bold name, and fill in the correct info for value.

FROM THIS POINT ON, UNMARKED AFTERBIRTH(+) SPOILERS. YOU HAVE BEEN WARNED!

• id. Must be a number. Defines the challenge list order.
  
• name. Defines the name of the challenge.
  
• endstage. Defines the stage at which the challenge should end. If using any value above 8, altpath must be set. Valid numbers are:
  
  • 6 = Mom
    
  • 8 = Mom's Heart/It Lives.
    
  • 9 = Satan/Sheol
    
  • 10 = Isaac/Cathedral.
    
  • 11 = The Lamb/Dark Room.
    
  • 12 = ??? (Blue Baby)/The Chest.

• startingitems. A comma serparated list of itemIDs that replace the normal starting items. Adding an active itemID will override any the character normally has. IDs can be found on Platinum God[platinumgod.co.uk].
  
• startingtrinkets. What trinketID to start with. IDs can be found on the Gamepedia wiki[bindingofisaacrebirth.gamepedia.com]. (See individual trinket pages for IDs).
  
• startingpill. Define the effect of the starting pill. Mutually exclusive with startingcard. Valid numbers are:
  
  • -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!
• startingcard Define the starting tarot card/rune. Mutually exclusive with startingpill.
  
  • -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
• playertype What player the build should be based on. Can be used to define special characters (Lost and Keeper). Valid values are:
  
  • 0 = Isaac (default)
    
  • 1 = Magdalene
    
  • 2 = Cain
    
  • 3 = Judas
    
  • 4 = ??? (Blue Baby)
    
  • 5 = Eve
    
  • 6 = Samson
    
  • 7 = Azazel
    
  • 8 = Lazarus
    
  • 9 = Eden (note: cannot define hairstyle!)
    
  • 10 = The Lost
    
  • 11 = Lazarus II
    
  • 12 = Black Judas
    
  • 13 = Lilith
    
  • 14 = Keeper
    
  • 15 = Appolyon
• roomfilter. Removes certain rooms from the floor. Not all rooms can be used. Comma serparated list.
  
  • 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 = Isaacs (?)
    
  • 19 = Barren (?)
    
  • 20 = Chest (?)
    
  • 21 = Dice Room
    
  • 22 = Black Market
• cursefilter. Removes certain curses from the floor. Values stack (so to block out both Darkness and the Labyrinth, the value is 3). Valid ids are:
  
  • 1 = Darkness
    
  • 2 = Labyrinth
    
  • 4 = Lost
    
  • 8 = Unknown
    
  • 16 = Cursed.
• getcurse. Force a curse each floor. Values are identical to cursefilter.
  
• achievements. Comma separated list of required IDs. IDs are in game files.
  
• altpath. If set to true, makes Isaac go to the Cathedral. If set to false, makes Isaac go to Sheol.
  
• canshoot. If set to false, Isaac wil gain a blindfold and can't shoot tears. Cannot be used to make Lilith shoot tears.
  
• 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.
• megasatan. Makes the last boss be Mega Satan. Path can be selected with endstage. Setting this to true does not give the player Key Piece 1 and Key Piece 2, so they still have to be forced manually through startingitems.

Alright. You've done it! Your challenge pack is complete. Time to upload it! Uploading is very easy. Before you start though, make sure to check the following things:

• Can you beat your own challenge? A challenge must be fair. Although nobody will stop you from uploading impossible challenges, unfair challenges just drive away people.
  
• Is your mod syntactically correct? This is easy to check. If there is any fault in your files, the game wil generate an update.it file inside your mods folder and will refuse to load the mod (listing it as [OLD] in the mod selector and red).
  
• Activate your mod at least once through the in-game mod selector. This will generate metadata.xml (which is needed for the uploader).

Checked that? Good. Let's get uploading!

First, open up Isaac's folder (the one we got savedatapath.txt from). Go to the 'tools' folder. Then to the ModUploader folder. Start the ModUploader. You will get a screen that looks like this:


Drag the generated metadata.xml file (if this doesn't exist, select the mod at least once in the in-game mod selector!)

You can edit the description if you wish and add change notes if you want. To add the icon, click on the change bar and browse to your icon. You can also change the visibility to friends only or private.

Finally, under tags tick the 'challenges' box. Then click upload mod. Wait a couple seconds, and it's visible.

If you change your mod later, just drag metadata.xml on it again and reclick upload. It should not create another upload. If you change it I recommend adding change notes so that subscribers know what has been changed.

If anything was unclear or if you didn't understand something, leave a comment! If you have any feedback or suggestions, leave a comment!

Lastly, here are some useful links to help you with modding:

• http://platinumgod.co.uk - Has a list of all items in Isaac along with their IDs. Also has a list of trinkets and their IDs.
  
• /r/themoddingofisaac - For more general modding support.
  
• Zodiac challenge - The Zodiac challenge mod I made as an example for this guide.

Have a good day!

~DD

• 21 januari 2017 - 1.0.3 - Platinum God removed trinketids. Trinketids are now found on Gamepedia's wiki.
  
• 11 januari 2017 - 1.0.2 - Minor edit on megasatan.
  
• 8 januari 2017 - 1.0.1 - Minor edit on endstages.
  
• 5 januari 2017 - 1.0 - Initial release.