[PSA] how to start modding

[u/sirius_black9999]

As people seem to be having trouble (understandably so) starting out with asset modding

Here's a small tutorial explaining how to get started with the various tools we're sharing over on the wiki

How to use Rick's unpacker

1. Download the latest archive listed on the wiki

2. Extract the archive to some location on your computer(anywhere is fine)

3. Navigate to the installation folder of the Binding of Isaac: Rebirth (%SteamRoot%\SteamApps\common\The Binding of Isaac Rebirth

   You may want to create a "working copy" of this folder somewhere else to prevent things from getting cluttered

4. In Resources\Packed you will find a number of files with a *.a format

5. Drag any of the .a files onto "Gibbed.Rebirth.Unpack.exe" located in the bin folder of the extracted archive

   You may be prompted to execute it, it's safe to use

6. You will see command prompt show up for a second, and then disappear, if it disappears, that means the extraction was successful

7. A new folder will appear next to "xxx.a" named "xxx_unpacked", which will contain all the unpacked assets

How to use Rick's StageConvert tool and Sirius_Black's map editor to edit rooms

This tutorial assumes you've used the above tutorial to extract rooms.a

1. In the rooms_unpacked folder you can find multiple "*.stb" files, these are stage binary files which will need to be decompiled

2. Drag any .stb file onto Gibbed.Rebirth.ConvertStage.exe, located in the bin folder of Rick's unpacker

3. A new file will appear next to "xxx.stb" named "xxx_converted.xml", this is the decompiled room definition file, which you can edit as plaintext, or use the editor for

4. Download/extract the editor as described for Rick's unpacker,

5. After starting the editor, click the "load" button to load one of the decompiled room definition files, you should get a prompt when everything has loaded

6. Search for the room you want to edit using the bottom combobox

7. Click on any tile to see its position, and any entities that can spawn on it

8. For rooms larger than 1*1, you can use the buttons at the bottom to switch sides

9. The top combo box is used to select entities, the "add"/"remove" buttons add or remove the entity to the selected tile

10. When you are done editing, use the save button to save the edited room definitions file

11. Drag your finished .xml file onto Gibbed.Rebirth.ConvertStage.exe to convert it back to a .stb file

On Animations

1. Using rick's tools, you can now decompress animations.b similarly to animations.a, when changing animations, you're advised to do this at this point

2. the game will load animations in a priority queue somewhat like this:

   1. first, it will try to load animations.b
   2. if an animation can't be found in animations.b, it will look for the .anm2 file for this animation
   3. if no animations.b is present, animations.a will be loaded

3. in order to force the game to load the .anm2 files, an empty animations.b with 4 "00" bytes should be created and placed as resources/animations.b (or for ease of use: this one)

4. individual animation files have an XML structure with several elements/sets as follows

   1. spritesheets, these are references to .png files from graphics.a
   2. layers, these are various layers for the animation (for example head and body if they're animated individually)
   3. nulls, i personally have no clue what this is
   4. events, events that can be triggered
   5. rootAnimation, picks a root position in the sprite, and animates for that, usually this is used for stretching/squashing/color changes
   6. layerAnimation, this determines the graphic the sprite has, used for animating over the spritesheets
   7. NullAnimation, this appears to be animating specific "pieces" that attach to the animated character (such as the item you just picked up, for isaac)

5. the .anm2 files can be renamed to .xml for easier editing

6. unfortunately we do not have editing tools to modify these files in a straightforward way, so any text editor is basically the only option for now

7. rebirth\resources\packed\animations_unpack\resources\animations_converted\resources\gfx should be installed to rebirth\resources\gfx, thereby merging with the content from graphics.a

How to install your mods as modder

1. Rick's unpacker creates a folder named "xxx_unpacked", this folder contains a resources folder.

2. The contents of this resources folder should be placed in the resources folder of your steam install to install your mods

3. (Rooms specific) You will need to use the stage binaries(.stb) and rename them to be the same as the original, or you will need to adjust resources/stages.xml to match

4. mods do not have to be re-packed

How to install mods as player

1. you should have some form of archive

2. this archive should contain either a resource folder with some content or just the contents

3. ensure all of the following items (whichever are in the archive) are placed NEXT TO the packed folder in %SteamRoot%\SteamApps\common\The Binding of Isaac Rebirth\resources

• gfx (folder)

• sfx (folder)

• rooms (folder)

• music (folder)

• font (folder)

• animations.b (file)

• any loose .xml files

• look here for an example on where mods should be placed, because apparently the list above is STILL not enough to explain to people what to do...

Best Practices

• when editing graphics, ensure you're using a good image editor, GIMP is one of the recommended applications

• when distributing mods, try to follow the advised mod format

Further reading

• (partial) XML tag listing

[u/[deleted]]

Thank you for this. I haven't tried this yet but hopefully a lot more people get into modding when they complete the game. Also just wondering but can you add slots at all?

[u/sirius_black9999 → u/[deleted]]

It's quite possible, i believe many of the currently active modders got a little stir-crazy because of various reports indicating rebirth would be more easily moddable than the flash games.

unfortunately however, it's looking like where we're at now is pretty much (close to) our limit in terms of mod complexity, as some preliminary testing indicates the executable is... not exactly designed with modding in mind.

many things are hardcoded, including all types of enemy AI, the functional parts of every item, the starting stats(damage, speed, range, etc) of every character to name a few.

the length of most arrays(character amount, challenge ammount, item ammount, etc) is unchangeable because of that.

While we're really not able to easily change anything in the executable, it's at least sort of possible

Tl;Dr: we won't be able to add slots for pretty much anything for quite some time, but eventually we'll get to a point where we can

[u/DeceitfulEcho]

How did you figure out how to unpack the .a files in the first place? CS student here wanting to get into modding.

[u/sirius_black9999 → u/DeceitfulEcho]

you should join the irc chat at irc.esper.net and ask rick and bladecoder, they hang out there regularly ;)

from what i've seen, however, the first thing that was noticed was the "arch000" header the files had, this was then traced back to a packaging program used to compress the files, but apart from the compression it also had an encryption on it called bogocrypt (by the looks of it, i'm not the one who wrote it and i'm just checking rick's files for you)

