arcade-js is an experiment in using an agentic harness to decompile ROM machine code.

A MAME ROM is a good candidate for porting — you can run it perfectly and capture its state. It is also a challenge — blind machine code running on odd hardware.

To get from machine code to readable JavaScript, we go through several stages:

1) Disassembly — pull the raw bytes apart into instructions and data.

2) Translation — rewrite it one instruction at a time into JavaScript that's provably identical to the original. We call this "assembly-JavaScript": it's JavaScript, but its shape is the assembly's.

3) State testing — run the assembly-JavaScript next to MAME and check that every register, every byte of memory, and the cycle count all track it. Not bit-perfect (real hardware has a CPU-vs-video-beam race we don't chase, etc.) but close enough to catch errors.

4) Decompilation — rewrite that assembly-JavaScript into real, idiomatic JavaScript.

5) Pixel testing — the idiomatic code no longer tracks registers or cycles, so we check the only thing that ultimately matters: the output.

6) Clarification — the surprise, where an LLM reasons about the code and its behavior to create human-readable JavaScript.

We point to two good examples of the technique: Donkey Kong (1981), because everyone has heard of it; and The Pit (1982), because no one has.

https://github.com/qarl/arcade-js/blob/main/games/dkong/idio...

https://github.com/qarl/arcade-js/blob/main/games/thepit/idi...

Note: the repo does not hold the original ROMs (which contain copyrighted artwork). If you want to actually play the games, you must provide your own.