Sonic Battle

A work-in-progress matching decompilation of Sonic Battle for Game Boy Advance. The initial target is the USA Rev. 0 release (BSBE78).

This repository contains no game binaries or assets. You must provide your own legally obtained copy of the game.

Setup

Requirements: Python 3.10+, Ninja, an ARM GNU binutils installation, and a copy of the USA Rev. 0 ROM. Build the pinned matching compiler with tools/setup_agbcc.sh before working on C translation units.

The C++ fallback additionally needs a 32-bit host C development environment (gcc-multilib on Ubuntu), curl, tar, and patch. Run tools/setup_gcc_cpp.sh after the agbcc setup. It builds the EGCS 1.1.2 C++ frontend with the pinned compiler's complete Thumb ELF code generator; downloaded source and build products stay under ignored tools/gcc_cpp/. This is a reconstruction toolchain, not a claim that the retail game used this exact compiler or C++ for every game unit.

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
tools/setup_agbcc.sh
tools/setup_gcc_cpp.sh
cp "/path/to/Sonic Battle.gba" rom/baserom.gba
.venv/bin/python configure.py
ninja
sha1sum -c config/BSBE78/build.sha1
python tools/check_unit_bytes.py main/unknown_08020134
python tools/check_unit_bytes.py main/unknown_08018444
python tools/check_unit_bytes.py main/unknown_0801F080

The required ROM SHA-1 is 8cf4fbbe73f6b1907ab9997caab4c4e7d9708937.

objdiff.json is generated by configure.py; open the repository root in objdiff after configuration. Unresolved game code has symbol-bearing target functions and a null base, so it counts honestly as unmatched code. Confirmed runtime-library translation units are separated; unresolved game TU boundaries remain grouped rather than guessed. Non-code ROM ranges are also present as unmatched data categories for decomp.dev reporting.

Compiler

The initial matching-compiler candidate is agbcc (GCC 2.95.1 for ARM/Thumb), consistent with related GBA Sonic titles. Compiler identity and per-file flags must still be established from Sonic Battle's emitted-code evidence before a unit is marked matching.

Progress

The progress badges and generated objdiff report are authoritative; percentages are not copied into prose because they become stale. Progress covers the complete 16 MiB ROM and is separated into game, SDK, runtime, embedded-payload, read-only-data, and asset categories. Unresolved regions count as unmatched rather than disappearing from the denominator.

The reconstructed runtime library is complete. Matching SDK work includes all 15 linked libagbsyscall veneers and the verified Nintendo communication translation units. Every unit marked complete must match all of its owned code, alignment, literal-pool, and data sections byte-for-byte.

CI regenerates and validates the objdiff report on every trusted pull request, verifies the rebuilt ROM SHA-1, checks the embedded-payload and function maps, and uploads the report as BSBE78_report for decomp.dev. A manually supplied, locally verified report is published as BSBE78_report-local, retaining the version/report prefix that decomp.dev discovers.

The main executable code ends at ROM offset 0x4B718. See docs/binary-analysis.md for the current evidence and boundary map. The optional mGBA/GDB workflow supports frame-stepped behavioral correlation without placing ROM data or runtime captures in the repository.

Legal

See LEGAL.md. This project does not accept ROMs, extracted assembly, game assets, leaked source code, or links to any of those materials.