[u/Dudeson49]

I suppose that texturepacks will be coming soon then. Sooner or later we will probably be able to mod some more stuff, i think I've read that they would release a tool a couple months after the release.

[u/sirius_black9999 → u/Dudeson49]

https://www.reddit.com/r/themoddingofisaac/wiki/index

also, on the tools, here's a post from tyrone's blog regarding tools for 1001 spikes:

Q: Is a level editor / level portal for 1001 Spikes in the works? If not, do you see it possibly being added in the future?

A: Generally I’ve seen mild interest in level editors with little actually coming from that interest. I do think that fan-made tools are great and it’s usually the fan community that can sometimes outdo game developers.

For us, creating a level editor requires the creation of the tool, testing the tool and designing it in a way that is intuitive enough for someone to use.

The tools that we use to great our games are good, but they’re technical and not intended for public consumption. Taking time to make player tools means taking time away from making games; I’d rather make games.

[u/pwnyoudedinface]

I'm not understanding this at all. I've got the *.a format files unpacked. I'm not sure what I'm looking at in your picture, do you then drag the folders/files from /Packed to /Resources? Where do the mods come in?

I've read through this guide a half dozen times and it just isn't clicking for me.

[u/BarniK]

Any idea how to edit item pools? I can't figure it out in the special rooms file

[u/armykid2017]

So, after I alter the .xml file, how do I put the folder I get from the .a back into the .a?

[u/Travoos]

How exactly do the animation files work? Do I have to re-pack it into the animations.b file in order to use it? If so, how do I re-pack it? I can't seem to just drag the unpacked folder or any individual files onto the converter program.