Guides‎ > ‎zzromtool‎ > ‎

Intro

This page covers the following:

  • Introduction, why this workflow?
  • Dumping a rom's filesystem
  • Building a rom
  • Building a compressed rom
  • Further reading

Introduction, why this workflow?

If you've done any Zelda hacking pre-2019, here are the rules you're likely very familiar with:
  • All custom content must replace something already existing within the game. (A custom object/map/actor/etc must replace an existing object/map/actor.)
  • The custom file must be smaller than or equal to the file being replaced. If not, it must be moved into free space.
  • You must keep track of the free space you have available. At first, the only free space available is at the end of the rom. As you progress, you'll free up space elsewhere. If it sounds like spaghetti, that's because it is.
  • By moving a file into free space, you create collisions with all other patches that use the same space. Patches that use free space in such a way are incompatible with each other.
  • Any time you want to work with entrances, you must replace existing entrances, breaking something somewhere else in the game.
  • The same holds true for entrance cutscenes.
  • In a team setting, you're going to want to designate one guy for stitching the content together (preferably CDi-Fails). The process typically starts anew for each demo, and assets must be finalized. That last part is optional if you're okay with him hating you for wanting to change major stuff after it's in.
  • Some (or many, depending on what you're doing) steps require hex editing.
The new workflow has been designed to improve upon these things. Every negative rule of the old workflow is countered with a positive:
  • No longer are you limited to simply replacing content: you can add content, too!
  • Files that you do replace no longer have to be smaller than or equal to the file being replaced.
  • What's free space? zzromtool takes care of getting the files into the rom as optimally as possible for you.
  • Sharing assets between projects is now much easier. Copy files over and make the necessary adjustments and you're gold.
  • In addition to changing existing entrances, you can add new entrances. The file containing the entrance information is easy to edit and allows you to embed notes.
  • In a team setting, having the project directory on a shared server works best. Everyone has access to all assets, can make changes, build the latest rom for testing, etc. No more fiddling around with passing patches back and forth and wondering which is the latest and what rom to apply them to. A change log is a good idea to include with your project if you're going this route.
  • No hex editing necessary, unless you're doing some weird advanced stuff.
This doesn't come without its caveats, though.
  • zzromtool doesn't edit the rom directly. As you test, you will have to build a new rom for each test. Even though rom building is very fast, this is still something to keep in mind.
  • If you enjoy hex editing and manually controlling what files go where, you're going to be disappointed. zzromtool abstracts this entire process.
  • Old school hex editing tutorials based on rom offsets will require some extra effort. See the section Adapting old tutorials for more information.
  • Possible forwards-compatibility nightmares between program revisions.
  • The only rom currently supported is OoT debug. Support for 1.0 U is underway.
  • You have to trust that a tool with version number 0.01 will actually work... reliably... consistently.
If you think it will serve you well, give it a spin and see if it suits you. Maybe you'll like it, maybe you'll hate it.

Dumping a rom's filesystem

To dump a rom, open a rom with zzromtool. You can do this by dragging and dropping the .z64 file directly onto zzromtool.exe, or right clicking the rom and opening with zzromtool.

It will give a prompt. Type Y and press the return key.

Things to keep in mind:
  • The rom must already be decompressed.
  • As of this writing, only the OoT debug rom is supported.
  • If you use an unsupported rom, it will either crash, or do something really bad.
  • It does not dump roms that it has already rebuilt.
  • So please use a clean debug rom, or at least one that has been modified using conventional methods.

Building a new rom

To build a rom, open project.zzrp in zzromtool. For faster building in the future, you can set .zzrp files to open with zzromtool by default so you can simply double-click them.

It will give a prompt. Type Y and press the return key.

A rom named build.z64 will be built and placed in the same folder as project.zzrp.

Building a compressed rom

Do the same steps described above, but type C instead of Y when prompted and give it a few minutes to do its thing. The initial compression is always the slowest. Subsequent compressions will be much faster.

Further reading

The guides are meant to be brief, and not all features will be covered. All the more in-depth information can be found within the manual.