Mother3Recomp — MOTHER 3, Recompiled

Static recompilation of MOTHER 3 (Game Boy Advance) to native PC, built on the gbarecomp framework. Forked from EmeraldRecomp; the Emerald sources and variant still in this tree are inherited scaffolding.

Goals: a low-latency native build (battle combos are timed to the music), a widescreen presentation, and a moddable game through function-level hooks.

What "static recompilation" means here

The ROM's ARM7TDMI machine code is statically translated to native C — every function the game runs becomes a generated C function, and the GBA BIOS is recompiled and executed too. The gbarecomp runtime models the rest of the console: PPU, APU + sound engine, DMA, timers, save chip and I/O.

Any code path the static recompiler missed runs through the built-in interpreter the first time it's hit, is JIT-compiled to native where possible, and is cached per ROM in recomp_cache/<rom-sha1>/. Misses are also written to recomp_master_misses_<code>.toml.frag for review.

Only symbol metadata from the Kurausukun/mother3 decompilation (function names, addresses, sizes) enters the build. The ROM is never redistributed; supply your own legally-dumped copy.

Targets

Target	Game	ROM SHA-1	Debug port
Mother3Recomp	MOTHER 3 (Japan)	4f0f493e12c2a8c61b2d809af03f7abf87a85776	19893
Mother3RecompEN	MOTHER 3 (English fan patch)	306fb8874533b0fd0796208faa8bed2db4ae77fb	19894

The runtime refuses to launch on an unrecognized ROM.

ROM locations: variants/mother3/roms/mother3_jpn.gba and variants/mother3en/roms/mother3_en.gba (gitignored).

Controls

Keyboard and controller bindings are in keybinds.ini. Save states: Shift+F1–F9 save to a slot, F1–F9 load it.

Audio latency

Audio output uses a small cushion by default so the music stays close to the game's timing clock. Tune with environment variables:

Variable	Default	Meaning
GBARECOMP_AUDIO_TARGET_MS	32	Steady-state buffer fill (12–250 ms)
GBARECOMP_AUDIO_SAMPLES	512	Device callback size in frames (128–4096)
GBARECOMP_AUDIO_PREROLL_MS	0	Extra startup cushion (0 = start at target)
GBARECOMP_AUDIO_MAX_MS	target+40	Latency ceiling; a backlog above it is skipped back to target (0 = off)
GBARECOMP_AUDIO_PROBE	off	1 logs underruns and buffer fill every 2 s

If audio crackles, raise GBARECOMP_AUDIO_TARGET_MS (try 40–48). The previous defaults were 60 / 1024 / 250.

Building from source

Prerequisites (Windows): MSYS2 with the mingw64 toolchain, CMake 3.20+, Ninja, and SDL2 (mingw64 package). Run builds from PowerShell with mingw64 on PATH.

git clone --recurse-submodules <this repo> Mother3Recomp
cd Mother3Recomp
cmake -S . -B build -G Ninja
cmake --build build --target Mother3RecompEN     # or Mother3Recomp

Regenerating the recompiled C (only after recompiler or config changes):

cd variants/mother3en
gba_recompile --rom roms/mother3_en.gba \
    --config game.toml \
    --config symbols/mother3_jpn.toml \
    --symbols symbols/imported_symbols.tsv \
    --data-symbols symbols/imported_data_symbols.tsv \
    --out generated --max-functions 65536

--config order matters: game.toml is the base and wins every conflict (see gbarecomp/docs/SYMBOL_OVERLAY.md).

gba_recompile is built from the gbarecomp submodule. The generated corpus is large — expect a multi-minute compile.

License

PolyForm Noncommercial 1.0.0 — see LICENSE. Third-party components retain their own licenses.

Legal

This project contains no copyrighted ROM data, no Nintendo BIOS, and no decomp source — only recompiler/runtime code and symbol metadata. You must supply your own legally-dumped ROM and BIOS. MOTHER 3 is a trademark of Nintendo / HAL Laboratory / Shigesato Itoi; this is an unaffiliated, non-commercial preservation and research project.