A matching decompilation of Shining Soul II for the Game Boy Advance
(Europe, AU2P, En/Fr/De/Es/It): C source that compiles to the original ROM,
byte for byte.
| Question | Status | What is left | |
|---|---|---|---|
| Does all the code build from source and match? | Done. Every game function is matching C. The few routines that were hand-written assembly in the original stay as matching assembly. | Optional source cleanup: guide | |
| Do we know what each function does? | Done, first pass. Every game function has a display name with evidence. Names describe behaviour; many can still be made more meaningful. | Improve names: audit, guide | |
| Are graphics, sound, text and tables separated and described, or still raw copies of the ROM? | Done at format level. Sound, graphics, palettes, animations, maps, tilemaps, text and tables have a known, checked format. Left: about sixty small structures that are only listed, and names for most objects. | Name objects and fields: guide |
The ROM already rebuilds exactly, so nothing below can break the game: names and data descriptions only make the source readable and moddable. They are the long part of the work and the best place to help.
Three views. Click a tab to open it; the figure on each tab is its current progress.
Code: is it matching?
Each cell is one function (area = size in bytes):
| Colour | Meaning |
|---|---|
| 🟩 green | matching C or linked library code; separate totals are shown above the map |
| 🟢 light green | routines that were hand-written assembly in the original game (start-up, task scheduler, BIOS call stubs, sound mixer core); kept as matching assembly, complete |
| 🟨 yellow | compiling C draft; tracked large functions fill progressively by documented work milestones |
| ⬜ grey | no matching C, or unfinished tracked milestones; hover for the exact state |
The graphic shows recognized display names while preserving canonical symbols in
its tooltips. Partial yellow fill is a count of evidenced work milestones, not
matching bytes, semantic equivalence or an estimate of remaining time. Function
owners update their own docs/agents/function_work/sub_XXXXXXXX.json at checkpoints;
CI refreshes the map when those commits are integrated.
All code counts every code byte that builds from this repository and matches: matching C, linked library code and the original hand-written assembly. The historical matched + linked percentage excludes that assembly. Matching C counts only matching C bytes over all C module bytes; compiling drafts are reported separately. Identification is a separate source/evidence metric, not a decompilation or understanding percentage. See metric definitions and naming workflow.
Names: do we know what each function does?
Same map as the code view (one cell per function, area = size), coloured by
identification: green has a name confirmed with evidence or already present in
the source, yellow has a proposed name that nobody reviewed, grey has no name
yet. Names are display names in tools/config/function_names.json; canonical
sub_XXXXXXXX symbols never change, so naming cannot break the match.
To help: naming pipeline,
identification summary.
Each function in src/ carries its name and a short description as a comment
above it (generated from the catalog by tools/scripts/annotate_names.py).
For a port or a debugger the names are exported on every update:
symbol file (ADDRESS Name, loads in mGBA
and no$gba), C header (#define Name sub_XXXXXXXX) and a table with a coarse
subsystem tag per function (audio, video, link, save, map, combat...). The
name audit lists names that still describe shape
instead of purpose.
Data: is the 16 MB of data split and described?
About 16 MB of the ROM is data, not code. It always builds byte for byte; the question is how much of it the source describes instead of copying. One bar shows it: green is described (the figure other decompilation projects report as data progress), yellow is split into objects but still raw bytes, grey is not split yet.
| Level | Meaning | Example |
|---|---|---|
| 1. Split | the bytes belong to one labelled object with known start and end | "this is resource 12 of category 6", "this is string 404 of language 1" |
| 2. Described | the object's format is known: written out in source, or declared and decodable by the tools | song table, sound samples, pointer tables, palettes, tile sheets |
Described so far: the sound engine data (songs, tracks, samples); inside the
two resource archives the graphics, palettes, sprite animation records, area
maps and screen tilemaps; the text of the five languages (1,493 strings each);
and the tables whose element type the code declares.
tools/scripts/data_extract.py decodes graphics to PNG and text to .txt
from your own ROM. Two footnotes to the 100%: one block at the end of the ROM
is unused (nothing refers to it), and about sixty small structures (0.12% of
the data) are listed with their users but their layout is not written down yet. Described means the format is known and
checked; field and object names are separate, later work.
Object counts are a lower bound. To help: data pipeline.
CI regenerates the complete function/name inventory, identification summary, source call graph (JSON, DOT) and raw data inventory without a ROM. The graph records source observations and unresolved calls; it is not a complete runtime graph.
This project targets the European ROM only until further notice. Function naming is active again now that the code matches: see the naming pipeline and the identification method.
Start with the contributor quick start. On Windows, download the ROM-free toolkit into your own folder, extract it there and start with its bootstrap script. Each contributor and agent needs an independent checkout. The open work is naming functions, describing data and cleaning source; each guide says how to reserve a piece. Bring your own EU ROM; it is never included in the toolkit or uploaded to Git.
Public guides, progress labels and tables, commit messages, and pull-request text use English so contributors can coordinate across communities.
The ROM is not included. You need your own dump, saved as baserom.gba:
| File | SHA1 |
|---|---|
baserom.gba |
aa1288be9257337abdfe3034898cf6c7aa778fbc |
Requirements: binutils-arm-none-eabi gcc-arm-none-eabi make python3 git gcc (Linux/WSL) or MSYS2 UCRT64 on Windows
(see CONTRIBUTING.md).
sh tools/setup_tools.sh # agbcc, m2c, decomp-permuter-agbcc, asm-differ, objdiff (all inside tools/, git-ignored)
make -j$(nproc) compare # -> shiningsoul2_eu.gba: OK
make expected # snapshot of the matching objects (diff target for objdiff / asm-differ)
python3 tools/scripts/gen_objdiff.py && tools/objdiff/objdiff
make progress # regenerate docs/progress/*.svgAnyone can help: read CONTRIBUTING.md (setup, per-function workflow, compiler rules). AI agents: CLAUDE.md and docs/agents/.
| Path | Contents |
|---|---|
src/*.c |
C modules. Not yet decompiled functions are pulled in with INCLUDE_ASM(...) |
asm/nonmatchings/<module>/<func>.s |
one assembly file per not yet decompiled function |
asm/crt0.s, asm/*.s |
hand written assembly (start up, m4a core, libgcc) |
data/rodata.s |
ROM data, taken from baserom.gba with .incbin |
include/ |
headers |
tools/config/functions.cfg |
function list (address, name) |
tools/config/modules.cfg |
module boundaries |
tools/scripts/ |
analysis, asm generation and progress tools |
To decompile a function: replace its INCLUDE_ASM line in src/<module>.c with C
code, delete its .s file and run make compare.
See docs/RESEARCH.md (Spanish) for the research behind the
project: how other GBA decompilations work, the toolchain and the ROM layout.