Skip to content
MatyMeatBoyPublic

About

Shining Soul 2 decompilation

Resources

Contributing

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

Shining Soul II (Europe) — Decompilation

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.

Where the project stands

Question Status What is left
code 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
names 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
data 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.

Progress in detail

Three views. Click a tab to open it; the figure on each tab is its current progress.

Code progress  Code: is it matching?

code treemap

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 progress  Names: do we know what each function does?

names treemap

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 progress  Data: is the 16 MB of data split and described?

data progress

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.

Join the collaboration

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.

Building

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/*.svg

Contributing

Anyone can help: read CONTRIBUTING.md (setup, per-function workflow, compiler rules). AI agents: CLAUDE.md and docs/agents/.

Layout

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.

About

Shining Soul 2 decompilation

Resources

Contributing

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages