0.4.6

This release adds ROM patches as a way to mod graphics and data.

• ROM patches (Issue #35): put .ips or .bps files in Mods/Patches in the user data folder. When the game starts they are applied, in name order, to the ROM in memory.

  • Graphics, palette, text and other data hacks made with ROM hacking tools work without rebuilding anything.
  • Your ROM file is never changed, and removing a patch undoes it.
  • BPS checks that it was made for this ROM and that it isn't damaged. The log says which patches were applied and why any were skipped.
  • The game checks its header checksum at boot and stops at a blank screen if it is wrong. If a patch leaves the checksum wrong, it is fixed after patching.
  • Patches that change the game's code work too, but that code runs in the slower interpreter. The recompiled code was made from the unpatched ROM, so it is never silently used instead of patched code:
    • Recompiled SH-2 code is checked against the unpatched ROM, so a routine a patch changed is interpreted.
    • A patch over the 68K's code (which runs straight from ROM) switches the 68K to the interpreter.

  Details: docs/ROM_PATCHES.md. Replacing sprites with loose image files, as the issue also suggests, is not done yet.

Thanks to @datadrivezz for the request.

Validation:

• Windows: all 30 CTest cases pass. One run of the full suite had a failure in rom_startup; it passed when rerun alone and in a second full run.
• Linux: all 27 Linux CTest cases pass, rom_patches included.
• New tests: unit tests for IPS, BPS and the patched ROM, and rom_patches, which uses the real ROM. It checks that a data patch keeps the code recompiled, that a patch over 68K code switches it to the interpreter, and that a patch over SH-2 code fails its validation. In all three cases the result is bit-identical to the interpreter.
• Packages: the packaged Windows and Linux builds pass the startup tests.
• Android: the APKs have not been tested on a device for this release.

Downloads: the Windows x64 zip, the Linux x64 tar.gz, and two Android APKs: arm64-v8a/x86_64 (the usual one) and armeabi-v7a (32-bit ARM). Both APKs use version code 19 and the same signing certificate as 0.4.5, so they update in place.

You must supply your own Knuckles' Chaotix (Japan, USA) ROM. No ROM image or game assets are included.