Getting started

This patch is a work in progress and is not finished. It is playable from end to end, but see What is missing before you judge it.

What you need first

A dump of the cartridge. Nothing here distributes one — not the original and not the translated one. What is published is a difference file: on its own it does not run.

The dump has to be this exact one:

size	32,768 bytes
sha256	24cb5bda5f55dcd5ab1343fb61ebac67e8c292f9714ee7a492431e33188b9b40

Any other dump of the same game may well work, but nothing here is checked against it, and make will stop before doing anything.

The short way: apply the IPS

Take parche/mahjong_en.ips and apply it to your dump with any IPS tool. That is all. The result is a 32,768-byte ROM you can run on an emulator or write to a flashcart, with sha256 5613f6b450c78113f3ae31079e54be2e26b31023522b3b14807eae6b99772e07.

If your ROM comes out with a different hash, the dump you started from was not the one above.

The long way: build it yourself

Worth doing if you want to change the wording, or just to see that the patch is what it says it is.

You need pasmo and Python 3. For the screenshots you also need openMSX and Pillow.

cp /wherever/your.rom mahjong.rom
make comprueba   # is this the right dump?
make             # listing, verify, sanity, the patch and the tests

make runs the whole chain and ends green or it does not end:

  ensamblado : 32768 bytes  24cb5bda...188b9b40
  original   : 32768 bytes  24cb5bda...188b9b40
OK: reproducible byte a byte
...
ROM modificada: 12103 bytes cambiados dentro de 46 bloques, 0 fuera
OK: fuera de los bloques sustituidos, la ROM es identica a la original
...
original + parche : 32768 bytes  5613f6b4...99772e07
modificada        : 32768 bytes  5613f6b4...99772e07
OK: original + parche = modificada, byte a byte

Read the middle line. 0 fuera means the build changed nothing outside the 46 blocks it declared it would change. That is the guarantee that a translation patch has not quietly moved something else.

The other targets

make parche      # just build work/mahjong_en.rom and the IPS
make juega_en    # run the translated ROM in openMSX
make capturas    # rebuild every screenshot on this website
make capturas_jp # the same for the original cartridge, to compare
make pantallas   # both, and check no invisible furniture lit up
make test        # the tests

make pantallas is the one that earns its keep — see the finding it exists for. It needs openMSX because it needs to see both cartridges running.

Where the listing comes from

src/mahjong.asm is here because parchea.py splices the translated blocks into a copy of it. The commented disassembly it comes from — every one of the 32,768 bytes explained, none unidentified — is a separate repository: KonamisMahjongDojo-disassembly. If you want to understand the cartridge rather than the patch, start there.