GT Advance 3 decompilation

Reconstruction of GT Advance 3: Pro Concept Racing (GBA, MTO/THQ). The goal is readable game source and cataloged data that build a ROM byte-identical to the US reference.

Project pages:

• GT Advance 3 on recomp.fyi
• GT Advance 3 on ByteMatch

Status

Two separate questions have two separate answers:

1. Does the ROM build byte-identical from this repository? Yes. The full 8 MiB C/ASM + registered-data link matches the US reference (make full-rom-match).
2. How much of the game is decompiled to C? Under half. Many functions in src/ are still assembly: naked functions whose body is an __asm__ listing, or C with real instructions spliced in through asm(). They link and match, but only the compiler's own output counts as decompiled, the way other decompilation projects count INCLUDE_ASM/NAKED placeholders.

<!-- progress:start (generated by tools/update_progress.py) -->

Decompiled to C: 141,460 / 188,760 executable bytes (74.94%), 1,551 / 1,676 functions (92.54%).

Source form	Functions	Bytes	Share of code	Counts as decompiled
Plain C	877	44,418	23.53%	yes
C with matching tricks (empty barriers, register pins, directives)	674	97,042	51.41%	yes
C with instructions spliced in through asm()	4	200	0.11%	no
Assembly in C files (naked or asm-dominated bodies)	121	46,476	24.62%	no
Identified function not yet selected for C	0	0	0.00%	no
Non-function bytes (header, startup, pools)	-	624	0.33%	no

<!-- progress:end -->

tools/source_quality.py assigns each function its source form and docs/data/source_quality.json records the result. "Matching tricks" are empty asm volatile("") barriers, register x __asm__("rN") pins, and assembler directives. They steer the compiler without emitting instructions, so those functions count as decompiled, but they are listed for cleanup. Run python3 tools/source_quality.py --list asm (or partial) for the worklist, largest functions first.

The reference build (make) produces a byte-identical ROM from reconstructed assembly and registered data generators. Maintained C is C89 for the pinned compiler and is compiled directly, with no C99-to-C89 rewrite step; tools/c89_check.py gates every translation unit. make matching-ready compiles the C corpus with pinned old_agbcc and verifies the selected functions in an independent executable slice. Byte matching measures emitted bytes, not source readability. The integrated data regions cover all cataloged data through content end 0x7B04C4 (7,873,388 non-padding bytes). Some compressed or raw payloads are preserved verbatim or extracted from the reference ROM, so byte reproduction is not the same as semantic asset decoding. See build status and completion criteria for the separate decompilation, link, data, and runtime measures.

Repository map

Path	Contents
src/, include/	Reconstructed C and hardware contracts.
asm/	Reference assembly, ROM layout, and the private data-tail input.
Build verification	Verification commands, ownership, and byte-matching constraints.
Compiler documentation	Compiler configuration and runtime provenance.
ROM map	Memory layout and data inventories.
docs/findings/	Compiler behavior and worked matching constraints.
Tools	Build, analysis, extraction, and emulator utilities.
baserom.sha256	Pinned US reference-ROM hash.

Setup and verification

Use Python 3.11 or newer. Supply your own US ROM as baserom.gba; it is ignored by Git. The build needs GNU Make, Git, a host C/C++ compiler, Clang, ARM GCC/binutils (arm-none-eabi), shasum, and Python pyelftools.

On Ubuntu 24.04:

sudo apt-get update
sudo apt-get install build-essential git clang python3 python3-venv \
    binutils-arm-none-eabi gcc-arm-none-eabi libnewlib-arm-none-eabi libdigest-sha-perl

The Ubuntu ARM compiler package provides the arm-none-eabi assembler, linker, and object tools used by the matching build.

On macOS, install Apple's Command Line Tools and Homebrew, then install Python and the ARM toolchain:

xcode-select --install  # once, if Command Line Tools are not already installed
brew install python@3.11
brew install --cask gcc-arm-embedded

Use python3.11 below if python3 --version still reports an older Python. Apple's Command Line Tools provide Git, Make, and Clang; macOS includes shasum.

From the repository root, create an isolated Python environment and provision the matching compiler from the pinned pret/agbcc revision:

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -r requirements.txt
make toolchain
make full-rom-match
make fast-check
make ci-check
make doctor            # read-only environment/ROM report

make full-rom-match includes matching-ready, the reference build, and the whole-image hybrid link/hash comparison. make alone runs the reference build and hash verification. make progress runs the full matching gate and refreshes the progress snapshot when build inputs change; see CONTRIBUTING.md.

make toolchain builds old_agbcc, the comparison agbcc binary, and their headers under build/toolchains/agbcc/. The reference assembly build does not require these compilers. See the tool index for details. Install Python dependencies in a virtual environment if required by your Python installation. Pillow is optional for asset PNG export and treemaps; emulator bindings are provisioned separately by tools/build_mgba_python.sh.

The runtime-provenance check also uses the vendored GCC 2.95.3 runtime source. Its original license and notices remain separate from this project's license.

make clean removes build outputs, including the auxiliary build-code/, build-slice/, build-c/, and build-s/ trees, while preserving build/toolchains/. make distclean removes those outputs and the compiler tree. Do not commit the private ROM, extracted assets, or generated binaries. The reference-build hash and executable-slice match do not establish a complete independent C ROM.

Contributing and CI

See CONTRIBUTING.md for contribution and verification steps. Hosted CI runs lightweight, ROM-free checks. Progress reporting documents the locally verified objdiff progress snapshot. objdiff.json provides per-function target/C comparisons with automatic rebuilds; refresh its inventory with make objdiff-config. See the optional viewer setup.

License

The reconstruction, tooling, and documentation are dedicated to the public domain under CC0 1.0 Universal. This does not apply to the original game or third-party material. See NOTICE for ownership and license boundaries. No complete ROM image or extracted asset files are distributed here. The cartridge-header constants and Nintendo boot logo are excluded from CC0; see NOTICE.