6 users online: JaizePLS,  Losoall, orka-bln, playagmes169, pyredrid,  Telinc1 - Guests: 213 - Bots: 232
Users: 65,483 (2,182 active)
Latest user: pyredrid

A Short Guide to Porting Your ROM


This is not going to be a super long tutorial, but it's something I've had to retype so many times for people that I may as well make a permanent one.

SO! You've accidentally messed something up but you have no idea what. Something's crashing, or acting weird, or just generally not working, but withing knowing how to debug it yourself, where do you even start? Well, turns out, the easiest way is to literally start back from square one, a clean slate. But obviously, you don't want to actually do that because you'd have to redo everything again, right?

Thankfully, no. Lunar Magic features a ton of ways to move resources from one hack to another fairly easily. This process, known as porting, doubles as a nice way to debug where whatever issue plagued your original ROM comes from! That said, Lunar Magic doesn't really provide a particularly standard method of doing this, so this will be a general guide on how to move everything from your old broken ROM to the fresh clean one.

Section 1. Lunar Magic's Resources
First things first, you'll want to deal with Lunar Magic-specific stuff. None of those fancy third-party tools. Since Lunar Magic is pretty much bug-free, you don't have to worry about debugging anything at this point.
(sidenote: if using SA-1, you actually do need to apply that before doing anything through LM, so make sure to do that first)

Here is a list of how to port everything that Lunar Magic natively handles:
  • Levels - Navigate the file menu to "File -> Levels -> Export Multiple Levels to Files...". This will allow you to choose a directory to export all of the modified levels in your hack to a set of MWL files. These files can then be imported back into your new hack through "File -> Levels -> Import Multiple Levels from Files..."; simply select all of the MWL files you created to bring them all in at once. This will also handle all level-related settings including ExGFX files, ExAnimation, and the palette.
  • Overworld - The overworld is one of the weirder things to port, because there's no actual export/import button for the overworld. Instead, open the overworld editor in your old hack. Then, while leaving the overworld editor open, go back to the main editor window and load the new hack. If you go back to the overworld editor, you'll notice the old overworld is still loaded; in fact, simply move any tile to re-enable the save button, then click that to save to the new rom! This will additionally copy all overworld-related settings, including palettes, message boxes, castle cutscenes, and level names.
  • Title Screen, Credits - Same process as the overworld, just with the title screen/credits loaded at the time.
  • Title Screen Inputs - On the overworld editor, go to "File -> Title Screen -> Export Title Moves Playback Data..." to create a fake emulator savestate for the data. Then just import that to the new ROM as normal.
  • Graphics - Before doing anything, extract and reinsert graphics in the new ROM with the #lm{extgfx} and #lm{insgfx} buttons, in order to insert one of Lunar Magic's graphics patches. Then just copy the Graphics and ExGraphics folders from your old hack's directory to the new hack's and import them as your normally would.
  • Map16 - Export and import a .map16 file through the Map16 editor with the #lm{expfile} and #lm{impfile} buttons.
  • Global Palettes - Export and import a .pal file through the palette editor with the #lm{expsha} and #lm{impsha} buttons.
  • Global Exanimation - Use the two buttons in the Global Exanimation editor labeled "Copy All Slots" and "Paste All Slots".

Section 2. Third Party Tools
Now that Lunar Magic is out of the way, it's time to deal with external stuff. For now, let's work with just the major tools: GPS (blocks), AddMusicK (music), Spritetool/Pixi/Giepy (sprites), and UberASM Tool (per-level code). Since the frameworks behind these are considered to be bug free, the only issues that can come up is from the interaction of your actual resources, so it's a good idea to get them out of the way first. Plus, you most likely still have all the resources for these tools, making them relatively easy to reinsert.

Thankfully, assuming you do still have all the resources from these tools, all you really have to do is reapply them as normal. Once this is done, it would be a good idea to do a quick test run of your hack (particularly anywhere that you saw break in your old ROM) to make sure it's not something there that's messing up (for instance, an UberASM code which doesn't correctly handle a certain custom sprite).

If you have trouble reaching some of these places due to not having a major patch applied, there's a few debug codes you can use to speed up the process. $00CC84 will allow you to zoom around the level by pressing L plus A twice, while the two codes around $00A25B will let you beat any level immediately by Start+Selecting out of it (with the secret exit activated by holding A at the same time). Lastly, the code at $049291 will let you freely walk across paths on the overworld, although if you want to take it a step further I also wrote a patch a while back to load every event along with it (just remember to restore your ROM back after testing!).

Section 3. Patches and Hex Edits
Now for the last step, which is also where debugging plays the largest part (see the last paragraph of the previous section for a quick list of cheats for getting to places in your hack faster). Basically, you just want to reinsert each of your old hack's patches one-by-one, and with each patch you apply, go to any places issues occurred in the old hack and check if that issue has reappeared. It's very important that you continually do this as you apply each patch; doing so will let you identify exactly which patch causes the issue, and in turn make it much easier for people to debug the cause. (at which point you can ask on the forum and possibly actually get a response)

But, you say, I don't have any of those patches anymore!
Unforunately, there's no way to simply extract patches from the old hack, so there's not really anything anyone can do to help there. Start by redownloading what you can remember patching, and then dedicate a playthrough of the hack for figuring out what you might have forgotten. In the future, always keep track of what patches you've applied; either keep a text document with a list of their names, or set aside a folder for holding all of them. For hex edits, I recommend compiling them into a single patch file as described here, so that you can just reapply them all in bulk later on. Be sure to use comments on them so you can identify what each one was, too, in case you find out one of those was causing your issues.

Once all this is done, one of two things will have happened:

1) The issue showed up again. If this happens, then whatever patch you had just applied is the root cause; generally this is either an issue with the patch itself, or a conflict with another patch you applied. If you don't know how to debug a solution for this on your own, ask in the forum; now that you know the actual cause, you might actually get someone to help. In order to make things easier on the person helping, try taking a clean ROM and applying as few patches/tools as you can to recreate the issue. Usually it's a conflict of two specific patches, so if you can figure out what the second patch was, it will help a lot.

2) The issue magically resolves itself. In which case, good enough! Most likely there was something you applied or changed incorrectly and then forgot about, so you don't have to worry about it now.
Thanks for this guide, it's really useful despite the fact it's simple and short. The only thing I noticed is related to title screen: you need to re-record the Mario's movement again when porting your rom (unless you use the no movement in title screen patch or something, of course)

Also, a question:

I have known cases where changing the order of the resources (mostly ASM) when inserting can avoid crashes/breaks, is there a specific reason why this happen? I was thinking it like... could, for example, patch A mess up with patch B when inserting A first and B later, but not when you patch B first and A later? (dumb example e.e)

By the way, can I translate this guide to spanish? I'm sure you don't mind about that but I wanted to ask you anyway, a short useful guide like this would be really useful for us.
Layout made by MaxodeX
2021 TRENO vibe check thread
im so happy this tutorail exists i was losing my mind after adding a patch and it messed up my whole rom, this worked like a dream thank you so much!!