How to play a Pokémon ROM hack: patching explained in plain English

A ROM hack doesn’t run on its own. It’s a patch file, and you apply it to your own clean copy of the original game before anything boots. You don’t need to know what a checksum is yet. I’ll get to it.

How to patch a ROM hack, step by step

1. Read the hack’s readme and write down the exact base game it wants, plus the hash (CRC32 or MD5).
2. Dump a clean copy of that game from your own cartridge.
3. Open Rom Patcher JS in your browser and load your base file.
4. Check the hash it shows against the readme. If it doesn’t match, stop here.
5. Load the hack’s patch file and apply it.
6. Save the output with a new name, and keep your clean base untouched.
7. Open the patched file in your emulator, or copy it to your flashcart, and play.

If a step goes wrong, the fix is further down. My first patch took me an hour, and now it takes me two minutes.

What a ROM hack actually is

A ROM hack is a retail game someone changed. “ROM” is the data from the cartridge. The hack is everything the author changed, from new maps and scripts to a whole new battle engine.

Pokémon Unbound is FireRed with a new region built on top. Booting it the first time and not recognizing a single town is a feeling I still chase. Pokémon SoulGold is Emerald rebuilt on the pokeemerald-expansion decomp, with a bigger Johto where Hoenn used to be.

Authors never ship the changed game. They ship the difference between their version and the original, and you bring the original. That way their work can go anywhere, and Nintendo’s code stays on your cartridge.

What is inside a patch file

A patch only holds the bytes that changed, plus enough info to put them in the right place. There’s no playable game in it. You have to bring your own copy of the base.

That’s why patches are small. I didn’t believe a whole new region could fit in a file that size until I saw it boot. Emerald is 16 MB, and its patches are a fraction of that, because most of the game is left alone.

Hacks built from decompiled source (pokeemerald, pokefirered, pokecrystal) get compiled into a full game by the author. They still release it as a patch against the retail game, so it works the same way for you.

IPS vs UPS vs BPS vs xdelta

Almost every Pokémon hack uses one of four formats. The difference you’ll feel is whether the format can tell you that you used the wrong base.

Format	Size limit	Checks your base?	What happens if your base is wrong	Hacks that use it
IPS	About 16 MB (24-bit offsets)	No	A wrong base produces a glitched or crashing game instead of an error	Rocket Edition, Light Platinum, Emerald Kaizo, Emerald Seaglass
UPS	None	Yes (CRC32 of source, output and patch)	The patcher refuses a wrong base. Applying the same patch twice reverses it	Unbound, Heart & Soul, Inclement Emerald, Run & Bun, Odyssey, Adventure Red Chapter
BPS	None	Yes (CRC32)	Handles moved data, so files are smaller; carries metadata; not reversible	Lazarus
xdelta (VCDiff)	None	Yes (checksum validation)	General-purpose delta format; the standard for DS hacks	Sacred Gold / Storm Silver, Renegade Platinum

UPS, BPS and xdelta are the friendly ones. A checksum error takes ten seconds to fix. An IPS patch on the wrong base can look fine for an hour and then crash in the first gym. That’s the kind of hour you only lose once before you start checking hashes.

Why the base ROM revision matters

A patch is built for one exact file, down to the byte. Use a different region, a different revision, or a file you already patched, and the changes land in the wrong places.

These are the ones that catch people out. I once spent a whole evening blaming the patcher before I checked my revision.

• FireRed hacks want FireRed (U) v1.0, the “1636 Squirrels” dump. That goes for Radical Red, Rocket Edition, Odyssey, Liquid Crystal and Adventure Red Chapter. Rocket Edition won’t work on any other version. If a FireRed patch fails, you probably have Revision 1.1 (Rev 1).
• Emerald hacks use the one US/EU dump. No-Intro lists “Pokemon - Emerald Version (USA, Europe)” at 16,777,216 bytes, CRC32 1F1C08FB, MD5 605b89b67018abcea91e693a4dd25be3, SHA-1 f3ae088181bf583e55daf962a92bb46f4f1d07b7. Run & Bun calls the same file the “1986 Trash Man” dump. You may see a different MD5 quoted for Trash Man somewhere. Go with the No-Intro hashes unless the hack’s readme says otherwise.
• Ruby: Light Platinum has separate patches for Ruby (U) v1.0 and v1.1, so find out which one you have.
• Platinum: Renegade Platinum has different patches for the “3541” and “4997” US dumps.
• HeartGold / SoulSilver: Sacred Gold and Storm Silver need the American version. The anti-piracy fix is already in the patch.
• Crystal (GBC): Polished Crystal, Crystal Clear and Prism all use the US Crystal.

How a patcher works

A patcher reads the patch and your clean base, then writes a third file: the hacked game. Your base stays untouched, so keep one clean copy and reuse it for every hack and every update. I keep mine in a folder named DO NOT TOUCH.

Use Rom Patcher JS. It’s Marc Robledo’s tool, and most hacks recommend it now, including Heart & Soul and Run & Bun. It runs in any modern browser, even on your phone. It handles IPS, UPS, APS, BPS, RUP, PPF, EBP, BSDiff and xdelta. It shows you the CRC32, MD5 and SHA-1 of your file before you apply anything, and it can strip headers from older files.

If you’d rather use something else, these each do one job:

• Floating IPS (Flips): IPS and BPS
• NUPS or tsukuyomi: UPS on Windows
• xdelta UI or Delta Patcher: the DS hacks

They all give you the same result.

