Sonic Heroes Decompilation

A work-in-progress matching decompilation of Sonic Heroes (SEGA, 2003) for the Nintendo GameCube: C and C++ source that, built with the original CodeWarrior compilers, reproduces the retail game byte for byte.

Website · Live progress · FAQ · Credits · Getting started · Discord · Português

This is a non-commercial study and preservation project. It is not affiliated with SEGA, and it takes no money: no ads, donations or paid builds.

This repository contains no game code, no game assets and no extracted assembly. Some functions are written as inline assembly in the source, which is explained under Status. You need your own legally obtained copy of the game to build it. The project does not produce a playable game and is not a port; once it is complete, ports or mods built on it would be separate projects.

Supported version:

• G9SE8P, GameCube, North America (NTSC-U), revision 0

Planned later: G9SP8P (PAL) and G9SJ8P (NTSC-J).

GameCube target and cross-platform evidence

This is a GameCube decompilation. The G9SE8P GameCube machine code, object layout and artifact hashes are authoritative for every match.

Some corresponding PS2 builds preserve useful symbol metadata. Maintainers may inspect a legally obtained PS2 copy locally to help classify a translation unit as C or C++, recover a symbol name or signature, and understand class or source structure. That evidence is only a cross-platform lead: it must be correlated with the GameCube unit and verified by GameCube objdiff. It cannot establish a GameCube byte match on its own.

The repository does not contain or distribute PS2 disc images, executables, extracted code or complete symbol dumps, and contributors do not need a PS2 copy to work here. Reviewed classifications and the minimum useful evidence are recorded in the repository. See the source-language policy for the workflow, the current migration audit for reviewed decisions, and LEGAL.md for the artifact rules.

Status

The progress badges and generated objdiff report are authoritative; avoid copying percentages into prose because they become stale.

main.dol and all 17 configured REL modules rebuild byte for byte. Their hashes are stored in config/G9SE8P/build.sha1, and CI verifies all eighteen artifacts on every change. stage00D is not configured; see the note at the end of config/G9SE8P/config.yml.

Exact linked artifacts do not mean that every function has been reconstructed as source. Unwritten regions can still be carried through the decompilation build, so source progress must be read from objdiff rather than from the final SHA-1 result alone.

The disc ships no .map file. Names and translation-unit boundaries are argued from GameCube cross references, private data, alignment and correlated metadata. PS2 symbols can supply cross-platform names and class evidence, but every conclusion is checked against the GameCube object. See the source-language policy and current audit.

Some SDK units legitimately require inline assembly for instructions with no C form, such as special-purpose-register and cache operations. Generated assembly and all other extracted binary material remain under ignored build/original directories and are never committed.

Reproducing the RELs needed a fix to decomp-toolkit. These RELs reserve an empty section slot before .text which mwld drops during the partial link, because nothing lands in it; dtk wrote its section table straight from the object indices, so every section came out one index low and the header fields shifted with them. The project therefore pins a fork carrying that change, tagged v1.8.3-sh1. It is reported upstream as encounter/decomp-toolkit#144, with the fix proposed in encounter/decomp-toolkit#145; point tools/download_tool.py back at upstream once it lands there.

AI assistance

I use LLMs to help write this decompilation. Nothing goes in unverified: every function has to match the original byte for byte in objdiff, and CI checks the SHA-1 of the built DOL on every push. A function either reproduces the original binary exactly or it does not get marked as matching.

Getting started

The short version is below. docs/getting_started.md walks through the whole workflow, from the first build to a pull request.

Dependencies

You need Python and ninja on your PATH.

Windows

Use native tooling. WSL and msys2 are not needed, and objdiff cannot watch files for automatic rebuilds under WSL.

• Python
• ninja, or pip install ninja

macOS

brew install ninja

Linux

Install ninja from your package manager.

On macOS and Linux, wibo is downloaded automatically to run the original Windows compilers.

Building

Clone the repository:

git clone https://github.com/Jovinull/sonicheroes.git

Turn on the repository hooks once, so a commit that stages game data or build output is refused before it happens:

git config core.hooksPath .githooks

Put your copy of the game in orig/G9SE8P/. Either drop the disc image there (ISO, RVZ, GCM, WBFS, CISO, GCZ, NFS or TGC), or extract the disc with Dolphin into that folder. If you use a disc image, it can be deleted after the first build.

Then:

python configure.py
python -m unittest tools.test_check_language_policy
python tools/check_language_policy.py
ninja

The checksum step verifies main.dol and all 17 configured REL modules.

Diffing

After the first build there will be an objdiff.json in the project root.

Get objdiff, open project settings and point Project directory at this repository. It picks up the config on its own. Pick an object in the sidebar to start diffing. It rebuilds automatically when you edit source, headers, configure.py, splits.txt or symbols.txt.

Contributing

See CONTRIBUTING.md.

Game-owned code is C++ by default, while reviewed C boundaries and known C libraries remain C. Legacy .c paths that already compile with -lang=c++ are migrated to .cpp in verified batches, not rewritten all at once. Each batch records its language evidence and must preserve the GameCube object before it is accepted. The exact policy and migration checklist are in docs/language-policy.md.

External resources that help with naming functions and structs (community disassemblies, SDK headers, format documentation) are tracked in REFERENCES.md.

Credits

Built by Jovinull, Cypress and everyone in the contributor list, with help from the community on Discord. The full credits, the tools this project builds on and where it has been featured are on the credits page.

Progress is tracked on ByteMatch; decomp.dev tracked it from July to October 2026.

Legal

See LEGAL.md.