把一款 32X 遊戲翻譯成原生程式：手把手製作流程Turning a 32X game into a native program, step by step

An emulator is like a live interpreter: each time the game runs a machine instruction, the emulator reads it and carries it out, one at a time, tens of millions of times a second.

A recompilation is like translating the whole book in advance: before you play, the game's machine code is translated piece by piece into C++, which your computer's own compiler turns into a native program. While you play, nothing has to be read and understood again.

But a game is more than code. It talks to a video chip, sound chips, timers and interrupts. That hardware behaviour can't be translated; it has to be reproduced by a separate layer. So a recompiled port is two halves: the translated game code, and a hardware compatibility layer.

A recompilation can be public only if it ships nothing from the game itself. Decide this on day one, because it shapes how every tool is designed.

• Players supply their own legally obtained ROM. The program checks its SHA-1 (here 0c2fff7b…7ced7) and won't use the translated code with anything else.
• The ROM, the code generated from it (generated/) and screenshots are all in .gitignore. They never go into git or any cloud service.
• CI (the automatic tests on GitHub) never has the game, so it tests what doesn't need it: instruction semantics, individual components. Tests that need the game run on the developer's own machine.
• No 32X BIOS is needed: the boot sequence is reproduced in code (HLE), so players don't have to find a BIOS file.

Before translating, learn the grammar of the original. The 32X plugs into a Mega Drive, so a 32X game has four processors running at once, talking through shared registers:

The output of this step is an architecture document: each processor's clock, the memory map (which addresses are ROM, RAM, hardware registers), and which hardware this particular game actually uses. This project's ARCHITECTURE.md started that way, and every claim in it is marked verified or still to verify.

It sounds like a detour, but it's the most important decision in the project: before writing the translator, write an interpreter that runs instructions one at a time (a small emulator). One each for the 68000, the SH-2 and the Z80.

It can be slow. Its job is to be the answer key: later, the translated code has to produce exactly the same result, every frame.

The key trick: what each instruction does is written once, in shared semantics headers (m68k_ops.h, sh2_ops.h). The interpreter uses them, and the generated C++ calls the very same code, so the two can't drift apart.

A ROM is a long run of numbers mixing code, graphics, sound and text. The translator can only translate code, so first you draw a map:

• Start from the known entry points (the reset address, interrupt vectors), follow every jump and call, and mark all reachable code (a control-flow graph, a function list).
• When a jump goes through a table of addresses, decode the table.
• Some entry points can't be found statically, so play the game and record which addresses run (a coverage file holding only addresses, no ROM content), then feed that back to the analyzer.

The recompiler turns each block on the map into a piece of C++. Every generated line carries the original assembly as a comment, and you can set breakpoints in it.

Why C++ and not lower-level LLVM IR? Every platform already has a C++ compiler (MSVC, GCC, Clang, the Android NDK, Xcode), so one translation builds everywhere.

The translated code reads and writes hardware registers, and the compatibility layer answers: both video chips (composited line by line), DMA, timers, the divider, the COMM registers, the FM/PSG/PWM sound, and the boot sequence.

The part that needs the most thought is time. On the real console the four processors run at once; in a program they take turns. This project cuts each scanline into 4 fixed slices and runs 68000 → Z80 → master SH-2 → slave SH-2 in each. The whole model is deterministic: the same input always gives the same result, however fast the computer is.

This step answers "how do you know the translation is right?". Run two machines on the same play session: one on the native translated code, one on the step-03 interpreter. At the end of every frame, compare everything: each CPU's registers and cycle counts, all of RAM, video memory, the 32X frame buffer, the output picture. If a single byte differs, the test fails and says which frame and where.

• Boot to level: 3,200 frames (boot → title → menus → into a level → run, jump, collect rings), identical every frame.
• 33 random-input runs (the sweep): different levels, characters, widescreen on and off, random buttons; every one must be bit-identical. It is re-run for every release.
• On another CPU too: the same comparison on an Apple M1 (ARM) is identical as well.

The frontend uses SDL3 for the window, fullscreen, scaling, keyboard/gamepad/touch, sound output and settings. There's also a windowless build, chaotix_headless, made for tests and measurement: it presses buttons from a script, saves screenshots, writes WAV files and reports how long each CPU took.

A good habit: produce sound and pictures from emulated time, and never let the computer's audio device decide how fast the game runs.

A port earns its keep with things the original can't do. This one added real widescreen, time attack, achievements, cheats, save states, rewind, netplay, character and music mods and more. The rule: never quietly break the original game.

Take widescreen: the 4:3 picture isn't stretched; the game's own level renderer is extended to draw real tiles, objects and sprites at the sides. A test guarantees the centre 320 pixels stay identical to the original.

Another example: time attack doesn't invent its own level picker. It uses a STAGE SELECT that is in the game but never reachable in the shipped version, calling its own "start level" routine, so a level starts exactly as the game itself would start it.

Because the output is C++, each platform uses its own compiler. Each still has its own traps, and a platform only counts once it has really run there:

A player said it stuttered on slow phones (issue #62). The goal: be faster than the PicoDrive emulator on the same phone, without giving up accuracy; no frame-skipping shortcuts.

The method was the same every time: measure 3,000 frames with the headless build on the real phone, find the biggest cost, change it, prove with lockstep that behaviour didn't change, then measure again.

One speed-up in detail: in a level the game writes about 370 times a frame right next to some SH-2 code. Each write used to make every translated function re-check itself: 4,049,824 checks in 3,000 frames. After each function was made to re-check only when its own bytes actually changed, the same 3,000 frames needed 75.

This loop is a rule set by the project owner, and every issue goes through it. Here is a complete real case from the same day this page was written.

1. Look at the evidence: the comment was under a gameplay video. Extract its audio and line it up with the emulated output. All four PWM tracks (the 32X's sample channel) were playing: nothing was missing.
2. Find a reference: a program can't be its own yardstick. Download PicoDrive's PC core and write a small windowless host that runs the same ROM, presses the same buttons, enters the same level and saves the sound and frames.
3. Compare frame by frame: Mighty's running, jumping, rolling and spin dash were identical frame for frame, so the "Mighty animation" needed no change. In the sound, PicoDrive's bass drum was clearly louder.
4. Confirm in the source: read PicoDrive's sound code (read only, nothing copied) for each source's peak level: FM ±8191, PSG ±2304, PWM ±32768, the sum times 0.875. That matched the measured gap.
5. Fix: mix at those levels; the PSG noise channel turned out to be half as loud as it should be, and was fixed too.
6. Verify the same way: title music -23.3 dB vs PicoDrive -23.5 (was -31.2), level -20.2 vs -20.1, and the bass-drum band from 9.4 dB short to within 1 dB.
7. The fix exposed another problem: with the louder mix, muting the music popped louder. Trace the cause (PWM parked off-centre, the waveform cut in one sample), ease volume changes over 38 ms, and add a test that fails without the easing.
8. Release: 0.15.12, only after six platforms, every test, 33 lockstep runs, the Mac and the real phone all passed.

Every release goes through this list; if any item fails, it doesn't ship:

The line links above are pinned to commit 1d0d519 (main at the 0.15.12 release), so they don't drift as the code changes. For the latest code: