Skip to content
sh1ftmakerPublic

About

Work-in-progress decompilation of The Legend of Zelda: Four Swords Adventures (GameCube)

Resources

Contributing

Stars

11 stars

Watchers

0 watching

Forks

Repository files navigation

Four Swords Adventures decompilation: an emblem with a gem for each of the eight categories of game code and a gold one for the libraries, each filled to its structural progress, with the structural progress and matched code of the whole DOL

Structural progress Matched code Functions matched Units Matching main.dol SHA-1 Pages

A byte-matching decompilation of The Legend of Zelda: Four Swords Adventures for the GameCube.

Progress site  ·  Progress  ·  Roadmap  ·  Contributing  ·  Plan

Player: 67.5 % matchedEnemies & bosses: 31.5 % matchedNPCs: 36.4 % matchedObjects & gimmicks: 35.9 % matchedStage & world: 21.6 % matchedMenus & screens: 38.3 % matchedGame core: 61.3 % matchedMedia & link: 44.3 % matched
JSystem: 97.9 % matchedDolphin SDK: 100 % matchedMSL, Runtime, TRK: 90.0 % matchedGX: 100 % matched
area = bytes of code, fill = matched

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.


Progress

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.dol built from them links byte-identically (SHA-1 OK).
Progress overview: where the remaining work is, the libraries as one group, and the game code's eight categories with matched-code and structural-progress bars

Libraries

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
MSL, Runtime, TRK: 3 libraries
Library Code matched Functions
MSL_C 79.4 % of 35,380 bytes 83 / 86
MetroTRK 100 % of 33,288 bytes 165 / 165
Runtime 100 % of 3,844 bytes 33 / 33

Game code

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.

Roadmap

Roadmap phases as gems: done, under way, next and later
  • 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.

About

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

How it works

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
Loading
What each step checks
  • Gate (tools/gate.py): no inline asm, register binding, #pragma (bar the evidenced auto_inline off/reset regions) or goto the 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.txt only renames placeholders. Every unit marked Matching is 100 % in code and data in the objdiff report, and main.dol links 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 full ninja (link and SHA-1), runs the gate again and refuses if matched code went down.
  • Publish: tools/site_data.py writes the site data, the images in site/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 publishes site/ to Pages.

Principles

  • No fakematches. A function counts only when natural source compiles to the original bytes. Register pins, ordering tricks and asm stand-ins stay NonMatching with a FIXME saying 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,deferred and 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/reset region, nothing more.
  • Names are a manifest. Evidence-based names live in docs/names/names.tsv (method in docs/names/METHOD.md, applied by tools/rename.py); weak ones are listed in docs/names/LOW_CONFIDENCE.md and keep their address names.

Building

You need your own legally obtained copy of the game. Nothing from the disc is in this repository.

  1. Install Python 3.8+ and ninja.

  2. Clone the repository and extract the disc's system data so that orig/sys/main.dol exists, for example with dtk disc extract or Dolphin's Export Partition Root.

  3. 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 fails

objdiff 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.

Contributing

Contributions are welcome, from people and from AI agents, under the same rules. In short:

  1. Build the project and pick a NonMatching file in objdiff or on the progress site.
  2. Claim it by opening an issue, so no two people work on the same file.
  3. Match it in natural C or C++ with real names and types; split its data too.
  4. Run python3 tools/gate.py until it prints gate: 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.

Repository layout

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.

Legal

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.

About

Work-in-progress decompilation of The Legend of Zelda: Four Swords Adventures (GameCube)

Resources

Contributing

Stars

11 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages