Golden Sun
A work-in-progress matching decompilation of Golden Sun (GBA, 2001), based on
[gsret's disassembly](https://github.com/gsret/goldensun).
**Target:** USA `goldensun.gba`, SHA1
`5c4695205413df7db52b9a184815a07783999971`.
## Progress
[](https://decomp.dev/Coaltergeist/goldensun-decomp)
[](https://decomp.dev/Coaltergeist/goldensun-decomp)
Each rectangle represents a translation unit, sized by original code bytes and
colored by matching progress. Click the treemap for unit and function details.
[](https://decomp.dev/Coaltergeist/goldensun-decomp)
## Getting started
- [Build and diff setup](INSTALL.md)
- [Contributing and matching requirements](CONTRIBUTING.md)
The build uses patched GCC 2.96 from
[camelot-gcc](https://github.com/Coaltergeist/camelot-gcc), with `old_agbcc` for
the stock m4a audio engine and most Flash library C. `make clean && make compare`
builds the ROM and checks it and all 96 code overlays against the original game.
Contributions are welcome, including matching C, reverse-engineering findings,
and cleanup of existing fakematches. **New fakematches are not accepted.**
See [CONTRIBUTING.md](CONTRIBUTING.md) for the source and verification requirements.
## Repository layout
| Path | Contents |
| --- | --- |
| `src/core/` | Startup, resident runtime code and the standalone RAM library |
| `src//` | Descriptive main-ROM modules, such as field_engine, field, ui, battle and battle_anim |
| `src/maps/*.c` | Map and other code overlays, one named translation unit per bank |
| `src/maps/common/` | The three shared overlay modules, compiled once each |
| `src/lib/` | GBA library code, including m4a and Flash support |
| `src/non_matching/` | Parked candidates and context headers, grouped by current TU ownership |
| `asm/core/`, `asm//`, `asm/maps/` | Active assembly fragments for the corresponding source TUs |
| `data/` and `exports/` | Maintained data assembly and exported symbols |
| `linker/` | Main-ROM and overlay linker scripts; address maps under `linker/symbols/` |
| `include/` | C headers and assembler macros |
| `tools/` | Build and comparison tools |
| `build/` | Build output only (ignored); `make clean` deletes it |
Overlay linker scripts are named by ROM offset (`linker/overlays/rom_XXXXXX.ld`)
and, with the main-ROM scripts, name every object that is built. Standalone
assembly lives under `src/`; disassembly included by C files stays under `asm/`.
Paths in `original_functions.json` are the original disassembly's, not current paths.
## References
- [decomp.me](https://decomp.me): function-matching sandbox.
- [asm-differ](https://github.com/simonlindholm/asm-differ) and
[decomp-permuter](https://github.com/simonlindholm/decomp-permuter): comparison
and matching tools.
- [SAT-R/sa2](https://github.com/SAT-R/sa2),
[zeldaret/tmc](https://github.com/zeldaret/tmc),
[pret/pokeemerald](https://github.com/pret/pokeemerald), and
[pret/pokefirered](https://github.com/pret/pokefirered): related GBA projects.
## Credits
- **[gsret](https://github.com/gsret):** the original Golden Sun disassembly.
- **FutureFractal:** Ghidra annotations, function and global names, and
[GS-headers](https://github.com/FutureFractal/GS-headers).
- **Tarpman:** compiler-reproduction and source-shape analysis.
- **Karathan:** compiler flag characterization, including
`-fcall-used-r4 -ffixed-r7`.
- **[pret](https://github.com/pret):** GBA decompilation methodology and
[agbcc](https://github.com/pret/agbcc), including `old_agbcc` and the compiler
installation pattern used by camelot-gcc.
- **[SAT-R/sa2](https://github.com/SAT-R/sa2):** the m4a ("Sappy") reconstruction
used by this project's [audio-engine C port](src/lib/m4a/).
- **[simonlindholm](https://github.com/simonlindholm):** asm-differ and
decomp-permuter.
- **The wider decompilation community:** the techniques and tooling developed
through sm64, oot, mm, pret, zeldaret, SAT-R, and other projects.
For credit corrections, please open an issue. See
[ATTRIBUTION.md](ATTRIBUTION.md) for component notices.