Some hacks have their own patcher. Radical Red has an online one. Heart & Soul, Emerald Rogue and SoulGold send you to HackDex, which patches your own file in the browser and doesn’t host any game. I patched SoulGold that way. I loaded my Emerald file and took the result to my emulator. For Unbound, use NUPS or Rom Patcher JS to apply the UPS file to a FireRed 1.0 base.

Common errors and what they mean

“Checksum mismatch” or “wrong source file.” Your base isn’t the file the patch expects. It’s almost always FireRed 1.1 instead of 1.0, or a file you already patched. Check the hash and start again from a clean base.

The game boots but glitches, freezes, or shows garbage. Same problem, IPS version. IPS can’t check anything, so a wrong base goes through and breaks later. Patching an already-patched file does this too. Always patch a clean copy. I learned this one the slow way.

The emulator refuses the file. You probably didn’t extract the archive, or the extension is wrong. Make sure you’re opening the patched game, not the patch.

The in-game clock is stuck, or events never trigger. A lot of hacks need a real-time clock. Adventure Red Chapter Beta 15 needs an RTC fix on mGBA and won’t run on VBA-M at all. If Unbound’s date is stuck on Sunday, switch emulators.

Cheats corrupt the save. Decomp hacks move memory around, so GameShark codes for vanilla Emerald or FireRed write to the wrong places. They can corrupt your save, and Radical Red won’t take bug reports if you used cheats.

“Inaccurate emulator detected.” SoulGold checks your emulator and shows this screen if it isn’t supported. Switch to mGBA or one of the mobile mGBA builds it lists. Don’t send bug reports from an unsupported emulator, because they won’t get looked at.

Save compatibility across hack versions

To update a hack, follow these steps:

1. Make an in-game save. Save states often break between versions.
2. Patch a clean base with the new patch.
3. Rename your old save file to match the new game file.
4. Load the new game and check your save. I still hold my breath on this step every time.

Whether your save survives depends on what the author changed. Hacks on this site, by save compatibility:

• Compatible: Rocket Edition (all earlier betas), Sors (1.0 through 1.2 work in 1.3), Crystal Clear (saves always transfer), Gaia 3.0 to 3.2, Heart & Soul 1.x to 1.2.x, Radical Red from 2.0 on, SoulGold (always forward, never backward).
• Not compatible: Gaia 2.5 or earlier to 3.x, Inclement Emerald 1.0 to 2.0 and later, Heart & Soul pre-2.0 to 2.0 (new engine), Odyssey 4.0.3 to 4.1.x (bigger bag), Adventure Red Chapter between betas 11 and 14. Emerald Rogue saves have also corrupted going from 1.3.2a to 2.0.1a.

Hotfixes almost never break a save. Engine changes and storage changes (more PC boxes, a bigger bag) usually do. SoulGold’s 1.1 raised PC boxes from 16 to 19, and once you save on the new version you can’t go back.

Emulators and real hardware

If an emulator runs the original game, it can usually run the hack. What changes is accuracy and clock support.

Use mGBA on desktop. It’s also on 3DS, Switch, Wii and Vita. Radical Red, Odyssey, Lazarus and SoulGold all recommend it. It supports IPS, UPS and BPS and detects save types, though detection fails now and then. mGBA can also soft-patch, applying a patch with the same name as the base when it loads. I don’t rely on it. Patch properly, so your save file belongs to one clear game file. mGBA is my daily driver, and I wouldn’t switch.

VBA and VBA-M run Radical Red and Rocket Edition, but not Adventure Red Chapter Beta 15. For Unbound, avoid old VBA versions, No$GBA, Eclipse and JohnGBA. OpenEmu on macOS is fine for Radical Red but doesn’t soft-patch.

Android and iOS. For Radical Red, use myBoy or JohnGBA. It won’t run on PizzaBoy, Eclipse or Twilight Menu. For SoulGold, use Lemuroid or a mobile mGBA build. Lazarus and SoulGold both work on Delta on iOS. You can skip SoulGold’s accuracy screen there with Start, but then you’re on an emulator the author doesn’t support. On mobile, patch in your browser with Rom Patcher JS, then import the finished file.

DS hacks load in DeSmuME or melonDS like any other game. Sacred Gold and Storm Silver already include the anti-piracy fix, so there’s no extra step.

Real hardware. Radical Red, Lazarus and SoulGold all run on real hardware with a flashcart. Crystal Clear runs on a GBC flashcart with save and RTC support, and needs Goomba mode on a GBA flashcart. Sors has an extra patch for emulators and 3DS Virtual Console that struggle with it.

The legal side, briefly

Authors hand out patches instead of games because a patch has none of Nintendo’s code in it. Lazarus tells you to bring your own legal copy of Emerald. PokeCommunity bans sharing or naming sources for game files. Heart & Soul’s developers take no donations and say their GitHub is the only official place to get their patch.

The community standard is to dump the cartridge you own. It’s still a gray area. I dug my old cartridges out of a shoebox for exactly this reason. Publishers treat any unauthorised copy as infringement, and anti-circumvention law can apply to modern cartridges. Nintendo has enforced it too. Pokémon Prism got a cease-and-desist in December 2016, days before release, and the author complied.

Beyond Kanto hosts no game files or patches and takes no position on how you get a base game. It isn’t affiliated with Nintendo or The Pokémon Company, and nothing here is legal advice. Start with the author’s own thread or repository, read the readme for the exact base, and check the hash before you patch.

Still picking a hack? The best Pokémon ROM hacks sorts them by what you want, and the best GBA hacks covers GBA only. SoulGold setup questions are in the SoulGold FAQ.