A byte-matching decompilation of The Legend of Zelda: Four Swords Adventures for the GameCube.
Progress site · Progress · Roadmap · Contributing · Plan
The whole DOL: area is bytes of code, the fill is matched code. The top row is the game code in its eight categories, the bottom row the libraries. Click a block to open it in the interactive treemap, which goes down to single functions.
As of 2026-11-15:
- Structural progress: 74.36 % (3,303,075 of 4,442,032 bytes): matched code plus, for each structurally matched or close function, its size times its match percent.
- Matched code: 51.44 % (2,284,996 of 4,442,032 bytes), 9,864 / 11,557 functions fully matched.
- Structurally matched: 10,420 / 11,557 functions (same instructions, register or order differences only), +474 close.
- 470 of 903 split units are Matching, and
main.dolbuilt from them links byte-identically (SHA-1 OK).
The Dolphin SDK, GX, JSystem, and MSL, Runtime and MetroTRK: imported from other decompilations and finished file by file. What is left is a few dozen holdouts.
Of 868,248 bytes of library code: 98.6 % structural progress, 97.7 % matched code; 4,714 / 4,768 functions fully matched.
| Library | Code matched | Functions | Left |
|---|---|---|---|
| Dolphin SDK | 100 % of 131,224 bytes | 610 / 610 | – |
| GX | 100 % of 33,660 bytes | 172 / 172 | – |
| JSystem | 97.9 % of 630,852 bytes | 3,651 / 3,702 | 51 |
| MSL, Runtime, TRK | 90.0 % of 72,512 bytes | 281 / 284 | 3 |
Every library
Dolphin SDK: 18 libraries
| Library | Code matched | Functions |
|---|---|---|
| os | 100 % of 29,664 bytes | 175 / 175 |
| card | 100 % of 25,944 bytes | 84 / 84 |
| dvd | 100 % of 17,796 bytes | 90 / 90 |
| exi | 100 % of 8,112 bytes | 27 / 27 |
| ar | 100 % of 7,900 bytes | 15 / 15 |
| pad | 100 % of 7,860 bytes | 24 / 24 |
| vi | 100 % of 7,780 bytes | 24 / 24 |
| gba | 100 % of 7,160 bytes | 35 / 35 |
| si | 100 % of 6,504 bytes | 26 / 26 |
| gd | 100 % of 2,940 bytes | 7 / 7 |
| OdemuExi2 | 100 % of 2,688 bytes | 14 / 14 |
| mtx | 100 % of 2,496 bytes | 23 / 23 |
| ai | 100 % of 2,276 bytes | 19 / 19 |
| dsp | 100 % of 1,536 bytes | 11 / 11 |
| base | 100 % of 276 bytes | 22 / 22 |
| db | 100 % of 236 bytes | 5 / 5 |
| amcstubs | 100 % of 48 bytes | 8 / 8 |
| odenotstub | 100 % of 8 bytes | 1 / 1 |
JSystem: 12 libraries
| Library | Code matched | Functions |
|---|---|---|
| J3D | 98.2 % of 173,328 bytes | 1,166 / 1,191 |
| J2DGraph | 97.1 % of 159,196 bytes | 878 / 887 |
| JAudio | 96.7 % of 120,700 bytes | 747 / 755 |
| JKernel | 99.3 % of 55,724 bytes | 325 / 327 |
| JParticle | 98.7 % of 54,360 bytes | 200 / 202 |
| JUtility | 100 % of 47,044 bytes | 190 / 190 |
| JMessage | 100 % of 7,936 bytes | 79 / 79 |
| JFramework | 100 % of 7,092 bytes | 21 / 21 |
| JSupport | 100 % of 3,264 bytes | 29 / 29 |
| JMath | 96.5 % of 1,256 bytes | 6 / 7 |
| JGadget | 100 % of 936 bytes | 10 / 10 |
| JStudio_JParticle | 0 % of 16 bytes | 0 / 4 |
FSA's own code is most of what remains. It is grouped by what each file is: the Player, enemies and bosses, NPCs, objects and gimmicks, the stage and world, menus and screens, the game core and media and link. The work still goes in boot path order (every file the game runs from power-on to the main menu, then on to a live Shadow Battle, measured in Dolphin); the progress site's Group by switch shows the game code that way too.
Of 3,573,784 bytes of game code: 68.5 % structural progress, 40.2 % matched code; 5,150 / 6,789 functions fully matched.
| Category | Structural | Code matched | Functions | Files Matching | Unconfirmed |
|---|---|---|---|---|---|
| Player | 94.6 % | 67.5 % of 407,528 bytes | 981 / 1,054 | 0 / 10 | – |
| Enemies & bosses | 56.1 % | 31.5 % of 679,252 bytes | 919 / 1,339 | 29 / 139 | 54 |
| NPCs | 64.9 % | 36.4 % of 291,360 bytes | 428 / 594 | 10 / 54 | 17 |
| Objects & gimmicks | 62.0 % | 35.9 % of 900,452 bytes | 1,071 / 1,518 | 68 / 229 | 56 |
| Stage & world | 60.6 % | 21.6 % of 182,272 bytes | 191 / 311 | 0 / 10 | 2 |
| Menus & screens | 73.2 % | 38.3 % of 801,312 bytes | 602 / 863 | 8 / 47 | 11 |
| Game core | 80.8 % | 61.3 % of 198,580 bytes | 667 / 773 | 4 / 24 | 7 |
| Media & link | 66.9 % | 44.3 % of 113,028 bytes | 291 / 337 | 6 / 15 | 2 |
- Player: The four players and their manager: the ten Player units of docs/PLAYER.md (states, movement, drawing).
- Enemies & bosses: Enemies and bosses: EnemyBase subclasses and actors docs/names/actors.tsv names as enemies, and their helpers.
- NPCs: Characters the players meet and talk to: actors.tsv NPCs, the escort and conversation actors.
- Objects & gimmicks: Every other actor: switches, pots, doors, platforms, generators, checks and stage gimmicks.
- Stage & world: The stage itself: GameView, the tile map, BgRewrite, the camera, collision, stage and enemy-map loading, the sky.
- Menus & screens: J2D screens: title, file select, game mode, connect screens, the HUD, pause, map, minigame results, message windows, disc error.
- Game core: The framework: main(), GameRoot and GameGlobals, the ActorBase / ActorManager / EnemyBase base classes, the effect spawner, save data and shared utilities.
- Media & link: The THP movie player, the audio manager and sound objects, the GBA link, and the game's memory card and DVD wrappers.
Each game file's category, its evidence and its confidence are in docs/names/categories.tsv (method: docs/names/METHOD.md); the 149 files placed on thin evidence (low confidence) are marked unconfirmed. The progress site can also group the game code by boot-path phase (Boot to main menu, Main menu to Shadow Battle, Actors, Everything else, from docs/BOOT_PATH.md) with its Group by switch.
Structural progress is matched code plus, for each structurally matched
function (same instructions, only register numbers or order differ) or
structurally close one, its size times its match percent (tools/structural.py). Matched code
counts fully matched functions only. Both come from one objdiff report
(build/G4SE01/report_honest.json, relocation diffs on): every unit is
diffed, and a function is fully matched only if its relocations point at the
same symbols too. They are regenerated with every merge; see
How it works.
- Now (phase 2): Library holdouts. About fifty JSystem functions that resist (register allocation and J3DMatBlock's word copies, tagged with FIXMEs) and MSL's ansi_fp and strtoul. Most go to the crack pass. Currently 98.6 % of the functions matched.
- Now (phase 3): Waves of small-function units. One agent per file, one reviewer per wave. Actor waves, the ActorManager spawner (tu_801F9484, 322 functions) and many small units are merged; recurring shapes are in the rules card. Currently 75.9 % of the functions matched.
- Now (phase 3): Big functions, structure first. Write a big function before it reaches 100 %, merge it when it is structurally done or close, so the literal pool, field offsets and callee names settle (docs/RULES_CARD.md). Just started on the file select, game mode screen and GBA link units.
- Now (phase 4): Boot to main menu. main(), the framework, the THP movie player (162 of 168 functions), the title screen and the screens built at boot (file select, the game mode screen, the GBA link manager). Currently 41.0 % of the code matched.
- Now (phase 4): Main menu to Shadow Battle. Stage load, the players, the field and the actors on it, up to two Links fighting on The Field. Currently 45.0 % of the code matched.
- Now (phase 4): The player. The Link class (Player_804A6F38, ten units from 0x8022AD64 to 0x802957CC) and the per-player queries. Every function is written and at least structurally matched (2026-11-06): 934 of 1,054 are at 100 %, the rest differ only in registers, scheduling, stack slots or a few instructions (docs/PLAYER.md), and one, the helper's counter/warp function, carries tagged crack-pass gotos (docs/CRACK_PASS.md).
- Now (phase 5): The naming track. Real names for game files, classes and functions, from debug and assert strings, Dolphin debug output and the dormant debug menus, reviewed on their own. The first evidence-based sweep ran on 2026-11-05 (docs/names/: names.tsv is applied by tools/rename.py, METHOD.md is the method; names without enough evidence are in LOW_CONFIDENCE.md and keep their provisional address names).
- Next (phase 4): Screens and menus. The remaining screens, HUD and menus, after their boot-path owners are written.
- Next (phase 4): Actors by family. Enemies, NPCs and objects family by family, sharing base classes and headers. The earlier actor waves matched the small ones; most update and init functions are still ahead. Currently 39.3 % of the code matched.
- Next (phase 4): Map and stage. Rooms, collision, background rewrites and the stage loader.
The phases and milestones are defined in docs/roadmap.yml;
docs/PLAN.md and docs/GAME_PLAN.md
explain the reasoning behind them.
This repository reconstructs the C and C++ source of Four Swords Adventures
(USA). The original Metrowerks CodeWarrior compilers build it back into a
main.dol that is identical, byte for byte, to the retail one. Readable,
correctly typed source with real names is part of the goal, in the style of
zeldaret/tp and KATAM.
| Property | Value |
|---|---|
| Game | The Legend of Zelda: Four Swords Adventures |
| Platform | Nintendo GameCube |
| Version | USA, G4SE01 |
main.dol SHA-1 |
d86b3d9f785566e34264035e140ef3daf3cc19f0 |
| Compilers | Metrowerks CodeWarrior GC/2.6 (game, JSystem, MSL, TRK); the SDK's own builds |
| Build system | ninja + decomp-toolkit + objdiff |
Each source file is worked on by one owner in its own branch and worktree.
Nothing reaches matching without passing the gate and an independent review,
and every merge relinks main.dol and checks its SHA-1.
flowchart LR
claim(Claim<br/>a file) --> work(Per-file<br/>work)
work --> gate(Gate)
gate -- ok --> review(Adversarial<br/>review)
review -- ACCEPT --> merge(Merge)
merge --> link(Link<br/>+ SHA-1)
link -- ok --> site(Site, README<br/>and badges)
gate -. fails .-> work
review -. CHANGES .-> work
What each step checks
- Gate (
tools/gate.py): no inline asm, register binding,#pragma(bar the evidencedauto_inline off/resetregions) orgotothe donor file doesn't have; no m2c leftovers; no field access through casts and offsets; no embedded bytes; no changes to measuring tools or report settings;symbols.txtonly renames placeholders. Every unit markedMatchingis 100 % in code and data in the objdiff report, andmain.dollinks with the original SHA-1. - Review (
docs/REVIEW_BRIEF.md): a separate reviewer that never saw the author's reasoning reads every changed function against the target assembly and the donor file, checks the data splits and the evidence for every new name, and returns ACCEPT, CHANGES or REJECT. Only ACCEPT merges. - Merge (
tools/merge_unit.py): squash-merges the branch, re-splits, runs the fullninja(link and SHA-1), runs the gate again and refuses if matched code went down. - Publish:
tools/site_data.pywrites the site data, the images insite/badges/and the numbers in this README in the same merge commit. CI cannot build the game (there is no disc), so GitHub Actions only publishessite/to Pages.
- No fakematches. A function counts only when natural source compiles to
the original bytes. Register pins, ordering tricks and asm stand-ins stay
NonMatchingwith aFIXMEsaying what differs. - One report, relocations checked. Every figure comes from the same
objdiff report, and the linked
main.dol's SHA-1 is the final authority. Byte-pattern hits and lenient diffs never count. - Every submission is reviewed adversarially before it merges.
- AI-first, no tricks. Most of the work is done by AI agents under the same gate and review as anyone else. Names need evidence: donor code, SDK symbols or strings in the binary.
- The compiler model is the original's. Game code builds with
-inline auto,deferredand each source lists its functions in descending address order (docs/INLINING.md); a callee the original never inlines gets an evidenced#pragma auto_inline off/resetregion, nothing more. - Names are a manifest. Evidence-based names live in
docs/names/names.tsv(method indocs/names/METHOD.md, applied bytools/rename.py); weak ones are listed indocs/names/LOW_CONFIDENCE.mdand keep their address names.
You need your own legally obtained copy of the game. Nothing from the disc is in this repository.
-
Install Python 3.8+ and ninja.
-
Clone the repository and extract the disc's system data so that
orig/sys/main.dolexists, for example withdtk disc extractor Dolphin's Export Partition Root. -
Configure and build:
python3 configure.py ninja
The compilers, dtk, objdiff-cli and (on Linux) wibo are downloaded into
build/ on the first run. A plain ninja compiles every unit, writes the
objdiff report, links main.dol and checks its SHA-1 against
config/G4SE01/build.sha1. On Windows the compilers run natively.
Reports, objdiff and decomp.me
ninja build/G4SE01/report_honest.json # compile every unit and write the objdiff report
python3 tools/progress.py # totals and per-library breakdown
python3 tools/fdiff.py <unit> # per-function match of one unit
python3 tools/link_check.py # which Matching units break the link, if the SHA-1 failsobjdiff reads objdiff.json
from the repository root; every function of the DOL can be browsed there.
Single functions can also be worked on at decomp.me
with the The Legend of Zelda: Four Swords Adventures (DOL) preset.
Contributions are welcome, from people and from AI agents, under the same rules. In short:
- Build the project and pick a
NonMatchingfile in objdiff or on the progress site. - Claim it by opening an issue, so no two people work on the same file.
- Match it in natural C or C++ with real names and types; split its data too.
- Run
python3 tools/gate.pyuntil it printsgate: ok, then open a pull request. It is reviewed before it merges.
CONTRIBUTING.md covers setup, claiming, code style, verification and submission in detail; AGENTS.md has the same rules as instructions for AI coding agents. Questions go to GitHub issues.
| Path | Contents |
|---|---|
config/G4SE01/ |
decomp-toolkit config: config.yml, splits.txt, symbols.txt, the library and game file maps |
libs/sdk/ |
Dolphin SDK sources from doldecomp/mkdd |
libs/sdk_gx/ |
GX from zeldaret/oot-gc |
libs/jsystem/ |
JSystem from doldecomp/mkdd and projectPiki/pikmin2 |
src/ |
MSL, Runtime and MetroTRK from projectPiki/pikmin2; JSystem units derived from zeldaret/tww |
include/ |
Headers for src/ |
docs/ |
The plan, the roadmap, the agent and review briefs, the coordinator runbook |
tools/ |
Build generator (from dtk-template), gate, merge and progress tools |
site/ |
The progress site; site/data/ and site/badges/ are generated |
Donors and credits
Library code is imported from other decompilation projects whose licenses allow it. Only CC0 and MIT sources are used.
| Project | Used for | License |
|---|---|---|
| doldecomp/mkdd | Dolphin SDK, JSystem | CC0-1.0 |
| zeldaret/oot-gc | GX | CC0-1.0 |
| projectPiki/pikmin2 | J3D, SDK leftovers, MSL_C, Runtime, MetroTRK | CC0-1.0 |
| zeldaret/tww | JSystem headers and units | CC0-1.0 |
| zeldaret/tp | Reference for JSystem and the SDK | CC0-1.0 |
Tools, downloaded at build time or adapted:
| Tool | License |
|---|---|
encounter/dtk-template (configure.py, tools/project.py) |
CC0-1.0 |
| encounter/decomp-toolkit | MIT or Apache-2.0 |
| encounter/objdiff | MIT or Apache-2.0 |
| decompals/wibo | MIT |
tools/ninja_syntax.py from ninja |
Apache-2.0 |
The imported directories keep their upstream LICENSE files.
This is a research and preservation project. It is not affiliated with or endorsed by Nintendo. The repository contains no game code, data or assets: building it requires your own copy of the game. The progress site and the images in this README are original work and publish only function names, addresses, sizes and match results. The Legend of Zelda and Four Swords Adventures are trademarks of Nintendo.