Start here

Install & play

Get the right ROM, apply the English + quality-of-life patch, and set up an emulator. Takes about five minutes.

Read this first: which ROM to patch

The patch only works on the Chinese hack itself, the "bugfix 2" build of Hyper Emerald: Lost Artifacts v5.7. It does not work on vanilla Pokémon Emerald (USA), on other Hyper Emerald versions (v5.5, v5.6, v5.7 without bugfix, bugfix 1), or on the older community English translation. Start from the untouched Chinese ROM.

What you need

Base ROM: Hyper EMR LA v5.7 bugfix 2.gba (the hack's own release; game code BPEE)
Size: 33,554,432 bytes (32 MB, twice the size of vanilla Emerald)
SHA-1: f785bed9d9e82e8da13ea4a5ad747e3ea4ec7ba9
Patch: release/hyper-emerald-en-qol.hpatch from the GitHub repository
Tool: Python 3 (no extra packages) to run tools/romdiff.py
Result: SHA-1 fa19d312ce155e30f31dc1461f21027c54d05405; the tool verifies this for you

Check your file's hash before patching:

# Windows
certutil -hashfile "Hyper EMR LA v5.7 bugfix 2.gba" SHA1

# Linux / macOS
sha1sum "Hyper EMR LA v5.7 bugfix 2.gba"

Apply the patch

Download the repository Use "Code → Download ZIP" on GitHub, or clone it. You need tools/romdiff.py and release/hyper-emerald-en-qol.hpatch.
Run the patcher
```
python tools/romdiff.py apply "Hyper EMR LA v5.7 bugfix 2.gba" release/hyper-emerald-en-qol.hpatch "Hyper Emerald v5.7 EN+QoL.gba"
```
The tool refuses to run on the wrong original ("this is not the expected original ROM") and checks the output's checksum when it finishes.
Play Load the new .gba in mGBA, RetroArch (mGBA core), or any GBA emulator. See the platform notes below.

Emulator setup

PC (mGBA or RetroArch)

mGBA is the reference emulator; everything in the patch was tested on it. Any recent build works.
RetroArch: use the mGBA core. Other GBA cores generally work too, but the optional cheat file is written for mGBA.
The hack runs at normal GBA speed; fast-forward is safe and does not break scripted events.

Android handhelds

RetroArch with the mGBA core, or standalone mGBA, both run the hack well on low-end chips.
Put the ROM and its .sav in the same folder with the same base name.

Nintendo Switch (homebrew mGBA)

mGBA 0.10.x for Switch runs the hack. Copy the ROM to your SD card and keep the file name stable so the save is picked up.
Set savegamePath in /mGBA/config.ini if you want several ROM builds to share one save folder.

Saves and save states

Your old save keeps working

Battery saves (.sav) transfer between the original Chinese hack, the older translation-only builds and this build in either direction. The patch never touches code that reads or writes the save; the new features keep their state in bytes the game never used.

Emulators match saves by ROM file name. Either name the new ROM exactly like the old one, or rename the .sav to match the new ROM.
Save states (.ss0, .state) do not transfer between ROM builds. Do an in-game save before switching ROMs, then load the battery save.
Keep a copy of your .sav before trying cheats or a new build. It is a 128 KB file; backups are cheap.

Optional cheats

The repository ships one cheat: it pins your active Pokémon's Attack, Sp. Atk and Speed to 9999 in battle (a one-hit-KO helper for grinding). It is a RAM code, so it changes nothing in the ROM or your save.

mGBA: copy cheats/OHKO.cheats next to the ROM and rename it to <rom name>.cheats. mGBA loads it automatically; toggle it in Tools → Cheats.
RetroArch: put cheats/Hyper Emerald v5.7.cht in the core's cheat folder and enable it from Quick Menu → Cheats.

Do not use HP-lock or "infinite HP" codes

Codes that pin the foe's HP make it impossible to faint them, because the game's faint check runs a few frames after HP reaches zero. The shipped cheat pins stats instead, which is safe.

Rebuilding the patch yourself

Every feature is a standalone Python patcher that checks the exact bytes it expects before writing. The repository README lists the order; you need keystone-engine, capstone and pillow. Most players never need this.